# 7. Agent 间通讯架构

> Agent 子进程之间完全隔离，不直接通讯。所有消息都经主进程路由，所有数据都通过 SQLite 共享。

---

## 7.1 核心原则：框架是"神经系统"

每个 Agent 是一个独立的 ACP（Claude Code）子进程。它们之间 **不直接通讯**。

```
                  ❌ 不是这样：Agent 之间直连
                  ┌──────┐    ┌──────┐
                  │Agent A│←──→│Agent B│
                  └──────┘    └──────┘

                  ✅ 而是这样：所有消息经主进程中转
                  ┌──────┐    ┌────────────┐    ┌──────┐
                  │Agent A│←──→│ 主进程路由  │←──→│Agent B│
                  └──────┘    │  (框架层)   │    └──────┘
                              └────────────┘
```

**类比**：部门之间不是互相打电话，而是通过公司的 OA 系统发任务、汇报、审批。

---

## 7.2 消息类型

| 消息方法 | 方向 | 场景 | 版本 |
|---------|------|------|------|
| `task.assign` | 上级 → 下级 | 分派任务 | v1.0 |
| `task.report` | 下级 → 上级 | 汇报结果/进度 | v1.0 |
| `task.handover` | 同级 → 同级 | Pipeline 节点流转 | v1.1 |
| `task.feedback` | 同级 → 同级 | 经验/数据反馈回流 | v1.1 |
| `cxo.review` | CXO ↔ CXO | 方案审核请求 | v1.2 |
| `cxo.approve` | CXO → CXO | 审核通过 | v1.2 |
| `cxo.reject` | CXO → CXO | 审核驳回 | v1.2 |
| `status.update` | 广播 | 状态变更通知 | v1.0 |
| `status.heartbeat` | 下级 → 上级 | 心跳状态上报 | v1.2 |
| `data.share` | 任意 | 共享数据/资源 | v1.2 |
| `data.request` | 任意 | 请求数据/资源 | v1.2 |

---

## 7.3 消息流转的完整流程

### 场景：Master 与用户聊完 → 下达指令给 CEO

**Step 1: 用户跟 Master 聊天**

```
用户: "我想做一个 AI 互动短剧平台，主打年轻女性市场"
           │
           ▼ (WebSocket / HTTP)
       框架服务器
           │
           ▼ (stdin pipe)
     Master ACP 进程
           │
           │ 根据 agent.md + soul.md 思考:
           │ → "用户意图: 做一个面向年轻女性的 AI 短剧平台"
           │ → "需要将意图结构化为 Goal，交给 CEO 去战略拆解"
```

**Step 2: Master 调用工具下达指令**

```
Master ACP 输出 (stdout):
{
  "jsonrpc": "2.0",
  "method": "tool.call",
  "params": {
    "name": "task.assign",
    "args": {
      "to": "cxo-ceo-001",
      "task": {
        "description": "设计 AI 互动短剧平台的完整业务体系",
        "goal": {
          "target": "Q1 日活 10 万",
          "audience": "18-28 岁年轻女性",
          "product": "AI 互动短剧，支持用户二改"
        },
        "priority": "high"
      }
    }
  }
}
```

**Step 3: 框架拦截 → 路由 → 触发 CEO**

```
框架主进程收到 Master 的工具调用:
  1. 生成消息 ID，写入 SQLite messages 表
  2. 查找 cxo-ceo-001 的 ACP 子进程
     ├── 如果 CEO 正在运行 → 向 CEO 的 stdin 注入消息
     └── 如果 CEO 处于 idle → 启动 CEO 的 ACP 子进程，注入消息
  3. 给 Master 返回: "已发送，任务 ID: task-xxx"
```

**Step 4: CEO 收到指令，开始工作**

```
CEO ACP 进程的 stdin 收到:
  "[来自 Master 的任务]
   设计 AI 互动短剧平台的完整业务体系
   目标: Q1 日活 10 万
   受众: 18-28 岁年轻女性
   产品: AI 互动短剧，支持用户二改"

CEO 根据 agent.md 和 soul.md 推理:
  → "需要 5 个 Role: 编剧、制作、运营、推广、数据"
  → "Pipeline: 选题→剧本→制作→上架→推广→反馈"

CEO 调用工具 (stdout → 框架拦截):
  tool_call: role.create({ name: "编剧部", type: "role", ... })
  tool_call: role.create({ name: "推广部", type: "role", ... })
  tool_call: pipeline.set({ edges: [...] })

框架拦截每个工具调用:
  → AgentScaffold 创建目录
  → AgentRegistry 注册到数据库
  → 启动 ACP 子进程
```

**Step 5: CEO 不等编剧部完成，继续做其他事**

```
CEO 发完 role.create 后继续:
  → 给推广部分派任务
  → 给数据部分派任务
  → 开始自己的 5 分钟心跳循环

编剧部做完后:
  → 编剧部 ACP → (stdout) → 框架 → (stdin) → CEO ACP
  → CEO 收到汇报，评估结果，继续下一步

全程异步。
```

---

## 7.4 三种数据共享方式

| 方式 | 适用场景 | 机制 |
|------|---------|------|
| **消息传递** | 任务指令、结果汇报、状态更新 | 主进程路由，payload 携带 JSON |
| **SQLite 查询** | 查看全局状态、组织架构、历史任务 | Agent 调用工具（如 `org.status`），主进程查 SQLite 返回 |
| **文件路径引用** | 剧本、视频、数据报表等大文件 | 消息里传路径，目标 Agent 读取文件 |

### 消息传递（轻量数据）

```json
{
  "method": "task.report",
  "params": {
    "from": "role-data-001",
    "to": "cxo-ceo-001",
    "payload": {
      "metrics": { "dau": 23000, "retention": 0.42, "conversion": 0.18 },
      "insight": "古装题材在 18-25 岁女性中转化率最高 (23%)"
    }
  }
}
```

### SQLite 查询（全局状态）

```
CEO 调用: org.status()
    ↓ 框架主进程查询 SQLite
    ↓ 返回:
{
  "total_agents": 12,
  "running": 8,
  "pipeline": "选题→剧本→制作→上架→推广→反馈",
  "goal_progress": 0.23,
  "recent_tasks": [...]
}
```

### 文件路径引用（大文件）

```
编剧部完成剧本 → 流转到制作部:

{
  "method": "task.handover",
  "params": {
    "from": "role-dramatist-001",
    "to": "role-producer-001",
    "payload": {
      "type": "script",
      "path": "data/agents/role-dramatist-001/workspace/assets/drama-ep01.md",
      "summary": "都市爱情第1集，含3个互动分支"
    }
  }
}

制作部的 ACP 进程根据 path 读取文件 → 开始制作
（框架授予制作部对该路径的只读权限）
```

---

## 7.5 通讯的设计约束

| 约束 | 原因 |
|------|------|
| 子进程之间不直连 | 隔离性——一个 Agent 崩溃不影响其他 Agent |
| 所有通讯经主进程 | 可审计、可持久化、可限流、可切断 |
| 大数据传路径不传内容 | 保持消息体轻量，避免主进程成为瓶颈 |
| Agent 不感知并发 | 每个 Agent 以为自己是唯一的，框架在背后调度 |

> **`task.assign` / `role.create` 这些工具不是 Agent 自己实现的，是框架暴露给 Agent 的。**
> Agent 在 agent.md 里写了"可用工具: task.assign"，框架在启动 ACP 时注册这些工具。
> 当 Agent 调用时，框架拦截并处理。