持久化组织

Team 是长期实体而非 ad-hoc session：固定成员、跨 session 累积上下文、可归档转移

策略可配置

每个 Team 独立选择协作模式（fan-out / sequential / lead-driven）、风险阈值、成本预算，不再走全局默认

共享记忆 scope

团队级长期记忆是多 agent 共享上下文的安身之所：跨 Run 沉淀团队经验，避免每次从零开始

详细设计说明

DESIGN DOCUMENT · AGENT TEAMS

用 Team 把"临时协作群"升级为"长期组织单元"

这份文档不讨论 Team 的产品形态，只讨论 Team 在三层架构里要承担的技术职责：作为持久化的协作单元，让多 agent 协作从单次 session 的 ad-hoc 配合，升级为带成员关系、协作策略、共享记忆和治理边界的工程实体。

设计主张

Tier 2 不能只有"协作机制"（fan-out / consolidate）这一面；必须有"协作单元"（Team）作为机制的承载实体。机制是动词，Team 是名词，缺一不可。

Persistent IdentityRole MappingStrategy ConfigShared Memory ScopeLifecycle

评审关注点

Team 与 Org / Persona / GroupSession 的边界
同一 Persona 加入多个 Team 时的角色冲突
团队级策略与全局策略的优先级
共享记忆的 scope 与隐私边界

D1持久化实体不是 ad-hoc session

D2角色 ≠ Persona同 Persona 多 Team 不同角色

D3策略可参数化Team 配置覆盖全局默认

D4记忆 scopeteam_id 是隔离维度

D5权限不放大Team 不是新权限主体

Agent Platform · Agent Teams 协议

状态：v0 草案
日期：2026-05-07
定位：Tier 2 多 Agent 协作机制的承载实体；Tier 1 暴露管理 API；Tier 3 不感知 Team 概念
关联：与 multi-agent-collaboration（协作协议）、memory-context-design（团队记忆 scope）、governance-hitl-design（团队级治理）配套
目标：明确 Team 在三层架构里的技术职责，让"多 agent 协作"从机制升级为可治理、可记忆、可演进的组织单元

1. 定位与概念

SECTION GOAL

一张图看清 Team 是什么、住哪一层、为什么要做、解决什么问题。本章是阅读其余章节的入口。

1.1 总体架构图

下图把 Team 的静态结构（实体关系）与三层定位叠加在一张图上：横向 3 个 tier 带，T1 区画 ER 关系（Org / Team / TeamMember / Persona / AgentSession），T2 区列 Coordinator 用 Team 数据做的 3 件事，T3 区只有一句话——不感知 Team。

关键约束：实线 = 强引用（Org/Team/TeamMember/Persona ER 链） · 虚线 = 软关联或注入（Team↔Session、T1→T2 配置流） · ⊗ = T3 完全屏蔽

1.2 三种典型协作场景时序图

下面 3 张时序图对应 collaboration_strategy 三种取值，分别可视化 Team 在不同业务场景下的不同执行模式。点击顶部导航卡片跳到对应场景，点击 Scenario A 中的 lifeline 头部色块跳到对应章节。

点击下方任意场景卡片跳到对应时序图。

SCENARIO · A fan-out-broadcast 扇出广播一次 @team 同时派给 N 个成员并行执行，Round 2 汇总。最常见。 SCENARIO · B sequential-relay 串行接力 A → B → C 顺序执行，前一位输出作为下一位输入。流水线模式。 SCENARIO · C lead-driven Lead 主导 Lead 拆分子任务后再派给执行者；Lead 收齐后整合输出。

Scenario A · fan-out-broadcast 扇出广播

@team 一次扇出 N 个 Agent 并行执行，结果汇总后回推。点击任意 lifeline 头部色块跳到下方对应章节。

↻ = 同层自循环 · 三色平行箭头 = N 个 child Run 并行扇出 · Tier 3 内核不感知 team，team_id 仅作 caller_extra 透传。

Scenario B · sequential-relay 串行接力

每个成员按 position 顺序执行，前一位的输出作为下一位的输入。没有汇总轮——最后一位的输出即终态。

注意：sequential-relay 没有 Round 2 汇总——链终态直接是最后一个 Run 的输出。中间任意 Run 失败可触发整链熔断。

Scenario C · lead-driven Lead 主导

Lead Run 先跑：拆解子任务 + 派单给 executor。Executor 完成后结果回到 Lead整合，再产出团队最终输出。

关键差异：lead-driven 有"Lead 二次激活"——Lead 先 plan，再在 executor 全部完成后 consolidate。executors 之间无直接通信，全部通过 Lead 收口。

1.3 为什么要做 Team

当前缺口：

缺口	具体表现	影响
每次协作群从零开始	用户每次新建群都要手动加 5-10 个 persona	体验差；高频协作场景重复劳动
协作策略只能全局配置	fan-out-broadcast / sequential 是全局默认；不同业务场景需要不同模式	同一份代码强行覆盖所有场景；调一个全局参数全员受影响
多 agent 不共享上下文	记忆挂在 Persona 上；同组 agent 之间不共享团队级经验	每次群聊都是新人开会；团队级 know-how 没法沉淀
角色与 Persona 强耦合	"架构师老王"既是 Persona ID 又是 Team 内的角色	同一 Persona 不能在 A 团队是 lead、在 B 团队是 reviewer
治理无承载实体	HITL 阈值 / 成本预算只能挂用户级	没法对"研发团队"和"营销团队"差异化治理

Team 解决的具体技术问题：

把 mention 协议从「persona name 列表」升级为「单个 team_id 展开」——降低协作群的初始化成本
把全局协作策略下沉到 team 配置——同一套机制，不同 team 用不同模式
给跨 Run 共享记忆一个隔离维度——team_id 作为 scope key
为治理（HITL / 成本 / 审计）提供聚合实体——团队级 dashboard 而非用户级散点

1.4 三层职责定位

层	承担	不承担
Tier 1 · Agent Platform	Team 实体的 CRUD、邀请 / 退出、归档、所有权转移；前端管理界面；权限校验（用户对 team 的可见性）	不参与运行时协作策略决策
Tier 2 · Runtime	读取 team 配置驱动协作策略选择；@team 展开成 fan-out 列表；记忆 scope 路由；team-aware Coordinator	不存储 team 实体；不暴露 team 管理 API
Tier 3 · Kernel	不感知 Team 概念——单 Run 执行内核保持纯粹	RunContext 里不带 team 字段（如需要由 Tier 2 通过 caller_extra 透传）

关键边界：Team 是 Tier 1 + Tier 2 概念，不向 Tier 3 渗透。Kernel 永远只跑单 Run，不需要知道这个 Run 是不是属于某个 team。Team 的影响力通过 Tier 2 的策略路由 + 记忆 scope 注入到 RunContext，但 RunState 状态机本身不变。

2. 数据模型

SECTION GOAL

列出 Team 引入的最小持久化实体，明确与 Org / Persona / GroupSession 的关系。

2.1 核心实体

Team：协作组织单元，拥有自己的成员、配置、记忆 scope

字段	类型	说明
`id`	uuid	主键
`org_id`	uuid?	所属组织（可空，支持个人 Team）
`owner_user_id`	uuid	所有者；可转移；不可空
`name`	string	团队名（@提及时使用，需在 user / org 范围内唯一）
`tagline`	string	一句话定位（用于群聊 mention 提示）
`collaboration_strategy`	enum	fan-out-broadcast / sequential-relay / lead-driven
`config`	jsonb	team 级配置（超时、最大 round、HITL 阈值、成本预算）
`archived_at`	ts?	归档时间（软删除）

TeamMember：Persona 与 Team 的多对多关联，承载角色定义

字段	类型	说明
`team_id`	uuid	关联 Team
`persona_id`	uuid	关联 AgentPersona
`role`	enum	lead / executor / reviewer / observer
`position`	int	排序权重（影响 sequential-relay 顺序、列表显示）
`added_at`	ts	加入时间
`added_by`	uuid	邀请人

2.2 与现有实体的关系

关系	基数	说明
`Org → Team`	1 : n	一个组织可以有多个 Team；个人 Team 时 org_id = null
`Team → TeamMember`	1 : n	Team 通过 TeamMember 关联多个 Persona
`TeamMember → AgentPersona`	n : 1	同一 Persona 可加入多个 Team
`Team → AgentSession`	1 : n（可选）	`session.team_id` 软关联：基于 Team 创建群聊时把成员一次性导入

关键解耦：

AgentPersona 表本身不动——Persona 是能力载体，Team 是组织载体，两个概念
同一 Persona 可加入多个 Team，每个 Team 内的角色（role）独立
AgentSession 通过 team_id 软关联——基于 Team 创建群时把成员一次性导入 group_agents；后续修改成员仅影响 session 范围，不影响 Team 本身

2.3 Role 语义

Role	含义	对协作策略的影响
`lead`	团队负责人，汇总 / 决策 / 派单	fan-out 后的 consolidation 默认派给 lead；@team 时如未指定个人，先派 lead
`executor`	主力执行	fan-out 列表的主体；接收派单
`reviewer`	审查者	不主动接收派单；可在 consolidation 阶段被自动 @ 加入
`observer`	观察者	看得见消息但不参与执行；用于审计 / 学习场景

3. @team 展开协议

SECTION GOAL

定义 mention parser 在遇到 @team_name 时的展开规则，保证 Tier 2 协作机制不需要为 team 引入新分支。

3.1 展开时机

Tier 2 mention parser 解析消息发现 @xxx 时：

先按 persona name 解析：命中 → 单 persona 派单
未命中再按 team name 解析：命中 → 展开为该 team 的 executor + lead 列表，按各自 persona_id 派单
都未命中 → 忽略

3.2 展开后的派单契约

步骤	动作	载荷
1	用户发送 `@团队A 干个活`	消息文本进入 mention parser
2	按名查找 Team	`team = lookup_by_name("团队A")`
3	展开成员列表	取 `role ∈ {lead, executor}` 的 persona_id 列表
4	选择派单策略	读 `team.collaboration_strategy`（fan-out / sequential / lead-driven）
5	调度 Tier 2 strategy.dispatch	按 team 配置走对应分发逻辑，与单 persona 派单复用同一接口

3.3 命名空间

场景	命名空间	冲突解决
个人 Team（org_id=null）	user 范围内唯一	persona name 优先；user 不允许 team name 撞 persona name
组织 Team	org 范围内唯一	org member 都能 @ 这个 team
persona 与 team 同名	persona 优先	提示用户改 team name 或用更具体的写法（如 `@team:名字`）

4. 协作策略：team 配置覆盖全局

SECTION GOAL

说明 team-scoped 协作配置如何注入到 Tier 2 策略层，让同一套机制服务不同业务场景。

4.1 配置传递路径

层	动作	注入位置
Tier 1	用户 @ team；chat 路由触发任务	把 `team_id` 写入 `Job.input`
Tier 2 · Coordinator	派 child Run 时透传 team 上下文	放入 `caller_extra.team_id`
Tier 2 · Strategy	选择协作策略	读 `team.collaboration_strategy`，未配置则回退全局默认
Tier 2 · Coordinator 状态	读 team 级运行时阈值	`max_agent_round` / `consolidation_required` / `hitl_threshold` / `cost_budget` 都从 `team.config` 读，缺失走全局默认
Tier 3 · Kernel	不感知 team_id	仅作为 caller_extra 透传，进 Trace 但不进 RunState 决策

4.2 可配置项

配置项	类型	默认（无 team 时）	典型 team 覆盖
`collaboration_strategy`	enum	fan-out-broadcast	研发团队用 lead-driven；客服团队用 sequential-relay
`max_agent_round`	int	5	简单团队设 3，复杂团队设 8
`consolidation_required`	bool	true	纯并行团队可关闭汇总轮
`hitl_threshold`	enum	medium	金融业务 team 设 low；内部研发 team 设 high
`cost_budget_per_run`	cents	无	给客户售卖的 team 设上限
`tools_whitelist`	list	用户级	团队级共享技能包，限制可用工具集

4.3 优先级

persona 级 > team 级 > user 级 > system 默认。任何一层缺失值，向上 fallback。

5. 共享记忆 scope（v0.2）

SECTION GOAL

定义 team_memory 的 scope 与隔离规则，让团队级经验沉淀有明确的存储和召回路径。

5.1 现状缺口

当前 AgentMemory 表按 (user_id, persona_id) 隔离。多个 persona 在同一 team 内协作时：

persona A 写的经验不能被 persona B 读到
团队级 know-how（"上次某客户的需求边界"）没有承载实体
跨 session 的团队对话历史没有索引维度

5.2 引入 team_memory

字段	类型	说明
`team_id`	uuid	新增 scope 维度
`persona_id`	uuid?	可空——空则为团队全员可见的共享记忆
`memory_type`	enum	team_lesson / team_decision / team_artifact
`scope_visibility`	enum	team_members（默认）/ team_lead_only
`...其他字段同 AgentMemory`		content / embedding / confidence

5.3 召回规则

当某 persona 在某 team 上下文内执行时，记忆召回的候选集是三类记忆并集，再按向量相似度排序取 top-N：

类	过滤条件	含义
个人记忆	`persona_id = 当前 persona` 且 `team_id IS NULL`	persona 自身的长期记忆，与团队无关
团队共享	`team_id = 当前 team` 且 `scope_visibility = team_members`	团队全员可见的共享经验
当前 persona 在该 team 的记忆	`team_id = 当前 team` 且 `persona_id = 当前 persona`	persona 在这个 team 内累积的角色化经验

三类候选合并后按 embedding 相似度排序，最终取 top-10 注入上下文。

5.4 隐私边界

团队记忆不跨 team泄露——同一 persona 在 A team 写的记忆不能被 B team 召回
团队记忆不跨 user泄露——个人 Team 的记忆只在 owner 范围内可见；组织 Team 仅在 org 成员范围内可见
用户级 OAuth token / PII 仍按用户级隔离，不进入 team_memory

6. 生命周期

SECTION GOAL

列出 Team 的状态流转和操作权限边界。

6.1 状态机

状态	含义	合法转移
`active`	正常态，可读可写	→ `archived`（owner 归档）/ `transferred`（所有权转移）
`archived`	归档态，仅读不可写；前端默认隐藏	→ `active`（30 天内可恢复）
`transferred`	所有权已转移给新 owner	新 owner 接管后回到 `active`

6.2 操作权限

操作	谁可以做
创建 Team	任何用户（个人 Team）；org admin（组织 Team）
添加 / 移除成员	owner、org admin
修改 collaboration_strategy / config	owner、org admin
转移所有权	owner（个人 Team）；org admin（组织 Team）
归档	owner、org admin
恢复归档 Team	owner、org admin（30 天内）
永久删除	不直接暴露；审计要求保留

6.3 持久化策略

归档不删数据：archived_at 置非空，前端默认隐藏；历史 group_session 仍能读到 team 关联用于审计。完整删除需走审计流程。

7. 治理（v0.3+）

SECTION GOAL

列出 v0.1 不做、但架构层要预留的治理能力，避免后续需要破坏性升级。

能力	v0.1 状态	预留
角色权重 / 否决权	不做	`TeamMember.role` 已分四档；权重逻辑后加
团队级 HITL 路由	不做	`Team.config.hitl_threshold` 已预留；策略层需扩展
团队级成本预算	不做	`Team.config.cost_budget_per_run` 已预留；与 budget 服务对接
团队级审计 dashboard	不做	所有相关 trace 已带 `team_id` 字段；dashboard 上层聚合即可
SLA 与质量评分	不做	需要先有真实 team 运行数据再设计

8. 演进路线

SECTION GOAL

把 Team 能力切成可单独验证的版本，按价值优先级落地。

版本	范围	验收
v0.1 MVP	Team / TeamMember 数据模型；CRUD + 邀请 / 移除；@team 展开为 fan-out 列表；前端 Team 管理页	能创建团队、群聊里 @ team 自动展开为 fan-out 给全员
v0.2 策略 + 记忆	collaboration_strategy 配置生效；team-scoped 记忆 scope；记忆召回路径扩展	同一群聊用不同 team 跑出不同协作模式；团队级经验跨 session 沉淀
v0.3 治理	角色权重 / 否决权；团队级 HITL / 成本预算；审计 dashboard	研发 / 营销 / 客服等不同 team 差异化治理
v0.4 跨组织	跨 Org 的协作 Team（联合项目场景）；权限 federate	有真实跨组织合作需求时再做

9. 与现有模块的关系

SECTION GOAL

明确 Team 引入后，已有模块需要的修改点。

模块	修改点
多 Agent 协作协议（multi-agent-collaboration）	CollaborationContext 增加 `team_id` 字段；DelegationTrace 增加 `team_id` 用于团队级聚合
Memory / Context 设计	AgentMemory 表增加 `team_id`；召回逻辑扩展（见 §6）
治理与 HITL 设计	HITL 决策树新增 team 级路由；Policy 引擎读取 team config
可观测与 Replay	所有 RunTrace / DelegationTrace 增加 `team_id`；支持 `WHERE team_id=X` 聚合查询
Skill 版本治理	SkillVersion 可选关联 team_id（团队级共享技能包）

Tier 3 内核不动——RunState / RunContext / ResultSink 都不感知 team；team_id 通过 caller_extra 透传，不进入 RunState 状态机。

Agent Teams 设计

持久化组织

策略可配置

共享记忆 scope

详细设计说明

用 Team 把"临时协作群"升级为"长期组织单元"

设计主张

评审关注点

Agent Platform · Agent Teams 协议

1. 定位与概念

1.1 总体架构图

1.2 三种典型协作场景时序图

1.3 为什么要做 Team

1.4 三层职责定位

2. 数据模型

2.1 核心实体

2.2 与现有实体的关系

2.3 Role 语义

3. @team 展开协议

3.1 展开时机

3.2 展开后的派单契约

3.3 命名空间

4. 协作策略：team 配置覆盖全局

4.1 配置传递路径

4.2 可配置项

4.3 优先级

5. 共享记忆 scope（v0.2）

5.1 现状缺口

5.2 引入 team_memory

5.3 召回规则

5.4 隐私边界

6. 生命周期

6.1 状态机

6.2 操作权限

6.3 持久化策略

7. 治理（v0.3+）

8. 演进路线

9. 与现有模块的关系