agent-Specialization/docs/multi_agent_mode/07_existing_code_analysis.md

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

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

---

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 需要设置合理超时，避免永久阻塞。