etchplan

<p align="center"> <img src="assets/etchplan-logo.svg" alt="etchplan logo" width="100"> </p> <h1 align="center"><em>etchplan</em></h1> **您的代理重复解决相同类型的任务。 _etchplan_ 将可重复的部分转化为已验证的例行程序，可以在无需模型调用的情况下重放，并在防护措施失效时回退到代理。** *由 [Egoist Machines, Inc.](https://egoistmachines.com/) 构建 - 面向可靠 AI 系统的高效全栈基础设施。* _etchplan_ 监视本地代理跟踪，挖掘重复的工作流程，并将安全的工作流程编译为确定的 `ExecutionPlan`。例行程序仅在验证后运行。如果输入偏移，防护措施失败或工具未绑定，则代理处理请求。 - 完全编译的重放时，无需进行模型调用。 - 在提供任何结果之前，进行防护、静态检查、验证和变异门控。 - 支持 Claude Code、Codex 和开源的本地捕获；跟踪写入 `~/.etchplan/`。 - 在实时服务之前，提供影子、审批、金丝雀和偏移终止开关。 - 例行决策、工具调用和回退的追加审计日志。 - CLI、MCP 服务器和可运行的 [BYO](examples/byo/README.md)、[MCP](examples/mcp/README.md) 和 [real-API](examples/real_traces/README.md) 示例。 ## 它是什么 **etchplan** 在验证的工具工作流程可以重放时移除重复的模型调用，而代理仍然在回退后。这 **不是** 提示缓存、响应缓存、可观察性或您手动编写的工作流程构建器。这些都是有效技术，您可以将其与 etchplan 结合使用，以使模型调用更便宜、跳过近似重复或帮助您监视代理。 **etchplan** 适用于结构化的工具调用工作流程：API/MCP 集成、浏览器操作和重复的多步骤工作，其中参数绑定到输入或早期工具输出。自由文本编码 churn 通常被挖掘和拒绝，因为参数是代码、shell 或散文，而不是稳定的参数。 参考点：[Agent JIT Compilation](https://arxiv.org/abs/2605.21470) 和 [Agent Workflow Optimization / meta-tools](https://arxiv.org/abs/2601.22037)。比较注释在 [RELATED_WORK.md](RELATED_WORK.md) 中。 ## 安装 Apache-2.0，本地优先，Python >= 3.12。 ```bash pip install etchplan # 或：uv tool install etchplan，pipx install etchplan etch demo # 完整的离线循环：导入、挖掘、编译、验证、运行。无需代理，无需密钥。 etch doctor # 确认捕获连接并检查 etch 是否在您的 PATH 上 ``` 无需安装即可试用：`uvx etchplan demo`。对于需要它们的部件，额外功能包括 `etchplan[mcp]`（MCP 服务器）、`etchplan[browser]`（Playwright 重放）、`etchplan[desktop]`（macOS GUI 捕获）。从源代码：`git clone https://github.com/Egoist-Machines/etchplan && cd etchplan && uv run etch demo`。 ## 在您的代理上使用它 安装一次捕获并正常使用您的代理。`etch setup` 为您运行 [Quickstart](#quickstart) 发现循环：自动管道捕获、挖掘并编译会话和回合结束时的草稿例行程序，因此您永远不需要手动运行这些步骤。 ```bash uv run etch setup claude-code --write # 另见：codex | opencode # 使用您的代理；会话捕获到 ~/.etchplan/，自动管道保持例行程序更新 uv run etch report # 节省的资金和时间，从管道填充的存储中读取 uv run etch report --format html --open ``` 该自动管道是 Quickstart 步骤 1-3（导入、挖掘、编译草稿）的调度；`etch report` 和 `etch yield` 只需读取它找到的内容。`etch doctor` 检查捕获是否安装并且事件正在流动。`etch mcp install` 为 Claude Code、Claude Desktop、Cursor、Codex 或所有支持的客户端注册 MCP 服务器。完整的命令表面、干运行行为、服务模式和 MCP 代理详细信息在 [docs/cli.md](docs/cli.md) 中。 只有服务保持手动设计（Quickstart 步骤 4-5）：使用 `etch run --shadow` 收集同意，一次批准，然后金丝雀批准例行程序。防护措施失败、缺少绑定、运行时错误或偏移会导致代理介入。 ## 示例结果 在 AppWorld（gpt-5.5）上，每次重复解决，在一次代理解决和一次编译后： | | 代理，每次 | _etchplan_ | |---|--:|--:| | 延迟 | ~116 秒 | ~0.2 秒（~580 倍快） | | 成本 | ~$0.47 | $0（零模型调用） | | 重用经济 | 每次支付全价 | ~1.07 次重用后收支平衡；第 10 次重用后 ~9 倍更便宜 | 那些数字背后的沉重实时代理负载不在此仓库中。紧凑的基准测试工件存在，每个数字都标记为 `measured`、`recorded`、`estimated` 或 `assumed`。参见 [docs/results.md](docs/results.md) 和 [docs/benchmark-methodology.md](docs/benchmark-methodology.md)。 真实 API 群体在流程上表现出相同的形状： | 领域 | 工作流程 | 跟踪 | 结果 | |---|---|---:|---| | `weather_brief` | geocode(city) -> forecast -> air_quality | 30 | 3 节点，0 模型 | | `ip_weather` | geoip(ip) -> forecast | 18 | 2 节点，0 模型 | | `zip_weather` | postal(zip) -> forecast | 18 | 2 节点，0 模型 | | `github_repo` | get_repo(slug) -> get_branch | 18 | 2 节点，0 模型 | | `word_assoc` | related(word) -> related(top) | 18 | 2 节点，0 模型 | | `pokemon` | get_pokemon(name) -> get_ability(url) | 18 | 2 节点，0 模型 | 所有六个编译在本地收益率检查中：120 次跟踪，6 个重复工作流程，6 个编译。跟踪和范围注释在 [examples/real_traces](examples/real_traces/README.md) 中。 ## 快速入门 实际流程找到代理重复的工作流程，编译并验证安全的工作流程，然后在代理后面提供服务。步骤 1-3 直接在存储库中提供的真实 API 群体上运行；步骤 4-5 绑定您自己的工具并赢得例行程序的服务权限。 **1. 获取跟踪。** 跟踪可以是您的代理（`etch setup <harness> --write` 将会话捕获到 `~/.etchplan/`，参见上文）。要立即运行每个步骤，请将提供的真实 API 群体导入到同一个存储中： ```bash db=.etchplan.sqlite uv run etch import jsonl examples/real_traces/weather_brief/traces.jsonl --db $db ``` **2. 查看递归和编译内容。** `etch yield` 挖掘重复的工作流程并报告哪些编译以及为什么拒绝其他内容。它仅进行测量，从不提供服务： ```bash uv run etch yield --db $db --min-support 5 # 递归：1 -> 编译：1 （weather_brief：geocode -> forecast -> air_quality，0 模型调用） ``` 在捕获的代理跟踪上，`etch report` 将同一个存储转换为节省的资金和时间。 **3. 编译和验证例行程序。** `--pattern-id top` 获取支持度最高的模式，该模式编译；验证在跟踪派生的案例上执行例行程序（测量，而不是估计）： ```bash uv run etch compile pattern --db $db --pattern-id top --out weather_brief.yaml uv run etch validate plan weather_brief.yaml --db $db ``` **4. 在您的工具后面运行它，并将代理作为回退。** `--registry` 将计划的工具名称绑定到您的可调用函数；任何防护措施失败、未绑定的工具或运行时错误都会路由到 `--fallback`，并且每个调用都记录在审计日志中： ```bash uv run etch run weather_brief.yaml --input in.json \ --registry your_tools:registry --fallback your_tools:agent --audit audit.jsonl ``` 在 [examples/byo](examples/byo/README.md) （普通可调用函数）和 [examples/mcp](examples/mcp/README.md) （MCP 工具加策略门控实时变异）中，具有真实绑定的可运行端到端。 **5. 在服务前获得信任。** 在第一天没有任何服务。积累影子中的同意，在证据清除您的栏后批准，然后金丝雀；偏移终止开关拉动一个例行程序，其回退率攀升： ```bash uv run etch run weather_brief.yaml --input in.json --registry your_tools:registry --shadow # 提供代理，记录匹配/不匹配 uv run etch plans approve weather_brief.yaml --min-matches 20 --max-mismatch-rate 0.0 uv run etch run weather_brief.yaml --input in.json --registry your_tools:registry --require-approval --canary --canary-pct 10 ``` 只需观看循环一次？`uv run etch demo` 在捆绑的示例上离线运行整个过程，无需代理和密钥。 ## 工作原理 ``` 代理跟踪 | v 标准化 清洁，编辑，插槽 | v 挖掘 查找重复，验证参数流，学习防护 | v 编译 合成受保护的执行计划 | v 验证 在跟踪派生的重放案例上执行 | v 运行 ------> 防护措施生效：重放，无需模型调用 | + ------> 防护措施失败：回退到代理 ``` 信任循环是 `draft -> shadow -> approved -> canary -> served`。变异步骤保持在幂等性和变异门控后面，如果例行程序验证失败，则永远不会运行。包映射、防护实现注释和更深层次的图表在 [docs/architecture.md](docs/architecture.md) 和 [docs/security-model.md](docs/security-model.md) 中。 ## 工作负载适合度 | 工作负载 | 适合度 | 为什么 | |---|---|---| | 重复的 API / MCP 工具工作流程 | 优秀 | 可绑定参数，步骤之间的数据流，学习防护 | | 浏览器 / 桌面操作循环 | 预览 | 语义操作可以在相同的信任循环后面重放 | | 编码代理编辑循环 | 设计拒绝 | 免费文本步骤参数不绑定到确定性例行程序 | | 一次性任务 | 否 | 一次种子解决方案加上一次编译不摊销 | 有关您自己的跟踪的自然编译收益率检查，请参见 [docs/measuring-yield.md](docs/measuring-yield.md)。主动前向边在 [docs/roadmap.md](docs/roadmap.md) 中跟踪。 ## 文档 - 结果：[docs/results.md](docs/results.md)，[docs/benchmark-methodology.md](docs/benchmark-methodology.md) - 构建/运行：[docs/cli.md](docs/cli.md)，[docs/architecture.md](docs/architecture.md)，[docs/security-model.md](docs/security-model.md) - 项目：[docs/development.md](docs/development.md)，[docs/roadmap.md](docs/roadmap.md)，[RELATED_WORK.md](RELATED_WORK.md)，[CHANGELOG.md](CHANGELOG.md)，[CITATION.cff](CITATION.cff) ## 许可证和安全 Apache-2.0，参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。开源代码可免费使用，包括商业用途；“Etchplan”名称和徽标是商标（[TRADEMARKS.md](TRADEMARKS.md)），Apache-2.0 不授予商标权。_etchplan_ 是本地优先的：默认情况下没有任何内容离开您的机器。 企业许可和商业支持来自 [Egoist Machines, Inc.](https://egoistmachines.com/)：托管/管理服务、SSO/RBAC、多租户计划注册表和本地 / BYOC 部署。请联系 [sales@egoistmachines.com](mailto:sales@egoistmachines.com)。 欢迎 PR；参见 [CONTRIBUTING.md](CONTRIBUTING.md)（提交需要 DCO 签名：`git commit -s`）。通过 [SECURITY.md](SECURITY.md) 私下报告安全问题，而不是在公共问题上。其他错误和功能请求转到 [问题跟踪器](https://github.com/Egoist-Machines/etchplan/issues)。