# Feishu Codex Console 产品需求地图

> 状态：V4 工作区会话模型已确认
> 当前版本：`1.0.0-beta.10`
> 产品定位：通过飞书远程、安全、持续地控制本地 Codex。

这份文档是产品需求的唯一入口。每个方向先讨论清楚用户问题、产品边界和验收标准，再进入实现；讨论结论持续回写到对应章节。

需求描述“为什么做、边界是什么”；产品实际怎样运行、失败怎样恢复以及怎样验收，分别以 [全项目 SOP 总览](SOP_INDEX.md)、[全项目正向 SOP](USER_SOP.md)、[全项目逆向与恢复 SOP](FAILURE_RECOVERY_SOP.md)和[验收测试矩阵](ACCEPTANCE_TEST_MATRIX.md)为准。

## 1. 产品定义

### 一句话定位

> 在飞书里，安全地继续使用你电脑上的 Codex。

### 完整定义

Feishu Codex Console 是一个开源、本地优先的 Codex 远程工作会话层。它把本地项目和 Codex thread 映射到飞书项目群与话题，让开发者自然提问、分析、写文件、修改代码、处理审批并安全地与团队接力，无需开放公网端口。

### 产品关键词

1. **本地优先**：代码、项目和 Codex 运行环境留在用户自己的设备。
2. **连续会话**：飞书控制真实 Codex Thread，不把每条消息当成孤立调用。
3. **安全可控**：用户知道谁在什么设备、项目和权限下执行了什么。

### 当前目标用户

| 用户 | 核心场景 | 首要诉求 |
|---|---|---|
| 个人开发者 | 离开电脑后继续处理本地项目 | 安装简单、连接可靠、随时接手 |
| 小团队维护者 | 共享开发机或团队项目 | 成员隔离、权限、项目 ACL、审计 |
| 开源贡献者 | 安装、调试和扩展项目 | 文档清楚、诊断明确、接口稳定 |

### 产品非目标

当前主线不做：

- 通用 AI 聊天机器人。
- 多模型聚合门户。
- 云端 IDE 或代码托管平台。
- 通用飞书自动化产品。
- 默认云端中继用户代码。
- 同时支持大量 IM 和 Agent 的平台。

## 2. 核心使用闭环

```text
打开飞书机器人首页
  → 进入或创建项目工作区
  → 在项目群的话题中恢复一个 Codex thread
  → 像聊天一样提问、分析、写内容或修改代码
  → 仅在长任务中查看紧凑进度
  → 仅在需要决定时处理追问或审批卡
  → 查看自然回复，按需展开文件、Diff 和测试
  → 继续对话、邀请协作者或回到本机接手
```

核心闭环完成的定义：用户在不接触本机终端的情况下，可以在一个稳定工作话题中连续完成问答、分析、内容交付或代码修改；只有真正需要决策或审阅的节点才出现卡片。

完整对象模型、状态机、回复规则和迁移阶段见 [V4 工作区会话交互模型](V4_WORKSPACE_SESSION_FLOW.md)。

## 3. 需求方向总览

| 编号 | 方向 | 核心问题 | 优先级 | 当前状态 |
|---|---|---|---|---|
| D1 | 安装与首次连接 | 别人能否在 10 分钟内装好并连接飞书 | P0 | beta.4 闭环已完成 |
| D2 | 设备与连接状态 | 用户能否确认本机当前真的可控 | P0 | beta.4 闭环已完成 |
| D3 | 项目与会话 | 用户能否准确进入正确项目和上下文 | P0 | beta.4 闭环已完成 |
| D4 | 远程任务执行 | 用户能否稳定发起、追加、排队和停止任务 | P0 | beta.4 闭环已完成 |
| D5 | Codex 原生交互 | 问题、审批、模型和推理能否在飞书完成 | P0 | beta.4 闭环已完成 |
| D6 | 结果与代码审阅 | 用户能否判断任务结果是否可以接受 | P0 | beta.4 闭环已完成 |
| D7 | 权限与安全治理 | 用户是否敢让它操作真实电脑和项目 | P0 | beta.4 已闭环 |
| D8 | 可靠性与恢复 | 断线、重启和异常后能否继续 | P0 | beta.4 闭环已完成 |
| D9 | 团队协作 | 多人使用时能否隔离、交接和治理 | P1 | beta.4 闭环已完成 |
| D10 | 维护与开源生态 | 维护者能否发布、升级、诊断和扩展 | P1 | beta.4 工程闭环已完成 |

---

## D1. 安装与首次连接

### 用户目标

不用理解项目内部结构，在 10 分钟内完成飞书应用绑定、本地 Codex 检查、成员识别和后台服务安装。

### 当前已有

- `npx feishu-codex-console@next init` 初始化向导。
- 个人安全、团队安全和高级模式预设。
- 自动识别 `open_id`、`chat_id` 和会话类型。
- 私有配置和数据目录。
- `doctor` 与后台服务安装。
- Codex 辅助安装提示词，以及 `install-status --json` / `doctor --json` 机器验收契约。

### MVP 需求

- 自动检查 Node、Codex 登录和飞书 Bot 身份。
- 自动识别当前安装者。
- 验证消息事件、卡片回调和 CardKit 权限。
- 自检失败时不安装服务，并给出下一条修复命令。
- 安装完成后主动生成第一张飞书引导卡。
- 已有安装可安全重跑，不覆盖未知配置。
- 安装助手在官方登录、Secret、权限差异和发布步骤暂停，只恢复持久化的下一安全步骤。

### 验收标准

- 新用户仅根据 README 可以完成安装。
- 安装过程不要求用户手工编辑 30 多个环境变量。
- 配置文件为 `0600`，数据目录为 `0700`。
- 安装失败时没有裸堆栈或模糊错误。
- 只有本地 `ready/ok` 与飞书真实回复同时成立，才声明端到端安装完成。

### 待讨论决策

- 是否由向导自动创建飞书应用，还是只绑定已有应用？
- 是否需要浏览器式安装页面，还是 CLI 足够？
- 安装结束是否自动给用户发送测试卡？
- 首次安装默认使用个人安全还是根据成员数量判断？

### 非目标

- 自动修改公司飞书管理员策略。
- 默认使用云端托管服务。

### 决策记录 2026-07-16

- 决策：MVP 绑定用户已有的飞书自建应用，不自动创建应用。
- 原因：自动创建会引入企业管理员权限、租户差异和外部账号状态，扩大首版边界。
- MVP 包含：应用绑定、能力检查、身份发现、服务安装和测试卡。
- MVP 不包含：创建企业、创建应用、管理员审批和自动发布应用版本。
- 安装交互：`beta.4` 只提供 CLI 向导；网页安装器延后。
- 测试卡：私聊自动发送、群聊再次确认，允许显式关闭。
- 配置更新：备份并合并已知键，保留未知高级配置。
- 完成标准：doctor、服务健康和端到端测试卡全部成功。
- 详细 PRD：[D1 安装与首次连接](requirements/D1_INSTALLATION_AND_FIRST_CONNECTION.md)。
- 非开发者入口：[让 Codex 帮你安装](INSTALL_WITH_CODEX.md)。

---

## D2. 设备与连接状态

### 用户目标

打开飞书后立即知道哪台设备在线、Codex 是否可用、当前是否适合发起任务。

### 当前已有

- 本地设备控制台。
- 飞书监听、Codex 引擎、队列、电源和 Remote Ready 状态。
- macOS `caffeinate` 远程就绪。

### MVP 需求

- 明确区分在线、连接中、离线、异常和维护中。
- 显示最后心跳和最后一次成功任务时间。
- 离线时不展示虚假的可执行按钮。
- 给出对应修复入口，而不只显示错误。
- 服务恢复后更新原控制台并发送一次恢复通知。

### 验收标准

- 用户 5 秒内能判断设备是否可执行任务。
- 每个异常状态都对应至少一个可执行修复动作。
- 断线恢复后不重复创建大量状态卡。

### 已确认决策

- 第一版一个桥接实例只代表一台设备，多设备路由等待中心控制面。
- 本地服务离线时无法主动上报，不伪装成云端实时监控；所有卡片展示绝对采样时间。
- 非预期离线超过 30 秒后恢复，按会话至多发送一次恢复通知，15 分钟内去重。
- Remote Ready 由管理员显式开启，不默认开启。

详细状态机和任务记录见 [D2 设备与连接状态](requirements/D2_DEVICE_AND_CONNECTIVITY.md)。

### 非目标

- 远程开机。
- 绕过系统合盖、电源或公司设备策略。

---

## D3. 项目与会话

### 用户目标

确认任务运行在正确的本地项目、分支和 Codex 上下文中，并可以恢复之前的工作。

### 当前已有

- Codex 已保存项目同步和 Git 根目录扫描。
- 项目切换、当前项目持久化和项目 ACL。
- Thread 创建、恢复和压缩。
- 群聊按成员隔离。

### MVP 需求

- 项目搜索、收藏和最近使用。
- 清楚展示项目路径、分支和未提交状态。
- 切换项目前说明是否会停止当前任务或重置上下文。
- 会话自动命名，并显示最后任务摘要。
- 飞书与本机能够接力同一 Codex Thread。

### 验收标准

- 用户不会因为项目重名而选错目录。
- 恢复会话后项目、模型和上下文保持一致。
- 无权访问的项目不会出现在列表、搜索和历史记录中。

### 已确认决策

- 一个飞书会话绑定一个当前项目并允许快速切换；群聊默认按成员隔离。
- 项目名称必须和可辨识路径一起展示；收藏和最近使用按成员保存。
- 卡片选择始终确认；存在任务、队列或已保存上下文时，文字切换也必须显式确认。
- 项目切换停止当前会话未完成任务并解除 thread 绑定，但不删除文件或 Codex 历史。
- 新 thread 根据首条任务自动命名；会话中心恢复 Codex 原生 thread。
- 团队成员只看本人已登记的历史；管理员在受审计前提下可查看当前项目的全部历史。

详细流程和任务记录见 [D3 项目与会话](requirements/D3_PROJECTS_AND_SESSIONS.md)。

### 非目标

- 在飞书创建任意本机目录。
- 替代 Git 仓库管理工具。

---

## D4. 远程任务执行

### 用户目标

像在 Codex 中一样发起任务，实时知道进度，并可随时补充、排队、停止和恢复。

### 当前已有

- 持久任务队列和全局并发。
- 实时任务卡。
- 普通消息自动追加、显式排队、停止和重试。
- 完成通知和服务重启恢复。

### MVP 需求

- 任务状态始终只有一个权威来源。
- 清楚区分“追加当前任务”和“创建新任务”。
- 任务卡展示项目、会话、权限、耗时和当前动作。
- 停止后说明哪些修改已经写入磁盘。
- 失败任务保留可恢复上下文和明确失败原因。

### 验收标准

- 重复事件不会产生重复任务。
- 服务重启后排队和运行任务状态一致。
- 用户可以在两次操作内停止任何本人任务。

### 已确认决策

- 用户不需要先选任务类型；系统仅在本地自动区分问答、分析、内容和代码，原始提示词不改写。
- 问答和分析强制只读，不建立 Git 基线、不消费完全访问租约；内容与代码才允许写入，只有代码默认要求测试证据。
- 任务卡的标题、进度、重试和验证入口跟随任务类型；没有真实文件或测试证据时不制造审阅入口。
- 运行期间的普通消息默认追加到当前 turn；`排队 <任务>` 明确创建独立任务。
- 同一会话串行、同一项目跨会话也串行；不同项目受全局并发上限控制。
- 排队任务在重启后自动恢复，已经运行的任务标记中断且不自动重放。
- thread ID 在启动时保存，停止、失败和中断不会丢失可恢复上下文。
- 管理员可以在当前项目停止团队任务，所有操作写入审计；成员只能操作本人任务。
- 优先级和定时任务不进入 beta.4，超时继续使用部署级配置。

详细状态机和任务记录见 [D4 远程任务执行](requirements/D4_REMOTE_TASK_EXECUTION.md)。

### 非目标

- 无限并发。
- 把飞书聊天变成完整终端模拟器。

---

## D5. Codex 原生交互

### 用户目标

不回到电脑也能完成 Codex 的问题、审批、模型、推理和会话交互。

### 当前已有

- Codex app-server 持久连接。
- 原生审批和结构化问题卡。
- 模型目录、推理强度和权限设置。
- 推理文案与 Codex 界面对齐。

### MVP 需求

- Codex 问题使用按钮、下拉框或下一条消息回答。
- 审批明确显示命令、目录、影响和有效范围。
- 模型和推理设置只展示当前模型实际支持的选项。
- 过期问题和审批不可继续操作，并提供回到最新任务入口。
- Codex 版本能力变化时自动降级而不是崩溃。

### 验收标准

- 飞书回答能准确恢复原 Codex Turn。
- 同一个审批不能被重复消费。
- 只读成员不能回答或批准他人的任务。

### 已确认决策

- 模型、推理和 sandbox 按飞书成员会话保存，下一轮生效；运行中的 turn 不热切换。
- “Codex 默认”保持动态默认语义，显式模型才固定版本；能力变化时按任务安全回退。
- 审批默认允许一次，会话允许是带二次确认的次级动作；所有终态和越权尝试写入审计。
- `isSecret` 问题完全禁止通过飞书回答或落入内容日志，只允许取消后回可信本机处理。
- 任务卡只展示任务结束后的真实 Token 用量，并拆分累计输入、新增输入和缓存命中；`读取项目` 使用本地确定性快照并保持 0 AI token。控制台只保留额度摘要，完整额度卡读取 Codex app-server 的真实账户窗口、重置时间与重置次数，不以累计 token 推测额度，也不预测耗时。

详细协议、状态机和任务记录见 [D5 Codex 原生交互](requirements/D5_CODEX_NATIVE_INTERACTIONS.md)。

### 非目标

- 自行实现一套与 Codex 不兼容的模型协议。

---

## D6. 结果与代码审阅

### 用户目标

在飞书中判断任务是否正确，了解修改内容和测试结果，再决定继续或接收。

### 当前已有

- 完成结果和文件变化摘要。
- 查看实时变更、重新执行和新会话。

### MVP 需求

- 文件级 Diff 摘要和可分页完整 Diff。
- 测试命令、结果、失败用例和耗时。
- 区分新增、修改、删除和未跟踪文件。
- 给出继续修改、保留、丢弃和回本机查看的动作。
- 超长结果使用独立飞书文档或附件，不截断关键结论。

### 验收标准

- 用户能够回答“改了什么、测试是否通过、下一步是什么”。
- Diff 不泄露无权查看的项目内容。
- 失败测试不会被展示为任务成功。

### 已确认决策

- beta.4 操作真实工作区并在任务实际启动时建立 Git 基线；脏文件按指纹排除或标记混合，不默认引入 worktree。
- 结果卡把 Codex turn 完成与测试通过分开；最后一次测试失败时不会显示绿色成功。
- 文件列表和逐文件 Diff 都使用飞书卡片分页；敏感路径不展示正文，极大差异提示回本机。
- 不提供一键丢弃或应用，避免误删任务前修改；commit、push 和 PR 继续走单独外部动作确认。

详细归因模型、审阅流程和任务记录见 [D6 结果与代码审阅](requirements/D6_RESULTS_AND_CODE_REVIEW.md)。

### 非目标

- 在飞书中实现完整代码编辑器。

---

## D7. 权限与安全治理

### 用户目标

明确知道 Codex 能做什么，危险能力必须有边界、时限和审计。

### 当前已有

- 管理员、操作者和只读成员。
- 用户、聊天、项目和外部动作门禁。
- 三级 sandbox 和操作者权限封顶。
- 项目 ACL、任务归属和 SQLite 审计。
- 敏感环境变量隔离。

### MVP 需求

- 完全访问改为本次任务、当前会话或限时权限租约。
- 权限到期后自动回退，并支持立即降权。
- 每个项目可以声明允许、拒绝和必须审批的操作。
- 所有审批记录操作者、资源、结果和有效范围。
- 日志、诊断包和卡片统一脱敏。

### 验收标准

- 未授权成员无法执行、查看或操作他人资源。
- 权限提升不会永久改变默认安全状态。
- 高风险外部动作不能因完全访问而绕过确认。

### 已确认决策

- 完全访问只提供下一任务（30 分钟内消费）、限时 30 分钟和当前会话（最长 60 分钟）三种租约；结束后自动回落到工作区写入或更低角色上限。
- 租约绑定成员、聊天、项目和 thread；成员只能自助提权，管理员可以代为撤销但不能代为授予。
- 项目策略使用仓库根目录 `.feishu-codex-policy.json`，随代码评审和版本控制；策略只能收紧 sandbox 与外部动作，不能取消全局确认底线。
- beta.4 延续 D6 的真实工作区方案，不默认使用 Git worktree；更强隔离通过独立系统账号或容器部署实现。
- 日志、文本 outbox、审计摘要、任务/审批/确认卡、测试摘要和 Diff 使用共享脱敏规则。

详细租约状态、策略格式和脱敏边界见 [D7 权限与安全治理](requirements/D7_SECURITY_GOVERNANCE.md)。

### 非目标

- 声称应用层命令检查等同于操作系统沙箱。

---

## D8. 可靠性与恢复

### 用户目标

电脑睡眠、网络切换、服务重启或飞书 API 短暂失败后，任务和状态不会混乱或丢失。

### 当前已有

- SQLite WAL、任务恢复、事件去重和可靠 outbox。
- CardKit 序号、确认记录和附件保留。
- LaunchAgent/systemd 自动守护。

### MVP 需求

- 明确的连接状态机和最后成功心跳。
- 飞书 API 限流、超时和失败重试策略。
- 服务升级前备份，迁移失败自动回滚。
- `doctor --fix` 和脱敏诊断包。
- 任务状态、卡片状态和 Codex Turn 状态可以对账修复。

### 验收标准

- 进程被终止后重启，不会重复执行已经完成的外部动作。
- 卡片更新失败时仍能通过文本获得最终结果。
- 数据库迁移失败不会破坏上一版本数据。

### 已确认决策

- `beta.4` 不提供云端离线队列；设备离线期间不承诺接收消息，恢复后由用户检查并重发未确认任务。同一飞书事件仍按 event ID 至多消费一次。
- 只自动恢复可以证明从未启动的排队任务；存在 `running`、启动时间或 thread 证据的任务统一中断，禁止自动重放。
- 任务记录、卡片 phase 和 Codex 启动证据采用保守对账；终态优先、启动证据优先于排队，并刷新卡片与审计。
- SQLite 迁移前创建带校验和的一致性备份，迁移失败自动回滚；另提供手动 backup/list/rollback。
- 任务、审计、事件、附件、日志和备份分别按数量、时长或容量限额保留；默认不上传遥测。
- 加密离线中继延后到中心控制面阶段，不进入本地优先 MVP。

详细恢复矩阵、重试、备份格式和自检边界见 [D8 可靠性与恢复](requirements/D8_RELIABILITY_AND_RECOVERY.md)。

### 非目标

- 在完全断电时继续运行本地 Codex。

---

## D9. 团队协作

### 用户目标

团队成员在不共享错误上下文、不越权的前提下共同使用一台或多台开发设备。

### 当前已有

- 成员角色、项目 ACL、成员级群聊隔离和审计。
- 本人任务与管理员视图。

### MVP 需求

- 清楚展示任务发起人和当前控制者。
- 任务转交与管理员接管需要显式操作。
- 团队 Runbook 可以预设项目、参数、权限和审批。
- 成员、项目和资源使用情况可查看。
- 多设备时根据项目路由到正确设备。

### 验收标准

- 两名成员同时使用不会共享 Thread、项目或设置。
- 管理动作都有审计记录。
- 团队模板不能绕过个人和项目权限上限。

### 已确认决策

- 私聊用于私密任务，群聊用于可见协作；群聊仍默认按成员隔离，不共享 Codex thread、项目、设置或队列。
- 任务保留不可变发起人和可变当前控制者；转交、发起人收回和管理员接管都必须显式操作并记录审计。
- 团队工作台只展示成员、角色、任务状态、项目负载和 token 聚合，不展示提示词、结果、Diff、附件或原始 open_id。
- Runbook 使用仓库根目录 `.feishu-codex-runbooks.json`；支持参数、默认值和模型/推理/权限预设，但只能降低权限，不能预授权外部动作。
- beta.4 一个实例只代表一台设备；多设备项目路由延后到带实例身份和离线协议的中心控制面。

详细角色矩阵、交接状态机、Runbook 格式和验收见 [D9 团队协作](requirements/D9_TEAM_COLLABORATION.md)。

### 非目标

- 完整企业 IAM 平台。

---

## D10. 维护与开源生态

### 用户目标

维护者能够安全发布、升级、诊断和扩展，贡献者可以快速理解边界并提交修改。

### 当前已有

- 可发布 npm 包和双 CLI 入口。
- tarball 干净安装测试。
- CI、npm provenance 与 GitHub Release 工作流。
- README、安装、安全、架构、团队部署和贡献文档。

### MVP 需求

- 稳定配置格式和版本迁移约定。
- Codex 与 lark-cli 兼容矩阵。
- `upgrade`、`backup`、`rollback` 和 `support-bundle`。
- 公共 Roadmap、Good First Issue 和发布节奏。
- 中英文入口文档和完整演示。

### 验收标准

- 新版本可以在保留用户数据的情况下升级和回退。
- npm 包、GitHub tag 和 Release 版本完全一致。
- 外部贡献者可以只根据 CONTRIBUTING 运行全部检查。

### 已确认决策

- 稳定版采用 Semantic Versioning；`1.x` 保证文档化 CLI、配置 v1、策略 v1、运行手册 v1 和持久状态自动迁移。
- 当前不开放公共插件 API，先保留内部适配边界；安全关键内部模块不作为扩展接口。
- 其他 IM/Agent 适配器暂不进入主包，避免飞书核心体验尚未稳定时扩大兼容和安全面。
- 默认不收集匿名遥测；本地指标不自动上传，未来遥测必须明确 opt-in 且排除代码、提示词、身份和路径。
- 升级默认只预览；执行前备份、阻止活动任务、验证新服务，失败时恢复数据和仍可用的旧服务包。
- npm 精确固定 Codex 与 lark-cli 版本，兼容矩阵和发布物由 release check 自动对齐。

详细版本契约、升级状态机、发布门禁和贡献路径见 [D10 维护与开源生态](requirements/D10_MAINTENANCE_AND_ECOSYSTEM.md)。

### 非目标

- 在核心体验稳定前建设大型插件市场。

## 4. 横向产品原则

所有方向共同遵守：

1. 默认安全，提升权限必须显式。
2. 没有本地设备就不承诺执行任务。
3. 每个状态都要说明用户下一步能做什么。
4. 飞书只展示当前决策需要的信息。
5. 失败状态必须可恢复、可诊断。
6. 不依赖实验性 Codex 能力完成核心闭环。
7. 默认不上传遥测、代码、完整提示词和执行日志。

## 5. 产品指标

### 北极星指标

> 通过飞书发起，并安全产出可审阅结果的 Codex 任务成功率。

### 辅助指标

- 从安装开始到首个成功任务的时间。
- 首次安装成功率。
- 任务完成率、失败率和恢复率。
- 用户主动停止与异常中断比例。
- 审批等待时间。
- 错误自助解决率。
- 一周内再次使用率。

所有指标默认仅保存在本地；如果未来提供遥测，必须明确、可关闭且不包含代码和提示词正文。

## 6. 讨论与落地顺序

依赖顺序建议：

1. D1 安装与首次连接。
2. D2 设备与连接状态。
3. D3 项目与会话。
4. D4 远程任务执行。
5. D5 Codex 原生交互。
6. D6 结果与代码审阅。
7. D7 权限与安全治理。
8. D8 可靠性与恢复。
9. D9 团队协作。
10. D10 维护与开源生态。

每个方向完成以下步骤后才能进入开发：

```text
确认用户问题
  → 确认 MVP 边界
  → 回答待讨论决策
  → 写出可验证验收标准
  → 拆分开发任务
  → 实现与验证
```

## 7. 决策记录模板

讨论一个方向时，在对应章节追加：

```markdown
### 决策记录 YYYY-MM-DD

- 决策：
- 原因：
- MVP 包含：
- MVP 不包含：
- 验收标准：
- 后续版本：
```