# 多智能体模式：现有代码分析

> 本文档梳理实现多智能体模式需要理解的现有代码，为复制改造提供依据。

---

## 1. 子智能体实现

### 1.1 核心文件

```
modules/sub_agent/
├── __init__.py
├── manager.py          # SubAgentManager
├── task.py             # SubAgentTask
├── toolkit.py          # 工具定义
├── prompts.py          # 提示词
├── state.py            # 状态管理
├── stats.py            # 统计
├── creation.py         # 创建参数
└── tools.py            # 本地工具实现
```

### 1.2 SubAgentManager（manager.py）

- 在主进程内以独立事件循环运行子智能体协程
- `create_sub_agent()` 创建并启动任务
- `wait_for_completion()` 阻塞等待完成
- `terminate_sub_agent()` 强制终止
- `poll_updates()` 检查已完成任务
- `execute_tool_for_sub_agent()` 代理工具执行，复用主进程链路
- `tasks` 字典保存所有任务状态

多智能体模式可继承点：
- 创建 `MultiAgentSubAgentManager`，重写 `create_sub_agent` 以创建 `MultiAgentSubAgentTask`
- 扩展任务记录字段：`role_id`、`display_name`、`pending_messages`、`pending_tool_calls`
- 扩展查询接口：`list_active_sub_agents()`、`get_sub_agent_status()`

### 1.3 SubAgentTask（task.py）

- `_run_loop()`：LLM 主循环，最多 50 轮
- `_call_model()`：流式调用模型
- `_execute_tool()`：通过 manager 执行工具
- `_finalize_task()`：任务结束时保存 output.json、stats.json、conversation.json
- `FINISH_TOOL`：必须调用 finish_task 才结束

多智能体模式改造点：
- 移除 `FINISH_TOOL` 依赖，自然结束输出即任务完成
- 在 `_run_loop` 中每轮模型调用前消费 `pending_messages`
- 捕获 assistant 输出并转发到主智能体对话
- 新增 `ask_master`、`ask_other_agent`、`answer_other_agent` 工具处理
- 维护 `pending_tool_calls`，支持阻塞等待回答

### 1.4 工具定义（toolkit.py）

现有 8 个工具：
- `read_file`
- `write_file`
- `edit_file`
- `run_command`
- `web_search`
- `extract_webpage`
- `search_workspace`
- `read_mediafile`

多智能体模式可复用这些工具定义，新增通信工具。

### 1.5 提示词（prompts.py）

- `build_user_message()`：给子智能体的任务消息
- `build_system_prompt()`：子智能体系统提示词

多智能体模式需要：
- 新的 `build_system_prompt()`，包含团队规则
- 新的 `build_user_message()`，使用统一消息格式
- 角色 prompt 拼接函数

---

## 2. 后台任务通知池机制

### 2.1 核心文件

- `server/chat_flow_task_support.py`
- `server/chat_flow_task_main.py`
- `server/chat_flow_tool_loop.py`

### 2.2 inject_runtime_user_message

位置：`server/chat_flow_task_support.py`

功能：运行期/空闲期统一向对话插入一条 user 消息。

关键参数：
- `web_terminal`：终端实例
- `messages`：当前运行中的消息列表（inline 时用）
- `text`：消息文本
- `source`：消息来源，如 `sub_agent`
- `inline`：True 表示运行期插入，不触发新任务
- `persist`：是否持久化到对话历史

多智能体模式参考点：
- 子智能体输出转发到主智能体时，使用类似机制
- 但消息格式改为统一 XML 格式，不使用 `[系统通知|sub_agent]` 前缀

### 2.3 process_sub_agent_updates

位置：`server/chat_flow_task_support.py`

功能：轮询子智能体完成状态，把结果插入当前对话上下文。

两种模式：
- `inline=True`：运行期间，插入 `messages` 不触发新任务
- `inline=False`：空闲期间，触发后续任务

多智能体模式参考点：
- 子智能体自然输出捕获后，可以 inline 插入主智能体 `messages`
- 子智能体空闲时收到的消息，作为 user 消息触发新任务

### 2.4 _collect_pending_completion_notices

位置：`server/chat_flow_task_main.py`

功能：从子智能体和后台命令两路统一取出所有待通知项，按时间排序，一次性处理。

关键设计：
- 取出时即就地标记 `notified`，防止重复消费
- 返回多条通知时，前 N-1 条作为前置通知，最后一条触发新任务

多智能体模式参考点：
- 每个子智能体维护自己的待处理消息队列
- 消费时批量取出，避免多次触发新任务
- 使用唯一 id 标记已消费

### 2.5 poll_completion_notifications

位置：`server/chat_flow_task_main.py`

功能：统一轮询器，单工作区只 spawn 一个，避免并发冲突。

多智能体模式参考点：
- 多智能体模式也需要一个类似的通知/消息处理循环
- 但消息源更多（Team Leader → Agent、Agent → Agent、Agent → Team Leader）

---

## 3. 主智能体工具调用链路

### 3.1 工具定义

位置：`core/main_terminal_parts/tools_definition/agent_tools.py`

现有主智能体子智能体工具：
- `create_sub_agent`
- `close_sub_agent`
- `terminate_sub_agent`
- `get_sub_agent_status`

多智能体模式需要移除这些，新增自己的工具定义。

### 3.2 工具执行

位置：`core/main_terminal_parts/tools_execution.py` 中 `handle_tool_call`

- 参数预检查
- 权限检查
- 根据 tool_name 分发到具体处理函数
- 返回 JSON 字符串

多智能体模式参考点：
- `MultiAgentTerminal.handle_tool_call` 中增加多智能体工具的分支
- 子智能体工具处理函数放在 `modules/multi_agent/tools/tool_handlers.py`

### 3.3 WebTerminal 广播

位置：`core/web_terminal.py`

- `handle_tool_call()` 覆盖父类，广播 `tool_execution_start` / `tool_status` / `tool_execution_complete`
- `broadcast()` 发送 WebSocket 事件

多智能体模式参考点：
- `MultiAgentTerminal` 可继承 `WebTerminal` 或 `MainTerminal`
- 保留广播能力

---

## 4. 对话上下文管理

### 4.1 ContextManager

位置：`utils/context_manager/`

- `ConversationMixin.start_new_conversation()`：创建新对话
- `ConversationMixin.load_conversation_by_id()`：加载对话
- `ConversationMixin.save_current_conversation()`：保存当前对话

多智能体模式参考点：
- 创建 `MultiAgentContextManager` 或直接用 `MultiAgentConversationStore`
- 保存格式与现有 `messages.json` 一致

### 4.2 ConversationManager

位置：`utils/conversation_manager/`

- `crud_mixin.py`：`create_conversation`、`save_conversation`、`load_conversation`
- `path_mixin.py`：文件路径管理
- `index_mixin.py`：索引管理

多智能体模式参考点：
- 复制 `ConversationManager` 的实现到 `MultiAgentConversationStore`
- 修改数据目录为 `~/.astrion/astrion/host/mutiagents/conversations/`

---

## 5. Skill 归档机制

### 5.1 核心文件

`modules/skills_manager.py`

### 5.2 关键函数

- `validate_skill_directory()`：验证 skill 目录
- `archive_skill_directory()`：移动 skill 到归档目录
- `_parse_frontmatter()`：解析 YAML Frontmatter
- `_scan_skills_catalog()`：扫描 skill 目录

多智能体模式参考点：
- 角色配置使用类似的 Frontmatter 格式
- 角色归档目录：`~/.astrion/astrion/host/mutiagents/agents/`
- 可以复制 `_parse_frontmatter`、`_scan_skills_catalog` 的实现到 `agent_store.py`

---

## 6. 前端消息渲染

### 6.1 现有机制

- `server/chat_flow_task_support.py` 中 `inject_runtime_user_message` 发送 `user_message` 事件
- 前端 `messaging.ts` 处理 `user_message` 事件
- 根据 `message_source`、`visibility`、`starts_work` 等 metadata 渲染

### 6.2 多智能体模式改造点

- 多智能体消息也发送 `user_message` 事件
- 前端根据消息内容中的 XML 解析出角色、类型、内容
- 渲染为特殊气泡，不显示 XML 标签

---

## 7. 关键接口总结

| 能力 | 现有实现位置 | 多智能体模式实现位置 |
|------|------------|-------------------|
| 子智能体创建/管理 | `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` |
| 主智能体工具定义 | `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` |
| 运行时消息注入 | `server/chat_flow_task_support.py` | `modules/multi_agent/message_router.py` |
| 通知池轮询 | `server/chat_flow_task_main.py` | `modules/multi_agent/message_router.py` |
| 对话存储 | `utils/conversation_manager/` | `modules/multi_agent/conversation_store.py` |
| 角色归档 | `modules/skills_manager.py` | `modules/multi_agent/agent_store.py` |
| 前端页面 | `static/src/views/ChatView.vue` | `static/src/views/MultiAgentView.vue` |

---

## 8. 实现注意事项

1. **不要修改现有文件**：所有改造在 `modules/multi_agent/` 中完成，通过继承或复制实现。
2. **状态同步**：子智能体状态变更时需要同步更新 `metadata.json`。
3. **消息不丢失**：待处理消息队列需要持久化。
4. **上下文隔离**：每个子智能体独立 messages，不要互相污染。
5. **模型工具列表**：每轮模型调用前需要重新构造工具列表，确保多智能体通信工具可用。
6. **自然结束检测**：子智能体某轮没有工具调用且 assistant 输出为空时，认为本轮结束。
7. **阻塞问答超时**：`ask_master` / `ask_other_agent` 需要设置合理超时，避免永久阻塞。