# Teams 团队空间

面向协作 Agent 团队的租户隔离共享记忆空间。空间管理员在管理平面管控工作区边界，而记忆访问则通过数据平面席位进行分区。

- Canonical: https://docs.xmemo.dev/zh/docs/capabilities/teams
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 683a48f04a5f54654f8d734721bc2af8e92c80d4945ca6276756bd086e701f4a
- Edition-Digest: 5a2ab6cf50b6c4916be67f2bb2db9701517fbae686c721f909a493c2d66f1168
- Source-Revision: sha256:097bdf026d1d9352be562c7452c3f2d43aa7b273daa1d8428329f4a76bcb7efe

## 团队记忆架构与 Preview 提供状态

Teams 是 Business 计划的功能。在生产环境中，在 Business 计划正式推出之前，团队创建默认处于禁用状态；当前运行时对未授权请求采用仅拒绝（deny-only）模式运行。空间管理员在工作区管理平面管控工作区边界与租户配置，而 Agent 对记忆的访问则由具有租户隔离密码学空间绑定的数据平面席位治理。

- Preview 状态：在 https://xmemo.dev/me#teams 的 Memory Console 中，Team Management 标有 Preview 徽章。
- 控制台工作区上下文：Team Management 顶部标语声明 "One workspace for members and invitations."，管理员在此管理有效成员和待处理邀请。
- 空间导航：协作者使用显式空间参数切换到团队空间（https://xmemo.dev/me?space=<team_id>#memory），或查看共享知识库（https://xmemo.dev/me?space=<team_id>#knowledge）与技能（https://xmemo.dev/me?space=<team_id>#skills）。
- 协作隔离：团队工作区提供多 Agent 共享上下文，与个人用户的独立个人记忆空间（/me#memory）严格隔离。

## 团队资格、创建要求及订阅边界

创建团队需要享有至少购买了 2 个席位的 Business 订阅权益。由于 Business 计划当前尚未开放购买，普通账户的自助团队创建默认处于禁用状态。公开文档绝不将购买席位作为可用操作展示。

- 创建态势：在 Business 计划正式推出前，生产环境中自助团队创建默认处于禁用状态。
- 权益要求：控制台在开启团队创建前会检查组织权益。如果不符合条件，界面会显示："A Business subscription with at least 2 purchased seats is required to create a team."
- Preview 限制原因：如果账户未获得许可名单批准，控制台会显示："Team creation is currently limited to preview accounts."
- 常规不可用原因：对于未配置的账户，控制台会声明："Team creation is not available for this account yet."
- 商业状态：Business 订阅目前暂不可购买。自助增购席位和升级计划功能均处于禁用状态。
- 创建弹窗：在获得许可的预览账户中，点击创建团队将打开一个弹窗，提示："Enter your company name. This will become the team name inside XMemo."，输入字段为 "Company name"（占位符为 "e.g. Acme Corp"）。

## 四级 RBAC 体系与凭证签发上限

团队成员权限和凭证签发上限由个人控制台服务强制执行。拥有 owner、admin 或 member 角色的有效成员可以在特定角色作用域上限内签发团队绑定凭证，而 viewer 严格只读且被拒绝签发令牌。以下角色架构为说明性摘要（非 API 响应）：

- 角色层次结构：将工作区角色映射到权限级别和令牌签发上限的说明性摘要（非 API 响应）。
- owner（第 3 级）：固定绑定到计费账户的工作区创建者。可以邀请具有 Admin、Member 或 Viewer 角色的成员；可以更新非 owner 成员的角色（在 Admin、Member 和 Viewer 之间）；可以移除非 owner 成员并撤销邀请。可以使用任何自助服务作用域签发团队绑定凭证，包括数据平面记忆、账本、知识库和审计作用域（memory:read、memory:write、memory:restore、read:memories、write:memories、delete:memories、ledger:read、ledger:write、knowledge:read、knowledge:write 和 read:audit）。
- admin（第 2 级）：工作区管理员。可以邀请具有 Member 或 Viewer 角色的成员（不能邀请 Admin）；可以移除非 owner 成员并撤销待处理邀请；不能修改成员角色。可以使用任何自助服务作用域签发团队绑定凭证，包括数据平面记忆、账本、知识库和审计作用域（memory:read、memory:write、memory:restore、read:memories、write:memories、delete:memories、ledger:read、ledger:write、knowledge:read、knowledge:write 和 read:audit）。
- member（第 1 级）：标准工作区协作者。拥有对共享团队记忆席位、团队知识库项和团队 Cloud Skill 的读取、写入和恢复访问权限。可以签发限制在团队成员作用域内的个人团队绑定凭证（memory:read、memory:write、memory:restore、read:memories 和 write:memories）；不能签发提升的账本或知识库作用域，也不能管理工作区成员或设置。
- viewer（第 0 级）：控制台中的只读记忆访问权限（memory:read）及共享知识库查看权限。不允许签发凭证；禁止写入记忆、更新状态或签发团队凭证。
- 唯一所有者约束：唯一所有者尝试退出团队时会收到提示："Cannot leave team as the sole owner. Transfer ownership or delete the team first."（提示工具文本："Sole owner must transfer ownership before leaving"）。

```json
{
  "roles": {
    "owner": {
      "level": 3,
      "token_issuance_cap": [
        "memory:read",
        "memory:write",
        "memory:restore",
        "read:memories",
        "write:memories",
        "delete:memories",
        "ledger:read",
        "ledger:write",
        "knowledge:read",
        "knowledge:write",
        "read:audit"
      ]
    },
    "admin": {
      "level": 2,
      "token_issuance_cap": [
        "memory:read",
        "memory:write",
        "memory:restore",
        "read:memories",
        "write:memories",
        "delete:memories",
        "ledger:read",
        "ledger:write",
        "knowledge:read",
        "knowledge:write",
        "read:audit"
      ]
    },
    "member": {
      "level": 1,
      "token_issuance_cap": [
        "memory:read",
        "memory:write",
        "memory:restore",
        "read:memories",
        "write:memories"
      ]
    },
    "viewer": {
      "level": 0,
      "token_issuance_cap": []
    }
  }
}
```

## 服务端权威空间绑定与动态废除

多租户隔离通过密码学空间绑定在服务端强制执行。每个团队作用域的 API 密钥都包含不可变声明（bound_team_id、membership_id_at_issue、space_binding_version），客户端请求无法篡改或指定这些声明。针对不匹配团队的请求会立即以 HTTP 403 token_space_mismatch 进行闭环失败处理（fail closed）。

- 权威空间验证：针对不匹配团队的请求会立即以 HTTP 403 token_space_mismatch 进行闭环失败处理。
- 防伪造保证：携带伪造或冲突团队请求头的请求会在边缘层被直接拒绝，而不会访问数据库连接池。
- 基于纪元的动态废除：成员身份验证在每次认证请求中检查实时的 membership_id 纪元，确保被移除的成员在纪元更新时立即失去访问权限，无需等待令牌到期。

## 席位管理、邀请生命周期与生命周期边界

工作区容量跨有效成员与待处理邀请进行定性跟踪。运行边界管控邀请签发、过期以及控制台功能：

- 定性席位计数：占用席位由有效成员加上未过期的待处理邀请构成，在控制台头部显示为 "Seats {used} / {limit} used, {members} members, {pending} pending"。
- 技术性邀请到期：团队邀请在签发 7 天后到期（teams_service.py:1184-1188）。过期的邀请会释放其预留，不再计入占用席位。
- 席位容量上限：当所有可用席位均被占用时，添加成员弹窗会发出警告："Team seat limit reached. Upgrade or remove a member or pending invitation to send more invitations."
- 邀请工作流状态：发送邀请会生成一个安全的 7 天有效令牌链接。然而，控制台界面目前没有消费该邀请的入口；完整的邀请接受工作流在控制台中尚不可用。
- 不支持团队删除或所有权转让：控制台不提供用于删除团队工作区或转让团队所有权的路由或 UI 控件。这些操作在自助服务中不可用。

## 共享资源、Agent 访问与数据导出边界

Teams 能力对 Model Context Protocol (MCP) 接口未引入任何变更。Agent 仅需通过团队绑定令牌完成认证，即可透明地使用标准工具（remember、recall、recall_context、search 等）访问共享团队记忆。

- 共享团队记忆：使用团队绑定令牌进行身份验证的已连接 Agent 可以对共享团队记忆空间进行读写。
- 共享团队知识库：在团队空间（?space=<team_id>#knowledge）下发布的文档集合，可由具备 knowledge:read 作用域的团队 Agent 和团队成员检索。
- 共享团队 Cloud Skill：在团队空间（?space=<team_id>#skills）下创建的规程技能受团队角色管控。在团队空间中发布会创建 PROPOSED 修订版，需要 Admin 或 Owner 审批。
- 个人项目边界：项目工作区目前仍严格仅限个人使用（services/personal_console.py:7222）。后端会拒绝创建带有 team_id 的项目工作区。
- 数据导出边界：个人数据导出（/api/v1/export 或 /me#memory）仅导出严格属于个人的记忆，坚决排除共享团队记忆记录。
- 冻结的工具接口：没有向 MCP 中添加任何团队管理工具（例如团队创建或邀请管理）。
- 通用客户端兼容性：Claude Desktop、ChatGPT、Codex、Cursor 和 Gemini CLI 无需客户端配置更改即可与团队记忆交互。
- 作用域隔离：Agent 在团队空间中写入的记忆会自动标记团队归属，并与个人用户的记忆保持隔离。

## 明确边界与未验证能力

为防止文档与已发布代码发生偏离，以下能力明确不可用且超出当前版本的范围：

- 需要 Business 计划：Teams 能力属于 Business 计划，该计划目前尚未开放公开购买。
- 生产环境创建已禁用：在 Business 计划正式推出之前，生产环境中常规自助团队创建处于禁用状态。
- 无自动化 SCIM / SAML 同步：不支持企业身份提供商目录同步。
- 无跨云或多区域数据复制：团队数据存放在单一区域租户分区中。
- 无 MCP 变更工具：无法通过 MCP 工具调用创建、修改或删除团队。
- 仅拒绝运行模式：在 Business 计划推出前，当前运行时对未授权请求采用仅拒绝模式运行。
- 无未经证实的性能指标：废除与查询时间是运行时的运维属性，而非固定数值保证。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。