# Team 规格 > Canonical path: `specs/collaboration/team.md` > Status: living-spec > Scope: AgentTeam 中可被提及、可被委托、可作为协作主体引用的 Team 产品模型。 ## 1. 目标 Team 是 AgentTeam 中由已有 agent 成员及其 Team 本地职责配置组成的集体协作主体。Team 拥有稳定身份、agent 成员集合、Team Description，以及每个 agent 成员在 Team 中的 Role Overlay。 Team 可在 channel、reply thread、DM、task scope 与其他支持 mention 的协作面中被提及。Team mention 解析为当前协作面中的标准 mention，并按 Team 成员展开为标准消息投递。投递给 agent 成员时，AgentTeam 在标准消息投递上下文中附加 Team Context，使 agent 以 Team 成员身份理解和处理同一条原始消息。 Team 提供以下核心能力： - 以稳定 handle 表达一个可提及的集体主体。 - 维护 Team 成员与成员在 Team 中的角色定位。 - 为 agent 成员注入 Team Description 与 TeamMember Role Overlay。 - 让 Team 成员在原协作面中围绕同一请求讨论、补充、分工与执行。 - 支持 Team 被相关系统以 actor reference 引用；具体合同由对应 spec 定义。 ## 2. 核心概念 ### 2.1 Team Team 是 workspace 内的命名协作主体。普通 Team 只对创建者可见、可提及、可编辑和可删除；workspace owner/admin 不拥有普通 Team 的发现或管理旁路。Team 对用户只暴露一个名称；该名称同时作为 Team 的 mention handle 与唯一可见标识，并包含一个成员集合。Team 可作为请求接收方，也可被相关系统以 actor reference 引用；具体合同由对应 spec 定义。 ### 2.2 Team Member Team Member 是 Team 中的一个 agent 成员单元。它可以来自模板成员行的复制结果，也可以在 Team 中手动添加；成员绑定连接一个 workspace agent 与该 agent 在 Team 中的职责配置。 Team Member 记录以下信息： - agent actor 引用。 - 成员类型；当前产品模型中固定为 `agent`。 - 成员显示顺序。 - 成员角色；当前只有 `leader` 与 `member`。 - 成员角色标签。 - agent 成员角色覆盖提示。 - `@Team` 时是否作为默认响应成员被自动唤醒。 Team 成员角色是 Team 本地协作语义，不是 agent canonical Role。添加、编辑或移除 Team 成员不得隐式创建 agent、不得执行 Role apply/rebind，也不得修改该 agent 当前的 canonical Role。 一个 active Team 必须至少保留一个 active agent 成员，必须且只能有一个 `leader`，并且必须至少有一个 `wake_on_team_mention=true` 的成员。创建、模板实例化，以及通过 Team 成员管理执行的成员添加、更新和移除，持久化后都必须满足这些约束；空 Team 不允许通过 Team 管理路径产生。 删除 agent 是独立的实体生命周期操作。删除 agent 时，AgentTeam 在同一事务中通过 `removed_at` 软移除该 agent 的全部 active TeamMember 绑定并释放 active 唯一键；该清理不受上述 Team 管理约束阻挡。TeamMember 历史行、绑定的 member 身份以及既有消息、任务、审批和投递中的历史引用继续保留。 ### 2.3 Team Description Team Description 是 Team 级协作提示。它是一段由 Team 管理者维护的完整 prompt 文本，描述 Team 的职责范围、协作方式与对外风格。 Team Description 会在 Team Context 中提供给 agent 成员。 ### 2.4 TeamMember Role Overlay TeamMember Role Overlay 是 agent 成员在某个 Team 中的角色覆盖提示。它是一段由 Team 管理者维护的 prompt 文本，描述该 agent 在该 Team 中的角色定位与贡献角度。 同一个 agent 可以在不同 Team 中拥有不同 Role Overlay。 ### 2.5 Team Context Team Context 是附加到标准消息投递上下文中的团队身份上下文。它由 Team mention 解析产生，并随同原始消息投递给 Team 的 agent 成员。 Team Context 包含 Team 身份、Team Description、当前 agent 成员的结构化 Team role、Role Overlay、角色标签与本次协作成员列表。 ### 2.6 本次协作成员列表 本次协作成员列表是 Team mention 展开后注入 Team Context 的成员快照。列表来自当前协作面可见、可参与本次请求的 Team 成员集合；首轮唤醒其中 `wake_on_team_mention=true` 的成员。 列表项包含稳定 TeamMember id、成员 actor kind、显示身份、mention handle、结构化 Team role、成员角色标签与参与方式。稳定 TeamMember id 只存在于隐藏的 agent-facing Team Context，用于需要引用完整 Team roster 的工具调用；不得复制到可见消息。Agent 成员可据此理解同一请求中还有哪些 Team 成员参与、各自角色是什么，以及当前 agent 在列表中的位置。 ### 2.7 Team-member Mode Team-member Mode 是 agent 成员处理带有 Team Context 的消息时的运行身份模式。进入 Team-member Mode 的 agent 同时获得自身基础身份、Team Description、TeamMember Role Overlay、本次协作成员列表与当前消息上下文。 ### 2.8 Team Template Team Template 是用于沉淀 Team 分工建议的蓝图，不是真实 Team，也不能被 mention。模板可以来自内置模板，也可以由用户保存自定义模板。自定义模板有 `private` 与 `workspace` 两种可见范围：private 模板仅创建者可见/可用；workspace 模板对 workspace 成员可见/可用。 模板包含 Team 分工草稿和 agent 成员行：Team 名称建议、description，以及每个成员行的 `leader`/`member` 角色、成员标签、agent 成员 Role Overlay 与响应方式。主 UI 不在创建 Team 的必填路径展示模板选择，也不在 Team settings 展示保存/分享模板入口；模板作为 Team channel 中成员职责未分配时的分工建议来源，由 leader 通过 approval 流程确认后落到真实 Team 成员配置。模板流程不会创建新 agent，不会保留未绑定成员行，也不会执行自动兼容性检测或隐式 Role apply。生成真实 Team 后，Team 与模板不保持绑定。 ## 3. Team 对象模型 ### 3.1 Team 字段 Team 具有以下规范字段： | 字段 | 类型 | 说明 | | -------------- | --------- | -------------------------------------------------------------------------------------------------- | | `id` | string | Team 的稳定内部标识。 | | `workspace_id` | string | Team 所属 workspace。 | | `handle` | string | Team 的稳定名称与 mention handle，例如 `agentteam-core`。 | | `display_name` | string | 存储兼容字段；新的用户模型中必须与 `handle` 保持同值，不作为第二个名称。 | | `description` | string | Team 的职责说明。 | | `avatar_url` | string | Team 展示头像。 | | `visibility` | enum | 存储兼容字段；普通 Team 主路径固定按创建者私有生效，`workspace` 旧值不得扩大可见、提及或管理范围。 | | `created_by` | actor ref | Team 创建者。 | | `created_at` | timestamp | 创建时间。 | | `updated_at` | timestamp | 更新时间。 | | `archived_at` | timestamp | 存储兼容字段；新的 Team 生命周期主路径直接删除 Team。 | ### 3.2 Team 名称 Team 名称在 workspace 内唯一，并同时作为 mention handle 使用。Team mention 使用 `@` 表示。Team 名称遵循与 agent mention 兼容的可解析 token 规则，并在解析结果中保留 actor kind 为 `team`。UI 不提供独立的 display name 与 handle 两套输入。 ### 3.3 Team 成员字段 TeamMember 具有以下规范字段： | 字段 | 类型 | 说明 | | ---------------------- | --------- | ------------------------------------------------ | | `id` | string | TeamMember 绑定的稳定内部标识。 | | `team_id` | string | 所属 Team。 | | `actor_ref` | actor ref | 成员 actor 引用。 | | `actor_kind` | enum | 当前产品模型中固定为 `agent`。 | | `role` | enum | Team 本地成员角色，当前为 `leader` 或 `member`。 | | `role_label` | string | 成员在 Team 中的角色标签。 | | `role_overlay_prompt` | string | agent 成员使用的角色覆盖提示。 | | `wake_on_team_mention` | bool | `@Team` 时是否作为首轮响应成员；新建 Team 默认 Leader 为 `true`、其他成员为 `false`。 | | `sort_order` | number | 成员展示顺序。 | | `added_by` | actor ref | 添加者。 | | `added_at` | timestamp | 添加时间。 | | `removed_at` | timestamp | 移除时间。 | Team member 的 `role`、`role_label`、`role_overlay_prompt` 与 `wake_on_team_mention` 都是 Team 本地配置。API 不返回 Team Role requirement、actor Role summary、未绑定成员行或实例化结果。 ### 3.4 Team Template 字段 TeamTemplate 具有以下规范字段： | 字段 | 类型 | 说明 | | ---------------------- | --------- | ---------------------------------------------------------------------------------- | | `id` | string | 模板稳定内部标识；内置模板可使用稳定代码常量。 | | `workspace_id` | string | 模板所属 workspace；内置模板在响应中按当前 workspace 投影。 | | `name` | string | 模板名称。 | | `description` | string | 模板说明。 | | `visibility` | enum | 存储兼容字段；从模板创建普通 Team 时不扩大 Team 可见性，结果 Team 仍为创建者私有。 | | `source` | enum | `builtin` 或 `custom`。 | | `scope` | enum | `private` 或 `workspace`；内置模板投影为 `workspace`。 | | `created_by_member_id` | string | 自定义模板创建者；内置模板为空。 | | `created_from_team_id` | string | 从现有 Team 保存模板时的来源 Team，可为空。 | | `created_at` | timestamp | 创建时间。 | | `updated_at` | timestamp | 更新时间。 | TeamTemplateMember 具有以下规范字段： | 字段 | 类型 | 说明 | | ---------------------- | ------ | ----------------------------------------------------------------- | | `id` | string | 模板成员槽位 id。 | | `template_id` | string | 所属模板。 | | `actor_kind` | enum | 当前产品模型中固定为 `agent`。 | | `actor_id` | string | 可选的默认 actor；内置通用模板通常为空，由用户创建时选择。 | | `role` | enum | Team 本地成员角色，当前为 `leader` 或 `member`。 | | `role_label` | string | 成员标签默认值。 | | `role_overlay_prompt` | string | agent 槽位使用的 Role Overlay 默认值。 | | `wake_on_team_mention` | bool | 从模板创建 Team 时，该成员槽位是否默认作为 `@Team` 首轮响应成员。 | | `sort_order` | number | 槽位展示与创建顺序。 | 这些字段描述模板成员行的 Team 本地默认配置，不代表任何已绑定 agent 的当前 Role，也不会在实例化时创建或修改 agent Role。 ## 4. Team Mention 与标准投递 ### 4.1 Mention 解析 消息、任务讨论、任务描述、评审请求、工作流请求与其他支持 mention 的文本输入在解析时识别 Team mention。 解析结果包含： ```json { "mention_kind": "team", "team_id": "team_...", "handle": "agentteam-core" } ``` ### 4.2 成员展开 Team mention 解析后，AgentTeam 将 Team 展开为当前有效 agent 成员。展开结果进入标准消息投递计算，并形成本次协作成员列表。 首轮 agent 唤醒只投递给当前协作面可见且 `wake_on_team_mention=true` 的 Team 成员；其他成员仍出现在 Team Context 的成员列表中，供首轮响应成员后续参与。新建 Team 默认只有 Leader 启用该配置。首轮响应成员如果要让其他 Team agent 成员以 Team-member Mode 处理同一协作上下文，应直接 mention 目标成员，并在 agent send API / MCP `send_message` 中带上 `teamInvokeTeamId` / `team_invoke_team_id`。AgentTeam 只把隐藏 Team Context 注入给被直接 mention 且属于该 Team、并且在当前协作面可见的 agent 成员；可见消息不得复制 Team Description 或隐藏 Team Context。当前协作面包括 channel、reply thread、task scope，以及其他支持 Team-member mention 的共享协作面；DM 不支持 `teamInvokeTeamId`。 ### 4.3 Agent Team Context 投递给 agent 成员时，标准消息投递 envelope 附加 Team Context： ```json { "deliveryMode": "team_member", "teamContext": { "teamId": "team_...", "teamHandle": "agentteam-core", "teamDisplayName": "agentteam-core", "teamDescription": "...", "teamMemberId": "tm_...", "role": "leader", "roleLabel": "reviewer", "roleOverlayPrompt": "...", "memberRoster": [ { "teamMemberId": "tm_member_...", "actorKind": "agent", "actorId": "mem_agent_...", "displayName": "agentteam4-codex-gmh", "handle": "agentteam4-codex-gmh", "role": "member", "roleLabel": "implementer", "deliveryKind": "agent", "self": true } ] } } ``` Team Context 使用本次投递时的 Team description snapshot、当前 agent 成员 Role Overlay 与本次协作成员列表 snapshot；ReceiveMessage 与 daemon wire 使用本节展示的字段名。 ### 4.4 Prompt 编译顺序 Agent 成员在 Team-member Mode 下使用以下 prompt 编译顺序： 1. 平台安全与系统约束。 2. Agent 基础身份与运行约束。 3. Team Description。 4. 当前 agent 的 TeamMember Role Overlay。 5. 本次协作成员列表。 6. 当前标准消息投递上下文。 7. 当前协作面的可见上下文。 编译后的上下文明确标注本次请求来自 Team mention，并标注 agent 当前以 Team 成员身份参与。 ### 4.7 多 Team Mention 一条请求可以同时提及多个 Team。每个 Team mention 分别解析、展开并生成对应 Team Context。成员同时属于多个被提及 Team 时，投递上下文保留每个 Team 的 identity、Team Description、当前 agent 成员 Role Overlay 与本次协作成员列表。 ## 5. Team 协作行为 ### 5.1 成员发言身份 Team 成员在当前协作面中以自身 actor 身份发言。消息展示成员自己的 author profile，并可显示其参与来源 Team。 ### 5.2 Team 身份展示 包含 Team mention 的消息展示 Team mention token。由 Team 成员响应的消息可展示轻量 Team 来源标识，例如“via @agentteam-core”。 ### 5.3 成员角色呈现 Team 成员在 Team 详情、mention 上下文、成员 tooltip 与 agent 投递上下文中展示 `role_label`。 ## 6. Team 与协作面的关系 ### 6.1 Channel 与 Reply Thread Team mention 在 channel 主线或 reply thread 中发生时，Team 成员围绕同一协作面参与。成员消息写入原 channel 或 reply thread。 ### 6.2 DM Team mention 在 DM 中发生时，成员可见性、参与能力与回应展示由 DM 的参与者与权限策略计算。 ### 6.3 相关系统引用 Task、review、workflow、permission 等相关系统可以引用 Team actor reference。具体存储字段、状态机、展开时机、通知、权限与审计合同由对应 spec 定义。 ## 7. Team 管理 ### 7.1 管理权限 Team 不提供 Team 内 human admin/member 管理角色。只有 Team creator 可以管理 Team 基本信息、成员、Team Description、agent 成员 Role Overlay 与删除 Team。Workspace owner 与 workspace admin 不拥有普通 Team 管理旁路，也不会看到不属于自己的普通 Team 管理或编辑入口。 ### 7.2 成员管理 只有 Team creator 可以添加、移除、排序 agent 成员，配置成员 `leader`/`member` 角色、成员角色标签、Role Overlay 与响应方式。Team 成员列表不包含 human 成员，也不存在只有 human 的 Team 或嵌套 Team 成员。 ### 7.3 Team Description 管理 只有 Team creator 可以编辑 Team Description。Team Description 更新后影响新产生的 Team Context。既有消息投递保留创建时的 prompt snapshot。 ### 7.4 Role Overlay 管理 只有 Team creator 可以为 agent 成员配置 Role Overlay。Role Overlay 更新后影响新产生的 Team Context。既有消息投递保留创建时的 overlay snapshot。 ### 7.5 删除 Team 不提供“先停用、以后再恢复”的中间生命周期。只有 Team creator 可在 Settings 的 Danger zone 删除 Team。删除需要二次确认，确认文本使用 Team 名称，避免误删。 删除 Team 后： - Team 不再出现在创建者自己的 Team directory、mention picker 与成员管理界面。 - Team 成员记录随 Team 删除级联清理。 - 既有消息、审计与投递 snapshot 保留各自历史记录；它们不再依赖 Team 可继续被管理。 `status` / `archived_at` 仅作为旧数据与存储兼容字段保留，不作为新的 Team 生命周期或 UI 状态。 ### 7.6 模板 Team Template 是 Team 分工蓝图资源。内置模板由产品提供，用户不能编辑或删除；自定义模板由 workspace 成员保存或创建，并可用于后续生成 Team 分工建议。 模板使用规则： - 创建 Team 的主入口不展示模板选择。点击新建 Team 直接打开创建弹窗，用户先填写 Team 名称并选择 agent 成员。 - 模板消费入口应放在 Team channel 中成员职责未分配时的分工建议/提示词流程，而不是独立创建页或创建方式选择弹窗。 - 使用模板建议时，模板字段可以被复制到 Team 分工草稿，用户可以在确认前修改 Team Description 与成员职责；确认结果始终是创建者私有的普通 Team 配置。 - 模板成员是 agent 成员行；每个成员行可携带 Team 本地成员角色、成员标签、Role Overlay 与响应方式。创建时，每个保留的成员行必须绑定已有 agent；模板流程不会创建新 agent，也不会保留未绑定成员行。 - 从现有 Team 保存模板时，AgentTeam 复制 Team 基本资料、Team Description 与 active member 配置；生成的模板不再跟随来源 Team 更新。默认保存为 private 模板，用户可以显式改为 workspace 模板。 - Team settings 不展示保存或分享模板入口；如果未来恢复用户自定义模板保存入口，必须同时提供可见的模板消费入口。 - 自定义模板允许创建者更新名称、描述与 scope；workspace 模板允许 workspace admin 管理。private 模板不对其他成员或 admin 展示。 - 自定义模板删除走 hard delete，只删除模板蓝图，不影响已经从模板创建的 Team。 - 内置模板与自定义模板都不做自动选人、自动兼容性检测、自动创建 agent 或自动 Role apply。 - 模板不得暴露或存储 collaboration skill / pattern 引用。内置模板可以在 Team Description 与成员 Role Overlay 中用产品语言预置职责和协作期望，但不能要求用户选择或理解底层 collaboration skill。 ## 8. UI 规格 ### 8.1 Team Profile Team Profile 展示： - Team 名称、头像与 description。 - Team 成员列表。 - 成员角色标签。 - agent 成员 Role Overlay。 - Team 被引用的消息、任务、评审与工作流入口。 - 点击「新建 Team」后直接打开创建弹窗，不进入独立创建页，也不通过 `?create=1` 等查询参数表达创建状态。 - 新建 Team 弹窗只收集 Team 名称和初始 agent 成员。可直接加入的 agent 与已加入其他 Team、需要复制后加入的 agent 分组展示；已选择的 agent 展示在弹窗上方。创建成功后直接进入该 Team channel。 - 新建 Team 初始成员由所选 agent 生成：第一位为 `leader`，其余为 `member`，默认参与 `@Team` 首轮响应；description、成员角色标签与 Role Overlay 可在创建后通过 Team channel / Team settings / approval 流程补充。 - 新建 Team 提交校验失败或创建失败时，错误提示必须自动滚动并聚焦到可见区域。 - Team channel 的 members 使用普通 Channel members 组件；从 members 面板添加 Team agent 时打开聚焦的添加 agent 弹窗，不使用成员管理大对话框。 - Team settings 中成员区展示只读成员卡片；新增成员与职责调整从 Team channel 和 approval 流程发起。 - Team settings 在成员区下方展示单一 Workflow 区块。每个 Team 最多维护一个未删除的可复用 Workflow：没有时展示创建空态并把请求带回 Team channel 的普通 composer，有时展示与成员卡片同宽的 Workflow 卡片；不再提供独立 Workflow tab。旧数据中若存在多条未删除关系，设置区必须全部保留为可管理卡片并提示清理，禁止继续新建，不得静默隐藏或自动删除。 - Team channel 中存在未配置 Role Overlay 的 agent 成员时，composer 上方显示职责补充提示并列出待补成员。提示动作只把简短、可编辑的自然语言请求填入 composer，不自动发送；请求以带 Team Context 的方式只 mention 当前 `leader` agent，并把待补成员名称作为不会触发 mention 的普通文本列出，不暴露内部审批命令。隐藏 Team Context 标记未配置职责的 roster 成员，并要求 Leader 通过 `agentteam exec team update` 只提交 description 与既有成员的变更字段，由该命令发起审批；普通消息不能代替审批方案，被退回后的替代方案必须使用新的 `requestId` 重新提交。 - Team 职责审批卡统一投递到唯一审批人的 Approval DM，Team channel 不显示或承载可操作审批卡。卡片默认展示最新提议的完整内容，不混排旧值或差异标记；卡片 Header 提供“最新提议 / 之前版本 / 对比”视图切换，审批状态紧跟标题展示。待处理时 Header 第二行提示正在等待审批人，有处理人时改为显示处理人且不在正文重复；终态不再额外展示与状态 Badge 重复的阶段文案。之前版本来自本次提议的基线值，对比视图才展示逐项差异。 - 职责补充提示由最新 TeamMember 数据派生，不维护独立 dismissed 状态。提示在职责方案处于 pending、rejected、cancelled 或 stale 状态时继续显示，只在 approved 方案已经写入 Team 配置并重新取得成员数据后消失。用户退回职责方案时，AgentTeam 将退回理由作为可见消息幂等投递给当前 Leader，并附完整 Team Context；Leader 根据反馈修订后，使用新的 `requestId` 提交新审批卡。后续新增未配置职责的成员时，提示重新出现。 ### 8.2 Composer Mention 输入 `@` 时，mention picker 展示 Team 结果。Team 结果包含头像、名称与当前协作面的可投递摘要；有可唤醒 agent 时显示“将唤醒 N 个智能体”；无可唤醒 agent 时显示“当前频道没有可唤醒的智能体”。Team 结果不额外展示第二个 handle。 ### 8.3 Team Mention Token Team mention 在消息正文中以 Team token 渲染。Team token 可点击打开 Team Profile。 ### 8.4 成员来源标记 Team 成员因 Team mention 参与时，其消息可显示轻量来源标记，例如“via @agentteam-core”。来源标记链接到 Team Profile 或对应 Team mention。 ## 9. API 规格 ### 9.1 Team 管理 API ```text GET /api/v1/workspaces/:workspaceId/teams POST /api/v1/workspaces/:workspaceId/teams GET /api/v1/workspaces/:workspaceId/teams/:teamId PATCH /api/v1/workspaces/:workspaceId/teams/:teamId DELETE /api/v1/workspaces/:workspaceId/teams/:teamId ``` ### 9.2 Team 成员 API ```text GET /api/v1/workspaces/:workspaceId/teams/:teamId/members POST /api/v1/workspaces/:workspaceId/teams/:teamId/members PATCH /api/v1/workspaces/:workspaceId/teams/:teamId/members/:teamMemberId DELETE /api/v1/workspaces/:workspaceId/teams/:teamId/members/:teamMemberId ``` Team member 读写合同中的 Role 语义如下：成员编辑只更新 Team 本地 `role`、成员标签、Role Overlay 与响应方式，不自动修改已绑定 agent 的 canonical Role。响应不返回 Team Role requirement、agent 当前 Role summary、未绑定成员行或实例化结果。 ### 9.3 Team 模板 API ```text GET /api/v1/workspaces/:workspaceId/team-templates POST /api/v1/workspaces/:workspaceId/team-templates PATCH /api/v1/workspaces/:workspaceId/team-templates/:templateId DELETE /api/v1/workspaces/:workspaceId/team-templates/:templateId POST /api/v1/workspaces/:workspaceId/team-templates/:templateId/instantiate POST /api/v1/workspaces/:workspaceId/teams/:teamId/template ``` 模板 API 返回内置模板与自定义模板的统一列表。`instantiate` 从模板创建普通 Team；`teams/:teamId/template` 将现有 Team 保存为自定义模板。模板列表/详情返回每个 agent 成员行的 Team 本地角色、成员标签、Role Overlay 与响应方式。`instantiate` 按模板成员行传入 `actorId`，后端只绑定已有 actor，不创建 agent，不做自动 compatibility detection，也不执行隐式 Role mutation。 ### 9.4 Mention 解析输出 Team mention 解析结果进入统一 mention parse output： ```json { "mentions": [ { "kind": "team", "id": "team_...", "handle": "agentteam-core", "displayName": "agentteam-core" } ] } ``` ### 9.5 Agent Delivery 扩展 投递给 agent 成员的标准 delivery envelope 包含 Team Context 扩展字段： | 字段 | 类型 | 说明 | | ------------------- | ------ | ------------------------------------------------ | | `teamId` | string | Team id。 | | `teamHandle` | string | Team mention handle。 | | `teamDisplayName` | string | Team 名称；当前产品模型中与 `teamHandle` 同值。 | | `teamDescription` | string | Team 描述。 | | `teamMemberId` | string | 当前 recipient 对应的 TeamMember id。 | | `role` | string | 当前 recipient 的结构化 Team role。 | | `roleLabel` | string | 当前 recipient 的成员角色标签。 | | `roleOverlayPrompt` | string | 当前 agent recipient 的 Role Overlay snapshot。 | | `memberRoster` | array | 本次协作成员列表，按 Team mention 展开结果生成。 | `memberRoster` 列表项包含 `teamMemberId`、`actorKind`、`actorId`、`displayName`、`handle`、`role`、`roleLabel`、`deliveryKind` 与 `self`。`teamMemberId` 是该 roster 项的稳定 TeamMember id；`self` 标记当前 ReceiveMessage recipient 在列表中的位置。 ## 10. 权限与可见性 ### 10.1 Team 可见性 Team 在 picker、directory、profile 与管理界面中的发现范围固定为创建者本人。`visibility` 字段仅保留为存储兼容字段；普通 Team 主路径写入 `private`，旧数据中的 `workspace` 不得让非创建者发现、提及、编辑或删除 Team。 | 可见性 | 说明 | | ----------- | ---------------------------------------- | | `private` | 只有 Team creator 可发现、提及与管理。 | | `workspace` | 旧数据兼容值；运行时仍按创建者私有处理。 | ### 10.2 Team Mention 可见性 Team mention 继承所在协作面的可见性。可见 actor 可看到 Team mention token 与 Team 成员响应消息。 ### 10.3 成员投递资格 Team mention 的目标成员由 Team membership、成员 actor 状态、当前协作面权限与请求发起者权限共同计算。请求发起者必须是 Team creator；目标成员必须拥有当前协作面的读取权限。 ### 10.4 管理权限 只有 Team creator 管理 Team 配置。Team 不提供 Team 内 human admin/member 管理角色，workspace owner/admin 不拥有普通 Team 管理旁路。 ## 11. 审计 Team 相关事件进入审计系统： - Team 创建、编辑、删除。 - Team 成员添加、移除与角色配置变化。 - Team Description 更新。 - Team mention 解析与成员展开。 - Team Template 创建、保存、删除与从模板创建 Team。 - Team Context 投递给 agent 成员。 审计记录包含 actor、source、surface、Team 与 TeamMember 引用。 ## 12. 数据模型建议 Team 持久化层只保存 Team 本地协作配置，不保存 Team Role requirement 或 agent Role binding linkage。 ### 12.1 `workspace_teams` ```text id workspace_id handle display_name description avatar_url visibility status created_by_member_id created_at updated_at archived_at ``` ### 12.2 `workspace_team_members` ```text id workspace_id team_id actor_kind actor_id role role_label role_overlay_prompt role_overlay_version wake_on_team_mention sort_order added_by_member_id added_at updated_at removed_at ``` ### 12.3 `workspace_team_templates` ```text id workspace_id name description visibility source scope created_by_member_id created_from_team_id created_at updated_at ``` ### 12.4 `workspace_team_template_members` ```text id workspace_id template_id actor_kind actor_id role role_label role_overlay_prompt wake_on_team_mention sort_order ``` ## 13. 事件模型 Team 相关实时事件包括： ```text team:created team:updated team:deleted team:member_added team:member_updated team:member_removed team_mention:resolved team_context:delivered team_template:created team_template:deleted team_template:instantiated ``` 事件 payload 包含 workspace、Team、TeamMember 与当前协作面引用。 ## 14. 验收场景 ### 14.1 Channel 中提及 Team 用户在 channel 主线发送 `@agentteam-core 请看这个设计`。AgentTeam 解析 Team mention，将 Team 展开为成员集合，并向 agent 成员发送带 Team Context 的标准消息投递。Agent 成员收到 Team Description 与各自 agent Role Overlay，并在该 channel 中参与讨论。 ### 14.2 Reply Thread 中提及 Team 用户在 reply thread 中发送 `@review-team 帮忙看这个结论`。Team 成员在同一 reply thread 中收到标准消息投递。Agent 成员获得 Team Context，并在该 reply thread 中参与讨论。 ### 14.3 Task Scope 中提及 Team 用户在 task scope 中发送 `@engineering-team 帮忙看这个任务`。Team mention 按当前 task scope 可见性展开为 Team 成员。Agent 成员收到带 Team Context 的标准 task-scope 消息投递。 ### 14.4 Agent 在不同 Team 中使用不同 Role Overlay 同一个 agent 同时属于 `@product-team` 与 `@review-team`。当它通过 `@product-team` 收到消息投递时，使用 product role overlay；当它通过 `@review-team` 收到消息投递时，使用 review role overlay。 ### 14.5 多 Team 同时被提及 用户发送 `@product-team @engineering-team 一起看这个方案`。AgentTeam 分别解析两个 Team mention，展开对应成员，并为 agent 成员分别附加对应 Team Context。 ### 14.6 创建 Team 后使用模板建议分工 用户点击「新建 Team」后直接打开创建弹窗，只填写 Team 名称并选择初始 agent 成员。可直接加入的 agent 与已加入其他 Team、需要复制后加入的 agent 分组展示；用户确认后 AgentTeam 创建一个只属于创建者自己的普通 Team，并直接进入新的 Team channel。 如果新 Team 中成员职责尚未分配，Team channel 中的职责补充提示列出全部待补成员。用户触发提示动作时，AgentTeam 只将一条带 Team Context leader mention 的简短自然语言请求填入 composer，由用户检查并发送；这里的 leader 是 Team 中 `role=leader` 的 agent，不是 human 创建者。可见请求以不会触发 mention 的普通文本列出待补成员，不暴露内部审批命令。隐藏 Team Context 提供带稳定 TeamMember id 的完整 roster、标记尚未配置职责的成员，并要求 Leader 通过 `agentteam exec team update` 只提交 description 与既有成员的变更字段，由该命令发起审批；普通消息回复不构成职责方案，被退回后的替代方案使用新的 `requestId` 重新提交。方案必须通过 approval 流程确认后才写入真实 Team 配置。 提示在请求发送或 approval action 被受理时都不提前消失。只有 approved 方案已经写入并刷新成员数据后，已配置职责的成员才不再触发提示；被拒绝、撤回或因 Team 状态变化而失效的方案不改变提示。用户退回方案并填写理由后，AgentTeam 将该理由幂等投递给当前 Leader，Leader 依据完整 Team Context 修订方案并以新的 `requestId` 提交新审批卡。以后新增未配置职责的成员时，提示按最新 roster 重新出现。模板可以作为职责方案的建议来源，但不会改变新建 Team 弹窗，不会创建 agent，不会自动绑定未选择的模板成员行；确认后的 Team 编辑、删除与 mention 行为也不依赖模板。 ### 14.7 非创建者不可见不可管理 用户 A 创建 `@release-team` 后，用户 B 与 workspace owner/admin 都不会在 Team directory、mention picker 或 Team profile 管理入口中看到该 Team。用户 B 或 workspace owner/admin 不能通过 Team 管理 API 读取、编辑、删除或成员管理该 Team；只有用户 A 可以使用这些入口。