diff --git a/docs/116/codex-improve.md b/docs/116/codex-improve.md index 1b52723..10d4bb5 100644 --- a/docs/116/codex-improve.md +++ b/docs/116/codex-improve.md @@ -4,7 +4,7 @@ ## 适用场景 -当你希望先弄清问题和方案,再让 Codex 修改代码时使用 Improve。它把工作分成 advisor 审查与规划、隔离 executor 实现、主会话验收,以及按风险触发的独立复核。调用 `$improve` 不会改变当前 Codex 会话使用的模型或 reasoning effort。 +当你希望先弄清问题和方案,再让 Codex 修改代码时使用 Improve。它把工作分成 advisor 审查与规划、隔离 executor 实现、主会话实现审查、按风险触发的独立复核,以及必要时交给用户或外部系统完成的实际验收。调用 `$improve` 不会改变当前 Codex 会话使用的模型或 reasoning effort。 进入目标仓库并启动 Codex: @@ -51,15 +51,21 @@ advisor 不会把第一版草稿直接交给 executor。`plan` 和 `review-plan` - 目标行为、约束、依赖、验证、回滚、停止条件和验收标准; - Engineering contract(仓库已有的 build、test、lint、CI、policy、classifier、兼容性、发布和部署等工程约束)及其影响。 +每项检查还会被明确分为三类: + +- implementation gate:Codex 可以通过测试、构建、浏览器、截图、日志、指标或模拟器验证的检查,必须在实现获批前完成; +- deferred acceptance:当前环境确实无法完成的实体机、人工判断或外部系统验收; +- observation:合并后的长期观察项,除非计划写明失败阈值和状态变化,否则不阻塞当前改动。 + 这些内容必须足以让没有历史对话的新 executor 执行。发生上下文压缩、会话恢复或中断后,计划和仓库证据才是任务语义来源,聊天摘要只用于定位。 如果实现需要改变仓库既有的 CI、测试政策、门控规则、发布策略或兼容边界,advisor 必须解释影响并以 `BLOCKED` 等待批准,不能把这类变化作为附带修改自动纳入范围。 ## 隔离执行 -`$improve execute <计划文件>` 会从当前 Git `HEAD` 创建临时 branch 和 worktree。worktree 是同一个 Git 仓库的独立工作目录,executor 只能在其中修改计划允许的路径。 +`$improve execute <计划文件>` 会从当前 Git `HEAD` 创建独立 branch 和 worktree。worktree 是同一个 Git 仓库的独立工作目录,executor 只能在其中修改计划允许的路径。 -主目录中尚未提交的修改不会自动进入 worktree,因此执行前应确认 executor 需要的基础改动已经提交。executor 会运行计划规定的检查并留下未提交 diff,但不会自行提交、合并、推送或创建 PR。临时 worktree 会保留给当前 Codex 会话检查和继续修改。 +主目录中尚未提交的修改不会自动进入 worktree,因此执行前应确认 executor 需要的基础改动已经提交。executor 会运行计划规定的检查并留下未提交 diff,但不会自行提交、合并、推送或创建 PR。worktree 保存在 `$XDG_STATE_HOME/codex-improve/worktrees`,未设置该变量时使用 `~/.local/state/codex-improve/worktrees`;会话中断或机器重启后仍可从输出的路径继续。 ## 外部实践与独立复核 @@ -70,9 +76,21 @@ executor 完成后,当前会话先检查完整 diff、验证结果和 Engineer - 行为重要或存在歧义时,correctness reviewer 检查正确性、安全、回归、测试以及计划是否落实。 - 引入抽象、模块、公开接口、依赖、兼容层、跨所有者边界、复杂生命周期、并发或安全逻辑时,elegance reviewer 检查复用、抽象必要性、模块边界、locality、speculative flexibility 和可删除代码。 -reviewer 接收一份不依赖聊天记录的完整 evidence dossier(证据包),并输出结构化 verdict。Elegance review 会把 Ponytail 的复杂度检查作为一个内部视角,但其建议只是待验证假设;不能为了减少代码而破坏正确性、用户决定、仓库规则或必要测试。 +reviewer 接收一份不依赖聊天记录的完整 evidence dossier(证据包),并输出结构化 verdict。当前主会话只运行一次 Ponytail 复杂度检查,并把原始建议及采纳或拒绝理由放入证据包;elegance reviewer 复核这些证据,不会再次调用 Ponytail。Ponytail 建议只是待验证假设,不能为了减少代码而破坏正确性、用户决定、仓库规则或必要测试。 + +review 有分阶段收敛规则和最终运行保护,但具体 token 与时间阈值仍在观察,不是稳定的用户承诺。reviewer 不会自动重试;无法形成可靠结论时返回 `INCONCLUSIVE`,需要用户批准后才能重试或改变计划。事件日志、结构化结果和诊断文件保存在 `$XDG_STATE_HOME/codex-improve/reviews`,未设置该变量时使用 `~/.local/state/codex-improve/reviews`。 + +## 实现审查与实际验收 + +Improve 分开记录三件事,避免把“代码已经正确实现”和“用户已经在真实环境确认”混成同一个结论: + +- Implementation review:实现仍待审查、已经批准、需要修改或被阻断; +- Checkpoint:当前改动还没有恢复点、已有可恢复目标,或已经集成; +- External acceptance:不需要外部验收、等待验收、已经通过或已经失败。 + +独立 reviewer 只判断实现和 agent 可获得的证据。需要观察实体机 UI、操作真实硬件或等待外部系统时,尚未执行的验收不会让一个正确实现被判为 `BLOCK`。主会话会先完成所有 implementation gates,再准备一个精确 checkpoint,例如持久 worktree 与 diff、commit、branch、PR 或 deployment ID。涉及 commit、push、部署或合并时,仍会先按仓库规则请求批准。 -review 有分阶段收敛规则和最终运行保护,但具体 token 与时间阈值仍在观察,不是稳定的用户承诺。reviewer 不会自动重试;无法形成可靠结论时返回 `INCONCLUSIVE`,需要用户批准后才能重试或改变计划。 +只有实现已批准、checkpoint 可以恢复,而且验收已经可以针对该目标执行时,计划才进入 `ACCEPTANCE PENDING`。此时可以退出终端、切换机器或稍后再回复;下一次对话会从计划和 checkpoint 恢复,而不是依赖聊天记忆。验收失败若证明实现有缺陷,任务回到实现阶段;如果只是代理、网络或其他无关环境故障,则保留待验收状态并记录证据。 ## 完整流程 @@ -84,8 +102,10 @@ review 有分阶段收敛规则和最终运行保护,但具体 token 与时间 -> executor 在独立 worktree 中修改和验证 -> 当前会话核对完整 diff 与 Engineering contract -> 按风险触发 correctness / elegance 独立复核 - -> 当前会话验证 reviewer 结论并给出验收结果 - -> 你决定接受、要求修改或放弃 + -> 当前会话验证 reviewer 结论并给出实现审查结果 + -> 若无需外部验收,你决定是否集成 + -> 若需要实体机、人工或外部验收,先准备可恢复 checkpoint + -> 你针对该 checkpoint 验收并反馈,记录结果并在集成后进入 DONE ``` ## 预定义 agents @@ -94,7 +114,7 @@ review 有分阶段收敛规则和最终运行保护,但具体 token 与时间 | Agent / profile | 模型与 effort | 权限 | 负责什么 | | --- | --- | --- | --- | -| 当前 Codex 会话(advisor) | 沿用当前会话设置 | 审查和规划阶段不修改源代码;只写计划 artifact(通常是 Markdown 计划文件) | 理解仓库、筛选问题、与用户确认方向、收敛计划,并在执行后承担最终验收。 | +| 当前 Codex 会话(advisor) | 沿用当前会话设置 | 审查和规划阶段不修改源代码;只写计划 artifact(通常是 Markdown 计划文件) | 理解仓库、筛选问题、与用户确认方向、收敛计划,并在执行后负责实现审查与外部验收交接。 | | `improve-scout` | `gpt-5.6-luna` + `high` | 只读 | 在大型审查中分区寻找候选问题;必要时围绕明确的外部实践问题收集一手社区证据。它只提供线索,不修改代码或作最终裁决。 | | `improve-executor` | `gpt-5.6-sol` + `medium` | 仅可写独立 worktree | 默认执行器;按照 `READY` 计划修改代码、运行检查并留下未提交 diff。 | | `improve-executor-deep` | `gpt-5.6-sol` + `xhigh` | 仅可写独立 worktree | 处理技术不确定性高、跨模块或需要更深入推理的计划;更慢且 token 消耗更高,不作为默认选择。 | @@ -105,7 +125,7 @@ review 有分阶段收敛规则和最终运行保护,但具体 token 与时间 Improve 会在内部使用两个命令: -- `codex-improve-exec` 创建临时 branch/worktree,并启动普通或 deep executor。 +- `codex-improve-exec` 创建持久 branch/worktree,并启动普通或 deep executor。 - `codex-improve-review` 用对应的只读 profile 运行 correctness 或 elegance review,保存结构化结果和诊断信息。 普通用户通常不需要直接调用它们,只需在 Codex 对话中使用 `$improve ...`。 diff --git a/flake.lock b/flake.lock index 096aaf6..9ba9925 100644 --- a/flake.lock +++ b/flake.lock @@ -1415,11 +1415,11 @@ "swww": "swww" }, "locked": { - "lastModified": 1784103861, - "narHash": "sha256-ixzEv/vtPZUz3Bpnt1z1PPqOfmDWPbE/56SK2325fYs=", + "lastModified": 1784165407, + "narHash": "sha256-jNBDZzaieAeBcVPsqobToiS7F8obdRgtb688XWqKTxY=", "owner": "bioinformatist", "repo": "dotfiles", - "rev": "8d10211367b86c5a5030c4763c0cecdd9b08192e", + "rev": "b0faf3233fe555ab0f69abd8d5399e2594756619", "type": "github" }, "original": {