305 lines
7.7 KiB
Markdown
305 lines
7.7 KiB
Markdown
# 多智能体模式数据模型
|
||
|
||
> 所有数据存储在 `~/.astrion/astrion/host/mutiagents/` 下，与现有系统完全隔离。
|
||
> 子智能体对话记录的保存精度、时机、格式与主智能体对话记录一致。
|
||
|
||
---
|
||
|
||
## 1. 目录结构
|
||
|
||
```
|
||
~/.astrion/astrion/host/mutiagents/
|
||
├── agents/ # 角色定义
|
||
│ ├── ui-operator.md
|
||
│ ├── full-stack-engineer.md
|
||
│ ├── code-reviewer.md
|
||
│ └── researcher.md
|
||
├── conversations/ # 多智能体会话
|
||
│ └── <conv_id>/
|
||
│ ├── metadata.json # 会话级元数据
|
||
│ ├── messages.json # Team Leader 对话
|
||
│ └── agents/
|
||
│ └── <agent_id>/
|
||
│ ├── metadata.json # 子智能体元数据
|
||
│ └── messages.json # 子智能体完整对话
|
||
└── state.json # 全局状态
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 角色定义（Agent Role）
|
||
|
||
文件路径：`agents/<role_id>.md`
|
||
|
||
格式：YAML Frontmatter + Markdown 正文
|
||
|
||
```markdown
|
||
---
|
||
id: ui-operator
|
||
name: UI Operator
|
||
description: 负责前端设计、UI 还原、配色方案
|
||
model: qwen3-max
|
||
thinking_mode: fast
|
||
---
|
||
|
||
你是团队的前端设计专家...
|
||
```
|
||
|
||
### Frontmatter 字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | string | 是 | 角色唯一标识，文件名也使用此 id |
|
||
| `name` | string | 是 | 角色显示名 |
|
||
| `description` | string | 是 | 角色简短描述 |
|
||
| `model` | string | 否 | 默认模型 key |
|
||
| `thinking_mode` | string | 否 | fast / thinking |
|
||
|
||
### 正文
|
||
|
||
正文部分为角色专属 prompt，会拼接在基础 prompt 之后。
|
||
|
||
---
|
||
|
||
## 3. 全局状态（state.json）
|
||
|
||
```json
|
||
{
|
||
"version": "1.0",
|
||
"last_conversation_id": "conv_xxx",
|
||
"agent_id_counter": 5,
|
||
"created_at": "2026-07-11T21:00:00",
|
||
"updated_at": "2026-07-11T21:30:00"
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `version` | 数据格式版本 |
|
||
| `last_conversation_id` | 最近一次会话 id |
|
||
| `agent_id_counter` | 全局实例编号计数器（可选） |
|
||
|
||
---
|
||
|
||
## 4. 会话元数据（metadata.json）
|
||
|
||
```json
|
||
{
|
||
"id": "conv_20260711_210000_001",
|
||
"title": "多智能体任务：设计前端",
|
||
"created_at": "2026-07-11T21:00:00",
|
||
"updated_at": "2026-07-11T21:30:00",
|
||
"project_path": "/Users/jojo/project",
|
||
"model_key": "qwen3-max",
|
||
"thinking_mode": true,
|
||
"run_mode": "thinking",
|
||
"status": "active",
|
||
"agent_count": 3,
|
||
"agent_ids": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `id` | 会话 id |
|
||
| `title` | 会话标题 |
|
||
| `created_at` | 创建时间 |
|
||
| `updated_at` | 更新时间 |
|
||
| `project_path` | 关联项目路径 |
|
||
| `model_key` | Team Leader 使用的模型 |
|
||
| `thinking_mode` | 是否思考模式 |
|
||
| `run_mode` | fast / thinking / deep |
|
||
| `status` | active / archived |
|
||
| `agent_count` | 当前子智能体数量 |
|
||
| `agent_ids` | 当前子智能体 agent_id 列表 |
|
||
|
||
---
|
||
|
||
## 5. 主智能体对话（messages.json）
|
||
|
||
与现有 `ConversationManager` 保存格式一致。
|
||
|
||
```json
|
||
{
|
||
"id": "conv_20260711_210000_001",
|
||
"title": "多智能体任务：设计前端",
|
||
"created_at": "2026-07-11T21:00:00",
|
||
"updated_at": "2026-07-11T21:30:00",
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "帮我设计一个前端页面",
|
||
"message_id": "msg_user_001",
|
||
"metadata": {
|
||
"message_source": "user",
|
||
"visibility": "chat",
|
||
"starts_work": true
|
||
}
|
||
},
|
||
{
|
||
"role": "assistant",
|
||
"content": "我来安排 UI Operator 处理这个任务...",
|
||
"message_id": "msg_assistant_001",
|
||
"tool_calls": [...]
|
||
},
|
||
{
|
||
"role": "user",
|
||
"content": "来自 UI Operator_1 的任务完成汇报\nid: out_uio_001\n\n<UI Operator_1>\n<Output>\n我完成了前端配色的设计...\n</Output>\n</UI Operator_1>",
|
||
"message_id": "msg_auto_001",
|
||
"metadata": {
|
||
"message_source": "sub_agent",
|
||
"visibility": "compact",
|
||
"starts_work": false,
|
||
"agent_id": 1
|
||
}
|
||
}
|
||
],
|
||
"metadata": { ... },
|
||
"token_statistics": { ... }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 子智能体元数据（agents/<agent_id>/metadata.json）
|
||
|
||
```json
|
||
{
|
||
"agent_id": 1,
|
||
"role_id": "ui-operator",
|
||
"display_name": "UI Operator_1",
|
||
"status": "running",
|
||
"created_at": "2026-07-11T21:05:00",
|
||
"updated_at": "2026-07-11T21:15:00",
|
||
"task_summary": "设计前端配色方案",
|
||
"model_key": "qwen3-max",
|
||
"thinking_mode": "fast",
|
||
"pending_messages": [
|
||
{
|
||
"id": "msg_tl_001",
|
||
"source_display_name": "Team Leader",
|
||
"source_agent_id": null,
|
||
"message_type": "message",
|
||
"content": "先不要创建 API...",
|
||
"created_at": 1752251700.0
|
||
}
|
||
],
|
||
"pending_tool_calls": [
|
||
{
|
||
"tool_call_id": "tc_ask_001",
|
||
"tool_name": "ask_master",
|
||
"question_id": "ask_uio_001",
|
||
"created_at": 1752251800.0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `agent_id` | 实例编号 |
|
||
| `role_id` | 角色 id |
|
||
| `display_name` | 显示名 |
|
||
| `status` | running / waiting / idle / completed / terminated |
|
||
| `task_summary` | 当前任务摘要 |
|
||
| `pending_messages` | 待处理消息队列 |
|
||
| `pending_tool_calls` | 正在等待回答的工具调用 |
|
||
|
||
---
|
||
|
||
## 7. 子智能体对话（agents/<agent_id>/messages.json）
|
||
|
||
保存精度、时机、格式与主智能体对话完全一致。
|
||
|
||
```json
|
||
{
|
||
"agent_id": 1,
|
||
"role_id": "ui-operator",
|
||
"display_name": "UI Operator_1",
|
||
"created_at": "2026-07-11T21:05:00",
|
||
"updated_at": "2026-07-11T21:15:00",
|
||
"messages": [
|
||
{
|
||
"role": "system",
|
||
"content": "你是智能体集群团队的一员..."
|
||
},
|
||
{
|
||
"role": "user",
|
||
"content": "来自 Team Leader 的任务发布\nid: task_001\n\n<Team Leader>\n<Task>\n请为项目设计前端配色方案...\n</Task>\n</Team Leader>",
|
||
"message_id": "msg_user_001"
|
||
},
|
||
{
|
||
"role": "assistant",
|
||
"content": "我先分析一下现有设计风格...",
|
||
"message_id": "msg_assistant_001"
|
||
},
|
||
{
|
||
"role": "user",
|
||
"content": "来自 Team Leader 的消息\nid: msg_tl_001\n\n<Team Leader>\n<Message>\n先不要创建 API...\n</Message>\n</Team Leader>",
|
||
"message_id": "msg_user_002"
|
||
},
|
||
{
|
||
"role": "assistant",
|
||
"content": "好的，我先确认现有 auth 模块...",
|
||
"message_id": "msg_assistant_002"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 持久化策略
|
||
|
||
### 8.1 保存时机
|
||
|
||
- 每次模型调用前保存子智能体 metadata 和 messages
|
||
- 每次工具调用后保存
|
||
- 每次状态变更时保存
|
||
- 每次收到外部消息并处理后保存
|
||
|
||
### 8.2 原子写入
|
||
|
||
参考 `ConversationManager._atomic_write_json`，使用临时文件 + replace：
|
||
|
||
```python
|
||
def _atomic_write_json(path: Path, data: dict):
|
||
tmp = path.with_suffix(path.suffix + ".tmp")
|
||
tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
|
||
tmp.replace(path)
|
||
```
|
||
|
||
### 8.3 索引
|
||
|
||
参考 `ConversationManager` 的索引机制，在 `conversations/index.json` 中维护会话列表：
|
||
|
||
```json
|
||
{
|
||
"conv_20260711_210000_001": {
|
||
"title": "多智能体任务：设计前端",
|
||
"created_at": "2026-07-11T21:00:00",
|
||
"updated_at": "2026-07-11T21:30:00",
|
||
"agent_count": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 与现有 ConversationManager 的关系
|
||
|
||
多智能体模式实现自己的 `MultiAgentConversationStore`，但：
|
||
|
||
- 数据格式与 `ConversationManager` 保持一致
|
||
- 文件结构与 `ConversationManager` 类似
|
||
- 不修改 `utils/conversation_manager/` 任何文件
|
||
- 可以复制 `ConversationManager` 的 CRUD 代码到 `MultiAgentConversationStore`
|
||
|
||
---
|
||
|
||
## 10. 实现位置
|
||
|
||
- 角色存储：`modules/multi_agent/agent_store.py`
|
||
- 会话存储：`modules/multi_agent/conversation_store.py`
|
||
- 全局状态：`modules/multi_agent/manager.py`
|