From 7be0f81378db26d03b7b126c6faeca87776752c6 Mon Sep 17 00:00:00 2001 From: lyon Date: Mon, 15 Jun 2026 00:39:49 +0800 Subject: [PATCH] docs: resolve HWLAB runtime by node lane --- AGENTS.md | 60 +++++++++---------- docs/reference/MVP-e2e-acceptance.md | 22 +++---- .../reference/agentrun-code-agent-dispatch.md | 8 +-- docs/reference/architecture.md | 16 ++--- docs/reference/cloud-workbench.md | 16 ++--- docs/reference/code-agent-chat-readiness.md | 37 +++++------- docs/reference/commander-collaboration.md | 27 +++++---- docs/reference/dev-runtime-boundary.md | 43 +++++++------ docs/reference/dev-runtime-hotfix-runbook.md | 12 ++-- docs/reference/documentation-governance.md | 2 +- docs/reference/gateway-outbound-demo.md | 6 +- docs/reference/m3-loop-rollout-runbook.md | 10 ++-- docs/reference/node-gitops-cicd.md | 54 ++++++++--------- docs/reference/spec-hwpod-harness.md | 8 +-- 14 files changed, 162 insertions(+), 159 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c406ddfd..90d1a6d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,13 +4,13 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 ## P0 CaseRun 无服务与单步调试规则 -- P0: v0.2 HWPOD CaseRun、case registry 产物整理、trace 语义化、harness 诊断、短连接 CLI 和 D601/G14 目标 host 上可直接运行的 runner 调试，默认是无服务工作流；只要不需要变更 cloud-api、web、gateway、GitOps、k3s runtime 或其他常驻服务，就必须直接无服务运行和验证，禁止为了运行 CaseRun 触发 CI/CD、rollout 或服务发布。 +- P0: HWPOD CaseRun、case registry 产物整理、trace 语义化、harness 诊断、短连接 CLI 和目标 node/lane host 上可直接运行的 runner 调试，默认是无服务工作流；目标 node 和 lane 以 issue、PR、CLI 参数或 `deploy/deploy.yaml` 的明确声明为准。只要不需要变更 cloud-api、web、gateway、GitOps、k3s runtime 或其他常驻服务，就必须直接无服务运行和验证，禁止为了运行 CaseRun 触发 CI/CD、rollout 或服务发布。 - P0: CaseRun 卡在 hwpod-node、workspace prepare、编译、下载、串口、artifact 收集或其他基础设施步骤时，必须先把卡点拆成同一目标运行面的单步命令验证；禁止用反复全量 CaseRun 大回环替代单步定位。 - P0: 只有单步卡点已经验证通过，且需要验证完整编排、trace 和 registry 产物时，才启动一次完整 CaseRun；完整 CaseRun 仍必须按 cli-spec 异步启动、短轮询状态、收集 trace，不得加入 evidence 自动评价、门禁或自动判断。 ## P0 文档/CLI 直接主 worktree 规则 -- P0: 单纯文档、AGENTS.md、docs/reference、SPEC、短连接 CLI、trans/tran/helper 这类轻量变更，禁止为了“隔离开发”新建 git worktree；必须在当前工作线固定主 worktree 直接修改、提交并 push 到对应 remote 分支，v0.2 默认 `/root/hwlab-v02` -> `origin/v0.2`。 +- P0: 单纯文档、AGENTS.md、docs/reference、SPEC、短连接 CLI、trans/tran/helper 这类轻量变更，禁止为了“隔离开发”新建 git worktree；必须在当前 issue/CLI 明确的 node + lane 固定主 worktree 直接修改、提交并 push 到对应 remote 分支。没有明确目标时才读取受控配置解析默认值，禁止把 G14、D601 legacy 或 v0.2 写成全局默认。 - P0: 只有业务代码、运行面、发布链路、CI/CD、Secret、权限、数据迁移、PROD 或明确高风险改动，才按项目规则创建隔离 worktree 或走 PR；不要把重型开发流程套到文档/CLI 轻量变更上。 - P0: 若固定主 worktree 因并行 dirty 文件无法快进，先保留并行变更，只提交当前文档/CLI相关文件；必要时使用非破坏性 rebase/autostash 或等价方式对齐 remote 后直接 push，禁止绕到新 worktree 掩盖主 worktree 状态。 @@ -24,18 +24,18 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - P0: HWLAB CLI 和 AgentRun/HWPOD runner 只允许从 `HWLAB_API_KEY` 读取用户 API key；不得新增或复活 `API_KEY`、`HWLAB_BEARER_TOKEN`、`--api-key`、`--bearer-token` 等别名入口。HTTP `Authorization: Bearer` 只是 CLI 从 `HWLAB_API_KEY` 生成的协议 header，不是第二个配置来源。 - P0: Web 只走 `hwlab_session` Web session；CLI 保护命令缺少 `HWLAB_API_KEY` 时必须返回 `api_key_required` 或 `unsupported_api_key_source`，不得回退 Web session、cookie、password login 或 Keycloak token。 -- P0: master server 和 G14 均已固化 v0.2 用户 API key，统一来源路径都是 `/root/.config/hwlab-v02/master-server-admin-api-key.env`；处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或 v0.2 验收前，必须先从当前执行 host 的该文件加载或确认 `HWLAB_API_KEY`，禁止先把问题定性为缺少 API key。 -- P0: master server 和 G14 的 `~/.bashrc` 会加载该固定文件，并通过 `BASH_ENV=$HOME/.bashenv` 让从交互 shell 派生的非交互 bash 也能读取 `HWLAB_API_KEY`；若当前进程没有继承环境，先显式 `source ~/.bashrc` 或确认该固定文件，不得改走别名、token、cookie 或临时 fallback。 -- P0: 查询 `HWLAB_API_KEY` 时只能输出 `present/missing`、source path 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。G14/HWLAB runtime 中环境变量缺失不代表 key 不存在，应先通过同一固定来源注入再继续排查。 +- P0: 处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或 runtime 验收前，必须先按当前 issue/CLI 明确的 node + lane 读取对应 API key sourceRef 或受控本地 env 文件；禁止先把问题定性为缺少 API key，也禁止把某个节点或 v0.2 的路径写成全局默认。 +- P0: 若当前进程没有继承 `HWLAB_API_KEY`，先确认目标 node/lane 的受控来源、`~/.bashrc` / `BASH_ENV` 注入和 CLI status 输出；不得改走别名、token、cookie、password login 或临时 fallback。 +- P0: 查询 `HWLAB_API_KEY` 时只能输出 `present/missing`、source path、sourceRef 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。目标 runtime 中环境变量缺失不代表 key 不存在，应先通过同一受控来源注入再继续排查。 -## P0 G14 原生 k8s/GitOps 运行面归一 +## P0 node/lane 运行面归一 -- G14 是当前 HWLAB DEV/PROD 原生 k8s 与 GitOps 运行面真相；`hwlab-dev` 与 `hwlab-prod` 均由 G14 k3s、Tekton、`G14-gitops` 和 Argo CD 管理，详见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 -- `v0.2` 是 G14 上的加法扩容线：固定分支 `v0.2`、固定开发 workspace `G14:/root/hwlab-v02`、固定 CI/CD source repo `G14:/root/hwlab-v02-cicd.git`、固定 namespace `hwlab-v02`、FRP 入口 `74.48.78.17:19666/19667`；创建和集成 `v0.2` 不得删除、重命名、复用或改义现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口。 +- HWLAB 当前开发、发布和验收目标必须先从 issue、PR、CLI 参数或受控 lane 配置解析 node + lane；例如 issue 明确 `目标节点：D601`、`目标分支：HWLAB v0.3` 时，D601 v0.3 就是当前运行面真相，不得回退到 G14、v0.2 或 D601 legacy。 +- 每个 lane 的 source branch、开发 workspace、CI/CD source repo、namespace、公网入口、Secret sourceRef 和 route 由 `deploy/deploy.yaml` 及 UniDesk `hwlab nodes ... --node --lane ` 控制面解析；长期文档只能记录解析规则和专项规格，不能把某个 node/lane 的数值写成全局默认。 - `v0.2` 的人写 deploy/runtime 配置单一出处是 `deploy/deploy.yaml`；`deploy/deploy.json` 不再是 v0.2 兼容源。所有脚本、renderer、planner 和 CLI 必须通过 `scripts/src/structured-config.mjs` / `scripts/src/deploy-config.mjs` 这类格式无关读写层消费配置，禁止把 YAML parser import 或 ad hoc YAML 解析散落到业务脚本里。 -- G14 GitOps render 若改变 Argo Application、AppProject、runtime path 或 DEV/PROD 拆分目录，必须同步应用 `deploy/gitops/node/argocd/project.yaml`、`application-dev.yaml` 和 `application-prod.yaml`；只推 `G14-gitops` 分支不等于 Argo 已切到新 path。 -- D601 HWLAB DEV、D601 `dev-cd-apply`、`ci-publish` 和旧 `main` JS 脚本式 CI/CD 已退出 G14 发布入口；G14 Tekton 只能通过 `scripts/artifact-publish.mjs` 作为集群内 build/push helper，再由 GitOps/Argo CD rollout，新开发、发布、验收、文档和运行面实验不得把 D601 或 legacy 脚本 CD 当作当前 HWLAB runtime source-of-truth。 -- G14 k3s 操作必须通过 UniDesk route `G14:k3s` 执行；不得用 D601 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为 G14 DEV/PROD 通过证据。 +- Node GitOps render 若改变 Argo Application、AppProject、runtime path 或 lane 拆分目录，必须同步应用对应 node/lane 的 GitOps 文件；只推 GitOps 分支不等于 Argo 已切到新 path。 +- D601 旧 DEV、`dev-cd-apply`、`ci-publish` 和旧 `main` JS 脚本式 CI/CD 只属于 legacy 路径；D601 的 node-scoped runtime lane（例如 D601 v0.3）不属于 legacy。新开发、发布、验收、文档和运行面实验不得把 legacy 脚本 CD 当作当前 HWLAB runtime source-of-truth。 +- k3s 操作必须通过当前目标 node 的 UniDesk route 执行，例如 `D601:k3s` 或 `G14:k3s`；不得用另一个节点的 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为当前 node/lane 的通过证据。 ## P0 HyueAPI Direct NO_PROXY 规则 @@ -49,8 +49,8 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 ## P0 Legacy CD 删除纪律 - 旧 D601 `ci-publish`、`dev-cd-apply`、`dev-deploy-apply` 和 `dev-artifact-publish` 脚本入口已经从当前发布面删除；不要恢复这些文件、CLI 子命令或文档入口。 -- 当前发布只走 G14 k3s Tekton + `G14-gitops` + Argo CD；镜像构建 helper 是 `scripts/artifact-publish.mjs`，desired state 由 `scripts/gitops-render.mjs` 生成，细则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 -- 发现旧脚本、旧文档或旧 `hwlab-cli cicd` 再次进入 G14 Pipeline、AGENTS 或长期参考时，优先删除旧入口并把调用方改到 G14 GitOps 路径，不再做兼容保留。 +- 当前发布只走受控 node/lane 的 Tekton/GitOps/Argo CD 控制面；镜像构建 helper 是 `scripts/artifact-publish.mjs`，desired state 由 `scripts/gitops-render.mjs` 或 node/lane 控制面生成，细则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 +- 发现旧脚本、旧文档或旧 `hwlab-cli cicd` 再次进入当前 node/lane Pipeline、AGENTS 或长期参考时，优先删除旧入口并把调用方改到受控 GitOps 路径，不再做兼容保留。 ## P0 门禁最小化纪律 @@ -65,25 +65,23 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 ## 工作区 -- G14 分支固定 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。在 G14 上进行代码、文档、GitOps render、Tekton/poller/Argo CD 修复或 CI/CD 验证前，必须先确认 `pwd` 为 `/root/hwlab` 且 `git status --short --branch` 为 `G14...origin/G14`；不满足时先停止并修正 workspace。 -- `v0.2` 固定开发 workspace 是 G14 节点上的 `/root/hwlab-v02`，固定使用 `v0.2` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。`/root/hwlab-v02` 只能作为 `v0.2` 人工开发、短连接源码工具和问题复现工作区，不得作为 `G14` scratch 区、DEV/PROD 热修目录或 CI/CD source commit 选择入口。 -- `v0.2` CI/CD source commit 只来自 G14 专用 bare repo `/root/hwlab-v02-cicd.git` 的自动 fetch 结果，并通过 `devops-infra` git mirror/relay 进入 Tekton、GitOps promotion 和 Argo；`/root/hwlab-v02` 的 dirty、stale 或 untracked `.worktree/` 状态只能作为 isolated warning，不得阻塞或改变 CI/CD。 -- G14 开发默认先以 `/root/hwlab` 做固定 repo 预检，再在 `/root/hwlab/.worktree/` 从最新 `origin/G14` 创建独立 worktree 修改和提交；固定 repo 不作为并行任务 scratch 区，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 -- G14 k3s 操作必须通过 UniDesk SSH route `G14:k3s` 执行，例如 `bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci`；禁止使用 `ssh G14 k3s ...`。不要把 `/workspace/hwlab`、`/root/HWLAB`、D601 workspace、master-server checkout 或临时 clone 当作 G14 分支 source truth。 +- 当前工作区必须由 issue、PR、CLI 或受控 lane 配置解析，预检内容至少包括 `pwd`、`git status --short --branch`、`git remote -v` 和目标 node/lane control-plane status；不满足目标时先停止并修正 workspace。 +- D601 v0.3 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `origin/v0.3`；当 issue 明确 D601 v0.3 时，这个 workspace 是当前 source truth，不是 legacy 对照面。 +- G14 v0.2、G14 DEV/PROD 或其他 lane 的固定 workspace 只在当前任务明确选择对应 node/lane 时使用；不得把它们写成所有 HWLAB 任务的默认入口，也不得用一个 lane 的 dirty、stale 或 untracked `.worktree/` 状态阻塞另一个 lane 的 CI/CD source commit 选择。 +- 业务代码、运行面或高风险变更按当前 node/lane 的固定 workspace 创建独立 worktree；固定 repo 不作为并行任务 scratch 区，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 +- k3s 操作必须通过目标 node 的 UniDesk SSH route 执行，例如 `D601:k3s` 或 `G14:k3s`；禁止使用 `ssh k3s ...`。不要把 `/workspace/hwlab`、`/root/HWLAB`、master-server checkout、另一个节点 workspace 或临时 clone 当作当前 node/lane source truth。 - Runner 和指挥常用工作区是 `/workspace/hwlab`；进入仓库先检查分支与工作树状态，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 -- G14 DEV/PROD CI/CD 由 `G14` source branch、G14 k3s Tekton 和 `G14-gitops` branch 驱动；`v0.2` CI/CD 由 UniDesk 手动 trigger、`/root/hwlab-v02-cicd.git`、`devops-infra` git mirror/relay、G14 k3s Tekton 和 `v0.2-gitops` 驱动；需要构建、Playwright、check、发布预检或运行面验证时放到 G14 k3s/runner/CI/CD，不在 master server 跑重型验证。 -- G14/v0.2 远端验证必须用短连接触发后台 job、PipelineRun 或脚本任务，再用短连接轮询 status/tail/exit code；不要用 UniDesk SSH/tran 长连接等待 check、layout、Playwright、Tekton/Argo 或发布动作完整结束，细则见 [docs/reference/spec-v02-cicd.md](docs/reference/spec-v02-cicd.md)。 -- D601 发布/构建 worktree 纪律只适用于 legacy 路径回溯，不再作为当前 HWLAB 发布默认入口；当前入口见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 -- 交付路径按变更风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前工作线的 source branch，G14 默认 `origin/G14`，`v0.2` 默认 `origin/v0.2`；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，PR base 必须匹配当前工作线，不能默认投向 `main`；默认不要合并自己的 PR，用户或指挥官明确授权且满足门禁时可按长期参考自合并，不要改 PROD、不要重启服务。 +- CI/CD 由当前 node/lane 的 source branch、CI/CD source repo、Tekton/GitOps branch 和 Argo Application 驱动；需要构建、Playwright、check、发布预检或运行面验证时放到目标 node/k3s/runner/CI/CD，不在 master server 跑重型验证。 +- 远端验证必须用短连接触发后台 job、PipelineRun、脚本任务或 `trans playwright`，再用短连接轮询 status/tail/exit code；不要用 UniDesk SSH/tran 长连接等待 check、layout、Playwright、Tekton/Argo 或发布动作完整结束。 +- D601 legacy 只指旧 DEV/CD 回放路径；D601 node-scoped runtime lane 由当前 issue/CLI 明确选择时是正式开发、发布和验收入口，当前入口见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 +- 交付路径按变更风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前工作线的 source branch；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，PR base 必须匹配当前 node/lane source branch，不能默认投向 `main`、G14 或 v0.2。默认不要合并自己的 PR，用户或指挥官明确授权且满足门禁时可按长期参考自合并，不要改 PROD、不要重启服务。 - `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78) 是当前 M3 虚拟硬件可信闭环的上位约束；其他任务不得把 SOURCE、LOCAL、DRY-RUN、fixture 或前端状态误报为 M3 DEV-LIVE。 - 仓库禁止创建或提交 repo report 目录；验收、进展和结论只承载在 #7、专题 issue、每日简报或 PR/issue 评论。临时 JSON 只能写入 `/tmp`、`.state` 或 CI artifact，不能进入源码仓库。 ## 固定入口 -- G14 DEV Cloud Web：`http://74.48.78.17:17666/`，规则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。 -- G14 DEV API/edge/live：`http://74.48.78.17:17667/health/live`，规则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。 -- G14 PROD 预留入口：`http://74.48.78.17:18666/` 与 `http://74.48.78.17:18667/health/live`，规则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 -- G14 `v0.2` 规划入口：`http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`，只能指向 `hwlab-v02` namespace，规则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 +- Runtime Web/API/live 入口必须从当前 issue/CLI 明确的 node + lane control-plane status 读取；没有明确目标时才从受控 lane 配置解析，不得把 G14、v0.2、DEV/PROD 或 D601 legacy 端口写成所有任务默认入口。 +- D601 v0.3、G14 v0.2 和其他 node/lane 的公网入口、namespace、route 与 GitOps 应分别由 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md) 和受控 CLI 输出确认。 - Cloud Workbench 默认首页与 UX 约束见 [docs/reference/cloud-workbench.md](docs/reference/cloud-workbench.md)。 ## 规格 @@ -140,7 +138,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - 中文优先：issue、PR 正文、长期参考文档和用户可见说明默认用中文；英文术语只在命令、协议、接口、ID、路径和标准名需要保真时保留，详见 [docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)。 - 用户反馈优先：用户和参谋提出的问题默认按高优先级用户反馈处理，blocker 状态不能替代反馈分流，必须挂到 [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7) 醒目位置，详见 [docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md)。 - docs-spec 本地权威优先：涉及 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，先按 [docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) 执行，不另建同级规则副本。 -- 交付路径按风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前工作线的 source branch，G14 默认 `origin/G14`，`v0.2` 默认 `origin/v0.2`；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 +- 交付路径按风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前 node/lane 的 source branch；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。 ## 常用轻量命令 @@ -155,16 +153,16 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 - GitOps lane 严格 TS 检查：`npm run gitops:ts:check`；新拆 GitOps 模块直接进入 `scripts/src/*.ts` 和 `tsconfig.gitops.json`，不要继续堆进单个 `.mjs`。 - DEV 依赖 runtime base 构建：`npm run dev-runtime-base:build` - Legacy D601 DEV CD：旧脚本入口已删除；事故回放只读历史 issue/commit，不恢复旧命令。 -- v0.2 WEB 等价短连接 CLI：在 `G14:/root/hwlab-v02` 或当前 v0.2 worktree 直接运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client ... --base-url http://74.48.78.17:19666`，默认走 Cloud Web 同源 API；细则见 [docs/reference/spec-v02-hwlab-cli.md](docs/reference/spec-v02-hwlab-cli.md)。 +- WEB 等价短连接 CLI：在当前 node/lane 固定 workspace 直接运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client ... --base-url `，默认走 Cloud Web 同源 API；v0.2 细则见 [docs/reference/spec-v02-hwlab-cli.md](docs/reference/spec-v02-hwlab-cli.md)。 - Code Agent session/trace/result/inspect/steer 操作见 `hwlab-code-agent` skill。 - v0.2 HWPOD CaseRun 无服务入口：用法见 `hwlab-caserun` skill；第一阶段默认 compile-only 并把 evidence 写回 case registry repo，开发/架构细则见 [docs/reference/spec-hwpod-harness.md](docs/reference/spec-hwpod-harness.md)。 -- D601 k3s 只读观测：legacy 回溯入口，仅在确认需要 D601 事故复盘时使用；当前 G14 运行面观察使用 UniDesk route `G14:k3s`。 +- 目标 k3s 只读观测：使用当前 node/lane 的 UniDesk route，例如 `D601:k3s` 或 `G14:k3s`；D601 legacy 事故复盘只在任务明确选择旧路径时使用。 - DEV runtime hotfix 只读审计计划：`npm run dev-runtime:hotfix-audit` - Gateway 主动出站本地 smoke：`npm run gateway:demo:smoke`；经本地 edge-proxy 验证用 `npm run gateway:demo:edge-smoke`。 -## D601 legacy 只读回溯 +## D601 legacy 与 D601 node-scoped lane -当前 HWLAB DEV/PROD runtime（运行态）以 G14 原生 k3s 与 GitOps 为准；D601 只保留 legacy 事故回放、迁移对比和历史证据查询，不作为当前开发、发布、验收或 hotfix 目标。需要观察当前运行态时使用 UniDesk route `G14:k3s`，细则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。 +`D601 legacy` 只指旧 DEV/CD、迁移对比、事故回放和历史证据查询路径。D601 上的 node-scoped runtime lane（例如 issue/CLI 明确的 D601 v0.3）是正式当前目标，不得被 legacy 规则排除；需要观察当前运行态时使用该 node/lane 的 UniDesk route，例如 `D601:k3s`，细则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。 ## 禁止误判 diff --git a/docs/reference/MVP-e2e-acceptance.md b/docs/reference/MVP-e2e-acceptance.md index e26d663c..c60868f1 100644 --- a/docs/reference/MVP-e2e-acceptance.md +++ b/docs/reference/MVP-e2e-acceptance.md @@ -6,8 +6,8 @@ ## 适用范围 -- 当前 G14 DEV 浏览器入口固定为 `http://74.48.78.17:17666/`。 -- 当前 G14 DEV API、edge 和 live health 入口固定为 `http://74.48.78.17:17667/` 与 `http://74.48.78.17:17667/health/live`。 +- 当前浏览器、API、edge 和 live health 入口必须从 issue/CLI 明确的 node + lane control-plane status 读取；没有明确目标时才从受控 lane 配置解析，禁止把 G14 DEV、v0.2 或 D601 legacy 端口写成全局默认。 +- D601 v0.3 这类 node-scoped runtime lane 是正式验收目标，不属于 D601 legacy。 - 当前 MVP 上位约束是 `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78)：M3 虚拟硬件可信闭环必须证明 `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1`。 - 当前默认前端方向以 [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99) 为准：`/` 必须是类 VS Code 的 Cloud Workbench，不是 Gate、status 或 diagnostics 首页。 @@ -28,8 +28,8 @@ - 源文档：docs/reference/MVP-e2e-acceptance.md - 报告编号：MVP-E2E-RPT- -- DEV Cloud Web： -- DEV API/edge： +- Target Cloud Web： +- Target API/edge： - observed frontend revision： - observed API revision： - runner / tester： @@ -60,7 +60,7 @@ ## 证据等级 -- `DEV-LIVE`：真实 G14 DEV `17666/17667` 上的浏览器、API、runtime 或短生命周期授权操作证据。 +- `DEV-LIVE`：真实目标 node/lane 上的浏览器、API、runtime 或短生命周期授权操作证据。 - `SOURCE`：源代码、静态检查、合同校验或未部署构建证据。 - `LOCAL`：本地浏览器、fixture 或本地服务证据。 - `DRY-RUN`：显式 dry-run 输出，不触碰 DEV runtime。 @@ -72,12 +72,12 @@ ## T1 DEV 入口与运行边界 -阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：打开 `http://74.48.78.17:17666/`，确认默认页是 HWLAB Cloud Workbench，不是 Gate、status、help 或 diagnostics；访问 `http://74.48.78.17:17667/health` 和 `http://74.48.78.17:17667/health/live`，确认返回 HWLAB DEV API/edge identity。报告必须写明 legacy public `:16666/:16667` 和 public `:6666/:6667` 未作为当前验收入口，UniDesk backend、provider-gateway 和 microservice proxy 未作为 HWLAB runtime 替代。 +阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：打开当前目标 Cloud Web URL，确认默认页是 HWLAB Cloud Workbench，不是 Gate、status、help 或 diagnostics；访问当前目标 API health 和 live health，确认返回 HWLAB API/edge identity。报告必须写明实际 node、lane、Web URL、API URL，且 legacy public `:16666/:16667`、public `:6666/:6667`、G14/v0.2 旧入口或其他 lane 未作为当前验收入口，UniDesk backend、provider-gateway 和 microservice proxy 未作为 HWLAB runtime 替代。 通过标准： -- `17666` 根页可由浏览器打开，页面标题、主导航或首屏内容明确指向 HWLAB 云工作台。 -- `17667/health` 或 `17667/health/live` 返回 JSON，包含 HWLAB service identity 和 dev environment。 +- 目标 Web 根页可由浏览器打开，页面标题、主导航或首屏内容明确指向 HWLAB 云工作台。 +- 目标 health 或 live health 返回 JSON，包含 HWLAB service identity 和当前 node/lane environment。 - 报告 issue 附桌面首屏截图和 API/health 摘要。 ## T2 Cloud Workbench 首屏、布局与中文 UX @@ -104,7 +104,7 @@ ## T4 Code Agent 真实 runner 能力 -阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：在 `17666` 工作台 Agent 区输入 `pwd` 和“列出你可用的 skills”，确认返回来自真实 Codex runner、workspace、tool calls 和 skills 注入，而不是 `openai-responses` text-chat-only。随后让 Agent 通过 `hwlab-cloud-api` 执行同一 M3 硬件任务，确认 agent trace 引用对应 hardware operation 和 audit。 +阅读 `AGENTS.md`，然后用浏览器或 Playwright 手动测试以下内容：在目标 Web 工作台 Agent 区输入 `pwd` 和“列出你可用的 skills”，确认返回来自真实 Codex runner、workspace、tool calls 和 skills 注入，而不是 `openai-responses` text-chat-only。随后让 Agent 通过目标 lane 的 `hwlab-cloud-api` 执行同一 M3 硬件任务，确认 agent trace 引用对应 hardware operation 和 audit。 通过标准： @@ -138,7 +138,7 @@ 出现以下情况时停止后续 live 或 mutating 测试，并在报告 issue 中标为 `BLOCKED` 或 `failed`： -- 入口不是 G14 DEV `17666/17667`，或命中非当前 HWLAB DEV runtime。 +- 入口不是当前 issue/CLI 明确 node + lane 的 Web/API，或命中非当前 HWLAB runtime。 - 需要读取或打印 Secret/token 明文。 - 需要触碰 PROD。 - 需要重启 UniDesk、Code Queue、backend-core 或无关基础设施。 @@ -149,7 +149,7 @@ ## 稳定来源 - [architecture.md](architecture.md)：MVP 边界、M3 trusted loop 和证据等级。 -- [dev-runtime-boundary.md](dev-runtime-boundary.md)：G14 `17666/17667`、PROD `18666/18667`、G14 k3s 和运行态边界；D601 只作 legacy 回溯。 +- [dev-runtime-boundary.md](dev-runtime-boundary.md)：node/lane Web/API、k3s 和运行态边界；D601 legacy 只指旧 DEV/CD 回溯，D601 v0.3 属于正式 node-scoped lane。 - [cloud-workbench.md](cloud-workbench.md)：Cloud Workbench 默认首页和 UX 约束。 - [code-agent-chat-readiness.md](code-agent-chat-readiness.md)：Code Agent 真实回复和 provider/runner blocker 判定。 - [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md)：M3 live 操作授权、证据和失败分类。 diff --git a/docs/reference/agentrun-code-agent-dispatch.md b/docs/reference/agentrun-code-agent-dispatch.md index 95823ecc..f78f5879 100644 --- a/docs/reference/agentrun-code-agent-dispatch.md +++ b/docs/reference/agentrun-code-agent-dispatch.md @@ -7,14 +7,14 @@ - 源码入口是 `internal/agent/agentrun-dispatch.mjs`。 - `createHwlabAgentRunDispatchAssembly()` 生成 AgentRun `POST /api/v1/runs`、`POST /api/v1/runs/:runId/commands` 和 `POST /api/v1/runs/:runId/runner-jobs` 三段 payload。 - `dispatchHwlabAgentRun()` 使用同一 assembly 顺序调用 AgentRun manager；调用方可以注入 `fetchImpl` 做合同测试或接入真实 manager。 -- 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`，默认 namespace 是 `agentrun-v01`，默认 providerId 是 `G14`，默认 workspace branch 是 `v0.2`。 +- 默认 manager URL 是 `http://agentrun-mgr.agentrun-v01.svc.cluster.local:8080`，默认 namespace 是 `agentrun-v01`；`providerId`、workspace branch 和 runtime URL 必须由当前 issue/CLI 明确的 node + lane 装配传入，没有明确目标时才从受控 lane 配置解析。禁止把 `G14`、`v0.2` 或 D601 legacy 写成 AgentRun dispatch 的全局默认。 - 人工和 agent 触发 HWLAB Code Agent 任务时，优先使用已成型的 `hwlab-cli client agent session create/send/result/trace`、Workbench 同路径 API 或 CaseRun 封装入口；只有在修 adapter/dispatcher/合同测试时才手写 AgentRun payload。排查 provider、API key、session 或 trace 问题时，先用这些 CLI 原入口确认 runtime config、SecretRef、session、trace 和 result，再定位具体组件，不把问题绕成 generic provider API、runner shell、直连 Cloud API 或临时脚本路径。 ## 会话和执行边界 - HWLAB `conversationId` / `sessionId` / `threadId` 是用户可见业务会话 authority；AgentRun `runId` / `commandId` / `runnerJobId` 是执行尝试 identity；AgentRun `SessionRef` 和 per-session PVC 承载 backend/profile 的续接状态。不要把新建 AgentRun run/job 等同于新建 HWLAB session，也不要把复用 workspace selection 当作 session state。 - AgentRun `type=steer` command 是作用在既有 target trace/target command 上的控制命令，不创建新的 HWLAB session，也不改变业务 `conversationId/sessionId/threadId`。HWLAB closeout 和 UI 展示必须同时保留 target command identity 与 `steerCommandId`，并从原 target trace 观察 `agentrun:steer:accepted` / `agentrun:steer:command-created`。steer command 创建成功只证明短连接控制动作已被 AgentRun 接收；目标 turn 后续 terminal 状态按原 command/result 判定。 -- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`、`providerId=G14`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef` 子字段保存，不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染，临时处理是修 adapter 的字段归一化并重放最小真实请求，不放宽 AgentRun tenant policy。 +- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`，并把当前 node/lane 解析出的 provider identity 写入 `providerId`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef` 子字段保存，不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染，临时处理是修 adapter 的字段归一化并重放最小真实请求，不放宽 AgentRun tenant policy。 - 显式 HWLAB session 是用户可见 provider profile authority。`client agent session create --provider-profile ` 建立 session 的 `providerProfile`，Cloud API 在 dispatch 时映射为 AgentRun `backendProfile`；后续 `client agent send --session-id ` 在未显式传 `--provider-profile` 时继承该 session 的 `providerProfile`。workspace 只记录当前已选 session 和展示 seed，不能作为 child agent profile 继承来源，也不得用旧 workspace 状态覆盖显式 session。 - 同一 HWLAB session 的 resume 判定看同一个 `sessionId`、`threadId`、`providerProfile/backendProfile`、AgentRun `SessionRef` 和 PVC，而不是只看是否复用了同一个 AgentRun `runId` 或 runner Job。runner pod 被删、Job 被重建或 lease 失效后的临时恢复可以创建 replacement run/job，但只有在复用同一 `SessionRef`/PVC/thread、没有拼接历史 prompt 且 assistant 能看到前序上下文时，才算 session 持久化恢复证据；它不替代 runner reuse window 内复用同一 run/runner 的长期目标。 @@ -51,11 +51,11 @@ Provider profile slug 与配置是 AgentRun profile 管理数据，不是 Cloud ## ResourceBundle - AgentRun run 必须使用 `ResourceBundleRef.kind="gitbundle"`，默认 repo 是 `http://git-mirror-http.devops-infra.svc.cluster.local/pikasTech/HWLAB.git`。 -- `commitId` 必须是完整 40 字符小写 SHA，不接受 branch、tag、`HEAD` 或短 SHA；`workspaceRef` 只描述目标 repo/branch，默认 branch 是 `v0.2`，实际 checkout 身份以 `resourceBundleRef.repoUrl + commitId` 为准。 +- `commitId` 必须是完整 40 字符小写 SHA，不接受 branch、tag、`HEAD` 或短 SHA；`workspaceRef` 只描述目标 repo/branch，branch 必须由当前 node/lane 装配显式给出，实际 checkout 身份以 `resourceBundleRef.repoUrl + commitId` 为准。 - 默认 `bundles[]` 只有两项：`{ name: "hwlab-tools", subpath: "tools", target_path: "tools" }` 和 `{ name: "hwlab-agent-skills", subpath: "skills", target_path: ".agents/skills" }`。不得再发送 `toolAliases`、`skillRefs`、`workspaceFiles`、`subdir` 或 `sparsePaths`。 - repo 自身必须提供 extensionless 工具入口，例如 `tools/hwpod`、`tools/hwpod-ctl`、`tools/hwpod-compiler`、`tools/unidesk-ssh` 和 `tools/hwlab-code-agent`；AgentRun 只把 materialized `tools/` 加入 PATH，不再生成 alias wrapper。 - HWPOD 快速阶段没有独立 lease 控制命令；标准 `hwpod` surface 只提交 HWPOD intent，经 compiler 生成 node-ops。Agent 不得新增 gateway shell 或其他 fallback 来绕过 `hwpod -> hwpod-compiler -> /v1/hwpod-node-ops -> hwpod-node`。 -- 默认 `promptRefs` 指向 `internal/agent/prompts/hwlab-v02-runtime.md`，`inject=thread-start` 且 `required=true`。该 prompt 只在 AgentRun/Codex stdio 新 thread 首轮注入；后续 turn 必须依赖原生 `thread/resume`，不得在 command payload 中拼接历史、旧 skill 列表或长业务 prompt。 +- 默认 `promptRefs` 必须由当前 node/lane 装配选择对应 runtime prompt；v0.2 可使用 `internal/agent/prompts/hwlab-v02-runtime.md`，v0.3 或后续 lane 不得隐式回落到 v0.2 prompt。runtime prompt 只在 AgentRun/Codex stdio 新 thread 首轮注入；后续 turn 必须依赖原生 `thread/resume`，不得在 command payload 中拼接历史、旧 skill 列表或长业务 prompt。 - skills 由 `skills/` subtree 作为整体复制到 `.agents/skills`。HWLAB 不再依赖 `/app/skills`、hostPath、默认 Codex skill registry、ConfigMap、workspace seed files、`workspaceFiles` 或用户长 prompt 作为 AgentRun runner 的 skill 注入 fallback。 - AgentRun runtime image 已预装 `gh`，结合 `tool=github` 注入的 `GH_TOKEN` 即可访问 HWLAB/UniDesk PR 与 issue；不得把 GitHub token 放入 prompt 或 `transientEnv`。 diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index c378393a..844d4fca 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -7,11 +7,11 @@ M3 virtual hardware trusted loop before broadening the product surface. ## MVP Boundary -- Environment: `dev` on G14 for MVP runtime work; `prod` on G14 exists as the GitOps-controlled production namespace and public FRP surface. -- Current DEV Cloud Web entry: `http://74.48.78.17:17666/`. -- Current DEV API/edge entry: `http://74.48.78.17:17667/`. -- Current PROD Cloud Web/API entries: `http://74.48.78.17:18666/` and `http://74.48.78.17:18667/`. -- Legacy public `:16666/:16667`, `:6666`, and `:6667` are historical or internal-port surfaces and must not be used as current browser or API acceptance targets. +- Environment: MVP runtime work must use the node/lane explicitly selected by the issue, PR, CLI parameters, or controlled lane config. G14 DEV/PROD and D601 v0.3 are lane examples, not global defaults. +- Current Cloud Web entry: read from the selected node/lane control-plane status. +- Current API/edge entry: read from the selected node/lane control-plane status. +- PROD entries exist only when the selected lane is a PROD lane and must be verified through its own GitOps/public health path. +- Legacy public `:16666/:16667`, `:6666`, and `:6667` are historical or internal-port surfaces and must not be used as current browser or API acceptance targets. D601 node-scoped lanes such as D601 v0.3 are not legacy. - UniDesk may support scheduling, CI, or CD. It is not a HWLAB runtime substitute. - M3 mutating proof remains DEV-first; PROD presence is verified through GitOps, Argo sync, Deployment readiness and public health, not through hardware mutation. @@ -19,12 +19,12 @@ M3 virtual hardware trusted loop before broadening the product surface. ## Runtime Shape Current service ownership and v0.2 keep/remove decisions are authoritative in -[spec-v02-services.md](spec-v02-services.md). The current G14 runtime path is: +[spec-v02-services.md](spec-v02-services.md). The selected node/lane runtime path is: ```text browser or CLI -> master edge / frp public ports --> G14 hwlab-dev or hwlab-prod namespace +-> selected node/lane namespace -> HWLAB cloud/runtime services -> gateway, simulators, patch panel, agent services ``` @@ -90,6 +90,6 @@ Code Agent chat 证据单独分级：只有真实同源 `/v1/agent/chat` board and priority status. - [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78): M3 decision and prompt/review guardrails. -- [dev-runtime-boundary.md](dev-runtime-boundary.md): G14 DEV/PROD and v0.2 runtime boundary. +- [dev-runtime-boundary.md](dev-runtime-boundary.md): node/lane runtime boundary and known lane examples. - [spec-v02-services.md](spec-v02-services.md): v0.2 microservice keep/remove and dependency boundary. - [spec-v02-documentation-governance.md](spec-v02-documentation-governance.md): root README and legacy process document migration. diff --git a/docs/reference/cloud-workbench.md b/docs/reference/cloud-workbench.md index d728a810..345504ce 100644 --- a/docs/reference/cloud-workbench.md +++ b/docs/reference/cloud-workbench.md @@ -1,7 +1,7 @@ # HWLAB Cloud Workbench Reference -Cloud Workbench is the default user-facing frontend at -`http://74.48.78.17:17666/`. It must serve the #99 workbench direction and the +Cloud Workbench is the default user-facing frontend for the current target +node/lane Web entry, resolved from issue/CLI control-plane status. It must serve the #99 workbench direction and the #108 UX constraints while respecting the M3 boundary from `DC-DCSN-P0-2026-003`. @@ -17,7 +17,7 @@ Cloud Workbench is the default user-facing frontend at - `/gate` and `/diagnostics/gate` are internal diagnostic aliases served by the same Cloud Web app router. They may carry Gate, blocker, and M0-M5 evidence because they are not the default homepage. -- `http://74.48.78.17:17667/` remains the API/edge boundary. +- The API/edge boundary is the current target node/lane API URL; it must be read from control-plane status or controlled lane config, not from a hardcoded G14/v0.2 default. - Browser data sources are same-origin `/v1`, read-only `/json-rpc`, source reports, gate reports, and blocked reports. - Code Agent conversation 使用受控同源 `POST /v1/agent/chat` 通道。直接 @@ -92,7 +92,7 @@ The #108 constraints are current baseline: ## Evidence And Labels Visible runtime or evidence state must keep `SOURCE`, `LOCAL`, `DRY-RUN`, -`DEV-LIVE`, and `BLOCKED` distinct. Loading the page from `17666` proves only +`DEV-LIVE`, and `BLOCKED` distinct. Loading the current target Web URL proves only that Cloud Web is reachable. It does not prove DB readiness, M3, M4, M5, or a hardware loop. @@ -185,7 +185,7 @@ node web/hwlab-cloud-web/scripts/check.mjs node web/hwlab-cloud-web/scripts/build.mjs node scripts/dev-cloud-workbench-smoke.mjs --static node scripts/dev-cloud-workbench-layout-smoke.mjs --static -node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:17666/ +node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url ``` `npm run web:check` 是 Cloud Workbench 的 repo-owned 前端检查入口。它会 @@ -200,7 +200,7 @@ M3 IO。 默认 `web:check` 只把当前工作台主路径、Code Agent/trace/quick-prompt、布局命中和 安全边界作为阻断检查。历史 auth fixture、演示 fixture 或与当前改动无关的浏览器 journey 可以继续产出诊断报告，但不得因为 Playwright `scrollIntoView` 与固定命令栏、 -顶部状态摘要等布局细节耦合而阻塞 G14 CI/CD。需要恢复为阻断检查时，必须先证明该 +顶部状态摘要等布局细节耦合而阻塞目标 node/lane CI/CD。需要恢复为阻断检查时，必须先证明该 fixture 代表真实用户入口问题，而不是旧检查假设。 The static smoke checks both sides of the route contract: `/` remains the @@ -209,7 +209,7 @@ for internal diagnostics. This PR-class check is intentionally source-only and does not deploy, restart services, call public DEV, or run the full live Code Agent browser journey. -Live checks against `http://74.48.78.17:17666/` are read-only and must report +Live checks against the current target Web URL are read-only and must report blocked/skip instead of false green when the browser or network path is not available. @@ -250,7 +250,7 @@ npm run web:layout:live | --- | --- | --- | | SOURCE/static | `npm run web:check` 或 `npm run web:layout` | PR/source gate 默认运行，不依赖公网 DEV。 | | local-build | `npm run web:layout:build` | Cloud Web build/publish 前运行；会先刷新本地 `dist`。 | -| DEV live | `npm run web:layout:live` | DEV deploy 后对 `http://74.48.78.17:17666/` 运行，只证明 UI layout/clickability。 | +| target live | `npm run web:layout:live` | 目标 node/lane deploy 后对当前 Web URL 运行，只证明 UI layout/clickability。 | 报告字段必须能定位 `status=pass|blocked|skip`、`viewport`、`selector`、 `failureType` 和 artifact 路径。当前允许的 `failureType` 包括 `overlap`、 diff --git a/docs/reference/code-agent-chat-readiness.md b/docs/reference/code-agent-chat-readiness.md index b3ca8ce8..2ed9ab50 100644 --- a/docs/reference/code-agent-chat-readiness.md +++ b/docs/reference/code-agent-chat-readiness.md @@ -6,10 +6,8 @@ Secret 或 token。 ## 运行边界 -- DEV Cloud Web 入口是 `http://74.48.78.17:17666/`，同源代理到 - `/v1/agent/chat`。 -- DEV API/edge 入口是 `http://74.48.78.17:17667/`；它不能替代 Workbench - 同源聊天入口的真实回复证据。 +- Cloud Web 和 API/edge 入口必须从当前 issue/CLI 明确的 node + lane control-plane status 读取；没有明确目标时才从受控 lane 配置解析，禁止把 G14 DEV、v0.2 或 D601 legacy 端口写成全局默认。 +- API/edge 入口不能替代 Workbench 同源聊天入口的真实回复证据；Web 问题必须在同一目标 Cloud Web base URL 下复现和验收。 - `internal/cloud/code-agent-chat.ts` 是 `/v1/agent/chat` 的后端处理入口。 - `scripts/code-agent-chat-smoke.mjs` 是 Code Agent chat schema 与 readiness 合同检查。 @@ -20,20 +18,19 @@ Secret 或 token。 当前 v0.2 部署合同中，`hwlab-cloud-api` 把 Code Agent 执行委托给 AgentRun `v0.1`。运行时必须具备可用的 AgentRun manager、runner job、`ResourceBundleRef`、`SessionRef`/PVC、profile SecretRef 和目标 backend profile；如果该 backend 使用 Codex app-server，runner 内还必须证明 workspace、`CODEX_HOME`、Codex binary 和 native thread/session continuation 可用。Per-profile config/credential/dynamic slug 管理见 [spec-v02-provider-management.md](spec-v02-provider-management.md)，dispatch/session/child inheritance 见 [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md)。 -Codex token boundary 仍由授权路径把 `OPENAI_API_KEY` 注入到 DEV runtime。DEV Pod -不能直接指向 public `api.openai.com`。G14 默认 `deepseek` profile 指向 +Codex token boundary 仍由授权路径把 `OPENAI_API_KEY` 注入到目标 runtime。目标 Pod +不能直接指向 public `api.openai.com`。`deepseek` profile 通常指向 `http://hwlab-deepseek-proxy..svc.cluster.local:4000/v1/responses`；该 Service 必须先进入 `hwlab-deepseek-responses-bridge`，由 bridge 解压 Codex Responses 的 zstd request body、规范化 `/v1/models` 返回、丢弃非 `function` tool， 再转发到同 Pod 内 Moon Bridge 4001。Moon Bridge 是 DeepSeek profile 的真实 Responses 转换和 prompt cache 保留层；不要在 HWLAB 中手写完整转换器替代它。 -`codex-api` profile 是独立的 Codex/OpenAI-compatible Responses 通道。G14 上 +`codex-api` profile 是独立的 Codex/OpenAI-compatible Responses 通道。node-scoped runtime 中 `hwlab-cloud-api` 应把 `codex-api` base URL 指向同 Pod 的 `127.0.0.1` loopback forwarder；forwarder 再直连 `hyueapi.com` / `.hyueapi.com`，并把这两个域名显式保留在 `NO_PROXY` / `no_proxy`。这不是 DeepSeek bridge，也不是公网 `api.openai.com`，不能把 hyueapi 流量改成 HTTP/SOCKS proxy。`http://172.26.26.227:17680/v1/responses` 只能作为 -D601 legacy Code Queue runner 或历史 egress 的对照线索；迁移到 G14 后不得把它当作 -G14 默认 `codex-api` base URL，也不得用 DeepSeek bridge 伪装 `codex-api` 通过。 +明确选择旧 D601 Code Queue runner 或历史 egress 时的对照线索；不得把它写回任何当前 node/lane 的默认 `codex-api` base URL，也不得用 DeepSeek bridge 伪装 `codex-api` 通过。 Runner 不得尝试修补、读取、回显或替换该 Secret。若 DEV runtime 缺少该授权凭证注入， `provider_unavailable` 且 `error.missingEnv` 包含 `OPENAI_API_KEY` 必须判为 @@ -49,8 +46,8 @@ Provider/profile 切换故障必须先在目标 pod/host 上打通最小真实 最小闭环按以下顺序分层，任何一层失败都不能跳到正式 CI/CD 试错： -1. 运行面确认：在 G14 `/root/hwlab` 与 G14 k3s 目标 pod 内确认当前分支、镜像、env overlay、 - `CODEX_HOME`、Codex 版本和 workspace；D601 只能作为 legacy 对照，不作为 G14 source truth。 +1. 运行面确认：在当前 issue/CLI 明确的 node/lane 固定 workspace 与目标 k3s Pod 内确认当前分支、镜像、env overlay、 + `CODEX_HOME`、Codex 版本和 workspace；D601 v0.3 这类 node-scoped lane 是正式目标，不得按 legacy 对照排除。 2. 凭证边界：只检查 Secret 引用、`auth.json` 顶层 key 和值长度，不打印 secret。Codex CLI 的 `auth.json` 应能暴露 `OPENAI_API_KEY` 顶层 key；形如 `auth` 的不明结构必须先按 blocker 处理。 3. 直连边界：`hyueapi.com` / `.hyueapi.com` 必须在 `NO_PROXY` 与 `no_proxy` 内。需要同时检查 @@ -59,9 +56,7 @@ Provider/profile 切换故障必须先在目标 pod/host 上打通最小真实 4. 裸 Responses API：在同一个目标 pod 内用同一份 auth、同一模型、同一 base host 发 `/responses` 或 `/v1/responses` 流式请求，确认网络、认证和模型是否可用。裸 API 通过只证明 upstream 可达，不等于 Workbench 或 Codex runner 通过。 -5. Codex CLI 对照：用同一模型、同一 `CODEX_HOME`、同一 prompt 运行 `codex exec --json`；同时在 - D601 Code Queue runner 上做同模型对照，记录版本、config 形态、NO_PROXY、proxy env 和 transport - 摘要。D601 对照只用于定位差异，不能把 D601 路径写回 G14 默认运行态。 +5. Codex CLI 对照：用同一模型、同一 `CODEX_HOME`、同一 prompt 运行 `codex exec --json`；如果任务明确需要旧 D601 Code Queue runner 或其他节点对照，再记录版本、config 形态、NO_PROXY、proxy env 和 transport 摘要。跨节点对照只用于定位差异，不能把对照路径写回当前 node/lane 默认运行态。 6. Loopback forwarder 对照：如果裸 Responses API 通过、Codex CLI 直连失败，并且 trace 已确认 `network_proxy: None`，必须在同一个目标 Pod 内增加只监听 `127.0.0.1` 的临时 forwarder，使用同一份 auth、同一模型和同一 prompt 复测 `codex exec` 与 `/v1/agent/chat`。forwarder 只能把流量转到可配置的 @@ -70,12 +65,12 @@ Provider/profile 切换故障必须先在目标 pod/host 上打通最小真实 排查记录应保留稳定结论和判定方法，不写 Secret、一次性 trace 全文或日期化流水账。遇到 “裸 API 通过但 Codex CLI/app-server 失败”时，优先抓 Codex/Rust transport 日志并与 D601 成功 -路径比对：模型、service tier、`auth.json` 结构、base URL、是否直连、实际连接 IP、请求体大小、 +路径或其他明确对照路径比对：模型、service tier、`auth.json` 结构、base URL、是否直连、实际连接 IP、请求体大小、 SSE 是否 completed。只有这些证据归一后，才修改源码、render、SecretRef 或发布配置。 ## Codex API 转发根因 -`codex-api` 在 G14 上采用 pod-local loopback forwarder 是一个受控传输边界修复，不是为了规避 +`codex-api` 在 node-scoped runtime 上采用 pod-local loopback forwarder 是一个受控传输边界修复，不是为了规避 hyueapi 直连要求。根因判定按以下证据链成立： - 同一目标 Pod 内，使用同一份 auth、同一模型、同一 Responses payload，通过 Node HTTPS 直接请求 @@ -88,8 +83,8 @@ hyueapi 直连要求。根因判定按以下证据链成立： hyueapi，`codex exec` 与 `/v1/agent/chat` 均能完成并返回非空 assistant 回复；这把失败边界收敛到 Codex CLI 的 Rust HTTPS/SSE transport 与 G14->hyueapi 边缘路径组合，而不是 Workbench、DeepSeek、 模型或 auth。 -- D601 Code Queue runner 使用同模型可成功，只能证明 D601 legacy 路径可作为对照；不能把 - `172.26.26.227:17680` 写回 G14 默认配置。 +- 旧 D601 Code Queue runner 使用同模型可成功，只能证明该对照路径可用；不能把 + `172.26.26.227:17680` 写回当前 node/lane 默认配置。 因此，在不修改 Codex CLI 二进制、不要求 hyueapi 改边缘行为、也不把 hyueapi 流量送进 HTTP/SOCKS proxy 的前提下，pod-local Node forwarder 是当前可控的最小修复。它的职责只是替换 Codex CLI 失败的 @@ -286,7 +281,7 @@ Workbench 静态接线检查： ```sh node scripts/dev-cloud-workbench-smoke.mjs --static -node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:17666/ +node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url ``` 该命令验证 Workbench 默认页、同源只读边界和 `/v1/agent/chat` 前端主流程接线。它只产出 @@ -298,14 +293,14 @@ node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:1 ```sh node scripts/code-agent-chat-smoke.mjs --live -node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:17667/ --timeout-ms 45000 +node scripts/code-agent-chat-smoke.mjs --live --url --timeout-ms 45000 ``` `--live` 会向真实 DEV `/v1/agent/chat` 发送一条最小聊天请求。输出只包含 readiness、provider/model/backend、assistant 回复是否非空和长度、错误分类等摘要；不打印 assistant 回复正文，不读取或打印任何 Secret 值。 -默认 `--live` 应指向当前 G14 DEV API/edge 入口 `17667`，而不是历史 D601 端口。 +默认 `--live` 应指向当前 issue/CLI 明确 node + lane 的 API/edge 入口，而不是历史 D601 legacy 端口、G14 DEV 端口或其他 lane 入口。 健康的 Codex stdio 冷启动首个 assistant token 可能需要数十秒；10 秒级 transport timeout 会把健康环境误报为 transport blocker。把 timeout 提高到 45 秒左右只是在真 实 DEV 路由上减少误报，不能替代 `completed` + 非空 assistant reply 的最终判定标 diff --git a/docs/reference/commander-collaboration.md b/docs/reference/commander-collaboration.md index 7962fe35..f57e40b1 100644 --- a/docs/reference/commander-collaboration.md +++ b/docs/reference/commander-collaboration.md @@ -5,9 +5,9 @@ ## 指挥作风 - 指挥官必须亲自掌握关键一手事实，不能只依赖 runner 的二手摘要。 -- 必须亲自查看 `http://74.48.78.17:17666/` 默认首屏、`/gate` 或内部诊断页、关键 PR diff、部署 revision、DEV 验收结果和失败证据。 +- 必须亲自查看当前 issue/CLI 明确 node + lane 的 Web 入口默认首屏、`/gate` 或内部诊断页、关键 PR diff、部署 revision、运行面验收结果和失败证据；没有明确目标时才从受控 lane 配置解析入口，禁止把 G14、v0.2 或 D601 legacy 写成全局默认。 - 专题 issue 评论是长任务的上下文锚点。调查结论、细化方案、阶段进展、卡点、修复边界、验收命令和最终结论必须及时写入对应 GitHub issue 评论；不要只存在对话上下文、临时文件或本地记忆里。上下文压缩、换 agent、跨仓库修复或进入 CI/CD 前，应先读最新 issue 评论，再继续执行。 -- Web/CLI 路径分叉属于优先级高的工具摩擦。浏览器工作台暴露问题后，先用 `hwlab-cli client` 走同一 Cloud Web base URL 复现；Code Agent continuation 优先用 `client agent send --from-trace ` 从 inspect 自动恢复 Web 上下文，HWPOD 操作优先验证 `hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node`，再决定是否修业务本体。 +- Web/CLI 路径分叉属于优先级高的工具摩擦。浏览器工作台暴露问题后，先用 `hwlab-cli client` 走同一目标 Cloud Web base URL 复现；Code Agent continuation 优先用 `client agent send --from-trace ` 从 inspect 自动恢复 Web 上下文，HWPOD 操作优先验证 `hwpod-cli -> hwpod-compiler-cli -> /v1/hwpod-node-ops -> hwpod-node`，再决定是否修业务本体。 - 一层 Code Queue 直接执行业务实现、修复、部署和验证是允许的基层指挥模式。 - 不得把战略判断、是否偏离用户目标的判断、关键 PR 最终审查、关键部署证据审查、指挥官自我反省和指挥规则更新外派给 runner。 - 不得为了 Gate 生成 Gate、为了报告生成报告、为了审查再派审查、为了管理继续拆管理；Gate、报告、预检和观测脚本只能作为真实上线、真实 E2E 或 blocker 解除的必要最小工具。 @@ -22,28 +22,29 @@ ## 工作区规则 -- 常规 runner 和指挥官工作区是 `/workspace/hwlab`。 -- 进入仓库先检查分支和工作树状态。 -- G14 人工/指挥官开发必须先在固定 repo `/root/hwlab` 做 `pwd`、`git status --short --branch`、`git remote -v` 和 `fetch` 预检，再在 `/root/hwlab/.worktree/` 从最新 `origin/G14` 创建任务专属 worktree；代码、文档、测试补丁、提交和 PR 准备都在该独立 worktree 中完成。 -- G14 `v0.2` 固定开发 workspace 是 `/root/hwlab-v02`，固定跟踪 `origin/v0.2`。所有 `v0.2` 文档、计划、CI/CD lane 和 namespace 设计必须在该 workspace 或其明确创建的 `v0.2` worktree 中完成；不得使用 `/root/hwlab` 根目录或现有 `hwlab-dev`/`hwlab-prod` 运行面作为 `v0.2` scratch 区。CI/CD source commit 选择只使用 `/root/hwlab-v02-cicd.git` 自动 fetch 后的 commit-pinned detached worktree，不能因为 `/root/hwlab-v02` dirty、stale 或存在 `.worktree/` 就阻塞或改变发布。 -- 固定 repo `/root/hwlab` 是 source truth 和 worktree 管理入口，不是并行任务 scratch 区；不要在固定 repo 根目录堆叠未提交改动，也不要复用其他任务遗留 `.worktree/`。 -- D601 `/home/ubuntu/workspace/hwlab` 只作为 legacy 事故回放和迁移对照工作区；当前 G14 DEV/PROD 与 `v0.2` 发布、rollout 和验收不使用 D601 作为运行面真相。 +- 常规 runner 和指挥官工作区是 `/workspace/hwlab`；进入仓库先检查分支和工作树状态。 +- 具体开发/验收 workspace 必须按当前 issue、PR、CLI 参数或受控 lane 配置解析 node + lane，再在对应固定 repo 做 `pwd`、`git status --short --branch`、`git remote -v` 和 `fetch` 预检。 +- D601 v0.3 的固定开发 workspace 是 `/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `origin/v0.3`；当任务明确 D601 v0.3 时，它就是当前 source truth，不是 legacy 对照面。 +- G14 DEV/PROD、G14 v0.2 和其他 node/lane 的固定 workspace 只在任务明确选择对应 node/lane 时使用；不得把 `/root/hwlab`、`/root/hwlab-v02` 或旧 `hwlab-dev`/`hwlab-prod` 运行面写成所有 HWLAB 任务默认 scratch 区。 +- CI/CD source commit 选择必须使用当前 node/lane 的受控 source repo 或 control-plane 自动 fetch 后的 commit-pinned detached worktree，不能因为人工开发 workspace dirty、stale 或存在 `.worktree/` 就阻塞或改变发布。 +- 固定 repo 是 source truth 和 worktree 管理入口，不是并行任务 scratch 区；不要在固定 repo 根目录堆叠未提交改动，也不要复用其他任务遗留 `.worktree/`。 +- D601 legacy 只指旧 DEV/CD、迁移对照和事故回放路径；D601 node-scoped runtime lane 不属于 legacy。 - 不要清理、reset 或复用无关 runner worktree 作为发布真相。 ## 分支和交付工作流 -- 单纯文档、CLI/helper 轻量变更默认直接提交并 push 到 `origin/G14`，不开 PR；这类变更仍要先从最新 `origin/G14` 创建独立 worktree，提交前审查 diff，只提交当前任务相关文件。 +- 单纯文档、CLI/helper 轻量变更默认直接提交并 push 到当前 node/lane source branch，通常不开 PR；这类变更仍要先快进目标固定 workspace，提交前审查 diff，只提交当前任务相关文件。 - `v0.2` 线的单纯文档和规格更新可以直接提交并 push 到 `origin/v0.2`，不开 PR；涉及 namespace 创建、Argo CD Application、Tekton Pipeline/control-plane、git mirror/relay、FRP、Secret、DB、权限或 runtime rollout 的变更必须先有 GitHub issue 承接过程计划，再按 issue 和对应 `docs/reference/spec-*.md` 分步执行。仓库内不再新增 `docs/plan/*.md`。 - 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD、重启服务、CI/CD 控制面高风险变更或其他影响 runtime truth 的变更默认走 PR 工作流。 - 用户或指挥官给出最新交付纠偏时，以最新要求为准，删除旧断言或旧门禁，不用 feature flag、legacy mode 或双路径长期并存绕开最新要求。 -- G14 线需要 PR 时，从最新 `origin/G14` 创建短分支，PR base 指向 `pikasTech/HWLAB:G14`；`v0.2` 线需要 PR 时，从最新 `origin/v0.2` 创建短分支，PR base 指向 `pikasTech/HWLAB:v0.2`。 -- `origin/main` / `main` 不再是当前 G14 或 `v0.2` 默认开发、PR 或发布 base；只有显式 branch-governance 或 D601 legacy 任务才可使用。 +- 需要 PR 时，从当前 node/lane 的 source branch 创建短分支，PR base 必须指向同一 source branch；例如 D601 v0.3 任务应以 `origin/v0.3` 为 base，G14 v0.2 任务才以 `origin/v0.2` 为 base。 +- `origin/main` / `main` 不再是当前 node-scoped runtime lane 的默认开发、PR 或发布 base；只有显式 branch-governance 或旧 D601 legacy 任务才可使用。 - 不要修改 PROD。 - 除非任务明确授权，不要重启服务。 -- 需要 PR 时，目标分支必须匹配当前工作线的 source branch；不要把 G14 或 `v0.2` 变更默认投向 `main`。 +- 需要 PR 时，目标分支必须匹配当前工作线的 source branch；不要把 D601 v0.3、G14 或 `v0.2` 变更默认投向 `main` 或其他 lane。 - runner 默认不合并自己的 PR；用户或指挥官可以对单个 PR 明确授权 runner 自合并。 -- 自合并前必须同时满足：PR 为 `MERGEABLE/CLEAN` 或等价无冲突状态；required checks 没有失败；G14/`v0.2` CI 或当前 issue 显式指定的 legacy/runtime 验证证据已贴到 PR/issue；变更不涉及 PROD、Secret、权限提升、数据迁移或未授权重启；runner 在最终评论中列出提交 SHA、验证命令和回滚边界。 +- 自合并前必须同时满足：PR 为 `MERGEABLE/CLEAN` 或等价无冲突状态；required checks 没有失败；当前 issue 明确 node/lane 的 CI 或 runtime 验证证据已贴到 PR/issue；变更不涉及 PROD、Secret、权限提升、数据迁移或未授权重启；runner 在最终评论中列出提交 SHA、验证命令和回滚边界。 - 当前 GitHub 写入仍优先走 UniDesk CLI 或 repo-owned GitHub 路径；若当前 CLI 不支持 merge，必须使用可审计的授权路径，不能用无记录的本地绕行来规避审计。 - PR 冲突由指挥官审阅并处理；runner 不做大范围冲突手术，除非被明确分配。 - 指挥官合并 PR 时必须同时 review，确认方向没有偏离 `#7`、`#78`、`#99` 和当前用户反馈。 diff --git a/docs/reference/dev-runtime-boundary.md b/docs/reference/dev-runtime-boundary.md index 2d77667a..c85f4823 100644 --- a/docs/reference/dev-runtime-boundary.md +++ b/docs/reference/dev-runtime-boundary.md @@ -1,23 +1,26 @@ -# HWLAB DEV Runtime Boundary +# HWLAB Runtime Boundary -This reference defines the stable DEV environment, port, k3s, and runtime -substitution rules. +This reference defines the stable node/lane environment, port, k3s, and runtime +substitution rules. Current work must resolve its target from the issue, PR, +CLI parameters, or controlled lane config before using any URL or workspace. -## Public G14 Runtime Ports +## Runtime Ports And Lane Examples -| Surface | DEV URL | PROD URL | v0.2 URL | +Current Web/API/live entries are read from `hwlab nodes ... --node --lane status` or the equivalent control-plane status. The table below records known lane examples; it is not a global default. + +| Surface | G14 DEV example | G14 PROD example | G14 v0.2 example | D601 v0.3 example | | --- | --- | --- | --- | -| Cloud Web browser entry | `http://74.48.78.17:17666/` | `http://74.48.78.17:18666/` | `http://74.48.78.17:19666/` | -| API/edge entry | `http://74.48.78.17:17667/` | `http://74.48.78.17:18667/` | `http://74.48.78.17:19667/` | -| API/live health | `http://74.48.78.17:17667/health/live` | `http://74.48.78.17:18667/health/live` | `http://74.48.78.17:19667/health/live` | +| Cloud Web browser entry | `http://74.48.78.17:17666/` | `http://74.48.78.17:18666/` | `http://74.48.78.17:19666/` | `https://hwlab.pikapython.com/` | +| API/edge entry | `http://74.48.78.17:17667/` | `http://74.48.78.17:18667/` | `http://74.48.78.17:19667/` | `https://hwlab.pikapython.com/` | +| API/live health | `http://74.48.78.17:17667/health/live` | `http://74.48.78.17:18667/health/live` | `http://74.48.78.17:19667/health/live` | `https://hwlab.pikapython.com/health/live` | -Public `:16666` and `:16667` are D601 legacy DEV endpoints. They can be used only for migration comparison or incident replay, not as the current HWLAB runtime acceptance target. Internal k3s services may still listen on `6667`; do not rewrite that as a public endpoint. +Public `:16666` and `:16667` are D601 legacy DEV endpoints. They can be used only for migration comparison or incident replay, not as the current HWLAB runtime acceptance target. D601 node-scoped lanes such as D601 v0.3 are not legacy. Internal k3s services may still listen on `6667`; do not rewrite that as a public endpoint. D601 `v0.3` 的公网入口是 `https://hwlab.pikapython.com/`，API/live health 是 `https://hwlab.pikapython.com/health/live`。该 lane 的内部 `hwlab-cloud-api` / `hwlab-edge-proxy` Service 仍可监听 `6667`，但浏览器、Web admin smoke 和公网验收必须以 HTTPS edge 为准。Node/undici `fetch` 会按 WHATWG bad-port 规则拒绝 `6666`/`6667`；探测内部 `:6667` 时使用 `curl`、Node `http`/`https` 原生 request、repo-owned probe，或改走公网 HTTPS。gateway 侧同一限制见 [gateway-outbound-demo.md](gateway-outbound-demo.md)。 ## Route Shape -The current G14 DEV route is: +Known route examples: ```text master hwlab-frps-dev :17666/:17667 @@ -34,40 +37,46 @@ master hwlab-frps-dev :19666/:19667 -> G14 v0.2 frpc in namespace hwlab-v02 -> hwlab-cloud-web on internal :8080 for browser traffic -> hwlab-edge-proxy / hwlab-cloud-api on internal :6667 for API and health + +PK01 Caddy/FRP HTTPS +-> D601 v0.3 frpc in namespace hwlab-v03 +-> hwlab-cloud-web on internal :8080 for browser traffic +-> hwlab-edge-proxy / hwlab-cloud-api on internal :6667 for API and health ``` G14 PROD is rendered by GitOps as namespace `hwlab-prod` and Argo CD application `hwlab-node-prod`; it uses the `:18666/:18667` public endpoints when enabled. G14 desired state is generated into `deploy/gitops/node/runtime-dev` and `deploy/gitops/node/runtime-prod` and promoted through the `G14-gitops` branch. G14 `v0.2` is an additive lane, not a replacement for DEV or PROD. It uses source branch `v0.2`, fixed development workspace `G14:/root/hwlab-v02`, dedicated CI/CD source repo `G14:/root/hwlab-v02-cicd.git`, namespace `hwlab-v02`, and public ports `19666/19667`. The `v0.2` GitOps branch, runtime path and Argo Application must be distinct from DEV/PROD before any automated rollout is enabled. -## G14 k3s Source Of Truth +## Node k3s Source Of Truth -G14 native k3s is the HWLAB DEV/PROD runtime source of truth. Commands that observe or mutate current HWLAB runtime must go through UniDesk route `G14:k3s`, for example: +The target node's native k3s is the runtime source of truth for the selected lane. Commands that observe or mutate current HWLAB runtime must go through the selected UniDesk route, for example: ```sh tran G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide tran G14:k3s kubectl -n argocd get application hwlab-node-dev hwlab-node-prod tran G14:k3s kubectl -n hwlab-v02 get deploy,svc,pod -o wide +tran D601:k3s kubectl -n hwlab-v03 get deploy,svc,pod -o wide ``` -Do not use D601 kubeconfig, D601 `dev-cd-apply`, old JS `ci-publish`, Docker Desktop Kubernetes, or master-server local checks as G14 runtime acceptance evidence. D601 remains a legacy migration/reference surface until the branch-role migration is complete. +Do not use another node's kubeconfig, D601 legacy `dev-cd-apply`, old JS `ci-publish`, Docker Desktop Kubernetes, or master-server local checks as current runtime acceptance evidence. D601 legacy is only the old DEV/CD replay path; D601 v0.3 is a valid current target when selected by issue/CLI. ## Branch Role Boundary -Current runtime work uses explicit branch lines: G14 DEV/PROD uses `origin/G14`, and the additive `v0.2` lane uses `origin/v0.2`, `/root/hwlab-v02-cicd.git`, `devops-infra` git mirror/relay and `hwlab-v02`. Do not merge `origin/main` as a routine precondition for G14 or `v0.2` runtime work. Treat `main` only as a historical branch-governance or D601 legacy reference unless a current issue explicitly assigns a `main` migration task. The `v0.2` lane remains separate from G14 DEV/PROD; its CI/CD branch, runtime path and acceptance rules are authoritative in [spec-v02-cicd.md](spec-v02-cicd.md). +Current runtime work uses explicit node/lane branch lines. For example, D601 v0.3 uses `origin/v0.3` and namespace `hwlab-v03`; G14 v0.2 uses `origin/v0.2`, `/root/hwlab-v02-cicd.git`, `devops-infra` git mirror/relay and `hwlab-v02`. Do not merge `origin/main` as a routine precondition for node-scoped runtime work. Treat `main` only as a historical branch-governance or legacy reference unless a current issue explicitly assigns a `main` migration task. Lane-specific CI/CD branch, runtime path and acceptance rules are authoritative in the corresponding spec and control-plane status. ## Distributed Passthrough Hygiene -When running more than one command on G14, keep all commands inside one remote `script` block: +When running more than one command on a target node, keep all commands inside one remote `script` block: ```sh -tran G14:/root/hwlab script <<'SCRIPT' +tran : script <<'SCRIPT' sed -n '1,80p' docs/reference/dev-runtime-boundary.md sed -n '1,80p' AGENTS.md SCRIPT ``` -Do not write `tran G14:/root/hwlab sed ... && sed ...` unless the second command is intentionally local. Shell operators such as `&&`, `;`, and pipes outside the `tran` invocation are evaluated by the local shell; this can make later commands run on the master server and look like a missing-file or truncation bug. +Do not write `tran : sed ... && sed ...` unless the second command is intentionally local. Shell operators such as `&&`, `;`, and pipes outside the `tran` invocation are evaluated by the local shell; this can make later commands run on the master server and look like a missing-file or truncation bug. ## Cloud API DB Readiness Authority diff --git a/docs/reference/dev-runtime-hotfix-runbook.md b/docs/reference/dev-runtime-hotfix-runbook.md index 68365a71..76d6592f 100644 --- a/docs/reference/dev-runtime-hotfix-runbook.md +++ b/docs/reference/dev-runtime-hotfix-runbook.md @@ -127,23 +127,23 @@ node scripts/dev-runtime-hotfix-audit.mjs --collect-readonly --pretty 优先回滚方式是用源码化 artifact/CD 覆盖 runtime hotfix：#460/#461 合并并发布后，Deployment 应消费正式镜像，不再通过 ConfigMap 覆盖 `/app/internal/cloud/code-agent-chat.ts`。注意 `kubectl apply -k` 可能保留运行面 patch 写入、且源码 desired-state 不拥有的 hotfix `volumes`、`volumeMounts` 或 template annotations；正式 DEV CD apply 应先识别这种 unmanaged hotfix 覆盖，删除对应 desired Deployment，再由同一次 apply 从源码重新创建。 -只读确认口径是通过当前 G14 k3s route 读取目标对象；不要从 master server 裸跑 `kubectl`，也不要把 D601 kubeconfig 当作当前 DEV/v0.2 控制面： +只读确认口径是通过当前 issue/CLI 明确 node + lane 的 k3s route 读取目标对象；不要从 master server 裸跑 `kubectl`，也不要把其他 node kubeconfig 当作当前控制面： ```sh -bun scripts/cli.ts ssh G14:k3s kubectl get nodes -o jsonpath='{.items[*].metadata.name}' -bun scripts/cli.ts ssh G14:k3s kubectl -n hwlab-dev get deployment hwlab-cloud-api -o json -bun scripts/cli.ts ssh G14:k3s kubectl -n hwlab-dev get configmap hwlab-cloud-api-code-agent-hotfix -o json +bun scripts/cli.ts ssh :k3s kubectl get nodes -o jsonpath='{.items[*].metadata.name}' +bun scripts/cli.ts ssh :k3s kubectl -n get deployment hwlab-cloud-api -o json +bun scripts/cli.ts ssh :k3s kubectl -n get configmap hwlab-cloud-api-code-agent-hotfix -o json node scripts/dev-runtime-hotfix-audit.mjs --collect-readonly --pretty ``` -如果必须直接移除运行态覆盖，授权操作者应先从 `kubectl -n hwlab-dev get deployment hwlab-cloud-api -o json` 中定位精确 indexes，再移除： +如果必须直接移除运行态覆盖，授权操作者应先从目标 namespace 的 `hwlab-cloud-api` Deployment JSON 中定位精确 indexes，再移除： - 指向 hotfix ConfigMap 的 `spec.template.spec.volumes[]`； - 指向 `/app/internal/cloud/code-agent-chat.ts` 的 `containers[].volumeMounts[]`； - `hwlab.pikastech.local/pc-gateway-shell-hotfix` 等 hotfix annotation； - 不再需要的 `hwlab-cloud-api-code-agent-hotfix` ConfigMap。 -直接 `kubectl patch`、`kubectl delete configmap`、`kubectl rollout status` 或等价写操作必须由明确授权的 DEV 操作者执行，并且当前 G14 DEV/v0.2 运行面必须通过 UniDesk route `G14:k3s` 操作。D601 kubeconfig 和节点确认只适用于显式 D601 legacy 事故回放，不能作为当前 G14 DEV/v0.2 hotfix 控制面。本 runbook 的审计脚本不执行这些写操作。回滚后再次运行 `scripts/dev-runtime-hotfix-audit.mjs --collect-readonly`，期望分类包含 `no-hotfix-detected`，且不包含 `deployment-mounts-hotfix`、`pod-loads-hotfix-marker` 或 `rollback-required`。 +直接 `kubectl patch`、`kubectl delete configmap`、`kubectl rollout status` 或等价写操作必须由明确授权的操作者执行，并且当前 node/lane 运行面必须通过对应 UniDesk route 操作，例如 `D601:k3s` 或 `G14:k3s`。D601 legacy 节点确认只适用于显式旧路径事故回放，不能替代当前 node/lane hotfix 控制面。本 runbook 的审计脚本不执行这些写操作。回滚后再次运行 `scripts/dev-runtime-hotfix-audit.mjs --collect-readonly`，期望分类包含 `no-hotfix-detected`，且不包含 `deployment-mounts-hotfix`、`pod-loads-hotfix-marker` 或 `rollback-required`。 ## 禁止误用 diff --git a/docs/reference/documentation-governance.md b/docs/reference/documentation-governance.md index cac6f2a1..1e5075fa 100644 --- a/docs/reference/documentation-governance.md +++ b/docs/reference/documentation-governance.md @@ -57,7 +57,7 @@ - `#122` 要求用户和参谋反馈默认高优先级并挂到 `#7`。 - `#123` 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill；本文就是该规则的等价本地文档。 - `#532` 是 `v0.2` 文档治理规格和被删除根文档/过程文档的全文归档入口；当前收敛规格见 [spec-v02-documentation-governance.md](spec-v02-documentation-governance.md)。 -- 当前 HWLAB 的 G14 DEV `17666/17667`、G14 PROD `18666/18667`、G14 工作区、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 维护；D601 只作为 legacy 迁移/事故回放口径维护。 +- 当前 HWLAB 的 node/lane 工作区、运行面入口、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 与受控 lane 配置维护；D601 legacy 只指旧 DEV/CD、迁移对照和事故回放路径，D601 v0.3 这类 issue/CLI 明确的 node-scoped runtime lane 不属于 legacy。 ## docs-spec 原文副本 diff --git a/docs/reference/gateway-outbound-demo.md b/docs/reference/gateway-outbound-demo.md index a83fe337..4603001a 100644 --- a/docs/reference/gateway-outbound-demo.md +++ b/docs/reference/gateway-outbound-demo.md @@ -31,7 +31,7 @@ Gateway 必须在 registration payload 和 `/v1/gateway/sessions` 中暴露 `inf | 变量 | 作用 | | --- | --- | -| `HWLAB_GATEWAY_CLOUD_URL` | cloud-api 或 edge-proxy 地址；本地可用 `http://127.0.0.1:6667`，当前 G14 DEV 可用 `http://74.48.78.17:17667`。 | +| `HWLAB_GATEWAY_CLOUD_URL` | cloud-api 或 edge-proxy 地址；本地可用 `http://127.0.0.1:6667`，目标运行面使用当前 issue/CLI node + lane 的 API/edge URL。 | | `HWLAB_GATEWAY_ID` | gateway 稳定身份，例如 `gtw_windows_1`。 | | `HWLAB_GATEWAY_SESSION_ID` | gateway session id；不填时默认为 `gws_${HWLAB_GATEWAY_ID}`。 | | `HWLAB_GATEWAY_CMD_EXEC_ENABLED=1` | 允许执行 shell 命令；未设置时 gateway 拒绝 `hardware.invoke.shell`。 | @@ -60,14 +60,14 @@ npm run gateway:demo:edge-smoke - `gateway:demo:smoke` 启动本地 `hwlab-cloud-api` 和 `hwlab-gateway`，验证 `hardware.invoke.shell` 返回 `stdout=hwlab-demo`。 - `gateway:demo:edge-smoke` 额外启动本地 `hwlab-edge-proxy`，验证普通 HTTP proxy 能转发 `/v1/gateway/poll`、`/v1/gateway/result` 和 `/json-rpc`。 - 两个 smoke 都会设置 `NO_PROXY/no_proxy`，用于规避本地代理误触发。 -- 对 G14 pod 内部 `127.0.0.1:6667` 或 service `:6667` 做 Node 探测时，不要用 Web/undici `fetch`；`6667` 属于 WHATWG bad port，Node 会直接报 `bad port`。gateway 传输层和 repo-owned 探测脚本应使用 `http/https` 原生 request，公网 `:17667` 或浏览器入口不受这个限制。 +- 对目标 pod 内部 `127.0.0.1:6667` 或 service `:6667` 做 Node 探测时，不要用 Web/undici `fetch`；`6667` 属于 WHATWG bad port，Node 会直接报 `bad port`。gateway 传输层和 repo-owned 探测脚本应使用 `http/https` 原生 request，或改走当前 target API/browser 入口。 ## DEV 使用 DEV cloud-api 部署包含 `/v1/gateway/*` 后，Windows gateway 可用以下方式主动连接： ```powershell -$env:HWLAB_GATEWAY_CLOUD_URL="http://74.48.78.17:17667" +$env:HWLAB_GATEWAY_CLOUD_URL="" $env:HWLAB_GATEWAY_ID="gtw_windows_1" $env:HWLAB_GATEWAY_SESSION_ID="gws_gtw_windows_1" $env:HWLAB_GATEWAY_CMD_EXEC_ENABLED="1" diff --git a/docs/reference/m3-loop-rollout-runbook.md b/docs/reference/m3-loop-rollout-runbook.md index ceaa3932..2c0a2b60 100644 --- a/docs/reference/m3-loop-rollout-runbook.md +++ b/docs/reference/m3-loop-rollout-runbook.md @@ -10,11 +10,11 @@ restart, or heavyweight e2e run. ## M3 Loop Boundary -M3 is a DEV-only trusted-loop acceptance path, not a generic deployment or -front-end acceptance path. +M3 is a target-runtime trusted-loop acceptance path, not a generic deployment or +front-end acceptance path. The target Web/API boundary must come from the current issue/CLI node + lane status. -- Public frontend boundary: `http://74.48.78.17:17666/`. -- Public API/edge boundary: `http://74.48.78.17:17667/`. +- Public frontend boundary: current target Web URL. +- Public API/edge boundary: current target API URL. - Historical public `:6666` and `:6667` endpoints are not current acceptance targets; internal k3s services may still use `6667`. - Runtime intent and artifact identity are reviewed through @@ -82,7 +82,7 @@ wiring are all observed. | Step | What to observe | Must have evidence | Failure class | Must not misread | | --- | --- | --- | --- | --- | -| 1 | Confirm the public DEV boundary and frozen route. | `http://74.48.78.17:17666` for frontend, `http://74.48.78.17:17667` for API/edge, internal `6667` only as a k3s port, and the checked-in docs or checklist that freeze those values. | `environment_blocker` | Do not treat legacy `:16666/:16667`, legacy `:6666`, or public `:6667` as acceptance targets. | +| 1 | Confirm the public target boundary and frozen route. | Current target Web URL for frontend, current target API URL for API/edge, internal `6667` only as a k3s port, and the checked-in docs or checklist that freeze those values. | `environment_blocker` | Do not treat legacy `:16666/:16667`, legacy `:6666`, public `:6667`, G14 DEV, v0.2, or another lane as the current acceptance target. | | 2 | Confirm two box simulators and two gateway simulators are present and distinct. | Two observable `hwlab-box-simu` identities, two observable `hwlab-gateway-simu` identities, their resource/session IDs, and the shared DEV project. | `runtime_blocker` | Do not infer cardinality from one box, one gateway, or fixture-only output. | | 3 | Confirm one patch panel owns the route. | `hwlab-patch-panel` status, wiring, and the active connection from `res_boxsimu_1:DO1` to `res_boxsimu_2:DI1`. | `runtime_blocker` | Do not accept box loopback, direct box mutation, or a UI state edit as routing proof. | | 4 | Confirm the live loop operation. | Operation ID, trace ID, audit ID, and evidence ID tied to `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1`. | `runtime_blocker` | Do not promote SOURCE, LOCAL, DRY-RUN, or edge-only evidence to PASS. | diff --git a/docs/reference/node-gitops-cicd.md b/docs/reference/node-gitops-cicd.md index c721817e..27c3feb7 100644 --- a/docs/reference/node-gitops-cicd.md +++ b/docs/reference/node-gitops-cicd.md @@ -1,47 +1,47 @@ -# G14 GitOps CI/CD +# Node GitOps CI/CD -G14 是 HWLAB 当前 DEV/PROD 原生 k8s 与 GitOps 运行面目标。G14 CI/CD 必须只作用于 G14 k3s，不接管 D601 legacy 运行面，不使用 UniDesk Code Queue 作为调度器，也不把 UniDesk backend、provider-gateway 或 microservice proxy 当作 HWLAB runtime。 +HWLAB CI/CD 运行面目标必须由当前 issue、PR、CLI 参数或受控 lane 配置解析为明确的 node + lane。CI/CD 只能作用于该 node 的 k3s 和该 lane 的 GitOps/namespace，不接管其他 node/lane，不使用 UniDesk Code Queue 作为调度器，也不把 UniDesk backend、provider-gateway 或 microservice proxy 当作 HWLAB runtime。G14 DEV/PROD、G14 v0.2 和 D601 v0.3 都只是 node/lane 实例；D601 legacy 只指旧 DEV/CD 回放路径。 ## 目标模型 - Source of truth：业务版本以 Git source commit 为唯一身份；镜像 tag、OCI labels、runtime annotation 和 Argo CD desired state 都必须记录同一个 source commit。 -- CI：Tekton 在 G14 k3s 内运行 `hwlab-node-ci-image-publish` Pipeline，由 `scripts/gitops-render.mjs` 直接生成原生 task；最小校验固定为 `repo-reports-guard`、`node-contract-check`、`codex-api-forwarder-check`，随后按 component plan 做 per-service BuildKit publish 与 GitOps promote；没有 `CI.json` runner、DIND 单任务发布或 Docker fallback。 -- Artifact：镜像使用 commit tag，例如 `127.0.0.1:5000/hwlab/hwlab-cloud-api:`；digest 由 registry 返回，CI report 只作为审计证据，不作为 CD 真相。发布态 artifact catalog 由 Tekton 写入 `G14-gitops:deploy/artifact-catalog.dev.json`。 -- Branch split：`G14` 是源码监控分支，只保存人写源码、声明和 seed contract；`G14-gitops` 是 Tekton promotion 写入的生成分支，保存 `deploy/artifact-catalog.dev.json` 与 `deploy/gitops/node/**` desired state。CI/CD 不再把 catalog promotion commit 写回 `G14`。 -- v0.2 扩容线：`v0.2` 必须从当前 `G14` fork 出来，并以 `G14:/root/hwlab-v02` 作为固定开发 workspace、`G14:/root/hwlab-v02-cicd.git` 作为固定 CI/CD source repo、`hwlab-v02` 作为固定 runtime namespace。`v0.2` CI/CD 只能作为新增 lane 接入现有 G14 Tekton/Argo 体系，不得改写、删除、暂停或重定向现有 `G14` poller、`G14-gitops` DEV/PROD desired state、`hwlab-dev` 或 `hwlab-prod`；详细规格见 [spec-v02-cicd.md](spec-v02-cicd.md)。 -- CD：Argo CD 只消费 `G14-gitops:deploy/gitops/node/runtime-dev` 与 `deploy/gitops/node/runtime-prod` 的 Git desired state，不重新构建镜像，不读取 D601 状态，不获取 legacy DEV CD Lease。 -- FRP：G14 DEV 通过 `hwlab-dev/hwlab-node-frpc` 暴露 `17666/17667`，G14 PROD 通过 `hwlab-prod/hwlab-node-prod-frpc` 暴露 `18666/18667`；`v0.2` 规划通过 `hwlab-v02` 内独立 frpc 暴露 `19666/19667`。master frps 的 `deploy/frp/frps.dev.toml` 与实际 `/etc/frp/frps.toml` 必须放行对应端口，但 `v0.2` 放行只能新增 19xxx 入口，不能复用或覆盖 DEV/PROD 入口。 +- CI：Tekton 在目标 node k3s 内运行 lane 对应 Pipeline，由 `scripts/gitops-render.mjs` 或 node/lane control-plane 直接生成原生 task；最小校验固定为当前 lane 需要的原语，随后按 component plan 做 per-service BuildKit publish 与 GitOps promote；没有 `CI.json` runner、DIND 单任务发布或 Docker fallback。 +- Artifact：镜像使用 commit tag，例如 `/hwlab-cloud-api:`；digest 由 registry 返回，CI report 只作为审计证据，不作为 CD 真相。发布态 artifact catalog 由 Tekton 写入当前 lane 的 GitOps branch。 +- Branch split：source branch 只保存人写源码、声明和 seed contract；GitOps branch 是 Tekton promotion 写入的生成分支，保存 artifact catalog 与 `deploy/gitops/node/**` desired state。CI/CD 不再把 catalog promotion commit 写回 source branch。 +- v0.2 扩容线：G14 v0.2 的固定 workspace、CI/CD source repo、runtime namespace 和 GitOps branch 只适用于当前任务明确选择 G14 v0.2 时；详细规格见 [spec-v02-cicd.md](spec-v02-cicd.md)。不得把 G14 v0.2 默认带入 D601 v0.3 或其他 lane。 +- CD：Argo CD 只消费当前 node/lane Git desired state，不重新构建镜像，不读取其他 node 状态，不获取 legacy DEV CD Lease。 +- FRP：公网暴露端口和 HTTPS host 必须由当前 node/lane control-plane status 或 lane 配置确认。G14 DEV/PROD、G14 v0.2 和 D601 v0.3 的入口都是示例实例，不得互相替代验收证据。 - 并行性：不同 source commit 的 CI build 不共享发布锁；并行安全由 immutable commit tag/digest 和 Git desired state 保证。最终运行版本由 Argo CD 当前同步的 Git revision 决定。 ## 门禁最小化与扩容治理 -不要滑向不必要的复杂门禁是 HWLAB G14 CI/CD 和 `v0.2` 扩容的通用原则。架构迁移、分支扩容和运行面治理应优先靠固定边界、清晰命名、唯一真相源、标准入口和长期参考文档收敛；不要把每个设计约定、运行策略、观测项或回滚手册都做成新的 preflight、guard、gate 或报告生成器。 +不要滑向不必要的复杂门禁是 HWLAB node/lane CI/CD 和 lane 扩容的通用原则。架构迁移、分支扩容和运行面治理应优先靠固定边界、清晰命名、唯一真相源、标准入口和长期参考文档收敛；不要把每个设计约定、运行策略、观测项或回滚手册都做成新的 preflight、guard、gate 或报告生成器。 -旧 DEV/D601/main 门禁如果阻碍当前 G14 或 `v0.2` 路径，默认处理是从当前调用链删除，而不是做兼容性迁移、fallback、legacy mode、双路径绕行或在旧门禁上叠加例外。新增门禁只能覆盖明确高价值风险，且必须最小、低噪声、容易删除；资源配额、RBAC 命名、清理策略、回滚顺序、人工同步策略等默认是设计约定或 runbook，不是 CI/CD 通过条件。 +旧 DEV/D601/main 门禁如果阻碍当前 node/lane 路径，默认处理是从当前调用链删除，而不是做兼容性迁移、fallback、legacy mode、双路径绕行或在旧门禁上叠加例外。新增门禁只能覆盖明确高价值风险，且必须最小、低噪声、容易删除；资源配额、RBAC 命名、清理策略、回滚顺序、人工同步策略等默认是设计约定或 runbook，不是 CI/CD 通过条件。 `v0.2` 的硬边界只包括：source branch 必须是 `v0.2`，CI/CD source repo 必须是 `/root/hwlab-v02-cicd.git`，GitOps branch 必须是 `v0.2-gitops`，Git mirror/relay 必须来自 `devops-infra`，runtime namespace 必须是 `hwlab-v02`，runtime path 必须是 `deploy/gitops/node/runtime-v02`，Argo Application 必须指向 `v0.2` GitOps lane，公网入口只能是 `19666/19667`，`v0.2` source branch 不跟踪生成物，旧 DEV/D601/main 门禁不进入 `v0.2` 调用链。其他事项先写成决策表或 runbook；只有被证明无法靠上述边界和标准入口自然收敛时，才允许新增最小检查。 ## 生成入口 -`scripts/gitops-render.mjs` 是 G14 专用转换器： +`scripts/gitops-render.mjs` 是 node/lane GitOps 转换器；G14 相关默认只在目标 lane 明确选择 G14 时使用： - 架构迁移时，过时的自检、预检、guard、gate 优先删除，不在旧门禁上叠加例外或复杂度；新门禁只允许覆盖明确高价值风险，必须保持最小、低噪声、易迁移。 - 直接声明 Tekton Pipeline、最小原语校验 task 和 PipelineRun 样板；不再读取 `CI.json` 或生成 `ci-json` step。 -- 读取 `deploy/deploy.yaml` 与 `deploy/k8s/*`，生成 Argo CD 可消费的 G14 runtime Kustomize path。 -- G14 Tekton 的镜像构建发布入口必须是 `scripts/artifact-publish.mjs`；它只是集群内 Task 的 build/push helper，不做 rollout、不写 D601、不获取 legacy DEV CD Lease。旧 `scripts/dev-artifact-publish.mjs` 入口已删除；`dev-cd-apply`、`ci-publish` 和旧 `main` JS CD 入口禁止出现在 G14 Pipeline 生成脚本和 G14 验收证据中。 +- 读取 `deploy/deploy.yaml` 与 `deploy/k8s/*`，生成 Argo CD 可消费的目标 node/lane runtime Kustomize path。 +- Tekton 的镜像构建发布入口必须是 `scripts/artifact-publish.mjs`；它只是集群内 Task 的 build/push helper，不做 rollout、不写其他 node、不获取 legacy DEV CD Lease。旧 `scripts/dev-artifact-publish.mjs` 入口已删除；`dev-cd-apply`、`ci-publish` 和旧 `main` JS CD 入口禁止出现在当前 node/lane Pipeline 生成脚本和验收证据中。 - `node-contract-check` 在 fresh source clone 内取当前 `HEAD`，把 GitOps 产物渲染到 `mktemp -d` 临时目录，并立刻用同一个 `--source-revision` 执行 `--check`；它校验 render 代码、原生 Tekton 产物生成合同和 forbidden-fragment 护栏，不依赖 source branch 预先存在 `deploy/gitops/node/source.json`。面向已发布 runtime 的 `source.json` 只存在于 `G14-gitops` 生成分支，作为 promotion evidence。 - 生成 `hwlab-node-branch-poller` CronJob：它使用 G14 集群内的 Git SSH Secret 轮询 `G14` 分支，按 source commit 创建确定命名的 Tekton PipelineRun。 -- 生成 `hwlab-node-control-plane-reconciler` CronJob：它使用同一个 Git SSH Secret 轮询 `G14`，运行 repo 内 `scripts/gitops-render.mjs`，并 server-side apply 生成的 Tekton RBAC、Pipeline、Poller 和 Reconciler manifests；因此 CI 控制面变化应自动进入 G14 k3s，不需要人工长期执行 render/apply。 +- 生成 node/lane control-plane reconciler：它使用对应 Git SSH Secret 轮询目标 source branch，运行 repo 内 `scripts/gitops-render.mjs`，并 server-side apply 生成的 Tekton RBAC、Pipeline、Poller 和 Reconciler manifests；因此 CI 控制面变化应自动进入目标 node k3s，不需要人工长期执行 render/apply。 - 默认输出到 `deploy/gitops/node/`。 -- 默认 GitOps 生成分支是 `G14-gitops`；Pipeline 成功后把本次 source commit 对应的 `deploy/artifact-catalog.dev.json` 与 `deploy/gitops/node/**` 推送到该分支，避免把生成提交继续写回 `G14`。 +- GitOps 生成分支由当前 node/lane 配置决定；Pipeline 成功后把本次 source commit 对应的 artifact catalog 与 `deploy/gitops/node/**` 推送到该 lane 的 GitOps 分支，避免把生成提交继续写回 source branch。 - `v0.2` GitOps lane 必须使用独立生成身份，例如 `v0.2-gitops`、`deploy/artifact-catalog.v02.json` 和 `deploy/gitops/node/runtime-v02`，并由独立 Argo CD Application 指向 `hwlab-v02`。若后续实现选择复用某个脚本入口，也必须通过显式参数区分 source branch、catalog、runtime path、Application 和 namespace，不能靠修改默认值让 `G14` DEV/PROD 行为漂移。 -- 默认 registry prefix 是 `127.0.0.1:5000/hwlab`，用于 G14 单节点 k3s 的 node-local registry。 -- 默认 CI/CD proxy 是 G14 本机 `http://127.0.0.1:10808` / `socks5h://127.0.0.1:10808`。Tekton CI step、BuildKit sidecar 和 publish step 都注入 proxy/no_proxy；服务镜像构建只允许通过 Pod 内 BuildKit Unix socket 直接 push 到 G14 本地 registry，不能回退到 Docker daemon、DIND 或 host Docker。 -- `prepare-source` 和最小原语校验 task 不允许每次运行时重新 `apk add`、`apt-get install` 或临时下载 browser/runtime 依赖。当前固定工具镜像是 `127.0.0.1:5000/hwlab/hwlab-ci-node-tools:node22-alpine-bun-v1`，包含 Node 22、npm、Bun、Git、OpenSSH、curl、Python3 和 Docker CLI。镜像内容由 `deploy/ci/hwlab-ci-node-tools.Dockerfile` 声明；脚本启动时必须输出工具与 proxy preflight 结构化日志。缺少工具时应先在 G14 构建并推送新的工具镜像，再修改 `HWLAB_NODE_CI_TOOLS_IMAGE`/render 默认值，不能回退到 runtime 安装。 -- G14 host 只用于 source workspace、GitOps render、k3s 控制和轻量语法/静态合同检查；不要把 host 当成浏览器执行面。低频 browser smoke 已不再属于默认 primitive CI。若确实需要一次性布局、移动端或交互验证，必须显式在 G14 k3s/Tekton 的专用 Playwright 镜像内运行，不能回退成 host 上强装 browser 的长期方案。 -- Poller、control-plane reconciler、image publish 和 GitOps promote step 都不允许每次运行时 `apk add` / `apt-get install`。当前 G14 registry 固定工具镜像是 `127.0.0.1:5000/hwlab/hwlab-ci-node-tools:node22-alpine-bun-v1`，包含 Node 22、npm、Bun、Git、OpenSSH、curl、Python3 和 Docker CLI；生成的脚本只做 proxy preflight 与工具存在性检查。若需要升级工具，先在 G14 构建/推送新的工具镜像，再修改 `HWLAB_NODE_CI_TOOLS_IMAGE`/render 默认值并由 reconciler apply。 -- 服务镜像构建的默认 parent/base image 不得从 Docker Hub 反复拉取。当前 `node:20-bookworm-slim` 已镜像到 G14 registry 的 allowlist 名称：`127.0.0.1:5000/hwlab/hwlab-node20-base:20-bookworm-slim`，render 默认 `base-image` 和 poller `BASE_IMAGE` 都指向这个本地镜像。需要升级 parent image 时，先通过 G14 proxy 拉取并推送到 G14 registry，再修改 `HWLAB_NODE_DEV_BASE_IMAGE`/render 默认值；image publish step 只允许从本地 registry pull base image，且 tag 必须符合 publish gate 的 `hwlab-node20-base`/`hwlab-dev-base`/`hwlab-node-runtime-base` allowlist。 +- Registry prefix 由当前 node/lane 配置决定；G14 单节点 k3s 的 node-local registry 示例是 `127.0.0.1:5000/hwlab`。 +- CI/CD proxy 由当前 node bootstrap 和 lane 配置决定；G14 本机示例是 `http://127.0.0.1:10808` / `socks5h://127.0.0.1:10808`。Tekton CI step、BuildKit sidecar 和 publish step 都注入 proxy/no_proxy；服务镜像构建只允许通过 Pod 内 BuildKit Unix socket 直接 push 到目标 registry，不能回退到 Docker daemon、DIND 或 host Docker。 +- `prepare-source` 和最小原语校验 task 不允许每次运行时重新 `apk add`、`apt-get install` 或临时下载 browser/runtime 依赖。工具镜像由当前 node/lane 配置解析，G14 示例为 `127.0.0.1:5000/hwlab/hwlab-ci-node-tools:node22-alpine-bun-v1`。镜像内容由 `deploy/ci/hwlab-ci-node-tools.Dockerfile` 声明；脚本启动时必须输出工具与 proxy preflight 结构化日志。缺少工具时应先在目标 node 构建并推送新的工具镜像，再修改 `HWLAB_NODE_CI_TOOLS_IMAGE`/render 默认值，不能回退到 runtime 安装。 +- 目标 node host 只用于 source workspace、GitOps render、k3s 控制和轻量语法/静态合同检查；不要把 host 当成浏览器执行面。低频 browser smoke 已不再属于默认 primitive CI。若确实需要一次性布局、移动端或交互验证，必须显式在目标 node/k3s/Tekton 的专用 Playwright 镜像或 UniDesk `trans playwright` 透传内运行，不能回退成 host 上强装 browser 的长期方案。 +- Poller、control-plane reconciler、image publish 和 GitOps promote step 都不允许每次运行时 `apk add` / `apt-get install`。当前 node/lane 固定工具镜像必须来自配置，生成的脚本只做 proxy preflight 与工具存在性检查。若需要升级工具，先在目标 node 构建/推送新的工具镜像，再修改 `HWLAB_NODE_CI_TOOLS_IMAGE`/render 默认值并由 reconciler apply。 +- 服务镜像构建的默认 parent/base image 不得从 Docker Hub 反复拉取。parent/base image 必须镜像到目标 node/lane registry 并由配置引用；G14 示例为 `127.0.0.1:5000/hwlab/hwlab-node20-base:20-bookworm-slim`。需要升级 parent image 时，先通过目标 node proxy 拉取并推送到目标 registry，再修改 `HWLAB_NODE_DEV_BASE_IMAGE`/render 默认值；image publish step 只允许从本地 registry pull base image，且 tag 必须符合 publish gate 的 allowlist。 - 任何依赖下载阶段都必须有可观测诊断。生成的 Tekton 脚本在 npm、BuildKit base image/local registry probe 和 GitOps promote 之前输出结构化 `dependency-proxy-probe`、`dependency-curl-probe` 或 `dependency-download-*` 日志，至少包含 phase、目标 URL/镜像、脱敏 proxy、首包耗时、总耗时、下载字节数和速度。CI/CD 卡在下载时，先用这些日志判断是 proxy 不可达、目标源慢、DNS/首包慢还是下载吞吐低，再决定是否切换 G14 代理节点或预热镜像；不能只凭 PipelineRun Running 时长判断业务测试失败。 常用命令： @@ -76,15 +76,15 @@ npm run gitops:render -- --source-revision HWLAB 是 monorepo，G14 CI/CD 加速必须按组件输入判断构建和滚动；v0.2 env-reuse 的组件边界与环境配方直接来自 `deploy/deploy.yaml`，运行态镜像身份来自 per-service artifact catalog；`CI.json` 已删除，不再作为任何 planner 输入。 - `deploy/deploy.yaml` 是当前 v0.2 人写 deploy/runtime 配置单一出处；`deploy/deploy.json` 不得作为 v0.2 兼容源恢复。配置读写由 `scripts/src/structured-config.mjs` 和 `scripts/src/deploy-config.mjs` 统一承载，只有该格式无关层直接处理 YAML/JSON 解析；planner、renderer、smoke、artifact helper 和 CLI 只调用读写 helper。 -- `scripts/ci-plan.mjs` 是只读 planner，默认读取当前 workspace 的 `deploy/deploy.yaml`、`deploy/artifact-catalog.dev.json`，以及 `deploy/deploy.yaml` 内的 lane service declarations/env recipe，输出 `affectedServices`、`reusedServices`、`componentCommitId`、`componentInputHash`、`dockerfileHash`、`baseImageDigest`、`buildArgsHash` 和原因；它不得修改 deploy、catalog 或 GitOps 文件。Tekton `prepare-source` 会先从 `G14-gitops` 注入上一轮发布态 catalog，source 分支里的 catalog 只作为 seed contract。 +- `scripts/ci-plan.mjs` 是只读 planner，默认读取当前 workspace 的 `deploy/deploy.yaml`、lane artifact catalog，以及 `deploy/deploy.yaml` 内的 lane service declarations/env recipe，输出 `affectedServices`、`reusedServices`、`componentCommitId`、`componentInputHash`、`dockerfileHash`、`baseImageDigest`、`buildArgsHash` 和原因；它不得修改 deploy、catalog 或 GitOps 文件。Tekton `prepare-source` 会先从当前 lane GitOps branch 注入上一轮发布态 catalog，source 分支里的 catalog 只作为 seed contract。 - v0.2 服务清单来自显式 `--services` 或 `deploy.lanes.v02.envReuseServices`；旧 `deploy.services[]`、`deploy.k3s.serviceMappings[]` 和 `internal/protocol.SERVICE_IDS` 推导路径不再作为 planner 输入。 - v0.2 env-reuse 组件边界和环境镜像配方以 `deploy/deploy.yaml` 的 `lanes.v02.serviceDeclarations`、`lanes.v02.envRecipe` 和 `lanes.v02.bootConfig` 为单一配置点；新增服务或调整 `componentPaths`、`runtimeKind`、`entrypoint`、Bun 版本、系统包、launcher 路径和 HWPOD alias 时先改 deploy 配置与 schema/测试，不再把这些属性硬编码进 planner 或 artifact publish helper。 - `hwpod` 是 runner 内的稳定 HWPOD task 入口，由 `tools/hwpod-cli.ts`、`tools/hwpod-compiler-cli.ts`、`tools/hwpod-ctl.ts`、`tools/hwpod-node.ts` 和 `skills/hwpod-cli/`、`skills/hwpod-ctl/` 组成。修改这些路径时，G14/v0.2 CI 必须至少触发携带 `/usr/local/bin/hwpod` 的 runtime skills/env-reuse 重新装配或 rollout，不能全量复用旧 artifact 后只报告 PipelineRun 成功。 - `scripts/artifact-publish.mjs` 默认启用组件级 lazy build：先运行 planner，再只构建/推送 `affectedServices`，`reusedServices` 从 `deploy/artifact-catalog.dev.json` 或 lane catalog 复用已有 sha256 digest。非 env-reuse 服务复用前必须满足 artifact provenance 自证：catalog 有可验证 digest、catalog 的 `sourceCommitId` 在当前 repo 可解析、用该 `sourceCommitId` 的 source tree 重新计算出的 `componentInputHash` 等于 catalog 记录、该 hash 再等于本轮 planner 计算值，且 `dockerfileHash`/`buildArgsHash` 没有不一致。catalog 缺 digest、缺 provenance、source tree 无法解析、catalog hash 与 catalog source tree 不一致、或 catalog hash 与本轮 input 不一致时，planner 必须把该服务列为 affected 并重新发布，不能用旧 guard 阻塞，也不能退回 Docker 或 legacy full-build 路线。 - Artifact catalog 的 per-service provenance 是镜像 digest 的身份证明，不是本轮 planner 状态缓存。reuse 路径只能保留旧 artifact 自身的 `sourceCommitId`、`componentCommitId`、`componentInputHash`、`dockerfileHash`、`baseImage*` 和 `buildArgsHash`；禁止把当前 planner 的 component/build 元数据写入复用的旧 digest，否则下一轮 planner 会把旧镜像误判成已包含新输入，造成 CI/CD false-green。 -- `scripts/artifact-publish.mjs` 的 publish report 必须携带 planner 的 per-service 元数据；`scripts/refresh-artifact-catalog.mjs` 默认只预览，只有 G14 Tekton promotion 显式传 `--write` 时，才把生成的 `commitId`、`image`、`imageTag`、`digest`、`publishState` 和 component provenance 字段写进当前 workspace 的 `deploy/artifact-catalog.dev.json`，随后只提交到 `G14-gitops`。`deploy/deploy.yaml` 是人写的 runtime config 真相源，不得被 promotion、refresh 脚本或人工发布流程回写镜像身份字段。 +- `scripts/artifact-publish.mjs` 的 publish report 必须携带 planner 的 per-service 元数据；`scripts/refresh-artifact-catalog.mjs` 默认只预览，只有当前 lane Tekton promotion 显式传 `--write` 时，才把生成的 `commitId`、`image`、`imageTag`、`digest`、`publishState` 和 component provenance 字段写进当前 lane artifact catalog，随后只提交到当前 lane GitOps branch。`deploy/deploy.yaml` 是人写的 runtime config 真相源，不得被 promotion、refresh 脚本或人工发布流程回写镜像身份字段。 - `scripts/gitops-render.mjs` 只支持混合 desired state：workload 的 container image、`HWLAB_IMAGE`、`HWLAB_IMAGE_TAG` 和 pod template `source-commit` 来自 `deploy/artifact-catalog.dev.json` 的 per-service artifact identity；普通 env、replica、healthPath、profile 等配置来自 `deploy/deploy.yaml`。全局 GitOps metadata 仍记录本次 source commit。`--legacy-source-images` 与 `HWLAB_NODE_USE_DEPLOY_IMAGES=0` 已废弃，不得把所有 workload image 回退渲染为同一个 source commit tag。 -- G14 Tekton promotion 在推送 `G14-gitops` 前，必须用 publish report 显式 `--write` 刷新 workspace 内的 `deploy/artifact-catalog.dev.json`，然后把刷新后的 catalog 和 rendered GitOps desired state 一起提交到 `G14-gitops`。promotion 不得自动修改或推送 `G14` source branch，也不得自动修改 `deploy/deploy.yaml` 或 `deploy/k8s/base/workloads.yaml`，这样人写配置不会和 CI 生成身份反复冲突。 +- 当前 lane Tekton promotion 在推送 GitOps branch 前，必须用 publish report 显式 `--write` 刷新 lane artifact catalog，然后把刷新后的 catalog 和 rendered GitOps desired state 一起提交到当前 lane GitOps branch。promotion 不得自动修改或推送 source branch，也不得自动修改 `deploy/deploy.yaml` 或 `deploy/k8s/base/workloads.yaml`，这样人写配置不会和 CI 生成身份反复冲突。 - Tekton 并发化只能以 planner 输出作为输入；每个 service 都有独立 TaskRun，changed service 启动 BuildKit，unchanged service 只写 reuse result 并复用 catalog digest，且不能改 pod template，避免无意义 rollout。没有完整 per-service desired state 证据时，必须修复 planner/catalog 证据，不能使用 `--full-build`、`--legacy-source-images`、DIND 或 Docker fallback 回退。 ## 加速判定与当前瓶颈 @@ -116,13 +116,13 @@ G14/v0.2 Code Agent 执行委托给 AgentRun `v0.1`。Per-profile config、crede 当前 profile 示例不是静态枚举：`deepseek` 通过集群内 DeepSeek Responses bridge/Moon Bridge，`dsflash-go` 等动态 slug 由 AgentRun profile config/SecretRef 承接，`codex-api` 使用同 Pod loopback forwarder 直连 hyueapi，`minimax-m3` 由 AgentRun `backendProfile=minimax-m3` 承接。HWLAB 对外的 conversation/session/thread 合同不随 AgentRun backend 切换而改变；adapter 内部传给 AgentRun 的 `sessionRef.sessionId` 必须按 `backendProfile` 分域，`accessController` 持久化记录仍以 HWLAB 原始 session 归属为准，嵌套 `agentRun.sessionId` 保存 AgentRun scoped sessionRef。G14 cloud-api 的 `NO_PROXY/no_proxy` 必须包含 `hyueapi.com` 和 `.hyueapi.com`；`codex-api` 的 hyueapi upstream 由同 Pod loopback forwarder 直连，不能被 proxy 注入污染。 -G14 `codex-api` 不得把 `http://172.26.26.227:17680/v1/responses` 作为默认 base URL；该地址只保留为 D601 legacy Code Queue runner 或历史 egress 对照线索。G14 上的 `codex-api` 应先进入同 Pod `127.0.0.1` loopback forwarder，再由 forwarder 直连 `hyueapi.com` / `.hyueapi.com`；这两个域名必须同时进入 `NO_PROXY` 和 `no_proxy`。DeepSeek profile 可以通过集群内 bridge/Moon Bridge 转换，`codex-api` 不能用 DeepSeek bridge 伪装通过，也不能因为默认 profile 切到 DeepSeek 而删除或覆盖 `codex-api` 的独立模型、base URL、auth 和最小闭环验证。 +当前 node/lane 的 `codex-api` 不得把 `http://172.26.26.227:17680/v1/responses` 作为默认 base URL；该地址只保留为旧 D601 Code Queue runner 或历史 egress 对照线索。`codex-api` 应先进入同 Pod `127.0.0.1` loopback forwarder，再由 forwarder 直连 `hyueapi.com` / `.hyueapi.com`；这两个域名必须同时进入 `NO_PROXY` 和 `no_proxy`。DeepSeek profile 可以通过集群内 bridge/Moon Bridge 转换，`codex-api` 不能用 DeepSeek bridge 伪装通过，也不能因为默认 profile 切到 DeepSeek 而删除或覆盖 `codex-api` 的独立模型、base URL、auth 和最小闭环验证。 共享 bridge/forwarder/runtime 变更必须按 [Code Agent Chat Readiness Runbook](code-agent-chat-readiness.md) 的分层方法先做目标 pod 最小闭环。普通 AgentRun profile config/credential/validate 走 [spec-v02-provider-management.md](spec-v02-provider-management.md)，不通过 GitOps render 或服务发布试错。裸 HTTP/SSE 请求通过只能证明 upstream、认证和模型可用；没有 AgentRun command result `completed` + 非空 reply 前，不得把 Workbench 状态标成 DEV-LIVE reply pass。 Codex app-server 当前要求 provider `wire_api="responses"`，不得把 DeepSeek profile 切到旧 `chat` wire API。DeepSeek profile 的真实 Responses 转换层固定使用 Moon Bridge；不要在 HWLAB 里手写完整 Responses-to-Chat/Anthropic 转换器，因为这会破坏 Moon Bridge 对 prompt cache、tool-result 顺序和模型目录的成熟处理。Codex 发往 `/v1/responses` 的请求体可能带 `Content-Encoding: zstd`，而 Moon Bridge 不负责解压 Codex zstd body。因此 GitOps 中的 `hwlab-deepseek-proxy` Pod 必须包含 repo-owned `hwlab-deepseek-responses-bridge` sidecar：Service 端口 4000 指向 bridge，bridge 只做 zstd request body 解压、删除 `Content-Encoding`/重写 `Content-Length`、丢弃非 `function` tool 类型和 Codex-style `GET /v1/models` 目录适配，再把请求转发给 4001 的 Moon Bridge。DeepSeek API 只接受 `function` tools，bridge 必须在转发前丢弃 Codex Responses 请求里的非 `function` tool 类型（例如 `web_search`、`image_generation`），但不得移除 shell/apply-patch 等 function tools。模型、cache、tool 调用顺序、密钥和真实推理仍由 Moon Bridge 管理；bridge 不新增业务 gate，也不得把兼容失败伪装成 SOURCE/legacy blocker。 -DeepSeek proxy manifest 是 GitOps desired state 的一部分，DEV/PROD 分别生成在 `runtime-dev/deepseek-proxy.yaml` 和 `runtime-prod/deepseek-proxy.yaml`。Moon Bridge 镜像由 `deploy/moonbridge/Dockerfile` 从上游 `ZhiYi-R/moon-bridge` 固定 commit 构建，默认镜像为 G14 本地 registry 的 `moonbridge:<上游短 commit>`；GitHub、Google 或 Docker base image 下载必须优先使用 G14 节点本地 proxy。DeepSeek key 仍通过 `hwlab-code-agent-provider/openai-api-key` Secret 注入到 init container 并写入 Pod 内 `emptyDir` 配置文件；ConfigMap、文档、trace、health、issue 和日志不得打印 Secret 值。 +DeepSeek proxy manifest 是 GitOps desired state 的一部分，并生成在当前 lane runtime path。Moon Bridge 镜像由 `deploy/moonbridge/Dockerfile` 从上游 `ZhiYi-R/moon-bridge` 固定 commit 构建，镜像 registry 由当前 node/lane 配置解析；GitHub、Google 或 Docker base image 下载必须优先使用目标节点本地 proxy。DeepSeek key 仍通过 `hwlab-code-agent-provider/openai-api-key` Secret 注入到 init container 并写入 Pod 内 `emptyDir` 配置文件；ConfigMap、文档、trace、health、issue 和日志不得打印 Secret 值。 ## Polling 触发 @@ -248,4 +248,4 @@ node scripts/ci-plan.mjs --base-ref origin/G14 --target-ref HEAD --pretty 7. 做最终运行态验证 - 先看公网 `/health/live`，再跑 focused live smoke；业务 smoke 必须在目标运行面已经 Healthy 后进行。 -- Code Agent 对话链路用 `node scripts/code-agent-chat-smoke.mjs --live` 或显式 `--url http://74.48.78.17:17667/ --timeout-ms 45000`；通过标准是“真实 DEV 路由 + `completed` + 非空 assistant reply”，不是单纯 HTTP 200、非 JSON chunk 或 10 秒内首包。 +- Code Agent 对话链路用 `node scripts/code-agent-chat-smoke.mjs --live --url --timeout-ms 45000`；通过标准是“真实目标 node/lane 路由 + `completed` + 非空 assistant reply”，不是单纯 HTTP 200、非 JSON chunk 或 10 秒内首包。 diff --git a/docs/reference/spec-hwpod-harness.md b/docs/reference/spec-hwpod-harness.md index 6cfb4def..ec6d6759 100644 --- a/docs/reference/spec-hwpod-harness.md +++ b/docs/reference/spec-hwpod-harness.md @@ -201,12 +201,12 @@ HWPOD 调试固定保留两种入口，二者必须调用同一套 `hwpod-cli` / ### 人工单步直调 hwpod-cli -人工或维护 agent 定位 CaseRun 卡点时，优先在 G14 v0.2 workspace 直接调用 `hwpod-cli` 的单步命令。调用前必须加载 v0.2 CLI API key 和 runtime endpoint，并显式传入 `--hwpod-id` 和本次 subject worktree 的 `--workspace-path`；resolved HWPOD document 是 DAPLink、Keil target、COM 口和波特率的输入权威，workspace path 是本次运行的覆盖参数。 +人工或维护 agent 定位 CaseRun 卡点时，优先在当前 issue/CLI 明确 node + lane 的固定 workspace 直接调用 `hwpod-cli` 的单步命令。调用前必须加载目标 node/lane 的 CLI API key sourceRef 和 runtime endpoint，并显式传入 `--hwpod-id` 和本次 subject worktree 的 `--workspace-path`；resolved HWPOD document 是 DAPLink、Keil target、COM 口和波特率的输入权威，workspace path 是本次运行的覆盖参数。 ```bash -. /root/.config/hwlab-v02/master-server-admin-api-key.env -export HWLAB_RUNTIME_API_URL=http://74.48.78.17:19667 -export HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666 +. +export HWLAB_RUNTIME_API_URL= +export HWLAB_RUNTIME_WEB_URL= export HWLAB_RUNTIME_ENDPOINT_LOCKED=1 bun tools/hwpod-ctl.ts spec validate --hwpod-id d601-f103-v2 --workspace-path