diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index 292ed78e..3315493e 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -130,6 +130,7 @@ Workbench 至少覆盖: - Workbench API 的 GET 路径不是修复入口。若 session/messages/turn/trace 出现状态不一致,应登记为投影唯一性或投影延迟问题,修 backend projector/read model;不得用前端轮询、session 切换、reload、read-through sync 或 GET 内部修复把问题掩盖。 - Workbench 读侧不得推理生命周期。`turn.status`、`message.status`、`session.running`、`trace terminal`、`finalResponse`、`projectionStatus` 只能来自唯一 durable projection;trace event row 的 `completed` 只表示该 event/tool row 完成,不能终结 turn;message 文本为空只表示无可展示正文,不能生成占位 final response;list summary、session detail、turn snapshot、trace page 之间的差异只能作为 diagnostic,不得用优先级函数在读侧“选一个看起来合理的状态”。 - Workbench durable projection 验收必须覆盖同一 session/trace 的 list、detail、messages、turn、trace events 和 DOM session tab/message card;尤其要用 fresh browser 或 runtime 重启后的历史 terminal 样本证明 read model 能从 durable trace events 恢复终态。若内存 trace 仍显示 running 而 durable trace 已 terminal,应修唯一 read model 的投影对象,不得在 GET handler、前端 reducer 或 probe 脚本里做临时状态仲裁。 +- HWLAB #1585/#1596 是 Workbench 投影禁令的固定判例:AgentRun 已 terminal 但 Workbench 停在旧 seq 时,不得用 GET/read-side 补 result;turn/card completed 但 TraceEventPage seq/range 不合法时,不得用 completed 状态压过 trace 不可读事实。合法修复是后台 projector/resumer 补 durable projection,或在同一 trace event 快照内修正分页输出契约;不得推断 lifecycle、补写 GET、切 session/reload 修页面或添加多来源优先级。 - Session rail 会话集合只消费 `/v1/workbench/sessions`;当前 session detail 只消费 `/v1/workbench/sessions/{sessionId}`;消息本体只消费 `/v1/workbench/sessions/{sessionId}/messages`;turn 状态只消费 `/v1/workbench/turns/{traceId}`;trace 阅读只消费 `/v1/workbench/traces/{traceId}/events` 或正式 trace event page。不要让 workspace snapshot、列表摘要、localStorage、trace polling 或 result polling 互相覆盖。 - 空消息 session 回收验收必须同时证明:未超过 TTL 的空 session 保留,有消息、running/admitting、terminal result 或 active trace 的 session 不被回收;超过 TTL 的空 idle session 由后端 GC 归档/删除后,rail/list/detail/messages/deep link 都按同一 canonical lifecycle 状态表现。 - UI transient state 只保存 route、显式选择、composer draft、scroll、展开状态和临时交互状态;服务端事实进入 server-state/reducer/projection。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 314935f2..009b9cef 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -72,6 +72,10 @@ Code Agent trace 的长期 API 和 Web 行为规格以 UniDesk OA 为权威:AP Workbench projection/read model 是持久化投影,不是 GET 侧隐式修复路径。Cloud API 重启、内存 finalizer 丢失或投影 worker 中断后,恢复只能由受控后台 projector/resumer 从 durable session、durable trace 和 AgentRun source cursor 继续推进;`/v1/agent/turns/:traceId`、`/v1/agent/traces/:traceId` 和 Web hydrate 不得为了让一次读取看起来正确而隐藏写入或 remap command。排查“AgentRun 已完成但 Workbench 仍 running/pending”时,先比较 AgentRun command result/session terminal、AgentRun raw event 最大 `sourceSeq`、HWLAB durable trace 最大 `sourceSeq` 和 session/turn 投影状态;若 AgentRun 已 terminal 且 HWLAB trace 落后,应归为 HWLAB projection resume gap,并用 YAML-first 配置的 projector/resumer 修复与验收。 +Workbench 投影相关问题的禁用模式以 HWLAB issue 历史为判定边界。`pikasTech/HWLAB#1585` 已证明 GET/read-side 补 AgentRun result 会把恢复能力藏进一次读取,Cloud API 重启、rollout 或内存 finalizer 丢失后仍会让 Workbench 长期停在旧 `lastProjectedSeq`;因此“事后修补/0repair”不能替代 durable projector/resumer。`pikasTech/HWLAB#1596` 已证明 turn/card completed 与 TraceEventPage 不一致会直接变成用户可见的“已完成但暂无可读 Trace”;因此不能让 AgentRun raw result、session summary、turn snapshot、trace tail 或 DOM 互相竞争,再用优先级规则仲裁显示状态。读侧也不得从 event `completed`、message text、elapsed timeout 或 final result cache 推测 lifecycle;这些只能作为诊断输入,最终事实必须由唯一 Workbench projection 写出。 + +TraceEventPage 自身的分页契约修复可以在同一持久化快照内做稳定排序和输出 cursor 归一化,但不得改变 lifecycle、补写 projector 状态或引入第二事实源。修复完成后的关闭证据必须同时覆盖同一 session/trace 的 turn、trace events、range/monotonic cursor 和 DOM Trace 可读性,避免只凭 completed card 或单个 API 通过误关。 + Code Agent trace/result 展示类问题的 typed CLI 关闭证据以 `hwlab-cli client agent result `、`hwlab-cli client agent trace --render web` 和必要的 `hwlab-cli client agent inspect --trace-id ` 为准,具体操作说明见 `$hwlab-code-agent` skill。三者的默认 JSON 都应暴露 `traceResultSummary`,其中 `ids`、`toolCalls`、`agentMessages`、`finalResponse`、`diagnostics`、`counts` 和 `upstreamGaps` 是给用户和审计者阅读的稳定摘要;不要要求关闭者从 raw `body`、`runnerTrace.events`、`rows` 或 `terminalEvidence` 人工拼事实。 `result` 和 `trace --render web` 必须能直接证明 final assistant response、实际工具调用及状态、关键 trace/session/conversation/run/command/runner ID 和 runner/provider/lane 诊断。`inspect` 用于确认 trace 所属 session/conversation/thread、恢复上下文和下一步入口;它可以佐证 ID 和上下文,但不能单独替代 final response 或 Web renderer 行。验证必须打到 issue/CLI 选中的同一 node/lane public origin 或等价 Cloud Web/Cloud API dispatcher,不能用临时 AgentRun manager 调用、手写 raw request 或旧 lane trace 代替。