# 多智能体模式消息协议

> 所有插入对话的 user 消息必须遵循统一格式。
> 不使用 `[系统通知|xxx]` 前缀，改用自然语言前缀。

---

## 1. 消息格式模板

所有通信 user 消息都使用以下结构：

```
来自 {显示名} 的{消息类型}
id: {消息id}

<{显示名}>
<{标签}>
{内容}
</{标签}>
</{显示名}>
```

### 字段说明

| 字段 | 说明 | 示例 |
|------|------|------|
| 显示名 | `{Role Name}_{agent_id}` 或 `Team Leader` | `UI Operator_1`、`Full-Stack Engineer_1` |
| 消息类型 | 任务发布 / 任务进度输出 / 任务完成汇报 / 提问 / 消息 / 回答 | 见下表 |
| 消息id | 本次消息的全局唯一标识，用于 answer 时引用 | `ask_fse_001`、`msg_uio_003` |
| 标签 | Task / Output / Ask / Message / Answer | 与消息类型对应 |
| 内容 | 消息正文 | 任意文本 |

### 消息类型与标签对应表

| 消息类型 | 标签 | 发送方 | 接收方 |
|---------|------|--------|--------|
| 任务发布 | `<Task>` | Team Leader | 子智能体 |
| 任务进度输出 | `<Output>` | 子智能体 | Team Leader |
| 任务完成汇报 | `<Output>` | 子智能体 | Team Leader |
| 提问 | `<Ask>` | 子智能体 | Team Leader / 其他子智能体 |
| 消息 | `<Message>` | Team Leader / 子智能体 | 子智能体 |
| 回答 | `<Answer>` | 子智能体 | 子智能体（返回到 ask 工具结果） |

---

## 2. 主智能体 → 子智能体

### 2.1 任务发布

当主智能体通过 `create_sub_agent` 或 `send_message_to_sub_agent` 向子智能体发布任务时使用。

```
来自 Team Leader 的任务发布
id: task_001

<Team Leader>
<Task>
请为项目设计前端配色方案，输出 design.md 到 sub_agent_results/design/。
</Task>
</Team Leader>
```

### 2.2 后续消息 / 运行中引导

当主智能体在子智能体运行期间通过 `send_message_to_sub_agent` 插入引导消息时使用。

```
来自 Team Leader 的消息
id: msg_tl_002

<Team Leader>
<Message>
先不要创建 API，先确认一下现有的 auth 模块是否可复用。
</Message>
</Team Leader>
```

### 2.3 主智能体问子智能体（ask_sub_agent）

当主智能体通过 `ask_sub_agent` 向子智能体提问时使用。

```
来自 Team Leader 的提问
id: ask_tl_001

<Team Leader>
<Ask>
你预计还需要多久完成？
</Ask>
</Team Leader>
```

子智能体的回答返回到 `ask_sub_agent` 工具结果中，不插入主智能体对话。

---

## 3. 子智能体 → 主智能体

### 3.1 任务进度输出

子智能体在自然输出中汇报进度时，由后端捕获并插入主智能体对话。

```
来自 UI Operator_1 的任务进度输出
id: out_uio_001

<UI Operator_1>
<Output>
我现在开始分析现有设计风格和用户需求...
</Output>
</UI Operator_1>
```

### 3.2 任务完成汇报

子智能体本轮自然结束输出时，最后一条输出作为完成汇报插入主智能体对话。

```
来自 UI Operator_1 的任务完成汇报
id: out_uio_002

<UI Operator_1>
<Output>
我完成了前端配色的设计，生成了 design.md，主色调为蓝色系。
</Output>
</UI Operator_1>
```

**注意**：子智能体不调用 `report_progress` 或 `finish_task` 工具。自然的 assistant 输出即表示进度或完成。

### 3.3 子智能体向主智能体提问

子智能体通过 `ask_master` 工具向主智能体提问。

```
来自 Full-Stack Engineer_1 的提问
id: ask_fse_001

<Full-Stack Engineer_1>
<Ask>
我该怎么处理版本冲突问题？项目里当前用的是什么分支策略？
</Ask>
</Full-Stack Engineer_1>
```

主智能体通过 `answer_sub_agent_question` 工具回答，回答内容返回到 `ask_master` 工具结果中。

---

## 4. 子智能体 → 子智能体

### 4.1 A 向 B 提问

子智能体 A 通过 `ask_other_agent` 向子智能体 B 提问。

```
来自 UI Operator_1 的提问
id: ask_uio_001

<UI Operator_1>
<Ask>
API 接口已经确定了吗？我需要接口字段来设计表单。
</Ask>
</UI Operator_1>
```

这条消息插入到 B 的 user 消息中。

### 4.2 B 回答 A

子智能体 B 通过 `answer_other_agent` 回答 A。

```
来自 Full-Stack Engineer_1 的回答
id: ans_fse_001

<Full-Stack Engineer_1>
<Answer question_id="ask_uio_001">
已经确定，见 api.md。用户注册接口为 POST /api/users，字段为...
</Answer>
</Full-Stack Engineer_1>
```

回答返回到 A 的 `ask_other_agent` 工具结果中。

### 4.3 A 向 B 发送普通消息

子智能体 A 通过 `ask_other_agent` 问 B，但内容不是需要回答的问题，而是通知。

```
来自 UI Operator_1 的消息
id: msg_uio_003

<UI Operator_1>
<Message>
前端页面已经 ready，可以开始对接了。
</Message>
</UI Operator_1>
```

B 可以直接通过自然输出回复，回复会返回到 A 的 `ask_other_agent` 工具结果中。

---

## 5. ID 生成规则

| 消息类型 | ID 前缀 | 示例 |
|---------|---------|------|
| 任务发布 | `task_` | `task_001` |
| 任务进度输出 | `out_` | `out_uio_001` |
| 任务完成汇报 | `out_` | `out_uio_002` |
| 子智能体问主智能体 | `ask_` | `ask_fse_001` |
| 主智能体问子智能体 | `ask_` | `ask_tl_001` |
| 子智能体间提问 | `ask_` | `ask_uio_001` |
| 子智能体间回答 | `ans_` | `ans_fse_001` |
| 普通消息 | `msg_` | `msg_tl_002` |

ID 需要保证在多智能体会话内全局唯一。

---

## 6. 前端渲染

前端消息气泡只显示三部分：

1. 角色：如 `UI Operator_1`
2. 目的/动作：如 `任务进度输出`、`提问`、`消息`
3. 内容：XML 标签内的文本

不显示 XML 标签本身。

示例渲染：

```
┌────────────────────────────────────┐
│ UI Operator_1 任务进度输出          │
│                                    │
│ 我现在开始分析现有设计风格...         │
└────────────────────────────────────┘
```

---

## 7. 关键约束

1. 所有插入对话的 user 消息都必须包含完整的 XML 包裹，便于后端解析和前端渲染。
2. `id` 放在 XML 外面，不放在 `<>` 属性中。
3. 子智能体之间的通信不强制同步到主智能体，但子智能体必须在提示词中被要求：向其他子智能体提问时，必须同时直接向主智能体输出汇报。
4. 回答类消息（`answer_sub_agent_question`、`answer_other_agent`）不插入 user 消息，只返回到对应 ask 工具的结果中。