Skill: lanyasheng/eh-multi-agent (version 2.4.0)

--- name: multi-agent version: 2.0.0 category: knowledge description: 多 agent 协调设计模式。当需要选择 coordinator/fork/swarm 模式或设计跨 agent 协作时使用。不适用于工具重试（用 tool-governance）或上下文管理（用 context-memory）。参见 execution-loop（coordinator 持续执行）。 license: MIT triggers: - multi agent - 多 agent - coordinator - fork vs swarm - agent coordination - workspace isolation - file conflict author: OpenClaw Team --- # Multi-Agent Coordination 多 agent 系统设计模式：委托模式选型、任务协调、并发控制、质量保障。纯设计指南。 ## When to Use - 选择 Coordinator/Fork/Swarm → Three delegation modes - 多 agent 同时编辑同一文件 → File claim and lock - 需要隔离工作空间 → Agent workspace isolation - 协调者需要综合 worker 结果 → Synthesis gate ## When NOT to Use - 只有 1 个 agent → 用 `execution-loop` - 跨阶段知识传递 → 用 `context-memory` --- ## Patterns ### 4.1 Three Delegation Modes 三种模式各有适用场景： | 模式 | 特点 | 适用 | |------|------|------| | **Coordinator** | Worker 从零开始，4 阶段（Research→Synthesis→Implementation→Verification） | 多阶段复杂任务 | | **Fork** | Child 继承 parent 完整上下文和 prompt cache（首次调用只付 cache read 价格 $0.003/1K vs 全量 $0.036/1K），单层限制 | 需要 parent context 的子任务 | | **Swarm** | 扁平名单，file-based mailbox，不能递归 spawn | 长期独立的同质工作流 | 不确定选哪个→ Coordinator，覆盖最广。Fork 限制：child 不能再 Fork、不能 clarify、不能 memory writes。 → [详见](references/delegation-modes.md) ### 4.2 Shared Task List Protocol 共享任务板 `.coordination/tasks.json`： ```json { "tasks": [ {"id": "t1", "description": "重构 auth 模块", "status": "pending", "claimed_by": null, "result": null} ], "updated_at": "2025-03-15T10:00:00Z" } ``` 四状态：`pending → claimed → done/failed`。领取任务通过原子锁 `mkdir ".coordination/tasks.lock"`（POSIX 上 mkdir 是原子操作），10 次重试，指数退避 50-500ms，释放用 `rmdir`。 Claude Code Swarm 使用 per-agent inbox `~/.claude/teams/{team}/inboxes/{agent}.json` 替代共享 tasks.json，减少锁竞争。 → [详见](references/task-coordination.md) ### 4.3 File Claim and Lock 编辑文件前写排他锁： ```json // .claims/src_handlers_ts.lock（路径中 / 替换为 _） {"session_id": "abc123", "file": "src/handlers.ts", "claimed_at": 1710489600, "expires_at": 1710490200} ``` - **10 分钟 TTL**（`expires_at = now + 600`），防 crash 死锁 - PreToolUse hook 拦截 Write/Edit，读 `tool_input.file_path`，检查 lock 是否被其他 session 持有且未过期 - 过期 lock 清理：`find .claims -name "*.lock" -mmin +15 -delete` 粒度是整个文件。需更细粒度→用 workspace isolation。 → [详见](references/file-claim-lock.md) ### 4.4 Agent Workspace Isolation 每个 worker 独立 git worktree： ```bash git worktree add .worktrees/${WORKER_ID} -b work/${WORKER_ID} HEAD claude -p --cwd .worktrees/${WORKER_ID} "..." ``` 共享 .git 仓库但独立工作目录和 index，彻底消除并发冲突。代价是 merge 阶段冲突集中爆发。三种 merge 策略：`git merge --no-ff`（保留历史）、`cherry-pick`（只取最终结果）、`git diff main...branch > patch`（最安全，人工 review）。清理：`git worktree remove` + `git branch -d`。 → [详见](references/workspace-isolation.md) ### 4.5 Synthesis Gate Research → Implementation 之间的强制关卡。**核心原则：coordinator must synthesize, not delegate understanding**。 Gate 脚本检查 `.coordination/synthesis.md`： 1. 文件存在且非空 2. 最少 10 行 3. 必含匹配 `Conclusion`、`Action Plan|Implementation Plan`、`Evidence|Rationale` 的 section 通过后 implementation worker 启动：`claude -p --max-turns 50 "$(cat .coordination/synthesis.md)"`。 把原始 research 结果直接转发给 implementation worker 是反模式。 → [详见](references/synthesis-gate.md) ### 4.6 Review-Execution Separation Implementation 和 review 由两个隔离 session 的 agent 分别执行，盲审消除确认偏误。 - Implementation agent：`claude -p --max-turns 60` - Review agent：`claude -p --max-turns 20`，只接收 `git diff main` 和任务描述，**不知道 implementation agent 的推理过程** - Review 输出：`.coordination/review-result.json` 含 `{approved: bool, issues: [...], suggestions: [...]}` - `approved == false` → issues 喂给一个**新** implementation session（不是原来那个），避免锚定 → [详见](references/review-execution-separation.md) ### E4.x Extended Patterns Cache-safe forking、完整 context 隔离、file-based mailbox（per-agent inbox JSON + lockfile）、permission delegation、结构化消息协议。 → [详见](references/extended-patterns.md) ## Workflow 选模式用决策树，选完后按对应路径执行。 ``` 需要多 agent？ ├── Worker 需要 parent 已加载的 context？ │ └── 是 → Fork │ · child 继承完整上下文 + prompt cache，首次调用只付 cache read 价格 │ · 单层限制：child 不能再 Fork │ · 任务和 parent context 无关时别用 Fork，浪费 context 装无关内容 │ ├── Workers 之间需要分阶段协调？ │ └── 是 → Coordinator（4 阶段） │ 1. Research — 多 worker 并行探索 │ 2. Synthesis — coordinator 独占，综合所有结果产出 synthesis.md │ （不可委派，不可跳过——直接转发原始结果会让下游无所适从） │ 3. Implementation — 按文件集分配，同文件串行防 merge conflict │ 4. Verification — 独立 review agent 盲审，不看 implementation 推理 │ └── 各自独立、同质任务？ └── 是 → Swarm · 扁平名单：teammate 不能 spawn 新 teammate · 通过 file-based mailbox 通信（per-agent inbox JSON + lockfile） · 用 .coordination/tasks.json 共享任务状态 ``` 所有模式通用：每个 worker 分配独立 worktree（Pattern 4.4），编辑文件前写 claim lock（Pattern 4.3）。 <example> 场景: 15 个文件的跨模块重构（统一错误处理）— Coordinator 模式 Phase 1 — 研究: 3 个 worker 各自 worktree（`git worktree add .worktrees/r1 -b work/r1 HEAD`），并行扫描输出影响分析 Phase 2 — 综合: coordinator 独自消化 3 份报告，写 `.coordination/synthesis.md`（迁移方案 + 文件优先级 + 依赖顺序），gate 脚本验证含 Conclusion + Action Plan + Evidence Phase 3 — 实现: 2 个 worker 按 synthesis 认领文件，编辑前写 `.claims/src_auth_ts.lock`（TTL 10min），防止并发编辑同一文件 Phase 4 — 审查: 1 个 review worker 只拿到 `git diff main` + 任务描述做盲审，输出 `.coordination/review-result.json` 结果: 15 文件迁移完成，0 冲突，审查一次通过 </example> <example> 场景: 10 个 API endpoint 的测试补全 — Swarm 模式 任务同质（每个 endpoint 独立写测试），无需跨阶段协调。 `.coordination/tasks.json` 列出 10 个 pending 任务。5 个 worker 各自领取：`mkdir .coordination/tasks.lock`（原子），读 tasks.json 找 pending 项，改为 claimed，`rmdir .coordination/tasks.lock`。 每个 worker 在独立 worktree 工作，写完测试后标记 done。Coordinator 最后 merge 所有 worktree。 </example> <anti-example> 错误: coordinator 收到 3 份 research 报告后直接说 "Based on your findings, fix it" 转发给 implementation worker 后果: 3 份报告有矛盾结论（Result 类型 vs exception），implementation worker 自己做了不一致的选择 违反: Pattern 4.5 — coordinator 跳过 synthesis，把判断责任下推给 worker </anti-example> <anti-example> 错误: 用 Fork 模式做需要递归委托的任务 parent Fork 出 child-A，child-A 想再 Fork child-B — 失败，Fork 只支持单层。 需要递归委托或多阶段协调 → 用 Coordinator。Fork 只适合 child 需要 parent context 的单层子任务。 </anti-example> ## Output | 产物 | 路径 | 说明 | |------|------|------| | 任务清单 | `.coordination/tasks.json` | 所有 worker 的任务分配、状态、认领记录 | | 综合文档 | `.coordination/synthesis.md` | coordinator 综合 worker 结果的结构化决策文档 | | 文件锁 | `.claims/*.lock` | 每个 worker 编辑文件前写入的排他锁，防止并发冲突 | ## Related - `execution-loop` — Ralph 持续执行循环，用于 coordinator 的长时间持续执行 - `context-memory` — handoff 文档，用于跨阶段（研究→综合→实现）的知识传递 - `tool-governance` — component-scoped hooks，用于给不同 worker 配置不同的工具权限

path: metadata.json
content: name: multi-agent
version: 2.0.0
description: Multi-agent coordination design patterns
license: MIT

path: references/delegation-modes.md
content: # Pattern 4.1: 三种委托模式选型（Coordinator / Fork / Swarm）

## 问题

需要多个 agent 并行工作，但不同任务适合不同的协调方式。选错模式会导致 context 爆炸（Fork 用在大任务上）、协调混乱（Swarm 没有领导者）、或效率低下（Coordinator 用在简单并行上）。

来源：Claude Code 内部 + 开源 skill 蒸馏实践 + Anthropic "Building multi-agent systems"

## 三种模式

| 模式 | Context 共享 | 适用场景 | 约束 |
|------|-------------|---------|------|
| **Coordinator** | 无——worker 从零开始 | 复杂多阶段任务（research → synthesize → implement → verify） | 最慢但最安全 |
| **Fork** | 完整——child 继承 parent 上下文 | 快速并行分支，共享已加载的上下文 | **单层限制**——Fork 的 child 不能再 Fork |
| **Swarm** | 点对点——通过共享 task list | 长期独立工作流 | **扁平名单**——teammate 不能 spawn 新 teammate |

## 黄金法则

> Coordinator must synthesize, not delegate understanding — "Based on your findings, fix it" is an anti-pattern.

Coordinator 收到 worker 的结果后，MUST 自己理解并综合，而不是把原始结果直接传给下一个 worker。这是来自 Anthropic 博客的核心原则。

## 选型决策树

```
需要多 agent？
├── worker 需要 parent 的 context 吗？
│   ├── 是 → Fork（但注意单层限制）
│   └── 否 → worker 之间需要协调吗？
│       ├── 是，需要分阶段 → Coordinator
│       └── 否，各自独立 → Swarm
```

## Fork 的单层限制与 Cache 继承

**为什么限制单层**：Fork child 继承完整的 parent context。递归 Fork 的 context 成本指数增长。Claude Code 内部的实现中，Fork tool 在 child agent 的 tool pool 中仍然可见（为了 cache sharing），但在 call time 被 guard 阻止。

**Prompt cache 继承**：Fork subagent（`isForkSubagentEnabled()` 开启）不仅继承 parent 的对话历史，还共享 parent 的 prompt cache。这意味着 Fork 的第一次 API 调用只需付 cache read 的价格（$0.003/1K tokens），而不是 full input 的价格（$0.036/1K tokens）。

Fresh worker（非 Fork）从空 context 开始，没有 cache 可共享。

**选 Fork 还是 Fresh 的关键依据**：
- Worker 需要 parent 已经加载的文件和讨论 → Fork（省 token，启动快）
- Worker 的任务和 parent 的 context 无关 → Fresh（不浪费 context 装无关内容）
- Worker 需要写 memory 或做危险操作 → Fresh（Fork child 的工具集受限：no recursive delegation, no clarify, no memory writes）

## Swarm 的扁平名单

**为什么**：teammate 不能创建新 teammate，防止不可控增长。roster 保持扁平。所有 teammate 通过 file-based mailbox 通信（JSON 文件 + lockfile 序列化，10 次重试，5-100ms 指数退避）。

## Coordinator 的四阶段工作流

1. **Research**（并行）：多个 worker 各自探索不同区域
2. **Synthesis**（coordinator 独占，绝不委派）：综合所有 research 结果
3. **Implementation**（按文件集序列化）：写并行、但同一文件串行，防止 merge conflict
4. **Verification**（并行）：多个 worker 各自验证不同方面

## 与现有 Pattern 的关系

- Pattern 3.1 (Handoff) 是 Coordinator 模式的核心机制——阶段间通过 handoff 文档传递上下文
- Pattern 2.5 (Component-Scoped Hooks) 可以给不同 worker 配不同的验证门禁
- Pattern 1.1 (Ralph) 可以用在 Coordinator 上确保整个流程不会半途而废

## Review-Execution 分离实践

本项目蒸馏过程中使用了 Review-Execution 分离模式：
- **Codex (GPT 5.4 xhigh)** 做 review——以全新视角对照源码审查
- **Claude Code (Opus 4.6 max)** 做 execution——带着对先前决策的完整理解
- 两个 agent 互不可见对方的 session
- 每轮 review-action 都在新 session 中执行（fresh token budget）
- 通过 handoff 文件协调（不依赖 session 内的上下文）

这本质上是 Coordinator 模式的变体：人作为 coordinator，两个 agent 作为 specialized worker。


path: references/extended-patterns.md
content: # Multi-Agent — Extended Patterns

### E4.1: Cache-Safe Forking
**What it does**: Fork 模式下 child agent 继承 parent 的完整 prompt prefix（系统指令 + 对话历史到 fork 点）。这让 child 的首次 API 调用命中 parent 的 prompt cache，避免为共享前缀重复计算。
**Why it matters**: Fork 的价值在于"不用重新加载 context"。如果 fork 后 child 的 API 调用无法利用 parent 的 cache，fork 退化成一个带有初始上下文的 Coordinator——有额外的 context 开销但没有 cache 收益。Cache-safe forking 让 fork 的延迟和成本优势真正生效。
**Source evidence**: Claude Code Fork 工具的实现。Anthropic prompt caching 的 prefix matching 机制。OMC 的 cache-sharing 策略。

### E4.2: Complete Context Isolation
**What it does**: Coordinator 模式下 worker agent 从零 context 开始——不继承 coordinator 的对话历史。Worker 只看到 coordinator 显式传入的任务描述。Worker 的工具结果也不会回流到 coordinator 的 context（coordinator 只看 worker 的最终输出）。
**Why it matters**: 共享 context 看似高效，实际有两个隐患：(1) coordinator 的探索性对话（多次尝试、回退）会误导 worker；(2) worker 的大量工具输出会污染 coordinator 的 context。完全隔离让每个 agent 在干净的环境中工作，通过结构化 handoff 传递必要信息。
**Source evidence**: Claude Code Coordinator 模式的 worker 隔离设计。Anthropic multi-agent 最佳实践。

### E4.3: 4-Phase Workflow
**What it does**: 将复杂任务分为 4 个固定阶段执行：(1) Research——多 worker 并行探索，收集信息；(2) Synthesis——coordinator 独占，综合 research 结果（不可委派）；(3) Implementation——按文件集分配 worker，同文件串行、跨文件并行；(4) Verification——多 worker 并行验证不同方面。
**Why it matters**: 没有固定 workflow 的 coordinator 会"边 research 边 implement"——在信息不完整时就开始写代码，发现不对再推倒重来。4 阶段强制先全面了解再动手，synthesis gate（单独的 pattern）确保 coordinator 真的理解了 research 结果。Implementation 阶段的"同文件串行"防止 merge conflict。
**Source evidence**: Claude Code Coordinator 模式的推荐工作流。Anthropic multi-agent 博客。OMC 的多阶段任务执行流程。

### E4.4: File-Based Mailbox
**What it does**: Swarm 模式下 teammate 之间通过 JSON 文件通信——每个 teammate 有独立的收件箱目录（`.coordination/mailbox/<teammate-id>/`），消息写入 JSON 文件。并发写入通过 lockfile + 指数退避（10 次重试，5-100ms 间隔）序列化。
**Why it matters**: Agent 运行在不同进程（tmux pane / headless session），无法使用内存中的消息传递。文件系统是唯一的可靠共享通道。Lockfile 防止并发写入损坏 JSON，指数退避防止锁竞争下的 CPU 空转。消息持久化还允许 crash 恢复——重启后读取 mailbox 即可了解错过的消息。
**Source evidence**: OMC Swarm 的 file-based communication 机制（10 次重试，5-100ms 指数退避）。经典的 mailbox 并发模式。

### E4.5: Permission Delegation
**What it does**: Worker agent 不直接处理权限请求——当 worker 遇到需要人类确认的操作（destructive bash 命令、MCP 权限等），将权限请求上报给 coordinator/leader，由 leader 决策或转发给人类。Worker 的 `allowedTools` 被限制为安全子集。
**Why it matters**: Worker 运行在 headless 模式，没有交互能力来请求人类确认。如果 worker 有完整权限，一个失控的 worker 可以做任何事。Permission delegation 确保破坏性操作经过有权限决策能力的 agent（coordinator）或人类审批。
**Source evidence**: Claude Code 的 `--allowedTools` 参数。Coordinator 模式下 worker 权限配置最佳实践。

### E4.6: Structured Message Protocol
**What it does**: Agent 之间的通信使用结构化消息类型而非自由文本。定义的消息类型包括：`shutdown`（请求 teammate 停止）、`plan_approval`（请求确认执行计划）、`permission`（权限请求上报）、`status_update`（进度通报）、`task_result`（任务结果提交）。每种类型有固定的 JSON schema。
**Why it matters**: 自由文本通信依赖 agent 正确解读对方的意图——"我觉得可以开始了"是同意还是建议？结构化消息消除歧义，让接收方可以用确定性逻辑（jq/代码）处理消息而非依赖 LLM 理解。特别是 `shutdown` 消息——必须被可靠识别和执行，不能被 agent 的"我还没做完"推理覆盖。
**Source evidence**: OMC Swarm 的消息协议。Claude Code 内部的 agent 间通信 schema。


path: references/file-claim-lock.md
content: # File Claim Lock

## Problem

多个 agent 同时编辑同一文件会产生冲突——agent A 读取文件，agent B 修改并保存，agent A 基于过期内容覆写。Git merge conflict 在 agent 场景下更难解决，因为 agent 不擅长处理 conflict marker。

## Solution

编辑文件前在 `.claims/` 目录创建 lock 文件，宣告对该文件的独占编辑权。其他 agent 的 PreToolUse hook 检测到 lock 存在时拒绝编辑操作。Lock 文件包含持有者信息和超时时间，防止 crash 后的死锁。

## Implementation

1. PreToolUse hook 在 Write/Edit 工具调用前检查 lock

```bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
echo "$TOOL" | grep -qE '^(Write|Edit)$' || exit 0

FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')
[ -z "$FILE" ] && exit 0

# 生成 claim 文件名（路径中的 / 替换为 _）
CLAIM_NAME=$(echo "$FILE" | sed 's|/|_|g')
CLAIM_FILE=".claims/${CLAIM_NAME}.lock"

if [ -f "$CLAIM_FILE" ]; then
  OWNER=$(jq -r '.session_id' "$CLAIM_FILE")
  EXPIRES=$(jq -r '.expires_at' "$CLAIM_FILE")
  NOW=$(date +%s)
  
  # 检查是否过期（默认 10 分钟）
  if [ "$NOW" -lt "$EXPIRES" ] && [ "$OWNER" != "$SESSION_ID" ]; then
    echo "{\"decision\":\"deny\",\"reason\":\"文件 ${FILE} 已被 session ${OWNER} 锁定，请等待释放或处理其他任务。\"}"
    exit 0
  fi
fi

# 创建或更新 claim
mkdir -p .claims
EXPIRES_AT=$(( $(date +%s) + 600 ))  # 10 分钟过期
jq -n --arg sid "$SESSION_ID" --arg file "$FILE" --argjson exp "$EXPIRES_AT" \
  '{session_id: $sid, file: $file, claimed_at: now | todate, expires_at: $exp}' \
  > "$CLAIM_FILE"
```

2. 编辑完成后释放 lock（PostToolUse hook 或 agent 手动删除）

```bash
rm -f "$CLAIM_FILE"
```

3. 定期清理过期 lock（cron 或 daemon）

```bash
find .claims -name "*.lock" -mmin +15 -delete
```

## Tradeoffs

- **Pro**: 防止并发编辑冲突，简单有效
- **Pro**: 超时机制防止 crash 导致的永久死锁
- **Con**: 粒度是整个文件——两个 agent 改同一文件的不同部分也会冲突
- **Con**: Agent 可能长时间持有 lock（在做复杂修改时），阻塞其他 agent

## Source

OMC Swarm 的文件锁定机制。经典的 advisory file locking 模式，适配到 agent 场景。


path: references/review-execution-separation.md
content: # Review-Execution Separation

## Problem

同一个 agent 既写代码又 review 自己的代码，会有确认偏误——agent 倾向于认为自己写的代码是对的。特别是在长 session 中，agent 对自己前几轮的决策有"沉没成本"心理，不愿推翻。

## Solution

用两个独立 agent 分别负责 implementation 和 review。两者运行在完全隔离的 session 中——review agent 看到的是代码本身，不知道 implementation agent 的推理过程。这种"盲审"迫使 review agent 从第一性原理判断代码质量。

## Implementation

1. **Implementation agent**：带完整任务上下文，执行编码

```bash
claude -p --max-turns 60 \
  "$(cat task-description.md)" \
  > .coordination/impl-output.md
```

2. **Review agent**：只看代码和需求，不看 implementation agent 的推理

```bash
# 收集变更的 diff
git diff main > .coordination/changes.diff

# Review agent 独立 session
claude -p --max-turns 20 \
  "$(cat <<PROMPT
审查以下代码变更。对照原始需求检查：
1. 功能是否正确实现
2. 是否有遗漏的边界情况
3. 是否引入了 regression

需求：$(cat task-description.md)

变更：$(cat .coordination/changes.diff)

输出结构化 review 结果到 .coordination/review-result.json：
{"approved": bool, "issues": [...], "suggestions": [...]}
PROMPT
)"
```

3. **Coordinator 处理 review 结果**

```bash
APPROVED=$(jq -r '.approved' .coordination/review-result.json)
if [ "$APPROVED" = "false" ]; then
  ISSUES=$(jq -r '.issues | join("\n")' .coordination/review-result.json)
  # 将 review 问题反馈给 implementation agent（新 session）
  claude -p --max-turns 30 \
    "修复以下 review 问题：${ISSUES}"
fi
```

4. 可选的高级配置：两个 agent 使用不同模型（如 implementation 用 Claude，review 用 GPT）增加视角多样性

## Tradeoffs

- **Pro**: 消除确认偏误，review agent 没有"沉没成本"
- **Pro**: 可以用不同模型组合，互补盲区
- **Con**: 成本翻倍——每个任务至少两个 agent session
- **Con**: Review agent 缺乏实现上下文，可能提出不切实际的修改建议

## Source

本项目的蒸馏实践——Codex 做 review、Claude Code 做 execution 的双 agent 模式。经典的代码审查最佳实践在 agent 场景下的适配。


path: references/synthesis-gate.md
content: # Synthesis Gate

## Problem

Coordinator 收到 worker 的 research 结果后，直接把原始结果传给下一个 worker——"Based on the findings above, implement the fix." 这违反了 Anthropic 的核心原则：coordinator 变成了传话筒，下游 worker 在没有综合理解的情况下工作，产出质量差且方向可能错误。

## Solution

在 Research 和 Implementation 阶段之间设置强制 synthesis gate。Coordinator 必须自己消化所有 research 结果，产出一份 synthesis 文档，才能启动下一阶段。Gate 的检查机制：synthesis 文档必须存在、长度达标、包含关键结构（结论、依据、行动计划）。

## Implementation

1. Research 阶段完成后，worker 将结果写入 `.coordination/research/`
2. Coordinator 执行 synthesis（这一步不可委派）
3. Gate 脚本检查 synthesis 质量

```bash
SYNTHESIS=".coordination/synthesis.md"

# 检查 1：文件存在且非空
if [ ! -s "$SYNTHESIS" ]; then
  echo "GATE FAILED: synthesis.md 不存在或为空"
  exit 1
fi

# 检查 2：最小长度（synthesis 不能是一句话）
LINES=$(wc -l < "$SYNTHESIS")
if [ "$LINES" -lt 10 ]; then
  echo "GATE FAILED: synthesis.md 只有 ${LINES} 行，不足以覆盖 research 结论"
  exit 1
fi

# 检查 3：必须包含关键结构
for SECTION in "结论\|Conclusion" "行动计划\|Action Plan\|Implementation Plan" "依据\|Evidence\|Rationale"; do
  if ! grep -qiE "$SECTION" "$SYNTHESIS"; then
    echo "GATE FAILED: synthesis.md 缺少必要节: ${SECTION}"
    exit 1
  fi
done

echo "GATE PASSED: synthesis ready for implementation phase"
```

4. Gate 通过后，将 synthesis.md 作为 implementation worker 的输入

```bash
claude -p --max-turns 50 \
  "根据以下 synthesis 执行实现。$(cat .coordination/synthesis.md)"
```

## Tradeoffs

- **Pro**: 强制 coordinator 理解而非传话，显著提升下游 worker 产出质量
- **Pro**: Synthesis 文档成为可审计的决策记录
- **Con**: 增加一个串行步骤，总耗时增加
- **Con**: 结构化检查是浅层验证——coordinator 可能写出满足格式但内容空洞的 synthesis

## Source

Anthropic "Building multi-agent systems" 博客的核心原则。本项目蒸馏实践中发现的 coordinator-as-passthrough 反模式。


path: references/task-coordination.md
content: # File-Based Task Coordination

## Problem

多个 agent 并行工作时需要知道：哪些任务已被领取、哪些正在进行、哪些已完成。没有中心化的任务状态，agent 会重复做同一件事或遗漏任务。MCP server 等进程内通信方案在跨 session 场景下不可用——agent 运行在不同 tmux pane、甚至不同机器上。

## Solution

用 JSON 文件作为共享任务板。每个任务有 `pending/claimed/done/failed` 四种状态，领取时写入 claim 者的 session-id。通过 lockfile 做并发控制，防止两个 agent 同时领取同一任务。

## Implementation

1. Coordinator 创建任务文件 `.coordination/tasks.json`

```json
{
  "tasks": [
    {"id": "t1", "description": "修改 parser.ts", "status": "pending", "claimed_by": null, "result": null},
    {"id": "t2", "description": "修改 visitor.ts", "status": "pending", "claimed_by": null, "result": null},
    {"id": "t3", "description": "写测试", "status": "pending", "claimed_by": null, "result": null}
  ],
  "updated_at": "2026-04-06T10:00:00Z"
}
```

2. Worker 领取任务（带锁）

```bash
LOCKFILE=".coordination/tasks.lock"
TASKFILE=".coordination/tasks.json"

# 获取锁（重试 10 次，指数退避 50-500ms）
for i in $(seq 1 10); do
  if mkdir "$LOCKFILE" 2>/dev/null; then
    # 找第一个 pending 任务并领取
    TASK_ID=$(jq -r '.tasks[] | select(.status == "pending") | .id' "$TASKFILE" | head -1)
    if [ -n "$TASK_ID" ]; then
      jq --arg id "$TASK_ID" --arg sid "$SESSION_ID" \
        '(.tasks[] | select(.id == $id)) |= (.status = "claimed" | .claimed_by = $sid)' \
        "$TASKFILE" > "${TASKFILE}.tmp" && mv "${TASKFILE}.tmp" "$TASKFILE"
    fi
    rmdir "$LOCKFILE"
    break
  fi
  sleep "0.$(( 50 * i ))"
done
```

3. Worker 完成后更新状态

```bash
# 标记完成（同样需要锁）
jq --arg id "$TASK_ID" --arg result "$RESULT_FILE" \
  '(.tasks[] | select(.id == $id)) |= (.status = "done" | .result = $result)' \
  "$TASKFILE" > "${TASKFILE}.tmp" && mv "${TASKFILE}.tmp" "$TASKFILE"
```

4. Coordinator 轮询任务状态，所有 done 后进入 synthesis 阶段

## Tradeoffs

- **Pro**: 零依赖——只需要文件系统，跨 session、跨机器可用
- **Pro**: 状态可审计——JSON 文件可以随时查看
- **Con**: Lockfile 竞争在高并发下效率低（>10 agent 可能需要更好的方案）
- **Con**: 没有 watch/notify 机制，只能轮询

## Claude Code Swarm 的邮箱 IPC 实现

Claude Code 的 Swarm 模式（~6,800 行，30 文件）使用 file-based mailbox：

- **路径**: `~/.claude/teams/{team-name}/inboxes/{agent-name}.json`
- **并发控制**: lockfile + 指数退避（10 次重试，5-100ms）
- **消息类型**: 10 种，包括 `permission_request/response`、`shutdown_request`、`plan_approval_request`
- **后端检测优先级**: tmux > iTerm2 > in-process（`backends/registry.ts`）
- **tmux 实现**: PID-scoped sockets（`claude-swarm-{pid}`），每个 agent 一个 pane
- **in-process fallback**: 同一 Node.js 进程内跑多个 query loop

与本 Pattern 的关系：Claude Code 的实现和我们的 `tasks.json` + lockfile 方案思路一致。但它用了 per-agent inbox（每个 agent 一个 JSON 文件）而不是共享的 tasks.json。Per-agent inbox 在高并发下锁竞争更少——每个 agent 只写自己的 inbox，读别人的 inbox 不需要锁。

## Source

Claude Code 源码 swarm 模块。OMC Swarm 模式的 file-based mailbox 机制。


path: references/workspace-isolation.md
content: # Workspace Isolation（Git Worktree per Agent）

## Problem

多个 agent 在同一工作目录下操作会互相干扰：agent A 的 `git checkout` 影响 agent B 看到的文件，agent A 的未提交改动污染 agent B 的 `git diff` 输出。共享工作目录是多 agent 冲突的根源。

## Solution

每个 worker agent 使用独立的 git worktree。Worktree 共享同一个 .git 仓库（提交历史、对象存储共享），但有独立的工作目录和 index。Agent 在自己的 worktree 中自由操作，完成后通过 merge/cherry-pick 合并结果。

## Implementation

1. Coordinator 为每个 worker 创建 worktree

```bash
# 从当前 HEAD 创建 worktree
WORKER_ID="worker-parser"
git worktree add ".worktrees/${WORKER_ID}" -b "work/${WORKER_ID}" HEAD

# Worker 在 .worktrees/worker-parser/ 中工作
# 独立的文件系统，独立的 git index
```

2. Worker agent 启动时 cd 到自己的 worktree

```bash
claude -p --cwd ".worktrees/${WORKER_ID}" \
  "在当前目录中完成以下任务：修改 parser.ts..."
```

3. 任务完成后合并结果

```bash
# 方案 A：merge（保留 commit 历史）
git merge "work/${WORKER_ID}" --no-ff

# 方案 B：cherry-pick（只取最终结果）
git cherry-pick "work/${WORKER_ID}"

# 方案 C：diff-apply（最安全，人工 review）
git diff main..."work/${WORKER_ID}" > "${WORKER_ID}.patch"
```

4. 清理 worktree

```bash
git worktree remove ".worktrees/${WORKER_ID}"
git branch -d "work/${WORKER_ID}"
```

## Tradeoffs

- **Pro**: 彻底消除并发文件冲突——每个 agent 有完全独立的文件系统视图
- **Pro**: Git 原生支持，无需额外工具
- **Con**: 磁盘空间消耗（每个 worktree 是完整的工作目录副本）
- **Con**: Merge 冲突在合并阶段集中爆发，需要 coordinator 处理
- **Con**: 共享 .git/objects 下的 gc 和 prune 需要注意时机

## Source

Claude Code worktree 功能。Git worktree 官方文档。OMC Coordinator 模式的 workspace 隔离实践。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)