# 多智能体模式数据模型

> 所有数据存储在 `~/.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`
