ide-super-worker

# IDE 超级工作者 [中文说明](#中文说明) · [English](#ide-super-worker) ## 中文说明 > 让 Codex 专注于规划与审阅；把大文件阅读、修复循环和测试日志交给低成本异步 worker，并只返回可核查的压缩证据。 不要把宝贵的 Codex 上下文花在批量读文件、反复修补和超大 diff 上。 `ide-super-worker` 将耗时的编码工作委派给运行在更低成本 OpenAI 兼容网关上的异步 worker。Codex 仍负责规划、判断与审阅，只接收必要的 压缩证据：改动文件、检查结果、日志和可选的裁剪 diff。 > **2.6 测量状态：** 仓库已具备成对成本/质量指标和失败即停止的验收机制，但未附带 > 真实的 10 对试点或 200 任务正式评估。在这些门禁通过前，不应宣称已节省成本或质量 > 不劣，也不要仅凭此版本扩大默认自动路由。  ### 它怎样工作 ```mermaid flowchart LR A["Codex\n规划与审阅"] -->|"精简 MCP 请求"| B["IDE Super Worker"] B -->|"启动"| C["Claude Code CLI\n后台任务"] C -->|"廉价模型网关"| D["OpenAI-compatible model"] C -->|"改动 + 检查"| B B -->|"压缩证据"| A ``` - `search`：零 LLM 的仓库发现。 - `analyze`、`review`：只读的低成本分析与审阅。 - `start`：将读文件、编辑、测试等实施循环放入后台 worker。 - `get`、`wait`：只把必要的文件变更、检查与摘要带回 Codex 主线程。 这样 Codex 专注于高价值判断，worker 吸收冗长的中间过程，减少主线程需要读取的 文件和测试日志。 ### 质量优先模式 `analyze` 和 `review` 可显式传入 `quality_mode:"high"`。该模式是可选且 **失败即停止（fail-closed）** 的：三个固定角色分支完成分析后，交由独立审阅器裁决； 任何截断输出、空答案、模型不匹配、无效引用或未解决分歧，都会返回 `needs_direct_review` 或 `failed`，绝不悄悄回退为普通答案。 ```mermaid flowchart LR A["高质量请求"] --> B["主分析 / 独立 / 红队"] B --> C["独立审阅器"] C --> D{证据与结论完整？} D -->|是| E["quality.v1 结果"] D -->|否| F["人工直接审阅 / 失败"] ``` 默认仍为 `standard`。只有通过真实冻结任务、盲评和 Trial A → B → C 的资格门禁， 才可讨论更改默认路由。详细的中英文迭代说明见 [质量优先迭代说明](docs/quality-first-iteration.zh-CN.md)。 ### 快速开始 ```bash npm install npm run build npm test ``` 配置示例与完整工具说明在下方英文文档中；质量模式环境变量示例见 [`.env.example`](.env.example)，评估要求见 [eval/README.md](eval/README.md)。 ## Efficiency First 大多数 AI 编码工具优化模型调用。本项目优化路径。 快速通道被故意分割： - `search` 处理仓库发现，无需 LLM 调用。 - `analyze` 和 `review` 使用一个廉价的网关调用进行只读工作。 - `start` 将实施循环移到异步 worker 中，以便 Codex 不被每个文件读取、失败尝试或测试日志阻塞。 - `get` 和 `wait` 返回压缩证据，而不是将整个记录转储回优质线程。 这种路由规则是效率优势：Codex 保持专注于规划和审阅，而 worker 吸收庞大的中间过程。 ## The Simple Picture 没有这个 worker，Codex 通常需要支付读取所有内容： ```text Codex 主线程 -> 读取大文件 -> 运行修复循环 -> 接收完整 diff -> 消耗优质上下文 ``` 有了这个 worker，Codex 委托噪音中间层： ```mermaid flowchart LR A["Codex<br/>规划与审阅"] -->|"小型 MCP 启动请求"| B["IDE 超级工作者"] B -->|"启动"| C["Claude Code CLI<br/>后台任务"] C -->|"Anthropic 消息"| D["本地适配器"] D -->|"OpenAI 兼容聊天"| E["廉价网关模型<br/>DeepSeek / OneAPI / New API"] C -->|"git diff + 检查"| B B -->|"更改的文件 + 检查<br/>可选 diff"| A ``` ## 为什么存在 Codex 在协调、审阅和决策时表现最佳。并非总是成本效益高让主 Codex 线程读取大文件、运行长修复循环和摄入巨大 diff。 这个 worker 改变账单结构： - Codex 发送一个紧凑的 `start` 请求。 - Claude Code 在后台执行繁重的工作。 - 本地适配器将模型流量路由到更便宜的后端。 - Codex 接收 `changed_files`、`checks`、日志和可选的修剪 diff。 对于大型代码读取和修补任务，这可以大大减少昂贵的主线程令牌摄入，因为 Codex 不再需要摄入每个中间文件读取和完整修补正文。 ## 使其优于“只需使用更便宜的模型” 仅靠便宜的模型是不够的。您仍然需要路由、安全、结果形状和验证。 该项目为您提供缺少的管道： - 一个 Codex 原生 MCP 接口，以便委托是一个工具调用。 - 一个 Claude Code 执行循环，以便 worker 可以实际编辑和测试。 - 一个本地 Anthropic 到 OpenAI 适配器，以便 Claude Code 可以使用更便宜的网关。 - 范围强制和检查命令，以便工作可审计。 - 紧凑的结果有效载荷，以便 Codex 不会吞下不必要的令牌。 - 指标、回退、重试和可选的工作树隔离以实现实际操作。 ## 效率比较 | 工作流 | 通常发生的情况 | 效率差距 | IDE 超级工作者路径 | | --- | --- | --- | --- | | 直接优质代理编码 | 主代理读取文件、重试修复、查看每个测试日志并摄入大 diff。 | 优质上下文成为工作区记录。 | Codex 发送一个小型任务；工作者返回更改的文件、检查、日志和可选的 diff。 | | 通用更便宜模型包装器 | 更便宜的模型运行，但主代理仍然需要庞大的上下文和手动验证。 | 更低的模型价格，相同的噪音工作流程。 | 廉价网关处理批量令牌；范围检查和紧凑结果决定工作是否值得信赖。 | | 仅限只读问题的完整代理循环 | 为摘要和发现启动可编辑循环。 | 启动缓慢和不必要的写入表面。 | `search` 是零 LLM；`analyze`/`review` 是只读的廉价调用。 | | 一个仓库中的并行实现 | 脏工作树冲突和审查有效载荷增长。 | 协调开销吃掉增益。 | 可选的工作树隔离加上范围检查使作业可分离。 | ## 亮点 - 异步 MCP 工具：`start`、`get`、`tail`、`wait`、`cancel`。 - 只读精简工具：`read_pack`、`analyze`、`diff_digest`、`history` 和 `draft` 将大批量读取/审阅/草拟排除在优质线程之外。`read_pack` 将其内联有效载荷保持在或低于 16 KB；当并非所有切片都适合时，`truncated:true` 信号表示完整的数据包可通过 `receipt.artifact_refs` 获取。 - 代码审查精简工具：`review` 通过廉价网关检查 diff/文件。 - 零 LLM 仓库发现和机械工作：`search` 使用有界本地搜索，`apply_edits` 在无需模型调用的情况下处理确定性替换。 - 工作端命令摘要：`shell` 可以运行测试/构建/ lint 并返回紧凑的失败摘要。测试和类型检查退出返回公共 `status:"failed"` 以及规范的 `failure`、`failure_kind` 和 `required_action`，而它们的接收/指标保持 `ok`；超时、丢失命令、权限失败和其他基础设施失败仍然是工具错误。 - 接收异常输出评估：每个接收结果都带有确定性的接受/修复判决和有界的修复指导，无需默认的多模型投票。 - 运行时工具隔离：工作者将工具错误分类，打开每个工具/错误类别的电路，拦截不健康的路由，并为 `review`/`analyze` 在 LLM 路由不健康时使用确定性回退。 - 可靠性层级和事件摘要：`start` 可以记录 `lite`、`standard`、`strict` 或 `critical` 期望而不会阻塞旧调用者；仅当 `blocking_policy:"enforce"` 时才会发生硬拒绝。 - 结果 v1：作业控制、拒绝和失败有效载荷添加一个版本化的语义结果，同时保留 2.5 版的旧投影。 - 独立语义验证：`semantic_gate:"required"` 执行专门的缓存免费审查，并在证据缺失或不完整时关闭。 - Anthropic 到 OpenAI 适配器：让 Claude Code 与 OpenAI 兼容的网关通信。 - 429 和 5xx 重试处理，支持 `Retry-After`。 - 可选 `include_diff:false` 以仅返回 `changed_files` 和 `checks`。 - 确定性验证层：范围检查、命令检查、结果信号和有界自动修订。 - 成本遥测：当设置 `WORKER_METRICS_FILE` 时，写入网关令牌使用情况和 `event=tool_calls` 行到 JSONL 中。 - 配对评估遥测：将直接/工作者 EvalSpan JSONL 验证并导入到单独的 `WORKER_EVAL_SPAN_FILE` 中。 - 可选的备用网关，当主提供商失败时。 - 可选的工作树隔离，用于在一个仓库中并行作业。 - 日志和工具响应中的机密信息删除。 ## 用例 在您希望 Codex 保持敏锐而不是累赘时使用： | 任务 | 正常流程 | 工作者流程 | | --- | --- | --- | | 修复大型仓库中的错误 | Codex 读取许多文件和测试输出 | 工作者读取/编辑/测试，Codex 审查紧凑的结果 | | 总结实现细节 | 完整的代理循环可能会启动 | `analyze` 调用廉价网关直接 | | 运行重复的修复传递 | 主线程吸收每个尝试 | 工作者处理循环并返回最终证据 | | 并行范围编辑 | 一个脏工作树会缠绕 | 可选的 git 工作树隔离使作业分开 | | 成本核算 | Claude Code 成本可能具有误导性 | 网关令牌使用情况写入 JSONL | ## 工具界面 | 工具 | 目的 | | --- | --- | | `start` | 在允许的目录中启动异步 Claude Code 作业。支持可选的顺序 `stages`。 | | `get` | 读取当前作业生命周期和权威 `outcome`；传递 `verbose:true` 以获取完整的旧版有效载荷。 | | `get_artifact_slice` | 从工作者接收结果引用的工件中读取有界的删减切片。工件引用是进程本地的，可能在 MCP 工作者重启后过期。 | | `tail` | 读取最近的工作日志。 | | `wait` | 等待作业完成而不会在超时时杀死作业；超时会使 `outcome.status="running"`。 | | `cancel` | 杀死正在运行的作业进程树。 | | `analyze` | 对选定的文件或有界通配符进行只读分析。`quality_mode:"high"` 选择失败关闭的 `quality.v1` 三目标管道。 | | `review` | 审查作业 diff/checks 或选定的文件。`quality_mode:"high"` 需要三个分支和独立的证据仲裁者。 | | `search` | 使用 `rg` 时无需 LLM 的有界仓库搜索。 | | `read_pack` | 选定路径的零 LLM 上下文打包器；返回最多 16 KB 的有序符号/关键字切片，并将完整的数据包存储在工件引用后面。 | | `diff_digest` | 按文件、行头和风险总结当前 git diff；可选运行廉价的红队审查。 | | `shell` | 运行有界的工作端命令，可选 `digest:true` 用于测试/构建/ lint 输出。 | | `apply_edits` | 无 LLM 的字面或正则替换，具有替换计数检查。 | | `history` | 文件或行考古的有界 git 日志/ blame 时间线。 | | `draft` | 从当前 diff 中草拟提交消息、PR 描述、变更日志注释或发布说明。 | ## 快速开始 ```powershell npm install npm run build npm run test npm run smoke ``` 从 `.env.example` 创建本地 `.env` 或在 shell 中设置环境变量。永远不要提交真实的密钥。 ```powershell setx ONEAPI_API_KEY "your-provider-key" setx ONEAPI_BASE_URL "https://your-gateway.example.com/v1" setx SANDBOX_ROOT "D:/workspaces" ``` 然后运行： ```powershell npm run doctor npm run doctor:network ``` ## Codex 桌面配置 复制并适应 `codex-mcp.example.toml` 到您的 Codex 配置。 ```toml [mcp_servers.codex_async_worker] command = "node" args = ["D:/path/to/ide-super-worker/dist/index.js"] cwd = "D:/path/to/ide-super-worker" startup_timeout_sec = 10 tool_timeout_sec = 3600 env = { SANDBOX_ROOT = "D:/workspaces", ONEAPI_BASE_URL = "https://your-gateway.example.com/v1", CLAUDE_MODEL = "deepseek-v4-flash", CLAUDE_CODE_MODEL = "sonnet", WORKER_SEMANTIC_REVIEW_MODEL = "deepseek-v4-pro", CLAUDE_PERMISSION_MODE = "acceptEdits", USE_OPENAI_ADAPTER = "1", WAIT_DEFAULT_MS = "1800000" } env_vars = ["ONEAPI_API_KEY"] ``` ## 示例作业 ```json { "prompt": "Fix the failing tests with the smallest safe code change.", "allowed_dirs": ["D:/workspaces/my-project"], "model": "deepseek-v4-flash", "permission_mode": "acceptEdits", "include_diff": false, "verification_policy": { "version": 1, "task_kind": "modifying" }, "semantic_gate": "required", "scoped_patch": { "paths": ["src", "tests"], "max_diff_bytes": 20000 }, "checks": [ { "name": "unit tests", "command": "npm test", "timeout_ms": 600000 } ] } ``` 典型结果： ```json { "contract_version": "outcome.v1", "outcome": { "status": "accepted", "reason_codes": ["verification_passed"], "verification": { "executor": "passed", "scope": "passed", "checks": "passed", "semantic": "passed" } }, "job_status": "completed", "changed_files": ["src/a.ts", "tests/a.test.ts"], "checks": ["scoped_patch: passed (src, tests)", "unit tests: passed"], "diff": "" } ``` `outcome` 是权威的验收。 `job_status`、`status`、`receipt`、`abnormal` 和旧版含义保留其 2.5 版含义；它们在 2.x 版本至少保留 90 天，并且只能在 3.0 版中删除。旧版执行不会被阻止，但那些情况不被视为已接受。 结果 v1 也失败关闭为 `needs_evidence`，当起始工作树已经脏，Git 无法提供可靠的更改摘要，审阅者输入被截断或多阶段管道缺少完整的先前阶段证据时。旧版执行不会被阻止，但这些情况不被视为已接受。 结果 v1 工作区证据基于 Git。具有额外可写根的作业不能成为作业证据。优先使用隔离的工作树，并将忽略的运行时数据排除在声明的修改范围之外；完整的工作区胶囊证据仍是一个后续迭代。 默认情况下，当 Codex 仅需要确定作业是否成功时，请使用 `include_diff:false`。仅当您实际上需要查看补丁详细信息时，才请求 diff。 ## 成本控制 本项目堆叠了多个成本控制措施： 这些控制措施减少了主线程上下文、有效载荷大小和会计噪音；它们不会对工作者 LLM 实施支出上限。主模型、备用模型和升级模型由功能和可靠性配置选择，而不是价格门控。`WORKER_PRICE_*` 值仅用于报告，不得降低、阻止或跳过备用/升级使用。 - `include_diff:false` 减少了高成本 Codex 消耗。 - `DIFF_MAX_BYTES` 限制补丁有效载荷。 - `INCLUDE_DIFF_DEFAULT=0` 使省略的 `include_diff` 表现为 `false`。 - `CHECK_OUTPUT_RESPONSE_MAX` 在 `get`/`wait` 响应中保持检查失败输出紧凑，而 `tail` 保留完整的日志。 - `analyze` 跳过 Claude Code 以获取只读摘要。 - `search` 处理无需 LLM 调用的符号/文件发现。 - `review` 和 `WORKER_FAILURE_DIGEST=1` 将差异审查和故障诊断转移到更便宜的网关。 - `read_pack`、`diff_digest`、`shell digest`、`apply_edits`、`history` 和 `draft` 将剩余的高令牌规划/审查工作转移到工作者通道。 - `WORKER_METRICS_FILE` 记录实际的网关令牌使用情况和 `event=tool_calls` 行以获取零 LLM 工作调用。对于成功的/缓存的 Lite 行，还包括用于延迟诊断的附加 `queue_wait_ms`、`upstream_ms`、`e2e_ms` 和 `attempt_count` 字段。 - `WORKER_EVAL_SPAN_FILE` 单独存储已验证的配对评估记录；它永远不会回退到 `JobResult.total_cost_usd`。 - `WORKER_ESCALATE_MODEL` 仅升级失败的、困难的修订传递。 - `WORKER_RELIABILITY_TIER`、`WORKER_BLOCKING_POLICY`、`WORKER_SEMANTIC_GATE` 和 `WORKER_TOOL_BUDGET` 记录可靠性期望和阻塞风险。默认设置为观察模式，以避免惊讶的停顿。 - `WORKER_ISOLATION=worktree` 允许在一个仓库中安全地并行工作。 - 保持稳定指令的 Prompt-cache 友好型用法，然后是动态任务文本。 Claude Code 自己的 `total_cost_usd` 可能反映 Anthropic 定价，而不是您的网关定价。请使用 `WORKER_METRICS_FILE` 和提供商价格来获取实际的会计信息。 ## 成本节约检查清单 为了获得最佳结果： 1. 对于委托实施任务，设置 `include_diff:false`。 2. 保持 `scoped_patch.paths` 窄。 3. 添加具体的 `checks` 以便工作者证明完成。 4. 对只读问题使用 `analyze`。 5. 启用 `WORKER_METRICS_FILE` 并按路由/模型比较令牌使用情况。 6. 使用 `read_pack` 代替完整的文件读取和使用 `diff_digest` 代替完整的差异摄入。 7. 使用 `shell` 和 `digest:true` 进行测试/构建/ lint，以便在 Codex 看到它之前总结命令输出。 8. 保持 `start` 低于工作调用的 30%；使用更精细的工具进行搜索、读取、差异消化、历史、草稿和机械编辑。 9. 将 `abnormal.verdict !== "accept"` 视为修复信号，然后再考虑多模型并行审查。对于 `shell`，首先使用 `failure_kind` 和 `required_action`；如果命令退出代码为非零，不要升级到主模型。 10. 使用适合任务的默认模型，并为困难的修订传递保留 `WORKER_ESCALATE_MODEL`；不要因为成本而降低主模型、备用模型或升级模型的级别。 ## 重要环境变量 有关不常见的统计信息、缓存、可靠性和熔断器设置，请参阅 [高级配置](docs/advanced-config.md)。 | 变量 | 用途 | | --- | --- | | `SANDBOX_ROOT` | 允许 worker 作业和 `analyze` 文件读取的根目录。 | | `WORKER_ALLOW_FILESYSTEM_ROOT` | 紧急覆盖。设置为 `1` 以允许在驱动器根目录下执行作业/搜索；默认禁用以防止意外整个磁盘扫描。 | | `ONEAPI_BASE_URL` / `ANTHROPIC_BASE_URL` | 主要网关 URL。 | | `ONEAPI_API_KEY` / `ANTHROPIC_API_KEY` | 主要网关密钥。请勿将其放入 git。 | | `CLAUDE_MODEL` / `ANTHROPIC_MODEL` | 网关使用的实际后端模型。 | | `CLAUDE_CODE_MODEL` | 传递给 Claude Code 进行本地验证的模型名称，通常为 `sonnet`。 | | `USE_OPENAI_ADAPTER` | 设置为 `1` 以使用本地 Anthropic-to-OpenAI 适配器。 | | `MAX_RUNNING_JOBS` | 每个 MCP 的次要限制，用于接受繁重的作业，默认值为 `4`，限制在 `1-100` 之间。 | | `WORKER_GLOBAL_COORDINATION_DIR` | 共享的机器本地 FIFO 状态目录。默认情况下为每个用户在 OS 临时目录下创建一个命名空间。所有应共享限制的 MCP 实例必须使用相同的值。 | | `WORKER_GLOBAL_HEAVY_MAX` | 机器全局活动 `start` 作业限制，默认值为 `1`。 | | `WORKER_GLOBAL_HEAVY_QUEUE_MAX` | 机器全局等待 `start` 作业限制，默认值为 `8`；超过此限制的作业将失败并返回可重试的忙碌错误。 | | `WORKER_GLOBAL_LITE_MAX` | 机器全局主动网关调用限制，用于分析/审查/语义/扇出工作，默认值为 `1`。 | | `WORKER_GLOBAL_LITE_QUEUE_MAX` | 机器全局等待轻量级调用限制，默认值为 `12`；超过此限制的调用将失败并返回可重试的忙碌错误。 | | `WORKER_GLOBAL_ACQUIRE_TIMEOUT_MS` | 全局重或轻槽的最大等待时间，默认值为 `600000` 毫秒。 | | `DIFF_MAX_BYTES` | 返回的最大差异大小。 | | `INCLUDE_DIFF_DEFAULT` | 省略的 `include_diff` 的默认值；设置为 `0` 以省略差异，除非明确请求。 | | `CHECK_OUTPUT_RESPONSE_MAX` | 紧凑的 `get`/`wait` 响应的每个检查输出上限。 | | `WORKER_METRICS_FILE` | 用于 token 使用情况、工具审计和轻量级延迟指标的 JSONL 日志文件的可选路径。 | | `WORKER_QUALITY_TARGETS_FILE` | 可选的路径，用于跟踪版本化的三分支 + 审查者配置，仅由 `quality_mode:"high"` 使用；键由环境变量名称引用。 | | `WORKER_EVAL_SPAN_FILE` | 可选的、独立的 JSONL 日志路径，用于验证直接/工作器 EvalSpan 记录。 | | `WORKER_EVAL_SUITE_ID` / `WORKER_EVAL_TASK_ID` / `WORKER_EVAL_RUN_ID` / `WORKER_EVAL_ARM` | 在隔离的评估运行期间追加到工作器指标的可选关联上下文。 | | `WORKER_PRICE_INPUT` / `WORKER_PRICE_OUTPUT` / `WORKER_PRICE_CACHE` | `npm run stats` 使用的可选的每 1M token 的 USD 价格；仅用于会计核算，永远不是工作器 LLM 成本门控。 | | `WORKER_PRICE_TABLE` | `npm run stats` 的可选 JSON 模型价格覆盖；不得影响主要/备用/升级选择。 | | `WORKER_FAILURE_DIGEST` | 设置为 `1` 以生成廉价网关诊断信息，用于失败的作业。 | | `WORKER_DIGEST_BEFORE_REVISE` | 设置为 `0` 以避免在自动修订之前生成失败摘要。 | | `WORKER_LITE_MODEL` | `analyze`、`review` 和 `failure_digest` 的可选更便宜的模型。 | | `WORKER_LITE_CACHE_DIR` | 轻量级读写工具的可选磁盘缓存目录；必须位于 `SANDBOX_ROOT` 内。 | | `WORKER_LITE_CACHE_TTL_MS` | 轻量级磁盘缓存条目的 TTL，默认值为 `3600000`；设置为 `0` 以绕过缓存。 | | `ADAPTER_PREFIX_CACHE` | 设置为 `1` 以使用前缀缓存友好的 `analyze` 消息。 | | `WORKER_FALLBACK_WARN_EVERY` | 每 N 次备用调用警告一次；默认值为 `5`，设置为 `0` 禁用。 | | `WORKER_OVERALL_TOOL_ERROR_MAX_PCT` | 工作器工具错误率的总门控阈值；默认值为 `5`，且比率必须低于此值。 | | `WORKER_SINGLE_TOOL_ERROR_MAX_PCT` | 每个工具错误率的门控阈值；默认值为 `3`，且比率必须低于此值。 | | `WORKER_CATEGORY_ERROR_MAX_PCT` | 类别级工具错误率的门控阈值；默认值为 `5`。`WORKER_TOOL_ERROR_MAX_PCT` 仍作为遗留别名。 | | `WORKER_TOOL_ERROR_MIN_CALLS` | 应用类别或单个工具错误率门控之前的最小样本计数；默认值为 `10`。 | | `WORKER_TOOL_REVIEW_INTERVAL_MS` | MCP 服务器运行时，工具错误率的运行时审查间隔；默认值为 `10800000`（3 小时）。 | | `WORKER_TOOL_REVIEW_SINCE_MINUTES` | 运行时工具错误率控制的审查窗口；默认值为 `180`。 | | `WORKER_TOOL_REVIEW_GRACE_MS` | 调度审查可以运行的最大延迟；默认值为 `300000`。 | | `WORKER_TOOL_REVIEW_DISABLED` | 设置为 `1` 以禁用运行时审查循环。 | | `WORKER_IDLE_EXIT_MS` | 在没有作业运行时，空闲退出工作器进程的最大时间；默认值为 `300000`（5 分钟）。每个 MCP 请求都会重置截止日期；设置为 `0` 以禁用空闲退出。 | | `WORKER_TOOL_CIRCUIT_BREAKER` | 活动运行时遏制开关；默认启用。设置为 `0` 以禁用每个工具/每个错误类别的电路。 | | `WORKER_TOOL_CIRCUIT_WINDOW_MS` | 即时电路决策的滚动窗口；默认值为 `900000`。 | | `WORKER_TOOL_CIRCUIT_OPEN_MS` | 打开的电路拦截不健康路由的时间；默认值为 `600000`。 | | `WORKER_TOOL_CIRCUIT_MIN_CALLS` | 通用工具错误率电路可以打开之前的最小调用次数；默认值为 `3`。 | | `WORKER_TOOL_CIRCUIT_MIN_ERRORS` | 通用工具电路可以打开之前的最小错误次数；默认值为 `2`。 | | `WORKER_TOOL_ERROR_CLASS_CIRCUIT_MIN_ERRORS` | 每个错误类别的电路可以在相同类别错误发生之前打开的最小错误次数；默认值为 `1`。 | | `WORKER_TOOL_CIRCUIT_IMMEDIATE_CLASSES` | 以逗号分隔的立即打开电路的类别；默认为 `upstream_404,search_timeout,shell_mismatch`。 | | `WORKER_TOOL_CIRCUIT_STATE_FILE` | 持久电路状态路径的可选值。默认为 `WORKER_METRICS_FILE + ".state.json"`，因此开放电路和有界滚动事件快照在 MCP 重启后存活。 | | `WORKER_TOOL_CIRCUIT_STATE_EVENT_MAX` | 持久电路状态的最近工具控制事件的最大数量；默认值为 `200`，设置为 `0` 以仅持久开放电路。 | | `WORKER_TOOL_CIRCUIT_STATE_SAVE_MIN_MS` | 非错误状态快照的最小间隔；默认值为 `30000`。错误和电路打开强制保存。 | | `WORKER_TOOL_CIRCUIT_STATE_LOCK_STALE_MS` | 尽力而为的状态锁定过期阈值；默认值为 `30000`。锁定争用跳过快照而不是阻止工具调用。 | | `WORKER_ESCALATE_MODEL` | 硬修订传递的可选更强模型。 | | `WORKER_RELIABILITY_TIER` | 默认 `start` 可靠性配置文件：`lite`、`standard`、`strict` 或 `critical`；默认为 `standard`。 | | `WORKER_BLOCKING_POLICY` | 缺失可靠性门控的行为：`observe`、`warn` 或 `enforce`；默认为 `observe`。 | | `WORKER_SEMANTIC_GATE` | 声明的语义审查期望：`off`、`warn` 或 `required`；关键作业默认为 `warn`。 | | `WORKER_SEMANTIC_REVIEW_MODEL` | 独立语义验证器使用的专用模型。 `required` 门控通过需要此模型。 | | `WORKER_SEMANTIC_REVIEW_TIMEOUT_MS` | 端到端语义审查截止日期，默认值为 `60000`，上限为 5 分钟。 | | `WORKER_TOOL_BUDGET` | 记入指标和可靠性配置文件的可选工具调用预算上限。 | | `WORKER_ISOLATION` | 设置为 `worktree` 以实现每个作业的 git 工作树隔离。 | | `FALLBACK_BASE_URL` / `FALLBACK_API_KEY` | 可选的备用网关。 | | `FALLBACK_MODELS` | 可选的以逗号分隔的备用模型池，限制为 3 个模型候选人，用于有界路由；在设置时覆盖 `FALLBACK_MODEL` / `FALLBACK_ESCALATE_MODEL`；不是成本上限。 | ## 安全模型 - 所有作业路径必须在 `SANDBOX_ROOT` 内解析。 - `scoped_patch` 拒绝更改声明路径之外的内容。 - 除非使用 `ALLOW_BYPASS_PERMISSIONS=1` 显式启用，否则 `bypassPermissions` 被阻止。 - 机密信息从日志和工具响应中被删除。 - `.env`、存档、日志、`node_modules` 和 `dist` 被 gitignore。 有关负责任的披露和操作说明，请参阅 [SECURITY.md](SECURITY.md)。 ## 验证 ```powershell npm run build npm run test npm run smoke npm run doctor:network npm run skills:validate npm run eval:contracts npm run eval:fixtures npm run codex:audit -- --since-minutes=60 npm run codex:guard ``` `doctor:network` 依赖于您的实际网关凭证。构建、测试和烟雾测试应该离线通过。 `npm run codex:audit -- --since-minutes=60` 检查最近的工作器指标、接收工件覆盖率、持久的 `AGENTS.md` 路由规则、备用使用情况和工作器类别证据。它还打印已知的盲点：直接主线程 shell 输出、完整文件读取、聊天上下文和粘贴的提示词均在 `WORKER_METRICS_FILE` 之外。 `npm run codex:guard` 运行本地 Codex 审计，然后运行 `stats:gate`。 `npm run eval:contracts` 验证 EvalSpan v1 导入器和配对/飞行员关闭规则。`npm run eval:fixtures` 验证冻结的 10 个任务飞行员语料库及其 SHA-256。 使用 `npm run eval:gate -- --import producer.jsonl --out .eval/eval-spans.jsonl` 导入外部用法；使用 `npm run eval:gate -- --input .eval/eval-spans.jsonl --mode pilot` 关闭飞行员。`WORKER_METRICS_FILE` 是操作遥测，而不是非零工作器模型用法的原始提供商导出的替代品；如果没有该导出，飞行员是不完整的。飞行员仅证明测量完整性，不证明成本节省或质量不劣性。完整的生产者和正式清单合同在 [eval/README.md](eval/README.md) 中；使用 `npm run eval:formal -- --input <spans.jsonl> --manifest <manifest.json>` 运行预注册的 200-400 个任务门控。 `npm run eval:quality -- --input <quality-pairs.jsonl>` 评估单独的试验 A -> B -> C 质量资格计划。 通过单元测试或 40+40 工程飞行员不授权高模式作为默认值；只有实际冻结、盲评估的配对才能产生该资格。 请参阅 [QUALITY_FIRST_PLAN.md](QUALITY_FIRST_PLAN.md)、[eval/README.md](eval/README.md) 和双语 [质量优先迭代指南](docs/quality-first-iteration.zh-CN.md)。 `npm run skills:validate` 检查项目特定的 `.claude/skills/` 库，用于为更便宜或更低上下文的工作会话保留项目教义。 `npm run stats` 报告网关令牌使用情况、接收字节/工件使用情况和工作器工具审计。 `npm run stats:gate -- <metrics.jsonl>` 将相同的阈值转换为硬门控，如果失败则退出代码为 2。 类别目标是：搜索 80%，context_pack 70%，command_digest 70%，diff_digest 60%，review 60%，mechanical_edit 50%，history 60%，draft 80%，analysis 60%，而 `start` 必须保持在或低于工作器调用的 30%。 门控模式还会在必需类别没有审计证据、整体工具错误率为 5% 或更高、任何单个工具错误率为 3% 或更高（在样本地板后）、备用比率超过 10%、大接收有效载体缺少工件引用或 `diff_digest` 红队覆盖率低于 30% 时失败。 工具错误率保留用于工作器/工具执行失败；shell 命令失败记录为 `command_status` 并提供本地修复指导，而过时的作业 ID 或无效调用者输入记录为 `rejected`。 当 MCP 服务器运行时，它还会每 3 小时审查最近的工具错误率。 阈值突破或审查运行晚于 `WORKER_TOOL_REVIEW_GRACE_MS`，为后续 `start` 调用启用升级自我修复默认值：`reliability_tier=strict`、`blocking_policy=warn`、`semantic_gate=warn`、`auto_revise=true`，至少有一个修订传递。 显式 `start` 参数仍然胜过这些默认值。 运行时遏制比 3 小时的审查更具侵略性。 每个工具结果更新一个内存滚动窗口。 实际工具执行错误被分类（`upstream_404`、`upstream_error`、`shell_mismatch`、`search_timeout`、`timeout`、`missing_command`、`missing_path`、`permission_denied`、`dependency_missing` 或 `unknown_failure`）。 重复错误或任何立即类错误都会打开临时电路。 在打开时，不健康的路由被拦截为 `rejected` 而不是产生更多错误；`review` 和 `analyze` 在可能的情况下会降级为确定性的本地证据。 开启的电路和有界滚动事件快照被持久化到状态侧车文件，并在 MCP 启动或下一个工具控制决策时重新加载，因此重启不会立即忘记不健康的路由或已经接近电路阈值的工具。 为了保持热路径的便宜，OK 结果仅在 `WORKER_TOOL_CIRCUIT_STATE_SAVE_MIN_MS` 后快照；错误和电路打开强制保存。 Shell 命令业务失败仍然记录 `command_status`，不会算作工具错误。 在 Windows 上，通过 `cmd.exe` 意外发送的 PowerShell 形状的 shell 命令会重试一次，通过 `powershell -NoProfile -ExecutionPolicy Bypass -Command`。 额外的冗余已经到位： - 门控冗余：`codex:guard` 结合最近的路由审计证据与 `stats:gate`。 - 路由冗余：`review`/`analyze` 可以在 LLM 审查路由不健康时回退到本地确定性证据。 - Shell 冗余：shell 不匹配一次重试通过匹配的 Windows shell 之前再表面失败。 - 状态冗余：电路状态原子写入临时文件加重命名，受尽力而为的锁保护，校验和保护，加载时修剪。损坏、不匹配或过期的状态被忽略而不是崩溃 MCP 服务器。 - 重启冗余：小型滚动事件快照恢复开启的电路，因此重启不会擦除已经接近电路阈值的工具。 路由合约测试锁定核心资金/安全不变性： - I3：路由前没有预测分类器调用。 - I5：相同的只读请求击中缓存；主要故障加上备用记录一个成功的上游。 - I6：只读工具不写入工作区。 烟雾测试还验证当前工具表面：`analyze`、`apply_edits`、`cancel`、`diff_digest`、`draft`、`get`、`get_artifact_slice`、`history`、`read_pack`、`review`、`search`、`shell`、`start`、`tail` 和 `wait`。 ## 何时使用它 使用此工作器进行： - 长代码库阅读任务， - 带测试的范围代码编辑， - 重复修复循环， - 廉价模型摘要， - 代码继续规划/审查时 Codex 继续进行。 将主要 Codex 线程保留用于高级别决策、代码审查、最终集成以及需要直接使用您最有能力的模型任务。 ## 归属 该项目建立在多个来源的想法基础上： - **潜在循环推理深度** - Geiping 等人，2025。 `src/reasoning.ts` 中的确定性松弛方法将“将信念松弛到固定点”的想法适配到代码工作器执行信号（检查、范围、退出代码、差异、stderr）。 - **Mythos 推理架构** - 计划 → 循环深度 → 验证 → 校准 → 矛盾 → 门控管道是自成体系的端口适配到具体执行信号。 代码不运行 LLM，不进行网络调用。 - **Claude Code** - Anthropic - 用作工作器作业的后台执行引擎。 - **模型上下文协议（MCP）** - 此工作器实现的开放协议。 此存储库中的所有源代码都是项目维护者的原创作品。 适应的算法在代码注释中清晰地记录了它们的来源。 ## 许可证 MIT - 请参阅 [LICENSE](LICENSE)。