JOJO/agent-Specialization

Fork 0

JOJO e8b857f3ae docs(multi-agent): 添加多智能体模式设计文档7份

2026-07-12 02:28:47 +08:00

9.0 KiB

Raw Blame History

多智能体模式总体架构

文档状态：设计草案
适用范围：宿主机模式（host mode），不覆盖 docker/web 模式
隔离原则：与现有对话系统完全隔离，复用底层能力但上层独立

1. 设计目标

在 Astrion 中引入一个实验性的「多智能体模式」：

主智能体固定扮演 Team Leader，负责任务拆解、调度、协调、回答子智能体提问。
支持预置角色与自定义角色，每个角色可以有多个实例（RoleName_1、RoleName_2）。
子智能体之间、子智能体与主智能体之间可以双向通信。
所有通信遵循统一的消息格式与路由规则。
与现有单智能体模式完全隔离，不影响现有代码与用户体验。

2. 核心设计原则

2.1 完全隔离

数据目录隔离：~/.astrion/astrion/host/mutiagents/
页面隔离：新页面 /multiagent/new
入口隔离：登录页单独按钮「多智能体模式 beta」
代码隔离：所有新增代码放在 modules/multi_agent/、docs/multi_agent_mode/、static/src/views/MultiAgentView.vue 等独立位置
现有文件如需改造，优先复制一份再改，不直接修改

2.2 能复用则复用

模型调用：复用 DeepSeekClient
工具执行链路：复用 WebTerminal.handle_tool_call 的底层执行能力
文件/终端/搜索等工具：复用现有工具实现
对话持久化格式：复用 ConversationManager 的存储格式
沙箱/权限机制：复用现有 evaluate_tool_permission 与宿主机沙箱

2.3 子智能体即完整对话

每个子智能体是一个独立的、完整的对话上下文：

有自己的 messages 列表
有自己的系统提示词
有自己的工具列表
自然输出 assistant 消息
支持被主智能体/其他子智能体在运行中插入消息引导
任务结束 = 本轮自然停止输出，但上下文保留

3. 角色与实例

3.1 角色（Role）

角色由 Markdown + YAML Frontmatter 定义，存储在：

~/.astrion/astrion/host/mutiagents/agents/<role_id>.md

示例 ui-operator.md：

---
id: ui-operator
name: UI Operator
description: 负责前端设计、UI 还原、配色方案
model: qwen3-max
thinking_mode: fast
---

你是团队的前端设计专家。你擅长：
- 根据需求设计 UI 界面
- 制定配色方案
- 输出设计文档和前端代码

工作风格：
- 先分析需求，再给出设计方案
- 输出简洁明确的设计说明

3.2 实例（Agent）

role_id：角色类型，如 ui-operator
agent_id：这个角色的第几个实例，从 1 开始
显示名：{Role Name}_{agent_id}，如 UI Operator_1、Full-Stack Engineer_1
同一个 role_id 可以有多个实例：UI Operator_1、UI Operator_2
不同 role_id 的实例序号独立：Full-Stack Engineer_1 与 UI Operator_1 可以同时存在
主智能体固定显示名为 Team Leader，没有 agent_id

4. 总体架构图

┌─────────────────────────────────────────────────────────────┐
│                     用户（Web 前端）                          │
│              /multiagent/new 页面                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  MultiAgentTerminal                         │
│              （基于 MainTerminal 复制改造）                   │
│  - 工具列表：主工具 + 多智能体专用工具                         │
│  - 子智能体管理器：MultiAgentSubAgentManager                  │
│  - 对话存储：指向 mutiagents/conversations/                   │
└─────────────────────────────────────────────────────────────┘
                              │
            ┌─────────────────┼─────────────────┐
            ▼                 ▼                 ▼
      ┌──────────┐     ┌──────────┐     ┌──────────┐
      │ Agent 1  │     │ Agent 2  │     │ Agent 3  │
      │UIOperator│     │ Full-   │     │ Code     │
      │    1     │     │ Stack   │     │ Reviewer │
      │          │     │Engineer1│     │    1     │
      └──────────┘     └──────────┘     └──────────┘
            │                 │                 │
            └─────────────────┴─────────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │       MessageRouter           │
              │   根据接收方状态决定：          │
              │   - inline 插入工具结果后       │
              │   - 空闲时作为 user 消息触发新任务│
              └───────────────────────────────┘

5. 主智能体职责

主智能体 = Team Leader，其系统提示词中明确：

除非任务极其简单或明确不需要，否则主动拆解任务并调用子智能体。
为每个子任务选择最合适的角色（role_id）。
子智能体可以向你提问，你必须及时通过 answer_sub_agent_question 回答。
子智能体之间可以互相沟通，你负责监督整体进度。
如果子智能体的中间输出需要干预，使用 send_message_to_sub_agent 引导。

6. 子智能体职责

子智能体系统提示词由两部分组成：

基础 prompt：通用团队规则
自定义 prompt：角色专属设定

基础 prompt 中明确：

你是智能体集群团队的一员。
不要频繁输出内容，不重要内容会污染主智能体上下文。
只汇报关键步骤。
任务完成后给出详细结论。
需要主智能体决策时，使用 ask_master。
需要与其他子智能体沟通时，使用 ask_other_agent / answer_other_agent。
如果向其他子智能体提问，必须同时直接向主智能体输出汇报。

7. 与现有系统的边界

现有系统	多智能体模式处理方式
现有对话页面	不改动，新增 `/multiagent/new`
现有 `MainTerminal`	不改动，复制为 `MultiAgentTerminal`
现有 `SubAgentManager`	不改动，继承创建 `MultiAgentSubAgentManager`
现有 `SubAgentTask`	不改动，继承创建 `MultiAgentSubAgentTask`
现有 `ConversationManager`	不改动，多智能体模式用自己的存储目录
现有后台通知池机制	参考其设计，多智能体模式实现自己的消息路由
现有工具执行链路	复用 `execute_tool_for_sub_agent`
现有沙箱/权限	复用，不额外限制子智能体工具参数

8. 入口与数据目录

8.1 入口

登录页面增加按钮：「多智能体模式 beta」。

点击后进入 /multiagent/new 页面，加载 MultiAgentTerminal。

8.2 数据目录

~/.astrion/astrion/host/mutiagents/
├── agents/                          # 角色定义
├── conversations/                   # 多智能体会话
│   └── <conv_id>/
│       ├── metadata.json
│       ├── messages.json            # Team Leader 对话
│       └── agents/
│           └── <agent_id>/
│               ├── metadata.json
│               └── messages.json    # 子智能体完整对话记录
└── state.json                       # 全局状态

子智能体对话记录的保存精度、时机、格式与主智能体对话记录一致。

9. 实现顺序（非严格 phase）

创建独立目录与数据存储结构
实现角色配置加载与预置角色
实现 MultiAgentSubAgentTask / MultiAgentSubAgentManager
实现 MultiAgentTerminal 与多智能体工具定义
实现消息路由（inline / idle / 通知池）
实现前端 /multiagent/new 页面
登录页加入口按钮
联调测试

10. 相关文档

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：现有代码分析

9.0 KiB Raw Blame History Unescape Escape