work-ally 0.2.0-alpha.1

package/docs/issues/resolved/ANALYSIS-blocking-state-visible-without-user-actionable-artifact-2026-03-16.md

@@ -0,0 +1,261 @@
+# 分析报告：阻塞态已对用户可见，但用户可操作实体缺失
+
+更新时间：2026-03-16  
+状态：已修复并补门禁（2026-03-17）  
+作者：Codex
+
+## 1. 这份报告回答什么
+
+这份报告不是只看某一条具体审批或某一次具体 user input 漏发，而是把最近两类真实事故收成同一个上位问题：
+
+> bridge 已经对用户宣告“当前轮进入阻塞态”，但用户实际上没有拿到可操作的阻塞实体；随后 bridge 又继续把用户后续消息拦下来，导致会话被错误挂起。
+
+这份文档要回答的是：
+
+1. 这是不是同一个问题家族。
+2. 它和单点审批 bug 的关系是什么。
+3. 它到底暴露的是实现漏洞，还是状态机设计问题。
+4. 后续修复应该围绕什么硬原则展开。
+5. 需要补哪些专项测试门禁。
+
+## 2. 结论先说
+
+结论很明确：
+
+- `waitingOnApproval` 缺审批卡
+- `waitingOnUserInput` 缺问题实体
+- MCP 纯读取应默认自动放行，但在真实链路中仍进入了 `waitingOnUserInput`
+
+这三件事，本质上是同一个上位问题：
+
+> **bridge 把 runtime thread 的 waiting flag 误当成了“用户已经拿到可操作实体”的充分条件。**
+
+这会造成同一种坏结果：
+
+1. 用户先看到“等你审批”或“等你回复”。
+2. 但前台没有审批卡、没有问题内容、也没有可执行句柄。
+3. 用户继续发自然语言时，bridge 不再转给 Codex，而是本地拦截。
+4. 用户会感知为“中间层把事情吞了”。
+
+## 3. 两个现场案例
+
+## 3.1 案例 A：Ally 的审批阻塞
+
+相关材料：
+
+- `docs/issues/resolved/ANALYSIS-approval-waiting-visible-but-approval-artifact-missing-2026-03-16.md`
+- archive：`/Users/allenfeng/.work-ally/assistants/Ally/.system/archive/2026/03/16/feishu--oc_1890ff7f9132a7d90b09765f27ff5bc8.ndjson`
+- timeline：`/Users/allenfeng/.work-ally/assistants/Ally/.system/logs/timeline-2026-03-16.log`
+
+已确认事实：
+
+1. runtime thread 进入了 `waitingOnApproval`。
+2. bridge 向用户发了：`当前已暂停，等待你审批后继续。`
+3. 但前台没有看到任何审批卡，也没有审批编号。
+4. 用户后续发 `进展如何？`、`同意`，都被 bridge 拦截，没有转给 Codex。
+5. 当前审批解析逻辑要求审批卡上下文或显式 `/approve <id>`；本次场景两者都不存在。
+
+该案例已经可以单独定义为：
+
+> 用户可见“等待审批”，但审批实体缺失。
+
+## 3.2 案例 B：TiRTC-Copilot 的用户输入阻塞
+
+相关材料：
+
+- archive：`/Users/allenfeng/.work-ally/assistants/TiRTC-Copilot/.system/archive/2026/03/16/feishu--oc_069d4ac4263d1a869e05ae86f095376a.ndjson`
+- bridge log：`/Users/allenfeng/.work-ally/assistants/TiRTC-Copilot/.system/logs/bridge-2026-03-16.log`
+- session meta：`/Users/allenfeng/.work-ally/assistants/TiRTC-Copilot/.system/runtime/sessions/feishu--oc_069d4ac4263d1a869e05ae86f095376a/meta.json`
+
+已确认事实：
+
+1. `2026-03-16T14:22:11Z` 左右，runtime thread 进入 `waitingOnUserInput`。
+2. bridge 向用户发了：`当前已暂停，等待你回复后继续。`
+3. 但 archive 里没有对应的 `user_input_requested` 可见实体，也没有任何真正的问题内容。
+4. session meta 中 `pendingUserInputRequestId` 仍为 `null`，说明 bridge 自己也没有拿到稳定的用户输入请求对象。
+5. 用户后续发 `继续`、`同意`，都被 bridge 按 `waiting_user_follow_up_intercepted` 拦截，没有转给 Codex。
+
+该案例可以定义为：
+
+> 用户可见“等待补充信息”，但用户输入实体缺失。
+
+## 4. 关于 MCP 纯读取默认审批的额外判断
+
+从产品意图和现有实现口径看：
+
+- Feishu MCP 的纯读取，本来应当默认自动放行；
+- 现有代码里，MCP tool approval / elicitation 确实存在 auto-resolve 逻辑；
+- 因此正常情况下，这类读取不应把用户卡在等待人工输入或等待人工审批。
+
+但 TiRTC-Copilot 的真实现场表明：
+
+1. 这次仍然进入了 `waitingOnUserInput`；
+2. 同时没有用户可见输入实体；
+3. 也没有自动放行结果稳定落地。
+
+所以当前可以得出的工程判断是：
+
+> **MCP 默认自动放行这条产品承诺，并没有在所有真实运行态里被稳定兑现。**
+
+这不一定说明规则表完全错误，但至少说明：
+
+- 要么 runtime 发出的 user input / elicitation 结构没有被当前 auto-resolve 逻辑识别；
+- 要么这条 user input 实体在 `runtime-client -> receiver` 链路中漏接了；
+- 要么 auto-resolve 生效前，bridge 已经先根据 waiting flag 把会话切进阻塞态。
+
+无论是哪一种，都属于中间层要修的问题，而不是用户侧的问题。
+
+## 5. 统一问题定义
+
+把两个案例并起来，这类问题的统一定义应该是：
+
+> **bridge 目前把 runtime waiting flag 当成了“用户已具备下一步操作条件”的事实，但没有强制要求对应的用户可操作实体已经成功到达前台。**
+
+这里的“用户可操作实体”包括但不限于：
+
+- 审批卡
+- 审批编号
+- user input 问题内容
+- elicitation 表单 / schema 问题
+- 被 auto-resolve 后的明确收口结果
+
+只要这些实体缺失，bridge 就不应把用户侧会话切进真正的 `waiting_user` 阻塞态。
+
+## 6. 根因分析
+
+### 6.1 第一层根因：阻塞态判定依据过早
+
+当前实现看到：
+
+- `waitingOnApproval`
+- 或 `waitingOnUserInput`
+
+就会先对用户发送等待提示，并更新本地 execution status。
+
+但这一步只说明 runtime thread 的内部状态变化，并不能证明：
+
+- 审批对象已经到达用户前台；
+- 问题表单已经到达用户前台；
+- auto-resolve 已经生效并结束；
+- 用户现在真的有能力采取下一步动作。
+
+### 6.2 第二层根因：阻塞态和“用户可操作实体”没有强绑定
+
+当前模型缺少一个关键约束：
+
+> **只有当用户可操作实体已经被 bridge 成功持久化并成功发给前台时，阻塞态才允许成立。**
+
+现在这个约束不存在，所以才会出现：
+
+- 有 waiting flag
+- 没有实体
+- 但已经阻塞会话
+
+### 6.3 第三层根因：follow-up 拦截条件过宽
+
+当前 follow-up 拦截是根据本地 `waitingState` 做的，而不是根据“当前是否真的存在用户可处理的 pending object”做的。
+
+于是就会出现：
+
+- 用户发 `进展如何？`
+- 用户发 `同意`
+- 用户发 `继续`
+
+bridge 一律不转给 Codex，而是直接回：
+
+- 你还没审批
+- 你还没补充信息
+
+这对用户来说是错误指控，因为前提条件根本不存在。
+
+### 6.4 第四层根因：auto-resolve 和 waiting state 缺少原子性
+
+MCP 默认自动放行本来是为了减少人为阻塞，但现场说明：
+
+- 这条自动决策没有在所有运行态里形成稳定闭环；
+- `waitingOnUserInput` 可能先暴露给状态机；
+- auto-resolve 或请求实体对账没有及时完成；
+- 前台于是先进入错误阻塞态。
+
+因此，auto-resolve 不是单独一个小 feature，而必须纳入同一套阻塞状态机设计中。
+
+## 7. 修复原则
+
+这类问题后续应统一按下面四条原则修改。
+
+### 7.1 原则一：没有用户可操作实体，就不能进入真正阻塞态
+
+- 没有审批卡，不得宣称“等待你审批”
+- 没有 user input 问题内容，不得宣称“等待你回复”
+- 没有稳定 auto-resolve 结果，也不得先把会话切成用户待处理
+
+### 7.2 原则二：waiting flag 只能是候选信号，不能直接当最终事实
+
+`waitingOnApproval` / `waitingOnUserInput` 只能表示：
+
+- 当前轮疑似进入阻塞环节
+
+它不能直接表示：
+
+- 用户已经获得审批对象
+- 用户已经获得输入问题
+- 用户当前应该对 bridge 负责完成下一步
+
+### 7.3 原则三：阻塞态需要拆成“候选阻塞态”和“可操作阻塞态”
+
+建议至少拆出两层：
+
+- `blocking_visibility_pending`
+  - 只看到了 waiting flag，或只知道当前轮可能卡在某个阻塞点
+  - 但用户侧可操作实体还没有稳定到达
+- `waiting_user_action`
+  - 审批卡 / user input 请求 / auto-resolve 收口结果已经稳定就位
+  - 这时才允许真正阻塞后续自然语言
+
+### 7.4 原则四：follow-up 拦截要以“pending object 存在”为前提
+
+以后只有在以下前提成立时，才允许拦截用户自然语言：
+
+- 当前有明确 pending approval record，且用户前台已见到对应卡片
+- 或当前有明确 pending user input record，且用户前台已见到问题实体
+
+如果没有这些前提：
+
+- 用户消息不应被误拦截
+- 应继续转给 Codex，或进入更准确的“阻塞详情同步中”异常提示
+
+## 8. 建议测试门禁
+
+后续至少要补这几个专项场景：
+
+1. `waitingOnApproval` flag 出现，但审批卡缺失
+2. `waitingOnUserInput` flag 出现，但问题实体缺失
+3. MCP pure-read 本应 auto-resolve，但 waiting flag 先到
+4. waiting flag 和实体晚到的时序错位
+5. 用户在“只有 waiting flag、没有实体”阶段继续追问
+6. 用户在没有审批卡/没有问题表单的情况下直接发 `同意` / `继续`
+7. auto-resolve 成功后，不应再把会话留在用户阻塞态
+
+## 9. 一句话结论
+
+这不是两个分散 bug，而是一个统一设计缺口：
+
+> **bridge 先根据 waiting flag 宣布“轮到用户处理”，却没有先证明用户真正拿到了可操作对象。**
+
+后续修复时，审批链路、用户输入链路、MCP auto-resolve 链路，都应按同一套阻塞状态机原则统一收口。
+
+## 10. 实现收口（2026-03-17）
+
+这个上位问题已按统一原则收口：
+
+1. waiting flag 不再直接等价于用户已拿到可操作实体。
+2. approval / user input 都改成“先 invisible 落库，发送成功后再 mark visible”。
+3. `classifyConversationState()` 与 follow-up interception 只认 session 中已经可见的 pending approval / pending user input，不再单靠 runtime waiting flag。
+4. 当 runtime 已进入 waiting，但实体还没同步到前台时，bridge 只发“详情同步中”的非阻塞提示，不再错误声称“正在等你审批 / 等你回复”。
+5. 对应门禁已补：
+   - `tests/integration/session/approval-flow.test.mjs`
+   - `tests/integration/session/user-input-flow.test.mjs`
+   - `tests/unit/session/session-store.test.mjs`
+
+这意味着 approval 缺卡、user input 缺题、waiting flag 晚于实体/早于实体的错位，都已经纳入同一套可验证的状态机约束。
+