236 lines
7.5 KiB
Markdown
236 lines
7.5 KiB
Markdown
# 多智能体模式实现计划
|
||
|
||
> 实现顺序不作为严格 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. 现有单智能体模式不受影响
|