work-ally 0.2.0-alpha.1

package/docs/implementation/SPEC-codex-same-machine-session-handoff-implementation.md

@@ -0,0 +1,239 @@
+# Codex 同机双向会话接续实施文档
+
+更新时间：2026-03-18  
+状态：已验收通过  
+Owner：implementation engineer  
+对应 spec：`docs/planning/SPEC-codex-same-machine-session-handoff.md`
+
+当前验收结论：
+
+- 2026-03-18：本专题已通过产品验收，same-machine、single-active 与 `work_session` 主合同成立。
+- 自动化、shell 与帮助入口验证已通过；真实 Codex runtime smoke 仍受当前环境上游网络请求失败影响，因此这里只记主合同成立，不记真实链路全绿。
+
+## 1. 文档定位
+
+这不是产品 spec，而是交付给实现者的施工文档。
+
+它承担 4 个职责：
+
+- 把 spec 落成可执行阶段，避免工程师按自己理解 freestyle。
+- 作为 handoff 专题的实时施工记录入口。
+- 帮助长任务在对话压缩后按正确路径恢复。
+- 作为交付前自检与 DoD 对照表。
+
+硬规则：
+
+- 本文开工前，先通读 `docs/planning/SPEC-codex-same-machine-session-handoff.md`。
+- `SPEC` 是灯塔；实现时不能绕开它自定产品语义。
+- 工程根目录已有其他专题的 `TASK.md` 时，不要直接复用旧内容；应新建或重写成当前专题的任务路径。
+- 每完成一个阶段，先更新 `TASK.md`，再进入下一阶段。
+
+## 2. 开工前必须理解的产品边界
+
+实现前必须先接受下面这些边界，不要边做边改题。
+
+1. 本专题要做的是 same-machine 双向 handoff，不是 backup patch。
+2. 本专题要连续的是同一条真实 runtime thread，不是复制摘要后的“看起来连续”。
+3. `work_session` 是新的产品对象，不是 `conversationRef -> threadId` 的别名文件。
+4. `runtimeThreadId` 与 `cliResumeRef` 必须逻辑分离，不允许先混写再说。
+5. V1 坚持 single-active ownership；不能为了“更丝滑”做成静默双写。
+6. V1 只正式支持 `official_codex_cli`，不要偷扩到 desktop app / VS Code / 第三方包装层。
+7. V1 不做 transcript 全量镜像；只做正确 handoff、attach、ownership 与拒绝路径。
+
+## 3. 本专题建议关注的代码范围
+
+以下范围大概率会被改动；接手前先自己读清楚。
+
+### 3.1 bridge
+
+- `bridge/src/session-store.ts`
+- `bridge/src/receiver.ts`
+- `bridge/src/router.ts`
+- `bridge/src/runtime-client.ts`
+- `bridge/src/server.ts`
+- `bridge/src/translator.ts`
+- 如有必要新增 `bridge/src/work-session-store.ts` 或等价模块
+
+### 3.2 shell / internal
+
+- `ally.sh`
+- `internal/modules/global/`
+- `internal/modules/assistant/`
+- 需要时新增 handoff 命令实现模块
+
+### 3.3 tests
+
+- `tests/unit/session/*.test.mjs`
+- `tests/integration/session/*.test.mjs`
+- `tests/shell/*.sh`
+- `tests/shell/codex-runtime.sh`
+
+## 4. 必须先创建并维护的 TASK.md
+
+接手开发后，第一步不是写代码，而是处理 `TASK.md`。
+
+要求：
+
+1. 工程根目录的 `TASK.md` 必须切换为当前 handoff 专题，不能继续保留其他专题的施工日志。
+2. `TASK.md` 必须明确：
+   - 目标
+   - 范围 / 非目标
+   - 分阶段任务
+   - 每个任务的 DoD
+   - 当前进行中
+   - 风险 / 待确认问题
+   - 验证计划
+   - 验证结果
+3. 每完成一项任务，先更新 `TASK.md`，再继续开发。
+4. 如果你发现 spec 与真实代码现状存在冲突，先在 `TASK.md` 记录，再回写 spec 或单独提问题，不要静默偏航。
+
+## 5. 分阶段实施建议
+
+### 阶段 1：建立 `work_session` 持久化与查询能力
+
+目标：
+
+- 把 handoff 的产品对象先真正建立起来。
+
+建议工作：
+
+- 为 `work_session` 建立独立持久化目录与最小索引。
+- 明确 assistant 当前 active `work_session` 查询路径。
+- 明确 delivery conversation 当前 active `work_session` 查询路径。
+- 明确 `runtimeThreadId` / `cliResumeRef` / `activeSurface` / `ownershipSource` 的持久化合同。
+
+阶段 DoD：
+
+- 已存在可独立读写的 `work_session` durable object。
+- 不再只能依赖 `conversationRef -> threadId` 临时映射回答“当前是哪条工作线程”。
+- `runtimeThreadId` 与 `cliResumeRef` 已分字段落盘。
+- 对应 unit tests 成立。
+
+### 阶段 2：收口 ownership 规则与渠道拒绝路径
+
+目标：
+
+- 先把“不能乱写”这件事守住。
+
+建议工作：
+
+- 在 router / receiver / session orchestration 中加入 `activeSurface` 判断。
+- 当 owner 为 `official_codex_cli` 时，渠道普通文本必须明确拒绝。
+- `/takeover`、`/new` 的行为要按 spec 收口。
+- 明确 `idle` 与 `closed` 的最低行为。
+
+阶段 DoD：
+
+- owner 为 `official_codex_cli` 时，渠道普通文本不会静默推进 turn。
+- `/takeover` 不会偷偷 `/new`。
+- `/new` 一定创建新的 `work_session`。
+- 拒绝路径已有 integration tests。
+
+### 阶段 3：打通 `work-ally -> Codex CLI`
+
+目标：
+
+- 让用户从渠道侧能精确切回官方 Codex。
+
+建议工作：
+
+- 新增 `/codex` 命令语义。
+- 新增 `./ally.sh handoff codex <assistant>` 命令面。
+- 输出稳定、可测试、可复用的 handoff payload / command。
+- 如果 `cliResumeRef` 不可用，返回 `not_ready` 与明确原因。
+
+阶段 DoD：
+
+- `/codex` 与 shell handoff 命令都能在 ready 状态下返回精确可执行接续方式。
+- `not_ready` 时不会拿 `runtimeThreadId` 假冒 CLI 恢复句柄。
+- shell tests 与至少一条真实 smoke 成立。
+
+### 阶段 4：打通 `Codex CLI -> work-ally` 已链接接回
+
+目标：
+
+- 让原本已被 `work-ally` 管理的线程，能从官方 CLI 接回渠道侧。
+
+建议工作：
+
+- 新增 `/takeover` 正式语义。
+- 基于 `runtimeThreadId` / `work_session` 恢复同一条 runtime thread。
+- 正确更新 `activeSurface` 与 `ownershipSource`。
+
+阶段 DoD：
+
+- 从 linked `work_session` 切到 CLI 后，再 `/takeover`，不会新建 thread。
+- `/takeover` 成功后，后续普通文本进入同一条 runtime thread。
+- 集成测试覆盖主路径。
+
+### 阶段 5：实现 unmanaged CLI thread attach
+
+目标：
+
+- 让先在官方 CLI 里开工的线程，也能被纳管后切回渠道侧。
+
+建议工作：
+
+- 实现 `./ally.sh handoff attach <assistant>`。
+- 支持 `--last`、`--thread`、`--resume-ref`。
+- 限定在 assistant 对应 `CODEX_HOME` 中发现候选。
+- 做 workspace 精确匹配与歧义拒绝。
+
+阶段 DoD：
+
+- 候选唯一时 attach 可成功创建正式 `work_session`。
+- 候选不唯一时稳定失败，不猜。
+- attach 后可通过 `/takeover` 接回渠道侧。
+
+### 阶段 6：回归、文档与交付收口
+
+目标：
+
+- 把实现从“能跑”收成“可交付”。
+
+建议工作：
+
+- 回写 README / 必要文档。
+- 补齐 shell、unit、integration、真实 smoke。
+- 清理临时调试逻辑与无效旧语义。
+
+阶段 DoD：
+
+- 文档与 shipped 行为一致。
+- 相关自动化测试通过。
+- `TASK.md` 已回填完整验证结果与缺口。
+
+## 6. 明确禁止的实现偏航
+
+实现过程中，以下做法一律视为偏航：
+
+1. 用“复制摘要 + 新开 thread”伪装 handoff 完成。
+2. 把 `conversationRef` 继续当成 handoff 主键。
+3. 把 `runtimeThreadId` 与 `cliResumeRef` 写进同一字段或默认互相替代。
+4. 当 owner 为 `official_codex_cli` 时，仍让渠道普通文本继续写入。
+5. `attach --last` 命中多个候选时按最近修改时间自动猜。
+6. 顺手把 scope 扩成 transcript 全量镜像。
+7. 不更新 `TASK.md`，只在聊天里口头汇报进度。
+
+## 7. 测试与验证基线
+
+接手实现后，至少要补齐或运行这些验证：
+
+- `tests/unit/session/` 下与 `work_session`、ownership 相关的单测
+- `tests/integration/session/` 下 handoff / takeover / reject path 相关集成测试
+- `tests/shell/` 下 `ally.sh handoff ...` 语义测试
+- 必要的 `tests/shell/codex-runtime.sh` 或等价真实 smoke
+- `bash -n ally.sh`
+- 相关 shell 模块语法检查
+- `./ally.sh help`
+
+若因环境限制无法完整执行，必须在 `TASK.md` 与最终交付说明中明确写出缺口。
+
+## 8. 恢复施工说明
+
+如果对话被压缩或换人接手，恢复顺序固定如下：
+
+1. 先读 `AGENTS.md` 与 `docs/planning/SPEC-codex-same-machine-session-handoff.md`。
+2. 再读本文件，确认阶段、边界和禁止事项。
+3. 然后查看工程根目录 `TASK.md`，确认当前做到哪一步、剩余 DoD 和验证缺口。
+4. 只有当 spec 边界仍成立时才继续写代码；若边界变了，先回写 spec。

package/docs/implementation/test-coverage-map.md

@@ -0,0 +1,363 @@
+# Test Coverage Map
+
+更新时间：2026-03-17  
+状态：Active
+
+## 1. 目的
+
+这份文档不是“测试命令清单”，而是 `work-ally` 的测试地图。
+
+它回答 4 个问题：
+
+1. 哪些链路可以被稳定模拟
+2. 哪些边界暂时不适合做全自动端到端模拟
+3. 当前自动化门禁按什么 MECE 结构组织
+4. 新需求落地时，测试应该补到哪一层、哪个域，而不是继续拍脑袋往某个大文件里堆 case
+
+## 2. 测试边界
+
+### 2.1 可以稳定模拟的链路
+
+这些是当前产品最应该建立自动化门禁的主战场：
+
+1. CLI / shell facade -> `internal/` 生命周期与状态管理
+2. bridge session state machine
+3. bridge <-> fake runtime / Codex runtime client contract
+4. channel adapter 的格式化、去重、收发规范化
+5. approval / user-input / stop / recovery / stale suppression 等会话语义
+6. archive / memory / routine / scheduler 的文件系统合同
+7. 多 assistant 绑定、全局入口、多实例状态感知
+
+### 2.2 暂时不做全自动端到端模拟的边界
+
+目前不把下面这层当成自动化主门禁：
+
+1. 真实 Feishu 云侧投递到本机 bridge 的公网/长连接链路
+2. 真实手机端 Feishu 交互体验
+3. 真实官方 Codex runtime 在线稳定性本身
+
+原因不是它们不重要，而是：
+
+1. 这几层更依赖外部平台与宿主环境
+2. 它们更适合 smoke probe、人工验收、真实值班排障来兜底
+3. `work-ally` 当前更该先把“自己可控的桥接层语义”做成确定性系统
+
+因此当前策略是：
+
+1. Feishu -> bridge 的真实接入，用人工验收与运行日志兜底
+2. bridge -> runtime 的主链路，用 fake runtime + runtime client tests 做高密度自动化
+3. shell / lifecycle / binding / release，用 shell smoke + temp workspace 做自动化门禁
+
+## 3. 测试金字塔
+
+### 3.1 Unit
+
+目标：验证单模块合同、状态归一化、格式化与持久化规则。
+
+典型特征：
+
+1. 不拉整条桥接链路
+2. 聚焦单个模块输入输出
+3. 用最小 fixture 验证边界分支
+
+### 3.2 Integration
+
+目标：验证 bridge 主链路、状态机、fake runtime 往返、session 演进与异常收口。
+
+典型特征：
+
+1. fake inbound -> receiver -> fake runtime -> channel outbound
+2. 会跨 `receiver` / `session-store` / `thread-sync` / `translator` / runtime client 语义
+3. 用真实文件落盘验证 ledger / archive / routine 合同
+
+### 3.3 Shell
+
+目标：验证用户入口、assistant desk 生命周期、global 命令、多 assistant 绑定、install-first 边界。
+
+典型特征：
+
+1. 直接走 `ally.sh`
+2. 用临时 HOME / workspace 验证真实 shell 行为
+3. 补 CLI 与运行边界，而不是补 bridge 细语义
+
+### 3.4 人工验收
+
+目标：兜住外部平台、真实 Feishu 体验、真实本机 runtime 与移动端体感。
+
+当前入口：
+
+1. `docs/manual-acceptance.md`
+2. `docs/troubleshooting.md`
+3. `docs/ops-runbook.md`
+
+## 4. MECE 测试域
+
+当前把自动化测试收为 7 个互斥但合起来覆盖主线的域。
+
+| 域 | 关注点 | 自动化层级 | 当前目录 |
+| --- | --- | --- | --- |
+| A. Shell / Lifecycle / Release | `ally.sh`、启动停止、global、release、锁、恢复、MCP shell 行为 | shell | `tests/shell/` |
+| B. Channel Contract | Feishu 规范化、格式化、adapter 收发、reply context、群聊触发 | unit + integration | `tests/unit/channel/`、`tests/integration/channel/` |
+| C. Runtime Contract | runtime client、terminal-state reconciliation、message phases、stdio transport lifecycle、runtime user input | unit | `tests/unit/runtime/` |
+| D. Session Control | `/status`、`/stop`、`/new`、continuity、approval、user input、empty inbound | integration + unit | `tests/unit/session/`、`tests/integration/session/` |
+| E. Presence / Recovery / Delivery | presence、协议路由、waiting user、runtime failure、recovery、redelivery、stale suppression、稳定性回归 | integration + unit(runtime) | `tests/integration/session/`、`tests/unit/runtime/` |
+| F. Memory / Thread Materials / Routine | thread snapshots、digest、scheduler、routine delivery / reuse | unit + integration | `tests/unit/memory/`、`tests/integration/routines/` |
+| G. System / Config | config、logger、system-notify、assistant status、runtime state 事实 | unit | `tests/unit/system/` |
+
+说明：
+
+1. `Session Control` 关注“用户命令和会话控制语义”
+2. `Presence / Recovery / Delivery` 关注“运行中状态、异常、恢复、补偿送达与稳定性”
+3. 它们相关但不混写，避免再次长成一个巨型杂糅文件
+
+## 5. 目录与文件映射
+
+### 5.1 Unit
+
+#### B. Channel Contract
+
+- `tests/unit/channel/formatter.test.mjs`
+- `tests/unit/channel/feishu-normalize.test.mjs`
+- `tests/unit/channel/feishu-adapter-inbound.test.mjs`
+- `tests/unit/channel/feishu-adapter-outbound.test.mjs`
+- `tests/unit/channel/feishu-adapter-delivery.test.mjs`
+
+#### C. Runtime Contract
+
+- `tests/unit/runtime/runtime-client-thread-status.test.mjs`
+- `tests/unit/runtime/runtime-client-message-phases.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary-recovery.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary-waiting.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary.test.mjs`
+- `tests/unit/runtime/runtime-client-lifecycle.test.mjs`
+- `tests/unit/runtime/runtime-user-input.test.mjs`
+
+#### D. Session Control
+
+- `tests/unit/session/router.test.mjs`
+- `tests/unit/session/session-store.test.mjs`
+
+#### F. Memory / Thread Materials / Routine
+
+- `tests/unit/memory/memory-digest.test.mjs`
+- `tests/unit/memory/scheduler.test.mjs`
+
+#### G. System / Config
+
+- `tests/unit/system/config.test.mjs`
+- `tests/unit/system/logger.test.mjs`
+- `tests/unit/system/system-notify.test.mjs`
+- `tests/unit/system/assistant-status.test.mjs`
+
+### 5.2 Integration
+
+#### B. Channel Contract
+
+- `tests/integration/channel/feishu-reply-context.test.mjs`
+- `tests/integration/channel/group-chat-sender-identity.test.mjs`
+
+#### D. Session Control
+
+- `tests/integration/session/approval-flow.test.mjs`
+- `tests/integration/session/mcp-tool-approval-flow.test.mjs`
+- `tests/integration/session/control-commands.test.mjs`
+- `tests/integration/session/continuity-flow.test.mjs`
+- `tests/integration/session/stop-flow.test.mjs`
+- `tests/integration/session/user-input-flow.test.mjs`
+- `tests/integration/session/empty-inbound-fallback.test.mjs`
+- `tests/integration/session/fake-bridge.test.mjs`
+- `tests/integration/session/blackbox-archive.test.mjs`（验证 final reply 后 thread-sync 快照写入）
+
+#### E. Presence / Recovery / Delivery
+
+- `tests/integration/session/presence-startup.test.mjs`
+- `tests/integration/session/protocol-routing.test.mjs`
+- `tests/integration/session/waiting-and-redelivery.test.mjs`
+- `tests/integration/session/runtime-failure-and-recovery.test.mjs`
+- `tests/integration/session/stale-output-and-new-turns.test.mjs`
+- `tests/integration/session/stability-regression.test.mjs`
+
+#### F. Memory / Thread Materials / Routine
+
+- `tests/integration/routines/routine-flow.test.mjs`
+- `tests/integration/routines/routine-reuse.test.mjs`
+- `tests/integration/routines/routine-delivery.test.mjs`
+- `tests/integration/routines/memory-pipeline.test.mjs`
+
+### 5.3 Shell
+
+#### A. Shell / Lifecycle / Release
+
+- `tests/shell/check-syntax.sh`
+- `tests/shell/smoke.sh`
+- `tests/shell/assistant.sh`
+- `tests/shell/assistant-remove.sh`
+- `tests/shell/assistant-lock.sh`
+- `tests/shell/global-entrypoint.sh`
+- `tests/shell/global-manage.sh`
+- `tests/shell/lifecycle.sh`
+- `tests/shell/recovery.sh`
+- `tests/shell/service-mode.sh`
+- `tests/shell/status-health.sh`
+- `tests/shell/startup-delivery-gate.sh`
+- `tests/shell/bridge-health-fallback.sh`
+- `tests/shell/channel-lock.sh`
+- `tests/shell/security.sh`
+- `tests/shell/ops.sh`
+- `tests/shell/mcp.sh`
+- `tests/shell/routines.sh`
+- `tests/shell/codex-runtime.sh`
+- `tests/shell/supervised-start-boundary.sh`
+
+## 6. 当前专项稳定性门禁
+
+针对这轮用户最痛的“bridge -> Codex 稳定性 / 会话状态误导 / 结果补偿送达”问题，最低门禁不是单个文件，而是下面这组：
+
+### 6.1 Runtime 终态与 pull-primary
+
+- `tests/unit/runtime/runtime-client-pull-primary-recovery.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary-waiting.test.mjs`
+- `tests/unit/runtime/runtime-client-pull-primary.test.mjs`
+- `tests/unit/runtime/runtime-client-lifecycle.test.mjs`
+
+覆盖：
+
+1. `runtime-client-pull-primary-recovery.test.mjs`：`thread/read(includeTurns=true)` 收口、late terminal reclaim、恢复窗口内对账
+2. `runtime-client-pull-primary-waiting.test.mjs`：waitingOnApproval / waitingOnUserInput / command activity 持续时不误超时，并能通过 poll 主动上报 blocked 状态
+3. `runtime-client-pull-primary.test.mjs`：transient `thread/read` 失败、bounded retry、fresh-thread materialization、`turn/completed` 与轮询冲突时的终态优先级
+4. `runtime-client-lifecycle.test.mjs`：stdio child-process 异常关闭后的对账、重连 lifecycle 事件
+
+### 6.2 Bridge 会话状态机
+
+- `tests/integration/session/presence-startup.test.mjs`
+- `tests/integration/session/protocol-routing.test.mjs`
+- `tests/integration/session/waiting-and-redelivery.test.mjs`
+- `tests/integration/session/runtime-failure-and-recovery.test.mjs`
+- `tests/integration/session/stale-output-and-new-turns.test.mjs`
+- `tests/integration/session/stability-regression.test.mjs`
+
+覆盖：
+
+1. quiet start / received status / commentary filtering
+2. `turn/steer` 协议路由、`/new` 忙时门控 / stale active turn 清理
+3. waiting_user 语义、long wait 不误报、blocked follow-up 拦截与解释、延迟 approval / user-input 仍能稳定暴露
+4. runtime infrastructure failure、delivery unavailable、recovery success/failure
+5. final reply 的 source-to-delivery 闭环：未送达结果会落账，并在 bridge 恢复后可补发
+6. stale output suppression、旧 turn 不串回用户面前
+7. 非 completed 但已有 reply 的终态仍按结果交付，不再被本地文案覆盖
+8. 100 轮 bridge <-> runtime ping-pong 稳定往返
+9. bridge / runtime 重启后，若 session 仍记得旧 threadId 但 runtime 已丢 rollout，下一条普通消息仍必须自动 fallback 到 fresh thread，而不是只在 `/codex`、`/new` 或 process-start 检查里显得正常
+
+### 6.3 Shell 运行边界
+
+- `tests/shell/assistant.sh`
+- `tests/shell/global-entrypoint.sh`
+- `tests/shell/global-manage.sh`
+- `tests/shell/recovery.sh`
+- `tests/shell/status-health.sh`
+
+覆盖：
+
+1. 多 assistant 绑定同一项目
+2. 隐式命令歧义时必须要求 `--assistant`
+3. install-first / global 管理 / 生命周期边界
+4. status / recovery / global stop 基础运维路径
+
+## 7. 新需求该怎么补测试
+
+### 7.1 先判域，再判层
+
+每次改动先回答两个问题：
+
+1. 它属于哪个域
+2. 它应该落在哪一层最先被验证
+
+默认规则：
+
+1. 纯格式、纯归一化、纯持久化合同：先 unit
+2. 会话语义、bridge 状态机、异常恢复：先 integration
+3. CLI 语义、workspace / assistant 绑定、生命周期：先 shell
+4. 外部平台真实体验差异：落人工验收，不假装用伪 E2E 替代
+
+补充纪律：
+
+1. runtime 域新增用例时，先判它属于 `recovery`、`waiting` 还是 `delivery/final-state arbitration`
+2. `tests/unit/runtime/runtime-client-pull-primary*.test.mjs` 三个文件各守一类语义，不再回到单文件巨型杂糅
+3. 只要改动触及 `resume` / `restart` / continuity / recovery，至少补一条“重启后再发普通消息”的集成回归；不能只用 `/codex`、`/new`、`process_start` 或 fake happy-path 代替
+4. runtime fallback 类用例必须覆盖真实错误形态：既要测裸 RPC 错误对象，也要测经过 `normalizeRuntimeError()` 之后的 `Error` 实例
+
+### 7.2 不再新增“杂糅大文件”
+
+新增 case 时遵守：
+
+1. 优先放进已有测试域目录
+2. 优先放到最贴近语义的文件
+3. 某文件继续明显变胖时，继续按场景切小文件，而不是把不相关 case 堆一起
+
+### 7.3 变更对照表
+
+| 变更类型 | 最低要求 |
+| --- | --- |
+| Feishu 格式 / reply context / 群聊触发 | `tests/unit/channel/*.test.mjs` + `tests/integration/channel/*.test.mjs` |
+| runtime client / disconnect / pull-primary | `tests/unit/runtime/*.test.mjs` |
+| session 语义 / approval / user-input / protocol routing / stale suppression | `tests/integration/session/*.test.mjs` + 必要的 `tests/unit/session/*.test.mjs` |
+| archive / digest / scheduler / routine | `tests/unit/memory/*.test.mjs` + `tests/integration/routines/*.test.mjs` |
+| status / config / system notice | `tests/unit/system/*.test.mjs` |
+| CLI / assistant binding / lifecycle / release | 对应 `tests/shell/*.sh` |
+
+## 8. 测试命令
+
+### 8.1 全量自动化
+
+```bash
+npm test
+```
+
+### 8.2 仅 bridge 自动化
+
+```bash
+npm run test:bridge
+```
+
+### 8.3 仅 shell
+
+```bash
+npm run test:shell
+```
+
+### 8.4 快速回归
+
+```bash
+npm run test:fast
+```
+
+### 8.5 渠道专项
+
+```bash
+node --test tests/unit/channel/*.test.mjs tests/integration/channel/*.test.mjs
+```
+
+### 8.6 稳定性专项
+
+```bash
+node --test \
+  tests/unit/runtime/*.test.mjs \
+  tests/unit/session/*.test.mjs \
+  tests/integration/session/*.test.mjs
+```
+
+## 9. 已知缺口
+
+当前仍保留这些清醒边界：
+
+1. 没有自动化模拟真实 Feishu 云侧投递
+2. 没有自动化证明真实官方 Codex runtime 在所有宿主环境下都稳定
+3. 没有大规模压测；当前稳定性回归采用 100 轮顺序 ping-pong 作为“合理强度门禁”，避免无意义地烧 token 和时间
+4. `tests/integration/session/` 下仍有一些 fixture 构造重复，后续若该域继续膨胀，可再抽 shared harness；但当前优先级低于保持测试语义清晰
+5. `tests/integration/session/runtime-failure-and-recovery.test.mjs` 与 `tests/integration/session/waiting-and-redelivery.test.mjs` 仍偏大；后续新增 case 时应优先继续拆子文件，而不是继续长胖
+
+## 10. 维护纪律
+
+1. 先改测试地图，再扩测试域；不要让目录结构再次失真
+2. 需求若跨多个测试域，提交说明里要明确哪些域被改动、哪些域被验证
+3. 任何新的稳定性事故，先在这份地图里补“归类位置”，再决定新增哪类用例