AstroResearch/docs/architecture/agent/team.md

多 Agent 团队 (team/)

基于文件邮箱 (file inbox) 的轻量级多 Agent 协作系统，参考 Claude Code Agent Teams 设计。

架构总览

graph LR
    subgraph Team["src/agent/team/"]
        direction TB
        Mod["mod.rs (11 lines)<br/>模块声明与重导出"]
        Config["config.rs (53 lines)<br/>TeamConfig, MemberConfig, MemberStatus"]
        Inbox["inbox.rs (110 lines)<br/>文件邮箱 (append-only JSONL + drain)"]
        Manager["manager.rs (205 lines)<br/>spawn/stop/send/broadcast/check_inbox/list"]
        Teammate["teammate.rs (270 lines)<br/>队友 ReAct 循环<br/>(idle poll → react turn → report result)"]
    end

    Tools["src/agent/tools/team.rs (292 lines)<br/>4 个团队工具暴露给 Lead Agent"]
    
    Manager --> Tools
    Teammate --> Manager
    Inbox --> Manager
    Inbox --> Teammate

graph TD
    subgraph Lead["Lead Agent (AgentRuntime)"]
        LR["ReAct Loop"]
        TR["ToolRegistry"]
    end

    subgraph TM["TeamManager"]
        Config["TeamConfig<br/>session_id + members[]"]
        Handles["HashMap&lt;name, TeamMemberHandle&gt;"]
    end

    subgraph InboxFS[".team/{session_id}/inbox/"]
        L["lead.jsonl"]
        S["searcher.jsonl"]
        R["reader.jsonl"]
    end

    subgraph Teammates["Teammates (tokio::spawn)"]
        T1["searcher<br/>ReAct loop<br/>max 5 steps"]
        T2["reader<br/>ReAct loop<br/>max 5 steps"]
    end

    LR -->|"spawn_teammate"| TM
    LR -->|"send_teammate_message"| S
    LR -->|"check_team_inbox"| L
    LR -->|"team_broadcast"| S
    LR -->|"team_broadcast"| R

    TM -->|"tokio::spawn"| T1
    TM -->|"tokio::spawn"| T2

    T1 -->|"append result"| L
    T2 -->|"append result"| L
    T1 -->|"drain inbox"| S
    T2 -->|"drain inbox"| R

通信机制：文件邮箱

消息传递不通过 channel 或共享内存，而是通过 append-only JSONL 文件：

.team/{session_id}/inbox/
├── lead.jsonl       ← 队友将结果写入此处
├── searcher.jsonl   ← Lead 将任务写入此处
└── reader.jsonl     ← Lead 将任务写入此处

消息类型 (TeamMessage)

字段	类型	说明
from	String	发送者名称
to	String	接收者名称
content	String	消息内容
msg_type	TeamMessageType	task / result / question / answer / status
timestamp	String	ISO 8601 时间戳 (UTC)

核心操作

• append_message(team_dir, agent_name, msg)：追加一行 JSON 到接收者文件，自动创建目录
• drain_inbox(team_dir, agent_name)：读取所有消息行 → 清空文件 → 返回 Vec（破坏性读取）
• has_pending(team_dir, agent_name)：检查文件是否存在且非空（用于快速轮询）

已知问题：drain_inbox() 在 read_to_string 和 write("") 之间存在 TOCTOU 竞态条件。若清空前有新消息追入，该消息会丢失。生产环境应使用 advisory file lock 或原子 rename 替代。

队友生命周期

  ┌──────────┐
  │ SPAWNING │  ← Manager 创建句柄，tokio::spawn 启动循环
  └────┬─────┘
       ▼
  ┌──────────┐   有新消息到达     ┌──────────┐
  │  IDLE    │ ─────────────────→ │ WORKING  │
  │          │ ←──────────────── │          │
  │ 5s×12   │   任务完成/超时    │ ReAct    │
  │ 轮询     │                    │ max 5步  │
  └────┬─────┘                    └──────────┘
       │ 收到取消信号
       ▼
  ┌──────────┐
  │ SHUTDOWN │  ← 发送告别 Status 消息给 Lead，退出循环
  └──────────┘

IDLE 阶段细节 (teammate.rs:68-92)

1. 设置状态为 Idle
2. drain_inbox() 检查是否有待处理消息
3. 若为空：以 5 秒间隔轮询 has_pending()，最长 60 秒（12 次 × 5 秒）
4. 在轮询中，若 cancelled 标志被设置或 has_pending() 返回 true，则提前退出
5. 超时无消息 → 回到步骤 2
6. 有新消息 → 进入 WORKING

WORKING 阶段细节 (teammate.rs:103-152)

1. 设置状态为 Working
2. 将收件箱消息作为 user 角色消息注入到队友的对话历史中
3. 调用 run_teammate_react_turn()：最多 5 步的简化 ReAct 循环
4. 若返回结果 → 封装为 TeamMessageType::Result 发送到 lead 的收件箱
5. 若返回 None（错误/超时）→ 静默回到 IDLE（不通知 Lead 出错）

队友 ReAct 循环 vs 主 Agent 循环

特性	主 Agent (Lead)	队友 (Teammate)
最大步数	8（可配置）	5（硬编码 min(config.max_steps, 5)）
流式输出	SSE 实时推送到前端	无 SSE，静默消费
工具注册表	完整（含 subagent、team 工具）	排除了 subagent 和 team 工具
上下文压缩	四层压缩 + CircuitBreaker	简单 token 估算 + compact::compress_context
Hooks	PreToolUse / PostToolUse / Stop	无
权限检查	PermissionChecker	无
数据库持久化	agent_messages 表	无
后台通知	BgNotificationQueue	有 Queue 但未使用
Skills	两层加载 (list + load_skill)	无，skill_registry 仅用于工具构造

队友的工具注册表构造 (teammate.rs:40-41)：

let tool_registry =
    ToolRegistry::new_with_queue(Some(queue.clone()), app_state.skill_registry.clone());

ToolRegistry::new_with_queue() 不注册 subagent 和 team 工具，防止无限委托链。

TeamManager 设计

锁顺序约定 (CRITICAL)

存在两个 tokio::sync::Mutex 的嵌套获取：

1. TeamManager.handles（外层）
2. TeamMemberHandle.status（内层）

所有代码必须遵守 handles → status 的顺序，否则死锁。list_members() 作为正确顺序的参考实现。

主要操作

操作	说明	锁行为
spawn(name, role)	tokio::spawn 队友循环，注册句柄	获取 handles 锁
stop(name)	设置 cancelled 标志	获取 handles 锁
stop_all()	停止所有队友	获取 handles 锁
send_message(from, to, content, type)	追加消息到接收者收件箱文件	无锁（纯文件 I/O）
broadcast(from, content)	向 config.members 中所有非发送者成员追加消息	无锁（纯文件 I/O）
check_inbox(agent_name)	drain_inbox 并返回消息	无锁（纯文件 I/O）
list_members()	获取所有队友的 (name, role, status)	handles → 各 status（正确顺序）

队友系统提示词 (manager.rs:70-93)

队友收到的是天体物理学研究助手角色设定 + 工具使用指引 + 通信协议说明。系统提示词始终通过 build_teammate_system_prompt(role) 生成，不使用 MemberConfig.system_prompt 字段。

4 个团队工具

工具定义在 src/agent/tools/team.rs，均设置 InterruptBehavior::Block（中断时先完成副作用再停止）。P3 工具分类注解已应用：

工具名	参数	功能	接收者	延迟加载	只读
spawn_teammate	name, role	启动一个后台队友	—	✅ defer_loading	—
send_teammate_message	to, content	向指定队友发送消息	队友收件箱	✅ defer_loading	—
team_broadcast	content	向所有队友广播消息	所有队友收件箱	✅ defer_loading	—
check_team_inbox	agent_name? (默认 "lead")	读取并清空收件箱	Lead 收件箱	—	✅ is_readonly

延迟加载说明（P3）：spawn_teammate、send_teammate_message、team_broadcast 标记为 defer_loading=true，不随常驻工具注入 system prompt，仅当 LLM 判断需要多 Agent 协作时通过 tool_catalog 按需加载。check_team_inbox 标记为 is_readonly=true（只读取文件邮箱，不修改队友状态），在 auto 模式下可跳过权限确认。

典型协作流程：

1. Lead 调用 spawn_teammate(name="searcher", role="ADS文献搜索专家")
2. Lead 调用 send_teammate_message(to="searcher", content="搜索2024年暗物质间接探测综述")
3. Lead 继续自己的 ReAct 循环（可以同时发起另一个 spawn_teammate）
4. 队友在后台执行 ReAct 循环（最多5步），完成后将结果写入 lead.jsonl
5. Lead 调用 check_team_inbox() 读取队友结果
6. Lead 综合队友结果，给出最终回答

与子代理 (subagent) 的对比

代码库中存在两种委托机制，适用不同场景：

	子代理 (subagent)	团队 (team)
执行模式	同步：Lead 等待完成	异步：后台运行，Lead 主动轮询
并发度	每次调用 1 个	可同时运行多个队友
上下文	任务完成后丢弃	跨任务累积（直到压缩）
通信方式	工具调用 → 返回摘要	文件邮箱：写入/轮询
Hooks	PreToolUse / PostToolUse / SubagentStart / SubagentStop	无
权限检查	PermissionChecker	无
进度透传	SSE 事件到父代理	无
DB 持久化	agent_messages 表	无
适用场景	"去完成这个子任务，给我摘要"	"留在后台，持续处理我分配的任务"

当前状态：未接入

重要：TeamManager 和 4 个团队工具已完整实现，但当前未接入 AgentRuntime。

AgentRuntime::new() 调用 ToolRegistry::new_with_queue()，而非 ToolRegistry::new_with_team()。团队工具通过独立的 add_team_tools() 函数接入，但该函数在当前代码路径中从未被调用。

实际可用的委托功能由 subagent 工具提供（通过 SubAgentTool 已接入）。

接入方法：在 AgentRuntime::new() 和 with_config() 中，创建 TeamManager 实例并用 ToolRegistry::new_with_team() 替代 new_with_queue()。

改进建议

1. 修复 drain_inbox 竞态条件：使用 advisory file lock 或原子 rename
2. 队友错误传播：run_teammate_react_turn() 返回 None 时应通知 Lead
3. 消息关联 ID：添加 correlation_id 字段，支持请求-响应匹配
4. 降低锁持有时间：将 send_message / broadcast 的文件 I/O 移出锁临界区（当前已是无锁，但工具层仍持有 team_manager 锁）
5. 队友名称去重：spawn 同名队友前检查是否已有活跃队友
6. 会话级清理：Agent 会话结束时调用 stop_all() 清理队友和收件箱文件