feishu-codex-console 1.0.0-beta.6

package/docs/requirements/D1_INSTALLATION_AND_FIRST_CONNECTION.md

@@ -0,0 +1,479 @@
+# D1 安装与首次连接 PRD
+
+> 产品：Feishu Codex Console
+> 状态：`beta.4` 闭环已完成
+> 优先级：P0
+> 目标版本：`1.0.0-beta.4`
+> 依赖：Node.js 22+、Codex 登录态、用户已有飞书自建应用
+
+## 1. 已确认边界
+
+MVP 绑定用户已有的飞书自建应用，不替用户自动创建飞书应用。
+
+初始化向导负责：
+
+- 检查本机运行环境。
+- 引导绑定已有飞书应用。
+- 验证 Bot 身份、所需权限和事件能力。
+- 自动识别安装者的 `open_id`、测试会话的 `chat_id` 和会话类型。
+- 选择默认项目和权限预设。
+- 生成私有配置。
+- 安装后台服务。
+- 发送第一张测试卡和新手引导入口。
+
+初始化向导不负责：
+
+- 替用户注册飞书账号或创建企业。
+- 绕过企业管理员审批应用权限。
+- 自动发布飞书应用版本。
+- 保存 App Secret 到项目仓库或桥接服务 `.env`。
+- 为用户修改 Codex 或操作系统账号安全策略。
+
+## 2. 用户问题
+
+当前能力可以运行，但第一次安装涉及飞书应用、Bot 身份、事件、成员 ID、项目路径、权限模式和后台服务。新用户不知道步骤之间的依赖，也无法判断失败发生在哪一层。
+
+需要把“阅读文档并手工拼装配置”变成一个可暂停、可恢复、可验证的安装流程。
+
+## 3. 目标
+
+### 业务目标
+
+- 新用户在 10 分钟内从运行安装命令到收到第一张飞书测试卡。
+- 降低因权限、事件订阅、身份 ID 和配置文件错误造成的安装失败。
+- 让个人模式和团队模式使用同一套向导。
+
+### 用户目标
+
+- 明确知道当前处于哪一步。
+- 每一步只填写当前需要的信息。
+- 失败时知道原因、修复动作和如何继续。
+- 不需要理解全部环境变量。
+
+### 安全目标
+
+- 默认使用个人安全或团队安全预设。
+- 高级模式需要单独确认。
+- 不在命令参数、日志和 Git 仓库中暴露 Secret。
+- 配置文件为 `0600`，数据目录为 `0700`。
+
+## 4. 非目标
+
+- 支持 Windows 后台服务。
+- 自动申请企业管理员权限。
+- 默认启用网络、Web 搜索或完全访问。
+- 在安装阶段配置所有高级参数。
+- 为多个 IM 平台提供统一安装器。
+
+## 5. 用户故事
+
+### 个人开发者
+
+> 作为个人开发者，我希望只提供已有飞书应用和默认项目，就能在飞书收到测试卡并开始使用。
+
+### 团队维护者
+
+> 作为团队维护者，我希望在安装时明确区分管理员、操作者和只读成员，并确保普通成员不能获得完全访问。
+
+### 已有用户
+
+> 作为已经通过源码运行的用户，我希望重新运行向导时识别现有配置，不覆盖未知配置，也不破坏 SQLite 数据。
+
+### 故障用户
+
+> 作为安装失败的用户，我希望修复某一步后从该步骤继续，而不是重新输入全部内容。
+
+## 6. 端到端安装流程
+
+```text
+运行 npx feishu-codex-console init
+  ↓
+欢迎页与已有安装检测
+  ↓
+本机环境检查
+  ↓
+绑定并验证已有飞书应用
+  ↓
+验证权限、事件和 CardKit
+  ↓
+发送测试消息，自动识别用户与会话
+  ↓
+选择个人安全 / 团队安全 / 高级模式
+  ↓
+选择默认项目与扫描根目录
+  ↓
+查看安装摘要并确认
+  ↓
+备份旧配置并原子写入新配置
+  ↓
+运行 doctor
+  ↓
+安装后台服务并等待健康
+  ↓
+向测试会话发送成功卡
+  ↓
+进入飞书新手引导
+```
+
+## 7. 分步需求
+
+### Step 0：欢迎与安装状态
+
+展示：
+
+- 产品一句话说明。
+- 预计耗时。
+- 本次会修改的位置。
+- 是否检测到已有配置、服务和数据。
+
+行为：
+
+- 新安装进入完整流程。
+- 未完成安装从最后成功步骤继续。
+- 已安装用户进入“检查、修改配置、修复、重新安装服务”菜单。
+
+### Step 1：本机环境检查
+
+检查：
+
+- Node.js 版本。
+- 当前操作系统和后台服务支持情况。
+- Codex CLI 是否可执行。
+- `codex login status` 是否成功。
+- 安装目录、配置目录和数据目录是否安全可写。
+- Git 是否可用。
+
+结果等级：
+
+- 通过：继续。
+- 提醒：不影响核心流程，可继续。
+- 阻塞：给出修复命令，修复后重新检查。
+
+### Step 2：绑定飞书应用
+
+如果 Bot 身份已配置：
+
+- 展示已绑定应用的脱敏信息。
+- 允许继续使用或重新绑定。
+
+如果尚未配置：
+
+- 解释需要已有自建应用。
+- 提供“启动 lark-cli 配置流程”。
+- 用户确认后运行 `lark-cli config init`。
+- Secret 通过安全输入或 stdin 交给 lark-cli，不回显、不写入桥接配置。
+
+### Step 3：验证飞书能力
+
+必须验证：
+
+- Bot 身份 Token 可用。
+- 能消费 `im.message.receive_v1`。
+- 能接收 `card.action.trigger`。
+- 具备消息回复能力。
+- 具备 `cardkit:card:write`。
+- 应用事件接收方式支持长连接。
+
+验证结果必须指出：
+
+- 缺少的具体权限或事件。
+- 应在飞书开发者后台的哪个位置修复。
+- 修改后是否需要重新发布应用版本。
+- “重新检查”入口。
+
+### Step 4：自动识别安装者
+
+流程：
+
+1. 启动最多接收一个事件、最多等待两分钟的只读监听。
+2. 提示用户在飞书中给机器人发送任意测试消息。
+3. 提取 `sender_id`、`chat_id` 和 `chat_type`。
+4. 不保存测试消息正文。
+5. 展示脱敏后的识别结果并要求用户确认。
+
+规则：
+
+- 私聊用于确认安装者身份，不加入群白名单。
+- 群聊用于确认身份，并默认建议把该群加入白名单。
+- 自动识别超时后允许重新监听或手工输入。
+- 团队模式仍必须显式确认管理员。
+
+### Step 5：权限预设
+
+默认顺序：
+
+1. 个人安全（推荐）。
+2. 团队安全。
+3. 高级模式。
+
+每个预设展示：
+
+- 谁可以使用。
+- 可以修改什么。
+- 是否允许网络。
+- 是否允许群聊。
+- 哪些动作仍需要审批。
+
+高级模式必须输入确认文字或完成单独确认步骤，不能通过默认回车启用。
+
+### Step 6：项目配置
+
+必填：
+
+- 默认项目目录。
+
+可选：
+
+- 同步 Codex 桌面端保存项目。
+- 增加一个或多个扫描根目录。
+
+验证：
+
+- 路径存在并解析真实路径。
+- 默认情况下要求 Git 仓库。
+- 扫描根目录不能是文件或不安全符号链接。
+- 展示预计发现的项目数量和前几个项目。
+
+### Step 7：安装摘要
+
+确认前展示：
+
+- 实例名称。
+- 飞书安装者和测试会话。
+- 权限预设。
+- 默认项目和扫描根目录。
+- 配置文件和数据目录。
+- 将安装的后台服务名称。
+
+不展示：
+
+- App Secret。
+- 完整 Token。
+- 测试消息正文。
+
+### Step 8：安全写入配置
+
+要求：
+
+- 新配置写入临时文件后原子替换。
+- 配置文件权限固定为 `0600`。
+- 数据目录权限固定为 `0700`。
+- 已有配置先备份，并记录备份路径。
+- 只管理已知键，保留未知高级配置。
+- 任一步失败时不留下半写入配置。
+
+### Step 9：自检与服务安装
+
+顺序：
+
+1. 运行完整 `doctor`。
+2. 有失败项时停止，不安装服务。
+3. 全部阻塞项通过后安装 LaunchAgent 或 systemd user service。
+4. 等待进程启动和连接健康。
+5. 检查服务使用的是刚生成的配置文件。
+
+### Step 10：发送测试卡
+
+向刚才识别的会话发送一张安装成功卡：
+
+- 设备名称和在线状态。
+- 默认项目。
+- 当前权限预设。
+- “开始新手引导”。
+- “打开控制台”。
+- “查看安装诊断”。
+
+测试卡发送成功，才将安装状态标记为完成。
+
+## 8. 安装状态模型
+
+```text
+not_started
+  → environment_ready
+  → feishu_bound
+  → capabilities_verified
+  → identity_discovered
+  → preferences_confirmed
+  → config_written
+  → service_running
+  → test_card_delivered
+  → completed
+```
+
+每一步保存：
+
+- 状态名称。
+- 完成时间。
+- 非敏感输入摘要。
+- 最近错误类型。
+- 是否可以安全重试。
+
+不保存 App Secret、Token 和测试消息正文。
+
+## 9. 异常与恢复
+
+| 异常 | 用户看到的结果 | 可执行动作 |
+|---|---|---|
+| Node 版本过低 | 当前版本和最低要求 | 打开升级说明、重新检查 |
+| Codex 未登录 | 登录状态失败 | 运行登录、重新检查 |
+| 飞书 Bot 无效 | 当前应用身份不可用 | 重新绑定应用 |
+| 权限缺失 | 缺少的权限名称 | 打开配置说明、重新检查 |
+| 事件未启用 | 缺少的事件名称 | 打开事件订阅说明、重新检查 |
+| 身份监听超时 | 未收到测试消息 | 重新监听、手工输入 |
+| 项目路径无效 | 具体路径和原因 | 重新选择 |
+| 配置已存在 | 检测到现有安装 | 检查、备份后更新、退出 |
+| doctor 失败 | 失败项与原因 | 修复、重新检查 |
+| 服务启动失败 | 服务名和日志位置 | 查看日志、重新安装 |
+| 测试卡失败 | 服务已启动但飞书发送失败 | 重试发送、运行诊断 |
+
+## 10. 功能需求编号
+
+| 编号 | 需求 | 优先级 |
+|---|---|---|
+| D1-FR-001 | 检测新安装、未完成安装和已有安装 | P0 |
+| D1-FR-002 | 分级检查本机环境 | P0 |
+| D1-FR-003 | 绑定和重新绑定已有飞书应用 | P0 |
+| D1-FR-004 | 验证消息、事件和 CardKit 能力 | P0 |
+| D1-FR-005 | 自动发现安装者和测试会话 | P0 |
+| D1-FR-006 | 提供三档权限预设 | P0 |
+| D1-FR-007 | 验证默认项目和扫描根目录 | P0 |
+| D1-FR-008 | 展示脱敏安装摘要 | P0 |
+| D1-FR-009 | 原子写入、备份并保留未知配置 | P0 |
+| D1-FR-010 | doctor 通过后安装后台服务 | P0 |
+| D1-FR-011 | 发送测试卡并进入新手引导 | P0 |
+| D1-FR-012 | 保存非敏感安装进度并支持恢复 | P1 |
+| D1-FR-013 | 提供非交互式安装参数 | P1 |
+| D1-FR-014 | 提供现有源码安装迁移入口 | P1 |
+
+## 11. 验收标准
+
+### 新安装
+
+- 给定已正确配置的飞书应用和已登录 Codex，新用户可以在 10 分钟内收到测试卡。
+- 用户无需手工编辑 `.env`。
+- 安装结果可以通过 `doctor` 和 `status` 再次验证。
+
+### 默认安全
+
+- 默认权限是 `workspace-write`。
+- 网络和 Web 搜索默认关闭。
+- 高级模式不能被误触启用。
+- App Secret 不进入桥接配置、日志或进程参数。
+
+### 可恢复
+
+- 身份监听超时后可以重试，而不丢失之前步骤。
+- doctor 失败时不安装或启动后台服务。
+- 已有配置更新前自动备份，未知配置保留。
+- 安装进程被中断后可以从最后安全步骤恢复。
+
+### 多平台
+
+- macOS 使用 LaunchAgent。
+- Linux 使用 systemd user service。
+- 不支持的平台在写配置前明确阻塞。
+
+### 自动化
+
+- 单元测试覆盖配置生成、身份事件解析和状态迁移。
+- tarball 测试从真实 npm 包完成非交互初始化。
+- CI 验证安装脚本、包文件和权限模式。
+
+## 12. 当前实现差距
+
+| 能力 | 当前状态 | 需要补充 |
+|---|---|---|
+| Node/Codex/Bot 检查 | 已实现 | 输出结构化检查结果 |
+| 三档权限预设 | 已实现 | 安装摘要和更清楚的影响说明 |
+| 身份自动发现 | 已实现 | 确认页、重试和进度恢复 |
+| 私有配置目录 | 已实现 | 原子写入、备份和未知键保留已完成 |
+| doctor | 已实现 | 能力检查与 `--fix` |
+| 后台服务 | 已实现 | 安装后等待双事件消费者健康，并核对实例、PID、心跳和配置路径 |
+| npm 干净安装测试 | 已实现 | 加入 macOS 实机发布前验证 |
+| 飞书权限/事件验证 | 已实现 | 已探测 Bot、消息事件和卡片事件；测试卡验证 CardKit 写入 |
+| 测试卡 | 已实现 | 私聊自动发送，群聊确认，失败不标记完成 |
+| 断点续装 | 部分完成 | 已持久化非敏感进度；仍需按步骤直接恢复 |
+| 旧安装迁移 | 已实现 | 复制旧源码配置、复用旧数据并在健康验证后切换服务 |
+
+## 13. 开发任务拆分
+
+### 第一批：安装状态与安全写入
+
+- [x] D1-T01：实现安装状态文件和状态迁移。
+- [x] D1-T02：解析已有配置，区分已知键和未知键。
+- [x] D1-T03：配置原子写入、`0600` 修正和自动备份。
+- [x] D1-T04：检测已有服务和已有数据。
+
+### 第二批：飞书能力验证
+
+- [x] D1-T05：定义消息、事件、卡片所需能力清单。
+- [x] D1-T06：实现 Bot、事件流和 CardKit 探测。
+- [x] D1-T07：把缺失能力映射成具体修复说明。
+- [x] D1-T08：为能力探测增加可替换测试适配器。
+
+### 第三批：服务闭环
+
+- [x] D1-T09：服务安装后等待健康状态。
+- [x] D1-T10：验证服务实际加载的配置文件。
+- [x] D1-T11：发送安装成功测试卡。
+- [x] D1-T12：测试卡跳转到飞书新手引导和控制台。
+
+### 第四批：迁移与自动化
+
+- [x] D1-T13：增加旧源码安装迁移。
+- [x] D1-T14：增加安装中断和恢复集成测试。
+- [x] D1-T15：增加 Linux/macOS 发布前检查清单。
+- [x] D1-T16：更新演示、排错和维护者文档。
+
+## 14. 仍需产品确认
+
+### 决策 A：安装交互形式（已确认）
+
+推荐：`beta.4` 保持 CLI 向导，不同时建设本地网页安装器。
+
+理由：
+
+- 当前用户是开发者和团队维护者。
+- CLI 更容易跨 macOS/Linux、测试和发布。
+- 本地网页仍要处理进程、权限、Secret 和服务安装，复杂度较高。
+- 等安装流程稳定后，可以让网页调用同一套安装状态机。
+
+### 决策 B：测试卡发送（已确认）
+
+确认：私聊自动发送；群聊在安装摘要中再次确认。提供 `--no-test-card` 关闭自动发送。
+
+### 决策 C：已有配置更新（已确认）
+
+确认：默认备份后合并已知键，保留未知键；只有 `--force-reset` 才完整重建。
+
+### 决策 D：安装完成标准（已确认）
+
+确认：后台服务健康且测试卡发送成功才算完成。使用 `--no-test-card` 时，以服务健康和完整 doctor 通过作为完成标准；仅写入配置不算安装成功。
+
+## 15. 决策记录
+
+### 决策记录 2026-07-16
+
+- 决策：MVP 绑定用户已有的飞书自建应用，不自动创建应用。
+- 原因：自动创建会引入企业管理员权限、租户差异和外部账号状态，扩大首版边界。
+- MVP 包含：应用绑定、身份验证、能力检查、测试消息、服务安装和测试卡。
+- MVP 不包含：创建企业、创建应用、管理员审批和自动发布飞书应用版本。
+- 验收标准：给定已有应用，新用户可以在 10 分钟内收到测试卡。
+- 后续版本：评估本地网页安装器和更深的开放平台自动化。
+
+### 决策记录 2026-07-16 · D1-A
+
+- 决策：`beta.4` 只提供 CLI 安装向导，不同时建设本地网页安装器。
+- 原因：目标用户是开发者和团队维护者；CLI 更容易跨 macOS/Linux、自动测试和发布。
+- MVP 包含：交互式 CLI、非交互参数、可恢复安装状态和结构化错误。
+- MVP 不包含：本地 Web 服务、浏览器安装页面和两套交互层。
+- 验收标准：CLI 覆盖新安装、继续安装、检查、修复和重新安装服务。
+- 后续版本：安装状态机稳定后，网页安装器可以复用同一套底层能力。
+
+### 决策记录 2026-07-16 · D1-B/C/D
+
+- 测试卡：私聊自动发送，群聊再次确认；支持 `--no-test-card`。
+- 配置更新：默认备份、合并已知键并保留未知键；`--force-reset` 才完整重建。
+- 完成标准：doctor 通过、服务健康并成功发送测试卡；禁用测试卡时以服务健康为准。
+- 原因：安装完成必须证明真实端到端链路可用，同时避免覆盖维护者的高级配置或在群聊中意外发消息。
+- MVP 不包含：自动向未参与身份发现的聊天发送消息。

package/docs/requirements/D2_DEVICE_AND_CONNECTIVITY.md

@@ -0,0 +1,54 @@
+# D2：设备与连接状态
+
+状态：`beta.4` 闭环已完成
+范围：`beta.4` 设备可用性闭环
+日期：2026-07-16
+
+## 1. 产品目标
+
+用户在飞书打开控制台后，5 秒内能判断这台本地设备现在是否适合执行 Codex 任务；异常时能看到原因、状态采样时间和下一步动作，而不是把旧卡片误认为实时在线证明。
+
+## 2. 已确认决策
+
+- 第一版一个桥接实例只代表一台设备；多设备路由留到存在中心控制面之后。
+- 状态卡必须显示绝对采样时间和本人最后一次成功任务时间，不显示提示词内容。
+- 本地服务已经离线时无法主动更新飞书卡或发送离线提醒；不为此引入公网入站服务，也不伪装成实时云监控。
+- 服务恢复后优先更新已有控制台卡，再按会话去重发送一次恢复通知。
+- Remote Ready 保持管理员显式开启，不默认开启，也不承诺远程开机或绕过合盖策略。
+
+## 3. 状态模型
+
+| 状态 | 含义 | 是否可发任务 | 卡片动作 |
+|---|---|---:|---|
+| 在线 | 消息与卡片事件可用，Codex 正常或可按需启动 | 是 | 完整控制 |
+| 连接中 | 消息事件尚未就绪 | 否 | 不显示虚假按钮 |
+| 部分可用 | 文字消息可用，卡片回调不可用 | 是，建议文字 | 隐藏按钮 |
+| 离线 | 健康心跳过期 | 否 | 展示电源/网络/服务恢复说明 |
+| 异常 | 飞书在线，但 Codex 最近启动失败 | 否 | 刷新、重连 Codex |
+| 维护中 | 服务在线但管理员暂停新任务 | 否 | 查看状态，等待恢复 |
+
+## 4. 核心流程
+
+1. 收到“状态”或控制台卡刷新请求。
+2. 汇总消息消费者、卡片消费者、Codex app-server、任务队列、电源和 Remote Ready。
+3. 生成唯一权威设备状态与可操作性。
+4. 展示采样时间、本人最后成功任务和对应恢复建议。
+5. 只在回调链路可用时展示按钮；Codex 异常时提供显式重连。
+6. 服务重启恢复后，更新持久化的旧控制台卡并去重通知。
+
+## 5. 开发任务
+
+- [x] D2-T01：定义在线、连接中、部分可用、离线、异常和维护状态。
+- [x] D2-T02：实现纯函数状态推导和状态测试。
+- [x] D2-T03：控制台展示采样时间和本人最后成功任务。
+- [x] D2-T04：异常状态隐藏不可执行动作。
+- [x] D2-T05：增加 Codex 重连动作。
+- [x] D2-T06：持久化设备控制台卡引用。
+- [x] D2-T07：服务恢复后原卡更新和通知去重。
+- [x] D2-T08：补齐重启、过期心跳和恢复集成测试。
+
+## 6. 非目标
+
+- 远程开机、远程解锁或绕过公司设备策略。
+- 在没有外部在线控制面的情况下承诺实时离线推送。
+- beta.4 内自动跨多台电脑路由项目和任务。

package/docs/requirements/D3_PROJECTS_AND_SESSIONS.md

@@ -0,0 +1,107 @@
+# D3：项目与会话
+
+状态：`beta.4` 闭环已完成
+优先级：P0
+日期：2026-07-16
+
+> 2026-07-17 更新：群聊话题现在是一等工作会话。群顶层普通 prompt 以根消息创建独立会话键，串内回复恢复同一个 Codex thread；详细规则见 [V4 工作区会话交互模型](../V4_WORKSPACE_SESSION_FLOW.md)。以下按成员隔离规则继续用于群主会话和兼容模式。
+
+## 1. 产品目标
+
+用户在飞书里发起任务前，能够明确确认本地执行目录、Git 分支、未提交状态和 Codex 上下文；项目重名、收藏排序、服务重启或多人共用时，都不能把任务静默送进错误的目录或会话。
+
+## 2. 已确认决策
+
+- 一个飞书会话只有一个当前项目，但允许快速切换；群聊默认按成员隔离当前项目和 Codex thread。
+- 项目列表始终展示项目名和可辨识路径。用户目录使用 `~` 缩写；重名项目依靠路径区分，不只显示文件夹名。
+- 收藏和最近使用按成员保存，不成为团队全局偏好，也不能由管理员替成员修改。
+- 收藏优先、最近使用其次；卡片顺序、文字回退列表和 `/use <编号>` 必须使用同一顺序。
+- 卡片下拉切换始终显示确认弹窗。文字切换在存在运行任务、排队任务或已保存 thread 时，需要发送 `确认切换 <项目>`。
+- 切换项目会停止该飞书会话中的未完成任务，并清空当前保存的 Codex 上下文；不会删除项目文件或 Codex 历史 thread。
+- Git 状态只读取当前项目，使用一次有 3 秒超时的只读 `git status`；读取失败不阻塞项目切换。
+- 新建 Codex thread 使用首条有效任务自动命名；名称写入 Codex 原生 thread，因此飞书和本机看到同一个名称。
+- 团队成员只能看到项目 ACL 允许的项目。历史 thread 默认只展示本人通过桥接创建或恢复的记录；管理员可做受审计的团队排障。
+
+## 3. 核心流程
+
+```text
+发送“项目”
+  → 按成员 ACL 过滤项目
+  → 收藏优先、最近使用其次排序
+  → 展示当前路径、分支、未提交文件数
+  → 搜索或选择目标项目
+  → 明确提示运行任务、队列和上下文影响
+  → 用户确认
+  → 停止当前会话未完成任务
+  → 切换项目并清空保存的 thread
+  → 记录最近使用并更新原卡片
+```
+
+恢复会话：
+
+```text
+发送“会话”
+  → 只读取当前项目的 Codex thread
+  → 应用成员可见性规则
+  → 展示名称、最近更新时间和任务摘要
+  → 用户选择并确认恢复
+  → 停止当前未完成任务
+  → 保存选中的原生 thread ID
+  → 下一条任务通过 thread/resume 继续
+```
+
+## 4. 交互与数据规则
+
+### 项目标识
+
+- 卡片当前项目区同时展示名称和 `displayPath`。
+- 下拉选项同时包含名称、类型和路径，并对收藏、最近使用增加视觉标记。
+- 最多在卡片展示 100 项；超过上限时，文字命令仍可按名称或路径搜索全部授权项目。
+- 模糊匹配到多个项目时返回候选名称和路径，不自动选择第一个。
+
+### Git 状态
+
+- 展示当前分支或 detached HEAD。
+- 展示未提交文件数量以及相对上游的 ahead/behind。
+- 不执行 fetch，不访问网络，不改变 index，也不持有 Git 锁。
+
+### 收藏与最近使用
+
+- 唯一键为 `owner_id + project_path`。
+- 最近使用在切换和实际创建任务时更新。
+- ACL 撤销后，对应项目立即从列表、收藏和最近使用结果中消失；保留本地偏好行以便恢复授权后继续使用。
+
+### 会话
+
+- 新 thread 名称取首条任务的第一行，清理 Markdown 前缀并限制长度。
+- 会话中心使用 Codex 原生 name/preview/updatedAt，不复制完整对话到桥接数据库。
+- 项目切换只解除当前飞书会话的 thread 绑定，不归档或删除原生 thread。
+
+## 5. 验收标准
+
+- 同名项目在所有选择入口都能通过路径辨识。
+- 收藏或最近使用改变排序后，`/use 1` 与列表第 1 项保持一致。
+- 存在任务、队列或保存上下文时，普通文字切换不会立即执行。
+- 项目卡能展示当前 Git 分支和未提交文件数；非 Git 目录不显示伪造状态。
+- 无权项目不会出现在卡片、文字回退、模糊搜索、最近使用或会话历史中。
+- 收藏按成员隔离，管理员不能通过他人的卡片修改其偏好。
+- 服务重启后当前项目、收藏、最近使用和 thread 绑定仍然存在。
+- 新建 thread 获得可读名称，恢复后下一轮继续同一个 thread ID。
+
+## 6. 开发任务
+
+- [x] D3-T01：实现当前项目只读 Git 分支、dirty、ahead/behind 采样。
+- [x] D3-T02：项目卡展示可辨识路径、Git 状态和重名辨识信息。
+- [x] D3-T03：实现按成员持久化的收藏、最近使用和访问隔离。
+- [x] D3-T04：统一卡片、文字回退和数字选择器的排序与搜索语义。
+- [x] D3-T05：切换前展示任务、队列和上下文影响，并要求显式确认。
+- [x] D3-T06：为首条任务创建的 Codex thread 自动命名。
+- [x] D3-T07：会话中心展示名称、摘要和更新时间，并恢复原生 thread。
+- [x] D3-T08：补齐 Git 解析、排序、选择、卡片、持久化和命名测试。
+
+## 7. 非目标
+
+- 通过飞书输入任意绝对路径并把它注册成项目。
+- 在项目卡内实现完整 Git 分支管理、提交、拉取或合并。
+- 删除、归档或跨项目搬运 Codex 原生 thread。
+- 在 `beta.4` 引入云端项目索引或多设备项目路由。