From dde2bc3ca6e349d340e8bee03be7cfa135dfba7a Mon Sep 17 00:00:00 2001 From: Lyon <88232613+pikasTech@users.noreply.github.com> Date: Tue, 23 Jun 2026 19:56:31 +0800 Subject: [PATCH] docs(web-probe): require trace timing integrity analysis (#748) Co-authored-by: Codex --- .agents/skills/unidesk-webdev/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index 3ee356e1..f9013c3e 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -101,7 +101,7 @@ bun scripts/cli.ts hwlab nodes web-probe observe analyze webobs-xxxx - `web-probe observe start` 默认是被动观测：记录 DOM 摘要、自然页面 request/response/requestfailed、截图和 performance 样本，不主动 fetch Workbench API、不切换 control session、不拦截路由、不调用 repair helper。长程 Workbench 观测必须保留 control/observer 双页面模型：control 页面执行显式 command，observer 页面只同步到同一 session URL 后被动采样，并按默认 180000ms 周期整页刷新同一 session 来模拟用户往返；周期刷新只作用于 observer，不得改变 control active session 或作为通过条件。两页的 `pageRole`、`pageId`、`sampleGroupSeq` 必须进入样本和 analyzer 报表。任何 `newSession`、`selectProvider`、`sendPrompt`、`goto`、`screenshot`、`mark`、`stop` 都必须通过 `observe command` 显式下发，并进入 `control.jsonl`；长 prompt 必须优先用 `sendPrompt --text-stdin`，不要为了绕开 shell quoting 退回裸 Playwright 或临时脚本。 - `web-probe observe` 的 issue evidence 优先记录 observer id、stateDir、report JSON/Markdown SHA、samples/control/network/artifact 计数、routeSessionId、activeSessionId、prompt hash/textBytes、traceId、AgentRun runId/commandId、最终 status 和必要摘要；不要把 prompt 原文、assistant 大段正文、完整 stdout/stderr 或 provider payload 粘贴到 issue。 - 多轮 Workbench 采样必须证明同一个 `sessionId` 连续承载所有轮次；每轮至少记录 prompt hash、traceId、终态、最终回答摘要和性能/产物表。若 Web UI 投影卡住但 Code Agent/AgentRun result 已 terminal，应同时登记“执行终态”和“Workbench 投影未收敛”，不得用 `goto`、reload、切 session 或 result polling 把 UI 失败伪装成通过。 -- `observe analyze` 是离线分析，只读取 artifact JSONL 并写 `analysis/report.md` 与 `analysis/report.json`，不访问 Workbench API、不驱动浏览器。`observe start` 每次启动必须先把同一 stateDir 中已有的根目录 JSONL 轮转到带时间戳的 `archive/` 文件；`observe analyze` 默认只分析当前根目录 JSONL，不扫描历史 archive，只有显式指定 archive prefix 时才分析历史轮转窗口。报告必须输出采样点 vs 每个 turn 的总耗时/最近更新时间表、可见“加载中”的数量/归属/并发 owner/连续出现区间、DOM diagnostic/HTTP/console/requestfailed/runtime execution error 分组、page asset provenance segment、同源 API Resource Timing 分位表和超过 YAML `webProbe.alertThresholds` budget 的慢路径 finding；页面/API 加载、可见“加载中”、长连接打开耗时、turn timing 跳变和 session fallback 标题比例的报警阈值只能改 YAML，不能在 analyzer/renderer 中写死。修复必须降低真实请求、投影、渲染或后端路径耗时，禁止为了减少“加载中”出现时间而提前展示未加载完的内容，也不能靠下游 retry/reload/fallback 掩盖。报告里的 `final-response-flicker`、`uncommanded-visible-state-change`、session changed、network 503 等 finding 是排障线索；用于 closeout 时必须结合原始 session/trace/DOM 证据解释，避免把采样噪声直接当作业务结论。 +- `observe analyze` 是离线分析，只读取 artifact JSONL 并写 `analysis/report.md` 与 `analysis/report.json`，不访问 Workbench API、不驱动浏览器。`observe start` 每次启动必须先把同一 stateDir 中已有的根目录 JSONL 轮转到带时间戳的 `archive/` 文件；`observe analyze` 默认只分析当前根目录 JSONL，不扫描历史 archive，只有显式指定 archive prefix 时才分析历史轮转窗口。报告必须输出采样点 vs 每个 turn 的总耗时/最近更新时间表、trace row 视觉顺序异常、terminal/轮次完成 row 是否最后、Code Agent 卡片耗时与 trace/轮次完成总耗时一致性、可见“加载中”的数量/归属/并发 owner/连续出现区间、DOM diagnostic/HTTP/console/requestfailed/runtime execution error 分组、page asset provenance segment、同源 API Resource Timing 分位表和超过 YAML `webProbe.alertThresholds` budget 的慢路径 finding；页面/API 加载、可见“加载中”、长连接打开耗时、turn timing 跳变、trace row 顺序、卡片耗时/轮次完成耗时一致性和 session fallback 标题比例的报警阈值只能改 YAML，不能在 analyzer/renderer 中写死。修复必须降低真实请求、投影、渲染或后端路径耗时，禁止为了减少“加载中”出现时间而提前展示未加载完的内容，也不能靠下游 retry/reload/fallback 掩盖。报告里的 `trace-row-order-nonmonotonic`、`trace-completion-row-not-last`、`round-completion-elapsed-mismatch`、`code-agent-card-duration-underreported`、`final-response-flicker`、`uncommanded-visible-state-change`、session changed、network 503 等 finding 是排障线索；用于 closeout 时必须结合原始 session/trace/DOM 证据解释，避免把采样噪声直接当作业务结论。 - 自定义 `web-probe script` 仍运行在 UniDesk `trans` 60s 最外层短连接约束内；能在一轮内完成的 P4 验收优先把 `--command-timeout-seconds` 控制在 55 秒以内，并减少无界 selector/network 等待。确需等待更久时，改用 `web-probe run` 的异步 job/status 语义，或把动作拆成“提交/采样/截图/状态读取”多次短 probe。若输出出现 `UNIDESK_SSH_RUNTIME_TIMEOUT` 但同时恢复了 `reportPath`、`reportSha256`、screenshots 或 DOM steps，先按远端报告判断脚本/页面实际状态；最终关闭证据仍优先用一次未触发短连接超时的 bounded rerun。 - issue closeout 优先引用 `web-probe script` 输出的顶层 `issueEvidence` 或 `summary.issueEvidence`；只有需要展开调查时才粘贴 `probe.script.result`、`probe.steps` 或完整 `reportPath`，避免 stdout、summary 和 report 多层重复同一证据。 - stdin heredoc 与 `--script-file` 都按 ES module 加载，脚本必须导出 `export default async ({ page, gotoStable, recordStep, ... }) => { ... }`；不要在模块顶层直接写 `return`。失败为 `Illegal return statement`、`does not provide an export named default` 或 finalUrl 仍是 `about:blank` 且 stepCount=0 时，先按 probe 脚本入口误用处理，不要归因成 Cloud Web 行为失败。