feishu-codex-console 1.0.0-beta.6

package/docs/PRODUCT_REQUIREMENTS_MAP.md

@@ -0,0 +1,591 @@
+# Feishu Codex Console 产品需求地图
+
+> 状态：V4 工作区会话模型已确认
+> 当前版本：`1.0.0-beta.4`
+> 产品定位：通过飞书远程、安全、持续地控制本地 Codex。
+
+这份文档是产品需求的唯一入口。每个方向先讨论清楚用户问题、产品边界和验收标准，再进入实现；讨论结论持续回写到对应章节。
+
+## 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 init` 初始化向导。
+- 个人安全、团队安全和高级模式预设。
+- 自动识别 `open_id`、`chat_id` 和会话类型。
+- 私有配置和数据目录。
+- `doctor` 与后台服务安装。
+
+### MVP 需求
+
+- 自动检查 Node、Codex 登录和飞书 Bot 身份。
+- 自动识别当前安装者。
+- 验证消息事件、卡片回调和 CardKit 权限。
+- 自检失败时不安装服务，并给出下一条修复命令。
+- 安装完成后主动生成第一张飞书引导卡。
+- 已有安装可安全重跑，不覆盖未知配置。
+
+### 验收标准
+
+- 新用户仅根据 README 可以完成安装。
+- 安装过程不要求用户手工编辑 30 多个环境变量。
+- 配置文件为 `0600`，数据目录为 `0700`。
+- 安装失败时没有裸堆栈或模糊错误。
+
+### 待讨论决策
+
+- 是否由向导自动创建飞书应用，还是只绑定已有应用？
+- 是否需要浏览器式安装页面，还是 CLI 足够？
+- 安装结束是否自动给用户发送测试卡？
+- 首次安装默认使用个人安全还是根据成员数量判断？
+
+### 非目标
+
+- 自动修改公司飞书管理员策略。
+- 默认使用云端托管服务。
+
+### 决策记录 2026-07-16
+
+- 决策：MVP 绑定用户已有的飞书自建应用，不自动创建应用。
+- 原因：自动创建会引入企业管理员权限、租户差异和外部账号状态，扩大首版边界。
+- MVP 包含：应用绑定、能力检查、身份发现、服务安装和测试卡。
+- MVP 不包含：创建企业、创建应用、管理员审批和自动发布应用版本。
+- 安装交互：`beta.4` 只提供 CLI 向导；网页安装器延后。
+- 测试卡：私聊自动发送、群聊再次确认，允许显式关闭。
+- 配置更新：备份并合并已知键，保留未知高级配置。
+- 完成标准：doctor、服务健康和端到端测试卡全部成功。
+- 详细 PRD：[D1 安装与首次连接](requirements/D1_INSTALLATION_AND_FIRST_CONNECTION.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 不包含：
+- 验收标准：
+- 后续版本：
+```

package/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,65 @@
+# 发布检查清单
+
+这份清单用于预发布版本和稳定版本。Git 标签必须与 `package.json` 版本完全一致。
+
+## 自动门禁
+
+- [ ] Ubuntu 和 macOS 均通过 `npm ci`。
+- [ ] Ubuntu 和 macOS 均通过类型检查和全部单元测试。
+- [ ] Ubuntu 和 macOS 均完成生产构建。
+- [ ] 真实 npm tarball 能在干净目录安装，两个 CLI 名称都可执行。
+- [ ] tarball 演练包含一次安装中断和断点恢复。
+- [ ] tarball 能初始化运行手册且绝不覆盖已有目录，并完成一次不带 `--yes` 的只读升级预览。
+- [ ] `version --json` 与兼容矩阵中的 Codex、lark-cli、配置、状态和 SQLite 版本一致。
+- [ ] `npm run release:check -- v<version>` 通过。
+- [ ] npm 发布使用 provenance，预发布版本进入 `next` dist-tag。
+
+这些门禁由 CI 和 Release workflow 执行；任一平台失败都不会进入 npm publish。
+
+## macOS 实机
+
+- [ ] 使用非开发者的测试账号完成一次全新 `init`。
+- [ ] LaunchAgent 重装后只有一个消息消费者和一个卡片消费者。
+- [ ] `bridge-health.json` 报告正确 PID、实例和配置路径。
+- [ ] 私聊测试卡、新手引导、项目切换和安全首次任务可用。
+- [ ] 服务重启后会话、队列和 SQLite 状态可恢复。
+- [ ] 已启动任务在重启后中断而非重放，任务记录与卡片冲突可以保守对账。
+- [ ] 结构迁移前生成备份；模拟迁移失败后自动恢复旧数据库。
+- [ ] `doctor --fix` 和脱敏诊断包在自定义 `BRIDGE_DATA_DIR` 下可用。
+- [ ] Remote Ready 可以开启和关闭，卸载服务后不残留 `caffeinate`。
+- [ ] 从旧仓库 `.env` 迁移一次，旧数据可读且旧文件未删除。
+- [ ] 从上一 npm 版本执行升级：活动任务被拒绝、排队任务保留、备份 ID 可见、新服务版本和双消费者验证通过。
+- [ ] 模拟新服务健康失败，数据和仍可用的旧包被自动恢复并验证。
+
+## Linux 实机
+
+- [ ] 使用带 systemd user service 的干净账号完成一次全新 `init`。
+- [ ] unit 使用指定 `DOTENV_CONFIG_PATH`，重启和登录后自动恢复。
+- [ ] `journalctl --user` 没有凭据、消息正文或未脱敏标识泄漏。
+- [ ] 私聊测试卡、新手引导、项目切换和安全首次任务可用。
+- [ ] 停止、重新安装和卸载不会删除用户配置与运行数据。
+- [ ] `backup`、`backups`、`stop` 和 `rollback` 流程在 systemd user service 上通过。
+- [ ] 从上一 npm 版本执行一次升级和一次显式允许的降级演练。
+
+## 飞书端到端
+
+- [ ] Bot、消息事件、卡片事件和 CardKit 探测全部通过。
+- [ ] 私聊自动发送测试卡；群聊未确认时不会自动发送。
+- [ ] 管理员、操作者、只读成员和项目 ACL 使用三个测试账号验证。
+- [ ] 两名操作者在群聊完成任务转交、发起人收回和管理员接管；私聊不展示交接控件。
+- [ ] 团队工作台不展示提示词、结果、路径、附件或原始 open_id。
+- [ ] 运行手册固定任务、默认参数一键任务、显式参数命令和无效配置失败关闭均通过。
+- [ ] 运行手册不能提升 sandbox，含提交、推送、部署或 PR 的模板和参数均被拒绝。
+- [ ] 普通操作者无法超过 `CODEX_OPERATOR_SANDBOX_MODE`。
+- [ ] 完全访问模式下，未加入白名单的群聊仍被拒绝。
+- [ ] 提交、推送、发布、部署和 PR/MR 操作仍要求短期确认。
+- [ ] 普通回复四种状态、CardKit 失败文本兜底和终态任务卡失败通知均通过。
+
+## 发布内容
+
+- [ ] `CHANGELOG.md` 包含用户可见变化、迁移影响和已知限制。
+- [ ] README、安装、排错和安全文档与当前 CLI 参数一致。
+- [ ] tarball 不包含 `.env`、SQLite、日志、附件、真实 ID 或个人路径。
+- [ ] GitHub Release notes 清楚标记 prerelease/stable，并给出升级与回滚方法。
+- [ ] 中英文入口、配置参考、兼容矩阵、演示、Roadmap 和 Good First Issue 入口与当前版本一致。
+- [ ] 发布后从 npm 注册表重新安装一次，并核对 CLI 版本和 dist-tag。

package/docs/TEAM_DEPLOYMENT.md

@@ -0,0 +1,35 @@
+# Team deployment
+
+Start with one dedicated Mac or Linux account that owns the approved workspaces and Codex login. Use one Feishu application per bridge instance.
+
+1. Add administrators, operators, viewers, and trusted chat IDs to `.env`.
+2. Keep `FEISHU_GROUP_SESSION_SCOPE=member` unless the group intentionally shares one Codex context.
+3. Set `CODEX_SANDBOX_MODE` to the administrator ceiling and `CODEX_OPERATOR_SANDBOX_MODE` to the lower everyday ceiling.
+4. Define `FEISHU_PROJECT_ACL_JSON` before inviting members if projects contain data with different access rules.
+5. Add `FEISHU_MEMBER_LABELS_JSON` so handoff and team dashboards use recognizable names instead of anonymous member codes.
+6. Review repository runbooks before copying them to `.feishu-codex-runbooks.json`; templates cannot grant full access or pre-authorize external actions.
+7. Move runtime data outside the checkout with `BRIDGE_DATA_DIR`, run `npm run doctor`, and install the service.
+8. Test with one viewer, two operators, and one administrator before broad rollout, including handoff and access revocation.
+
+Automatic onboarding is enabled by default. Each member sees one adaptive welcome card and can reopen it with `新手引导`. The card exposes only the next useful action for that member and keeps deployment identifiers out of the experience. Team usage is introduced as an optional convention: one project per group, new work as a new top-level message, and follow-ups in replies. Set `FEISHU_AUTO_ONBOARDING=false` only when your organization provides a separate onboarding flow.
+
+Operators see only thread history the bridge has associated with their own Feishu identity. Administrators can inspect all Codex threads in an authorized project. A group task can be handed to another operator with project access, but the initiator and execution policy remain unchanged. Queued tasks are re-authorized after every restart; revoked controllers lose control and stale work cannot resume under removed permissions.
+
+Example:
+
+```dotenv
+BRIDGE_INSTANCE_ID=engineering
+BRIDGE_DATA_DIR=/Users/codex-bridge/Library/Application Support/feishu-codex-bridge
+ALLOWED_FEISHU_OPEN_IDS=ou_frontend,ou_backend
+FEISHU_ADMIN_OPEN_IDS=ou_platform_admin
+FEISHU_VIEWER_OPEN_IDS=ou_product
+FEISHU_MEMBER_LABELS_JSON={"ou_platform_admin":"Platform Admin","ou_frontend":"Frontend","ou_backend":"Backend","ou_product":"Product"}
+ALLOWED_FEISHU_CHAT_IDS=oc_engineering
+FEISHU_GROUP_SESSION_SCOPE=member
+FEISHU_AUTO_ONBOARDING=true
+CODEX_SANDBOX_MODE=danger-full-access
+CODEX_OPERATOR_SANDBOX_MODE=workspace-write
+FEISHU_PROJECT_ACL_JSON={"frontend":["ou_frontend","ou_product"],"backend":["ou_backend"]}
+```
+
+The bridge is an execution gateway, not a replacement for operating-system account separation. For mutually untrusted teams, run separate instances under separate system accounts and expose different project roots.