docs: record v02 CLI runtime endpoint friction
This commit is contained in:
Codex
@@ -124,6 +124,12 @@ devops-infra git mirror 仍是 PipelineRun 和 Argo CD 的集群内读写源。`
|
||||
8. UniDesk CLI 或 mirror/relay flush 操作把本地 `v0.2-gitops` 推送到 GitHub canonical remote；flush 不在 CI runtime-ready 的关键路径内，但必须可查询 pending、lastFlushed 和 failure。
|
||||
9. 验收只观察 `hwlab-v02` runtime 和 `19666/19667`。
|
||||
|
||||
`trigger-current --lane v02 --confirm` 默认返回异步 job，不等同于 PipelineRun 已经创建完成。调用方必须先运行返回的 `job status <jobId>`，等 `progress.stage=create-pipelinerun` 且 `progress.pipelineCreated=true` 后，再用 `control-plane status --lane v02 --pipeline-run <name>` 做定点发布观察。`progress.pipelineRun` 可以在 control-plane refresh 或 mirror pre-sync 阶段提前给出预期名称；此时如果重型 status 报 `target-pipelinerun-not-found-or-unreadable`，只能说明 PipelineRun 尚未创建，不能作为发布失败、mirror 失败或 runtime 回归结论。
|
||||
|
||||
定点发布观察优先使用 `--pipeline-run <name>` 或 `--source-commit <full-sha>`，避免 branch 后续推进导致历史 run 被最新 head 口径误判。`control-plane status` 会同时做 source/mirror/TaskRun/Argo/runtime/web asset 汇总，可能比普通只读查询慢；高频轮询时先看异步 job progress 和 TaskRun 条件摘要，只在阶段收口或异常定位时再跑完整 status。
|
||||
|
||||
GitOps promotion 成功后，本地 mirror/relay 的 `v0.2-gitops` 可立即被 Argo 消费；GitHub 上游 flush 是归档与跨节点同步步骤，不在 runtime-ready 关键路径内。`git-mirror status.pendingFlush=true` 时应运行 `git-mirror flush --confirm`，再用该 flush job 的 `job status` 或 `git-mirror status` 确认 `pendingFlush=false`、`localGitops=githubGitops`。不要把 pending flush 误判为 runtime 未发布，也不要在 flush job 仍运行时反复做全量 status。
|
||||
|
||||
`v0.2` 可以复用 G14 的 registry、proxy、BuildKit、工具镜像和脚本库；不得复用 `hwlab-g14-ci-image-publish`、`hwlab-g14-branch-poller`、`hwlab-g14-control-plane-reconciler`、`G14-gitops` runtime path 或 DEV/PROD Argo Application 作为 `v0.2` 发布入口。运行时不得为每个版本硬编码 namespace、catalog、runtime path 或健康判断；版本差异只通过 `deploy.json.lanes[profile]`、GitOps render 输入和实际 runtime 对象表达，新增版本不得新增运行时代码分支。
|
||||
|
||||
`v0.2` 不设自动轮询发布。历史上若存在 `hwlab-v02-branch-poller`、`hwlab-v02-control-plane-reconciler` 或等价 CronJob，均视为迁移残留，应由 UniDesk control-plane apply 清理；后续发布、重跑、暂停和恢复都通过手动 CLI 触发或停止创建新的 PipelineRun 完成，不新增替代 CronJob。
|
||||
|
||||
@@ -6,13 +6,15 @@
|
||||
|
||||
标准调用入口是直接使用 Bun 运行 TypeScript 入口：`bun tools/hwlab-cli/bin/hwlab-cli.ts client ...`。不要把 `node scripts/run-bun.mjs ...` 作为 v0.2 手动验收入口；该 wrapper 只保留历史兼容价值，曾经在远端交互中输出 wrapper usage 并遮蔽真实 CLI 行为。长期文档、issue 复现步骤和手动验收命令都应使用直接 Bun 入口。
|
||||
|
||||
正式复现和验收必须通过运行时装配解析 endpoint，而不是在命令里手动传 URL。标准环境是 `HWLAB_RUNTIME_NAMESPACE=hwlab-v02`、`HWLAB_RUNTIME_LANE=v02`、`HWLAB_RUNTIME_ENDPOINT_LOCKED=1` 和 `HWLAB_CODE_AGENT_ASSEMBLED_RUNTIME=1`；CLI 输出必须包含 `runtimeEndpoint.source=runtime-namespace`、`runtimeEndpoint.explicitOverride=false` 和解析出的 `baseUrl`。`--base-url`、`--api-base-url`、`HWLAB_CLIENT_BASE_URL` 或等价显式 URL 只允许在本地 debug 且未设置 endpoint locked 时使用；issue 复现、最终验收、Web 等价 CLI、AgentRun runner、device-pod-cli 和 `hwpod` 都不得靠人工判断 17666/19666/19667。
|
||||
|
||||
## 在系统中的职责划分
|
||||
|
||||
- 提供 WEB 等价的非视觉业务入口：登录鉴权、session 恢复、Device Pod 看板、Code Agent 对话、trace/result 轮询、logout 和工作台 live summary。
|
||||
- 只走 Cloud Web 同源 API surface；默认 base URL 是 `http://74.48.78.17:19666`，也可通过 `--base-url` 或 `HWLAB_CLIENT_BASE_URL` 指向其他 Cloud Web 入口。
|
||||
- Web/CLI 路径一致性优先于继续 Web 修复。Cloud Web 暴露 Code Agent、AgentRun、continuation、steer、trace/result 或 provider 问题后，必须先能用 `bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send/result/trace/inspect/steer --base-url http://74.48.78.17:19666 ...` 对同一 Cloud Web base URL、同一 `/v1/agent/chat*`、同一 `conversationId/sessionId/threadId/retryOf` 复现或解释，再继续修 Web 状态机。`19667` Cloud API 只用于显式 admin/setup/gateway 诊断，不得替代 WEB 同源路径验收。
|
||||
- 只走 Cloud Web 同源 API surface；正式运行时由 `HWLAB_RUNTIME_*` 装配出当前 lane 的 Web/API endpoint，失败时必须 fail closed，不能静默退回 legacy DEV 入口。
|
||||
- Web/CLI 路径一致性优先于继续 Web 修复。Cloud Web 暴露 Code Agent、AgentRun、continuation、steer、trace/result 或 provider 问题后，必须先能用 runtime namespace/lane 装配出的 `bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send/result/trace/inspect/steer ...` 对同一 Cloud Web origin、同一 `/v1/agent/chat*`、同一 `conversationId/sessionId/threadId/retryOf` 复现或解释，再继续修 Web 状态机。Cloud API 只用于显式 admin/setup/gateway 诊断，不得替代 WEB 同源路径验收。
|
||||
- 从 Web trace 回放 Code Agent 问题时，优先用 `client agent send --from-trace <traceId>` 读取 Cloud Web 的 `/v1/agent/chat/inspect`，自动带回原 `conversationId/sessionId/threadId` 并把 `retryOf` 指向来源 trace；只有 inspect 缺失时才手动传 `--conversation-id`、`--session-id`、`--thread-id` 和 `--retry-of`。CLI 输出必须包含 replay 来源、inspect 状态和 redacted continuation 摘要。
|
||||
- 默认业务子命令不直连 Postgres、Kubernetes Service、Secret、device-pod 内部 Service、gateway RPC 或本地 fixture；需要鉴权的请求使用 `/auth/*` 返回的 cookie 或显式 `--cookie`。唯一例外是 `client gateway` 诊断族：它允许显式 `--api-base-url` 指向 Cloud API，用于短连接观测 gateway session、单次 shell invoke 和 transport 压测；该入口只验证底层传输稳定性，不替代 Web 用户流程授权，也不发布镜像或常驻服务。
|
||||
- 默认业务子命令不直连 Postgres、Kubernetes Service、Secret、device-pod 内部 Service、gateway RPC 或本地 fixture；需要鉴权的请求使用 `/auth/*` 返回的 cookie 或显式 `--cookie`。唯一例外是 `client gateway` 诊断族：它使用同一 runtime endpoint resolver 定位 Cloud API，用于短连接观测 gateway session、单次 shell invoke 和 transport 压测；该入口只验证底层传输稳定性，不替代 Web 用户流程授权，也不发布镜像或常驻服务。显式 API URL 只作为 unlocked local debug 入口。
|
||||
- Pod 内透传执行不放进 `hwlab-cli`；需要进入正在工作的 Code Agent/Cloud API pod 时，`hwlab-cli` 只查询并输出 UniDesk 标准 route，实际透传由 UniDesk `bun scripts/cli.ts ssh 'G14:k3s:hwlab-v02:pod:<pod>:<container>' ...` 完成。`pod:` 是 route 语法，`/` 只用于 pod 内文件系统路径。
|
||||
- `client runtime routes` 必须按当前运行 profile/lane 的数据生成 UniDesk `pod:` route；实现不得硬编码 `dev`、`v0.2`、`v0.3`、namespace 或 catalog path。新增版本只允许通过 `deploy.json.lanes[profile]` 声明 namespace、artifact catalog 和 service overrides，不为每个版本新增代码分支。
|
||||
- 运行时不做内部证明型校验、旧健康诊断或重断言；CI/CD 只保留能证明代码可构建、语法正确和最小冒烟可用的校验。功能正确性通过 `hwlab-cli client` 短连接真实业务 E2E 暴露和修复。
|
||||
@@ -77,11 +79,11 @@
|
||||
|
||||
## T1
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 或当前 v0.2 worktree 用 cli 手动测试以下内容：运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client auth login --base-url http://74.48.78.17:19666 --username admin --password-env HWLAB_PASSWORD`，确认返回 JSON、HTTP 200、保存 cookie，输出不包含 password 或 Secret 原文。
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 或当前 v0.2 worktree 用 cli 手动测试以下内容：先设置 `HWLAB_RUNTIME_NAMESPACE=hwlab-v02 HWLAB_RUNTIME_LANE=v02 HWLAB_RUNTIME_ENDPOINT_LOCKED=1 HWLAB_CODE_AGENT_ASSEMBLED_RUNTIME=1`，再运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client auth login --username admin --password-env HWLAB_PASSWORD`，确认返回 JSON、HTTP 200、保存 cookie，输出不包含 password 或 Secret 原文，且 `runtimeEndpoint.source=runtime-namespace`、`runtimeEndpoint.explicitOverride=false`。
|
||||
|
||||
## T2
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：运行 `client auth session`、`client device-pods list`、`client device-pods status device-pod-71-freq` 和 `client workbench summary --pod-id device-pod-71-freq`，确认全部走 `19666` Cloud Web 同源 API，未登录时返回认证 blocker，登录后返回真实 Device Pod payload，不读取本地 fixture。
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：在 runtime endpoint locked 环境下运行 `client auth session`、`client device-pods list`、`client device-pods status device-pod-71-freq` 和 `client workbench summary --pod-id device-pod-71-freq`，确认全部由 runtime namespace 解析到 Cloud Web 同源 API，未登录时返回认证 blocker，登录后返回真实 Device Pod payload，不读取本地 fixture，也不需要手动传 URL。
|
||||
|
||||
## T3
|
||||
|
||||
@@ -97,7 +99,7 @@
|
||||
|
||||
## T3A
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：分别用 `--profile admin-a` 和 `--profile admin-a-second` 登录同一个账号，运行 `client workbench restore/status`，确认两个 profile 看到相同 `workspaceId` 和 revision；再用 `--profile other-user` 登录另一个账号，确认 workspace 不同；最后切回 `admin-a`，确认原 workspace、conversation/session/thread 仍能恢复。该验收必须使用真实 `http://74.48.78.17:19666`，不能 mock。
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：在 runtime endpoint locked 环境下分别用 `--profile admin-a` 和 `--profile admin-a-second` 登录同一个账号，运行 `client workbench restore/status`，确认两个 profile 看到相同 `workspaceId` 和 revision；再用 `--profile other-user` 登录另一个账号，确认 workspace 不同；最后切回 `admin-a`，确认原 workspace、conversation/session/thread 仍能恢复。该验收必须使用真实 runtime namespace/lane 自动解析入口，不能 mock，不能手动传 URL。
|
||||
|
||||
## T3.2
|
||||
|
||||
@@ -105,7 +107,7 @@
|
||||
|
||||
## T3.3
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：先运行 `client agent send --message "执行一个会持续运行的任务，等待后续 steer" --provider-profile deepseek` 获得运行中 trace，再运行 `client agent steer <traceId> --message "请把最终回复包含 STEER_ACCEPTED 标记"`，最后用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 确认同一 target trace 出现 AgentRun steer command 事件且最终回复或 trace 可见 steer 处理结果。该验收必须使用真实 `http://74.48.78.17:19666` 或 runtime namespace 自动解析出的同源 Web 入口，不能 mock，也不能用自动交互脚本。
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：在 runtime endpoint locked 环境下先运行 `client agent send --message "执行一个会持续运行的任务，等待后续 steer" --provider-profile deepseek` 获得运行中 trace，再运行 `client agent steer <traceId> --message "请把最终回复包含 STEER_ACCEPTED 标记"`，最后用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 确认同一 target trace 出现 AgentRun steer command 事件且最终回复或 trace 可见 steer 处理结果。该验收必须使用 runtime namespace/lane 自动解析出的同源 Web 入口，不能 mock，也不能用自动交互脚本，不能手动传 URL。
|
||||
|
||||
## T3.4
|
||||
|
||||
@@ -121,11 +123,11 @@
|
||||
|
||||
## T6
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：运行 `hwpod job output --pod-id D601-F103-V2 <jobId> --api-base-url http://74.48.78.17:19667`，确认默认输出包含 `body.compacted=true`、状态、job 摘要和 bounded text，且不包含嵌套 `dispatch.command`；再加 `--full` 确认完整 payload 可按需展开。通过 `client harness submit` 让 Code Agent 执行同一 `hwpod job output`，确认 trace 中 commandExecution 可以完成，不需要 `| head`。
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容：在 runtime endpoint locked 环境下运行 `hwpod job output --pod-id D601-F103-V2 <jobId>`，确认 `device-pod-cli` 自动定位当前 lane 的 Cloud API，默认输出包含 `body.compacted=true`、状态、job 摘要和 bounded text，且不包含嵌套 `dispatch.command`；再加 `--full` 确认完整 payload 可按需展开。通过 `client harness submit` 让 Code Agent 执行同一 `hwpod job output`，确认 trace 中 commandExecution 可以完成，不需要 `| head`，也不需要手动传 URL。
|
||||
|
||||
## T7
|
||||
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 或当前 v0.2 worktree 用 cli 手动测试以下内容：运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client gateway pressure --api-base-url http://74.48.78.17:19667 --gateway-session-id gws_D601_F103 --large-bytes 131072 --parallel 8 --request-timeout-ms 60000 --timeout-scenario-ms 1000 --no-auth --full`。确认 small stdout、大 stdout、长单行 stdout、stderr flood、timeout 和并发超容量全部返回结构化 JSON；大输出应显示 `stdoutBytes` 或 `stderrBytes`、`stdoutTruncated` 或 `stderrTruncated`、sha256 和 preview，超出 `maxInflightRequests` 的请求必须显示 `structured_gateway_busy`，不能出现无输出或卡死。
|
||||
阅读 docs/reference/spec-v02-hwlab-cli.md，然后在 `G14:/root/hwlab-v02` 或当前 v0.2 worktree 用 cli 手动测试以下内容：在 runtime endpoint locked 环境下运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client gateway pressure --gateway-session-id gws_D601_F103 --large-bytes 131072 --parallel 8 --request-timeout-ms 60000 --timeout-scenario-ms 1000 --no-auth --full`。确认 gateway CLI 自动定位当前 lane 的 Cloud API；small stdout、大 stdout、长单行 stdout、stderr flood、timeout 和并发超容量全部返回结构化 JSON；大输出应显示 `stdoutBytes` 或 `stderrBytes`、`stdoutTruncated` 或 `stderrTruncated`、sha256 和 preview，超出 `maxInflightRequests` 的请求必须显示 `structured_gateway_busy`，不能出现无输出或卡死。
|
||||
|
||||
## 规格的实现情况
|
||||
|
||||
|
||||
Reference in New Issue
Block a user