# D9 团队协作

## 目标

让多个成员安全地共用一台本地 Codex 设备：默认不共享项目、thread、模型设置和队列；需要协作时显式转交控制权，并让团队看到足够的运行负载与治理信息。

## 已确认产品决策

1. **私聊负责私密任务，群聊负责显式协作。** 群聊中的消息和任务卡天然对群成员可见；包含未公开代码、事故信息或客户数据的任务应在私聊发起。
2. **群聊仍默认按成员隔离。** `FEISHU_GROUP_SESSION_SCOPE=member` 时，每个成员拥有自己的项目、thread、设置和串行队列。团队协作不等于共享 Codex 上下文。
3. **转交的是控制权，不是身份和权限。** 任务保留不可变的发起人；当前控制者可以停止任务、打开审阅和处理非敏感运行时交互。执行仍使用发起任务时冻结的项目和权限设置。
4. **发起人可以显式收回，管理员可以显式接管。** 接管不会静默发生，所有转交和接管写入本地审计。
5. **团队面板只展示元数据。** 成员名称、角色、任务数量、状态、项目负载和 token 用量可见；不展示提示词、结果正文、Diff、附件或原始 `open_id`。
6. **运行手册属于仓库。** `.feishu-codex-runbooks.json` 随项目代码评审和版本控制；第一版不提供飞书内编辑器。
7. **运行手册不能预授权危险动作。** 模板只能保持或降低当前权限，不能请求完全访问；提交、推送、部署和 PR 模板会校验失败。参数替换后再次检查。
8. **第一版一个实例代表一台设备。** 多设备项目路由需要中心控制面、实例身份和离线状态协议，延后到后续版本；当前团队通过不同飞书应用或独立系统账号部署多个实例。

## 角色与资源模型

| 能力 | 管理员 | 操作者 | 只读成员 |
|---|---:|---:|---:|
| 创建普通任务和运行手册 | 是 | 是 | 否 |
| 查看自己的团队概览 | 是 | 是 | 是 |
| 查看全团队聚合 | 是 | 否 | 否 |
| 控制自己当前持有的任务 | 是 | 是 | 否 |
| 接收任务转交 | 是 | 是，且需项目 ACL | 否 |
| 接管他人任务 | 是，显式操作 | 仅任务发起人收回 | 否 |
| 查看他人提示词和结果 | 仅群聊中原本可见的内容 | 同左 | 同左 |

任务包含两个身份：

- `ownerId`：不可变的发起人，也是执行策略、项目与历史 thread 的归属身份。
- `controllerId`：当前控制者，初始等于发起人，可在同一群聊中显式变化。

旧任务没有 `controllerId` 时，迁移会安全回填为 `ownerId`。服务恢复时如果控制者已被移除、降为只读或失去项目权限，控制权回到发起人；旧控制者不能继续批准或停止任务。

## 任务交接流程

```text
群聊成员发起任务
  → 任务卡显示发起人和当前控制者
  → 当前控制者从友好名称列表选择目标
  → 服务重新检查目标角色与项目 ACL
  → 更新 controllerId、任务卡与审计
  → 新控制者可停止、审阅或回答非敏感运行时问题
```

约束：

- 私聊不展示交接控件。
- 目标选项使用稳定匿名 selector，卡片不携带原始 `open_id`。
- 友好名称来自 `FEISHU_MEMBER_LABELS_JSON`；未配置时显示稳定匿名成员码。
- 转交不改变 sandbox、模型、推理强度、外部动作授权或项目。
- 密码、令牌和密钥问题即使完成转交也不能在飞书回答。

## 团队工作台

发送 `团队` 或 `/team` 打开。

管理员看到最近 7 天的授权团队汇总；其他成员只看到自己的发起/控制任务：

- 活跃与排队任务。
- 成员发起数、控制数、成功率与合计 token。
- 项目任务数、活跃数和参与成员数。
- 进入任务中心、运行手册和项目工作台的入口。

统计来自本地保留的任务记录，不上传遥测。记录清理后，面板只代表当前保留窗口，不是计费系统。

## 团队运行手册

复制 `.feishu-codex-runbooks.example.json` 为项目根目录的 `.feishu-codex-runbooks.json`：

```json
{
  "version": 1,
  "runbooks": [
    {
      "id": "inspect-module",
      "name": "检查指定模块",
      "description": "只读检查模块结构和风险",
      "prompt": "只读检查 {{module}} 模块，说明职责、风险和测试缺口。",
      "sandboxMode": "read-only",
      "reasoningEffort": "high",
      "parameters": [
        {
          "name": "module",
          "label": "模块",
          "required": true
        }
      ]
    }
  ]
}
```

使用方式：

- 发送 `运行手册` 或 `/runbooks` 查看当前项目模板。
- 所有必填参数都有默认值时，可以点击“一键运行”。
- 需要输入参数时，发送 `/run inspect-module module="auth"`。

校验规则：

- 每个项目最多 30 个模板、每个模板最多 12 个参数。
- ID 和参数名必须稳定、唯一且只使用安全字符。
- 每个参数必须在 prompt 中使用，未声明占位符会拒绝整份配置。
- `sandboxMode` 只允许 `read-only` 或 `workspace-write`，并与成员当前权限取更低值。
- 模型和推理设置仍经过当前 Codex 能力目录兼容检查。
- 参数替换后如果出现外部动作，任务不会启动，用户需作为普通任务发送并单独确认。
- 文件缺失、JSON 无效或任一模板不安全时失败关闭，不执行部分目录。

## 验收标准

- 两名成员在同一群聊发起任务，conversation key、项目、thread、设置和队列互不共享。
- 任务卡不出现原始 `open_id`，并明确显示发起人与当前控制者。
- 未被转交的普通操作者不能停止或回答他人任务；当前控制者和管理员可以。
- 只读成员、无项目 ACL 成员和已撤权成员不能成为控制者。
- 重启后旧任务自动回填控制者，失效控制权安全回收。
- 团队工作台不包含提示词、结果正文、文件路径或附件内容。
- 运行手册无法提升 sandbox，也无法静默执行外部动作。
- 所有交接、接管和运行手册执行均有审计记录。
- Card 2.0 payload 通过唯一 element ID、行列上限和敏感文本回归测试。

## 后续版本

- 中心控制面中的多设备心跳、实例证书、项目到设备路由和离线队列。
- 在安全的交互表单中填写运行手册参数，而不依赖命令文本。
- 团队级运行手册签名、版本固定和变更审批。
- 按项目设置可见聚合指标与更长统计窗口。