docs(webdev): record MDTODO web-probe closeout evidence rules

This commit is contained in:
Codex
2026-06-27 01:35:13 +00:00
parent a08b44fb7b
commit de0bf888fe
3 changed files with 8 additions and 1 deletions
+2 -1
View File
@@ -25,12 +25,13 @@ description: UniDesk Web 开发与浏览器验证技能。用户处理 UniDesk/H
- 文档/任务类页面优先就地阅读和就地编辑:标题和正文双击或显式编辑态切换,不为常规查看单独铺满输入框;正文渲染态必须可见,不能只显示 taskRef、文件名或更新时间。 - 文档/任务类页面优先就地阅读和就地编辑:标题和正文双击或显式编辑态切换,不为常规查看单独铺满输入框;正文渲染态必须可见,不能只显示 taskRef、文件名或更新时间。
- 报告、Markdown、日志和 JSON 片段要用成熟 Markdown/代码块渲染,代码块采用浅色 Workbench 风格、可滚动且不撑破布局;不要把裸 JSON 或长日志直接挤爆页面。 - 报告、Markdown、日志和 JSON 片段要用成熟 Markdown/代码块渲染,代码块采用浅色 Workbench 风格、可滚动且不撑破布局;不要把裸 JSON 或长日志直接挤爆页面。
- 页面状态要可深链:重要 source/file/task/report/session 选择进入 RESTful URL,并能刷新后恢复;联动其他功能只通过公共 API、稳定 id 和 URL,不把两个功能互相嵌入成强依赖。 - 页面状态要可深链:重要 source/file/task/report/session 选择进入 RESTful URL,并能刷新后恢复;联动其他功能只通过公共 API、稳定 id 和 URL,不把两个功能互相嵌入成强依赖。
- 设计验收必须用截图或 web-probe 样本检查真实版面:正文是否可见、主区域是否足够、弹窗是否遮挡流程、长文本是否溢出、移动/窄屏是否仍可操作。项目/MDTODO/报告类页面至少覆盖紧凑桌面视口(例如 960x600)的深链默认态、左侧树折叠态、右侧报告关闭态;记录 document overflow、pane 宽高、正文/报告可见性、按钮是否被遮挡,以及截图 SHA。 - 设计验收必须用截图或 web-probe 样本检查真实版面:正文是否可见、主区域是否足够、弹窗是否遮挡流程、长文本是否溢出、移动/窄屏是否仍可操作。项目/MDTODO/报告类页面至少覆盖紧凑桌面视口(例如 960x600)的深链默认态、左侧树折叠态、右侧报告关闭态;涉及报告渲染或布局重写时还必须覆盖右侧报告栏和报告全屏态。记录 document overflow、pane 宽高、正文/报告可见性、按钮是否被遮挡,以及截图 SHA。
## web-probe 证据规则 ## web-probe 证据规则
- 交互式线上验收优先使用 `web-probe observe start``observe command``observe collect``observe analyze``web-probe script` 只作为一次性探测逃生口。重复出现的高频动作(折叠侧栏、关闭报告、切换全屏、导出低码率截图、采集布局指标)必须沉淀为 observe command 或 analyzer 能力。 - 交互式线上验收优先使用 `web-probe observe start``observe command``observe collect``observe analyze``web-probe script` 只作为一次性探测逃生口。重复出现的高频动作(折叠侧栏、关闭报告、切换全屏、导出低码率截图、采集布局指标)必须沉淀为 observe command 或 analyzer 能力。
- Issue closeout 引用 observer id、command id、stateDir/report SHA、screenshot SHA 和关键字段摘要;不要粘贴截图二进制、完整 JSON、Secret、cookie 或无界日志。 - Issue closeout 引用 observer id、command id、stateDir/report SHA、screenshot SHA 和关键字段摘要;不要粘贴截图二进制、完整 JSON、Secret、cookie 或无界日志。
- Project Management/MDTODO closeout 必须区分 `control` 页和被动 `observer` 页:显式 `observe command` 的 command result、control URL 和对应截图是用户动作证据;observer 周期刷新或 stop 后根路由空态只能作为对照信号,不能覆盖 command result。涉及报告的验收要同时记录 `reportPreviewVisible``reportFullscreenVisible`、报告 deep link 和截图 SHA。
- `observe analyze` 的 archive/history findings 可能包含旧样本或旧规则误判;关闭用户入口问题前同时核对最新 sample 字段、DOM 几何和截图。若 top-level findings、latest sample 和 archive red 冲突,说明冲突并补工具反馈 issue,不要只凭 archive red 或单张截图下结论。 - `observe analyze` 的 archive/history findings 可能包含旧样本或旧规则误判;关闭用户入口问题前同时核对最新 sample 字段、DOM 几何和截图。若 top-level findings、latest sample 和 archive red 冲突,说明冲突并补工具反馈 issue,不要只凭 archive red 或单张截图下结论。
## 高频工作流 ## 高频工作流
@@ -139,6 +139,10 @@ bun scripts/cli.ts web-probe observe collect webobs-xxxx --view project-mdtodo-s
bun scripts/cli.ts web-probe observe analyze webobs-xxxx bun scripts/cli.ts web-probe observe analyze webobs-xxxx
``` ```
MDTODO 或 Project Management 的 Web 重写/布局 closeout 不能只引用组件 diff、PipelineRun 成功或一张默认截图。最小证据应按 SPEC 覆盖:默认深链任务正文可见、Source/File 下拉显示 direct MDTODO 文件名、Rxx 任务树为 outline 辅助视图、右侧报告栏可打开且不挤爆主工作区、报告全屏可读并可关闭。涉及报告渲染时,先用有 `reportLinkCount > 0` 的任务执行 `openMdtodoReportPreview`,再执行 `toggleMdtodoReportFullscreen`,并在 closeout 中记录 command id、`reportPreviewVisible``reportFullscreenVisible`、报告 deep link、截图 SHA 和 analyze report SHA。
`observe` 的 Project Management 采样可能同时包含 control 页和 observer 页。control 页是显式用户动作所在页面;observer 页用于被动对照和周期刷新。若 `project-mdtodo-summary``observe analyze` 的最新汇总被 observer 周期刷新、stop 命令或根路由样本带成 `SRC=0/FILES=0/TASKS=0`,不得直接推翻已完成 command result 和 control 页面截图;必须按 `pageRole`、command JSON、control URL、screenshot path/SHA 和相邻 samples 解释。反过来,若 control command 失败、command backlog 未清空或截图 URL 不在目标 source/file/task/report 深链上,也不能用 observer 的健康样本替代用户入口证据。
`observe command --type newSession` 是显式用户/control action:它通过当前 Workbench UI 点击 `#session-create` 创建新 session,等待 active session id 改变和 composer ready,并把前后 snapshot 写入 control log。它只能用于采样开始时建立目标 session,或作为用户明确的新建会话动作;不得在 route/session mismatch 后当作 repair 手段。 `observe command --type newSession` 是显式用户/control action:它通过当前 Workbench UI 点击 `#session-create` 创建新 session,等待 active session id 改变和 composer ready,并把前后 snapshot 写入 control log。它只能用于采样开始时建立目标 session,或作为用户明确的新建会话动作;不得在 route/session mismatch 后当作 repair 手段。
约束: 约束:
+2
View File
@@ -95,6 +95,8 @@ AgentRun terminal `failed`、`blocked` 或 `canceled` 也是最终结果,不
Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../../project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md) 为权威;具体 Web 开发、fake-server Playwright、fixture 采集脱敏、移动端断言、截图 artifact 和线上 web-probe 闭环统一见 `$unidesk-webdev`。HWLAB repo 只保留入口边界:专项代码位于 `web/hwlab-cloud-web`,命令必须在 issue/CLI 选中的目标 node/lane workspace 或独立 worktree 上运行,不得在 master server 本地跑浏览器或仓库级前端 check。 Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../../project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md) 为权威;具体 Web 开发、fake-server Playwright、fixture 采集脱敏、移动端断言、截图 artifact 和线上 web-probe 闭环统一见 `$unidesk-webdev`。HWLAB repo 只保留入口边界:专项代码位于 `web/hwlab-cloud-web`,命令必须在 issue/CLI 选中的目标 node/lane workspace 或独立 worktree 上运行,不得在 master server 本地跑浏览器或仓库级前端 check。
MDTODO/Project Management Web 的重写或布局类 issue 以 UniDesk OA 对应 SPEC 为权威;关闭时必须用选中 node/lane 的 public origin 和 `$unidesk-webdev``observe command` 证据证明默认任务正文、Rxx 树、Source/File 选择、报告侧栏和报告全屏状态。`observe` 同时采集 control/observer 页面时,显式 command result、control URL 和截图是用户动作证据;被动 observer 周期刷新或 stop 后根路由空态只能作为对照,不能覆盖用户入口截图和 command JSON。
Workbench session lifecycle、空 session 后台回收、archived/deleted deep link 和 GET 纯读投影的判定口径统一见 `$unidesk-webdev`。指挥侧关闭这类 issue 时只记录选中 node/lane、受控配置来源、后台 mutation/GC 证据、list/detail/messages/deep link 摘要和截图 SHATTL、interval、batch 等可调数值以选中 lane 的受控配置为准,不在本参考维护第二份数值真相。 Workbench session lifecycle、空 session 后台回收、archived/deleted deep link 和 GET 纯读投影的判定口径统一见 `$unidesk-webdev`。指挥侧关闭这类 issue 时只记录选中 node/lane、受控配置来源、后台 mutation/GC 证据、list/detail/messages/deep link 摘要和截图 SHATTL、interval、batch 等可调数值以选中 lane 的受控配置为准,不在本参考维护第二份数值真相。
### Web Live DOM Probe 验收 ### Web Live DOM Probe 验收