# 多智能体模式实现计划

> 实现顺序不作为严格 phase，而是按依赖关系自然推进。  
> 核心原则：完全隔离、复制改造、底层复用。

---

## 1. 目录与文件规划

### 1.1 后端代码

```
modules/multi_agent/
├── __init__.py
├── terminal.py                  # MultiAgentTerminal
├── manager.py                   # 多智能体会话与全局状态管理
├── agent_store.py               # 角色配置加载与保存
├── conversation_store.py        # 多智能体会话存储
├── message_router.py            # 消息路由与待处理队列
├── sub_agent_task.py            # MultiAgentSubAgentTask
├── sub_agent_manager.py         # MultiAgentSubAgentManager
├── prompts.py                   # prompt 模板
└── tools/
    ├── __init__.py
    ├── master_tools.py          # Team Leader 工具定义
    ├── agent_tools.py           # 子智能体工具定义
    └── tool_handlers.py         # 工具处理函数
```

### 1.2 前端代码

```
static/src/views/MultiAgentView.vue
static/src/components/multi-agent/
├── ChatPanel.vue
├── AgentList.vue
├── MessageBubble.vue
└── CreateAgentDialog.vue
```

### 1.3 设计文档

```
docs/multi_agent_mode/
├── 01_overview.md
├── 02_message_protocol.md
├── 03_tool_definitions.md
├── 04_message_routing.md
├── 05_data_model.md
├── 06_implementation_plan.md
└── 07_existing_code_analysis.md
```

### 1.4 数据目录

```
~/.astrion/astrion/host/mutiagents/
├── agents/
├── conversations/
└── state.json
```

---

## 2. 实现步骤

### Step 1：基础设施

1. 创建 `modules/multi_agent/` 包
2. 创建 `docs/multi_agent_mode/` 目录（已完成）
3. 创建 `~/.astrion/astrion/host/mutiagents/` 数据目录
4. 预置 4 个角色文件到 `agents/`

### Step 2：角色配置

1. 实现 `agent_store.py`
   - 加载角色 Frontmatter
   - 保存自定义角色
   - 列出所有角色
   - 构建完整 prompt（基础 prompt + 自定义 prompt）

2. 预置角色：
   - `ui-operator`
   - `full-stack-engineer`
   - `code-reviewer`
   - `researcher`

### Step 3：子智能体改造

1. 实现 `MultiAgentSubAgentTask`（继承 `SubAgentTask`）
   - 覆盖 `_run_loop`，使用多智能体工具列表
   - 覆盖系统提示词生成
   - 捕获 assistant 输出并转发到主智能体
   - 维护 `pending_messages` 队列
   - 维护 `pending_tool_calls` 等待列表
   - 支持 inline 消息注入
   - 支持自然结束（不依赖 finish_task）

2. 实现 `MultiAgentSubAgentManager`（继承 `SubAgentManager`）
   - 创建 `MultiAgentSubAgentTask` 实例
   - 管理所有子智能体状态
   - 提供查询活跃子智能体接口
   - 提供终止实例接口

### Step 4：消息路由

1. 实现 `message_router.py`
   - `route_message(target_agent_id, message)`
   - 根据目标状态选择 inline / 工具结果返回 / 触发新任务
   - 处理边界情况（最后一轮输出时收到消息）
   - 批量消费待处理消息

2. 实现消息格式化函数
   - `format_task_message(display_name, content)`
   - `format_output_message(display_name, content)`
   - `format_ask_message(display_name, content, message_id)`
   - `format_message_message(display_name, content, message_id)`
   - `format_answer_message(display_name, content, message_id)`

### Step 5：主智能体 Terminal

1. 实现 `MultiAgentTerminal`（基于 `MainTerminal` 复制）
   - 移除旧版子智能体工具
   - 添加多智能体专用工具
   - 使用 `MultiAgentSubAgentManager`
   - 使用 `MultiAgentConversationStore`
   - 实现 `answer_sub_agent_question` 等工具处理

2. 实现工具处理函数
   - `create_sub_agent`
   - `terminate_sub_agent`
   - `send_message_to_sub_agent`
   - `ask_sub_agent`
   - `answer_sub_agent_question`
   - `list_active_sub_agents`
   - `get_sub_agent_status`
   - `create_custom_agent`
   - `list_agents`

### Step 6：会话存储

1. 实现 `MultiAgentConversationStore`
   - 复制 `ConversationManager` 的 CRUD 逻辑
   - 数据目录指向 `~/.astrion/astrion/host/mutiagents/conversations/`
   - 保存主智能体对话
   - 保存每个子智能体对话

### Step 7：前端页面

1. 创建 `MultiAgentView.vue`
   - 类似现有 ChatView，但专门用于多智能体模式
   - 支持消息气泡按角色/类型渲染
   - 支持显示活跃子智能体列表
   - 支持创建子智能体

2. 创建组件
   - `MessageBubble.vue`：渲染统一消息格式
   - `AgentList.vue`：显示子智能体状态
   - `CreateAgentDialog.vue`：创建自定义角色

3. 添加路由 `/multiagent/new`

### Step 8：入口

1. 登录页添加「多智能体模式 beta」按钮
2. 点击后跳转到 `/multiagent/new`
3. 初始化 `MultiAgentTerminal`

### Step 9：联调测试

1. 测试创建子智能体
2. 测试子智能体自然输出转发
3. 测试 `send_message_to_sub_agent` 运行中引导
4. 测试 `ask_master` / `answer_sub_agent_question`
5. 测试 `ask_other_agent` / `answer_other_agent`
6. 测试子智能体对话持久化
7. 测试角色创建与保存

---

## 3. 代码隔离清单

| 现有文件 | 处理方式 |
|---------|---------|
| `core/main_terminal.py` | 复制为 `modules/multi_agent/terminal.py` |
| `core/main_terminal_parts/tools_definition/agent_tools.py` | 复制改造为 `modules/multi_agent/tools/master_tools.py` |
| `core/main_terminal_parts/tools_execution.py` | 复制需要的部分到 `modules/multi_agent/terminal.py` |
| `modules/sub_agent/manager.py` | 继承创建 `modules/multi_agent/sub_agent_manager.py` |
| `modules/sub_agent/task.py` | 继承创建 `modules/multi_agent/sub_agent_task.py` |
| `modules/sub_agent/toolkit.py` | 复制改造为 `modules/multi_agent/tools/agent_tools.py` |
| `modules/sub_agent/prompts.py` | 复制改造为 `modules/multi_agent/prompts.py` |
| `utils/conversation_manager/*.py` | 复制改造为 `modules/multi_agent/conversation_store.py` |
| `server/chat_flow.py` | 参考实现，为 `/multiagent` 创建新的 API 入口 |
| `server/chat_flow_task_support.py` | 参考 `inject_runtime_user_message` 实现多智能体消息注入 |
| `static/src/views/ChatView.vue` | 复制改造为 `static/src/views/MultiAgentView.vue` |

---

## 4. 复用点清单

| 能力 | 复用方式 |
|------|---------|
| 模型调用 | `DeepSeekClient` |
| 工具执行底层 | `WebTerminal.handle_tool_call` 的执行链路 |
| 文件/终端/搜索等工具 | 现有工具函数 |
| 沙箱/权限 | `evaluate_tool_permission` |
| 对话存储格式 | `ConversationManager` 的 JSON 结构 |
| 原子写入 | `_atomic_write_json` 模式 |
| 前端组件 | 复制 ChatView 改造 |

---

## 5. 风险与应对

| 风险 | 应对 |
|------|------|
| 子智能体消息丢失 | 待处理队列持久化 + 唯一 id + 消费确认 |
| 子智能体状态错乱 | 状态机清晰 + reconcile 机制 |
| 主智能体上下文爆炸 | 子智能体只汇报关键步骤，详细内容放文件 |
| 多实例并发冲突 | 每个实例独立上下文，独立存储 |
| 与现有代码耦合 | 严格隔离，复制改造 |

---

## 6. 验收标准

1. 登录页有「多智能体模式 beta」按钮
2. 点击后进入 `/multiagent/new`
3. 可以创建至少 2 个不同角色的子智能体
4. 子智能体输出自动显示在主对话中
5. Team Leader 可以运行中引导子智能体
6. 子智能体可以向 Team Leader 提问并收到回答
7. 子智能体可以向其他子智能体提问并收到回答
8. 子智能体对话完整保存，刷新后可恢复
9. 现有单智能体模式不受影响