recursive-router

recursive-router

当 recursive-mode 和 recursive-subagent 已经确定了委派角色，而你希望由用户可编辑的 CLI/模型策略驱动路由，而不是由控制器临时决定时，使用此技能。

此技能不会放宽 recursive-mode 的要求。在主 Agent 根据实际文件、实际差异和实际递归产物完成核验之前，路由产生的外部输出仍不可信。

控制器边界

主协调器仍然是用户当前在 CLI、IDE 或 Agent 会话中交互的模型。

recursive-router 不会成为第二个协调器，也不会成为第二套工作流规范。它只帮助当前控制器为有明确边界的委派角色选择并调用外部 CLI/模型。

当前控制器仍负责：

• 选择并安排当前递归阶段
• 在委派前阅读起控制作用的递归文档
• 使用 recursive-subagent 以及规范的 review-bundle / prompt-bundle 契约
• 准备委派上下文包或提示词包
• 确保路由到的角色收到所需文档和准确的输出契约
• 拒绝不完整、缺少上下文或不符合契约的路由输出
• 决定是修复、重新路由、回退，还是继续工作流
• 修复委派输出引入的问题，并重新运行审计-修复循环，直到实际门禁通过

调用边界

路由器设置、本地 CLI 发现和路由重新配置均为自选操作，因为这些操作可能会检查用户设备上的本地 CLI 安装及提供商/模型配置。仅当用户明确请求路由，或现有的活动路由策略需要刷新清单才能执行时，才运行 init、probe、configure 或其他发现/配置步骤。

明确请求路由的有效示例包括包含以下短语的表达：

• route
• routing
• router
• set model
• set provider
• configure routing
• configure model routing
• use <provider/model> for <role>

当用户以这类表达请求新建配置时，先询问用户是否希望为此仓库设置提供商间的模型路由。在用户确认之前，不要检查本地设备状态，也不要修改路由策略。

如果用户拒绝，或只是想了解路由器的行为，则不要检查本地设备，也不要修改路由策略。

用户明确请求路由委派后，或选定的规范角色已有活动的已配置外部路由后，路由器即在适用范围内，控制器不应再询问是否要将其用于该委派任务。活动的已配置外部路由是指 /.recursive/config/recursive-router.json 中该角色的 enabled: true、mode: "external-cli"、非空的 cli 和非空的 model，或者用户为该角色提供了明确的路由绑定。

如果 recursive-router-resolve 返回 external-cli，则通过 recursive-router-invoke 派发。只有当有效路由解析为 fallback-local、local-only、blocked 或 ask-user 时，本地执行/自审才可作为可接受的替代方案，并且必须在阶段产物或子 Agent 操作记录中记录该路由结果。控制器可以在核验后拒绝路由输出并在本地修复，但必须记录这次拒绝/修复，不能把本地修复当作路由角色已完成任务的证明。

如果 recursive-router-invoke 返回 success: false 或非零 exit_code，则应将此次路由尝试视为失败，即使 output_text 中包含有用的助手文本也不例外。保留该输出作为诊断证据，记录失败的尝试，然后修复提示词/上下文，或要求同一路由角色修复所报告的问题并重试。不得接受该路由角色的结果、将阶段门禁标记为 PASS，或声称测试员/实现者/审查者已完成任务。

用途

使用 recursive-router 来：

• 探测当前环境中有哪些受支持的 CLI 可用
• 检查生成的 CLI ID 和已公布模型清单
• 在编写策略前安全地配置已验证的 CLI／模型绑定
• 将子 Agent 角色解析为已配置的 CLI／模型对
• 当策略规定为 ask 时，询问用户尚未解决的角色绑定
• 当路由到的 CLI 不可用时，保留明确的回退行为

触发示例

• Set up routing between Codex, Kimi, and Opencode for this repo
• Use the router for delegated review roles
• Route code-reviewer through Kimi
• Set model bindings for the audit roles
• Configure model routing between providers

规范路径

• 路由策略：/.recursive/config/recursive-router.json
• 发现清单：/.recursive/config/recursive-router-discovered.json

规范脚本名称为 recursive-router-*。 旧版 recursive-router-cli-* 脚本名称仍作为兼容包装器保留；在新的控制器流程和文档中，优先使用规范名称。

规范角色

• orchestrator
• analyst
• planner
• implementer
• code-reviewer
• memory-auditor
• tester

路由器策略中会显式列出 orchestrator，以便在同一配置中呈现控制器角色；但默认情况下，它应保持为 local-only，并使用 local-controller 作为回退角色。它负责最终集成、修复和验收：其他路由角色可以提出范围明确的工作，但编排器必须修复它们遗留的缺陷，并确保所有必需的检查关卡均通过。

旧版兼容别名仍会解析为与阶段对应的角色：

• phase-auditor -> analyst
• traceability-auditor -> planner
• bounded-implementer -> implementer
• test-reviewer -> tester

阅读顺序

1. 阅读 /.recursive/RECURSIVE.md。
2. 阅读 ../recursive-subagent/SKILL.md。
3. 阅读 /.recursive/config/recursive-router.json。
4. 阅读 /.recursive/config/recursive-router-discovered.json。
5. 阅读 /.recursive/memory/skills/SKILLS.md，以及与当前阶段能力相关的任何委派审查或能力说明。

recursive-mode 和 recursive-subagent 仍负责阶段顺序、审计标准、审查材料包规则和验收标准。不要在此处重述或弱化这些内容。

必须遵守的行为

• 路由是对 recursive-subagent 的扩展，而不是替代。
• 当前 CLI/IDE/Agent 会话仍是唯一的工作流控制器；路由的 CLI 是助手，而不是自主的阶段管理器。
• 除非用户明确启用了路由并确认了设置，否则不要扫描本地 CLI/提供方/模型状态。
• 外部 CLI 始终是可选基础设施。
• 如果无法使用路由的 CLI 或模型，应遵循已配置的回退行为，而不是降低阶段标准。
• 当策略规定为 ask 时，不要暗自编造 CLI/模型绑定。
• 未经主 Agent 根据真实仓库状态进行验证，不得接受任何路由输出。
• 不要让路由角色自行选择阶段、输入或验收标准。
• 路由角色不负责最终验收。编排器仍负责审计-修复循环，并且必须持续修复或重新路由，直到阶段门槛确实通过。
• 派发前，为路由角色提供真实的上下文包：规范审核包或提示词包路径、确切的产物路径、相关上游文档、必需的检查项以及确切的输出格式。
• 优先使用简短的派发提示，指向规范工作流产物，例如 00-requirements.md、01-as-is.md、02-to-be-plan.md、当前阶段产物或生成的审核包，而不是另行编造一套仅供路由使用的工作流说明。
• 不要仅用“阅读文档”等含糊的文件引用来委派任务，因为路由模型需要具体上下文才能成功完成任务。
• 如果路由模型表现出较弱的指令遵循能力，请在指派任务时直接提供所需的具体要求、产物或章节摘录，并拒绝任何未引用或未遵循这些内容的输出。

发现

使用路由脚本初始化、探测、验证并解析路由：

python ./.recursive/scripts/recursive-router-init.py --repo-root .
python ./.recursive/scripts/recursive-router-probe.py --repo-root . --json
python ./.recursive/scripts/recursive-router-configure.py --repo-root . --set code-reviewer=codex:gpt-5.4-mini --json
python ./.recursive/scripts/recursive-router-invoke.py --repo-root . --role code-reviewer --prompt-file "./.recursive/run/<run-id>/router-prompts/code-reviewer-bundle.md" --json
python ./.recursive/scripts/recursive-router-validate.py --repo-root .
python ./.recursive/scripts/recursive-router-resolve.py --repo-root . --role code-reviewer --json
pwsh -NoProfile -File ./.recursive/scripts/recursive-router-probe.ps1 -RepoRoot . -Json
pwsh -NoProfile -File ./.recursive/scripts/recursive-router-configure.ps1 -RepoRoot . -Set code-reviewer=codex:gpt-5.4-mini -Json
pwsh -NoProfile -File ./.recursive/scripts/recursive-router-invoke.ps1 -RepoRoot . -Role code-reviewer -PromptFile "./.recursive/run/<run-id>/router-prompts/code-reviewer-bundle.md" -Json

内置发现目标包括：

• codex
• kimi
• opencode

内置模型发现来源包括：

• codex：使用原生 model/list 的 codex app-server --listen stdio://；如果 app-server 发现不可用，则回退到 ~/.codex/models_cache.json
• kimi：从 ~/.kimi/config.toml 获取已配置的模型别名，以确保路由值与 kimi --model ... 接受的值一致
• opencode：通过 opencode models 获取已配置或已认证的 CLI 模型清单

对于 opencode，路由器发现应使用 CLI 已配置或已认证的提供方和模型清单，使路由模型选项来自用户实际的 opencode 配置，而不是硬编码列表。

对于 opencode，只要已认证的模型清单中包含提供方限定的模型 ID（例如 github-copilot/... 和 opencode/...），它们就是有效的路由目标。

对于 codex，下游分发器需要实际发送提示词时，路由传输应优先使用原生 app-server 协议，而不是 codex exec。

自动化时不要依赖不存在的顶层 codex model 命令。手动抽查时，codex exec -m <model> 很有用，但发现依据仍应是 app-server model/list。

对于 kimi，自动化时不要将 /model 视为接口。/model 是会话内的交互式选择器，不是顶层发现命令；路由配置必须使用可调用的别名键，而不是底层模型的原始标识。

启动器的详细信息可能因操作系统、Shell 和设备而异。内置适配器命令仅作默认值。如果实际的本地启动器或调用形式不同，应先探索环境，再将该机器专属绑定记录到内置 CLI 的 cli_overrides 或完全自定义适配器的 custom_clis 中，而不是将仓库级路径或包装器假设硬编码进去。

路由策略中也可以定义自定义 CLI。

策略超时行为：

• 默认探测超时为 50000 毫秒。
• 默认调用超时为 180000 毫秒。
• 早于 defaults.invoke_timeout_ms 的旧版路由策略仍然有效；它们会沿用当前默认调用超时，而不会在验证时失败。

从实时路由中总结的 Windows 启动器注意事项

• 如果 npm 或 PATH 垫片已被移除，请通过 cli_overrides 将 codex 或 opencode 绑定到实际可执行文件路径，而不要假设 codex.cmd 或 opencode.cmd 仍然存在。
• 对于 codex，请将覆盖项指向支持 app-server 的真实 codex.exe；路由传输应保持为原生 app-server 路径。
• 对于 opencode，请使用专用 CLI 二进制文件，例如 opencode-cli.exe，而不是桌面应用封装程序，例如 OpenCode.exe。
• 对于简单的一次性 kimi shell 调用，kimi --quiet --prompt "..." 可以使用，但 CLI 仍可能附加会话元数据，例如 <choice>STOP</choice> 和恢复指令。
• 其他 Agent 需要机器可读的 kimi 输出时，优先使用 kimi --work-dir "<repo>" --print --output-format stream-json --max-ralph-iterations 0 --prompt "..."，并且只从结构化流中解析助手文本。将 Ralph 最大迭代次数设为 0，可避免一次性路由任务继承本地循环控制选项，例如 <choice>STOP</choice>。
• 如果调用方使用 ACP，并且需要持久服务而不是一次性 shell 委派，受支持的 Kimi ACP 入口点是 kimi acp。
• 对于简单的一次性 opencode shell 调用，opencode-cli.exe run "..." 可以使用；对于机器可读的编排，优先使用 opencode-cli.exe run --format json --dir "<repo>" "..."。
• 如果调用方使用 ACP，并且需要持久服务而不是一次性 shell 委派，请使用 opencode-cli.exe acp --cwd "<repo>"，而不是桌面封装程序。
• 委派实际任务时，请传入明确的工作目录：kimi 使用 --work-dir，opencode 使用 --dir。
• 仅当上游调用方实际使用 ACP 时才使用 ACP 模式。对于常规路由委派，优先使用 kimi --print ... 或 opencode-cli.exe run ...。
• 已通过此计算机上的 CLI 帮助信息直接验证 kimi 和 opencode 的 ACP 服务入口点。在当前环境中验证可用之前，不假定 ACP 客户端／路由模式（例如 acpx）可用。

推荐的路由工作流

1. 如果仓库尚无路由器配置框架文件，请运行 init。
2. 运行 probe 并检查 /.recursive/config/recursive-router-discovered.json。
3. 请用户以简洁的 role=cli:model 格式提供任何尚未解决的角色绑定。
4. 使用 recursive-router-configure.py 或 .ps1 应用所需绑定，确保每条路由在保存前都经过验证。
5. 根据 recursive-subagent 中的约定，为确切的委派任务构建或刷新规范审查包或路由提示词包。
6. 在将要分派该角色的同一仓库/工作树中，确保 /.recursive/config/recursive-router.json 和 /.recursive/config/recursive-router-discovered.json 存在且为最新。发现清单是本地文件，可能未被跟踪，因此在新的工作树中解析路由前，请先刷新或复制该清单。
7. 在委派执行前立即针对特定角色运行 resolve，使回退行为与当前环境保持一致。
8. 如果决策为 external-cli，请使用 recursive-router-invoke.py 或 .ps1 分派范围明确的任务，记录元数据/输出路径，然后在验收前根据真实仓库状态验证结果。
9. 如果调用失败，请修复上下文或分派提示词，并重新运行相同的路由角色。当子 Agent 输出指出了可修复的问题时，控制器应明确指示该路由角色在其限定的职责范围内修复问题，然后重新运行控制器验证和路由检查。

控制器进行更改时，优先使用配置脚本，而不是手动编辑策略，因为配置并验证的流程可防止错误或过时的绑定被悄然保存。

控制器实际分派路由任务时，优先使用调用脚本，而不是定制的 Shell 片段或一次性辅助脚本。这样可以确保路由解析、启动器选择、传输处理和输出捕获都沿用仓库支持的路径。

委派负载格式

路由器应传递简洁的分派提示词，并引用实际的递归工作流产物，而不是重复其中内容。典型的负载要素包括：

• 委派角色
• 当前阶段和产物路径
• 规范审查包路径或提示词包路径
• 需要阅读的确切上游文档，通常包括当前运行文档，例如 00-requirements.md、01-as-is.md、02-to-be-plan.md 或当前审计产物
• 由 recursive-subagent 或生成的审查包规定的确切输出约定

路由器的职责是将该工作包路由到选定的 CLI/模型并返回输出。路由器不应另行编造替代性的工作流规则。

用户提示

当路由角色尚未确定时，请提出简洁的角色相关问题，并注明：

• 已发现的 CLI ID
• 可用时列出版本字符串
• 可用时列出已发现的模型
• 尚未确定的角色
• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

示例提示：

I found these CLIs in this environment:
- codex (available, version 1.2.3)
- kimi (available, version 1.32.0)

Please choose a CLI and model for these roles in /.recursive/config/recursive-router.json.
For valid CLI ids and model ids, check /.recursive/config/recursive-router-discovered.json.

Unresolved roles:
- analyst
- code-reviewer

有效的简洁回答：

analyst=codex:gpt-5
code-reviewer=kimi:kimi-code/kimi-for-coding

用户回答后，优先使用 recursive-router-configure.py 或 .ps1，通过一个或多个 --set role=cli:model 绑定进行配置。配置命令必须先向选定模型发送实时提示，以验证每条拟议路由，然后才能写入 /.recursive/config/recursive-router.json。如果任何验证失败，都不要保存部分更改。如果用户直接编辑了策略文件，应重新读取该文件，而不是贸然覆盖这些手动修改。

从实时路由中总结的验证指南：

• 验证 codex 应使用 app-server 传输，而非通用 CLI 模板调用。
• 验证 kimi 应使用已配置的别名；即使已生成所需令牌，也可能仍返回非零退出码。将该令牌视为模型可访问性的证明，但要在操作记录中记录退出码。
• 验证 opencode 应使用 opencode models 返回的、带有确切提供商限定的模型 ID。
• 验证只能证明路由可访问，不能证明路由角色拥有完成实际任务所需的足够上下文。控制器仍须为实际派发整理所需文档和输出约定。

回退行为

路由决策可能解析为：

• external-cli
• local-only
• fallback-local
• blocked
• ask-user

回退必须明确且可审计。不要在不记录原因的情况下，悄然从路由委派切换到本地路径。

可审计性

使用或尝试路由委派时，阶段产物和操作记录应记录：

• Routing Mode
• Routed Role
• Routed CLI
• Routed Model
• Routing Config Path
• Routing Discovery Path
• Routing Resolution Basis
• 适用时记录 Routing Fallback Reason
• Controller Orchestrator
• Delegated Context Bundle

使用 .recursive/scripts/recursive-subagent-action.py 或 .ps1 捕获路由操作记录详情，例如：

• Router Used
• CLI Probe Summary
• Prompt Bundle Path
• Invocation Exit Code
• Output Capture Paths

将路由助手输出、原始 stdout/stderr 转录和调用元数据存储在运行证据树下，例如 /.recursive/run/<run-id>/evidence/router/。将初始提示包保存在按运行划分的提示包位置，例如 /.recursive/run/<run-id>/router-prompts/，并将其标为 Prompt Bundle Path。不要在可复用仓库中初始化顶层 /.recursive/router-prompts/。不要将原始转录直接存储在 /.recursive/run/<run-id>/subagents/ 下；subagents/ 中的每个 Markdown 文件都是规范的子 Agent 操作记录，必须符合操作记录架构。操作记录可以引用 evidence/router/ 中的转录和元数据文件。

如果路由提示对精确的章节划分或引用有要求，优先使用持久化提示包，其中包括：

• 角色和范围明确的任务
• 正在审查的产物路径
• 确切的上游文档或审查包路径
• 必要时内嵌的相关摘录，以适应指令遵循能力较弱的模型
• 确切的必需章节标题和首行规则
• 明确的拒绝条件

警告

• 如果配置不完整且策略要求 ask，不要臆造 CLI/模型绑定。
• 不要强制要求使用外部 CLI。
• 如果控制器可以使用 recursive-router-configure.py 或 .ps1，不要保存未经检查的绑定。
• 不要将路由器视为当前会话中主控制器的替代品。
• 不要使用 ~/.kimi/config.toml 中的原始 model = "..." 值配置 Kimi；应使用 kimi --model ... 接受的别名键。
• 不要假定 Codex 会足够早地拒绝所有无效模型，从而可用于发现。应以 app-server model/list 和发现清单为准。
• 不要接受未经控制器根据实际文件、实际差异和实际递归产物验证的路由外部输出。
• 不要接受任何 success: false 或 exit_code 非零的路由尝试；应修复并重试，或记录明确的回退方案。
• 不要将原始路由转录内容作为 Markdown 文件存储在 subagents/ 下；应将原始路由证据放在 evidence/router/ 下，并在 subagents/ 下生成规范的操作记录。
• 如果路由角色需要打包的上下文或精确的输出格式说明才能成功，不要仅通过简单的文件路径引用进行委派。