From 0093fbf34144d13f10bb68811be2534b728505dd Mon Sep 17 00:00:00 2001 From: csh Date: Wed, 27 May 2026 16:35:31 +0800 Subject: [PATCH] :memo: docs(main_loop): make plan archive contract tool-neutral --- templates/AGENT_RULES.template.md | 56 +++++++++++-------- .../prompts/coding/update-memory.template.md | 2 +- tests/test_sync_templates_placeholders.py | 15 ++++- 3 files changed, 46 insertions(+), 27 deletions(-) diff --git a/templates/AGENT_RULES.template.md b/templates/AGENT_RULES.template.md index 764ab149..aca661a5 100644 --- a/templates/AGENT_RULES.template.md +++ b/templates/AGENT_RULES.template.md @@ -83,7 +83,8 @@ - `$subagent-driven-development` 仅在 Plan 或平台明确要求时使用， 不是默认执行器 - 执行完成后，必须先运行 `main_loop.py finish` 写回状态， - 再更新 `progress.md` 上半部分摘要，并按主循环收尾要求提交 + 再更新 `progress.md` 上半部分摘要，并按主循环收尾要求归档当前 + Plan 变更 ### Plan 要求 @@ -194,11 +195,11 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ -note "<原因>" ``` -### Plan 场景下的分支与隔离策略 +### Plan 场景下的执行上下文与隔离策略 - 本节仅适用于通过主循环领取并执行 Plan 的场景 -- 默认允许在当前分支直接执行 Plan，包括 `main` / `master` -- 不强制为 Plan 执行创建隔离工作区、临时分支或 `git worktree` +- 默认允许在当前项目上下文直接执行 Plan +- 不强制为 Plan 执行创建隔离上下文 - 仅在以下场景使用隔离工作区： - 用户明确要求隔离执行 - Plan 文本自身明确要求隔离执行 @@ -220,32 +221,39 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ 8. 触碰安全红线时立即停止，不继续后续 Plan 9. 常规模式下可对高风险事项向用户确认；无交互模式按本文件 的“需要确认的场景”自动处理 -10. 每次 `claim` 只领取一个 Plan；写回并完成必要提交后再领取下一个 +10. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后 + 再领取下一个 11. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、 环境需求与待确认事项 -### Plan 完成提交契约 +### Plan 完成归档契约 -- Plan `done` 后必须完成一次 commit，然后才能继续领取下一个 Plan -- 提交顺序： +- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 + Plan；归档方式由项目约定决定 +- 收尾顺序： 1. 完成 Plan 约定验证 2. 运行 `main_loop.py finish -status done` 写回状态 3. 必要时更新 `progress.md` 上半部分摘要和相关 memory - 4. 检查 `git status --short` 与 diff - 5. 只提交当前 Plan 相关改动 + 4. 检查当前变更清单与差异 + 5. 只归档/提交当前 Plan 相关改动 - 当前 Plan 相关改动包括但不限于： - 本轮代码、配置、测试、模板改动 - 当前 Plan 文件（创建、补充、勾选 Task、记录结果等） - `memory-bank/progress.md` 中本轮 `workflow-state`、`plan-status` 与摘要更新 - 必要 memory 更新，例如 `active-context.md`、`decisions.md` -- 不得由 `main_loop.py finish` 自动执行 `git commit` -- 不得把用户已有改动或其他 Plan 的改动混入当前 Plan commit -- 如 Plan `done` 后没有 diff，必须在回复中说明无提交原因 -- `blocked` / `skipped` 不默认提交代码改动；只有状态留痕或已验证的 - 局部成果需要保留时才提交 -- 工作区保持干净后再领取下一个 Plan；如存在不属于当前 Plan 的脏改动， - 常规模式先向用户确认，无交互模式写入风险并停止继续领取 +- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断 +- 允许存在其他 session 的未归档改动，只要它们不属于当前 Plan、 + 不与当前 Plan 范围冲突、且不会被混入本轮归档/提交 +- 不得由 `main_loop.py finish` 自动执行提交或变更归档 +- 不得把用户已有改动或其他 Plan 的改动混入当前 Plan 交付单元 +- 如 Plan `done` 后没有当前 Plan 相关差异，必须在回复中说明无归档原因 +- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的 + 局部成果需要保留时才归档/提交 +- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异属于 + 其他 session 或其他 Plan，保留在原处并在报告中说明 +- 如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户 + 确认；无交互模式写入风险并停止继续领取 ## 通用执行约束 @@ -255,7 +263,7 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ - 遵循 `.agents/`、项目代码风格和现有命名约定 - 只改必要部分，不顺手重构无关内容 - 执行与改动相称的验证；如有相关测试且未被豁免，必须通过 -- 遵循 `.gitattributes` 等换行与文件格式规则 +- 遵循项目声明的换行与文件格式规则 ### 决策与留痕 @@ -271,11 +279,12 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ `AGENT_RULES.local.md` 或 `memory-bank/decisions.md` - 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md` -### Git 操作 +### 归档操作 -- 不使用 `--amend`，除非用户明确要求 -- 不使用 `--force`；如用户坚持，必须先说明风险 -- 不使用 `--no-verify` 跳过 hooks +- 不改写既有归档历史，除非用户明确要求 +- 不覆盖他人或其他 session 的归档成果；如用户坚持，必须先说明风险 +- 不跳过项目约定的归档前检查 +- 如项目没有归档机制，在回复中列出本轮交付的文件清单与验证证据 ### 工具使用 @@ -325,7 +334,8 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \ - [ ] 换行符与文件格式正确 - [ ] 无语法错误或明显运行时错误 - [ ] 已通过 `main_loop.py finish` 写回 Plan 状态 -- [ ] Plan `done` 后已完成对应 commit，或已说明无 diff 无需提交 +- [ ] Plan `done` 后已完成当前 Plan 变更归档/提交，或已说明无当前 Plan + 差异无需归档 --- diff --git a/templates/prompts/coding/update-memory.template.md b/templates/prompts/coding/update-memory.template.md index 9c445b66..5130cb75 100644 --- a/templates/prompts/coding/update-memory.template.md +++ b/templates/prompts/coding/update-memory.template.md @@ -63,7 +63,7 @@ - 流程规则或项目私有约束变更写入 `AGENT_RULES.local.md` - `progress.md` 的状态块只由 `main_loop.py` 维护 - 摘要应与 `workflow-state` / `plan-status` 保持一致 -- 摘要区保持短期状态快照；长期历史依赖 commit、Plan 文件和 +- 摘要区保持短期状态快照；长期历史依赖项目归档记录、Plan 文件和 `decisions.md` ## 禁止事项 diff --git a/tests/test_sync_templates_placeholders.py b/tests/test_sync_templates_placeholders.py index 2a2d79e6..a6b04867 100644 --- a/tests/test_sync_templates_placeholders.py +++ b/tests/test_sync_templates_placeholders.py @@ -173,14 +173,23 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): self.assertIn("memory-bank/progress.md", rules_template) self.assertIn("已有 `in-progress` 优先恢复", rules_template) self.assertIn("按 Plan 文件顺序选择第一个可执行 Plan", rules_template) - self.assertIn("Plan `done` 后必须完成一次 commit", rules_template) self.assertIn( - "不得由 `main_loop.py finish` 自动执行 `git commit`", rules_template + "Plan `done` 后必须完成当前 Plan 变更的归档/提交", rules_template + ) + self.assertIn("Plan 范围是归档/提交边界", rules_template) + self.assertIn( + "不得由 `main_loop.py finish` 自动执行提交或变更归档", + rules_template, ) self.assertIn("当前 Plan 文件", rules_template) self.assertIn("`memory-bank/progress.md`", rules_template) self.assertIn("必要 memory 更新", rules_template) - self.assertIn("工作区保持干净后再领取下一个 Plan", rules_template) + self.assertIn("允许存在其他 session 的未归档改动", rules_template) + self.assertIn("当前 Plan 无遗留差异", rules_template) + self.assertNotIn("git status", rules_template) + self.assertNotIn("git commit", rules_template) + self.assertNotIn("git worktree", rules_template) + self.assertNotIn(".gitattributes", rules_template) self.assertIn("`progress.md` 上半部分是短期状态快照", rules_template) self.assertIn("`active-context.md` 是短期上下文快照", rules_template)