Initial commit

docs/tool-contracts.md

@@ -0,0 +1,125 @@
+# 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 入口）