agent-Specialization/docs/multi_agent_mode/06_implementation_plan.md

多智能体模式实现计划

实现顺序不作为严格 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. 现有单智能体模式不受影响