# 多智能体模式总体架构

> 文档状态：设计草案  
> 适用范围：宿主机模式（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`：现有代码分析