diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index 9a033950..833e8a88 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -134,8 +134,10 @@ 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 sealed final response 必须与读侧诊断分仓。`messageProjection` 承载 role/status/text/finalResponse/sealedAt，`traceDetail` 承载 events/page hydration/trace diagnostics，`sessionStatus` 承载 rail/card 运行摘要，`transportDiagnostics` 承载 SSE/poll/hydration timeout 等可见性诊断；等价结构可以使用不同命名，但主消息投影和 diagnostic 不能竞争同一字段。`showMessageText()`、message diagnostic selector 和组件模板不得让 diagnostic 压过 sealed final response。 +- Workbench trace 视觉顺序的唯一权威是 durable projection 分配的 `projectedSeq`。`projectedSeq` 必须由持久化 runtime store 在 trace 内全局递增分配，并按 `traceId + sourceEventId` 幂等复用；本地 `event.seq`、`sourceSeq`、事件到达顺序、时间戳、DOM 顺序和 renderer 输入顺序只能作为审计输入或源游标，不能直接派生视觉位置或参与仲裁。重复源事件不能分配新 `projectedSeq`；不同源事件即使局部 `event.seq` 重置为 1 也必须分配新的全局 `projectedSeq`，这个幂等性需要有最小单元测试覆盖。 +- Trace event page 检测到同一 trace 内历史 `projectedSeq` collision 时必须暴露 `projectionStatus=blocked`、`projectionHealth=degraded` 和稳定 blocker code，不能把损坏序列交给 CLI/Web renderer 继续展示。CLI/Web trace renderer 只能按 projection 已给定的位置一次渲染；不得通过 assistant 文本相等/包含、final response 匹配、尾部排序、terminal row 合并或 completion row 追加来事后修正视觉顺序。 - 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 修页面或添加多来源优先级。 +- HWLAB #1585/#1596/#1690 是 Workbench 投影禁令的固定判例：AgentRun 已 terminal 但 Workbench 停在旧 seq 时，不得用 GET/read-side 补 result；turn/card completed 但 TraceEventPage seq/range 不合法时，不得用 completed 状态压过 trace 不可读事实；Trace timeline 乱序或 terminal row 重排时，不得让 `sourceSeq`、局部 `event.seq`、输入顺序和 renderer 文本匹配多来源仲裁。合法修复是后台 projector/resumer 补 durable projection，在同一 trace event 快照内修正分页/顺序契约，或暴露 historical projection blocker；不得推断 lifecycle、补写 GET、切 session/reload 修页面、添加多来源优先级或在 renderer 做事后 repair。 - 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 102204df..6ffbc561 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -72,7 +72,7 @@ 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 写出。 +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 互相竞争，再用优先级规则仲裁显示状态。`pikasTech/HWLAB#1690` 进一步固定 Trace 视觉顺序权威：`projectedSeq` 必须由 durable projection 幂等分配，局部 `event.seq`、`sourceSeq`、输入顺序和 renderer 文本匹配不能参与视觉位置仲裁；历史 collision 应暴露为 projection blocker，而不是交给读侧重排。读侧也不得从 event `completed`、message text、elapsed timeout 或 final result cache 推测 lifecycle；这些只能作为诊断输入，最终事实必须由唯一 Workbench projection 写出。具体 Web/CLI renderer 和 web-probe 验收口径统一见 `$unidesk-webdev`。 TraceEventPage 自身的分页契约修复可以在同一持久化快照内做稳定排序和输出 cursor 归一化，但不得改变 lifecycle、补写 projector 状态或引入第二事实源。修复完成后的关闭证据必须同时覆盖同一 session/trace 的 turn、trace events、range/monotonic cursor 和 DOM Trace 可读性，避免只凭 completed card 或单个 API 通过误关。