Agent Teams 设计文档 (L1330)¶

状态: MVP 已交付 (2026-04-16, 5 commits) TODO.md 对应条目: L1330 engine/team.go + inbox/ - 接线 Agent Teams 模式 Anthropic 对标: Claude Code Agent Teams v2.1.32 (2026-02-05 研究预览版)

目标¶

让 Flyto 引擎支持多 Agent 之间的 peer-to-peer 通讯 和 共享任务清单 协作, 实现 Anthropic Claude Code Agent Teams 研究预览中的核心能力, 但不照搬其研究阶段保守决策, 坚持"领域无关 Agent 引擎"定位.

架构总览¶

                        ┌────────────────────────┐
                        │   engine.Team (协调者)   │
                        │  router / TaskList     │
                        └────────────┬───────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    │                │                │
                    ▼                ▼                ▼
          ┌───────────────┐  ┌───────────────┐ ┌───────────────┐
          │ Leader Engine │  │  Worker A     │ │  Worker B     │
          │ incomingInbox │  │  SubAgent     │ │  SubAgent     │
          │   = "leader"  │  │  inbox.ID=A   │ │  inbox.ID=B   │
          └──────┬────────┘  └──────┬────────┘ └──────┬────────┘
                 │                  │                 │
                 └────── router ────┴──── messages ───┘
                              (inbox.Router)

       共享任务清单:
       ┌─────────────────────────────────────────────────────┐
       │ tasklist.TaskList (业务层: Add/Claim/Complete 状态机) │
       │         ↓                                            │
       │ tasklist.Store (存储层, 多实现)                       │
       │   - MemoryStore   (默认, 零外部依赖)                  │
       │   - MarkdownStore (Anthropic Claude Code 互操作)      │
       │   - CustomStore   (消费层: DB / Redis / WMS / HIPAA)  │
       └─────────────────────────────────────────────────────┘

决策对照表 (vs. Anthropic Claude Code v2.1.32)¶

Anthropic 特性	Flyto 决策	原因
Mailbox 消息格式 (from/to/type/content)	保留	原生 `inbox.Message` 字段逐项对应 (`Router.Send ↔ SendMessage`), 通用模式, 跨行业中立
Teammates 独立 context window	保留	SubAgent 已有独立 context, 金融/医疗场景天然需要隔离
shared task list (markdown 文件)	升华: 抽象成 Store 接口, Markdown 是默认实现之一	Markdown 本身通用 (Notion/Confluence/法律草稿也用); 但 file locking + 硬编码路径对医疗 HIPAA / 金融审计有害. 接口化后编程客户互操作 Anthropic, 合规行业换 Store 实现
TaskCreated / TaskCompleted / TeammateIdle hooks (shell)	升华: 复用 `flyto.EventObserver` 统一事件总线	Observer 是 hook 的真超集 (可跑 shell 也可跑 Go 逻辑 / 审计 DB / Slack 通知); 新增 hook 系统等于架构回退 L1326 收敛
`send_message` mailbox 原语	升华: 作为内置工具 (非"让模型学着写文件到 mailbox 目录")	模型 tool calling 原生支持; Qwen / MiniMax / Gemini 都能直接用, 不依赖模型理解文件系统
消息 ID (UUID)	升华: 纳秒时间戳 + 4 字节随机 hex	时间戳前缀自带时序, 调试日志一眼排序; 金融审计场景天然需要时序
`FLYTO_EXPERIMENTAL_AGENT_TEAMS=1` env flag	拒绝	Anthropic 研究阶段保守; Flyto 不假设运维场景 (医院 IT / 银行运维不会 ssh 改 env)
`no nested teams / lead fixed / no session resumption` 限制	拒绝	研究阶段保守决策; 供应链 "总装→子装→零件" / 大型组织 "部门→小组" 天然嵌套; 照抄等于主动砍掉企业场景
三个独立 shell hook	拒绝	和"升华 Observer"重复, 避免两套 hook 系统并存
File locking 作为唯一并发原语	拒绝 (作为唯一)	Markdown 实现用 flock, 但 Store 接口允许 DB 事务 / Redis MULTI 等

核心 API¶

Engine 级别¶

type Config struct {
    // ...
    AgentName     string      // 此 Engine 的身份名 ("" = 不参与 Teams)
    IncomingInbox inbox.Inbox // peer 消息收件入口 ("" = 不参与)
}

type Engine struct {
    // 内部字段:
    agentName     string
    incomingInbox inbox.Inbox
}

Engine.runLoop 每轮开始 Poll incomingInbox, 收到的消息包装成 <teammate-message> XML 注入对话流, 同时发 TeammateMessageReceivedEvent 给 Observer.

Team 级别¶

type TeamConfig struct {
    LeaderEngine      *Engine
    PermissionHandler PermissionHandler
    SharedTaskList    *tasklist.TaskList // 可选, 共享任务板
}

func NewTeam(cfg TeamConfig) *Team {
    // 自动布线 Leader.incomingInbox = router.Inbox("leader")
    // 自动设置 Leader.agentName = "leader" (如未设置)
}

// 把发件身份注入 ctx, Leader Engine.Run(ctx, ...) 后可用 send_message 工具
func (t *Team) ContextForLeader(ctx context.Context) context.Context

内置工具¶

工具	用途	权限默认
`send_message`	Worker/Leader 向同伴投递消息	AutoApprove (Team 内信任)
`add_shared_task`	发布新任务到共享清单	AutoApprove
`list_shared_tasks`	查看当前任务板 (可按 status 过滤)	ReadOnly
`claim_shared_task`	认领 Pending 任务	AutoApprove
`complete_shared_task`	标记任务完成附结果	AutoApprove

非 Team 场景 (ctx 无 sender/provider) 调用这些工具返回错误, 对 SDK 零副作用.

使用示例¶

最简场景: peer-to-peer 对话¶

team := engine.NewTeam(engine.TeamConfig{
    LeaderEngine: leaderEngine,
})
ctx := team.ContextForLeader(context.Background())
ch := leaderEngine.Run(ctx, "和 reviewer-agent 讨论这段代码")

Leader 在对话中可调 send_message(to="reviewer", content="..."), 消息送达 reviewer 的 incomingInbox, reviewer 下一轮对话自然读到.

带共享任务清单¶

store := tasklist.NewMarkdownStore("/tmp/team-tasks.md")
list := tasklist.New(store)
defer list.Close()

team := engine.NewTeam(engine.TeamConfig{
    LeaderEngine:   leaderEngine,
    SharedTaskList: list,
})
ctx := team.ContextForLeader(context.Background())

// Leader 可调 add_shared_task / list_shared_tasks /
// claim_shared_task / complete_shared_task

跨行业: 自定义 Store¶

// 金融合规场景
import "mycorp/storage/audit"

auditStore := audit.NewPostgresTaskStore(db)
list := tasklist.New(auditStore)

team := engine.NewTeam(engine.TeamConfig{
    LeaderEngine:   leaderEngine,
    SharedTaskList: list,
})

只要 audit.NewPostgresTaskStore 实现 tasklist.Store 接口四方法 (Get/CAS/List/Close), 引擎层零改动.

跨行业场景三例¶

金融 (风控会审)¶

Leader: "评估 AAPL 买入 10000 股, 价 $180"
  ↓ send_message to=risk-analyst
risk-analyst: "VaR=2.3%, 超过 2% 阈值, 建议拒绝"
  ↓ send_message to=compliance
compliance: "合规合规, 仅反转风险; 建议降至 5000 股重测"
  ↓ 回报 Leader
Leader: 调整建议, add_shared_task 记录决策供审计

Store 选择: CustomStore 连 PostgreSQL audit_trades 表.

医疗 (会诊)¶

Primary-doctor: "患者 X 胸痛, 心电图 ST 段抬高"
  ↓ send_message to=cardiologist
cardiologist: "急性心梗可能, 建议立即冠脉造影"
  ↓ send_message to=pharmacist
pharmacist: "患者对阿司匹林过敏, 换氯吡格雷"
  ↓ add_shared_task "冠脉造影 + 氯吡格雷准备"

Store 选择: CustomStore 连 HIPAA 加密存储.

仓储 (波次调度)¶

Dispatcher: list_shared_tasks (status=pending)
  → 找到 "波次 W2026-01-001 待分配"
  claim_shared_task
  ↓ send_message to=picker-03
picker-03: 完成拣货, complete_shared_task (result=货物已集结)
  ↓ Dispatcher 看到, 启动下一波次

Store 选择: CustomStore 连 WMS DB (波次表集成).

运行示例¶

cd core/
go run ./examples/agent_teams/debate            # peer-to-peer 辩论
go run ./examples/agent_teams/tasklist_markdown # Anthropic 互操作
go run ./examples/agent_teams/tasklist_custom   # 跨行业接入模板

竞品对比 (LangGraph / CrewAI / AutoGen / Anthropic 等)¶

详见配套文档 agent_teams_competitive.md, 含: - 7 大主流方案核心维度对比表 - Flyto vs Anthropic 优缺点细节 - Flyto vs LangGraph / CrewAI 真正生态对手分析 - 跨行业通用性评分 (Flyto 综合 5 星) - 销售 / onboarding 话术参考

测试覆盖¶

pkg/inbox/*_test.go: 原 P0 覆盖 (message / router / memory / uds)
pkg/tasklist/tasklist_test.go: 业务层 + MemoryStore, 含并发 Claim 争抢
pkg/tasklist/markdown_store_test.go: MarkdownStore, 含跨实例持久化 / round-trip / 并发 flock / 手写格式导入

所有测试 go test ./... 在 C5 交付时为绿.

迁移指南 (Anthropic Claude Code → Flyto)¶

Anthropic Claude Code	Flyto 对应
`~/.claude/teams/{name}/tasks.md`	`tasklist.NewMarkdownStore(path)`
`TeammateIdle` shell hook	`Observer.Event("teammate_idle", ...)` 订阅
`FLYTO_EXPERIMENTAL_AGENT_TEAMS=1`	不需要 (默认启用)
`claude code teams create` CLI	`engine.NewTeam(TeamConfig{...})`

将来扩展 (等真实客户需求驱动, 不预先设计)¶

fsnotify.Watcher 实时监听 tasks.md 变化 (当前 Store 接口无 Watch 方法, 未阻塞 MVP)
Cross-machine Agent Teams (通过 Redis/NATS Inbox 实现, MemoryInbox 是接口之一)
Self-claim 重入策略 (失败任务如何允许别的 Worker 重试)
Task 嵌套 (parent/child 关系)
优先级 / 截止时间字段

历史背景¶

2026-02-05: Anthropic 发布 Claude Code Agent Teams research preview
2026-04-14: Flyto session 发现 engine.Team.router 字段构造但未使用, 初判 dead code 建议删除; 后经核实是前一棒工程师的"前瞻性预留", 路径订正后登记 P2 接线 TODO.
2026-04-16: L1330 MVP 交付 (本文档涵盖的 5 个 commit):
C1 f7f75a3 耳朵+嘴巴 (Engine incoming inbox + send_message 工具)
C2 2928316 TaskList 业务层 + MemoryStore + 4 工具
C3 b573019 MarkdownStore + Anthropic 兼容测试
C4 1318b37 三个跨行业 example
C5 (本 commit) 文档 + TODO 对账