docs: pin hwlab and agentrun to nc01
This commit is contained in:
Codex
+39
-42
@@ -10,60 +10,59 @@ AgentRun 唯一长期仓库是：
|
||||
git@github.com:pikasTech/agentrun.git
|
||||
```
|
||||
|
||||
AgentRun 当前 `v0.1` 固定 source worktree 是：
|
||||
AgentRun 当前固定 source worktree 是：
|
||||
|
||||
```text
|
||||
G14:/root/agentrun-v01
|
||||
NC01:/root/agentrun
|
||||
```
|
||||
|
||||
该目录必须固定使用 `v0.1` 分支，`origin` 必须是 `git@github.com:pikasTech/agentrun.git`，并保持 clean。任何明确面向 UniDesk/HWLAB 基础 Code Agent 调用服务 `v0.1` 的开发、文档修改、部署观察或恢复中断后，先通过 UniDesk SSH 透传执行：
|
||||
该目录必须固定跟踪当前 NC01 lane 声明的 AgentRun source branch，remote 必须符合 `config/agentrun.yaml#controlPlane.lanes.nc01-v02.source.remote`，并保持 clean。任何 AgentRun 开发、文档修改、部署观察或恢复中断后，先通过 UniDesk SSH 透传执行：
|
||||
|
||||
```bash
|
||||
trans G14:/root/agentrun-v01 sh -- 'pwd; git status --short --branch; git remote -v'
|
||||
trans NC01:/root/agentrun sh -- 'pwd; git status --short --branch; git remote -v'
|
||||
```
|
||||
|
||||
期望状态：
|
||||
|
||||
- 当前路径是 `/root/agentrun-v01`；
|
||||
- 分支是 `v0.1...origin/v0.1`；
|
||||
- `origin` 是 `git@github.com:pikasTech/agentrun.git`；
|
||||
- 当前路径是 `/root/agentrun`；
|
||||
- 分支和 remote 与 `config/agentrun.yaml` 的 NC01 lane 声明一致；
|
||||
- 固定 source worktree clean。
|
||||
|
||||
如果固定 source worktree 缺失、dirty、分支不对或 remote 不对，必须先修正，再继续工作。不得把 `/root/agentrun` 主线历史目录、`/root/unidesk`、`/root/hwlab`、D601 workspace、临时 clone、runner checkout、pod 内副本或 master-server 副本当作 AgentRun `v0.1` source truth。
|
||||
如果固定 source worktree 缺失、dirty、分支不对或 remote 不对，必须先修正，再继续工作。不得把非 NC01 workspace、`/root/unidesk`、`/root/hwlab`、临时 clone、runner checkout、pod 内副本或 master-server 副本当作 AgentRun source truth。
|
||||
|
||||
## Worktree 规则
|
||||
|
||||
固定 source worktree 只用于预检、fetch、worktree 管理和最终同步。常规 AgentRun `v0.1` 功能、文档和部署修改必须使用独立 worktree：
|
||||
固定 source worktree 只用于预检、fetch、worktree 管理和最终同步。常规 AgentRun `v0.2` 功能、文档和部署修改必须使用独立 worktree：
|
||||
|
||||
```text
|
||||
G14:/root/agentrun-v01/.worktree/{pr_branch}
|
||||
NC01:/root/agentrun/.worktree/{pr_branch}
|
||||
```
|
||||
|
||||
`v0.1` worktree 必须从最新 `origin/v0.1` 创建。任务分支只覆盖当前变更，提交时只提交当前任务相关文件。不要把 `/root/agentrun-v01` 根目录当作并行任务 scratch 区。
|
||||
任务 worktree 必须从 NC01 lane 声明的最新 source branch 创建。任务分支只覆盖当前变更，提交时只提交当前任务相关文件。不要把 `/root/agentrun` 根目录当作并行任务 scratch 区。
|
||||
|
||||
## 文档落库规则
|
||||
|
||||
AgentRun 仓库内长期参考、`spec-v01-*` 和 `architecture.md` 交叉引用 stub 变更不创建 PR。完成本地审查后，必须直接提交并推送到对应目标分支，例如 `origin/v0.1`。需求规格正文变更落到 UniDesk OA 的 `project-management/PJ2026-01/specs/`，不要在 AgentRun repo 另维护一份正文。过程计划、阶段证据、验收结果和阻塞点写入对应 GitHub issue 评论区，不能用文档 PR 代替直接落库。
|
||||
AgentRun 仓库内长期参考、`spec-v01-*` 和 `architecture.md` 交叉引用 stub 变更不创建 PR。完成本地审查后，必须直接提交并推送到对应目标分支，例如 `origin/v0.2`。需求规格正文变更落到 UniDesk OA 的 `project-management/PJ2026-01/specs/`，不要在 AgentRun repo 另维护一份正文。过程计划、阶段证据、验收结果和阻塞点写入对应 GitHub issue 评论区，不能用文档 PR 代替直接落库。
|
||||
|
||||
## 部署目标
|
||||
|
||||
AgentRun 废弃旧 `dev/prod` 运行口径。`v0.1` 固定部署目标是 G14 原生 k3s namespace：
|
||||
AgentRun 废弃旧 `dev/prod` 和非 NC01 node 运行口径。固定部署目标是 NC01 k3s 的 AgentRun namespace：
|
||||
|
||||
```text
|
||||
G14:k3s namespace agentrun-v01
|
||||
NC01:k3s namespace agentrun-v02
|
||||
```
|
||||
|
||||
所有 k3s 操作必须使用 UniDesk route 语法：
|
||||
|
||||
```bash
|
||||
trans G14:k3s kubectl get pods -n agentrun-v01
|
||||
trans NC01:k3s kubectl get pods -n agentrun-v02
|
||||
```
|
||||
|
||||
不得把临时 NodePort、host port、pod IP、provider-gateway 业务 HTTP proxy 或一次性 port-forward 固化为 AgentRun 部署路径。任何公网入口、UniDesk/HWLAB 集成入口或跨服务访问路径，都必须先通过 AgentRun 仓库内经过审查的变更引入；UniDesk 只在后续记录对应运维入口。
|
||||
|
||||
## 受控 CI/CD 入口
|
||||
|
||||
AgentRun 控制面写操作必须通过 UniDesk 高层 CLI 执行。无 `--node/--lane` 的控制面命令不再表示代码里的固定 G14/v0.1 常量，而是解析 `config/agentrun.yaml.controlPlane.default`；显式 `--node <node> --lane <lane>` 仍可选择其他 lane。新增或迁移 lane 必须从 `config/agentrun.yaml` 解析目标，不得从 AgentRun service repo 的 `deploy.json` 读取部署真相。
|
||||
AgentRun 控制面写操作必须通过 UniDesk 高层 CLI 执行。无 `--node/--lane` 的控制面命令解析 `config/agentrun.yaml.controlPlane.default`，当前固定为 `NC01/nc01-v02`；显式 `--node <node> --lane <lane>` 也只应选择 NC01 lane。新增或迁移 lane 必须从 `config/agentrun.yaml` 解析目标，不得从 AgentRun service repo 的 `deploy.json` 读取部署真相。
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts agentrun control-plane status
|
||||
@@ -71,8 +70,8 @@ bun scripts/cli.ts agentrun control-plane trigger-current --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane trigger-current --confirm
|
||||
bun scripts/cli.ts agentrun control-plane refresh --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane refresh --confirm
|
||||
bun scripts/cli.ts agentrun control-plane cleanup-runners --node D601 --lane v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane cleanup-runners --node D601 --lane v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane cleanup-runs --min-age-minutes 30 --limit 200 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane cleanup-runs --min-age-minutes 30 --limit 200 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane cleanup-released-pvs --limit 200 --dry-run
|
||||
@@ -82,23 +81,23 @@ bun scripts/cli.ts agentrun control-plane cleanup-released-pvs --limit 200 --con
|
||||
YAML-only lane 的标准入口是：
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts agentrun control-plane plan --node D601 --lane v02
|
||||
bun scripts/cli.ts agentrun control-plane apply --node D601 --lane v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane apply --node D601 --lane v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane secret-sync --node D601 --lane v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane secret-sync --node D601 --lane v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane restart --node D601 --lane v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane restart --node D601 --lane v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane trigger-current --node D601 --lane v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane trigger-current --node D601 --lane v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane status --node D601 --lane v02 --full
|
||||
bun scripts/cli.ts platform-infra gitea mirror status --target JD01
|
||||
bun scripts/cli.ts platform-infra pipelines-as-code status --target JD01
|
||||
bun scripts/cli.ts agentrun control-plane plan --node NC01 --lane nc01-v02
|
||||
bun scripts/cli.ts agentrun control-plane apply --node NC01 --lane nc01-v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane apply --node NC01 --lane nc01-v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane secret-sync --node NC01 --lane nc01-v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane secret-sync --node NC01 --lane nc01-v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane restart --node NC01 --lane nc01-v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane restart --node NC01 --lane nc01-v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane trigger-current --node NC01 --lane nc01-v02 --dry-run
|
||||
bun scripts/cli.ts agentrun control-plane trigger-current --node NC01 --lane nc01-v02 --confirm
|
||||
bun scripts/cli.ts agentrun control-plane status --node NC01 --lane nc01-v02 --full
|
||||
bun scripts/cli.ts platform-infra gitea mirror status --target NC01
|
||||
bun scripts/cli.ts platform-infra pipelines-as-code status --target NC01
|
||||
```
|
||||
|
||||
`status` 只读观察 YAML 选中 lane 的 source authority、对应 PipelineRun、GitOps latest、Argo Application、runtime workload、manager source commit 和 git mirror/Gitea 摘要，并报告 Argo revision 是否对齐该 lane 的 GitOps latest。未迁移的 legacy `v0.2` lane source authority 只来自 k8s git-mirror snapshot：受控 sync 先为 branch tip 创建 `refs/unidesk/snapshots/agentrun-yaml-lane/<branch>/<commit>`，`status` / `trigger-current` / build 只读取该 snapshot 和 `sourceStageRef`，不得把 host source workspace、本地 fetch/pull、可变 branch ref 或 Pipeline 直连 GitHub 当 authoritative source。默认输出是 compact commander 视图：`target` 只保留 node/lane/source/runtime/CI/GitOps/git-mirror/database 摘要，关键结论在 `summary` 和 `alignment`，成功 probe 的 stdout/stderr tail、完整 YAML target、原始 `source`、`runtime`、`gitMirror` payload 默认省略；需要完整展开时使用返回的 `disclosure.fullCommand` 或显式加 `--full`，需要原始调试视图时加 `--raw`。`status` 额外支持 `--pipeline-run <name>` 与 `--source-commit <sha>` 定点查询；`--pipeline-run` 会读取 PipelineRun `revision` 参数作为 pinned source commit，并在 `alignment.branchDrift` / `summary.branchDrift` 中同时披露当前 snapshot tip、目标 source commit、PipelineRun source commit、是否已被当前 snapshot supersede 以及 `triggerLatest` 下一步。`status` 会向 stderr 输出 `agentrun.control-plane.status.progress` 阶段事件，覆盖 `source`、`runtime` 和 `git-mirror`，避免长时间聚合时无可见进展。legacy `trigger-current` 会先执行 k8s git-mirror sync 并以 snapshot commit 创建 commit-pinned PipelineRun；同名 PipelineRun 正在运行或已经成功时必须拒绝重复触发，只允许在失败态或不存在时创建。该命令只提交 CI/CD 工作，不等待完整 PipelineRun 或 rollout 完成，后续用 `job status` 和 `status --pipeline-run <name>` 轮询。`refresh` 只对 YAML 声明的 Argo Application 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。
|
||||
|
||||
JD01/NC01 `agentrun-<node>-v02` PaC 迁移 lane 的正式触发链路是：GitHub PR 合并到 `pikasTech/agentrun@v0.2` -> GitHub webhook bridge 同步到 Gitea controlled mirror 和 immutable snapshot refs -> Gitea repository push webhook 触发 Pipelines-as-Code -> Tekton PipelineRun -> GitOps/Argo -> k8s runtime。该 lane 不再使用 branch-follower、Gitea Actions、act_runner 或自维护 `trigger-current` 作为正式 CI 触发器；对应 source authority、repo visibility、public exposure 和 mirror credentials 属于 `config/platform-infra/gitea.yaml`，PaC controller/Repository/webhook/Tekton 参数属于 `config/platform-infra/pipelines-as-code.yaml`。多节点共享同一 GitHub upstream 时，每个目标 node 的 webhook bridge 必须使用 target 级 YAML path 和 FRP remote port，不得复用另一节点的 GitHub hook URL 或 bridge。Gitea 的公开 Web UI 是 `https://gitea.pikapython.com`，但 CI、Argo 和 runtime 内部读取必须使用 `gitea-http.devops-infra.svc.cluster.local:3000` 的 ClusterIP URL，避免公网回环和 legacy git-mirror commit 缺失。
|
||||
NC01 `agentrun-nc01-v02` PaC lane 的正式触发链路是：GitHub PR 合并到 `pikasTech/agentrun@v0.2` -> GitHub webhook bridge 同步到 Gitea controlled mirror 和 immutable snapshot refs -> Gitea repository push webhook 触发 Pipelines-as-Code -> Tekton PipelineRun -> GitOps/Argo -> k8s runtime。该 lane 不再使用 branch-follower、Gitea Actions、act_runner 或自维护 `trigger-current` 作为正式 CI 触发器；对应 source authority、repo visibility、public exposure 和 mirror credentials 属于 `config/platform-infra/gitea.yaml`，PaC controller/Repository/webhook/Tekton 参数属于 `config/platform-infra/pipelines-as-code.yaml`。Gitea 的公开 Web UI 是 `https://gitea.pikapython.com`，但 CI、Argo 和 runtime 内部读取必须使用 `gitea-http.devops-infra.svc.cluster.local:3000` 的 ClusterIP URL，避免公网回环和 legacy git-mirror commit 缺失。
|
||||
|
||||
AgentRun PaC lane 的 closeout 以 `bun scripts/cli.ts cicd status --node <NODE>` 或 `bun scripts/cli.ts platform-infra pipelines-as-code status --target <NODE> --consumer agentrun-<node>-v02` 为首选状态入口。默认输出必须能直接看到 webhook 是否存在、最新 PipelineRun/TaskRun duration、image status、env identity、digest、GitOps commit、Argo revision/health、manager Deployment readiness 和 runtime source/env annotation。env reuse 的通过证据是 `IMAGE_STATUS=reused`、同一 env identity 和稳定 digest；首次 cache miss 可以作为冷启动事实记录，但不能替代后续 env-reuse 秒级收口。若 GitHub PR 已合并但没有新 PipelineRun，应先排查 `platform-infra gitea mirror webhook status|test` 与 `platform-infra pipelines-as-code history`，不得改用 `trigger-current`、直接创建 PipelineRun、手工 push Gitea 或裸 `kubectl` 作为正式补触发。
|
||||
|
||||
@@ -106,9 +105,9 @@ YAML-only lane 的 `trigger-current --confirm` 是受控长流程入口；k8s gi
|
||||
|
||||
AgentRun YAML-only lane 发布收口必须以当前 k8s git-mirror snapshot tip 为准。`trigger-current` 期间若 lane source branch 被并行 PR 推进，`status --pipeline-run <name>` 会通过 `branchDrift.sourceBranchAdvanced=true` / `targetSupersededByCurrentBranch=true` 标记该 PipelineRun 已不是当前 snapshot tip；closeout 必须确认最新 snapshot commit 包含本次修复，再按最新 snapshot 重新 `trigger-current`，最后用最新 PipelineRun 的 `status` 证明 `aligned=true`、`blockers=[]`、`argoSyncedToGitops=true` 和 `managerSourceMatchesExpected=true`。不要用已经被更新 source supersede 的中间 PipelineRun 作为最终 closeout。
|
||||
|
||||
YAML-only lane 的 `trigger-current` 会先确保目标 branch 已同步到 k8s git-mirror snapshot，再从 UniDesk YAML 声明的 image build、GitOps branch/path、runtime namespace、Secret、数据库和 manager env 渲染 artifact catalog 与 GitOps desired state。该路径会删除新 lane source branch 中的 `deploy/deploy.json`，因为部署真相已经迁入 UniDesk YAML；旧 `v0.1` branch 中历史文件只作为迁移前遗留产物存在，不能作为新 lane 的事实来源。Secret export 格式或外部数据库连接参数变化时，先用 `platform-db postgres export-secrets --confirm` 物化本地 Secret source，再用 `agentrun control-plane secret-sync --node <node> --lane <lane> --confirm` 下发，最后用 `agentrun control-plane restart --node <node> --lane <lane> --confirm` 让 manager Deployment 通过 rollout 读取新 Secret；不要手工删除 Pod 或直接 patch Secret。
|
||||
YAML-only lane 的 `trigger-current` 会先确保目标 branch 已同步到 k8s git-mirror snapshot，再从 UniDesk YAML 声明的 image build、GitOps branch/path、runtime namespace、Secret、数据库和 manager env 渲染 artifact catalog 与 GitOps desired state。该路径会删除新 lane source branch 中的 `deploy/deploy.json`，因为部署真相已经迁入 UniDesk YAML；旧 `v0.2` branch 中历史文件只作为迁移前遗留产物存在，不能作为新 lane 的事实来源。Secret export 格式或外部数据库连接参数变化时，先用 `platform-db postgres export-secrets --confirm` 物化本地 Secret source，再用 `agentrun control-plane secret-sync --node <node> --lane <lane> --confirm` 下发，最后用 `agentrun control-plane restart --node <node> --lane <lane> --confirm` 让 manager Deployment 通过 rollout 读取新 Secret；不要手工删除 Pod 或直接 patch Secret。
|
||||
|
||||
Provider credential Secret 的 `auth.json` 和 `config.toml` 也必须按 lane 的 YAML `sourceRef` 下发，不能把指挥机全局 Codex 配置当成所有 lane 的运行真相。lane 的模型、provider、endpoint 和 Codex runtime options 需要由 UniDesk YAML 拥有时，使用 `sourceMode: codex-config` 和同一 Secret spec 下的 `codexConfig` 渲染 `config.toml`；不要通过修改 `/root/.codex/config.toml` 或 `~/.codex/config.toml` 来改变 HWLAB/AgentRun 运行面模型。HWLAB 通过 D601/NC01 `agentrun-v02` 使用 Codex profile 时，`config.toml` 应只携带该 lane 需要的 Codex CLI runtime options，例如 model、reasoning、context window、auto compact、storage 和 network 相关键；除非对应 `auth.json` / API key source 也由同一 lane 明确拥有并已验证，否则不要在 lane config 中覆盖 provider endpoint、`base_url`、`model_provider` 或其他 endpoint 绑定。常见回归有两类：同步到 runner 的 config 缺少 `model_context_window` / `model_auto_compact_token_limit`，导致多轮 tool/webSearch 后报 context-window failure；或者为了补参数误加不匹配的 provider endpoint，导致 provider auth failure。修复必须走 `agentrun control-plane secret-sync --node <node> --lane <lane>` 的 dry-run/confirm，再用 `restart` 生效，并通过 HWLAB `hwlab-cli client agent send|trace|result` 原入口验证；不要从 Kubernetes Secret 反解配置内容或在 issue/trace 中打印 payload。
|
||||
Provider credential Secret 的 `auth.json` 和 `config.toml` 也必须按 NC01 lane 的 YAML `sourceRef` 下发，不能把指挥机全局 Codex 配置当成运行真相。lane 的模型、provider、endpoint 和 Codex runtime options 需要由 UniDesk YAML 拥有时，使用 `sourceMode: codex-config` 和同一 Secret spec 下的 `codexConfig` 渲染 `config.toml`；不要通过修改 `/root/.codex/config.toml` 或 `~/.codex/config.toml` 来改变 HWLAB/AgentRun 运行面模型。HWLAB 通过 NC01 `agentrun-v02` 使用 Codex profile 时，`config.toml` 应只携带该 lane 需要的 Codex CLI runtime options，例如 model、reasoning、context window、auto compact、storage 和 network 相关键；除非对应 `auth.json` / API key source 也由同一 lane 明确拥有并已验证，否则不要在 lane config 中覆盖 provider endpoint、`base_url`、`model_provider` 或其他 endpoint 绑定。常见回归有两类：同步到 runner 的 config 缺少 `model_context_window` / `model_auto_compact_token_limit`，导致多轮 tool/webSearch 后报 context-window failure；或者为了补参数误加不匹配的 provider endpoint，导致 provider auth failure。修复必须走 `agentrun control-plane secret-sync --node NC01 --lane nc01-v02` 的 dry-run/confirm，再用 `restart` 生效，并通过 HWLAB `hwlab-cli client agent send|trace|result` 原入口验证；不要从 Kubernetes Secret 反解配置内容或在 issue/trace 中打印 payload。
|
||||
|
||||
AgentRun resource/session client policy 也由 `config/agentrun.yaml` 声明。`client.sessionPolicy` 是未显式选择 node/lane 时 `agentrun send session/...` 和相关 session payload 生成的默认 `tenantId`、`projectId`、`providerId`、`backendProfile`、`workspaceRef` 和 execution policy 来源；显式 `--node <node> --lane <lane>` 后，`explain session-policy`、`send session`、resource primitives 和 AipodSpec render 都必须改用目标 lane 的 YAML 事实。lane `secrets[].providerCredential.profile` 声明 provider credential Secret 归属，UniDesk CLI 只按 YAML 聚合 Secret name/key，不再用代码拼接 provider Secret 名称。只读入口 `bun scripts/cli.ts agentrun explain session-policy` 用于查看选中目标 lane、policy 来源、实际 executionPolicy payload 和 provider credential binding 来源；输出只能包含 Secret metadata、key 名和 `valuesPrinted=false`，不得打印 Secret value。
|
||||
|
||||
@@ -118,21 +117,19 @@ AgentRun resource/session client policy 也由 `config/agentrun.yaml` 声明。`
|
||||
|
||||
`cleanup-runners --force-active` 只用于 operator 已明确决定“强杀 runner pod”的资源恢复场景，例如 runner Job 顶满单节点 pod 配额并阻塞 git-mirror、CI/CD 或其他控制面调度。使用前仍必须先执行同参 `--dry-run`，确认 `criteria.forceActive=true`、命中的 namespace/selector、`selectedRunnerJobs` 和预期一致；`--confirm` 会删除所有匹配 runner Job，包括 protected active runner，并会中断对应 run、command 或 session。该开关不得作为日常 retention、静默自愈或 over-limit 默认策略；需要强杀时也必须走这个受控入口，禁止回退到裸 `kubectl delete pod/job`。
|
||||
|
||||
`cleanup-runs` 是 AgentRun `v0.1` 完成态 CI workspace retention 入口，只清理 `agentrun-ci` namespace 中超过 `--min-age-minutes` 的 `agentrun-v01-ci-*` PipelineRun，通过 Tekton ownerRef 释放临时 workspace PVC。dry-run 必须披露候选 PipelineRun、owned PVC、active mount 保护、local-path 实际估算 bytes 和 confirm 命令。默认保护最新完成的 PipelineRun，保留当前 CI/CD 状态证据。`cleanup-released-pvs` 是二次回收入口，只处理 `agentrun-ci`、`local-path`、`Delete` reclaim policy 的 `Released` PV；它不触碰 AgentRun runtime namespace、业务 PVC、Secret、registry storage 或 GitOps desired state。磁盘治理和 G14 safe-stop 规则见 `docs/reference/gc.md`。
|
||||
`cleanup-runs` 是 AgentRun `v0.2` 完成态 CI workspace retention 入口，只清理 `agentrun-ci` namespace 中超过 `--min-age-minutes` 的 `agentrun-v02-ci-*` PipelineRun，通过 Tekton ownerRef 释放临时 workspace PVC。dry-run 必须披露候选 PipelineRun、owned PVC、active mount 保护、local-path 实际估算 bytes 和 confirm 命令。默认保护最新完成的 PipelineRun，保留当前 CI/CD 状态证据。`cleanup-released-pvs` 是二次回收入口，只处理 `agentrun-ci`、`local-path`、`Delete` reclaim policy 的 `Released` PV；它不触碰 AgentRun runtime namespace、业务 PVC、Secret、registry storage 或 GitOps desired state。磁盘治理规则见 `docs/reference/gc.md`。
|
||||
|
||||
Runner 持久化、空闲退出窗口和 session PVC 相关运维参数的唯一归属是 UniDesk `config/agentrun.yaml` 中目标 lane 的 `deployment.runner.*` 配置；不要在 HWLAB 仓库新增运维 YAML，也不要让 AgentRun service repo 的 `deploy.json` 或 Kubernetes runtime 状态反向成为配置真相。Manager Deployment 需要把 YAML 渲染为 `AGENTRUN_RUNNER_IDLE_TIMEOUT_MS` 等 manager env，但这只能证明控制面配置已到 manager；关闭 HWLAB/AgentRun 长会话或 runner 持久化问题前，还必须通过原入口创建新 turn，并检查新建 runner Job 的 env、session PVC 和 `AGENTRUN_SOURCE_COMMIT`。AgentRun manager 内所有创建 runner Job 的路径，包括 `/api/v1/runs/:runId/runner-jobs`、session send 和 queue dispatch，都必须复用同一 runner defaults helper；新增 `deployment.runner.*` 字段时禁止在某条 route 手写一份 defaults。
|
||||
|
||||
涉及 AgentRun runner egress、`transientEnv` 或 Secret 不泄露的 closeout，必须用真实 `create/apply/send` 资源原语触发目标 lane 的 runner Job，再通过 `describe runnerjob/...`、`events run/...`、`logs session/...` 或必要的兼容 bridge 检查 runner job response、event/trace 和 Kubernetes Pod spec。Runner egress proxy 的部署真相是 `config/agentrun.yaml` 中对应 lane 的 `deployment.runner.egressProxyUrl` 与 `deployment.runner.noProxyExtra`；manager Deployment 必须把它们暴露为 `AGENTRUN_RUNNER_EGRESS_PROXY_URL` 与 `AGENTRUN_RUNNER_NO_PROXY_EXTRA`，实际验收还必须确认新建 runner Job Pod 继承了对应 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY`，不能只看 manager env 或 plan 输出。通过证据应显示 proxy env 是否存在、`NO_PROXY` 是否包含 `hyueapi.com`/`.hyueapi.com`、短期 `HWLAB_API_KEY` 等 `transientEnv` 是否通过 per-job Secret 的 `valueFrom.secretKeyRef` 注入，以及 response/event 只输出 env name、Secret metadata 和 `valuesPrinted=false`。不得在 issue、trace 或 Pod spec 摘要中输出 Secret value。HWLAB-facing SecretRef 和 RuntimeAssembly 需求以 [Runtime装配](../../project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md) 与 [YAML运维](../../project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md) 为权威；AgentRun 仓库 stub 只交叉引用这些 OA 规格。
|
||||
|
||||
通过 `g14-provider-egress-proxy.unidesk.svc.cluster.local:18789` 验证 `codeload.github.com` 时，必须同时确认 G14 runtime egress Service 有 ready endpoint。Service/DNS 存在但 Deployment `0/1`、Endpoint 只有 notReady address、Pod `ImagePullBackOff` 或 `ContainerStatusUnknown` 时，问题归为 UniDesk/G14 runtime egress 基础设施；不能把 runner 已注入 proxy env 后的 `connect refused` 归为 AgentRun 业务修复失败，也不能关闭要求“通过受控 proxy 成功访问 codeload”的 issue。
|
||||
|
||||
## UniDesk 边界
|
||||
|
||||
UniDesk 是 AgentRun 的综合分布式开发和运维中心。UniDesk 可以记录：
|
||||
|
||||
- AgentRun 的固定仓库、source worktree 和 worktree 规则；
|
||||
- G14 预检、route 语法和远程操作入口；
|
||||
- `v0.1` 固定 namespace 与后续版本 lane 规则；
|
||||
- `v0.2` 固定 namespace 与后续版本 lane 规则；
|
||||
- 部署观察、受控 rollout 和运维入口；
|
||||
- UniDesk OA 定义公共契约后，UniDesk 与 HWLAB 如何接入。
|
||||
|
||||
@@ -147,13 +144,13 @@ AgentRun 的产品边界、REST resource/API 语义、run/command/event/session/
|
||||
|
||||
## AgentRun Queue 与旧 Code Queue 边界
|
||||
|
||||
AgentRun `v0.1` 的指挥官任务面已经按 AgentRun issue #105 完成真实运行面验收，可作为新任务派发、commander queue 观察、events/logs/result、steer/send、ack 和 cancel 的 AgentRun 侧标准路径。长期能力规格以 UniDesk OA 的 [队列会话](../../project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md) 和 [AgentRun核心](../../project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md) 为准；UniDesk 只记录该路径已经通过 G14 `agentrun-v01` 运行面和 `hy` profile + `gpt-5.5` 验证。
|
||||
AgentRun 指挥官任务面已经按 AgentRun issue #105 完成真实运行面验收，可作为新任务派发、commander queue 观察、events/logs/result、steer/send、ack 和 cancel 的 AgentRun 侧标准路径。长期能力规格以 UniDesk OA 的 [队列会话](../../project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md) 和 [AgentRun核心](../../project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md) 为准；UniDesk 只记录该路径以 NC01 `agentrun-v02` 运行面和 YAML profile 为准。
|
||||
|
||||
UniDesk 指挥官新任务入口固定使用 `bun scripts/cli.ts agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|steer|send` 资源原语。该入口是 render-only client：UniDesk 客户端保留 k8s 风格命令解析、human 表格、生命周期摘要、下一步命令、分页、`-o json|yaml` 稳定客户端 schema 和错误展示；AgentRun 服务端只提供稳定 RESTful API、鉴权和业务事实，不承载 UniDesk CLI 渲染。日常派单优先用 `agentrun create task --aipod Artificer --prompt-stdin` 或 `agentrun apply -f -` 的 quoted YAML/JSON heredoc/stdin 形式；已创建未运行任务用 `agentrun dispatch task/<taskId>` 派发；`--json-file`、`--prompt-file` 和 `--runner-json-file` 只是客户端输入来源，用于已审阅且可复用的受控文件。UniDesk 不实现 AgentRun queue 协议，也不把任务 double-write 回旧 Code Queue。
|
||||
|
||||
使用 lane-scoped AipodSpec 派单前，必须通过 `get/describe aipodspec`、render 输出或首个 runner job 摘要确认 `backendProfile`、provider credential SecretRef、tool credential SecretRef 和 bundle/workspaceRef 都存在于选中 lane 的 YAML 事实中。D601/v02 这类非默认 lane 的 Artificer 默认装配应从 lane YAML 绑定真实存在的 provider credential 和 tool credential：GitHub PR token 用 `tool=github`、`purpose=github-pr`、Secret key/projection env `GH_TOKEN`；UniDesk 透传 token 用 `tool=unidesk-ssh`、`purpose=ssh-passthrough`、Secret key/projection env `UNIDESK_SSH_CLIENT_TOKEN`。`tool=github-ssh`、`sub2api` 或其他 legacy tool credential 只有在 YAML 明确声明完整 SecretRef、keys 和 projection 时才允许渲染。若 runner Pod 出现 `FailedMount`，且缺失对象是渲染出的 SecretRef，应归为 AipodSpec/YAML 绑定问题并修正受控配置；不得在 runtime namespace 手工创建 legacy Secret 或把其他 lane 的 Secret 复制过去。AipodSpec render 的默认输出也应是 bounded summary/table/drill-down；完整 render JSON 只在显式 `--full`、`--raw`、`-o json` 或机器消费路径展开，残余 dump 问题继续归 [#862](https://github.com/pikasTech/unidesk/issues/862) 跟踪。
|
||||
使用 lane-scoped AipodSpec 派单前，必须通过 `get/describe aipodspec`、render 输出或首个 runner job 摘要确认 `backendProfile`、provider credential SecretRef、tool credential SecretRef 和 bundle/workspaceRef 都存在于选中 lane 的 YAML 事实中。NC01/nc01-v02 的 Artificer 默认装配应从 lane YAML 绑定真实存在的 provider credential 和 tool credential：GitHub PR token 用 `tool=github`、`purpose=github-pr`、Secret key/projection env `GH_TOKEN`；UniDesk 透传 token 用 `tool=unidesk-ssh`、`purpose=ssh-passthrough`、Secret key/projection env `UNIDESK_SSH_CLIENT_TOKEN`。`tool=github-ssh`、`sub2api` 或其他 legacy tool credential 只有在 YAML 明确声明完整 SecretRef、keys 和 projection 时才允许渲染。若 runner Pod 出现 `FailedMount`，且缺失对象是渲染出的 SecretRef，应归为 AipodSpec/YAML 绑定问题并修正受控配置；不得在 runtime namespace 手工创建 legacy Secret 或把其他 lane 的 Secret 复制过去。AipodSpec render 的默认输出也应是 bounded summary/table/drill-down；完整 render JSON 只在显式 `--full`、`--raw`、`-o json` 或机器消费路径展开，残余 dump 问题继续归 [#862](https://github.com/pikasTech/unidesk/issues/862) 跟踪。
|
||||
|
||||
资源原语和旧兼容 group 的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。不带 `--node`/`--lane` 时按 YAML 的默认 manager `baseUrl` 访问；显式 `--node <node> --lane <lane>` 时按同一 YAML 选中 runtime lane，经 `lane-k8s-service-proxy` 进入 manager `internalBaseUrl`，并用 manager pod env 中声明的 API key metadata 发起请求；输出只披露 node/lane/namespace/baseUrl/auth env metadata 和 `valuesPrinted=false`，不得打印 key value。该模式用于 D601 `agentrun-v02` 等非默认 lane 的资源原语操作与证据采集，尤其是 `get/describe/events/logs/result`，不替代 `agentrun control-plane ...` 发布或运维控制。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`--raw` 只披露直连 AgentRun REST envelope 和必要的 `transport=direct-http`、`clientRole=render-only`、`configPath`、`baseUrl`、auth source/redacted metadata，不打印 token value。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 G14 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
|
||||
资源原语和旧兼容 group 的默认 transport 是直连 AgentRun REST API，配置来源是 UniDesk 自有 YAML `config/agentrun.yaml`。不带 `--node`/`--lane` 时按 YAML 的默认 manager `baseUrl` 访问；显式 `--node <node> --lane <lane>` 时按同一 YAML 选中 runtime lane，经 `lane-k8s-service-proxy` 进入 manager `internalBaseUrl`，并用 manager pod env 中声明的 API key metadata 发起请求；输出只披露 node/lane/namespace/baseUrl/auth env metadata 和 `valuesPrinted=false`，不得打印 key value。该模式用于 NC01 `agentrun-v02` lane 的资源原语操作与证据采集，尤其是 `get/describe/events/logs/result`，不替代 `agentrun control-plane ...` 发布或运维控制。鉴权可以复用 `HWLAB_API_KEY` 的环境变量/固定文件发现风格，但不得依赖 HWLAB runtime、HWLAB backend-core、HWLAB frontend 代理或 SSH official CLI；多一层转发会增加故障面，不能作为正式路径。`--raw` 只披露直连 AgentRun REST envelope 和必要的 `transport=direct-http`、`clientRole=render-only`、`configPath`、`baseUrl`、auth source/redacted metadata，不打印 token value。`agentrun control-plane ...` 和 `git-mirror ...` 仍属于 NC01 source/runtime 运维控制路径，可以继续使用 UniDesk SSH capture bridge；这些控制面路径不得反向成为 queue/session 资源原语的默认 transport。
|
||||
|
||||
AgentRun 公网 HTTPS 入口、FRP/Caddy edge、direct REST base URL 和鉴权来源都由 UniDesk `config/agentrun.yaml` 声明。YAML-only lane 不允许把这些部署选择写回 AgentRun source branch 的 `deploy/deploy.json`；AgentRun source repo 只保留应用代码、构建输入和 repo 内部实现文档。`bun scripts/cli.ts agentrun control-plane expose --confirm` 只负责按 UniDesk YAML 补 edge 侧 allow port 与 Caddy site，不在 AgentRun k3s 中创建 Ingress、NodePort、LoadBalancer、hostPort 或 HWLAB 转发层。
|
||||
|
||||
@@ -165,7 +162,7 @@ AgentRun Queue 任务如果需要调用 UniDesk 维护桥，例如 `trans` / `un
|
||||
|
||||
HWLAB 接入 AgentRun 时，必须先按公共契约和运行证据判断问题归属，再进入对应仓库修改。谁拥有缺失能力、错误语义或未修复行为，就改谁；不得为了让当前联调继续推进而在另一侧迁就、伪造语义、补观测替代实现，或把缺失能力包装成已完成。
|
||||
|
||||
AgentRun 负责共享 Agent 执行基础设施本身，包括 run/command/runner-job 生命周期、bundle 物化、cancel、trace/result 元语、backend adapter 事件语义、runner 环境传递、CLI 结果查询和 OA 规格中已经承诺的能力。若这些能力缺失或行为错误，必须回到 UniDesk OA 规格确认需求，再在 `pikasTech/agentrun` 的源码、自测、CI/CD 和 `agentrun-v01` 运行面中补齐；HWLAB 不应在渲染层、adapter 层或 prompt 中推断、补造 AgentRun 没有发出的事实。
|
||||
AgentRun 负责共享 Agent 执行基础设施本身，包括 run/command/runner-job 生命周期、bundle 物化、cancel、trace/result 元语、backend adapter 事件语义、runner 环境传递、CLI 结果查询和 OA 规格中已经承诺的能力。若这些能力缺失或行为错误，必须回到 UniDesk OA 规格确认需求，再在 `pikasTech/agentrun` 的源码、自测、CI/CD 和 `agentrun-v02` 运行面中补齐；HWLAB 不应在渲染层、adapter 层或 prompt 中推断、补造 AgentRun 没有发出的事实。
|
||||
|
||||
HWLAB 负责自身产品和接入层，包括用户鉴权、Cloud Web/CLI 对外 API、conversation/session 归属、前端展示、device-pod 业务授权、HWLAB 到 AgentRun 的 adapter 映射，以及不改变外部 API 的内部调用切换。若 AgentRun 已按契约输出正确语义，而 HWLAB 消费、映射、渲染或业务路径仍有问题，必须在 `pikasTech/HWLAB` 修复，不能要求 AgentRun 为 HWLAB 私有 UI 或业务模型增加临时兼容。
|
||||
|
||||
@@ -173,7 +170,7 @@ HWLAB 负责自身产品和接入层，包括用户鉴权、Cloud Web/CLI 对外
|
||||
|
||||
直接通过 AgentRun manager、`dispatchHwlabAgentRun()` 或手写 runner job 发起的 canary 只能证明 AgentRun 基础设施和凭据投影本身可用，不能证明 HWLAB Cloud Web/Cloud API 的产品入口已经正确请求这些能力。涉及 Cloud Web Workbench、用户会话、conversation/session/thread、AgentRun runtime assembly 或业务授权的 issue，必须用 HWLAB 的 Web dispatcher 原入口，或调用同一 dispatcher 的 CLI 验证。当前 HWLAB v0.2 到 AgentRun 的资源装配需求权威是 UniDesk OA 的 [Runtime装配](../../project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md) 和 [HWLAB接入](../../project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md)：`ResourceBundleRef.kind="gitbundle"` 通过 `bundles[]` 装配 `tools/` 和 `.agents/skills`，旧 `toolAliases` / `skillRefs` / `workspaceFiles` 不再是有效接入口。若消费侧 Web dispatcher 没有按该契约传递 `gitbundle`、tool credential 或 transient env，应归为 HWLAB 接入层问题；若 dispatcher 已正确请求但 AgentRun runner 没有装配，应归为 AgentRun 执行基础设施问题。
|
||||
|
||||
HWLAB 与 UniDesk/Artificer 的 `gitbundle` checkout authority 是 repo URL + workspace ref，而不是 cloud-api artifact revision、AipodSpec mirror 开关或运行时 prompt。`ResourceBundleRef` / AipodSpec 必须继续声明无明文凭据的 GitHub repo URL；Git mirror 是 G14/AgentRun 基础设施能力，由 runner 在物化阶段自动把 GitHub URL 改写到受控 mirror read URL。不得在 AipodSpec、Queue task、prompt 或业务 adapter 中声明 `gitMirror`、mirror base URL 或 direct/mirror 分支开关。AgentRun runner 物化后必须记录原始 `repoUrl`、实际 `fetchRepoUrl`、`mirrorUsed`、`mirrorBaseUrl`、requested ref/commit 和 actual `commitId`；devops-infra mirror cache 必须覆盖 Artificer 和 HWLAB 常用 bundle repo，缺 cache 属于基础设施缺口，不能通过让 AipodSpec 直连 GitHub 来绕过。cloud-api、CI/CD 或 rollout 注入的 `commitId` 只可作为 requested hint 或显式 pin 的输入，不得作为默认 materialization 来源。关闭相关 issue 时，证据必须同时显示 `repoUrl`、`requestedRef`、actual `commitId`，以及 `bundles/tools/promptRefs/skillDirs` 摘要；若 actual `commitId` 仍等于旧 cloud-api rollout commit 且不是显式 pin，应继续归为 AgentRun bundle 物化问题。
|
||||
HWLAB 与 UniDesk/Artificer 的 `gitbundle` checkout authority 是 repo URL + workspace ref，而不是 cloud-api artifact revision、AipodSpec mirror 开关或运行时 prompt。`ResourceBundleRef` / AipodSpec 必须继续声明无明文凭据的 GitHub repo URL；Git mirror 是 NC01/AgentRun 基础设施能力，由 runner 在物化阶段自动把 GitHub URL 改写到受控 mirror read URL。不得在 AipodSpec、Queue task、prompt 或业务 adapter 中声明 `gitMirror`、mirror base URL 或 direct/mirror 分支开关。AgentRun runner 物化后必须记录原始 `repoUrl`、实际 `fetchRepoUrl`、`mirrorUsed`、`mirrorBaseUrl`、requested ref/commit 和 actual `commitId`；devops-infra mirror cache 必须覆盖 Artificer 和 HWLAB 常用 bundle repo，缺 cache 属于基础设施缺口，不能通过让 AipodSpec 直连 GitHub 来绕过。cloud-api、CI/CD 或 rollout 注入的 `commitId` 只可作为 requested hint 或显式 pin 的输入，不得作为默认 materialization 来源。关闭相关 issue 时，证据必须同时显示 `repoUrl`、`requestedRef`、actual `commitId`，以及 `bundles/tools/promptRefs/skillDirs` 摘要；若 actual `commitId` 仍等于旧 cloud-api rollout commit 且不是显式 pin，应继续归为 AgentRun bundle 物化问题。
|
||||
|
||||
HWLAB CaseRun 需要专用 skill 时，skill 必须通过 AgentRun `gitbundle` resource bundle 装配给 Code Agent，subject repo 只作为待修改源码来源，不能携带 `.agents/skills` 副本。收口证据应同时包含正向装配和负向隔离：AgentRun trace 或 CaseRun 归档显示 `resource-bundle-materialized`、`resourceBundlePolicy` 和 `.agents/skills/<skill>/SKILL.md` 读取；subject repo diff 或 artifact 中没有新增 `.agents/skills`。若 runner 已按 `gitbundle` 装配但 HWLAB case 仍把 skill 复制进 subject repo，应归为 HWLAB CaseRun 接入层问题；若 HWLAB 已按契约请求而 runner 未物化 skill，则归为 AgentRun bundle 物化问题。
|
||||
|
||||
|
||||
+46
-154
@@ -5,20 +5,15 @@
|
||||
## 固定入口
|
||||
|
||||
- UniDesk 指挥侧 workspace：`/root/unidesk`，固定使用 `master`，开始前执行 `git status` 和 `git pull --ff-only origin master`。
|
||||
- HWLAB legacy G14 DEV/PROD 已退役；`G14`/`G14-gitops`、`hwlab-dev`/`hwlab-prod`、17666/17667 和 18666/18667 不再是当前 source/runtime truth。退役状态和执行入口是 `bun scripts/cli.ts hwlab g14 retirement status|plan|execute --confirm`，细则见 `docs/reference/g14.md`。
|
||||
- HWLAB 指挥侧目标选择必须以 issue 或 CLI 中明确写出的 lane/node 为准；只有没有明确目标时，才读取 `config/hwlab-node-lanes.yaml` 的默认值。`config/hwlab-node-lanes.yaml` 是 node、lane、workspace、CI/CD repo、namespace、GitOps path、公网入口和 Secret sourceRef 的配置真相，长期参考不能把 G14、D601、v0.2 或 v0.3 写成隐藏默认。
|
||||
- HWLAB node-scoped `git-mirror` 的 GitHub upstream 标准传输使用 SSH，并由 `config/hwlab-node-control-plane.yaml` 的 `targets[].gitMirror.githubTransport.mode: ssh` 声明。D601/v03 固定通过 `GIT_SSH` wrapper 访问 `ssh://git@ssh.github.com:443/...`；node-global HTTP proxy 只作为 SSH CONNECT tunnel，不是 GitHub HTTPS auth/token transport。若运行面或 CLI 输出 `transport=https`、`GITHUB_TOKEN`、`git-mirror-github-token` 或 HTTPS token sourceRef，视为 control-plane drift/配置回归，先修 YAML 并执行 `hwlab nodes control-plane apply --node <node> --lane <lane> --confirm`，禁止改走 HTTPS、host workspace repair、fallback 或多来源仲裁。
|
||||
- HWLAB v0.3 CI/CD source authority 由 YAML 中选中的 node/lane `sourceAuthority` 决定：legacy target 使用 k8s git-mirror snapshot；Gitea/PaC 迁移 target 使用 Gitea controlled mirror 和 immutable snapshot ref。`trigger-current` / `status` / build 只消费受控 source snapshot，不得把 host worktree、本地 fetch/pull、可变 branch ref 或 Pipeline 直连 GitHub 当 authoritative source。固定 workspace 只服务源码修改、PR 准备和 repo 内验证；rollout closeout 以 source snapshot、PipelineRun、GitOps/Argo revision 和 runtime revision 收口。完整操作口径见 `$unidesk-cicd`。
|
||||
- 进入任何 HWLAB lane 工作前，先解析目标 `--node <node> --lane <lane>` 或 issue 中的“目标分支/目标节点”，再用 YAML 解析出的 route/workspace/sourceBranch/kubeRoute/runtime namespace 做预检、快进和验证。例如 `目标分支: HWLAB v0.3` 且 `目标节点: D601` 时，工作面是 `D601:/home/ubuntu/workspace/hwlab-v03`、source branch 是 `v0.3`、k3s route 是 `D601:k3s`、runtime namespace 是 `hwlab-v03`、公网入口是 `https://hwlab.pikapython.com`。
|
||||
- D518 的 HWLAB v0.3 固定主 workspace 是 `D518:/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `github/v0.3`。D518 上的源码修改、PR 准备和 repo 内验证必须在该固定 workspace 下创建任务级 `.worktree/<task>`；master server 本地 `/root/HWLAB`、一次性 clone 或未由 YAML 选中的路径只能做只读对照，不能承担 D518 开发 source truth。
|
||||
- JD01 的 HWLAB v0.3 固定主 workspace 是 `JD01:/root/workspace/hwlab-v03`，固定跟踪 `github/v0.3`。JD01 上的源码修改、PR 准备和 repo 内验证必须在该固定 workspace 下创建任务级 `.worktree/<task>`；如果固定目录尚未初始化，先建立该目录的固定 repo，再继续当前任务。
|
||||
- JD01 的出网、依赖拉取、k3s/bootstrap、git-mirror 和 web-probe 浏览器依赖都以 UniDesk YAML 中的 host-route/host-proxy 声明为准：`config/hwlab-node-control-plane.yaml` 的 `nodes.JD01.egressProxy`、`config/platform-infra/host-proxy.yaml#targets.JD01`，以及 `config/hwlab-node-lanes.yaml` 的 JD01 network/download/sourceWorkspace 配置。JD01 的 MDTODO、Cloud Web、web-probe 或 rollout 任务不是 Sub2API 任务；除非 issue/CLI 明确指向 Sub2API runtime、Codex pool 或 platform-infra sub2api target，不要把这类故障默认归因到 Sub2API，也不要把 JD01 egress 临时切到 Sub2API 路径。
|
||||
- JD01 的 node-local registry 是 k3s workload/PVC，不是 host Docker registry。`hwlab nodes control-plane infra status --node JD01 --lane v03` 应显示 registry workload ready、PVC bound、endpoint ready、`zeroSeeded=true` 和 `seededFromOldRegistry=false`；旧 host Docker `registry` 容器应保持停止。零种子 registry 迁移后，必须通过受控 `runtime-image preload` 和 `infra tools-image build/status` 补齐 BuildKit、runtime/base 和 tools image，再把 HWLAB/AgentRun status 与 web-probe smoke 作为可用性证据。
|
||||
- HWLAB 开发、部署和验证固定只使用 NC01。`config/hwlab-node-lanes.yaml` 是 node、lane、workspace、CI/CD repo、namespace、GitOps path、公网入口和 Secret sourceRef 的配置真相，当前默认目标必须是 `NC01/v03`。
|
||||
- HWLAB 固定主 workspace 是 `NC01:/root/hwlab`，固定跟踪 `v0.3`。源码修改、PR 准备、repo 内验证、GitOps render 和 rollout 修复都必须在该固定 workspace 下创建任务级 `.worktree/<task>`；master server 本地 `/root/HWLAB`、一次性 clone、runner clone、pod 内副本或非 NC01 workspace 只能做只读对照，不能承担开发 source truth。
|
||||
- HWLAB v0.3 CI/CD source authority 由 `config/hwlab-node-lanes.yaml#lanes.v03.targets.NC01.sourceAuthority` 决定。`trigger-current` / `status` / build 只消费受控 source snapshot，不得把 host worktree、本地 fetch/pull、可变 branch ref 或 Pipeline 直连 GitHub 当 authoritative source。固定 workspace 只服务源码修改、PR 准备和 repo 内验证；rollout closeout 以 source snapshot、PipelineRun、GitOps/Argo revision 和 runtime revision 收口。完整操作口径见 `$unidesk-cicd`。
|
||||
- 进入任何 HWLAB 工作前，按 `NC01/v03` 解析 route/workspace/sourceBranch/kubeRoute/runtime namespace 做预检、快进和验证：工作面是 `NC01:/root/hwlab`、source branch 是 `v0.3`、k3s route 是 `NC01:k3s`、runtime namespace 是 `hwlab-v03`、公网入口由 YAML 的 NC01 target 声明。
|
||||
- NC01 的 node-local registry 是 k3s workload/PVC，不是 host Docker registry。`hwlab nodes control-plane infra status --node NC01 --lane v03` 应显示 registry workload ready、PVC bound 和 endpoint ready；必须通过受控 `runtime-image preload` 和 `infra tools-image build/status` 补齐 BuildKit、runtime/base 和 tools image，再把 HWLAB/AgentRun status 与 web-probe smoke 作为可用性证据。
|
||||
- HWLAB 项目内长期规则入口仍以目标 repo 的 `AGENTS.md` 为准。进入已解析的目标 workspace 后，必须重新读取该 workspace 的规则文件；不能只凭主 server 的压缩上下文继续操作。
|
||||
- 每次开始 node/lane 源码修改、PR 准备或 repo 内验证前必须通过 YAML-first 受控入口检查并同步目标 workspace：`bun scripts/cli.ts hwlab nodes control-plane source-workspace sync --node <node> --lane <lane> --confirm`，再用 `source-workspace status` 读取 clean、branch、remote、HEAD 和依赖状态。`source-workspace status` 必须显示声明 remote/base 已对齐；如果返回 `source-workspace-not-ready`、`remoteUpToDate=false`、ahead/behind/diverged 或 HEAD 与声明 remote/base 不一致，先修复固定 workspace，再创建 `.worktree/<task>`、提交测试 PR 或给验收写结论。运行面 `status` healthy、PaC snapshot 对齐和 GitOps/Argo healthy 只能证明 runtime source authority，不代表 host 固定 workspace 已可用于源码工作。该入口从 `config/hwlab-node-lanes.yaml#lanes.<lane>.targets.<node>.sourceWorkspace` 读取 workspace remote、proxy env、identityTarget/identityId 和 up-to-date policy，并复用 `config/deploy-ssh-identities.yaml` 分发非交互 GitHub SSH 身份；不要把裸 `trans <node>:<workspace> git fetch ...` 当成正式预检入口。CI/CD trigger、status 和 rollout source closeout 仍以选中 `sourceAuthority` 解析出的受控 source snapshot 为准。
|
||||
- k3s 操作必须使用 YAML 解析出的 route 语法，例如 `trans D601:k3s ...` 或 `trans G14:k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。
|
||||
- D601 node-scoped runtime（例如 `D601` + `v0.3`）不是 legacy；只要 issue/CLI 明确选择 D601 node/lane，就按 YAML 中的 D601 target 执行。D601 legacy 只指旧 DEV/迁移/回滚对照路径（如 `/home/ubuntu/workspace/hwlab-dev`、16666/16667 或历史 `deploy/deploy.json` wrapper），必须由 issue/CLI 明确写成 legacy/迁移/回滚才使用。
|
||||
- `/root/HWLAB`、`/workspace/hwlab`、`/home/ubuntu/hwlab`、`/tmp/hwlab-*`、无关 runner clone、master-server checkout 或未由 YAML 选中的 workspace 都不能作为当前 HWLAB 开发 source truth；CI/CD source authority 只看选中 YAML `sourceAuthority` 的受控 source snapshot。
|
||||
- 每次开始源码修改、PR 准备或 repo 内验证前必须通过 YAML-first 受控入口检查并同步 NC01 workspace：`bun scripts/cli.ts hwlab nodes control-plane source-workspace sync --node NC01 --lane v03 --confirm`，再用 `source-workspace status` 读取 clean、branch、remote、HEAD 和依赖状态。`source-workspace status` 必须显示声明 remote/base 已对齐；如果返回 `source-workspace-not-ready`、`remoteUpToDate=false`、ahead/behind/diverged 或 HEAD 与声明 remote/base 不一致，先修复固定 workspace，再创建 `.worktree/<task>`、提交测试 PR 或给验收写结论。运行面 `status` healthy、PaC snapshot 对齐和 GitOps/Argo healthy 只能证明 runtime source authority，不代表 host 固定 workspace 已可用于源码工作。
|
||||
- k3s 操作必须使用 YAML 解析出的 route 语法，例如 `trans NC01:k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。
|
||||
- 非 NC01 workspace、`/root/HWLAB`、`/workspace/hwlab`、`/tmp/hwlab-*`、无关 runner clone、master-server checkout 或未由 YAML 选中的 workspace 都不能作为当前 HWLAB 开发 source truth；CI/CD source authority 只看 NC01 YAML `sourceAuthority` 的受控 source snapshot。
|
||||
|
||||
## 关键 GitHub 入口
|
||||
|
||||
@@ -43,34 +38,32 @@ HWLAB v0.2/v0.3 仓库内 `docs/reference/spec-*`，以及已收编的 `cloud-wo
|
||||
|
||||
## DEV 入口
|
||||
|
||||
- 退役 G14 DEV/PROD 前端/API 入口曾使用 `http://74.48.78.17:17666/`、`http://74.48.78.17:17667/health/live`、`http://74.48.78.17:18666/` 和 `http://74.48.78.17:18667/health/live`；这些端口不再作为当前 HWLAB runtime 证据。
|
||||
- 当前入口必须从 `config/hwlab-node-lanes.yaml` 的选中 node/lane 读取，不从长期文档硬编码推断。G14 `v0.2` 的公开入口、G14 `v0.3` 的公开入口和 D601 `v0.3` 的 `https://hwlab.pikapython.com` 都只是各自 YAML target 的结果，不是彼此 fallback。
|
||||
- D601 `v0.3` 前端/API 入口固定为 `https://hwlab.pikapython.com`，只能按 `config/hwlab-node-lanes.yaml` 中的 `lanes.v03.targets.D601.publicExposure` 验证；域名侧浏览器验收比裸 IP 或旧端口更能覆盖 Caddy、FRP、同源 cookie 和 Vue workbench 路由。
|
||||
- D601 legacy DEV 前端/API 入口曾使用 `http://74.48.78.17:16666/` 和 `http://74.48.78.17:16667/health/live`；只在显式 D601 legacy 排障或迁移对照时使用，不能作为当前 HWLAB DEV 运行面证据。
|
||||
- 旧公网 `:6666` 和 `:6667` 不是浏览器验收入口；内部 k3s service 仍可使用 `6667` 作为服务端口。
|
||||
- 不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 和 retired G14 DEV/PROD 端口的 FRP 说明只用于历史对照。
|
||||
- 当前入口必须从 `config/hwlab-node-lanes.yaml#lanes.v03.targets.NC01` 读取，不从长期文档硬编码推断。
|
||||
- NC01 `v0.3` 前端/API 入口固定为 `https://hwlab.pikapython.com`，只能按 `config/hwlab-node-lanes.yaml` 中的 `lanes.v03.targets.NC01.publicExposure` 验证；域名侧浏览器验收比裸 IP 或旧端口更能覆盖 Caddy、FRP、同源 cookie 和 Vue workbench 路由。
|
||||
- 旧公网端口不是浏览器验收入口；内部 k3s service 仍可使用 `6667` 作为服务端口。
|
||||
- 不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。
|
||||
|
||||
## D601 v0.3 User-Billing 管理闭环
|
||||
## NC01 v0.3 User-Billing 管理闭环
|
||||
|
||||
D601 node-scoped `v0.3` 已按 `pikasTech/HWLAB#1176` 收敛到 Sub2API-style 的最小多用户运营基线。该基线包括 app-local 注册登录、用户自服务 API key/profile/password、admin users 管理、credit adjust、Code Agent reservation/terminal billing、`/v1/billing/summary`、plan/entitlement/quota/concurrency/RPM、admin usage/ledger filter/export、manual credit audit、redeem/manual recharge，以及 subscription/payment 的 provider-agnostic `unconfigured` 占位。审计细节、PR、PipelineRun、public smoke 和 closeout 证据以 #1176 及其 R1-R6 子 issue 为准；长期参考只记录完成态边界和复验入口。
|
||||
NC01 `v0.3` 已按 `pikasTech/HWLAB#1176` 收敛到 Sub2API-style 的最小多用户运营基线。该基线包括 app-local 注册登录、用户自服务 API key/profile/password、admin users 管理、credit adjust、Code Agent reservation/terminal billing、`/v1/billing/summary`、plan/entitlement/quota/concurrency/RPM、admin usage/ledger filter/export、manual credit audit、redeem/manual recharge，以及 subscription/payment 的 provider-agnostic `unconfigured` 占位。审计细节、PR、PipelineRun、public smoke 和 closeout 证据以 #1176 及其 R1-R6 子 issue 为准；长期参考只记录完成态边界和复验入口。
|
||||
|
||||
该能力的业务 authority 仍是 HWLAB `hwlab-user-billing`。Cloud API 只做代理和同源 Web session/API key 鉴权，不维护第二套 user、credit、usage、ledger、redeem、subscription 或 payment 状态；Cloud Web 只消费 Cloud API 暴露的正式路径，不直连 user-billing 内部端口。
|
||||
|
||||
D601 `v0.3` 的 DB 执行面不再硬编码为外置 PostgreSQL，而由 UniDesk YAML `config/hwlab-node-lanes.yaml` 中选中 target 的 `runtimeStore.postgres.mode` 决定。mode 为 `local-k3s` 时，Cloud API、user-billing、workbench-runtime、project-management 和 OpenFGA 消费 `hwlab-v03` namespace 内的本地 `hwlab-v03-postgres`；复验和关闭证据应来自 `hwlab nodes control-plane plan|status`、`hwlab nodes secret status`、运行面 workload/Secret 摘要和 `external bridge/secrets not-required`，而不是要求本地 PostgreSQL 缺失。`externalPostgres` 与 PK01 platform DB YAML 必须继续保留为 `platform-service` mode 的候选配置；把 mode 切回 `platform-service` 时应重新启用 bridge/Secret 路径，但不得因为当前使用 `local-k3s` 删除外置配置。
|
||||
NC01 `v0.3` 的 DB 执行面不再硬编码为外置 PostgreSQL，而由 UniDesk YAML `config/hwlab-node-lanes.yaml` 中选中 target 的 `runtimeStore.postgres.mode` 决定。mode 为 `local-k3s` 时，Cloud API、user-billing、workbench-runtime、project-management 和 OpenFGA 消费 `hwlab-v03` namespace 内的本地 `hwlab-v03-postgres`；复验和关闭证据应来自 `hwlab nodes control-plane plan|status`、`hwlab nodes secret status`、运行面 workload/Secret 摘要和 `external bridge/secrets not-required`，而不是要求本地 PostgreSQL 缺失。`externalPostgres` 与 PK01 platform DB YAML 必须继续保留为 `platform-service` mode 的候选配置；把 mode 切回 `platform-service` 时应重新启用 bridge/Secret 路径，但不得因为当前使用 `local-k3s` 删除外置配置。
|
||||
|
||||
复验 D601 `v0.3` user-billing 管理闭环时使用 `https://hwlab.pikapython.com`，不要用 G14 `v0.2` 的 `19666/19667` 或旧 D601 legacy 端口替代。最小 smoke 应覆盖：`/health/live` revision 指向目标 source commit；admin Web session 登录；admin 创建/list/disable redeem code；普通用户注册或登录后兑换 code；重复兑换 one-time code 不重复入账；admin redemptions 和 ledger 能查到同一 ledger/redemption；subscription/payment summary 在没有真实 provider 配置时明确返回 `unconfigured`；`/billing` 和 `/admin/billing` 页面加载且部署 bundle 包含对应 endpoint。验证输出只能记录对象 id、prefix、状态、计数和 redacted presence，不能打印 bootstrap admin password、raw redeem code、API key secret、DB DSN 或 provider token。
|
||||
复验 NC01 `v0.3` user-billing 管理闭环时使用 `https://hwlab.pikapython.com`。最小 smoke 应覆盖：`/health/live` revision 指向目标 source commit；admin Web session 登录；admin 创建/list/disable redeem code；普通用户注册或登录后兑换 code；重复兑换 one-time code 不重复入账；admin redemptions 和 ledger 能查到同一 ledger/redemption；subscription/payment summary 在没有真实 provider 配置时明确返回 `unconfigured`；`/billing` 和 `/admin/billing` 页面加载且部署 bundle 包含对应 endpoint。验证输出只能记录对象 id、prefix、状态、计数和 redacted presence，不能打印 bootstrap admin password、raw redeem code、API key secret、DB DSN 或 provider token。
|
||||
|
||||
真实 payment provider、外部支付回调、订单结算和增长活动策略不是 #1176 完成态的一部分。只有当 `config/hwlab-node-lanes.yaml` 或 HWLAB 自有受控 YAML 明确声明 provider/sourceRef，并且 Secret sync、回调入口、ledger/order 状态机和 public end-to-end smoke 都齐备时，才可以把 D601 `v0.3` 从 provider-agnostic placeholder 扩展到真实支付；不得通过硬编码 provider、手写 k8s Secret、临时 SQL 或 Cloud API 平行账本绕过 user-billing authority。
|
||||
真实 payment provider、外部支付回调、订单结算和增长活动策略不是 #1176 完成态的一部分。只有当 `config/hwlab-node-lanes.yaml` 或 HWLAB 自有受控 YAML 明确声明 provider/sourceRef，并且 Secret sync、回调入口、ledger/order 状态机和 public end-to-end smoke 都齐备时，才可以把 NC01 `v0.3` 从 provider-agnostic placeholder 扩展到真实支付；不得通过硬编码 provider、手写 k8s Secret、临时 SQL 或 Cloud API 平行账本绕过 user-billing authority。
|
||||
|
||||
## HWLAB 测试账号 YAML 归属
|
||||
|
||||
HWLAB node/lane 测试账号、bootstrap admin API key 观测、普通测试用户固定 API key、workbench 绑定、user-billing DB sync 输入和 sourceRef/targetKey 映射属于 UniDesk 指挥侧运维真相，必须写入 UniDesk `config/hwlab-test-accounts.yaml`，并通过 `bun scripts/cli.ts hwlab nodes test-accounts status|sync --node <node> --lane <lane>` 受控读取和同步。HWLAB 仓库可以保留应用代码、user-billing schema/migration 和业务 API，但不能另建一份账号 YAML 真相，也不能用运行面 Secret、pod env、日志或 DB 结果反推 owner-only key source。
|
||||
|
||||
`config/hwlab-test-accounts.yaml` 中的相对 `sourceRef` 以该文件的 `sourceRoot` 为根解析，属于 UniDesk 指挥侧 owner-only source，不要求也不应要求同名文件存在于 D601/G14 目标 host。目标 host 或 runtime pod 中没有该 env 文件不能判定为 key 缺失；应先用 UniDesk 受控 CLI 确认 source 与 target fingerprint，再把选中身份的 `HWLAB_API_KEY` 仅作为一次性进程环境注入目标 HWLAB CLI。不要为了复验把测试用户 key 持久化复制到目标 workspace、shell 启动文件、issue、日志或 Git tracked 文档。
|
||||
`config/hwlab-test-accounts.yaml` 中的相对 `sourceRef` 以该文件的 `sourceRoot` 为根解析，属于 UniDesk 指挥侧 owner-only source，不要求也不应要求同名文件存在于 NC01 目标 host。目标 host 或 runtime pod 中没有该 env 文件不能判定为 key 缺失；应先用 UniDesk 受控 CLI 确认 source 与 target fingerprint，再把选中身份的 `HWLAB_API_KEY` 仅作为一次性进程环境注入目标 HWLAB CLI。不要为了复验把测试用户 key 持久化复制到目标 workspace、shell 启动文件、issue、日志或 Git tracked 文档。
|
||||
|
||||
该入口的输出只能记录 logicalId、role、permissions、workbench、sourceRef、sourceKey、targetKey、对象 id、byte count、prefix、fingerprint、presence、matchesSourceFingerprint 和 mutation 摘要；不得打印完整 `HWLAB_API_KEY`、完整 `DATABASE_URL`、base64 payload 或可复制凭据。D601 `v0.3` T1/T2 类验证如果需要 admin/test 两套身份，先用此 UniDesk YAML/CLI 准备账号，再在目标 HWLAB workspace 使用原 `hwlab-cli` 切换 `HWLAB_API_KEY` 做真实入口复验。
|
||||
该入口的输出只能记录 logicalId、role、permissions、workbench、sourceRef、sourceKey、targetKey、对象 id、byte count、prefix、fingerprint、presence、matchesSourceFingerprint 和 mutation 摘要；不得打印完整 `HWLAB_API_KEY`、完整 `DATABASE_URL`、base64 payload 或可复制凭据。NC01 `v0.3` T1/T2 类验证如果需要 admin/test 两套身份，先用此 UniDesk YAML/CLI 准备账号，再在目标 HWLAB workspace 使用原 `hwlab-cli` 切换 `HWLAB_API_KEY` 做真实入口复验。
|
||||
|
||||
`test-accounts status|sync` 中涉及 DB 的读写也必须跟随选中 node/lane 的 DB authority。D601 `v0.3` 处于 `local-k3s` mode 时，工具不得从指挥机直接连接保留下来的外置 DB sourceRef；只有 mode 明确为 `platform-service` 时才使用外置 DB 路径。若旧 test-accounts DB 探测仍因外置 sourceRef DNS 或网络失败而报错，应登记为 CLI mode-awareness follow-up，不得把它当成 access-control 预置用户或根导航 ACL 的失败证据；这类 ACL 关闭证据应来自受控 preset-user Web/API 验证和 redacted Secret 状态。
|
||||
`test-accounts status|sync` 中涉及 DB 的读写也必须跟随选中 node/lane 的 DB authority。NC01 `v0.3` 处于 `local-k3s` mode 时，工具不得从指挥机直接连接保留下来的外置 DB sourceRef；只有 mode 明确为 `platform-service` 时才使用外置 DB 路径。若旧 test-accounts DB 探测仍因外置 sourceRef DNS 或网络失败而报错，应登记为 CLI mode-awareness follow-up，不得把它当成 access-control 预置用户或根导航 ACL 的失败证据；这类 ACL 关闭证据应来自受控 preset-user Web/API 验证和 redacted Secret 状态。
|
||||
|
||||
身份、权限、workbench、trace/result 和 usage/billing 复验优先使用目标 HWLAB repo 的 typed CLI；`client request` 只能作为缺 typed wrapper 时的有界探测或后端路径确认。若 raw request 覆盖了真实用户验收所需的字段，关闭前必须把缺失的 typed CLI 包装登记到对应 HWLAB issue，不能把 raw request 静默当成长期正式用户入口。
|
||||
|
||||
@@ -124,13 +117,13 @@ OpenCode provider/model、public hostname、SecretRef 和 extra FRP proxy 都必
|
||||
|
||||
## HWLAB FRP 维护
|
||||
|
||||
HWLAB 公网 FRP server 由 master server 上的 `hwlab-frps-dev` 容器承担，容器使用 host network，并把 `/opt/hwlab-frp/frps.dev.toml` 只读挂载到 `/etc/frp/frps.toml`。这个 server 侧 allowlist 是 UniDesk 指挥侧维护对象，不属于 G14 k3s GitOps desired state；G14 侧 `frpc` ConfigMap/Deployment 只负责各 runtime namespace 的客户端 tunnel。
|
||||
HWLAB 公网 FRP server 由 master server 上的 `hwlab-frps-dev` 容器承担，容器使用 host network，并把 `/opt/hwlab-frp/frps.dev.toml` 只读挂载到 `/etc/frp/frps.toml`。这个 server 侧 allowlist 是 UniDesk 指挥侧维护对象，不属于 NC01 k3s GitOps desired state；NC01 侧 `frpc` ConfigMap/Deployment 只负责各 runtime namespace 的客户端 tunnel。
|
||||
|
||||
新增或恢复 HWLAB 公网入口时，先判断问题是否只是 server 侧 `allowPorts` 缺口。若 `frpc` 日志出现 `port not allowed`，优先在 master server 修改 `/opt/hwlab-frp/frps.dev.toml` 的 `allowPorts`，而不是改 active runtime lane 的 GitOps、Service 或 `frpc` ConfigMap。修改前保留一份本机备份，例如 `/opt/hwlab-frp/frps.dev.toml.bak-<reason>`；修改后只重启 `hwlab-frps-dev`，不要重建镜像、清理 Docker volume、重启无关 UniDesk/HWLAB 服务或触碰数据库状态。
|
||||
|
||||
当前 HWLAB FRP server allowlist 至少应覆盖 `config/hwlab-node-lanes.yaml` 中 active target 声明的 publicExposure 入口以及仍被明确使用的维护端口。Legacy `16666/16667` 和 retired G14 DEV/PROD `17666/17667`、`18666/18667` 只作为历史对照，不应作为新增 runtime 入口要求。新增端口或域名必须对应一个明确的 node/lane/namespace/runtime 入口，不能把大范围端口段作为默认放行策略。
|
||||
当前 HWLAB FRP server allowlist 至少应覆盖 `config/hwlab-node-lanes.yaml` 中 NC01 active target 声明的 publicExposure 入口以及仍被明确使用的维护端口。旧节点历史端口只作为历史对照，不应作为新增 runtime 入口要求。新增端口或域名必须对应 NC01 的明确 node/lane/namespace/runtime 入口，不能把大范围端口段作为默认放行策略。
|
||||
|
||||
FRP 维护验证顺序是：确认 `hwlab-frps-dev` 或 `config/hwlab-node-lanes.yaml` 指定的 publicExposure 入口仍挂载/渲染目标配置；重启或 apply 后用等价只读命令确认 FRP/Caddy 正在监听目标公网端口或 hostname；再在目标 namespace 查看 `frpc` 日志，确认对应 proxy `start proxy success`；最后验证选中 node/lane 的 active runtime 入口。D601 `v0.3` 验证使用 `https://hwlab.pikapython.com`；其他 node/lane 使用 YAML 中的 public URL。
|
||||
FRP 维护验证顺序是：确认 `hwlab-frps-dev` 或 `config/hwlab-node-lanes.yaml` 指定的 publicExposure 入口仍挂载/渲染目标配置；重启或 apply 后用等价只读命令确认 FRP/Caddy 正在监听目标公网端口或 hostname；再在 NC01 目标 namespace 查看 `frpc` 日志，确认对应 proxy `start proxy success`；最后验证 NC01 active runtime 入口。NC01 `v0.3` 验证使用 `https://hwlab.pikapython.com`。
|
||||
|
||||
当 public URL 返回 404/502 或 Caddy local probe 失败时，不要只凭某个历史端口、旧 worktree YAML 或当前 Caddyfile 猜测修复方向。先对齐三层事实：UniDesk `config/hwlab-node-lanes.yaml` 的 publicExposure、目标 runtime GitOps/ConfigMap 渲染出的 `frpc` 配置、以及 PK01 loopback 对每个 FRP remote port 的真实响应；同时查看 `frpc` 日志中对应 proxy 是 `start proxy success`、`port already used` 还是 `port not allowed`。Caddy 主站的 API 路径应指向 edge-proxy，上层 Web/auth/OpenCode iframe 路径应由 Cloud Web 处理；若三层事实不一致，先修拥有该事实的 YAML/source，再用受控 public-exposure 或 GitOps render 收敛，不能手工把 Caddy 临时指向看似可用的旧端口。
|
||||
|
||||
@@ -138,53 +131,53 @@ FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Sec
|
||||
|
||||
## 门禁最小化与扩容治理
|
||||
|
||||
不要滑向不必要的复杂门禁是 HWLAB 指挥侧通用原则。Legacy G14 DEV/PROD 退役、runtime lane 扩容、CI/CD 迁移、运行面热修和文档治理都应优先靠固定边界、清晰命名、唯一真相源、标准入口和长期参考文档收敛，不要把每个设计约定、运行策略或回滚手册都做成新的 preflight、guard、gate 或报告生成器。
|
||||
不要滑向不必要的复杂门禁是 HWLAB 指挥侧通用原则。旧节点退役、runtime lane 扩容、CI/CD 迁移、运行面热修和文档治理都应优先靠固定边界、清晰命名、唯一真相源、标准入口和长期参考文档收敛，不要把每个设计约定、运行策略或回滚手册都做成新的 preflight、guard、gate 或报告生成器。
|
||||
|
||||
旧 DEV/main/G14/D601 特例门禁如果阻碍 issue/CLI 明确选中的 node/lane 路径，默认处理是从当前调用链删除，而不是做兼容迁移、fallback、legacy mode、双路径绕行或在旧门禁上叠加例外。新增门禁只能覆盖明确高价值风险，且必须最小、低噪声、容易删除；资源配额、RBAC 命名、清理策略、回滚顺序、人工同步策略等默认是设计约定或 runbook，不是 CI/CD 通过条件。
|
||||
旧 DEV/main/非 NC01 特例门禁如果阻碍 NC01 node/lane 路径，默认处理是从当前调用链删除，而不是做兼容迁移、fallback、legacy mode、双路径绕行或在旧门禁上叠加例外。新增门禁只能覆盖明确高价值风险，且必须最小、低噪声、容易删除；资源配额、RBAC 命名、清理策略、回滚顺序、人工同步策略等默认是设计约定或 runbook，不是 CI/CD 通过条件。
|
||||
|
||||
每个 runtime lane 的硬边界必须从 `config/hwlab-node-lanes.yaml` 的选中 target 解析：source branch、CI/CD source repo、GitOps branch/path、runtime namespace、publicExposure、service 列表和 workspace 都以 YAML 为准。长期文档只记录“如何解析和验证”，不得把某个 node/lane 的当前数值写成全局默认。其他事项应先作为决策表或 runbook 固化，只有被证明无法靠边界和标准入口自然收敛时，才允许加最小检查。
|
||||
NC01 runtime lane 的硬边界必须从 `config/hwlab-node-lanes.yaml` 的 NC01 target 解析：source branch、CI/CD source repo、GitOps branch/path、runtime namespace、publicExposure、service 列表和 workspace 都以 YAML 为准。其他事项应先作为决策表或 runbook 固化，只有被证明无法靠边界和标准入口自然收敛时，才允许加最小检查。
|
||||
|
||||
## 最小 Device Agent/Gateway 桥接模型
|
||||
|
||||
最小打通目标是只新增桥接面，不改动既有 HWLAB 应用、GitOps、FRP、CD 或前端路径：
|
||||
|
||||
- 在选中 node/lane runtime namespace 手动建立一个 standalone `device-agent-71-freq` Pod/Deployment 和 ClusterIP Service。它暴露设备语义入口，例如 `/health`、`/skills`、`/workspace/*`、`/run`，并把真实硬件调用转成 HWLAB cloud-api 的 gateway operation，而不是在 Pod 内直接访问 Windows 硬件。
|
||||
- 在 `D601:win` 上启动 `hwlab-gateway`，作为 71-FREQ/ConStart/Keil/串口资源的外部 host bridge。gateway 通过公网或受控网络出站连接选中 node/lane 的 cloud-api，注册稳定的 `gatewaySessionId`、`resourceId` 和 `capabilityId`。
|
||||
- `hwlab-gateway` 是 Windows 长驻 outbound poll 进程，不能用 `trans D601:win cmd start ...` 或 PowerShell `Start-Process` 直接挂在一次性 trans/tran 会话下；这种启动方式可能继承输出句柄或被 provider 按子进程树等待，导致 trans/tran 卡住并阻塞后续 provider session。临时实验也应通过 Windows Task Scheduler、Windows Service、NSSM、PM2 service 或等价 detached launcher 启动，`trans` 只负责触发和读取状态；通用规则见 `docs/reference/windows-passthrough.md`。
|
||||
- D601 Windows gateway 的最小配置必须来自 profile 或环境变量，核心字段是 `HWLAB_GATEWAY_CLOUD_URL=<active-runtime-lane-cloud-api>`、`HWLAB_GATEWAY_ID`、`HWLAB_GATEWAY_SESSION_ID`、`HWLAB_GATEWAY_RESOURCE_ID`、`HWLAB_GATEWAY_CMD_CAPABILITY_ID`、`HWLAB_GATEWAY_CMD_EXEC_ENABLED=1`、`HWLAB_GATEWAY_DEMO_OPEN=1`、`HWLAB_GATEWAY_MAX_INFLIGHT` 和 `HWLAB_GATEWAY_CMD_TIMEOUT_MS`。这些值用于声明能力和执行边界，不得散落在 device-agent 代码里。
|
||||
- 在明确登记的外部 Windows 硬件网关上启动 `hwlab-gateway`，作为 71-FREQ/ConStart/Keil/串口资源的 host bridge。gateway 通过公网或受控网络出站连接 NC01 lane 的 cloud-api，注册稳定的 `gatewaySessionId`、`resourceId` 和 `capabilityId`。
|
||||
- `hwlab-gateway` 是 Windows 长驻 outbound poll 进程，不能用一次性 trans/tran 会话直接挂载；这种启动方式可能继承输出句柄或被 provider 按子进程树等待，导致 trans/tran 卡住并阻塞后续 provider session。临时实验也应通过 Windows Task Scheduler、Windows Service、NSSM、PM2 service 或等价 detached launcher 启动，`trans` 只负责触发和读取状态；通用规则见 `docs/reference/windows-passthrough.md`。
|
||||
- Windows gateway 的最小配置必须来自 profile 或环境变量，核心字段是 `HWLAB_GATEWAY_CLOUD_URL=<active-runtime-lane-cloud-api>`、`HWLAB_GATEWAY_ID`、`HWLAB_GATEWAY_SESSION_ID`、`HWLAB_GATEWAY_RESOURCE_ID`、`HWLAB_GATEWAY_CMD_CAPABILITY_ID`、`HWLAB_GATEWAY_CMD_EXEC_ENABLED=1`、`HWLAB_GATEWAY_DEMO_OPEN=1`、`HWLAB_GATEWAY_MAX_INFLIGHT` 和 `HWLAB_GATEWAY_CMD_TIMEOUT_MS`。这些值用于声明能力和执行边界，不得散落在 device-agent 代码里。
|
||||
- device-agent 访问集群内 cloud-api 时优先使用选中 runtime lane 的 Service DNS；Node 实现访问 `6667` 时遵循 Node/Lane 运行面口径里的 bad-port 规则，不为 device-agent 单独维护另一套例外。
|
||||
- 71-FREQ 的 device profile 必须配置化保存，至少包含工程根目录、Keil project/target、默认串口波特率、gateway/resource/capability 选择器和 workspace 根。不得把 `F:\Work\ConStart`、工程名、串口号或 probe UID 硬编码进 device-agent 镜像。
|
||||
- 最小验收顺序是：选中 node/lane cloud-api `/health/live` ready；D601 Windows 能访问该 lane 的 public `/health/live`；D601 `hwlab-gateway` 注册后 cloud-api 能看到 gateway session/resource/capability；`device-agent-71-freq` `/health` 和 `/skills` 返回 ready；通过 device-agent 发起一条只读或 `echo` 级 gateway shell operation，并返回 operation/evidence/trace 摘要。
|
||||
- 这个模型只证明 `device-agent Pod -> 选中 lane cloud-api -> D601 hwlab-gateway -> Windows host` 的控制链路。Keil 编译下载、串口日志抓取和 workspace CRUD 可以作为后续 device-agent skill 子命令逐步接入；未接入前不能把 device-agent 标成完整 71-FREQ 硬件代理。
|
||||
- 最小验收顺序是：NC01 lane cloud-api `/health/live` ready；外部 Windows gateway 能访问该 lane 的 public `/health/live`；`hwlab-gateway` 注册后 cloud-api 能看到 gateway session/resource/capability；`device-agent-71-freq` `/health` 和 `/skills` 返回 ready；通过 device-agent 发起一条只读或 `echo` 级 gateway shell operation，并返回 operation/evidence/trace 摘要。
|
||||
- 这个模型只证明 `device-agent Pod -> NC01 lane cloud-api -> external hwlab-gateway -> Windows host` 的控制链路。Keil 编译下载、串口日志抓取和 workspace CRUD 可以作为后续 device-agent skill 子命令逐步接入；未接入前不能把 device-agent 标成完整 71-FREQ 硬件代理。
|
||||
|
||||
## Master Server 校验边界
|
||||
|
||||
- master server 是 UniDesk/HWLAB 的生产入口且资源紧张；它只能承担轻量源码编辑、Git 操作、日志/健康观察、JSON CLI 指挥和受控 CD 审阅，不能承担正式校验执行面。
|
||||
- 禁止在 master server 上运行 HWLAB 或 UniDesk 的仓库级 `check`/`test`/smoke 命令，包括但不限于 `bun scripts/cli.ts check`、`node --test`、`node web/hwlab-cloud-web/scripts/check.mjs`、`node scripts/dev-cloud-workbench-smoke.mjs`、Playwright/browser layout smoke，以及其他会长时间占用 CPU/内存、启动浏览器或遍历大仓库的校验流程。
|
||||
- 需要正式验证时，固定切到 issue/CLI 选中的 node/lane workspace、k3s/Tekton、HWLAB repo-owned CI 或其他获批外部执行面；master server 只负责发起、观察和记录，不负责实际跑 check。
|
||||
- 如果为了排障必须从 master server 生成命令或查看源码，后续验证命令也必须显式改到目标 node/lane 路径执行，例如 `trans D601:/home/ubuntu/workspace/hwlab-v03 sh -- ...` 或 `trans D601:k3s ...`，而不是直接在 `/root/unidesk` 或 master server 上本地运行。
|
||||
- 如果为了排障必须从 master server 生成命令或查看源码，后续验证命令也必须显式改到目标 node/lane 路径执行，例如 `trans NC01:/root/hwlab sh -- ...` 或 `trans NC01:k3s ...`，而不是直接在 `/root/unidesk` 或 master server 上本地运行。
|
||||
|
||||
## Node/Lane 运行面口径
|
||||
|
||||
HWLAB 当前真实 runtime 由 issue/CLI 选中的 node/lane 决定。只读观察使用 YAML 解析出的 kube route、namespace 和 public endpoint；例如 D601 `v0.3` 使用：
|
||||
HWLAB 当前真实 runtime 固定为 NC01 `v0.3`。只读观察使用 YAML 解析出的 kube route、namespace 和 public endpoint：
|
||||
|
||||
```sh
|
||||
trans D601:k3s kubectl -n hwlab-v03 get deploy,svc,pod -o wide
|
||||
trans NC01:k3s kubectl -n hwlab-v03 get deploy,svc,pod -o wide
|
||||
```
|
||||
|
||||
HWLAB node/lane control-plane 的 PipelineRun 失败定位优先使用 UniDesk 受控状态入口，而不是先手工拼 TaskRun/Pod 查询：`bun scripts/cli.ts hwlab nodes control-plane status --node <node> --lane <lane> --pipeline-run <name>`、`trigger-current --wait` 的返回对象，以及异步 `bun scripts/cli.ts job status <jobId> --tail-bytes 12000` 都应直接暴露失败 TaskRun、Pod、container、失败 step、termination reason 和 bounded `trans <node>:k3s logs --namespace hwlab-ci --pod <pod> --container <container> --tail 200` 查看命令。默认状态输出只给诊断命令和受控摘要，不打印完整 pod 日志、Secret、完整 DSN、API key 或其他可复制凭据。遇到 service build 的 `step-publish` 失败时，下一步先跑 `bun scripts/cli.ts platform-infra sub2api status --target <node>` 和 `bun scripts/cli.ts platform-infra sub2api validate --target <node>`，区分 Sub2API/proxy 整体故障和单上游 transient，再选择受控 rerun 或修复 artifact-publish/envRecipe 的有限 retry。
|
||||
|
||||
`hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内可使用 `6667` Service 端口；对外入口以选中 target 的 publicExposure/public URL 为准。Node/Bun/undici 的 Fetch 实现会按 Fetch bad-port 规则拒绝 `6667`，因此任何需要代理、转发、探测或服务间访问该端口的 Node 实现都必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口；不要把 Fetch bad-port 造成的 `fetch failed` / 502 误判为 Service DNS、PVC、数据库或 trace 数据缺失。G14 local details 见 `docs/reference/g14.md` 和 G14 节点 `/root/docs/hwlab-g14-workspace.md`；D601 node-scoped target 以 `config/hwlab-node-lanes.yaml` 的 `nodes.D601` 和 `lanes.v03.targets.D601` 为准。
|
||||
`hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内可使用 `6667` Service 端口；对外入口以 NC01 target 的 publicExposure/public URL 为准。Node/Bun/undici 的 Fetch 实现会按 Fetch bad-port 规则拒绝 `6667`，因此任何需要代理、转发、探测或服务间访问该端口的 Node 实现都必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper，或改用不触发 bad-port 的受控代理端口；不要把 Fetch bad-port 造成的 `fetch failed` / 502 误判为 Service DNS、PVC、数据库或 trace 数据缺失。NC01 target 以 `config/hwlab-node-lanes.yaml` 的 `nodes.NC01` 和 `lanes.v03.targets.NC01` 为准。
|
||||
|
||||
D601 原生 k3s 是 D601 node-scoped runtime 的正式控制面；D601 legacy 对照也使用同一 native k3s guard。任何 D601 k3s 操作都必须显式使用 UniDesk route `D601:k3s` 或等价的 `/etc/rancher/k3s/k3s.yaml`，不能使用裸默认 kubeconfig：
|
||||
NC01 k3s 是 HWLAB 当前正式控制面。任何 HWLAB k3s 操作都必须显式使用 UniDesk route `NC01:k3s` 或等价的 NC01 kubeconfig，不能使用裸默认 kubeconfig：
|
||||
|
||||
```sh
|
||||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev get deploy,svc,pod -o wide
|
||||
trans NC01:k3s kubectl -n hwlab-v03 get deploy,svc,pod -o wide
|
||||
```
|
||||
|
||||
D601 上不要直接相信默认 `kubectl` context。默认 context 可能是 `docker-desktop`，它会展示另一套与公网 legacy `16666/16667` 无关的状态，并可能给出误导性的 `ImagePullBackOff`。
|
||||
不要直接相信默认 `kubectl` context。默认 context 可能指向非 NC01 环境，并可能给出误导性的 workload 状态。
|
||||
|
||||
历史 D601 legacy `frpc` 配置不是 D601 host `/etc/frp/frpc.toml`，而是 D601 legacy `hwlab-dev` namespace 里的 `hwlab-frpc-config` ConfigMap 和 `hwlab-frpc` Deployment。D601 `v0.3` publicExposure 以 `config/hwlab-node-lanes.yaml` 和 PK01 Caddy/FRP target 为准。
|
||||
NC01 `v0.3` publicExposure 以 `config/hwlab-node-lanes.yaml` 和 PK01 Caddy/FRP target 为准。
|
||||
|
||||
## Code Agent 模型通道
|
||||
|
||||
@@ -196,11 +189,11 @@ HWLAB 与 AgentRun 协同修复必须按 `docs/reference/agentrun.md` 的职责
|
||||
|
||||
### Code Agent Provider Profile 配置与验收
|
||||
|
||||
本小节只适用于明确选择 HWLAB `v0.2` provider profile 的任务；其他 node/lane 的 profile 配置必须先按 issue/CLI 目标和 `config/hwlab-node-lanes.yaml` 解析运行面，再读取目标 HWLAB repo 的对应规则。G14 节点参考、CLI 参考和 `hwlab-code-agent` skill 只交叉引用这里；AgentRun 内部 Secret 物化和 backend adapter 设计仍以 AgentRun 仓库自身为准。
|
||||
本小节只适用于 NC01 `v0.3` provider profile。配置必须先按 `config/hwlab-node-lanes.yaml` 解析 NC01 运行面，再读取目标 HWLAB repo 的对应规则；AgentRun 内部 Secret 物化和 backend adapter 设计仍以 AgentRun 仓库自身为准。
|
||||
|
||||
HWLAB v0.2 provider profile 必须通过已部署的 HWLAB Cloud API/CLI 管理，正式入口是 `hwlab-cli client provider-profiles`。不要把手工 patch `agentrun-v01` Secret、直接调用 AgentRun manager 或临时 runner job 当作正式配置路径或关闭证据；这些只可作为基础设施定位证据。标准执行面是 `G14:/root/hwlab-v02`，调用前锁定 `HWLAB_RUNTIME_NAMESPACE=hwlab-v02`、`HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666` 和 `HWLAB_RUNTIME_ENDPOINT_LOCKED=1`，`HWLAB_API_KEY` 从 `/root/.config/hwlab-v02/master-server-admin-api-key.env` 加载。
|
||||
Provider profile 必须通过已部署的 NC01 HWLAB Cloud API/CLI 管理，正式入口是 `hwlab-cli client provider-profiles`；不要把手工 patch AgentRun Secret、直接调用 AgentRun manager 或临时 runner job 当作正式配置路径或关闭证据。
|
||||
|
||||
当明确需要把当前 operator 的 Codex 凭据作为 AgentRun 动态 profile 提供给 HWLAB Code Agent 或 CaseRun 使用时，固定操作手册在 `$hwlab-code-agent` 的 `AgentRun 动态 sub2api profile` 小节。该场景是 AgentRun runtime profile 投影，不替代上面的 HWLAB provider-profiles 正式配置路径；默认 profile 名为 `sub2api`、模型为 `gpt-5.5`，优先使用 G14 k3s 内 Sub2API ClusterIP 作为 `base_url`，并只记录 SecretRef、keyPresence、hash suffix 和原入口验收结果。
|
||||
当明确需要把当前 operator 的 Codex 凭据作为 AgentRun 动态 profile 提供给 HWLAB Code Agent 或 CaseRun 使用时，固定操作手册在 `$hwlab-code-agent` 的 `AgentRun 动态 sub2api profile` 小节。该场景是 AgentRun runtime profile 投影，不替代上面的 HWLAB provider-profiles 正式配置路径；默认 profile 名为 `sub2api`、模型为 `gpt-5.5`，优先使用 NC01 k3s 内受控 Sub2API ClusterIP 作为 `base_url`，并只记录 SecretRef、keyPresence、hash suffix 和原入口验收结果。
|
||||
|
||||
`config.toml` 和 Codex `auth.json` 是两个独立输入。`set-config <profile> --config-stdin` 写入 profile 的 Codex 配置文本；`set-auth-json <profile> --auth-json-stdin` 写入完整 Codex auth JSON object，并在 AgentRun runtime Secret 中作为 `auth.json` key 保留。`set-key --key-stdin` 只用于单值 API key profile；当输入本来就是 Codex `auth.json` 时，不得再把它压扁、拆成单个 key、改走 legacy API-key-only 路径或保留旧断言阻塞提交。遇到 CLI 不支持完整 auth JSON、输出不可见或缺少 hash/keyPresence 等证据时，先补 HWLAB CLI/API 和 AgentRun provider-profile 能力，再继续试机。
|
||||
|
||||
@@ -220,113 +213,12 @@ CaseRun 的 case/registry/aggregate、评价、回放、训练反馈和硬件证
|
||||
|
||||
CaseRun skill 交付边界按 `docs/reference/agentrun.md#agentrun--hwlab-协同职责边界` 判定：专用 skill 通过 AgentRun `gitbundle` 装配给 Code Agent，subject repo 不能携带 `.agents/skills` 副本。关闭要求涉及 skill 的 case 时，除 runId、traceId、provider profile 和 registry commit 外，还应记录 `resourceBundlePolicy`、实际装配的 skill 名、AgentRun/CaseRun 归档中的 skill 读取证据，以及 subject repo diff 或 artifact 中没有新增 `.agents/skills` 的负向检索结果。
|
||||
|
||||
CaseRun `summary.md`、`result.json` 和 registry aggregate 是阅读索引，不是替代原始执行证据的判定器。若 summary 中的 build/download/UART 字段与 AgentRun trace、HWPOD command output、Keil job、下载日志或 UART 输出不一致，应先用原始 trace rows、terminal command id、硬件命令输出和串口证据收口当前用户问题，同时把 summary/aggregate 语义缺口提到拥有该契约的仓库继续修复。D601 硬件 case 的 UART 证据必须来自当前 run 的串口输出；`serial-monitor` 服务或 Windows wrapper 不可用时，应先恢复或登记基础设施问题，不能把串口不可见误判为 subject 源码失败。
|
||||
CaseRun `summary.md`、`result.json` 和 registry aggregate 是阅读索引，不是替代原始执行证据的判定器。若 summary 中的 build/download/UART 字段与 AgentRun trace、HWPOD command output、Keil job、下载日志或 UART 输出不一致，应先用原始 trace rows、terminal command id、硬件命令输出和串口证据收口当前用户问题，同时把 summary/aggregate 语义缺口提到拥有该契约的仓库继续修复。NC01 硬件 case 的 UART 证据必须来自当前 run 的串口输出；`serial-monitor` 服务或 Windows wrapper 不可用时，应先恢复或登记基础设施问题，不能把串口不可见误判为 subject 源码失败。
|
||||
|
||||
### D601 v0.3 Web CaseRun 最小闭环
|
||||
### NC01 v0.3 Web CaseRun 最小闭环
|
||||
|
||||
D601 `v03` 的 Web CaseRun 最小闭环是 Cloud Web -> Cloud Web proxy -> Cloud API `/v1/caserun*` -> built-in/configured case repo -> HWPOD node ops -> Python UI node/HWPOD -> Keil。验证 Web 用户入口时使用 UniDesk `bun scripts/cli.ts hwlab nodes web-probe script --node D601 --lane v03`，让 `config/hwlab-node-lanes.yaml` 中的 `webProbe.defaultOrigin` 选择内部 IP 或公网入口；只有显式临时覆盖时才传 `--url`，不要把内部 IP 写进脚本或 issue 作为长期默认。
|
||||
NC01 `v03` 的 Web CaseRun 最小闭环是 Cloud Web -> Cloud Web proxy -> Cloud API `/v1/caserun*` -> built-in/configured case repo -> HWPOD node ops -> Python UI node/HWPOD -> Keil。验证 Web 用户入口时使用 UniDesk `bun scripts/cli.ts hwlab nodes web-probe script --node NC01 --lane v03`，让 `config/hwlab-node-lanes.yaml` 中的 `webProbe.defaultOrigin` 选择内部 IP 或公网入口；只有显式临时覆盖时才传 `--url`，不要把内部 IP 写进脚本或 issue 作为长期默认。
|
||||
|
||||
Web-probe short script 仍受 60s 级别的交互超时约束；长 CaseRun 应拆成“启动 run”和“轮询 run”两段，或使用 observe/专用归档入口承接下载、UART 和 Arm2D stage D 这类长证据链。Cloud Web 对 GET `/v1/*` 可以走通用代理，但 POST/写操作必须在 Cloud Web route policy 中显式登记认证代理路由；新增 CaseRun 写入口时不能只验证 Cloud API 直连。
|
||||
|
||||
当前 Web smoke case 使用 `d601-f103-v2-compile` 的 Keil compile-only 能力。关闭 D601/v03 Web CaseRun compile-only 问题时，证据至少记录 runId、registry aggregate sha256、Keil jobId、`hwpodExitCode`、`.hex`/`.axf` artifact、YAML 选中的 origin、HWLAB source revision 和 GitOps revision。compile-only 不要求下载日志、UART 输出或 AgentRun traceId；需要这些硬件证据时按 `pikasTech/HWLAB#2120` 和 `pikasTech/HWLAB#2121` 继续扩展，不要把 compile-only smoke 误判为完整下载/UART/Arm2D 闭环。
|
||||
|
||||
## D601 Legacy HWLAB DEV CD Wrapper
|
||||
|
||||
以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口，只用于显式 legacy 诊断和迁移对照。当前 HWLAB 发布、GitOps 和运行面收敛必须优先按 issue/CLI 选中的 node/lane 与 HWLAB repo-owned 规则执行；不要把下面的 D601 legacy wrapper 当作 D601 `v0.3` 或其他当前 HWLAB release truth。
|
||||
|
||||
本节里的 `deploy/deploy.json` 只属于 D601 legacy DEV CD wrapper。当前 node/lane 的部署配置源以 HWLAB repo 和 UniDesk YAML 声明为准，并由对应 format-agnostic config layer 读取；不要把 legacy `deploy/deploy.json` 当作 D601 `v0.3` truth。
|
||||
|
||||
UniDesk 指挥侧固定入口：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts hwlab cd status --env dev
|
||||
bun scripts/cli.ts hwlab cd audit --env dev
|
||||
bun scripts/cli.ts hwlab cd preflight --env dev
|
||||
bun scripts/cli.ts hwlab cd apply --env dev --dry-run
|
||||
```
|
||||
|
||||
wrapper 的职责是把 host commander 常用的 HWLAB DEV rollout 查看/准备动作收敛到单一入口。默认路径通过 UniDesk main-server frontend/backend-core 的 provider `host.ssh` 能力进入 D601；frontend transport 先用多个短 `host.ssh` 命令把远端 runner 分块上传到 `/tmp/unidesk-hwlab-cd/`，再在 D601 上执行有界检查脚本，避免 provider-gateway 的短命令长度限制成为审计入口单点故障。经 frontend/backend-core 返回的 stdout 只允许承载短 JSON 摘要；完整结果必须写入 D601 `~/.state/unidesk-hwlab-cd/<run-id>/result.full.json`，防止 backend JSON 安全摘要把 stdout 截断后导致 CLI 失明。它只调用 HWLAB repo-owned 受控脚本，不在 UniDesk 内重写发布流程或拼接 ad hoc `kubectl apply`：
|
||||
|
||||
- 默认 HWLAB CD repo 是每次运行在 D601 `~/.state/unidesk-hwlab-cd/<run-id>/ephemeral-repo/HWLAB` 新建的一次性 clone。一次性 repo 只从专用 full bare cache `~/.cache/unidesk/hwlab-cd/git-cache/HWLAB.git` 拷贝生成，必须使用 `--no-hardlinks` 形成独立 `.git` 对象库，不能通过 `--shared` 或 alternates 在运行时依赖 cache 对象库。cache 本身只允许作为 HWLAB CD 专用 Git 加速源，不承载 runner workspace、部署副本、手工改代码、报告留痕或任何其他用途。
|
||||
- 专用 cache 由当前 `host.ssh` 执行用户拥有，`~/.cache/unidesk/hwlab-cd` 必须保持 owner-only 权限；owner 不匹配、不可写或权限收紧失败时返回结构化 blocker。cache 初始化可以从本机已有 HWLAB clone seed 一次性拷贝，但 seed 只能用于降低首次出网成本，不能作为 release truth。cache remote 固定优先 `git@github.com:pikasTech/HWLAB.git`，GitHub 出网通过 D601 provider egress proxy `127.0.0.1:18789` 和 SSH `ProxyCommand`。cache 必须保存 full bare repo 历史，而不是 depth=1 浅缓存；wrapper 需要能解析 `refs/heads/main:deploy/deploy.json` 指向的 promotion commit，浅缓存即使 main HEAD 一致也不能证明 CD desired-state 完整。若 GitHub refresh 失败但本地 full cache 同时满足 main HEAD 和 deploy promotion commit，可作为 stale-cache 诊断继续读数，但必须暴露 `hwlab-cache-refresh` blocker，不能伪装成 release-truth PASS。
|
||||
- 一次性 repo 是当前 `host.ssh` 执行用户创建的临时发布读数，避免长期 `/home/ubuntu/hwlab_cd` 被 root 或其他 runner owner 污染后成为 CD 单点故障。`--hwlab-repo` 或 `UNIDESK_HWLAB_REPO` 仍可显式指定同等干净 clone 供人工诊断；被指定的 clone 必须由执行用户拥有并可读写。root-owned 或其他用户拥有的 clone 会触发 Git dubious ownership、`FETCH_HEAD` 不可写和 `.git/worktrees` 权限 blocker。修复 owner 污染应重建或显式修正 mirror 权限，不能用 `git config --global safe.directory` 掩盖发布真相污染。wrapper 必须检查 `git status --short --branch`、origin remote、当前 branch `main`、本地 `origin/main`、`FETCH_HEAD` 和 worktree 权限；任何 dirty worktree、错误 remote、非 main、HEAD 未跟上本地 `origin/main` 或权限异常都返回结构化 blocker。`/home/ubuntu/hwlab` 是 runner 历史目录，不得作为发布真相。
|
||||
- `deploy/deploy.json` 是唯一 desired-state。wrapper 只把 `deploy/artifact-catalog.dev.json`、`deploy/k8s/base/workloads.yaml` 和 `reports/dev-gate/dev-artifacts.json` 当作派生/证据读数；`status`/`preflight` 必须显示 target commit/ref、deploy.json、artifact catalog、workloads 和 live workload image 是否同源/收敛，不引入第二套 desired state。
|
||||
- `status` 只读汇总 HWLAB repo path、Git clean/main/origin-main、desired-state 收敛、D601 native k3s guard 和 `Lease/hwlab-dev/hwlab-dev-cd-lock`；同时调用 HWLAB `scripts/dev-cd-apply.mjs --status --skip-live-verify` 取得 repo-owned target/promotion/deploy.json/artifact 摘要。16666/16667 live verification 不由本 runner 执行。
|
||||
- `audit` 是 DEV CD 恢复后的只读健康审计，不是验收 gate 或报告生成器。它在 `status` 受控路径上补充只读 `kubectl get`/HTTP health probes，输出有界 JSON summary，分类 `control-plane-unavailable`、`docker-desktop-context-risk`、`second-control-plane-risk`、`workspace-unavailable`、`dirty-worktree`、`secret-missing`、`registry-unavailable`、`lease-held`、`lease-stale-candidate`、`artifact-missing`、`artifact-mismatch`、`runtime-job-blocked`、`rollout-unhealthy`、`public-tunnel-unhealthy` 和 `db-runtime-durability-risk`。audit 只显示 Secret 对象/key 是否存在，不显示值；只读判断 Lease 是否 stale，不释放或 break；只读拉取 16666/16667 `/health/live` 的 commit/readiness 摘要，不把它当作 M3 DEV-LIVE 验收。
|
||||
- `preflight` 在 `status` 的基础上检查 apply 前 SecretRef：`hwlab-cloud-api-dev-db/database-url`、`hwlab-cloud-api-dev-db-admin/admin-url`、`hwlab-code-agent-provider/openai-api-key`。只验证 Secret 对象和 key 元数据存在性，缺失时返回 blocker、影响范围和修复 runbook；禁止读取或打印 Secret value。
|
||||
- `apply --dry-run` 调用 HWLAB `scripts/dev-cd-apply.mjs --dry-run --kubeconfig /etc/rancher/k3s/k3s.yaml --skip-live-verify`，只生成受控事务准备/阻塞摘要，不做真实 apply、rollout、Lease mutation 或 live verification。历史 `scripts/dev-deploy-apply.mjs` 可作为 HWLAB 内部支持脚本出现，但 UniDesk wrapper 不能把它当成平行 CD 入口。
|
||||
- 完整下游 stdout/stderr 和 kubectl 读命令输出写入 D601 `~/.state/unidesk-hwlab-cd/<run-id>/`，UniDesk 本地仅保存 provider task stdout/stderr dump；CLI stdout 只显示有界摘要和 dump path。
|
||||
- wrapper 显式注入 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 并以这个显式目标作为唯一 gate：目标 context/server/nodes 若出现 `docker-desktop`、`desktop-control-plane` 或 `127.0.0.1:11700` 必须拒绝继续，写操作计划或 `apply --dry-run` 前目标 nodes 必须包含 `d601`。裸 `kubectl` 默认 context 只作为诊断输出；即使默认 kubeconfig 仍残留 Docker Desktop，只要显式 D601 kubeconfig 通过，也不能把默认 context 当成 CD blocker。
|
||||
|
||||
真实 DEV apply 只允许 host commander 在明确授权后执行。UniDesk wrapper 可以展示受控命令形状：
|
||||
|
||||
```sh
|
||||
node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production --write-report --kubeconfig /etc/rancher/k3s/k3s.yaml
|
||||
```
|
||||
|
||||
本 Code Queue runner 没有 `ROLLOUT_OK` 时不得执行真实 apply、rollout、CD lock 竞争或 live health 复验。
|
||||
|
||||
## HWLAB 热修边界
|
||||
|
||||
当 HWLAB DEV runtime 的 Secret、环境变量、rollout、DNS、egress 或 provider 权限缺口阻塞业务闭环，并且 Code Queue runner 无法安全完成对应运行态操作时，UniDesk 指挥官只能承担指挥入口、授权确认、监督验收和误判边界收敛。UniDesk reference 可以记录“哪些状态不能被误判”和“哪些动作必须上收”，但不能成为 HWLAB runtime truth。
|
||||
|
||||
这类热修必须满足以下边界：
|
||||
|
||||
- 先确认用户或项目负责人已授权具体运行态修复范围；没有授权时只做只读诊断、issue 记录和修复方案准备。
|
||||
- 证据只记录对象名、状态、revision、健康结果和已脱敏差异；不得把 Secret 值、token、可复用凭证命令或完整敏感 env 输出写入 issue、PR、日志或文档。
|
||||
- live Secret、env、ConfigMap、Deployment patch 或 rollout 结果只能作为临时恢复证据，不能成为长期部署真相。
|
||||
- HWLAB runtime truth 必须回写到 HWLAB 仓库自己的 issue、`AGENTS.md`、`docs/reference/`、部署配置或 secret 管理入口；UniDesk 只保留指挥侧边界和交叉引用。
|
||||
- 热修后必须说明 durable source fix 如何进入 HWLAB 的 CLI、manifest、选中 node/lane 的配置/CI/CD/GitOps 路径，或显式 D601 legacy `deploy/deploy.json`；如果尚未完成，要保留 HWLAB issue 追踪。
|
||||
|
||||
## D601 Legacy Cloud Web 手动 DEV 发布路径
|
||||
|
||||
以下路径是 D601 legacy DEV 的历史手动发布基准，只用于迁移对照或显式 D601 回滚排障。当前 HWLAB 发布必须优先按 issue/CLI 选中的 node/lane、对应 GitOps 和 HWLAB repo-owned 规则执行；不要把这里的 D601 legacy 命令当作 D601 `v0.3` 发布入口。
|
||||
|
||||
1. 更新 D601 部署副本：
|
||||
|
||||
```sh
|
||||
trans D601 'cd /home/ubuntu/workspace/hwlab && git pull --ff-only origin main'
|
||||
```
|
||||
|
||||
2. 刷新 Cloud Web 静态构建产物。运行时 wrapper 优先读取 `web/hwlab-cloud-web/dist`，如果该目录残留旧内容，即使源码已经更新，镜像仍可能继续服务旧页面：
|
||||
|
||||
```sh
|
||||
trans D601 'cd /home/ubuntu/workspace/hwlab && node web/hwlab-cloud-web/scripts/build.mjs'
|
||||
```
|
||||
|
||||
3. 发布镜像到 D601 本地 registry：
|
||||
|
||||
```sh
|
||||
trans D601 'cd /home/ubuntu/workspace/hwlab && node scripts/dev-artifact-publish.mjs --publish --services hwlab-cloud-web --report reports/dev-gate/dev-artifacts-hwlab-cloud-web-<tag>.json'
|
||||
```
|
||||
|
||||
4. 在滚动前用一次本地容器探针确认镜像内容，不把 commit tag 等同于页面内容：
|
||||
|
||||
```sh
|
||||
trans D601 'docker run --rm -d --name hwlab-cloud-web-probe -p 127.0.0.1:18088:8080 127.0.0.1:5000/hwlab/hwlab-cloud-web:<tag> && sleep 1 && curl -fsS http://127.0.0.1:18088/health/live && curl -fsS http://127.0.0.1:18088/ | sed -n "1,40p"; docker rm -f hwlab-cloud-web-probe'
|
||||
```
|
||||
|
||||
5. 滚动 D601 原生 k3s：
|
||||
|
||||
```sh
|
||||
trans D601 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev set image deployment/hwlab-cloud-web hwlab-cloud-web=127.0.0.1:5000/hwlab/hwlab-cloud-web:<tag> && KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev rollout status deployment/hwlab-cloud-web --timeout=180s'
|
||||
```
|
||||
|
||||
6. 用公网入口验收：
|
||||
|
||||
```sh
|
||||
curl -fsS http://74.48.78.17:16666/health/live
|
||||
curl -fsS http://74.48.78.17:16666/ | sed -n '1,80p'
|
||||
curl -fsS http://74.48.78.17:16666/styles.css | rg 'overflow: hidden|100dvh'
|
||||
```
|
||||
|
||||
验收时必须同时看 `health/live` 的 revision、HTML 语言/标题和 CSS 外层滚动锁定。不能只看镜像 tag 或 deployment 镜像字段。
|
||||
|
||||
## 监督原则
|
||||
|
||||
- HWLAB 派单 prompt 必须自包含，并在开头引用 `DC-DCSN-P0-2026-003`，说明任务服务 M3 闭环的哪一环。
|
||||
- `SOURCE`、`LOCAL`、`DRY-RUN`、fixture 或只读报告不能被当作 `DEV-LIVE`。真正的 M3 DEV-LIVE 需要证明 `res_boxsimu_1:DO1 -> hwlab-patch-panel -> res_boxsimu_2:DI1` 并带有 operation、audit、evidence 链。
|
||||
- 前端体验、Cloud Workbench polish、Gate 页面、诊断页和发布路径修复都是支撑任务，不等同于 M3 PASS。
|
||||
- 指挥官可以手动处理 PR 冲突和最终合并判断；runner 不应承担复杂冲突合并。
|
||||
- 任何临时手动上线或绕行都要回写 HWLAB issue 与 HWLAB 长期参考文档，并标明后续如何收敛到 CLI、选中 node/lane 的配置/CI/CD/GitOps 路径、显式 D601 legacy `deploy/deploy.json` 或等价发布路径。
|
||||
- HWLAB Secret/env/rollout 热修按本文“HWLAB 热修边界”和 `docs/reference/devops-hygiene.md` 执行；UniDesk 侧只沉淀边界，HWLAB 侧沉淀运行真相。
|
||||
当前 Web smoke case 使用 NC01 lane 声明的 Keil compile-only 能力。关闭 NC01/v03 Web CaseRun compile-only 问题时，证据至少记录 runId、registry aggregate sha256、Keil jobId、`hwpodExitCode`、`.hex`/`.axf` artifact、YAML 选中的 origin、HWLAB source revision 和 GitOps revision。compile-only 不要求下载日志、UART 输出或 AgentRun traceId；需要这些硬件证据时按 `pikasTech/HWLAB#2120` 和 `pikasTech/HWLAB#2121` 继续扩展，不要把 compile-only smoke 误判为完整下载/UART/Arm2D 闭环。
|
||||
|
||||
Reference in New Issue
Block a user