work-ally 0.2.0-alpha.1

package/docs/issues/resolved/ANALYSIS-approval-waiting-visible-but-approval-artifact-missing-2026-03-16.md

@@ -0,0 +1,466 @@
+# 分析报告：审批等待已对用户可见，但审批实体缺失导致会话被错误阻塞
+
+更新时间：2026-03-16  
+状态：已修复并补门禁（2026-03-17）  
+作者：Codex
+
+## 1. 这份报告回答什么
+
+这份报告聚焦一个非常具体、可复现且用户可感知的问题：
+
+> 飞书前台已经收到“当前已暂停，等待你审批后继续”，但用户实际上看不到任何可操作的审批卡；此后用户继续追问或直接回复“同意”，中间层仍然把会话卡在“等待审批”状态，导致消息既没有转给 Codex，也没有真正完成审批。
+
+这份文档的目标不是立刻给 patch，而是把以下内容低上下文讲清楚：
+
+1. 真实现象是什么。
+2. 证据链在哪里。
+3. 已经确认的事实是什么。
+4. 尚未确认但不影响修复方向的点是什么。
+5. 根因属于文案问题、实现 bug，还是状态机/架构设计问题。
+6. 后续应按什么原则修改，才能把这类问题真正收口。
+7. 应补哪些自动化测试，避免以后同类问题再次漏掉。
+
+## 2. 事件背景
+
+### 2.1 排查对象
+
+- 助理：`Ally`
+- 办公桌：`/Users/allenfeng/.work-ally/assistants/Ally`
+- 会话：`feishu--oc_1890ff7f9132a7d90b09765f27ff5bc8`
+- 关注时间：2026-03-16 17:07 左右（Asia/Shanghai，对应 `2026-03-16T09:07Z`）
+- 对应 turn：`019cf5e0-e31d-7081-b714-a2119e66dc74`
+- 对应 thread：`019cebce-0481-7be3-98ce-38432074d5bd`
+
+### 2.2 用户可见现象
+
+用户在飞书前台看到的关键对话序列是：
+
+1. 助理先正常推进新任务，连续输出 commentary。
+2. 随后系统发出：`当前已暂停，等待你审批后继续。`
+3. 但用户前台没有看到任何审批卡，也没有任何审批编号、审批内容或操作入口。
+4. 用户发：`进展如何？`
+5. 系统回：`当前这轮已暂停，正在等你审批；你刚发的这条我还没转给 Codex。先处理审批，再继续发下一条。`
+6. 用户再发：`同意`
+7. 系统再次回：`当前这轮已暂停，正在等你审批；你刚发的这条我还没转给 Codex。先处理审批，再继续发下一条。`
+
+对用户而言，这里的直观体感是：
+
+- 系统宣称“卡在审批”；
+- 但人类看不到审批对象；
+- 人类主动表态“同意”也没用；
+- 中间层仍然持续阻塞会话。
+
+这已经不是“提示不够友好”，而是一个**真实的会话阻塞 bug**。
+
+## 3. 证据位置
+
+### 3.1 用户可读原材料
+
+- archive：`/Users/allenfeng/.work-ally/assistants/Ally/.system/archive/2026/03/16/feishu--oc_1890ff7f9132a7d90b09765f27ff5bc8.ndjson`
+
+### 3.2 运行日志
+
+- timeline：`/Users/allenfeng/.work-ally/assistants/Ally/.system/logs/timeline-2026-03-16.log`
+- bridge：`/Users/allenfeng/.work-ally/assistants/Ally/.system/logs/bridge-2026-03-16.log`
+
+### 3.3 相关实现代码
+
+- `bridge/src/receiver.ts`
+- `bridge/src/router.ts`
+- `bridge/src/runtime-client.ts`
+- `bridge/src/channels/feishu/adapter.ts`
+- 相关测试目录：`tests/integration/session/`
+
+## 4. 事实链
+
+### 4.1 新任务本身是正常启动的
+
+在本次问题发生前，turn `019cf5e0-e31d-7081-b714-a2119e66dc74` 已经正常启动，并持续向用户输出了多条 commentary，内容明确是在处理“新的群聊 feature/spec 需求”，不是旧 turn 重放。
+
+关键证据：
+
+- `timeline-2026-03-16.log` 中 `09:01:22Z` 记录 `runtime.turn_started`
+- `09:02:16Z`、`09:03:11Z`、`09:04:55Z`、`09:06:44Z`、`09:07:00Z` 均有同一 turn 的 commentary
+- archive 中对应记录位于第 28-44 行
+
+这说明：
+
+- 这不是消息没进 bridge；
+- 也不是 turn 根本没跑起来；
+- 问题发生在 turn 已经运行一段时间之后。
+
+### 4.2 17:07 左右 runtime 确实进入了 `waitingOnApproval`
+
+`timeline-2026-03-16.log` 记录：
+
+- `2026-03-16T09:07:10.174Z [DEBUG] [bridge] runtime.thread_status_changed {"status":{"type":"active","activeFlags":["waitingOnApproval"]}}`
+
+这说明：
+
+- runtime 侧确实进入了“等待审批”的 thread 状态；
+- 用户看到“等待审批”并非完全空穴来风。
+
+### 4.3 bridge 只把“等待审批”状态发给了用户，没有把审批实体发出来
+
+archive 记录表明：
+
+- 第 45 行：`09:07:12Z` 向飞书发出 `status_reply`，文案是 `当前已暂停，等待你审批后继续。`
+- 但同一时间段内，archive 里没有任何 `approval_requested` 的 outbound 记录；
+- timeline/bridge log 同一时间段也没有 `receiver.approval_requested` 或等价事件；
+- 唯一可见的发送记录是普通状态消息对应的 `feishu.message_sent`。
+
+因此可以明确判断：
+
+> 这次不是“审批卡发了但用户没看到”，而是**系统根本没有把审批实体稳定交付到飞书前台**。
+
+### 4.4 用户后续自然语言追问没有转给 Codex，而是被本地拦截了
+
+archive 记录表明：
+
+- 第 46-48 行：用户发 `进展如何？`，bridge 记录 `waiting_user_follow_up_intercepted`，并回了“你刚发的这条我还没转给 Codex”
+- 第 49-51 行：用户发 `同意`，bridge 再次记录 `waiting_user_follow_up_intercepted`，仍未转给 Codex
+
+timeline 也对应记录：
+
+- `09:10:40.659Z receiver.waiting_user_follow_up_intercepted`
+- `09:11:00.236Z receiver.waiting_user_follow_up_intercepted`
+
+所以可以确认：
+
+- 用户的追问确实到达了 bridge；
+- bridge 故意没有往 Codex 转发；
+- 阻塞是 bridge 本地状态机造成的，不是飞书丢消息，也不是 Codex 没响应。
+
+### 4.5 “同意”没有生效，不是因为用户说错了，而是当前解析前提根本不成立
+
+当前实现里，审批解析分两类：
+
+1. 明确控制命令：`/approve <approvalId>` / `/deny <approvalId>`
+2. 对审批卡内容的自然语言回复：例如回复一张含“审批编号”的卡，然后说“同意”
+
+`bridge/src/router.ts` 中，`parseApprovalReply()` 必须从 `replyToText` 里解析出审批编号；如果当前消息不是“回复那张审批卡”，就拿不到 `approvalId`，自然无法提交审批。
+
+而这次现场中：
+
+- 用户根本没看到审批卡；
+- 飞书入站记录里也没有 `reply_to_message_id` / `reply_to_text`；
+- 所以“同意”这条消息不可能被解释成审批动作。
+
+这解释了为什么用户明明已经表态“同意”，系统却仍然卡住。
+
+## 5. 问题定义
+
+这个问题不能定义成“审批文案有点误导”，也不能定义成“偶发漏发一条卡片”。
+
+更准确的问题定义是：
+
+> **bridge 把 `waitingOnApproval` 这个 runtime thread flag 直接升级成了对用户可见的“待审批阻塞事实”，但它并没有保证审批实体本身已经被成功持久化、成功发送并成功暴露给用户。**
+
+一旦审批实体缺失，当前状态机就会进入自相矛盾：
+
+- 一方面告诉用户“正在等你审批”；
+- 另一方面又不给用户任何可执行对象；
+- 再进一步把用户后续所有自然语言都拦下来，不再发给 Codex。
+
+## 6. 5 Why 根因分析
+
+### Why 1：为什么用户看到了“等待审批”，却看不到审批卡？
+
+因为 bridge 在 `onThreadStatus` 路径里，只要看到 `waitingOnApproval`，就会立刻发送 `waitingApprovalStatusMessage()`，不要求审批实体已经存在。
+
+对应代码：`bridge/src/receiver.ts` 中 `onThreadStatus` 分支。
+
+### Why 2：为什么系统会把 thread flag 当成“用户已获得审批对象”的依据？
+
+因为当前设计把两个概念混成了一个：
+
+1. runtime 内部 thread 进入了等待审批状态；
+2. 用户侧已经拿到了可操作的审批对象。
+
+这两个概念在实现上被默认视为等价，但真实系统里并不等价。
+
+### Why 3：为什么这两个概念不等价？
+
+因为审批是一个独立实体，它至少有三个独立阶段：
+
+1. runtime 内部产生审批请求；
+2. bridge 收到并记录审批请求；
+3. bridge 成功把审批内容交付到飞书用户前台。
+
+只有第三步完成，才算“用户真的可以审批”。当前设计却在第一步甚至只看到 flag 时，就把会话推进到了等待用户审批的阻塞态。
+
+### Why 4：为什么用户后续消息会被拦截？
+
+因为 `handleInbound()` 会优先根据 `waitingStateFor()` 和当前 session 状态，把会话判定为 `waiting_user`；只要等待态是 `approval`，后续自然语言就会进入 `waiting_user_follow_up_intercepted` 路径，而不是继续发给 Codex。
+
+也就是说，阻塞是否生效，目前绑定的是“本地看到等待态”，而不是“审批对象已经对用户可见”。
+
+### Why 5：为什么用户发“同意”也无法自救？
+
+因为当前审批解析依赖审批卡上下文或显式 `/approve <id>`。当审批卡本身缺失时，用户没有审批编号、也没有 reply target，于是“同意”既不能被当作审批动作，也不会被转发给 Codex，只会再次被等待态拦截。
+
+### 根因收口
+
+根因不是单点漏日志，也不是文案问题，而是：
+
+> **审批阻塞状态机建模错误：系统把“观察到等待审批状态”误当成了“审批实体已对用户可操作”，从而过早进入阻塞态，并吞掉后续用户输入。**
+
+## 7. 已知事实与未知点
+
+### 7.1 已知事实
+
+已经可以确定的事实有：
+
+1. runtime thread 真实进入了 `waitingOnApproval`。
+2. bridge 真实向用户发了“等待你审批”的状态提示。
+3. bridge 没有把对应审批实体稳定送到飞书前台。
+4. 用户的“进展如何？”和“同意”都到达了 bridge。
+5. bridge 明确没有把这两条消息转给 Codex，而是本地拦截了。
+6. 当前控制解析机制要求审批卡或审批编号；本次场景两者都不存在。
+
+### 7.2 仍待进一步确认、但不影响修复方向的点
+
+还没有最终钉死的子问题是：
+
+> 这次审批实体为什么没有出现？
+
+目前有两种可能：
+
+1. runtime 在这次场景下只暴露了 thread flag，但没有把审批 request 事件送到 bridge；
+2. runtime 发了审批 request，但 `runtime-client -> receiver.onApproval` 这条链路在当前实现/当前时序下漏接了。
+
+无论是哪一种，这都不改变主修复方向，因为问题的关键并不是“审批事件到底丢在更上游还是更下游”，而是：
+
+> **只要审批实体没有真正成功交付给用户，bridge 就不应该把会话切成“等待用户审批”的阻塞态。**
+
+也就是说，即使上游偶发不稳定，bridge 也应该把这种情况建模成“审批详情待同步”或“阻塞原因待确认”，而不是甩给用户一句“等你审批”。
+
+## 8. 影响范围
+
+这个问题的影响不只是一轮会话卡住，而是会损伤三件事：
+
+### 8.1 用户信任
+
+用户会认为：
+
+- 系统把事情吞了；
+- 自己明明被要求审批，却根本无从操作；
+- 连“同意”都没有用；
+- 中间层像是在自说自话。
+
+### 8.2 会话连续性
+
+因为后续自然语言被拦截，用户没法继续追问，也没法显式转为新的任务；整轮会话会被错误挂起。
+
+### 8.3 同类阻塞机制的普遍风险
+
+如果 `waitingOnApproval` 这里成立，`waitingOnUserInput` 也存在同类风险：
+
+- 只看到 flag，没把真正的问题表单/elicitation 内容稳定送到用户前台；
+- 却已经把会话切成“等你输入”的阻塞态。
+
+因此这不是审批专属小洞，而是**阻塞态与用户可见实体脱钩**这一类系统性问题。
+
+## 9. 修复原则
+
+这次不要按“补个 if”思路修，而要按下面的原则改。
+
+### 9.1 原则一：阻塞态必须绑定“用户已拿到可操作实体”
+
+只有当以下条件成立时，才能把会话切到真正的 `waiting_approval`：
+
+1. bridge 已收到明确的审批实体；
+2. bridge 已把审批实体持久化到 session/archive；
+3. bridge 已成功把审批卡发送到飞书；
+4. 发送结果被确认成功。
+
+换言之：
+
+- `waitingOnApproval` flag 只能说明“可能卡在审批”；
+- 不能直接说明“用户已经可以审批”。
+
+### 9.2 原则二：flag-only 场景要建成异常态，不要建成用户阻塞态
+
+如果 bridge 只观察到 `waitingOnApproval`，却没有拿到审批实体，那么应进入一种单独状态，例如：
+
+- `approval_visibility_unconfirmed`
+- 或“审批详情同步中”
+
+在这个状态下：
+
+- 可以对用户透明说明“检测到当前轮可能进入审批阻塞，正在同步审批详情”；
+- 但不能说“等你审批后继续”；
+- 更不能把所有后续消息都拦下来当成未审批。
+
+### 9.3 原则三：后续消息拦截条件应收紧
+
+当前拦截 follow-up 的条件过宽。以后只有当“用户可见审批实体已存在”时，才允许把后续自然语言解释成“你还没处理审批”。
+
+如果审批实体缺失：
+
+- 用户的后续消息要么继续转给 Codex；
+- 要么进入“当前阻塞详情仍未同步完成”的异常提示；
+- 但不能再假设“用户明明已经拿到审批对象却不处理”。
+
+### 9.4 原则四：用户补救路径要完整
+
+当系统处于审批阻塞态时，用户至少应始终拥有以下其一：
+
+1. 可直接操作的审批卡；
+2. 可引用的审批编号；
+3. 明确的错误说明：当前没有拿到审批对象，因此无法审批。
+
+不能再出现：
+
+- 系统要求审批；
+- 但又不给任何审批句柄。
+
+### 9.5 原则五：pull/reconcile 不能只关注最终回复，也要关注阻塞实体
+
+此前稳定性优化更偏向“最终结果补发”。这次问题说明：
+
+- 审批请求、用户输入请求这类阻塞实体也必须纳入对账模型；
+- 否则就可能出现“最终回复还没问题，但阻塞对象丢了”的前台假死。
+
+## 10. 建议实现方向
+
+这里只给实现方向，不直接给 patch。
+
+### 10.1 状态模型调整
+
+把当前单一的 `waiting_approval` 拆成至少两层：
+
+1. `approval_pending_visibility`
+   - 只看到了 runtime flag，或只确认当前轮疑似进入审批阻塞；
+   - 但还没有用户可见审批实体。
+2. `waiting_approval`
+   - 已有审批记录；
+   - 已成功把审批对象交给用户；
+   - 这时才允许把会话切成真正等待用户审批。
+
+### 10.2 发送顺序与幂等要求
+
+审批链路要调整为：
+
+1. 收到审批实体。
+2. 先落 session / archive durable record。
+3. 发送审批卡。
+4. 发送成功后，才把 turn execution status 标成真正 `waiting_approval`。
+5. 如果发送失败或审批实体未拿到，则停在异常态并继续 reconcile。
+
+### 10.3 用户输入拦截逻辑调整
+
+`waiting_user_follow_up_intercepted` 这条路径要以“可见阻塞实体存在”为前提，而不是仅依赖 thread flag。
+
+### 10.4 审批答复容错增强（可选增强，不作为根修复替代）
+
+在保证审批实体稳定可见之后，可考虑额外增强：
+
+- 当当前 session 恰好只有一个 pending approval 时，允许用户直接发“同意/拒绝”而不必强依赖 reply-to；
+- 但这只能算兜底体验增强，不能替代“审批实体必须先送达”这个主修复。
+
+## 11. 必补测试
+
+这次暴露的是专项门禁缺口，后续至少要补下面这些自动化场景。
+
+### 11.1 flag-only waiting approval
+
+场景：
+
+- runtime thread status 进入 `waitingOnApproval`
+- 但 bridge 没有收到审批实体
+
+期望：
+
+- 不发送“等待你审批后继续”
+- 不进入真正的 `waiting_approval`
+- 不拦截后续自然语言为“未审批 follow-up”
+
+### 11.2 approval entity arrives after waiting flag
+
+场景：
+
+- 先收到 waiting flag
+- 后收到审批实体
+
+期望：
+
+- 只有在审批实体持久化并成功发给用户后，才进入真正的审批等待态
+- 不重复发卡
+- 不重复发状态
+
+### 11.3 approval entity send failure
+
+场景：
+
+- bridge 收到了审批实体
+- 但向飞书发送审批卡失败
+
+期望：
+
+- 会话不能假装已经在等用户审批
+- 要进入可见异常态
+- 后续可以补发或重试
+
+### 11.4 follow-up while approval visibility unconfirmed
+
+场景：
+
+- 用户在“只看到等待 flag、还没看到审批卡”的阶段发追问
+
+期望：
+
+- 不要误报“你这条没转给 Codex，因为在等你审批”
+- 要么继续转发给 Codex，要么给出准确的“审批详情仍未同步完成”提示
+
+### 11.5 plain approve text without visible card
+
+场景：
+
+- 用户直接发“同意”
+- 当前没有审批卡、没有审批编号
+
+期望：
+
+- 不能静默吞掉
+- 应明确告知“当前没有可确认的审批对象”或等价信息
+
+### 11.6 mirrored waitingOnUserInput
+
+场景：
+
+- `waitingOnUserInput` 只有 flag，没有实体问题单/elicitation
+
+期望：
+
+- 与审批场景同样处理，不得重复犯同类错误
+
+## 12. 验收标准
+
+这类问题修好后，前台体验必须满足下面三条：
+
+1. **只要系统说“等你审批”，用户就一定看得到可操作审批内容。**
+2. **如果审批内容还没真正送达，系统不能把后续自然语言拦截成“你还没审批”。**
+3. **用户发“同意/拒绝”时，要么能正确处理，要么明确告诉用户当前没有可确认的审批对象，不能再自相矛盾。**
+
+## 13. 一句话结论
+
+这次 bug 的本质不是“偶发漏发一张卡”，而是：
+
+> **bridge 把 runtime 的等待审批状态过早解释成了“用户已经拥有审批对象”，从而把会话错误地切进了阻塞态。**
+
+后续修复必须围绕一个硬原则展开：
+
+> **审批阻塞只有在审批实体已成功送达到用户前台时才成立；否则它应被建模为异常同步态，而不是用户待操作态。**
+
+## 10. 实现收口（2026-03-17）
+
+本问题已按“先实体可见，再进入真实 waiting_approval 阻塞态”收口：
+
+1. `receiver.onApproval` 先把 approval record 以 `visible: false` 落库。
+2. 只有 `approval_requested` 真正成功发到 channel 后，才调用 `markApprovalVisible()`，并把 session / ledger 切到真实 waiting approval。
+3. `onThreadStatus` 若只观察到 `waitingOnApproval` flag、但还没有可见审批实体，只会发“审批详情同步中”的非阻塞提示，不再把后续自然语言误拦截成 `waiting_user_follow_up_intercepted`。
+4. 针对这一条补了自动化用例：`tests/integration/session/approval-flow.test.mjs` 中 `waitingOnApproval flag without visible approval artifact does not block follow-up input`。
+
+因此，这个问题现在已经不是 pending 行为。后续若再出现，只应按新状态机视为 regression。
+