# V4：工作区会话交互模型

状态：`已确认，分阶段实现`
日期：2026-07-17
范围：飞书中的项目、Codex 会话、消息、运行过程、审批与团队协作

## 1. 产品定义

> 把本地 Codex thread 映射成一个可持续交流、可以协作和接管的飞书工作会话。

飞书是远程工作入口，不是任务管理器、远程终端或通用聊天机器人。用户首先感知的是一个持续存在的工作会话；队列、任务记录、审计和恢复仍然存在，但默认退到后台。

## 2. 核心对象

| 产品对象 | 飞书载体 | 用户心智 | 是否默认可见 |
|---|---|---|---|
| 设备 | 机器人私聊首页 | 哪台本机可以接管 | 是 |
| 项目工作区 | 一个项目群 | 我正在操作哪个仓库 | 是 |
| Codex 会话 | 群里的一个话题/回复串 | 我在继续哪段上下文 | 是 |
| Turn | 用户消息与 Codex 回复 | 一轮自然交流 | 是 |
| Execution | 本地执行记录 | 系统正在处理 | 仅长任务简要可见 |
| Interrupt | 审批、追问、失败、离线 | 现在需要我决定 | 是，使用卡片 |
| Task/Audit | 持久任务、队列和审计记录 | 可靠性基础设施 | 默认隐藏 |

### 不变量

1. 一个工作话题只绑定一个本地项目、一个 Codex thread 和一台执行设备。
2. 同一话题内的普通消息默认继续当前 Codex thread，不创建新的用户可见任务。
3. 模型、推理和权限属于工作会话，不在每次回复中重复展示。
4. 卡片只承载控制、决策和异常，不包裹普通问答。
5. 项目和会话身份不能依赖聊天中的“当前选择”猜测；每次执行都使用入队时保存的不可变快照。

## 3. 信息架构

```text
机器人私聊：首页 / 控制面
  ├─ 本地设备
  ├─ 最近项目工作区
  ├─ 最近 Codex 会话
  └─ 创建 / 恢复工作区

项目群：一个本地项目
  ├─ 置顶工作区控制卡
  │   ├─ 设备与分支
  │   ├─ 模型与推理
  │   ├─ 权限
  │   └─ 新建会话 / 本机打开
  └─ 话题 A、B、C：独立 Codex thread
      ├─ 自然问答
      ├─ 分析与写文件
      ├─ 代码修改
      └─ 必要时出现审批/追问卡
```

### 项目群建立

支持两条全部在飞书内完成的路径：

- 私聊项目卡一键创建项目群，自动邀请授权成员、绑定项目并置顶工作区卡。
- 把机器人加入已有群，由管理员在首次卡片中选择一次项目。

群与项目绑定后不可切换；另一个项目必须使用另一个群。绑定前不接受任何 Codex 任务。绑定完成后：

- 私聊维持一个当前工作会话。
- 群聊中的顶层普通 prompt 自动在回复串中创建新工作会话。
- 群聊回复串使用根消息作为稳定会话键，同一话题共享一个 Codex thread。
- 群聊主会话中的项目和设置会复制到新话题，之后由话题独立保存。

## 4. 回复呈现规则

| 用户意图 | 接收时 | 运行中 | 完成时 |
|---|---|---|---|
| 提问 | 同一条轻量 Markdown 回复进入处理态 | 原消息增量更新 | 变成干净的普通回答 |
| 分析 | 显示当前分析动作 | 原消息增量更新摘要 | 结论 + 可选详情 |
| 写文件 | 一条紧凑进度消息或卡片 | 更新文件/检查阶段 | 交付摘要 + 文件入口 |
| 改代码 | 一张紧凑运行卡 | 更新命令、文件和测试阶段 | 结果摘要 + Diff/测试入口 |
| 审批/追问 | 不创建新任务 | 暂停当前 turn | 决策卡处理后继续原 turn |
| 失败/离线 | — | — | 异常卡 + 一个明确恢复动作 |

普通回答不得默认展示：任务 ID、thread ID、token、权限、模型、重复 prompt、重新执行、新会话按钮或安全脚注。这些信息进入工作区控制卡、任务中心或“详情”。

普通回答遵循移动端优先的排版：先给结论，段落保持简短，列表默认不超过 5 项，不使用宽表格；简短的首句结论优先映射为飞书原生富文本标题，让消息预览直接表达内容，而不是暴露 Markdown 符号或只显示泛化标签。

飞书原生文本与富文本消息最多编辑 20 次。渐进回答必须合并高频增量、限制中间刷新次数，并始终为成功、失败、取消或中断的最终状态预留编辑额度；不得因追求逐 token 动画而留下永远停在“处理中”的消息。

## 5. 关键流程

### 5.1 创建工作区

```text
私聊机器人
  → 选择在线设备
  → 选择授权项目
  → 创建或绑定项目群
  → 生成置顶工作区控制卡
  → 新建第一个话题会话
```

### 5.2 持续对话

```text
用户在话题发送消息
  → 根据 chat + root message 定位工作会话
  → 若当前 turn 运行中则追加要求
  → 否则恢复该话题绑定的 Codex thread
  → 系统在后台创建 Execution 记录
  → 使用与意图匹配的轻量呈现
  → 完成后会话回到 idle，可继续下一轮
```

### 5.3 多项目并行

```text
项目群 A / 话题 A1 → 项目 A / Codex thread A1
项目群 B / 话题 B1 → 项目 B / Codex thread B1
项目群 B / 话题 B2 → 项目 B / Codex thread B2
```

不同项目可受全局并发限制并行；同一工作树默认串行。用户无需发送 `/use` 来辨认正在操作的项目。

### 5.4 审批与接管

审批卡必须绑定工作区、会话、turn、发起人和有效期。批准后恢复原 turn，不新建任务。团队成员需要通过显式转交或接管获得控制权，发起人和管理员保留可审计的收回能力。

### 5.5 回到本机

工作区控制卡提供“在本机打开”。本机 Codex 读取同一个 thread，不复制或重建上下文。点击时飞书侧必须没有运行或排队中的 turn；打开后应只在一端继续，避免两个客户端同时向同一 thread 发送 turn。

当前实现中，会话卡会先确认该 thread 仍属于当前项目且聊天没有运行/排队任务，再通过 `codex://threads/<thread-id>` 导航 macOS Codex。其他平台或启动失败时只展示 `codex resume <thread-id>`，不会显示虚假成功。

### 5.6 双向接力与可见性

飞书不是 Codex 桌面端的镜像。只有实际路由给 Codex 的用户输入、附件和运行时补充会进入原生 thread；飞书卡片、按钮、状态消息、审计信息及无关聊天仍留在飞书。

```text
飞书工作会话 ──发送 turn──→ 原生 Codex thread ←──本机继续── Codex 桌面端
     │                              │
     └─ 卡片 / 控制 / 通知留在飞书   └─ 唯一上下文来源，不复制完整记录
```

接力规则：

- “在 Codex 中打开”必须打开当前绑定的同一个 thread，而不是创建新 thread。
- 本机在该 thread 中新增 turn 后，飞书下一次恢复应继承其上下文。
- 用户在本机另开 thread 时，飞书绑定保持不变；只有显式选择并确认后才能重新绑定。
- 两端展示同一个可读会话名，并显示最近活动来源与时间。
- 无法导航桌面端时，退化为展示可搜索的会话名，不谎报已经打开。

## 6. 状态模型

### 工作区

```text
unbound → ready ↔ offline
            ↓
          blocked
            ↓
          archived
```

### 工作会话

```text
idle → running → idle
          ├─ waiting_for_approval → running
          ├─ waiting_for_answer → running
          ├─ failed → idle（用户继续或重试）
          └─ interrupted → idle（恢复上下文，不自动重放）

idle → archived
```

### Turn

```text
accepted → running → completed
                    ├─ failed
                    ├─ cancelled
                    └─ interrupted
```

Task 是 Turn 的可靠执行记录，不再作为主要交互对象。

## 7. 数据与路由

### 会话键

- 私聊：`chat_id`
- 群主会话：沿用部署的 `chat` 或 `member` 隔离策略
- 群话题：`chat_id::topic::root_message_id`

群话题优先使用 `root_id`；只有缺少 `root_id` 时才回退到 `thread_id`。群顶层普通 prompt 使用自己的 `message_id` 作为新话题根键，并在回复时开启 `reply-in-thread`。

### 工作区快照

每个新话题从群主会话复制：

- 项目路径
- 模型与推理设置
- 持久 sandbox 上限

不会复制：

- Codex thread ID
- 临时完全访问租约
- 运行或排队任务
- 未完成审批和问题

## 8. 安全与团队规则

- 项目 ACL 在创建话题和每轮执行前都检查。
- 话题共享不等于执行权共享；默认由当前控制者操作。
- 完全访问仍不绕过 commit、push、deploy、PR 和外部副作用确认。
- 群被重新绑定项目时，已有话题保持原项目快照；不会静默漂移。
- 审计记录 actor、workspace、session、turn、结果和权限，不记录秘密。

## 9. 分阶段迁移

### Phase 1：对话成为主界面

- [x] 确认产品对象和交互不变量。
- [x] 解析飞书 `root_id`、`thread_id` 和 `reply_to`。
- [x] 群回复串获得独立、共享的 Codex 会话键。
- [x] 问答与分析使用可更新的 Markdown 消息，不创建完整任务卡。
- [x] 普通回复自动把短结论映射为飞书原生富文本标题，清理会话列表里的 Markdown 符号，并使用无装饰的轻量处理中状态。
- [x] 顶层群 prompt 自动回复到话题。
- [x] 项目和设置复制到新话题。

### Phase 2：紧凑执行与结果

- [ ] 写文件和代码任务改为一张紧凑状态卡。
- [ ] 完成结果以普通回复呈现，Diff/测试作为次级入口。
- [ ] 取消重复完成通知、重复 prompt 和每轮元数据。
- [ ] Token、额度、模型和权限移入详情与工作区控制卡。

### Phase 3：项目群工作区

- [ ] 私聊首页支持创建、恢复和搜索工作区。
- [ ] 可选自动创建项目群并邀请成员/机器人。
- [ ] 置顶工作区控制卡成为项目唯一控制面。
- [ ] 实现本机打开同一原生 thread、已有 thread 显式绑定、归档和跨设备接管。
- [ ] 展示最近活动来源，并对“飞书内容不会全部同步”提供清晰说明。

### Phase 4：团队化

- [ ] 话题级转交、接管和观察者模式。
- [ ] 工作区模板、团队策略和审计导出。
- [ ] 多设备路由与同项目锁冲突提示。

## 10. V4 验收标准

1. 在群里同时打开两个话题，能稳定对应两个不同 Codex thread。
2. 简单问题只出现一条持续更新的普通回复，不出现绿色任务完成卡。
3. 同一话题继续提问会沿用原 Codex thread；新话题不会继承旧 thread。
4. 任何任务都能从持久记录恢复，但用户不需要理解 Task 才能正常使用。
5. 卡片只在控制、审批、追问、长任务和异常中出现。
6. 多项目执行时，用户仅凭群名和话题标题即可辨认项目与上下文。
7. 原有私聊、队列、安全门禁、审批、任务中心和审计数据保持兼容。
8. 飞书与本机接力时使用同一个原生 thread；本机另开会话不会静默改变飞书绑定。