# Tool 合约

## 1. 定位

LLM 通过 **tool call** 表达意图；Runtime 校验后执行 tool 或转为 **RuntimeEvent** 改变 phase。

**真 tool loop**：循环 tool 的返回值 append 到 agent `messages[]`；边界 tool 结束 burst。  
不依赖「副作用列表」隐式推进（迁移方向，见 `architecture.md`）。

黑板与上下文：`tag-blackboard.md`、`context-assembly.md`。

---

## 2. 调用者

| 调用者 | 可用 tool | 禁止 |
|--------|-----------|------|
| 总管 Agent | 见 §3 | 改 phase 直接写黑板；传 inputTags；accept 产物 |
| Worker LLM | `ask_user`、`submit`（目标态） | 调度其他 skill；写未声明 tag |
| 用户 / CLI | submit_input、approve、reject、accept | — |
| Runtime | 发射 event、拼接上下文、执行 worker | — |

---

## 3. 总管 Tool

### 3.1 循环 tool（burst 内，不改 phase）

| name | 作用 |
|------|------|
| `read_blackboard` | `tags: string[]` 读正文 |
| `list_workers` | 当前包可调度 skill 列表 |
| `list_artifacts` | 产物状态 |

### 3.2 边界 tool（结束 burst）

| name | 行为 |
|------|------|
| `run_worker` | 执行 skill；`requiresApproval` → `approve_step` |
| `ask_user` | `waiting_user(input)` |
| `review_blackboard` | 向用户展示概况 → `input` |
| `finish` | `done` |

```ts
type RunWorkerParams = {
  workerId: string;
  reason: string;
  requiresApproval: boolean;
  roleId?: string;
};
```

Runtime 从 Worker Skill 读 `inputTags` / `outputTags`，总管 **不得传入**。

### 3.3 Tool loop burst

```text
计数器 toolLoopBurstCount 在每次用户硬事件时归零：
  user_submitted_input、user_confirmed_intake、user_approved_next_step、
  user_rejected_next_step、user_accepted_artifact、user_rejected_artifact、…

running 内每轮 LLM+tool 使 burst+1；超过 maxBurst（默认 12，可配置）→ 强制 waiting_user
```

**maxBurst = 两次用户操作之间的上限**，非 Session 累计。

代码：`src/main-agent/tool-loop.ts`、`src/runtime/tool-registry.ts`。

---

## 4. Worker Tool（目标态）

| name | 行为 |
|------|------|
| `ask_user` | `worker_questions` + resumeContext |
| `submit` | 校验 tag ⊆ outputTags → 写黑板 → `worker_completed` |

Phase A 仍用 JSON `outputs` + `askUser`，语义等价。

---

## 5. 用户硬事件

| waitingReason | 用户动作 |
|---------------|----------|
| `skill_selection` | 选包 |
| `intake` / `input` | 输入 |
| `approve_step` | approve / reject |
| `review_artifact` | accept / reject |
| `worker_questions` | 输入 |
| `revision` | 输入修改说明 |

---

## 6. 校验

```text
1. phase + waitingReason 允许该 actor
2. tool 参数 schema
3. workerId ∈ manifest 注册表
4. submit tag ⊆ outputTags
5. 总管不得带 inputTags
6. burst ≤ maxBurst
```

---

## 7. 代码对应

| 章节 | 文件 |
|------|------|
| 总管 tool loop | `src/main-agent/tool-loop.ts` |
| tool 定义 | `src/main-agent/tools.ts` |
| 解析/校验 | `src/runtime/tool-registry.ts` |
| worker | `src/worker/executor.ts` |
| 阶段机 | `src/runtime/phase-machine.ts` |

---

## 8. 已废弃

- 总管 JSON 一次性决策（保留 fallback 解析）
- `inputKeys` / `outputKeys`
- orchestrator 思维链逐步调度
- 以 `PhaseEffect.invoke_main_agent` 链为主的路径（迁向 burst 入口）