docs: require web-equivalent hwlab agent validation

2026-06-02 10:52:34 +00:00
parent 960886b9cd
commit 0386faa3f0
3 changed files with 6 additions and 0 deletions
@@ -197,6 +197,8 @@ CLI 会在 Host route、workspace route、k3s 控制面脚本和 pod route 的 s

 HWLAB `hwlab-cli client agent` 端到端验证经 UniDesk `tran`/`ssh` 进入 G14 时，也按短连接 submit-and-poll 执行：在目标 workspace 和锁定 runtime env 下先 `agent send` 提交 turn，避免在可能超过 60 秒的路径上使用 `--wait` 长挂；随后多次短查询 `agent result <traceId>`、`agent trace <traceId> --render web` 或 `agent inspect --trace-id <traceId>` 取证。关闭 context-loss、AgentRun 复用或多轮会话类 issue 时，证据至少应记录 `conversationId`、`sessionId`、`threadId`、`traceId`、`runId`、`commandId` 和关键 event label。需要验证“第二轮继承第一轮上下文”时，显式传入同一 conversation/session/thread 标识，不能依赖旧 Cloud Web workspace 历史或人工印象；`--no-workspace` 这类绕过恢复的实验只可作为定位证据，不能替代默认入口验收。

+HWLAB Cloud Web Workbench 或 Code Agent 装配类 issue 的 CLI 验证必须贴近 Web 路径：优先使用会调用同一 Cloud API/Web dispatcher 的正式 `hwlab-cli client agent` 或等价 UniDesk 高层 CLI，再从 trace/inspect/result 中确认 runner job 的 `toolCredentials`、`toolAliases`、`transientEnv`、`runId` 和 `commandId`。直接调用 AgentRun manager、手写 `dispatchHwlabAgentRun()` 或临时 runner job 只可作为基础设施 canary；它不能替代 Web Workbench 原入口验收，也不能作为关闭 Web issue 的唯一证据。若缺少这种同路径 CLI，先补 CLI 可见性和 submit-and-poll 入口，再继续修复或关闭 issue。
+
 `bun scripts/cli.ts ssh D518` 应表现为登录 D518 WSL 的 shell；`bun scripts/cli.ts ssh D518 hostname` 应像 `ssh D518 hostname` 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，`-p`、`-i`、`-l`、`-o` 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。指挥官、CI 预检和其他非交互流程不要依赖 ssh-like 自由拼接；单进程标准写法是 `bun scripts/cli.ts ssh D601 argv true`，多行 shell 逻辑标准写法是 quoted heredoc 单步调用 `bun scripts/cli.ts ssh D601 script <<'SCRIPT'`。

 UniDesk CLI/tran 客户端改进本身是 master server 高频控制入口维护，可以直接在 `/root/unidesk` 轻量开发、提交并推送 `origin/master`；不要为这类客户端小改强制迁移到 D601 worktree。该例外不改变 master server 禁重型验证规则：仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译、Code Queue runner 实测仍必须在 D601、CI runner 或目标运行面执行。若 `tran`/SSH 文件传输遇到 provider-gateway 单次 stdin、argv 或 stdout 限制，先在 CLI 客户端做分块、SHA-256 校验、失败可观测输出和最小真实闭环；只有 client 侧不能解决且有证据时，才改 provider-gateway。`upload`/`download` 成功 JSON 中的 `verified=true`、`verification.automatic=true`、`verification.verified=true` 和 `verification.match.{bytes,sha256}=true` 就是端到端完整性证明，调用方不需要再额外手写 `sha256sum` 比对。