work-ally 0.2.0-alpha.1

package/docs/planning/SPEC-active-turn-steer-and-context-compaction-visibility.md

@@ -0,0 +1,269 @@
+# SPEC: Active Turn 默认 Steer 与 Context Compaction 可见性
+
+更新时间：2026-03-18  
+状态：Shipped  
+Owner：work-ally product / engineering  
+相关文档：
+- `docs/planning/SPEC-bridge-app-server-protocol-alignment.md`
+- `docs/planning/SPEC-session-presence-and-state-visibility.md`
+- `PRODUCT.md`
+- `AGENTS.md`
+
+## 1. Summary
+
+这是一条很小的协议收口型 feature，只做两件事：
+
+1. 当同一条 thread 仍有 active turn，且当前没有已对用户可见的 blocking request 时，用户新的普通自然语言输入默认走 `turn/steer`，不在 bridge 里再造 queue 模式。
+2. 当 Codex App Server 发出 `contextCompaction` item 时，若这条 turn 当前属于 `work-ally` 渠道侧可见工作流，bridge 诚实观测并发送一条轻量系统消息：`Codex 正在压缩当前会话上下文。`
+
+这不是新状态机，也不是一套“更聪明的中间层”。
+
+它的本质是把 `work-ally` 再往正确边界收紧一步：
+
+> 官方已有稳定协议原语时，中间层默认直接复用；只补最小必要的产品可见性，不重做第二套语义。
+
+## 2. 背景
+
+目前有两个相邻问题。
+
+### 2.1 active turn 期间的新消息，产品合同还不够清楚
+
+App Server 已提供：
+
+- `turn/start`
+- `turn/steer`
+- `turn/interrupt`
+
+官方 CLI 的默认交互也更接近“运行中插话”，而不是“默认排队下一轮”。
+
+但如果 `work-ally` 在这里自己再加一层 queue / pending 队列 / 可配置模式，会把中间层做厚，并让用户多学一层并不必要的新概念。
+
+### 2.2 context compaction 是真实协议事实，但当前用户侧看不到
+
+App Server 已经把 `contextCompaction` 暴露为协议 item。
+
+这意味着：
+
+- Codex 正在压缩会话上下文，不再只是内部黑盒推测
+- bridge 可以观测到这件事
+- 如果用户正通过 Feishu / work-ally 渠道工作，中间层应诚实把这个事实轻量告诉用户
+
+但这件事不值得被做成重状态机或复杂面板；对话里一条克制系统消息就够了。
+
+## 3. 问题定义
+
+本专题要解决两个问题。
+
+### 3.1 busy follow-up 如果不拍板，工程实现容易继续分叉
+
+如果这里不明确规定默认行为，工程实现很容易在以下几种方向之间漂移：
+
+- 本地 queue 一层
+- 本地 busy gate 一层
+- steer 一层
+- 甚至再做用户配置
+
+结果是：
+
+- 用户心智变复杂
+- 中间层语义变厚
+- 后续还要解释“到底什么时候 queue，什么时候 steer”
+
+### 3.2 context compaction 如果完全不可见，用户会误以为 assistant 卡住或失联
+
+当 Codex 压缩上下文时，用户可能看到：
+
+- assistant 还在工作，但暂时没有新正文
+- runtime 正常，只是内部在整理上下文
+
+如果 bridge 明明能观测到这个协议事实，却完全不说，用户很容易把它误解成：
+
+- 卡住了
+- 消息没送进去
+- runtime 出异常了
+
+## 4. 目标
+
+本专题必须达成以下目标：
+
+1. 把 active turn 期间普通 follow-up 的默认路径拍板为 `turn/steer`。
+2. 明确这不是 queue feature，不新增 queue 模式、不新增用户配置。
+3. 当 App Server 发出 `contextCompaction` item 时，渠道侧能收到一条轻量系统消息。
+4. 文案保持克制，只表达协议事实，不扩成“中间层解释世界”。
+5. 保持 bridge 边界轻薄：复用官方协议原语，不重复发明第二套会话语义。
+
+## 5. 非目标
+
+本次明确不做：
+
+1. 不做 queue 模式。
+2. 不在用户面板里加入 `queue / steer` 配置。
+3. 不做 compaction 的完成提示、进度条、独立状态面板。
+4. 不把 compaction 事件上升成新的持久化工作流状态机。
+5. 不改写现有 approval / user-input blocking 合同。
+6. 不顺手扩写为“全面 runtime presence 重做”。
+
+## 6. 产品定义与用户路径
+
+### 6.1 一句话定义
+
+`work-ally` 对 active turn follow-up 的默认产品定义是：
+
+> 只要当前仍在同一条 active turn 上工作，且没有已经对用户可见的 blocking request，新的普通自然语言输入就默认作为“插话”进入当前 turn，而不是由 bridge 额外排队。
+
+同时：
+
+> 当 Codex 自己开始压缩当前会话上下文时，bridge 只做诚实观测，并轻量通知用户一次。
+
+### 6.2 主路径 A：active turn 期间的新普通消息
+
+场景：
+
+- 用户刚发过一条消息
+- 当前 turn 仍在进行中
+- 用户又补充一句自然语言
+
+路径：
+
+1. bridge 先判断这条输入不是 slash 命令。
+2. 如果当前存在 active turn，且当前没有已对用户可见的 approval / user-input blocking request，则默认调用 `turn/steer`。
+3. 新输入进入当前 turn，作为同一轮工作的 follow-up。
+4. bridge 不额外创建 queue，不向用户解释“这条先排队了”。
+
+### 6.3 主路径 B：发生 context compaction
+
+场景：
+
+- 当前渠道侧有一条正在进行中的工作线程
+- App Server 在该 turn 生命周期里发出 `contextCompaction` item
+
+路径：
+
+1. bridge 观测到 `contextCompaction` item started。
+2. 如果该 item 属于当前渠道侧可见 turn，则发送一条系统消息：`Codex 正在压缩当前会话上下文。`
+3. 该消息只表达事实，不追加额外解释，不额外开启新状态流。
+
+### 6.4 例外路径
+
+以下情况不走默认 steer：
+
+1. 输入是 slash 控制命令。
+2. 当前存在已对用户可见的 approval blocking request。
+3. 当前存在已对用户可见的 user-input blocking request。
+4. 当前不存在 active turn，此时正常走 `turn/start`。
+
+### 6.5 竞态回落
+
+如果 bridge 判断当前有 active turn，并尝试 `turn/steer`，但在真正调用时该 turn 已自然结束：
+
+1. bridge 可以做一次最小回落判断。
+2. 若当前 thread 已回到可继续 start 的状态，则将这条输入按正常新 turn 继续推进。
+3. 不因此引入本地 queue。
+
+要求：
+
+- 这是一次协议竞态回落，不是 queue 语义。
+- 文案不额外暴露内部细节，除非失败到用户可感知。
+
+## 7. 机制设计
+
+### 7.1 active turn follow-up 合同
+
+默认规则：
+
+- `slash command`：仍由 bridge 本地消费。
+- `visible blocking request reply`：仍走 approval / user-input 解析路径。
+- `ordinary natural language`：
+  - 若存在 active turn，则优先 `turn/steer`
+  - 若不存在 active turn，则 `turn/start`
+
+这里的“存在 active turn”以 runtime / session 当前事实为准，不再额外引入本地 queue 状态。
+
+### 7.2 为什么不做 queue
+
+产品判断：
+
+- queue 不是当前用户的真实问题。
+- queue 会让用户开始思考“我刚刚那句到底是插话还是排队到下一轮”。
+- queue 一旦开放成配置，又会引入更多解释、验证和 UI 成本。
+
+因此本期直接拍板：
+
+- 默认 steer
+- 不开放 queue
+- 后续若真的出现稳定、明确、用户可感知的 queue 场景，再单独立 spec
+
+### 7.3 context compaction 通知合同
+
+触发条件：
+
+- App Server 发出 `contextCompaction` item started
+- 该 item 属于当前渠道侧正在进行、且用户可感知的一条工作 turn
+
+用户文案：
+
+- `Codex 正在压缩当前会话上下文。`
+
+文案要求：
+
+- 不写“自动”二字，避免对触发来源做超出协议事实的推断。
+- 不写大段解释，不把它扩成帮助文档。
+- 不追加“请稍候”这类低价值语气填充。
+
+### 7.4 去重与噪音控制
+
+为了避免 transport 抖动或重复事件导致刷屏，bridge 应做最小去重：
+
+- 以 `threadId + turnId + itemId` 作为同一次 compaction 事件的去重键
+- 同一个 compaction item 最多通知一次
+
+本期不要求把它做成长期 durable 账本；当前 turn 生命周期内的最小去重即可。
+
+### 7.5 与现有 state visibility 的关系
+
+这条通知不是新状态类别，只是对已有协议事实的一次轻量翻译。
+
+因此：
+
+- 不新增 `compacting` 持久态
+- 不要求 `/status` 先显示它
+- 不改变“最终回复仍是主要结束信号”的原则
+
+## 8. 验收标准
+
+满足下面条件，才算完成：
+
+1. 当 active turn 存在且没有可见 blocking request 时，新的普通自然语言输入默认走 `turn/steer`。
+2. 当 active turn 不存在时，新的普通自然语言输入仍走 `turn/start`。
+3. 当存在可见 approval / user-input blocking request 时，bridge 不错误地把用户回复发成 steer。
+4. 当 App Server发出 `contextCompaction` item 时，渠道侧会收到系统消息：`Codex 正在压缩当前会话上下文。`
+5. 同一个 compaction item 不会重复通知多次。
+6. 实现中没有新增 queue 模式、没有新增用户配置项。
+
+## 9. 验证建议
+
+至少补齐下面验证：
+
+- unit：active turn 下普通 follow-up 选择 `turn/steer` 的路由判断
+- unit：visible blocking request 存在时，不走 steer
+- integration：同一轮工作中第二条自然语言进入 steer 主路径
+- integration：turn 在 steer 调用前自然结束时，最小回落到新 turn 的竞态路径
+- integration：收到 `contextCompaction` item started 时，前台收到对应系统消息
+- integration：重复 compaction 事件不会重复通知
+
+## 10. 风险 / 假设 / 待决问题
+
+### 10.1 风险
+
+- 如果实现里对 active turn 的判断仍然混有旧 busy gate 语义，可能名义上说 steer，实际上仍被桥层提前拦截。
+- 如果 compaction 事件与 channel 可见 turn 的关联关系没理清，可能会把不该前台可见的内部 turn 也通知出去。
+
+### 10.2 假设
+
+- 当前 App Server 的 `contextCompaction` item 在 bridge 事件流中可稳定观测。
+- 现有 session / turn ledger 已足够支撑最小去重键，不需要额外重型状态层。
+
+### 10.3 待决问题
+
+1. `/status` 是否需要在后续专题里顺手显示“最近一次 compaction 发生过”，本期不做。
+2. 若未来真的出现需要显式 queue 的用户场景，应另立 spec，而不是在本专题内偷扩。