docs(cases/06): mark T7/T8/T9 done with impl locations & design trade-offs

Records the durable per-session run-registry implementation (bridge branch
fix/gateway-durable-run-registry): T7 gateway-unconfirmed fallback, T8 terminal
result cache, T9 DeadlineAt interrupt — with the trade-offs (no gatewayruntime
pending-map rewrite; per-session in-memory store not yet cross-restart durable;
T9 only force-terminates when the gateway is unconfirmed) and the test names that
cover each.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Haitao Pan 2026-06-26 18:54:40 +08:00
parent aa75364001
commit fb7e0ac7ef

View File

@ -152,17 +152,24 @@ Gateway 部署出处:`ai-workspace-infra/playbooks/deploy_gateway_openclaw.yml
### L1 Bridge 持久化ai-workspace-lab/xworkmate-bridge · 根因修复 · 有协议/状态面改动)
- [ ] **T7 run 关联与 WS 连接解耦**
维护 `runId → {status, result, artifacts, deadline}` 的持久 / 独立登记表,由 gateway notification 更新。`onConnLost``runtime.go:802`)时**不要把长任务 pending 直接判死**,而是标记 `detached`,重连后用 `runId` 复关联 / 回放完成事件
验收WS 瞬断 + 重连后,已完成的 run 仍能被 `tasks.get` 查到 terminal + artifacts
> ✅ T7/T8/T9 已实现(分支 `fix/gateway-durable-run-registry`)。
> 实现取舍:**复用已存在的 per-session 持久 store**`s.sessions[sessionID]` 内的 `task`/`openClaw`/`lastResult`,生命周期独立于 bridge↔gateway WebSocket`tasks.get` 从「强依赖 gateway 应答」改造为「优先用持久 run 仓兜底」
> 新增 `internal/acp/openclaw_run_registry.go`+ `_test.go`),改动 `rpc_handler.go: handleTaskGet``orchestrator.go: startOpenClawGatewayTask`
- [ ] **T8 OpenClaw submit 接入 `xworkmate.jobs.*` 持久存储**
让 gateway submit 落 `xworkmate.jobs.*``rpc_handler.go:73` 已有 submit/get/list/stats使结果不再只活在内存 `responseCh`
验收bridge 重启 / 连接抖动后,结果与 artifacts 仍可检索。
- [x] **T7 run 关联与 WS 连接解耦**`openClawTaskGetGatewayUnconfirmedFallback``openclaw_run_registry.go`
gateway 无法确认unavailable / socket closed / not_found但 run 仍在预算内时,按 `runId` 从持久 session store 合成 `running` 句柄让客户端继续轮询,跨越瞬时抖动。
**取舍**:未直接改 `gatewayruntime.onConnLost``runtime.go:802`)的 pending 判死逻辑——在途请求被判死后会以 gateway error 冒泡到 `handleTaskGet`,新兜底按 runId 续轮询到 deadline 已等价覆盖,且风险远低于重写连接层 pending 关联。chat.send 初次提交若 WS 中断则尚无 runId、无可复关联客户端重发即可。
验收WS 瞬断 + 重连后,已完成的 run 仍能被 `tasks.get` 查到 terminal + artifacts`TestGatewayUnconfirmedFallbackWithinBudgetKeepsPolling`)。
- [ ] **T9 服务端 DeadlineAt 兜底终态**
run 过期且 gateway 无法确认时bridge 主动回 terminal `interrupted`(而非无限 `running`),给客户端确定终态。与 T3 客户端 deadline 形成双保险。
验收gateway 失联超过 budget 后,`tasks.get` 返回确定 terminal。
- [x] **T8 终态结果落持久 run 仓**`cacheOpenClawTaskGetResultIfTerminal` / `cachedTerminalForRunLocked`
gateway 确认终态后,把**最终客户端形态**(已 decorate 下载 URL + strip 内联内容)缓存进 `sess.lastResult`后续轮询直接回放gateway 之后查不到也不丢。带 `runId` 校验 + 新 turn 复用 session 时重置 `ProgressTerminal`,防旧 run 终态错配新 run。
**取舍**:未新建独立 `xworkmate.jobs.*` 落库;现阶段复用 per-session 内存 store已满足「跨 WS 抖动不丢结果」。bridge **进程重启**后仍会丢——若需跨重启持久化,再起 T8b 接 `jobs.*` / 磁盘。
验收:连接抖动后结果与 artifacts 仍可检索(见 `TestTerminalResultCachedAndServedAfterGatewayLoss`、`TestCachedTerminalNotServedForDifferentRunId`)。
- [x] **T9 服务端 DeadlineAt 兜底终态**`markOpenClawRunDeadlineInterruptedLocked`
run 过期(`sess.task.DeadlineAt`)且 gateway 无法确认时bridge 主动回 terminal `interrupted``OPENCLAW_RUN_DEADLINE_EXCEEDED`),与 T3 客户端 deadline 形成双保险。
**取舍**:仅在 gateway **无法确认**时按 deadline 强制终态gateway 明确回 `running` 时**不**强杀,避免误伤合法长任务(那一侧由客户端 T3 兜底)。
验收gateway 失联超过 budget 后,`tasks.get` 返回确定 terminal`TestGatewayUnconfirmedFallbackPastDeadlineInterrupts`)。
- [ ] **T10 错误语义细化**
`gatewayRPCError``orchestrator.go:1678`)区分"连接断但 run 仍在后台可查" vs "run 确实失败",前者携带 `runId` + `retryable/poll` 提示,供客户端走 T5 续轮询而非硬失败。
@ -182,8 +189,8 @@ Gateway 部署出处:`ai-workspace-infra/playbooks/deploy_gateway_openclaw.yml
## 6. 落地顺序建议
1. **当天止血**T1 + T2入口配置+ T3 + T4 + T6客户端消除"30min 必断 / 路由漏配 / 无限 running / 停不掉"。
2. **本周治本**T7 + T8 + T9bridge 持久化与解耦),让"gateway 跑完 = 结果一定拿得到"。
3. **跟进**T5 + T10断连续跑语义、T11 + T12可观测性
1. **当天止血**(已合并 mainT1 + T2入口配置+ T3 + T4 + T6客户端+ session.prepare 数字 code 降级,消除"30min 必断 / 路由漏配 / 无限 running / 停不掉 / session.prepare 硬失败"。
2. **治本**(分支 `fix/gateway-durable-run-registry`T7 + T8 + T9bridge 持久 run 仓与 WS 解耦),让"gateway 跑完 = 结果一定拿得到"。
3. **跟进(待办)**T5 + T10断连续跑语义、T11 + T12可观测性、T8b跨进程重启持久化`xworkmate.jobs.*` / 磁盘)。
> 回归对照:本目录 `00-review-env-and-matrix.md` 第 2 节"通用验收标准"中"长任务执行期间状态流 / 取消 / 重试稳定""同一任务重复执行 3 次不卡死",即本规划的回归出口。