228 lines
9.0 KiB
Markdown
228 lines
9.0 KiB
Markdown
# 多智能体模式总体架构
|
||
|
||
> 文档状态：设计草案
|
||
> 适用范围：宿主机模式（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`：
|
||
|
||
```markdown
|
||
---
|
||
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. 子智能体职责
|
||
|
||
子智能体系统提示词由两部分组成：
|
||
|
||
1. **基础 prompt**：通用团队规则
|
||
2. **自定义 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）
|
||
|
||
1. 创建独立目录与数据存储结构
|
||
2. 实现角色配置加载与预置角色
|
||
3. 实现 `MultiAgentSubAgentTask` / `MultiAgentSubAgentManager`
|
||
4. 实现 `MultiAgentTerminal` 与多智能体工具定义
|
||
5. 实现消息路由（inline / idle / 通知池）
|
||
6. 实现前端 `/multiagent/new` 页面
|
||
7. 登录页加入口按钮
|
||
8. 联调测试
|
||
|
||
---
|
||
|
||
## 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`：现有代码分析
|