recursive-mode

recursive-mode

用途

使用此技能运行 /.recursive/RECURSIVE.md 中定义的仓库工作流。

此文件是该技能的可安装入口点，不是规范工作流说明。 阶段顺序、审计循环规则、锁规则、附加说明、后期阶段回执、状态／决策更新和记忆维护，均以 /.recursive/RECURSIVE.md 为准。

初始化

开始 recursive-mode 工作前，确保仓库脚手架已就绪：

• /.recursive/RECURSIVE.md
• /.recursive/STATE.md
• /.recursive/DECISIONS.md
• /.recursive/memory/MEMORY.md
• /.recursive/memory/skills/SKILLS.md
• /.recursive/memory/{domains,patterns,incidents,episodes,archive}/
• /.recursive/memory/skills/{availability,usage,issues,patterns}/
• /.recursive/run/
• /.codex/AGENTS.md 主要 Codex 桥接文档
• /.agent/PLANS.md 桥接文档
• 可选的镜像 AGENTS.md 文档（仅当仓库已在使用时）

如果缺少上述任何文件或目录，或其内容已过时，Agent 应在继续前自动初始化仓库。只有当环境中没有可用的 Python 或 shell 运行时，才请用户手动执行初始化。PowerShell 可选，并非必需。

首选的初始化命令：

python "<SKILL_DIR>/scripts/install-recursive-mode.py" --repo-root .
python3 "<SKILL_DIR>/scripts/install-recursive-mode.py" --repo-root .
bash "<SKILL_DIR>/scripts/install-recursive-mode.sh" --repo-root .
powershell -ExecutionPolicy Bypass -File "<SKILL_DIR>/scripts/install-recursive-mode.ps1" -RepoRoot .
pwsh -NoProfile -File "<SKILL_DIR>/scripts/install-recursive-mode.ps1" -RepoRoot .

重要说明：

• npx skills add ... 会将技能包安装到 Agent 目录中。
• 随后应在首次使用 recursive-mode 时自动创建目标仓库脚手架，或通过已配置的会话启动钩子创建。
• Python 和 Bash 路径是首选方案，应能在 macOS 和 Linux 上运行，无需 PowerShell。
• 手动初始化命令是备用方案，并非首选的常规体验。

读取顺序

1. 阅读 /.recursive/RECURSIVE.md。
2. 如存在，阅读 /.codex/AGENTS.md，将其作为主要 Codex 桥接文档。
3. 仅当仓库使用其他 AGENTS.md 副本时，才将其作为镜像桥接指南阅读。
4. 如存在，阅读 /.agent/PLANS.md，将其作为主要 Codex 计划桥接文档。
5. 阅读 /.recursive/STATE.md。
6. 阅读 /.recursive/DECISIONS.md。
7. 阅读 /.recursive/memory/MEMORY.md。
8. 仅加载 /.recursive/memory/ 下的相关记忆文档。

如果任何桥接文档与 /.recursive/RECURSIVE.md 冲突，应遵循 /.recursive/RECURSIVE.md。

操作路径

• 规范运行根目录：/.recursive/run/<run-id>/
• 规范工作流说明：/.recursive/RECURSIVE.md
• 规范状态文件：/.recursive/STATE.md
• 规范决策记录：/.recursive/DECISIONS.md
• 规范记忆路由文件：/.recursive/memory/MEMORY.md

触发示例

• Implement requirement '<run-id>'
• Run Recursive Phase 2 for .recursive/run/<run-id>/
• Resume requirement '<run-id>' after manual QA
• Verify locks for .recursive/run/<run-id>/

实用脚本

• scripts/install-recursive-mode.py
• scripts/install-recursive-mode.ps1
• scripts/install-recursive-mode.sh
• scripts/recursive-init.py
• scripts/recursive-init.ps1
• scripts/recursive-status.py
• scripts/recursive-status.ps1
• scripts/lint-recursive-run.py
• scripts/lint-recursive-run.ps1
• scripts/recursive-review-bundle.py
• scripts/recursive-review-bundle.ps1
• scripts/recursive-closeout.py
• scripts/recursive-closeout.ps1
• scripts/recursive-router-init.py
• scripts/recursive-router-init.ps1
• scripts/recursive-router-probe.py
• scripts/recursive-router-probe.ps1
• scripts/recursive-router-configure.py
• scripts/recursive-router-configure.ps1
• scripts/recursive-router-invoke.py
• scripts/recursive-router-invoke.ps1
• scripts/recursive-router-resolve.py
• scripts/recursive-router-resolve.ps1
• scripts/recursive-router-validate.py
• scripts/recursive-router-validate.ps1
• scripts/recursive-subagent-action.py
• scripts/recursive-subagent-action.ps1
• scripts/recursive-lock.py
• scripts/recursive-lock.ps1
• scripts/verify-locks.py
• scripts/verify-locks.ps1
• scripts/check-reusable-repo-hygiene.py
• scripts/check-reusable-repo-hygiene.ps1
• .recursive/scripts/recursive-training-grpo.py
• .recursive/scripts/recursive-training-grpo.ps1
• .recursive/scripts/recursive-training-phase8-trigger.py
• .recursive/scripts/recursive-training-phase8-trigger.ps1
• .recursive/scripts/recursive-training-extract.py
• .recursive/scripts/recursive-training-extract.ps1
• .recursive/scripts/recursive-training-sync.py
• .recursive/scripts/recursive-training-sync.ps1
• .recursive/scripts/recursive-training-loader.py
• .recursive/scripts/recursive-training-loader.ps1
• .recursive/scripts/recursive-training-mcp.py
• .recursive/scripts/recursive-training-mcp.ps1

子技能

• ../recursive-spec/SKILL.md
• ../recursive-worktree/SKILL.md
• ../recursive-debugging/SKILL.md
• ../recursive-tdd/SKILL.md
• ../recursive-review-bundle/SKILL.md
• ../recursive-router/SKILL.md
• ../recursive-subagent/SKILL.md
• ../recursive-training/SKILL.md — 从已完成的运行中提取持久的经验知识

使用这些子技能遵循其专门规范，但请将 /.recursive/RECURSIVE.md 保留为整体工作流约定的唯一事实来源。

规范的路由 CLI 配置位于：

• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

感知路由的委派执行

当此技能或任何递归子技能即将调用另一个模型或外部 CLI，以进行委派审计、审查、有界实现或其他路由子 Agent 工作时，请在选择 CLI/模型之前立即从磁盘重新读取这些路由文件。

如果仓库策略已定义路由或回退行为，请勿为路由委派硬编码提供方或模型字符串。

如果涉及路由委派，请优先使用 ../recursive-router/SKILL.md 以及规范的 recursive-router-resolve 和 recursive-router-invoke 脚本，而不是自定义模型选择逻辑。

如果已明确请求路由委派，或者所选角色的 recursive-router-resolve 返回 external-cli，请勿用本地/自审工作来代替该委派名额，除非生效路由为 fallback-local、local-only、blocked 或 ask-user，且已记录该结果。控制器可以在根据实际文件、差异和递归产物进行核验后拒绝路由输出，但未经核验的本地工作不能代替已配置的路由实现者、测试者、审查者、审计者或规划者角色。

如果路由调用返回 success: false、以非零状态退出，或报告了有界角色应负责修复的问题，请执行审计-修复-重试循环：保留失败尝试作为证据，明确告知路由子 Agent 要修复的内容，修复后通过相同路由重新运行，然后在本地核验新输出后再予以接受。请勿根据非零退出的路由尝试，将委派角色或阶段门标记为已完成。

从隔离工作树派发之前，请确保该工作树中存在最新的路由策略和发现清单。发现清单通常未跟踪，因此新建的工作树可能包含 /.recursive/config/recursive-router.json，但不包含 /.recursive/config/recursive-router-discovered.json；在解析或调用路由之前，请从该工作树刷新发现信息，或从控制器/源仓库复制当前清单，然后在阶段产物或操作记录中记录路径和结果。

可选附加组件

• recursive-benchmark 不属于默认递归模式软件包的组成部分。
• 仅当用户明确要求对递归模式进行基准测试时才安装它，最好通过 find-skills 安装，或添加其专用基准测试附加组件软件包或仓库源。 对于经过审计的阶段，已安装的工作流要求依次执行 draft -> audit -> repair -> re-audit -> pass -> lock，且必须先满足 Audit: PASS，Coverage/Approval 才能通过。 将 ## Worktree Diff Audit 视为按阶段划分：Phase 2 负责规划完整性以及预期的产品/工作树路径，Phase 3-4 负责实际的产品/工作树偏差，Phase 6 负责 /.recursive/DECISIONS.md，Phase 7 负责 /.recursive/STATE.md，Phase 8 负责 /.recursive/memory/**。 新运行应使用 Workflow version: recursive-mode-audit-v2，其中 Phase 1 必须包含 ## Source Requirement Inventory，Phase 2 必须包含 ## Requirement Mapping、## Plan Drift Check 和规划阶段的 ## Requirement Completion Status。 对于 Phase 3，声明 TDD Mode: strict|pragmatic。Strict 模式要求提供具体的 RED 和 GREEN 证据路径。Pragmatic 模式要求明确说明例外理由，并提供补偿性证据。 对于 Phase 5，声明 QA Execution Mode: human|agent-operated|hybrid。不要伪造 agent-operated QA 的人工签署，也不要遗漏 human 或 hybrid QA 的签署。 对于委派审查，优先使用 .recursive/scripts/recursive-review-bundle.py 或 .recursive/scripts/recursive-review-bundle.ps1，以便 Phase 3.5 记录规范的 Review Bundle Path。 如果子 Agent 的重要工作对某个阶段有贡献，请将其记录在 /.recursive/run/<run-id>/subagents/ 下，并在接受前根据实际文件、实际差异和实际递归产物核验操作记录。对于委派审查/审计，优先使用稳定的已审查产物作为 Current Artifact，而不是可变的草稿回执。 经过审计的阶段必须记录 Subagent Capability Probe、Delegation Decision Basis、## Subagent Contribution Verification 和 ## Requirement Completion Status。 当有可用子 Agent 且上下文包完整时，默认采用委派审计/审查路径。如果控制器仍使用 Audit Execution Mode: self-audit，请记录具体的 Delegation Override Reason。 在 ## Requirement Completion Status 中，根据所选状态酌情使用更完整的要求处置字段：Changed Files、Implementation Evidence、Verification Evidence、Deferred By、Scope Decision、Blocking Evidence 和 Addendum。 没有具体的 Changed Files，不要标记为 implemented 或 verified。没有独立的验证证据，不要标记为 verified。 将附录视为权威的有效输入。存在相关附录时，请在 Inputs 下列出，并在 ## Effective Inputs Re-read 中重新读取，在 ## Earlier Phase Reconciliation 中协调处理。 审查包应自动包含相关附录；书面的 Phase 3.5 审查应在审查说明中引用基于审查包的上游产物、附录以及已更改文件或代码引用。 00-worktree.md 是差异依据的事实来源。记录基线类型/引用、比较引用、规范化后的基线/比较对象，以及规范化差异命令；之后不要悄然另行采用不同依据。 如果本次运行让仓库获得了关于技能可用性、适用性、委派审查质量或技能发现结果的持久经验，请使用 Phase 8 更新 /.recursive/memory/skills/ 下的技能记忆。 Phase 8 还应记录本次运行中的技能使用情况，然后再将经验教训提升为持久记忆。 如果运行计划进行委派审查、生成审查包或开展烟雾测试框架的可移植性工作，请在规划或审计前阅读 /.recursive/memory/skills/SKILLS.md 和相关技能记忆分片。 如果运行需要的专门能力当前不可用，且存在 find-skills 技能，请优先使用它。否则直接使用 Skills CLI（npx skills find、npx skills add、npx skills check、npx skills update），并在技能使用与任务相关时记录结果。 除非仓库有意追踪，否则差异审计会忽略 __pycache__/、*.pyc、.pytest_cache/、.mypy_cache/ 和 .ruff_cache/ 等偶然产生的运行时副产物。 将 Phase 6、Phase 7 和 Phase 8 的回执视为简明的增量回执，指向最终控制平面文档，而不是重述大段内容。 正常锁定时应使用 .recursive/scripts/recursive-lock.py 或 .recursive/scripts/recursive-lock.ps1，而不是手动编辑 Status、LockedAt 和 LockHash。 recursive-lock 会强制执行单调阶段门禁：如果运行目录中存在任何较早阶段且该阶段尚未处于 LOCKED 状态，就会拒绝锁定。若要重新打开已锁定的产物并将其重置为 DRAFT（这也会使下游回执失效），请使用 --reopen 标志。 在 Windows 上，请从真实工作树路径运行 Node/Vite/Vitest 命令，不要使用 subst 或映射驱动器别名。 评估或构建浏览器本地应用时，请查阅 references/local-first-web-app-checklist.md，了解常见的导入/持久化/QA 边缘情况。 如果正在改进的仓库本身是可复用的技能/工作流仓库，除非当前会话运行文件夹、证据日志、审查包、子 Agent 操作记录或临时路径引用是有意纳入的测试固件，否则不要提交它们；在认定仓库干净之前，请使用 scripts/check-reusable-repo-hygiene.py 或 scripts/check-reusable-repo-hygiene.ps1。