work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-session-presence-and-state-visibility.md

@@ -0,0 +1,397 @@
+# Session Presence And State Visibility
+
+更新时间：2026-03-15  
+状态：Partially shipped / baseline updated 2026-03-18
+
+> 注：这份 spec 建立了“对话内可见性”的基础思路，但自 2026-03-18 起，bridge 前台边界已进一步收紧。后续实现与产品口径以 `docs/planning/SPEC-minimal-bridge-semantics-and-user-visible-surface.md` 为准：默认只转发事实，不解释内部 recovery / stale cleanup / artifact pending 等实现层状态。
+
+## 1. 背景
+
+当前 `work-ally` 已经有一部分“工作中”反馈能力：
+
+- 入站后有轻量 ack reaction
+- 长耗时 turn 期间，bridge 会发送 `progress_update`
+- 等审批、等补充信息、runtime 不可用时，也有不同文案
+
+但在真实 Feishu 对话里，用户仍然会频繁遇到一个核心问题：
+
+> **我不知道 assistant 现在到底还在干活，还是已经停下来了，还是其实在等我。**
+
+这说明当前产品缺的不是单一文案，而是一套稳定的**会话状态可见性**能力。
+
+## 2. 问题定义
+
+当前缺口主要有三类。
+
+### 2.1 已收到后的任务状态语义仍需克制表达
+
+现在 ack reaction 只能说明“系统看到了消息”，但如果再补一条通用“开始处理”文案，又会引入新的噪音。因此关键不再是简单加一句收到文案，而是让用户只在真正重要的状态切换时得到提示：
+
+- 是否真正进入处理
+- 是否已经启动 turn
+- 是否只是消息到了桥接层
+- 当前是否已经进入“等待我操作”或“恢复未确认”
+
+对 IM 用户来说，这个差别很重要。
+
+### 2.2 长时间无消息时，用户无法判断是忙、卡、还是结束
+
+虽然系统有 heartbeat 机制，但当前默认心跳周期较长，而且它主要覆盖“turn 正在运行”的阶段。
+
+因此用户会遇到歧义：
+
+- assistant 仍在处理
+- runtime / bridge 出现异常
+- 当前轮其实已经结束，只是系统没明确宣布状态
+
+### 2.3 “等待用户动作”没有被提升为明确状态
+
+当系统处于以下状态时：
+
+- 等审批
+- 等补充信息
+- 等用户继续推进
+
+当前虽然有局部消息，但没有形成稳定、统一、显式的“现在轮到你了”状态模型。
+
+## 3. 目标
+
+建立一套面向 Feishu 对话的最小 presence / state visibility 能力，让用户随时知道：
+
+1. assistant 是否已开始处理
+2. assistant 当前是在工作、卡住、还是等我
+3. 一轮任务是否已经结束并回到空闲状态
+
+## 4. 非目标
+
+本 feature 不做：
+
+- 实时细粒度 token 流可视化
+- 复杂 dashboard 或独立控制台
+- 完整 workflow engine 状态机
+- 替代 `/status` 的重型管理面板
+
+这是一条 **对话内可见性** feature，不是运维看板 feature。
+
+## 5. 产品定义
+
+### 5.1 要暴露给用户的最小状态集合
+
+V1 只保留下面五类状态：
+
+1. reaction ack（轻量收到）
+2. `正在处理`
+3. `等待你操作`
+4. `处理异常 / 正在恢复`
+5. `本轮已结束 / 当前空闲`
+
+### 5.2 用户侧的核心问题
+
+用户在任何时刻都应能回答下面这两个问题：
+
+1. **现在是谁在动？**
+   - assistant 在动
+   - 轮到我动
+2. **这一轮结束了吗？**
+   - 还没结束
+   - 已结束
+
+## 6. 建议状态模型
+
+### 6.1 Received
+
+含义：消息已被 bridge 接住，并且准备进入处理。
+
+建议表现：
+
+- 保留 reaction ack
+- 正常路径不再额外补一条“已收到，开始处理”文本状态；只有进入真实 runtime 进度、等待用户或异常恢复时再显式出声
+
+原因：reaction 已足够表达“bridge 已接住消息”；继续补通用收到文案会把正常对话刷成状态流。
+
+### 6.2 Running
+
+含义：当前 turn 正在执行。
+
+建议表现：
+
+- 首条 running 文案尽早发送，不等太久
+- 后续 heartbeat 继续存在，但间隔应更贴近 IM 体验
+- runtime 有中间 commentary 时，优先发真实进度；无真实进度时再发通用 heartbeat
+
+### 6.3 WaitingUser
+
+含义：assistant 当前没有继续推进所需条件，正在等用户动作。
+
+包括：
+
+- approval pending
+- user input pending
+- 其他明确需要用户继续的中间状态
+
+建议表现：
+
+- 不只发审批卡或提问文案
+- 还要显式告诉用户：**当前已暂停，等待你回复/审批后继续**
+
+### 6.4 Recovering / Blocked
+
+含义：系统异常、runtime 不可用、连接抖动，当前无法正常推进。
+
+建议表现：
+
+- 明确说是系统问题，不要继续假装“正在思考中”
+- 明确当前是否在自动恢复
+- 如果本轮无法恢复，明确提示用户重发上一条消息
+
+### 6.5 Idle / Completed
+
+含义：上一轮已经结束，当前没有活跃任务。
+
+建议表现：
+
+- 最终回复成功发出后，用户应默认理解为本轮结束
+- 对某些没有 final reply 的中间分支，也应有显式“当前空闲”回落信号
+
+这里的重点不是一定要额外发一条“已结束”，而是要避免让用户长期处于“不知道现在是不是结束了”的状态。
+
+## 7. 核心产品判断
+
+### 7.1 不能只做 heartbeat
+
+heartbeat 只能解决“长时间处理中没声音”的问题。
+
+它解决不了：
+
+- 是否已经真正开始处理
+- 是否已切到等待用户
+- 是否本轮已经结束
+
+所以本 feature 本质上是 **状态切换通知**，不是单纯“更频繁的工作中文案”。
+
+### 7.2 不能把判断责任丢给用户
+
+用户不应该通过下面这些线索自行猜测：
+
+- 有没有 reaction
+- 有没有过了很久
+- 有没有最终回复
+- 有没有看起来像卡住
+
+中间层必须主动把状态语义讲清楚。
+
+### 7.3 `/status` 是诊断入口，不是常规 presence 替代品
+
+`/status` 仍然有价值，但它更像诊断工具。
+
+常规 IM 交互里，用户不应每次都靠 `/status` 才知道当前到底发生了什么。
+
+## 8. 建议实现切片
+
+### Phase 1：补齐状态切换文案
+
+先不引入新协议，优先基于现有 outbound 类型补齐文案与发送时机：
+
+- 收到后快速补一条 `status_reply`：已收到，开始处理
+- heartbeat 首次触发更早
+- 审批 / user input 出现时，补显式“等待你操作”状态
+- runtime 故障时，切换成恢复/阻塞状态，而不是继续假装运行中
+
+## 8.1 V1 明确范围
+
+本次实现只做 Feishu / 当前 channel 通用对话链路里的最小闭环，不额外扩协议。
+
+V1 必做：
+
+1. 收到用户消息后，先保留 reaction ack，不再默认补“已收到，开始处理”文本状态
+2. 只有存在真实 runtime 中间进度时，才发送对应的工作中消息
+3. 出现审批或补充信息时，额外补一条“等待你操作”状态
+4. runtime 故障 / 恢复中时，保持现有故障提示，但不再继续发送误导性的“正在思考中”
+5. 保持最终回复仍然是本轮结束的主要信号，不额外引入多余“已结束”噪音
+6. 如果本轮已经结束，但没有可见正文可发，必须补一条明确的“本轮已结束 / 当前没有更多动作”系统状态，避免用户误以为 assistant 仍在后台继续工作
+
+V1 不做：
+
+- 新的持久化状态字段
+- 新的 channel 协议类型
+- 独立面板、会话列表或状态总览 UI
+- “空闲”状态的额外独立通知
+
+## 8.2 直接派工实现点
+
+建议工程按下面顺序做。
+
+### A. 文案层
+
+文件：`bridge/src/translator.ts`
+
+新增或整理三类明确文案：
+
+1. `waiting_user` 文案
+   - 审批场景：`当前已暂停，等待你审批后继续。`
+   - 补充信息场景：`当前已暂停，等待你回复后继续。`
+3. 继续保留现有 heartbeat / recovery 文案，但避免语义重叠
+
+要求：
+
+- 文案短
+- 明确说清“现在谁在动”
+- 不引入工程内部术语
+
+### B. Receiver 发送时机
+
+文件：`bridge/src/receiver.ts`
+
+需要补三个发送点：
+
+1. **收到消息并准备 runTurn 前**
+   - 发送一条 `status_reply`
+   - 文案为 `已收到，开始处理`
+   - 这条消息应在 reaction ack 之后、真正进入 turn 之前发出
+
+2. **首次 running 心跳前移**
+   - 不要求立刻狂发 heartbeat
+   - 但要确保用户在短时间内能看到“正在处理”的文本状态
+   - 若 runtime 很快给出真实 progress，则以真实 progress 为准；若没有，则 fallback 到通用 heartbeat
+
+3. **进入等待用户状态时**
+   - `onApproval` 里，在审批卡之外，补一条 `status_reply`
+   - `onUserInput` 里，在问题文案之外，补一条 `status_reply`
+   - 文案明确说明：当前已暂停，等待你操作后继续
+4. **完成但无正文时**
+   - 若 turn 已 `completed`，但最终可见 reply 为空，不要静默结束
+   - 改发一条带系统前缀的 `status_reply`
+   - 文案明确说明：本轮已结束，当前没有更多动作；如需继续，请直接发下一条消息
+
+额外要求：
+
+- 如果当前已经进入 waiting_user，不应继续发送“正在思考中，请稍候…”类 heartbeat
+- runtime unavailable 分支保持现有逻辑，不再伪装成 running
+
+### C. 心跳策略
+
+文件：`bridge/src/receiver.ts`、必要时 `bridge/src/config.ts`
+
+V1 不一定要改默认配置值，但至少要满足：
+
+- 在测试与真实体验上，首次可见 running 状态明显早于当前用户体感
+- 不让用户长期只有 reaction 而没有文本状态
+
+如果工程上更稳妥，可以这样做：
+
+- 保留现有 `progressHeartbeatSeconds` 作为常规周期
+- 但新增一次性的“首条运行提示”快速发送逻辑
+
+这样改动更小，也更符合 V1。
+
+### D. 测试补齐
+
+优先补 integration tests，文件建议放在：
+
+- `tests/integration/session/*.test.mjs`
+
+至少补这几类：
+
+1. `received` 文案测试
+   - 用户消息进入后，除了 ack reaction，还能看到 `status_reply: 已收到，开始处理`
+
+2. running 可见性测试
+   - 慢任务开始后，用户能在短时间内收到明确 running 文案或真实 progress
+
+3. waiting approval 测试
+   - 出现审批时，除了审批卡，还会收到“等待你审批后继续”的状态提示
+
+4. waiting user input 测试
+   - 出现补充信息请求时，除了问题文案，还会收到“等待你回复后继续”的状态提示
+
+5. waiting 状态下不再伪装 running
+   - 进入 waiting_user 之后，不再继续发通用 thinking heartbeat
+
+6. runtime unavailable 测试
+   - 继续验证故障时不会发误导性的 running heartbeat
+
+### E. 文档回写
+
+至少同步更新：
+
+- `docs/user-quickstart.md`
+- `docs/troubleshooting.md`
+- 如有必要，`docs/manual-acceptance.md`
+
+要让用户侧文档能回答：
+
+- 为什么我会看到“已收到，开始处理”
+- 为什么系统会提示“等待你操作”
+- 哪些情况下说明 assistant 还在工作，哪些情况下说明已经轮到我
+
+### Phase 2：统一 presence 事件模型
+
+如果 Phase 1 验证有效，再考虑抽出统一的 presence 状态事件，例如：
+
+- `received`
+- `running`
+- `waiting_user`
+- `recovering`
+- `idle`
+
+这样后续 CLI、日志、面板都可以复用一套状态语义。
+
+## 9. 验收标准
+
+满足以下条件时，本 feature 才算成立：
+
+1. 用户发出消息后，能明确知道系统已开始处理，而不只是看到 reaction
+2. 长耗时处理中，用户能持续知道当前仍在运行
+3. 等审批或等补充信息时，用户能明确知道当前轮到自己动作
+4. runtime 或连接异常时，系统不再继续伪装成“正常思考中”
+5. 一轮任务结束后，用户不会长时间处于“到底结束没”的模糊状态
+
+补充成工程可验收口径：
+
+- 用户发消息后，channel 中出现 `status_reply`，文本明确表达“已收到，开始处理”
+- slow turn 下，channel 中出现至少一条 running 可见性消息
+- approval / user input 场景下，channel 中出现一条 waiting_user 状态消息
+- waiting_user 建立后，不会继续发送通用 thinking heartbeat
+- runtime unavailable 场景下，继续发送故障/恢复提示，而不是 running heartbeat
+
+## 10. 与现有主线的关系
+
+这条 feature 应视为 `会话 mobility / 状态可见性` 主线的一部分。
+
+它优先于真正的面板建设，因为：
+
+- 面板只是状态放大器
+- 状态模型才是底层产品能力
+
+没有稳定的状态语义，做更重的工作台只会放大模糊感。
+
+## 11. 可直接转交工程师的任务说明
+
+### 任务标题
+
+补齐 Feishu 对话内的 session presence / state visibility，解决“用户无法判断 assistant 是在工作、在等我还是已经停下”的体验缺口。
+
+### 任务目标
+
+在不引入新协议、不做重面板的前提下，让用户在对话中明确看到：
+
+- 已收到，开始处理
+- 正在处理
+- 等待你操作
+- 异常/恢复中
+
+### 主要改动文件
+
+- `bridge/src/translator.ts`
+- `bridge/src/receiver.ts`
+- `tests/integration/session/*.test.mjs`
+- 可能涉及 `docs/user-quickstart.md` / `docs/troubleshooting.md` / `docs/manual-acceptance.md`
+
+### Definition of Done
+
+1. 收到消息后，除了 reaction ack，还能看到明确的开始处理状态
+2. 长耗时任务不会让用户长期无感知
+3. 审批/补充信息时，用户能明确知道当前轮到自己操作
+4. 等用户期间不再继续伪装成 assistant 正在思考
+5. 故障/恢复提示保持明确
+6. 对应 integration tests 补齐并通过