# Agent Dispatch

> 子代理调度 — 将Agent激活指令翻译为运行时具体操作。当 orchestrator 将某 phase agent 激活为 subagent_type 子代理、需要派发任务并解析返回值时由本 skill 翻译执行。

- Skill: `lync-cyber/agent-dispatch` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lync-cyber/agent-dispatch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lync-cyber/agent-dispatch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: lync-cyber (https://skillmd.com/u/lync-cyber)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lync-cyber/agent-dispatch

---


# 子代理调度 (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 收到子代理返回后，按以下优先级解析:

1. **正常解析**: 提取 `<agent-result>` 标签内容，获取 status/outputs/summary
2. **标签缺失兜底**: 如果返回文本中不含 `<agent-result>`:
   - 使用 `Glob docs/{doc_type}/` 检查是否有新文件产出
   - 有新文件 → 推断为 completed，outputs 为新文件路径列表
   - 无新文件 → 标记为 blocked，记录原因"子代理未返回结构化结果"
3. **标签不完整兜底**: 如果 `<agent-result>` 缺少必填字段(status/outputs):
   - 缺 status → 默认为 completed (如果有 outputs)
   - 缺 outputs → 使用 Glob 扫描 docs/ 推断产出
4. **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` —— 判据见 [子代理模型选型判据](../../references/subagent-model-policy.md)：默认 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
- 状态通过文件系统传递，避免上下文膨胀