Merge pull request #1325 from pikasTech/issue-1324-spec
docs: require mechanical OpenCode migration review
This commit is contained in:
Lyon
@@ -33,7 +33,7 @@
|
||||
|
||||
Workbench实时运行面负责把浏览器侧多轮 Workbench 的实时输入、SSE 事件、REST snapshot、trace/message 投影、可见性诊断和 Web 哨兵采样收敛为可控、可观测、可回归的运行链路。目标是解除第二轮消息后页面卡死、浏览器内存无界上涨、SSE error 引发 REST 请求风暴、刷新后消息堆叠、跨 session/trace 串线和 monitor 只能看到症状看不到根因的问题。
|
||||
|
||||
本专项采用 OpenCode serve 的边界作为对照：事件流负责 replay 和 ordering，REST 负责初始加载、分页和受控 gap-fill，错误 envelope 统一诊断，队列/single-flight 限制重复工作，timeline row model 保持稳定 identity。HWLAB Vue 侧不物理复制 Solid/Effect/TanStack 代码；纯 TypeScript 策略模块按语义迁移，Vue lifecycle、浏览器 EventSource、Pinia store 和 web-probe 观察层按本文一一对应重写。
|
||||
本专项采用 OpenCode serve 的边界作为对照：事件流负责 replay 和 ordering，REST 负责初始加载、分页和受控 gap-fill，错误 envelope 统一诊断，队列/single-flight 限制重复工作，timeline row model 保持稳定 identity。可整模块迁移的 TypeScript 策略模块必须先按 OpenCode 原文件或原核心函数机械拷贝，再在拷贝件上做 Vue/HWLAB 适配；禁止只阅读 OpenCode 后重写一个薄 wrapper 或只覆盖 happy path。Solid/Effect/TanStack 等框架专属层不直接搬运，但其状态机、分支语义、错误处理和 row/queue/transport 边界必须在 HWLAB runtime 中逐项保真。
|
||||
|
||||
所有可调参数必须来自 YAML/source-of-truth 或其前端 runtime projection。本文和源码只定义字段族、状态机、责任边界和验收读取方式；不得写入硬编码阈值、采样周期、重试次数、并发数、缓存容量、退避窗口、超时窗口或浏览器内存 kill 数值。
|
||||
|
||||
@@ -79,7 +79,7 @@ Workbench实时运行面负责把浏览器侧多轮 Workbench 的实时输入、
|
||||
| 外部使用者 | Workbench 用户、平台值守人员、web-probe smoke、Web 哨兵、OTel 调查 agent、发布验收流程。 |
|
||||
| 外部输入 | 用户消息、session route、REST snapshot、SSE event/cursor、runtime config projection、YAML policy、browser memory sample、Long Task/freeze sample、OTel trace context。 |
|
||||
| 受控资源 | Vue Workbench store、SSE client、event queue、refresh queue、session/cache/timeline model、storage namespace、scroll controller、web-probe observer、OTel/RUM events。 |
|
||||
| 外部输出 | 用户可见 timeline、diagnostic panel、OTel span/attribute、RUM event、web-probe analysis report、monitor red finding、PR/issue closeout smoke evidence。 |
|
||||
| 外部输出 | 用户可见 timeline、diagnostic panel、OTel span/attribute、RUM event、web-probe analysis report、monitor red finding、PR/issue closeout 复查证据。 |
|
||||
| 用户接口 | HWLAB Cloud Web `/workbench`、同源 `/v1/workbench/*` REST/SSE、`web-probe observe`、monitor Web 哨兵报告和受控 GitHub issue/PR。 |
|
||||
| 系统边界 | 本专项只约束浏览器运行面和哨兵观测面；不拥有 durable Workbench facts、AgentRun execution facts、Secret、用户权限或发布流水 source of truth。 |
|
||||
|
||||
@@ -213,8 +213,10 @@ sequenceDiagram
|
||||
| OPS-WBRT-REQ-006 | BrowserRuntime | storage、scroll、pane layout 和 health probe 的失败只能写入 diagnostic 或受控 recovery action；不得通过 reload、fallback、localStorage truth 或 document 级无限滚动掩盖状态分裂。 |
|
||||
| OPS-WBRT-REQ-007 | SentinelFreeze | web-probe 必须把浏览器无响应和浏览器内存超过受控 policy 的状态分类为 blocker red，并保存 memory sample、freeze sample、request family、trace/span 和截图/日志证据；触发 blocker 后必须杀死浏览器，不得自动刷新页面或降级为 fallback。 |
|
||||
| OPS-WBRT-REQ-008 | OTelEvidence | REST/SSE/queue/timeline/web-probe 必须暴露同一 scoped key 摘要、request family、transport state、recovery action 和 root cause 字段，确保 monitor 再次出现 INV/CHECK 类问题时能直接看到根因。 |
|
||||
| OPS-WBRT-REQ-009 | WebProbeSmoke | 每个实现阶段合入或滚动上线后，必须用 `web-probe observe` 对 JD01/HWLAB v0.3 `/workbench` 做 smoke；smoke 证据至少包含页面可操作性、第二轮消息、memory/freeze 判定、request family 摘要和是否出现 blocker red。 |
|
||||
| OPS-WBRT-REQ-009 | CompletionReview | Workbench OpenCode 迁移完成度不以 smoke、上线或一次 web-probe 通过为判据；每个实现阶段必须按 OpenCode 对照、HWLAB 迁移模块、生产接入、旧散逻辑删除/变薄和 guard 结果做多轮复查。web-probe smoke 只作为入口健康补充证据。 |
|
||||
| OPS-WBRT-REQ-010 | StageTracking | 本专项每个执行阶段必须有独立 GitHub 子 issue 跟踪，父 issue 只保存总 SPEC、阶段索引、PR/rollout/web-probe evidence 和剩余风险。 |
|
||||
| OPS-WBRT-REQ-011 | MechanicalCopy | 可迁移的 OpenCode 通用模块必须先机械拷贝再适配；closeout 必须记录 OpenCode 来源行号、HWLAB 拷贝后行号、适配 diff 范围、被保留/删除/改名的能力清单，以及不存在“参考后重写”的复查结论。 |
|
||||
| OPS-WBRT-REQ-012 | ShrinkageReview | 缩水是独立 P0 缺口；如果迁移后模块缺少 OpenCode 原有状态机、错误处理、限流/防抖、SSE/reducer、scroll persistence、timeline row parity 或 root cause 输出，即使生产路径已经 import，也不得判定完成。 |
|
||||
|
||||
## 7. 过程控制和源码引用
|
||||
|
||||
@@ -231,16 +233,16 @@ SPEC: PJ2026-0106050514 Workbench实时运行面 draft-2026-06-30-p0-1297-spec-f
|
||||
| 阶段 | 子 issue 职责 | 退出条件 |
|
||||
| --- | --- | --- |
|
||||
| P0 SPEC | 更新本 SPEC、父 issue P0 gate、阶段子 issue 索引和 YAML 参数来源约束 | 父 issue 链接 SPEC 和所有子 issue，后续代码阶段不再缺规格入口 |
|
||||
| P1 纯 TS 模块 | 迁移/重写 typed error、queue/single-flight、scoped key、timeline row、storage、health 等纯 TS 模块和窄测试 | 模块有源码 SPEC 头，测试覆盖 key/coalesce/cache/timeline/storage/health 基本语义 |
|
||||
| P2 Vue runtime 接入 | 接入 SSE runtime、refresh queue、server-state reducer、timeline/scroll/storage/health 和 OTel/RUM 事件 | 第二轮消息不再请求风暴，刷新后 timeline 不堆叠，scope/key/原因可见 |
|
||||
| P1 纯 TS 模块 | 先机械拷贝 OpenCode typed error、queue/single-flight、scoped key、timeline row、storage、health 等纯 TS 模块或核心函数，再做 HWLAB 类型/API 适配和窄测试 | 模块有源码 SPEC 头，测试覆盖 key/coalesce/cache/timeline/storage/health 基本语义，并能追溯 OpenCode 来源行号 |
|
||||
| P2 Vue runtime 接入 | 接入 SSE runtime、refresh queue、server-state reducer、timeline/scroll/storage/health 和 OTel/RUM 事件 | 第二轮消息不再请求风暴，刷新后 timeline 不堆叠，scope/key/原因可见；store 中对应通用逻辑已删除或变薄 |
|
||||
| P3 Web 哨兵增强 | 接入 browser memory/freeze blocker red、no fallback/no auto refresh 和 monitor root cause 展示 | 卡死或内存 policy 命中时浏览器被杀死并报阻塞红错误，monitor 能看到根因 |
|
||||
| P4 rollout smoke | PR 合并、JD01 滚动上线、web-probe smoke 和 issue closeout | smoke 通过或明确记录 blocker；父 issue 回填 PR、版本、截图/报告和 OTel 证据 |
|
||||
| P4 多轮复查 | issue closeout 前按缩水表、未使用/部分使用/散写表、生产 import/call site 和 guard 结果复查 | 表项达到 100%，父 issue 回填 PR、单测、行号对照、机械拷贝证明和剩余风险；上线和 smoke 不作为完成度前置 |
|
||||
|
||||
P0 未完成前，不得把 P1-P4 标记为可执行完成；P1-P4 中任何稳定语义、字段族、状态机或验收口径变化，必须先更新本 SPEC，再更新对应子 issue 和代码。
|
||||
|
||||
### 7.1 #1315 纠偏完成定义
|
||||
|
||||
#1315 不再以“降低 web-probe/Playwright 启动内存占用”作为修复方向；web-probe 的浏览器资源占用只作为观测 baseline。真正完成标准是：OpenCode 可整模块迁移的能力在 HWLAB Vue Workbench 中 100% 完成机械复制/语义重写/生产接入，且所有新增策略参数都由 YAML 或 runtime projection 控制。
|
||||
#1315 不再以“降低 web-probe/Playwright 启动内存占用”作为修复方向；web-probe 的浏览器资源占用只作为观测 baseline。真正完成标准是：OpenCode 可整模块迁移的能力在 HWLAB Vue Workbench 中 100% 完成机械拷贝、适配和生产接入，且所有新增策略参数都由 YAML 或 runtime projection 控制。
|
||||
|
||||
| 编号 | 迁移模块 | OpenCode 对照能力 | HWLAB 目标接入点 | 完成口径 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
|
||||
Reference in New Issue
Block a user