---
name: dispatch-agent-task
description: 把冻结角色任务包派发给 Agent 框架子代理执行并自动留痕：注入角色 prompt 与输出 Schema、按白名单开放工具、归一框架事件流写入代理事件账本，结构化输出经 Draft 2020-12 校验后返回回执。当前生产入口使用 Pi；DSH headless 仅有独立的无工具 fresh 对照适配器，尚未接入本 Skill 的生产派发。执行 writer/planner/detector/judge/extractor 角色任务时使用；不经框架的直接 HTTP 批处理走 execute-role-task；本 Skill 不做补证、重写等业务决策。
disable-model-invocation: true
---

# 派发 Agent 框架任务

本 Skill 只拥有「框架派发」接缝：角色执行交给 Agent 框架（pi/codex/opencode…）的原生 ReAct 循环、工具调用与子代理机制，项目不自造编排。任务包可移植（角色 + 冻结输入 + 输出 Schema + 工具白名单，不含框架字段）；框架适配器是全仓唯一直接调用框架二进制的位置（架构门禁白名单）。不经过框架、需要直接 HTTP 模型调用的无工具批处理走 `execute-role-task`，两者不共用执行路径。

## 入口

```
.venv/bin/python muse/lifecycle/dispatch/skills/dispatch-agent-task/scripts/dispatch_agent_task.py \
  --spec task.json --provider P --model M [--thinking low] \
  [--repo-root .] [--run-id ID] [--run-dir DIR] [--trigger-source user] \
  [--session-id ID --session-dir DIR] [--enable-read-tools]
```

| 模块 | 职责 |
|---|---|
| `muse/lifecycle/dispatch/skills/dispatch-agent-task/scripts/role_task.py` | Muse 侧任务包装配：spec、角色合同、业务 Schema 和模型策略前置校验。 |
| `muse/flow/dispatch.py` | 装配与编排：任务包、角色模型策略、证据账本、结构化输出校验；调用 runtime 执行。 |
| `runtime/agent_executor.py` | 多轮 Agent 调用；不加载 Muse 合同。 |
| `runtime/runs.py` | 不可变 run 目录读写；不加载 Muse 合同。 |
| `framework/primitives/execution.py` | 框架通用执行请求、事件和结果对象；不加载 Muse 合同。 |
| `framework/adapters/pi/runner.py` | Pi 框架适配器：只消费 `FrameworkExecutionRequest`，构造 argv、消费 JSON 事件流并执行超时保护；当前生产入口。 |
| `framework/adapters/dsh/` | DSH headless 对照适配器：只开放无工具 fresh 任务，读取 flush 后 session JSONL；未接入本 Skill 的生产派发。 |
| `muse/lifecycle/dispatch/skills/dispatch-agent-task/scripts/read_tools.py` | 探索工具 server 只读实现：五个登记工具（细纲/文风/范式绑定/章节正文/实体检索），只读连接、未知工具拒绝、结果有界；`--list` 输出登记表。 |
| `framework/adapters/pi/mcp_bridge.ts` | 工具 server 的框架扩展：装载时从 `read_tools.py --list` 动态注册工具，每次执行转给只读实现；不经派发器注入环境变量时不注册任何工具。 |
| `muse/lifecycle/dispatch/skills/dispatch-agent-task/scripts/dispatch_agent_task.py` | CLI 薄入口：解析参数后调用 `muse.flow.dispatch.run_dispatch`。 |

## 输入与输出

- 输入：`AgentTaskSpec` JSON（specVersion=agent-task-v1；role 限五个角色，角色合同来自 `muse/sot/角色合同.md`；outputSchema 必须是合法 Draft 2020-12；inputSha256 可选校验）。`provider`、`model`、`thinking` 属于执行策略，其中 `provider` 和 `model` 必须由调用方显式传入并如实记账。
- 输出：回执 JSON（runId、框架、请求/实际模型、逐回合用量与成本、哈希链、证据 ID）与退出码；结构化输出经 `muse_llm.extract_json` + 完整 Draft 2020-12 校验，失败关闭（退出码 4）。
- 事件协议（九类闭集，逐条追加 `example_agent_event`）：run.started / agent.started / model.completed / tool.started / tool.completed / agent.completed / agent.failed / run.completed / run.failed。
- 会话复用：`--session-id` + `--session-dir` 继续/创建指定框架会话（同一章补证/修改复用）；缺省为一次性会话。会话文件由框架写入指定目录，随运行目录同权限保护。
- 探索工具：`--enable-read-tools` 启用只读工具 server（扩展经 `-e` 显式加载，自动发现仍被 `--no-extensions` 禁用）；任务包含登记表工具名但未启用时失败关闭（READ_TOOLS_NOT_ENABLED）。工具调用参数进事件账本，成功后产 `dependencies.json`（依赖清单：本次运行实际读了什么），回执含 `dependencies` 摘要。
- 退出码：0 成功；2 spec 非法；3 框架失败（超时/非零退出/流不可解析/无模型回合）；4 输出不合 Schema；5 证据落库失败。

## 红线

- 适配器不含业务决策：补证、重写、下一步做什么属于框架里的模型与主代理，不属于本 Skill。
- 框架二进制只能由 `framework/adapters/` 下的宿主适配器调用；当前 `dispatch-agent-task` 生产路径只调用 `framework/adapters/pi/runner.py`。角色合同、fixed-opus 和额度策略由 Muse 派发层解析，不进入框架。
- 不读取本机模型客户端配置文件；框架凭据走框架自身环境变量，本 Skill 不经手。
- 角色文件只提供身份提示；中央角色合同是稳定边界唯一事实源。系统提示词由适配器按固定顺序装配，不裁剪角色合同；工具白名单外的能力不开放（空名单 = `--no-tools`）。
- 工具 server 只提供登记过的只读工具：不提供裸查询、不写库；登记表（`read_tools.py` TOOL_REGISTRY）是唯一事实源，扩展不自带工具清单。
- 失败一律关闭：框架异常、Schema 不符、证据落库失败都终止运行并记 run.failed，不部分成功。

## 数据边界

- `example_agent_event`（DDL-113，append-only）：归一事件账本，只存身份、用量、成本与安全摘要。
- `example_llm_call`：每个模型回合一条投影（无额度窗时 `window_key=NULL`，以 `run_id` 归属本次派发，raw 指针指向全量转录）。
- raw 表：system prompt（prompt）、最终输出（response）、框架全量转录（supplier）经 `record-run-evidence/agent_trace.persist_agent_evidence` 单事务原子落库，写前密钥拦截。
- `example_run`：start_run/finish_run 登记终态；运行目录（/tmp/muse-agent-runs/<run_id>）保留 task-spec、system-prompt、user-message、transcript、output、dependencies（如有）、receipt 审计件。
- 留痕是旁路义务：派发路径不提供「不留痕」选项，业务调用方不能决定是否记录。

## 复利合同

- **模式 C（平台底座）**：`lifecycle=platform`，D8 不适用；不登记创作经验 `example_lesson`。框架派发的效果信号由业务 Skill 在消费回执时归因。