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

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

7.7 KiB

Raw Blame History

多智能体模式数据模型

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

---
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）

{
  "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）

{
  "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 保存格式一致。

{
  "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）

{
  "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）

保存精度、时机、格式与主智能体对话完全一致。

{
  "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：

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 中维护会话列表：

{
  "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

7.7 KiB Raw Blame History Unescape Escape