diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9f541e73..b61b1a5b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -22,7 +22,7 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 runtime lane 滚动 G14/D601 v03 的 bootstrap admin password 是 HWLAB runtime Secret 生命周期的一部分，必须收敛到 `config/hwlab-node-lanes.yaml` 的 `bootstrapAdmin` 声明与受控 `hwlab nodes secret status|ensure --node --lane v03 --name hwlab-v03-bootstrap-admin` CLI。明文只能存在于 Git 忽略、owner-only 的 `.state/secrets/...` sourceRef 文件；CLI 在本地把明文转换为 HWLAB 兼容 password hash，只向运行面同步 `password-hash`，并在输出中只披露 sourceRef、sourceKey、target Secret/key、presence、byte count、fingerprint、mutation 与后续命令。`secret ensure --force` 只用于明确需要按 YAML sourceRef 重灌 bootstrap admin hash 并重启 Cloud API 的受控恢复场景，默认 ensure 不做强制重灌；不要把人工生成 hash、手工写 k8s Secret 或原生 `kubectl rollout` 沉淀为长期入口。 -`hwlab nodes web-probe run --node --lane [--url ]` 是 HWLAB Cloud Web DOM probe 的受控指挥入口。它从 `config/hwlab-node-lanes.yaml` 解析目标 workspace、public URL 和 bootstrap admin sourceRef，在 UniDesk 指挥侧读取 owner-only 明文后只通过一次性 stdin/env 注入目标 workspace 的 `scripts/web-live-dom-probe.mjs`；stdout 只披露 sourceRef、sourceKey、presence、fingerprint、注入方式、DOM 摘要和 artifact hash，不打印密码。缺少 sourceRef 或 source 文件时应结构化返回 `web_login_secret_missing`，不能回退历史默认密码或要求把 secret 复制到 D601/G14 目标 host。需要自定义 Playwright route/intercept、in-flight DOM 读取或专用截图时，使用 `hwlab nodes web-probe script --node --lane <<'JS' ... JS`，由 CLI 负责同一 sourceRef 凭据解析、`/auth/login` 建立 `hwlab_session`、已认证 `browser/context/page/baseUrl` 注入和 artifact path/hash 摘要；自定义脚本不得自行读取或打印 Web 登录凭据。`web-probe script` 托管登录先对同源 `/auth/login` 做短重试；仍未拿到 `hwlab_session` 时自动回到当前 Cloud Web 登录表单，以浏览器方式提交同一凭据。`probe.auth` 只输出 method、origin、loginPath、status、attempts、retryCount、fallbackUsed、fallback、retryable、transientObserved、fingerprint、commanderAction 和 redacted errorSummary，不打印密码、cookie 或可复制 session 值。 +`hwlab nodes web-probe run --node --lane [--url ]` 是 HWLAB Cloud Web DOM probe 的受控指挥入口。它从 `config/hwlab-node-lanes.yaml` 解析目标 workspace、public URL 和 bootstrap admin sourceRef，在 UniDesk 指挥侧读取 owner-only 明文后只通过一次性 stdin/env 注入目标 workspace 的 `scripts/web-live-dom-probe.mjs`；stdout 只披露 sourceRef、sourceKey、presence、fingerprint、注入方式、DOM 摘要和 artifact hash，不打印密码。缺少 sourceRef 或 source 文件时应结构化返回 `web_login_secret_missing`，不能回退历史默认密码或要求把 secret 复制到 D601/G14 目标 host。Code Agent Trace 实时性验收使用 `--trace-sample-count ` 和 `--trace-sample-interval-ms ` 透传到目标 helper，输出每次采样的 agent status、trace presence/status、row count、empty label 和最新 row preview，用于证明运行中渐进拉取；这类采样不能由终态截图替代。需要自定义 Playwright route/intercept、in-flight DOM 读取或专用截图时，使用 `hwlab nodes web-probe script --node --lane <<'JS' ... JS`，由 CLI 负责同一 sourceRef 凭据解析、`/auth/login` 建立 `hwlab_session`、已认证 `browser/context/page/baseUrl` 注入和 artifact path/hash 摘要；自定义脚本不得自行读取或打印 Web 登录凭据。`web-probe script` 托管登录先对同源 `/auth/login` 做短重试；仍未拿到 `hwlab_session` 时自动回到当前 Cloud Web 登录表单，以浏览器方式提交同一凭据。`probe.auth` 只输出 method、origin、loginPath、status、attempts、retryCount、fallbackUsed、fallback、retryable、transientObserved、fingerprint、commanderAction 和 redacted errorSummary，不打印密码、cookie 或可复制 session 值。 `web-probe script` 的默认 `goto('/workbench')` 是稳定导航边界：它会先复用当前 page，失败后有限次切 fresh page 重试，并等待 workbench 基础 DOM（默认 `#workspace` 和 `#command-input`）可见；需要显式控制时使用注入的 `gotoStable(target, { selectors, activeSelector, attempts, readinessTimeoutMs })`、`waitForReady({ selectors })`、`gotoRaw()` 和 `getPage()`。稳定化失败必须在 `probe.readiness` 中低噪声披露 attempt、阶段、selector、是否观察到 `/v1` API request、API failure 摘要和失败截图 artifact；分类值固定为 `browser-load-jitter`、`selector-timeout`、`api-not-sent`、`api-response-failed`，避免把“页面没准备好/请求未发出”和“后端响应失败”混成同一种 selector timeout。runner 不在用户脚本执行前抢先导航同一 page，保证脚本仍可先安装 `page.route` 或 context route；如重试切换 fresh page，后续脚本应通过 `gotoStable()` 返回值或 `getPage()` 取得当前 page。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 4cd4f884..3118cc77 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -66,6 +66,8 @@ HWLAB node/lane 测试账号、bootstrap admin API key 观测、普通测试用 Code Agent trace 的长期 API 和 Web 行为规格以 UniDesk OA 为权威：API 资源形态见 [PJ2026-010403 API契约](../../project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md) 的 `GET /v1/agent/traces/{traceId}`，Web 自动补齐和分片显示见 [PJ2026-010401 Web工作台](../../project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md) 的 Trace阅读要求。UniDesk 指挥侧只记录验证入口和误判边界，不在本参考重新定义 trace endpoint、分页字段、游标语义或自动折叠策略。 +实时 Trace 展示必须把 turn 状态和 trace event 分页视为两条独立读路径。`/v1/agent/turns/:traceId` 只回答 running/terminal/final/error 等 turn 状态；`/v1/agent/traces/:traceId` 只负责按下游读 cursor 拉取已经持久化的 trace events。Web 在运行中不能等 turn terminal 后才 hydrate trace，也不能让 compact turn snapshot 覆盖已经拉到的 trace rows。后端刷新 AgentRun 上游失败时，trace API 仍应返回本地 trace store 中已有的分页快照，并把 refresh failure 作为诊断字段暴露；已有事件不得被硬 502 遮住。关闭“运行中 Trace 加载不出”类 issue 时，应证明 running 期间 trace API 与 Web DOM 都能看到已写入事件，而不是只展示最终完成后的 timeline。 + 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 代替。 @@ -84,6 +86,8 @@ Web 登录凭据必须从目标 node/lane 的受控 source 解析并作为一次 排查 probe 登录误报时，优先看 JSON 里的 `actions`、`dom.authState`、`finalUrl`、`failureDom` 和 `dom.requiredSelectors`。新版登录页 fallback 必须先等待真实登录 surface（`#workspace`、legacy id 或 `.login-card input`）再判断 input count；提交前还要确认表单值已经落到 DOM，例如 `actions.login.valuesReady=true`。只在 `authState=login` 的瞬间立即 `count()`，或在 Vue 尚未更新 input value 时 submit，都可能把前端填表时序误判成凭据错误。关闭 Workbench 登录/DOM helper 问题时，证据至少包含原命令、目标 URL/lane、登录 `selectorMode`、`valuesReady`、`finalUrl` 和 `workspace`/`commandInput` 等关键 selector 结果。 +Trace 实时性问题必须使用间隔采样，而不是只看静态截图或终态 DOM。`hwlab nodes web-probe run` 可用 `--trace-sample-count` 和 `--trace-sample-interval-ms` 采集运行中样本；自定义场景使用 `hwlab nodes web-probe script` 在同一 public origin 上读取 `.message-card[data-role="agent"]`、`.trace-timeline`、`.trace-render-row`、`data-status` 和 `.trace-empty`。采样判断要区分“加载中”和“思考中”：加载中表示页面仍在拉取已有 trace 或 trace 资源未就绪；思考中表示 trace 容器已挂载、turn 正在运行，但还没有第一条可读 Code Agent 事件。通过证据应包含连续样本里的 `agentStatus`、`tracePresent`、`traceStatus`、`rowCount`、`emptyLabel` 和最后一行预览；至少要看到 running 期间 trace 容器存在，并在上游写入后逐步出现 rows。 + 浏览器控制台中的随机文件名脚本、扩展注入脚本或浏览器实验功能警告不得直接归因到 HWLAB Cloud Web。遇到 `Permissions policy violation`、`unload is not allowed` 或类似 console 噪声时，先用 `hwlab nodes web-probe script` 在干净 Playwright 上记录 `document.scripts`、同源响应 header 和相关 console 过滤结果；只有脚本实际来自 HWLAB public origin、部署产物或响应 header 明确由 HWLAB 设置时，才把它登记为 HWLAB Web bug。Edge/Copilot、浏览器扩展或用户侧注入脚本产生的随机 bundle 名称，应作为浏览器环境噪声记录，不阻塞已通过的 Web 功能验收。 ### Cloud Web Workbench Prompt 浏览器闭环