| name | agent-dispatch |
| description | 子代理调度 — 将Agent激活指令翻译为运行时具体操作。当 orchestrator 将某 phase agent 激活为 subagent_type 子代理、需要派发任务并解析返回值时由本 skill 翻译执行。 |
| argument-hint | <agent_id: 目录名如architect> <task: 任务描述> |
| suggested-tools | file_read, file_glob, file_grep, shell_exec, agent_dispatch |
| depends | [] |
| disable-model-invocation | false |
| user-invocable | false |
子代理调度 (agent-dispatch)
能力边界
- 能做: 将"激活Agent X执行任务Y"指令翻译为当前运行时环境的具体操作
- 不做: 决定激活哪个Agent(由orchestrator决定)、决定任务内容(由上游Agent决定)
调度输入
调用方(orchestrator)提供:
- agent_id: 目标Agent目录名 (如 "architect", "reviewer")
- task: 任务描述
- task_type: new_creation | revision | continuation | amendment（恢复协议见 SUB-AGENT-PROTOCOLS）
- input_docs: 输入文档路径列表
- expected_output: 期望产出类型
- 仅revision: REVIEW报告路径
- 仅continuation: 用户回答、中间产出路径、恢复指引
- 仅amendment: change-analysis 结果(XML格式)、用户变更描述
reflector 家族任务（retrospective / skill-improvement / apply-learnings）经 orchestrator inline 或 CLI cataforge agent run --task-type 触发，不走本调度枚举。
Agent-Skill 依赖映射
单一事实来源: 各 AGENT.md 的 skills: 字段（由 subagent_type 自动加载）。
本文件不维护映射副本。查询当前映射请运行:
cataforge agent list --skills
平台调度实现
当前运行时平台由 .cataforge/platforms/{platform_id}/profile.yaml 声明。
调度工具名和参数由 profile.yaml 的 dispatch 段定义。
prompt 主模板: .cataforge/skills/agent-dispatch/templates/dispatch-prompt.md。
平台特异性覆盖: .cataforge/platforms/{platform_id}/overrides/dispatch-prompt.md（若存在）。
调度前 orchestrator 自行 Read 主模板 + 当前平台 override（若有），两者由 LLM 上下文合并使用 —— OVERRIDE 块边界在源文件中以 <!-- OVERRIDE:<section> --> 注释标识，便于 LLM 识别替换语义。主模板已含平台分支（如 "Claude: .claude/rules，Cursor: .cursor/rules"），override 只在需要补充平台特异性内容时才填充对应块。
deploy 阶段无运行时合并器；frontmatter 能力标识符翻译由 cataforge.runtime.agent.translator.translate_agent_md 负责，agent 返回值解析由 orchestrator 主循环按下方 §返回值解析与容错 处理。
修改 prompt 模板影响所有通过 agent-dispatch 调度的 Agent，请谨慎变更并做 diff review。
TDD 子代理由 tdd-engine 直接调度，仅传入任务信息，通用约束和返回格式依赖 AGENT.md 自动加载，无需同步。
返回值解析与容错
orchestrator 收到子代理返回后，按以下优先级解析:
- 正常解析: 提取
<agent-result> 标签内容，获取 status/outputs/summary
- 标签缺失兜底: 如果返回文本中不含
<agent-result>:
- 使用
Glob docs/{doc_type}/ 检查是否有新文件产出
- 有新文件 → 推断为 completed，outputs 为新文件路径列表
- 无新文件 → 标记为 blocked，记录原因"子代理未返回结构化结果"
- 标签不完整兜底: 如果
<agent-result> 缺少必填字段(status/outputs):
- 缺 status → 默认为 completed (如果有 outputs)
- 缺 outputs → 使用 Glob 扫描 docs/ 推断产出
- maxTurns 截断恢复: 如果子代理明显被截断(返回文本不含结束标签):
- 通过
git status docs/ 检查是否有自本次调度后新增或修改的文件（untracked 或 modified）
- 有新增/修改文件 → 检查文件内容是否含非空章节（至少一个 ## 标题下有实际内容），有则以 continuation 模式重新调度同一Agent
- 无新增/修改文件或文件仅含空骨架 → 标记 blocked 并请求人工介入
实现: orchestrator 主循环按上述优先级处理子代理返回，无独立 runtime 模块。
写入范围校验
子代理返回后，orchestrator 通过 git diff --name-only 检查本次调度期间修改的文件:
- 读取目标 Agent 的 AGENT.md frontmatter 中
allowed_paths 字段
allowed_paths 为空数组 [] 时跳过校验（orchestrator 等无限制 Agent）- 框架管理副产物不计入越界，禁止回滚：
docs/EVENT-LOG.jsonl、docs/.doc-index.json、.cataforge/**（context / event CLI 在任何角色调度期间都可能自动刷新，回滚即审计与索引数据破坏）
- 所有修改文件均在 allowed_paths 列表的目录下 → 正常
- 存在 allowed_paths 以外的修改文件 → 使用
git checkout -- {违规文件} 回滚，在 summary 中标注"Agent 写入违规已回滚"，记录违规文件路径
注意事项
execution_host: subagent 的 Phase Agent 作为独立子代理运行，拥有自己的上下文窗口（inline phase 由 orchestrator 主线程承载，不经本 skill，见 ORCHESTRATOR-PROTOCOLS.md §Inline Role Execution Protocol）- 子代理无法直接访问调用方的上下文，所有必要信息通过prompt传入
- 子代理无法使用调度工具 — TDD子代理由orchestrator直接通过tdd-engine skill启动
- subagent_type 使子代理自动加载 AGENT.md 中的角色定义、工具权限和约束
- 续接（continuation）一律 file-based 重派发：独立上下文窗口 + 从中间产出文件 reload，禁止依赖任何平台「带上下文续接已派发子代理」的原生原语
模型选型
框架 13 agent 的 model tier 由各自 AGENT.md model_tier 固定、deploy 解析为原生 model:，调度时无需干预。派发无 frontmatter tier 的通用子代理（general-purpose / Explore / Plan 等）时，调用方必须显式指定 model —— 判据见 子代理模型选型判据：默认 sonnet，仅重推理判据用 opus，禁 haiku；省略即继承会话模型（常为 opus）造成静默过度使用。
派发类事件（agent_dispatch / tdd_phase / review_verdict）记录时附 --model <tier|id>：派发子代理填其 model_tier（standard / heavy）或原生 id，主线程内联档填 inline，供 reflector 成本复盘（EVENT-LOG schema 字段 model）。
Anti-Patterns
- 禁止: 接受 light-inline / prototype-inline 档的调度请求 — 档位由 tdd-engine 判定，内联档前提是主线程直接执行，收到此类调度请求本身即上游错误，调度会撕裂上下文
- 禁止: 跳过 §写入范围校验 的 allowed_paths 检查 —
git diff 检测的违规由本 skill 兜底，跳过会让 phase-bound agent 写入越权而无回滚
- 禁止: 把任务上下文拆成多次 dispatch 增量传递 — 子代理无持久上下文，每次 dispatch 都是独立窗口；必须一次 prompt 内联全量信息，否则触发"上下文丢失型 blocked"
- 避免: 在主线程读取子代理返回的全文再二次摘要 — 主线程上下文消耗翻倍，应让子代理在
<agent-result>.summary 内自摘要，主线程仅解析结构化字段
效率策略
- 调度层薄而透明: 仅负责翻译，不增加额外逻辑
- subagent_type 自动加载 AGENT.md，节省子代理文件读取 turn
- prompt 模板外置于 templates/dispatch-prompt.md，便于独立 diff/review
- 状态通过文件系统传递，避免上下文膨胀
