feishu-codex-console 1.0.0-beta.6

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,130 @@
+# 故障排查
+
+先使用安装时的同一份配置运行：
+
+```bash
+feishu-codex-bridge doctor --config /absolute/path/to/default.env
+feishu-codex-bridge status --config /absolute/path/to/default.env
+```
+
+低风险问题可让 doctor 自动修复，并生成一份不覆盖已有文件的脱敏诊断包：
+
+```bash
+feishu-codex-bridge doctor --fix --config /absolute/path/to/default.env
+feishu-codex-bridge doctor \
+  --diagnostics /private/path/feishu-codex-diagnostic.json \
+  --config /absolute/path/to/default.env
+```
+
+诊断包仍可能包含项目名称、时间和错误上下文，提交 Issue 前请人工检查。
+
+也可以让 CLI 自动选择私有文件名：
+
+```bash
+feishu-codex-bridge support-bundle --config /absolute/path/to/default.env
+```
+
+它不会上传文件。复制给维护者前仍需人工复核。
+
+不要在 issue、截图或日志中公开真实 `open_id`、`chat_id`、App Secret、Token、提示词、附件路径或个人目录。
+
+## Bot 身份不可用
+
+```bash
+npx lark-cli config init --new
+npx lark-cli whoami --as bot
+```
+
+已有飞书应用时可以不带 `--new` 重新绑定。桥接服务使用 Bot 身份，不需要把 App Secret 写入 `.env`。
+
+## 消息或卡片事件不可用
+
+确认飞书应用已启用机器人，并通过长连接订阅：
+
+- `im.message.receive_v1`
+- `card.action.trigger`
+
+同时确认应用具有 `im:message:readonly` 和 `cardkit:card:write`。修改权限或事件后，按飞书后台要求发布新应用版本，再重新运行 `init`。
+
+如果检查显示“已有运行中的事件消费者”，说明当前服务已经占用该应用的长连接，这本身不是权限错误。重新安装服务时，安装器会停止旧实例并等待新实例接管。
+
+## 服务启动但安装一直等待
+
+安装器只有在以下条件同时满足时才显示成功：
+
+- 后台 PID 仍存活。
+- 消息和卡片两个事件消费者都已就绪。
+- 实例名称与本次安装一致。
+- 后台进程读取了本次指定的配置文件。
+- 健康心跳没有过期。
+
+慢速机器可先延长等待：
+
+```bash
+feishu-codex-bridge install --config /absolute/path/to/default.env --health-timeout 60s
+```
+
+macOS 日志位于实例数据目录的 `log/bridge.log` 和 `log/bridge.error.log`。Linux 使用：
+
+```bash
+journalctl --user -u feishu-codex-bridge-default -n 200 --no-pager
+```
+
+“读取了另一份配置”通常表示服务曾用不同的 `--config` 安装。使用正确路径重新运行 `install`，不要直接修改 LaunchAgent plist 或 systemd unit。
+
+## 飞书里显示离线
+
+检查电脑是否开机、联网和保持唤醒。在 macOS 飞书控制台中开启“远程就绪”只能防止空闲睡眠，不能绕过合盖睡眠、断电、系统更新或网络中断。
+
+如果健康文件存在但心跳过期，先查看错误日志，再重新安装服务。不要仅修改 `bridge-health.json`；它是运行时只读证据，不是配置入口。
+
+## 数据升级或状态异常
+
+先确认实际版本契约：
+
+```bash
+feishu-codex-bridge version --json
+```
+
+`upgrade` 不带 `--yes` 只展示计划。如果提示仍有运行任务，请在飞书等待完成或显式停止，不要强杀服务绕过检查。升级失败信息会保留升级前备份 ID；自动恢复也失败时，按下方手工流程恢复。
+
+查看已有备份：
+
+```bash
+feishu-codex-bridge backups --config /absolute/path/to/default.env
+```
+
+数据库迁移前会自动生成一致性快照；迁移任一步失败会恢复旧快照并拒绝启动。需要手工回滚时：
+
+```bash
+feishu-codex-bridge stop --config /absolute/path/to/default.env
+feishu-codex-bridge rollback \
+  --backup <backup-id> \
+  --yes \
+  --config /absolute/path/to/default.env
+feishu-codex-bridge install --config /absolute/path/to/default.env
+```
+
+回滚前还会创建 `before-rollback` 安全备份。不要在服务仍运行时复制或替换 `state.sqlite`、`-wal`、`-shm` 文件。
+
+## 重跑安装器发现旧数据
+
+这是保护行为。`init` 会展示已有配置、服务、数据和最近健康状态，并在更新配置前创建 `0600` 备份。未知高级配置默认保留；只有明确使用 `--force-reset` 才完整重建。
+
+旧源码安装使用：
+
+```bash
+npx feishu-codex-console migrate --from /absolute/path/to/old/source
+```
+
+迁移不会删除旧 `.env` 或数据。新服务通过验证后再手工归档旧目录。
+
+## 完全访问模式问题
+
+`danger-full-access` 只是服务权限上限，不会自动允许普通成员获得同等权限，也不会取消提交、推送、发布、部署等外部动作的确认。团队部署应检查：
+
+- 管理员、操作者、只读成员是否明确分开。
+- `CODEX_OPERATOR_SANDBOX_MODE` 是否仍为 `workspace-write`。
+- 群聊是否加入 `ALLOWED_FEISHU_CHAT_IDS`。
+- 项目根目录和 ACL 是否只覆盖必要仓库。
+- 网络、Web 搜索和额外环境变量是否保持最小开放。

package/docs/V4_WORKSPACE_SESSION_FLOW.md

@@ -0,0 +1,232 @@
+# 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
+      ├─ 自然问答
+      ├─ 分析与写文件
+      ├─ 代码修改
+      └─ 必要时出现审批/追问卡
+```
+
+### 兼容模式
+
+首阶段不强制自动创建项目群。已有私聊和群聊继续可用：
+
+- 私聊维持一个当前工作会话。
+- 群聊中的顶层普通 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，但不复制或重建上下文。
+
+## 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：项目群工作区
+
+- [ ] 私聊首页支持创建、恢复和搜索工作区。
+- [ ] 可选自动创建项目群并邀请成员/机器人。
+- [ ] 置顶工作区控制卡成为项目唯一控制面。
+- [ ] 实现本机打开、归档和跨设备接管。
+
+### Phase 4：团队化
+
+- [ ] 话题级转交、接管和观察者模式。
+- [ ] 工作区模板、团队策略和审计导出。
+- [ ] 多设备路由与同项目锁冲突提示。
+
+## 10. V4 验收标准
+
+1. 在群里同时打开两个话题，能稳定对应两个不同 Codex thread。
+2. 简单问题只出现一条持续更新的普通回复，不出现绿色任务完成卡。
+3. 同一话题继续提问会沿用原 Codex thread；新话题不会继承旧 thread。
+4. 任何任务都能从持久记录恢复，但用户不需要理解 Task 才能正常使用。
+5. 卡片只在控制、审批、追问、长任务和异常中出现。
+6. 多项目执行时，用户仅凭群名和话题标题即可辨认项目与上下文。
+7. 原有私聊、队列、安全门禁、审批、任务中心和审计数据保持兼容。

package/docs/requirements/D10_MAINTENANCE_AND_ECOSYSTEM.md

@@ -0,0 +1,103 @@
+# D10 维护与开源生态
+
+## 1. 用户问题
+
+Feishu Codex Console 会长期运行在真实开发机上。安装者需要在不理解源码、不丢失队列和会话的前提下升级、诊断和回退；维护者需要确定发布物与运行时依赖一致；贡献者需要从一个清楚、可测试的小改动进入项目。
+
+## 2. 产品目标
+
+1. 一条命令看懂版本与兼容性，一条命令生成脱敏支持包。
+2. 升级默认只预览；执行前备份，执行后验证，失败尽可能自动回退。
+3. 配置、状态、SQLite、仓库策略和运行手册都有显式版本。
+4. npm tarball 是真实安装单位，而不是只能从维护者源码目录运行。
+5. 贡献者只根据公开文档即可完成检查、打包和提交。
+
+## 3. 已确认产品决策
+
+- 稳定版采用 Semantic Versioning。`1.x` 保证已文档化 CLI、配置 v1、策略 v1、运行手册 v1 和自动状态迁移；内部 TypeScript 模块不承诺为公共 API。
+- npm 包精确固定 `@openai/codex` 与 `@larksuite/cli`。升级依赖必须经过跨平台、tarball 和真实飞书/Codex 验证。
+- 当前不开放插件 API。扩展点先保持为内部适配边界，直到飞书核心协议和安全模型稳定。
+- 其他 IM/Agent 适配器暂不进入主包；未来需保持核心任务域与传输层解耦后再独立评估。
+- 默认不收集匿名遥测。安装、任务和恢复指标只保存在本地；未来遥测必须显式选择加入且不含代码、提示词、Diff、身份 ID 或路径。
+- 一个 npm 包升级一个本机实例。多设备编排不与本地包升级混在一起。
+
+## 4. 版本契约
+
+| 契约 | 当前版本 | 不兼容处理 |
+|---|---:|---|
+| 配置文件 | 1 | 未填写按 v1；未知未来版本拒绝启动 |
+| 持久状态 | 6 | 逐版本迁移；迁移前备份；失败恢复 |
+| SQLite schema | 1 | `PRAGMA user_version` 校验和事务化迁移 |
+| 仓库策略 | 1 | 整份失败关闭 |
+| 运行手册 | 1 | 整份失败关闭，替换参数后再次检查 |
+| 健康文件 | 1 | 安装器只接受已知健康格式 |
+
+新增环境变量必须有安全默认值，并同步 `.env.example`、配置参考、向导和测试。删除或重新解释配置键需要主版本和迁移说明。
+
+## 5. 安全升级状态机
+
+```text
+读取当前健康与版本
+  → 有活动任务：拒绝
+  → 无 --yes：只显示计划
+  → 创建并校验 SQLite 备份
+  → 用目标包运行 doctor
+  → 停止旧服务
+  → 安装目标包
+  → 等待 PID、配置、心跳和两个飞书消费者
+  → 版本一致：完成
+  → 任一步失败：停止失败服务 → 恢复数据 → 恢复可用旧服务 → 报告备份 ID
+```
+
+排队但从未启动的任务保留在 SQLite，升级后按 D8 规则重新授权和恢复。运行中任务不会为升级被静默中断；操作者必须先等待或显式停止。
+
+如果旧 npm 临时目录已被清理，工具仍恢复数据并尝试启动当前可用包，但必须明确提示无法保证旧包二进制回退。手工 `backup` / `backups` / `rollback` 始终保留。
+
+## 6. 诊断与支持
+
+- `version --json`：产品、Node、固定依赖、配置/状态/SQLite 和平台契约。
+- `doctor`：只读检查；`doctor --fix` 只修复文件权限、过期健康标记和日志容量。
+- `support-bundle`：默认写入私有数据目录的脱敏 JSON，不覆盖已有文件。
+- Issue 模板要求版本、平台、最小复现和人工复核后的支持包；禁止上传数据库、凭据和真实身份。
+
+支持包是诊断辅助，不是匿名遥测，也不会自动上传。
+
+## 7. 发布门禁
+
+1. tag、`package.json` 和 Release 版本完全一致。
+2. Ubuntu 与 macOS 完成 `npm ci`、typecheck、全部测试、构建和真实 tarball 安装。
+3. tarball 验证双 CLI、断点安装恢复、配置权限、运行手册初始化和升级只读预览。
+4. 兼容性文档必须和固定依赖、配置/状态/SQLite 版本一致。
+5. 预发布使用 npm `next` dist-tag；稳定版使用 `latest`。
+6. 发布前完成真实 macOS、Linux、飞书成员角色、任务交接、审批、审阅和恢复清单。
+
+## 8. 开源贡献路径
+
+- `README.md` 提供中文产品和安装入口，`README.en.md` 提供完整英文入门路径。
+- `CONTRIBUTING.md` 给出代码地图、检查命令和高风险变更要求。
+- `ROADMAP.md` 公开现在、下一阶段、后续和明确非目标。
+- Good First Issue 只选择不需要真实凭据、范围单一、有自动验收的工作。
+- 安全漏洞通过私有 Security Advisory；授权绕过、凭据泄漏和命令策略逃逸不得公开披露。
+
+## 9. 验收标准
+
+- [x] 配置存在显式 v1 合约，未知未来版本拒绝加载。
+- [x] 版本命令报告固定依赖和数据合约。
+- [x] 支持包使用现有脱敏 doctor 输出并写入私有目录。
+- [x] 升级无 `--yes` 不修改系统；有活动任务时拒绝。
+- [x] 执行升级前生成校验备份，成功后验证健康与产品版本。
+- [x] 失败路径恢复数据，并在旧包仍存在时验证旧服务。
+- [x] 运行手册可从已安装 npm 包初始化且不覆盖团队文件。
+- [x] tarball 测试覆盖安装恢复、运行手册和升级预览。
+- [x] 发布门禁验证兼容性文档与包清单。
+- [x] 中英文入口、配置、兼容性、演示、Roadmap 和贡献入口齐全。
+- [ ] 发布候选版本完成一次干净 macOS 和 Linux 实机升级/降级演练。
+- [ ] 建立真实 GitHub `good first issue`，并由外部贡献者完成一次文档或纯测试 PR。
+
+## 10. 后续版本
+
+- `runbooks validate` 与本地 JSON Schema。
+- 支持包在飞书中生成前的字段预览和选择性导出。
+- 本地、明确 opt-in 的安装/首任务可靠性统计。
+- 多设备中心控制面的独立协议、版本协商和代理升级设计。
+- 核心任务域成熟后，再评估稳定 adapter SDK；不直接暴露安全关键内部对象。