mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: pin hwlab and agentrun to nc01

Browse Source
This commit is contained in:
Codex
2026-07-09 09:29:32 +02:00
parent d7f9967f68
commit 8de8ac3691
8 changed files with 176 additions and 2100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+2 -7
View File
@@ -57,15 +57,10 @@ UniDesk 以主 server 为统一入口。本文件只做自动加载的顶级索
## P0: HWLAB、AgentRun 与节点边界
- P0: HWLAB 目标选择以 issue/CLI 明确的 lane+node 为准；无明确目标时才读取 `config/hwlab-node-lanes.yaml`。node、lane、workspace、namespace、GitOps path、Secret sourceRef 和 route 都以 YAML 为 source of truth。细则见 `docs/reference/hwlab.md`。
- P0: 每次开始 HWLAB node/lane 或 D601 UniDesk 分布式开发，必须先解析目标 node/lane，读取目标 workspace 的 `AGENTS.md`，并以该仓库规则为准。
- P0: D601 node-scoped HWLAB v0.3 不是 legacy；D601 legacy 只用于明确指定的旧 DEV/迁移/回滚对照路径。D601 k3s 操作使用 route `D601:k3s`，不得依赖裸 `kubectl` 默认 context。
- P0: D518 HWLAB v0.3 固定主 workspace 是 `D518:/home/ubuntu/workspace/hwlab-v03`；源码/PR/rollout 修复必须在该路径下从最新 `github/v0.3` 创建独立 `.worktree/<task>`，不得用 master server 或本机 `/root/HWLAB` 代替。
- P0: HWLAB 开发和部署固定只使用 NC01：固定 workspace 是 `NC01:/root/hwlab`，k3s route 是 `NC01:k3s`，配置真相是 `config/hwlab-node-lanes.yaml`。细则见 `docs/reference/hwlab.md`。
- P0: BK7258 项目/苗总项目/飞思创/脚本适配/中间件适配/MicroPython 相关材料常用目录是 `D518:D:\Work\HWLabOA\Project Management\[EPIC002][MIAO][PRJ001][BK7258]\`，进入后先读 `D002001001-SUMMARY.md`。
- P0: JD01 HWLAB v0.3 固定主 workspace 是 `JD01:/root/workspace/hwlab-v03`；源码/PR/rollout 修复必须在该路径下从最新 `github/v0.3` 创建独立 `.worktree/<task>`。
- P0: JD01 HWLAB v0.3 出网/拉取以 YAML host-route/host-proxy 为准；故障先修 host proxy，不换源绕过；不要把 JD01 MDTODO/Cloud Web 任务默认归因或切到 Sub2API。
- P0: D601 UniDesk 固定开发 workspace 是 `/home/ubuntu/workspace/unidesk-dev`；源码/配置任务先从最新 `origin/master` 创建独立 worktree。细则见 `docs/reference/dev-environment.md`。
- P0: AgentRun 是共享 Agent 执行基础设施；source-truth、lane、k3s route、gitbundle checkout authority、session policy 和 AipodSpec SecretRef 规则见 `docs/reference/agentrun.md`。
- P0: AgentRun 开发和部署固定只使用 NC01：固定 workspace 是 `NC01:/root/agentrun`，k3s route 是 `NC01:k3s`，配置真相是 `config/agentrun.yaml`。细则见 `docs/reference/agentrun.md`。
## P0: HWLAB API key 与 issue 关闭
config/agentrun.yaml
+3 -1018
View File
File diff suppressed because it is too large Load Diff
config/hwlab-node-lanes.yaml
+11 -802
View File
@@ -3,40 +3,12 @@ kind: HwlabNodeLaneConfig
metadata:
name: hwlab-node-lanes
defaults:
node: G14
node: NC01
lane: v03
requiredNoProxy:
- hyueapi.com
- .hyueapi.com
nodes:
G14:
route: G14
kubeRoute: G14:k3s
sourceWorkspace: /root/hwlab
gitopsRoot: deploy/gitops/node
networkProfile: node-ci-egress
downloadProfile: node-default
D601:
route: D601
kubeRoute: D601:k3s
sourceWorkspace: /home/ubuntu/workspace/hwlab-v03
gitopsRoot: deploy/gitops/node
networkProfile: d601-node-ci-egress
downloadProfile: d601-node-default
D518:
route: D518
kubeRoute: D518:k3s
sourceWorkspace: /home/ubuntu/workspace/hwlab-v03
gitopsRoot: deploy/gitops/node
networkProfile: d518-node-ci-egress
downloadProfile: d518-node-default
JD01:
route: JD01
kubeRoute: JD01:k3s
sourceWorkspace: /root/workspace/hwlab-v03
gitopsRoot: deploy/gitops/node
networkProfile: jd01-node-ci-egress
downloadProfile: jd01-node-default
NC01:
route: NC01
kubeRoute: NC01:k3s
@@ -45,47 +17,9 @@ nodes:
networkProfile: jd01-node-ci-egress
downloadProfile: jd01-node-default
lanes:
v02:
node: G14
minor: 2
version: v0.2
sourceBranch: v0.2
workspace: /root/hwlab-v02
cicdRepo: /root/hwlab-v02-cicd.git
cicdRepoLock: /tmp/hwlab-v02-cicd-repo.lock
app: hwlab-g14-v02
pipeline: hwlab-v02-ci-image-publish
pipelineRunPrefix: hwlab-v02-ci-poll
serviceAccountName: hwlab-v02-tekton-runner
controlPlaneFieldManager: unidesk-hwlab-v02-control-plane
git:
url: git@github.com:pikasTech/HWLAB.git
readUrl: http://git-mirror-http.devops-infra.svc.cluster.local/pikasTech/HWLAB.git
writeUrl: http://git-mirror-write.devops-infra.svc.cluster.local/pikasTech/HWLAB.git
gitopsBranch: v0.2-gitops
catalogPath: deploy/artifact-catalog.v02.json
runtime:
path: deploy/gitops/g14/runtime-v02
namespace: hwlab-v02
renderDir: runtime-v02
tektonDir: tekton-v02
argoApplicationFile: application-v02.yaml
registryPrefix: 127.0.0.1:5000/hwlab
baseImage: 127.0.0.1:5000/hwlab/hwlab-node20-base:20-bookworm-slim
serviceIds:
- hwlab-cloud-api
- hwlab-cloud-web
- hwlab-gateway
- hwlab-edge-proxy
- hwlab-agent-skills
observability:
prometheusOperator: true
public:
webUrl: http://74.48.78.17:19666
apiUrl: http://74.48.78.17:19667
v03:
node: G14
activeTarget: JD01
node: NC01
activeTarget: NC01
minor: 3
version: v0.3
sourceBranch: v0.3
@@ -99,7 +33,7 @@ lanes:
stageRefPrefix: "refs/unidesk/snapshots/hwlab-node-runtime/{branch}"
missingObjectPolicy: fail-fast
refreshPolicy: sync-before-snapshot
workspace: /root/hwlab-v03
workspace: /root/hwlab
cicdRepo: /root/hwlab-v03-cicd.git
cicdRepoLock: /tmp/hwlab-v03-cicd-repo.lock
app: hwlab-node-v03
@@ -139,7 +73,7 @@ lanes:
bootstrapAdmin:
username: admin
displayName: HWLAB v0.3 Admin
passwordSourceRef: hwlab/g14-v03-bootstrap-admin.env
passwordSourceRef: hwlab/nc01-v03-bootstrap-admin.env
passwordSourceKey: HWLAB_BOOTSTRAP_ADMIN_PASSWORD
passwordHashTransform: hwlab-sha256
secretName: hwlab-v03-bootstrap-admin
@@ -147,734 +81,6 @@ lanes:
rollout:
deployment: hwlab-cloud-api
targets:
D601:
node: D601
workspace: /home/ubuntu/workspace/hwlab-v03
cicdRepo: /home/ubuntu/workspace/hwlab-v03-cicd.git
cicdRepoLock: /tmp/hwlab-v03-cicd-repo.lock
app: hwlab-node-v03
pipeline: hwlab-v03-ci-image-publish
pipelineRunPrefix: hwlab-v03-ci-poll
serviceAccountName: hwlab-v03-tekton-runner
controlPlaneFieldManager: unidesk-hwlab-d601-v03-control-plane
git:
url: git@github.com:pikasTech/HWLAB.git
readUrl: http://git-mirror-http.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
writeUrl: http://git-mirror-write.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
argo:
repoURL: http://git-mirror-http.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
gitopsBranch: v0.3-gitops
catalogPath: deploy/artifact-catalog.d601-v03.json
runtime:
path: deploy/gitops/node/d601/runtime-v03
namespace: hwlab-v03
renderDir: runtime-v03
runtimeStore:
postgres:
mode: local-k3s
secretName: hwlab-v03-postgres
statefulSet: hwlab-v03-postgres
serviceName: hwlab-v03-postgres
adminUser: hwlab_v03
adminPasswordSourceRef: hwlab/d601-v03-postgres.env
adminPasswordSourceKey: HWLAB_V03_POSTGRES_PASSWORD
cloudApi:
secretName: hwlab-cloud-api-v03-db
secretKey: database-url
database: hwlab_v03
role: hwlab_v03
openfga:
secretName: hwlab-v03-openfga
secretKey: datastore-uri
authnKey: authn-preshared-key
postgresPasswordKey: postgres-password
database: hwlab_openfga
role: hwlab_openfga
poolMax: 16
connectionTimeoutMs: 5000
queryRetryMaxAttempts: 5
queryRetryInitialDelayMs: 250
queryRetryMaxDelayMs: 5000
hwpodPreinstall:
enabled: true
configRefs:
preinstall: "config/hwlab-hwpod-preinstalls/constart-71freq-c.yaml#hwpodPreinstall"
projectManagementSource: "config/hwlab-project-management/constart-71freq-mdtodo.yaml#projectManagement.sources[0]"
gatewayProfile: "config/hwlab-gateway/constart-71freq-d601-v03.yaml#gateway.profile"
webProbe:
extends: templates.hwlabV03.webProbeWorkbench
tektonDir: tekton-v03
argoApplicationFile: application-v03.yaml
registryPrefix: 127.0.0.1:5000/hwlab
baseImage: 127.0.0.1:5000/hwlab/hwlab-node20-base:20-bookworm-slim
baseImageSource: node:20-bookworm-slim
serviceIds:
- hwlab-cloud-api
- hwlab-workbench-runtime
- hwlab-user-billing
- hwlab-project-management
- hwlab-cloud-web
- hwlab-gateway
- hwlab-edge-proxy
- hwlab-agent-skills
buildkit:
sidecarImage: 127.0.0.1:5000/hwlab/buildkit:rootless
sourceImage: docker.io/moby/buildkit:rootless
stepEnv:
HOME: /tekton/home
XDG_CONFIG_HOME: /tekton/home/.config
observability:
prometheusOperator: false
traceExplorerUrlTemplate: "/v1/workbench/traces/{trace_id}/events"
metricsEndpoint:
serviceName: hwlab-cloud-api
containerName: hwlab-cloud-api
port: 6667
scheme: http
path: /v1/web-performance/metrics
scrapeMode: pod-loopback
publicRawMetrics: denied
webProbe:
sentinels:
- id: workbench-dsflash-go-tool-call-10x
enabled: true
configRef: "config/hwlab-web-probe-sentinels/d601-v03/workbench-dsflash-go-tool-call-10x.yaml#sentinel"
- id: workbench-auth-session-switch-2users
enabled: true
configRef: "config/hwlab-web-probe-sentinels/d601-v03/workbench-auth-session-switch-2users.yaml#sentinel"
- id: mdtodo-visual-regression
enabled: true
configRef: "config/hwlab-web-probe-sentinels/d601-v03/mdtodo-visual-regression.yaml#sentinel"
workbench:
enabled: true
summaryPath: /v1/web-performance/summary
lowSampleThreshold: 5
metricPrefixes:
- hwlab_workbench_
- hwlab_agentrun_
- hwlab_webui_
- hwlab_http_
requiredSeries:
[]
backendLabelDenylist:
- unknown
maxUnknownEventLines: 0
recordingRules:
- id: workbench_submit_first_visible_p95
metric: hwlab:workbench_submit_first_visible:p95_seconds
sourceMetric: hwlab_workbench_journey_duration_seconds
quantile: 0.95
window: 5m
minSamples: 5
groupBy:
- namespace
- gitops_target
- journey
- route
- backend
- transport
- entry
- outcome
matchLabels:
journey: submit_to_first_visible
- id: workbench_backend_event_visible_p95
metric: hwlab:workbench_backend_event_visible:p95_seconds
sourceMetric: hwlab_workbench_backend_event_visible_latency_seconds
quantile: 0.95
window: 5m
minSamples: 5
groupBy:
- namespace
- gitops_target
- event_type
- backend
- transport
- outcome
- id: workbench_session_switch_p95
metric: hwlab:workbench_session_switch:p95_seconds
sourceMetric: hwlab_workbench_journey_duration_seconds
quantile: 0.95
window: 5m
minSamples: 5
groupBy:
- namespace
- gitops_target
- journey
- route
- target_state
- cache
- source
- outcome
matchLabels:
journey: session_switch_first_visible|session_switch_full_load
- id: workbench_open_p95
metric: hwlab:workbench_open:p95_seconds
sourceMetric: hwlab_workbench_journey_duration_seconds
quantile: 0.95
window: 5m
minSamples: 5
groupBy:
- namespace
- gitops_target
- journey
- route
- cache
- auth_state
- outcome
matchLabels:
journey: workbench_open_first_visible|workbench_open_full_load
- id: workbench_projection_lag_p95
metric: hwlab:workbench_projection_lag:p95_seconds
sourceMetric: hwlab_workbench_projection_lag_seconds
quantile: 0.95
window: 5m
minSamples: 1
groupBy:
- namespace
- gitops_target
- node
- lane
- projection_status
- source
- status
- reason
- id: workbench_terminal_projection_delay_p95
metric: hwlab:workbench_terminal_projection_delay:p95_seconds
sourceMetric: hwlab_workbench_terminal_projection_delay_seconds
quantile: 0.95
window: 5m
minSamples: 1
groupBy:
- namespace
- gitops_target
- node
- lane
- projection_status
- source
- status
- reason
- id: workbench_turn_get_p95
metric: hwlab:workbench_turn_get:p95_seconds
sourceMetric: hwlab_workbench_turn_get_duration_seconds
quantile: 0.95
window: 5m
minSamples: 1
groupBy:
- namespace
- gitops_target
- node
- lane
- route
- status
- degraded_reason
- id: agentrun_result_p95
metric: hwlab:agentrun_result:p95_seconds
sourceMetric: hwlab_agentrun_result_duration_seconds
quantile: 0.95
window: 5m
minSamples: 1
groupBy:
- namespace
- gitops_target
- node
- lane
- event_count_bucket
- status
- id: workbench_projector_batch_p95
metric: hwlab:workbench_projector_batch:p95_seconds
sourceMetric: hwlab_workbench_projector_batch_duration_seconds
quantile: 0.95
window: 5m
minSamples: 1
groupBy:
- namespace
- gitops_target
- node
- lane
- phase
- status
warningAlerts:
- id: HWLABWorkbenchSubmitFirstVisibleSlow
ruleId: workbench_submit_first_visible_p95
severity: warning
thresholdSeconds: 15
minSamples: 5
for: 10m
matchLabels:
journey: submit_to_first_visible
- id: HWLABWorkbenchBackendEventVisibleSlow
ruleId: workbench_backend_event_visible_p95
severity: warning
thresholdSeconds: 10
minSamples: 5
for: 10m
- id: HWLABWorkbenchSessionSwitchSlow
ruleId: workbench_session_switch_p95
severity: warning
thresholdSeconds: 8
minSamples: 5
for: 10m
- id: HWLABWorkbenchOpenSlow
ruleId: workbench_open_p95
severity: warning
thresholdSeconds: 13
minSamples: 5
for: 10m
- id: WorkbenchProjectionStuck
ruleId: workbench_projection_lag_p95
severity: warning
thresholdSeconds: 60
minSamples: 1
for: 10m
- id: WorkbenchTerminalProjectionMissing
ruleId: workbench_terminal_projection_delay_p95
severity: warning
thresholdSeconds: 60
minSamples: 1
for: 10m
- id: WorkbenchTurnReadSlow
ruleId: workbench_turn_get_p95
severity: warning
thresholdSeconds: 5
minSamples: 1
for: 10m
- id: AgentRunResultSlowLongTrace
ruleId: agentrun_result_p95
severity: warning
thresholdSeconds: 2.5
minSamples: 1
for: 10m
- id: WorkbenchProjectorNoProgress
ruleId: workbench_projector_batch_p95
severity: warning
thresholdSeconds: 10
minSamples: 1
for: 10m
runtimeImageRewrites:
- extends: templates.hwlabV03.runtimeImageRewrites.frpc
- extends: templates.hwlabV03.runtimeImageRewrites.openfga
runtimeImageBuilds:
- extends: templates.hwlabV03.runtimeImageBuilds.moonbridge
- extends: templates.hwlabV03.runtimeImageBuilds.opencodeGit
public:
webUrl: https://hwlab.pikapython.com
apiUrl: https://hwlab.pikapython.com
bootstrapAdmin:
username: admin
displayName: HWLAB v0.3 Admin
passwordSourceRef: hwlab/d601-v03-bootstrap-admin.env
passwordSourceKey: HWLAB_BOOTSTRAP_ADMIN_PASSWORD
passwordHashTransform: hwlab-sha256
secretName: hwlab-v03-bootstrap-admin
secretKey: password-hash
rollout:
deployment: hwlab-cloud-api
publicExposure:
extends: templates.hwlabV03.publicExposurePk01
frpc:
webProxy:
remotePort: 22096
apiProxy:
remotePort: 22095
externalPostgres:
extends: templates.hwlabV03.externalPostgresConsumer
provider: PK01
configRef: config/platform-db/postgres-pk01.yaml
serviceName: d601-pk01-platform-postgres
endpointAddress: 82.156.23.220
runtimeAccess:
routeName: d601-pk01-postgres
endpointAddress: d601-tcp-egress-gateway.unidesk.svc.cluster.local
port: 25432
database: hwlab_d601_v03
cloudApi:
sourceRef: hwlab/d601-v03-cloud-api-db.env
role: hwlab_d601_v03_app
openfga:
sourceRef: hwlab/d601-v03-openfga-db.env
role: hwlab_d601_v03_app
variables:
LANE: v03
NODE: D601
D518:
node: D518
workspace: /home/ubuntu/workspace/hwlab-v03
sourceWorkspace:
requiredCommands:
- git
- node
- npm
- npx
requiredFiles:
- AGENTS.md
- package.json
- package-lock.json
- scripts/src/browser-launcher.mjs
- scripts/web-live-dom-probe.mjs
install:
executor: k3s-job
dependencyCommand: npm ci
browserCommand: PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install chromium
timeoutSeconds: 900
cicdRepo: /home/ubuntu/workspace/hwlab-v03-cicd.git
cicdRepoLock: /tmp/hwlab-v03-cicd-repo.lock
app: hwlab-node-v03
pipeline: hwlab-d518-v03-ci-image-publish
pipelineRunPrefix: hwlab-d518-v03-ci-poll
serviceAccountName: hwlab-d518-v03-tekton-runner
controlPlaneFieldManager: unidesk-hwlab-d518-v03-control-plane
git:
url: git@github.com:pikasTech/HWLAB.git
readUrl: http://git-mirror-http.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
writeUrl: http://git-mirror-write.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
argo:
repoURL: http://git-mirror-http.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
gitopsBranch: v0.3-gitops
catalogPath: deploy/artifact-catalog.d518-v03.json
runtime:
path: deploy/gitops/node/d518/runtime-v03
namespace: hwlab-v03
renderDir: runtime-v03
runtimeStore:
postgres:
mode: local-k3s
secretName: hwlab-v03-postgres
statefulSet: hwlab-v03-postgres
serviceName: hwlab-v03-postgres
adminUser: hwlab_v03
adminPasswordSourceRef: hwlab/d518-v03-postgres.env
adminPasswordSourceKey: HWLAB_V03_POSTGRES_PASSWORD
cloudApi:
secretName: hwlab-cloud-api-v03-db
secretKey: database-url
database: hwlab_v03
role: hwlab_v03
openfga:
secretName: hwlab-v03-openfga
secretKey: datastore-uri
authnKey: authn-preshared-key
postgresPasswordKey: postgres-password
database: hwlab_openfga
role: hwlab_openfga
poolMax: 16
connectionTimeoutMs: 5000
queryRetryMaxAttempts: 5
queryRetryInitialDelayMs: 250
queryRetryMaxDelayMs: 5000
webProbe:
extends: templates.hwlabV03.webProbeWorkbench
browserProxyMode: direct
browserFreezePolicy:
memory:
totalRssBlockerMb: 500
tektonDir: tekton-v03
argoApplicationFile: application-v03.yaml
registryPrefix: 127.0.0.1:5000/hwlab
baseImage: 127.0.0.1:5000/hwlab/hwlab-node20-base:20-bookworm-slim
baseImageSource: node:20-bookworm-slim
serviceIds:
- hwlab-cloud-api
- hwlab-workbench-runtime
- hwlab-user-billing
- hwlab-project-management
- hwlab-cloud-web
- hwlab-gateway
- hwlab-edge-proxy
- hwlab-agent-skills
buildkit:
sidecarImage: 127.0.0.1:5000/hwlab/buildkit:rootless
sourceImage: docker.io/moby/buildkit:rootless
stepEnv:
HOME: /tekton/home
XDG_CONFIG_HOME: /tekton/home/.config
observability:
prometheusOperator: false
webProbe:
monitorRoot:
enabled: true
sentinelId: workbench-fake-echo-session-invariance-10x
publicBaseUrl: https://monitor.pikapython.com
routePrefix: /
caddyManagedBlockOwner: hwlab-web-probe-sentinel-active-root
sentinels:
- id: workbench-dsflash-go-tool-call-10x
enabled: true
configRef: "config/hwlab-web-probe-sentinels/d518-v03/workbench-dsflash-go-tool-call-10x.yaml#sentinel"
- id: workbench-fake-echo-session-invariance-10x
enabled: true
configRef: "config/hwlab-web-probe-sentinels/d518-v03/workbench-fake-echo-session-invariance-10x.yaml#sentinel"
runtimeImageRewrites:
- extends: templates.hwlabV03.runtimeImageRewrites.frpc
- extends: templates.hwlabV03.runtimeImageRewrites.openfga
runtimeImageBuilds:
- extends: templates.hwlabV03.runtimeImageBuilds.moonbridge
- extends: templates.hwlabV03.runtimeImageBuilds.opencodeGit
public:
webUrl: https://hwlab.pikapython.com
apiUrl: https://hwlab.pikapython.com
bootstrapAdmin:
username: admin
displayName: HWLAB v0.3 Admin
passwordSourceRef: hwlab/d518-v03-bootstrap-admin.env
passwordSourceKey: HWLAB_BOOTSTRAP_ADMIN_PASSWORD
passwordHashTransform: hwlab-sha256
secretName: hwlab-v03-bootstrap-admin
secretKey: password-hash
rollout:
deployment: hwlab-cloud-api
codeAgentProvider:
secretName: hwlab-v03-code-agent-provider
sourceRef: hwlab/d518-v03-code-agent-provider.env
openaiSourceKey: OPENAI_API_KEY
opencodeSourceKey: OPENCODE_API_KEY
codeAgentRuntime:
enabled: true
adapter: agentrun-v02
managerUrl: http://agentrun-mgr.agentrun-v02.svc.cluster.local:8080
apiKeySecretName: hwlab-v03-master-server-admin-api-key
apiKeySecretKey: api-key
runnerNamespace: agentrun-v02
secretNamespace: agentrun-v02
repoUrlFrom: runtimeGitReadUrl
providerIdFrom: runtimeNodeId
defaultProviderProfile: fake-echo
codexStdioSupervisor: repo-owned
kafkaShadowProducer:
enabled: true
mode: shadow-produce-only
consumeEnabled: false
configRef: "config/platform-infra/kafka.yaml#clients.hwlab-v03-cloud-api"
bootstrapServers: platform-infra-kafka-kafka-bootstrap.platform-infra.svc.cluster.local:9092
commandTopic: hwlab.agentrun.command.v1
clientId: hwlab-v03-cloud-api
publicExposure:
extends: templates.hwlabV03.publicExposurePk01
frpc:
webProxy:
remotePort: 22092
apiProxy:
remotePort: 22091
externalPostgres:
extends: templates.hwlabV03.externalPostgresConsumer
provider: PK01
configRef: config/platform-db/postgres-pk01.yaml
serviceName: d518-pk01-platform-postgres
endpointAddress: 82.156.23.220
runtimeAccess:
routeName: d518-pk01-postgres
endpointAddress: d518-tcp-egress-gateway.unidesk.svc.cluster.local
port: 25432
database: hwlab_d518_v03
cloudApi:
sourceRef: hwlab/d518-v03-cloud-api-db.env
role: hwlab_d518_v03_app
openfga:
sourceRef: hwlab/d518-v03-openfga-db.env
role: hwlab_d518_v03_app
variables:
LANE: v03
NODE: D518
JD01:
node: JD01
workspace: /root/workspace/hwlab-v03
sourceAuthority:
extends: templates.hwlabV03.sourceAuthorityGiteaSnapshot
giteaMirrorRepoKey: hwlab-jd01-v03
sourceSnapshot:
extends: templates.hwlabV03.sourceSnapshotGiteaControlled
sourceWorkspace:
git:
remoteName: github
remoteUrl: git@github.com:pikasTech/HWLAB.git
identityTarget: JD01
identityId: github.com
proxyEnvPath: /etc/unidesk/proxy.env
verifyRemote: true
requireUpToDate: true
requiredCommands:
- git
- node
- npm
- npx
requiredFiles:
- AGENTS.md
- package.json
- package-lock.json
- scripts/src/browser-launcher.mjs
- scripts/web-live-dom-probe.mjs
hostDependencies:
checkCommands:
- git
- node
- npm
- npx
stateDir: /var/lib/unidesk/hwlab-source-workspace
install:
timeoutSeconds: 300
command: "set -eu\n. /etc/unidesk/proxy.env 2>/dev/null || true\nexport HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY http_proxy https_proxy all_proxy no_proxy\nnpm_version=11.17.0\ntmp_dir=$(mktemp -d)\ntrap 'rm -rf \"$tmp_dir\"' EXIT\ncurl -fsSL --retry 3 --connect-timeout 20 --max-time 300 \"https://registry.npmmirror.com/npm/-/npm-${npm_version}.tgz\" -o \"$tmp_dir/npm.tgz\"\nmkdir -p /usr/local/lib/node_modules\nrm -rf /usr/local/lib/node_modules/npm\ntar -xzf \"$tmp_dir/npm.tgz\" -C \"$tmp_dir\"\nmv \"$tmp_dir/package\" /usr/local/lib/node_modules/npm\nln -sfn /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm\nln -sfn /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx\nnpm --version\nnpx --version\n"
install:
executor: host
dependencyCommand: "set -eu\nnpm install --no-save --package-lock=false --ignore-scripts --no-audit --no-fund playwright@1.59.1\nif [ -n \"${HTTP_PROXY:-}\" ]; then\n cat >/etc/apt/apt.conf.d/99unidesk-host-proxy <<APT_PROXY\nAcquire::http::Proxy \"${HTTP_PROXY}\";\nAcquire::https::Proxy \"${HTTPS_PROXY:-$HTTP_PROXY}\";\nAcquire::Retries \"3\";\nAcquire::http::Timeout \"60\";\nAcquire::https::Timeout \"60\";\nAPT_PROXY\nfi\nfor apt_source in /etc/apt/sources.list /etc/apt/sources.list.d/*.list /etc/apt/sources.list.d/*.sources; do\n [ -f \"$apt_source\" ] || continue\n sed -i 's|http://mirrors.jdcloudcs.com/ubuntu|http://archive.ubuntu.com/ubuntu|g' \"$apt_source\"\ndone\nnpx playwright install-deps chromium\n"
browserCommand: PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install chromium
stateDir: /var/lib/unidesk/hwlab-source-workspace-install
timeoutSeconds: 900
cicdRepo: /root/workspace/hwlab-v03-cicd.git
cicdRepoLock: /tmp/hwlab-v03-cicd-repo.lock
app: hwlab-node-v03
pipeline: hwlab-jd01-v03-ci-image-publish
pipelineRunPrefix: hwlab-jd01-v03-ci-poll
serviceAccountName: hwlab-jd01-v03-tekton-runner
controlPlaneFieldManager: unidesk-hwlab-jd01-v03-control-plane
git:
url: git@github.com:pikasTech/HWLAB.git
readUrl: http://gitea-http.devops-infra.svc.cluster.local:3000/mirrors/pikasTech-HWLAB.git
writeUrl: http://git-mirror-write.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
argo:
repoURL: http://git-mirror-http.devops-infra.svc.cluster.local:8080/pikasTech/HWLAB.git
gitopsBranch: v0.3-gitops
catalogPath: deploy/artifact-catalog.jd01-v03.json
runtime:
path: deploy/gitops/node/jd01/runtime-v03
namespace: hwlab-v03
renderDir: runtime-v03
runtimeStore:
postgres:
mode: platform-service
secretName: hwlab-v03-postgres
statefulSet: hwlab-v03-postgres
serviceName: hwlab-v03-postgres
adminUser: hwlab_v03
adminPasswordSourceRef: hwlab/jd01-v03-postgres.env
adminPasswordSourceKey: HWLAB_V03_POSTGRES_PASSWORD
cloudApi:
secretName: hwlab-cloud-api-v03-db
secretKey: database-url
database: hwlab_v03
role: hwlab_v03
openfga:
secretName: hwlab-v03-openfga
secretKey: datastore-uri
authnKey: authn-preshared-key
postgresPasswordKey: postgres-password
database: hwlab_openfga
role: hwlab_openfga
poolMax: 16
connectionTimeoutMs: 5000
queryRetryMaxAttempts: 5
queryRetryInitialDelayMs: 250
queryRetryMaxDelayMs: 5000
webProbe:
extends: templates.hwlabV03.webProbeWorkbench
playwrightBrowsersPath: "0"
tektonDir: tekton-v03
argoApplicationFile: application-v03.yaml
registryPrefix: 127.0.0.1:5000/hwlab
baseImage: 127.0.0.1:5000/hwlab/hwlab-node20-base:20-bookworm-slim
baseImageSource: node:20-bookworm-slim
serviceIds:
- hwlab-cloud-api
- hwlab-workbench-runtime
- hwlab-user-billing
- hwlab-project-management
- hwlab-cloud-web
- hwlab-gateway
- hwlab-edge-proxy
- hwlab-agent-skills
buildkit:
sidecarImage: 127.0.0.1:5000/hwlab/buildkit:rootless
sourceImage: docker.io/moby/buildkit:rootless
stepEnv:
HOME: /tekton/home
XDG_CONFIG_HOME: /tekton/home/.config
observability:
prometheusOperator: false
webProbe:
monitorRoot:
enabled: true
sentinelId: jd01-web-probe-sentinel
publicBaseUrl: https://monitor.pikapython.com
routePrefix: /
caddyManagedBlockOwner: hwlab-web-probe-sentinel-active-root
sentinels:
- id: jd01-web-probe-sentinel
enabled: true
configRef: "config/hwlab-web-probe-sentinel/profiles.yaml#nodes.${NODE}.sentinels.${nodeLower}-web-probe-sentinel.sentinel"
runtimeImageRewrites:
- extends: templates.hwlabV03.runtimeImageRewrites.postgres
- extends: templates.hwlabV03.runtimeImageRewrites.frpc
- extends: templates.hwlabV03.runtimeImageRewrites.openfga
- extends: templates.hwlabV03.runtimeImageRewrites.opencode
runtimeImageBuilds:
- extends: templates.hwlabV03.runtimeImageBuilds.moonbridge
- extends: templates.hwlabV03.runtimeImageBuilds.opencodeGit
public:
webUrl: https://hwlab.pikapython.com
apiUrl: https://hwlab.pikapython.com
bootstrapAdmin:
username: admin
displayName: HWLAB v0.3 Admin
usernameSourceRef: .env/HWLAB_admin.txt
usernameSourceLine: 1
passwordSourceRef: .env/HWLAB_admin.txt
passwordSourceKey: HWLAB_ADMIN_PASSWORD
passwordSourceLine: 2
passwordHashTransform: hwlab-sha256
secretName: hwlab-v03-bootstrap-admin
secretKey: password-hash
rollout:
deployment: hwlab-cloud-api
codeAgentProvider:
secretName: hwlab-v03-code-agent-provider
sourceRef: hwlab/jd01-v03-code-agent-provider.env
openaiSourceKey: OPENAI_API_KEY
opencodeSourceKey: OPENCODE_API_KEY
codeAgentRuntime:
enabled: true
adapter: agentrun-v02
managerUrl: http://agentrun-mgr.agentrun-v02.svc.cluster.local:8080
apiKeySecretName: hwlab-v03-master-server-admin-api-key
apiKeySecretKey: api-key
runnerNamespace: agentrun-v02
secretNamespace: agentrun-v02
repoUrlFrom: runtimeGitReadUrl
providerIdFrom: runtimeNodeId
defaultProviderProfile: dsflash-go
codexStdioSupervisor: repo-owned
publicExposure:
extends: templates.hwlabV03.publicExposurePk01
frpc:
webProxy:
remotePort: 22090
apiProxy:
remotePort: 22088
extraProxies:
- id: opencode
name: hwlab-jd01-v03-opencode
remotePort: 22095
localIP: hwlab-cloud-web.hwlab-v03.svc.cluster.local
localPort: 8080
hostname: opencode-jd01-v03.pikapython.com
publicBaseUrl: https://opencode-jd01-v03.pikapython.com
cloudWebEnvName: HWLAB_CLOUD_WEB_OPENCODE_URL
externalPostgres:
extends: templates.hwlabV03.externalPostgresConsumer
provider: PK01
configRef: config/platform-db/postgres-pk01.yaml
serviceName: jd01-pk01-platform-postgres
endpointAddress: 82.156.23.220
runtimeAccess:
endpointAddress: 82.156.23.220
port: 5432
database: hwlab_jd01_v03
cloudApi:
sourceRef: hwlab/jd01-v03-cloud-api-db.env
role: hwlab_jd01_v03_app
openfga:
sourceRef: hwlab/jd01-v03-openfga-db.env
role: hwlab_jd01_v03_app
variables:
LANE: v03
NODE: JD01
NC01:
node: NC01
workspace: /root/hwlab
@@ -942,8 +148,11 @@ lanes:
bootstrapAdmin:
username: admin
displayName: HWLAB v0.3 Admin
passwordSourceRef: hwlab/nc01-v03-bootstrap-admin.env
passwordSourceKey: HWLAB_BOOTSTRAP_ADMIN_PASSWORD
usernameSourceRef: .env/hwlab.auth
usernameSourceLine: 1
passwordSourceRef: .env/hwlab.auth
passwordSourceKey: HWLAB_ADMIN_PASSWORD
passwordSourceLine: 2
passwordHashTransform: hwlab-sha256
secretName: hwlab-v03-bootstrap-admin
secretKey: password-hash
@@ -1458,4 +667,4 @@ templates:
sourceSnapshotGiteaControlled:
stageRefPrefix: "refs/unidesk/snapshots/gitea-actions/hwlab-node-runtime/{branch}"
missingObjectPolicy: fail-fast
refreshPolicy: gitea-controlled-snapshot
refreshPolicy: gitea-controlled-snapshot
docs/reference/agentrun.md
+39 -42
View File
@@ -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 物化问题。
docs/reference/hwlab.md
+46 -154
View File
@@ -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 闭环。
scripts/src/agentrun/entry.ts
+24 -24
View File
@@ -51,7 +51,7 @@ export function agentRunHelp(): unknown {
output: "human by default; use -o json|yaml or --raw for machine/debug output",
usage: [
"bun scripts/cli.ts agentrun get tasks --queue commander --limit 20",
"bun scripts/cli.ts agentrun describe run/<runId> --node D601 --lane v02",
"bun scripts/cli.ts agentrun describe run/<runId> --node NC01 --lane nc01-v02",
"bun scripts/cli.ts agentrun get tasks -o wide",
"bun scripts/cli.ts agentrun get tasks -o json",
"bun scripts/cli.ts agentrun describe task/<taskId>",
@@ -66,16 +66,16 @@ export function agentRunHelp(): unknown {
"bun scripts/cli.ts agentrun send session/<sessionId> --aipod Artificer --prompt-stdin",
"bun scripts/cli.ts agentrun explain task",
"bun scripts/cli.ts agentrun explain session-policy",
"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 status --node D601 --lane v02",
"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 secret-sync --node D601 --lane v02 --secret-id tool-github-pr-token --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 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 status --node NC01 --lane nc01-v02",
"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 secret-sync --node NC01 --lane nc01-v02 --secret-id tool-github-pr-token --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",
"bun scripts/cli.ts agentrun control-plane status --full",
"bun scripts/cli.ts agentrun control-plane status --pipeline-run <yaml-lane-pipelinerun>",
@@ -86,8 +86,8 @@ export function agentRunHelp(): unknown {
"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",
@@ -245,7 +245,7 @@ export function agentRunHelpText(args: string[]): string {
"Kinds: task|run|command|runnerjob|session|aipodspec",
"Examples:",
" bun scripts/cli.ts agentrun describe task/qt_...",
" bun scripts/cli.ts agentrun describe run/<runId> --node D601 --lane v02",
" bun scripts/cli.ts agentrun describe run/<runId> --node NC01 --lane nc01-v02",
" bun scripts/cli.ts agentrun describe command/cmd_... --run <runId>",
" bun scripts/cli.ts agentrun describe session/<sessionId> --full",
].join("\n");
@@ -284,17 +284,17 @@ export function agentRunHelpText(args: string[]): string {
"",
"Actions: plan, apply, status, secret-sync, expose, trigger-current, refresh, cleanup-runners, cleanup-runs, cleanup-session-pvcs, cleanup-local-postgres, cleanup-released-pvs",
"Examples:",
" 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 status --node D601 --lane v02",
" bun scripts/cli.ts agentrun control-plane secret-sync --node D601 --lane v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane trigger-current --node D601 --lane v02 --dry-run",
" 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 status --node NC01 --lane nc01-v02",
" bun scripts/cli.ts agentrun control-plane secret-sync --node NC01 --lane nc01-v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane trigger-current --node NC01 --lane nc01-v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane status",
" bun scripts/cli.ts agentrun control-plane status --pipeline-run <yaml-lane-pipelinerun>",
" bun scripts/cli.ts agentrun control-plane expose --dry-run",
" bun scripts/cli.ts agentrun control-plane trigger-current --dry-run",
" bun scripts/cli.ts agentrun control-plane cleanup-runners --node D601 --lane v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane cleanup-session-pvcs --node JD01 --lane jd01-v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane cleanup-runners --node NC01 --lane nc01-v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane cleanup-session-pvcs --node NC01 --lane nc01-v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane cleanup-local-postgres --node NC01 --lane nc01-v02 --dry-run",
" bun scripts/cli.ts agentrun control-plane cleanup-runs --min-age-minutes 30 --limit 200 --dry-run",
].join("\n");
@@ -313,7 +313,7 @@ export function agentRunHelpText(args: string[]): string {
"Use resource primitives for daily commander work:",
" bun scripts/cli.ts agentrun get tasks --queue commander --limit 20",
" bun scripts/cli.ts agentrun describe task/<taskId>",
" bun scripts/cli.ts agentrun describe run/<runId> --node D601 --lane v02",
" bun scripts/cli.ts agentrun describe run/<runId> --node NC01 --lane nc01-v02",
" bun scripts/cli.ts agentrun events run/<runId> --after-seq 0 --limit 100",
" bun scripts/cli.ts agentrun logs session/<sessionId> --tail 100",
"",
@@ -329,7 +329,7 @@ export function agentRunHelpText(args: string[]): string {
"Common:",
" bun scripts/cli.ts agentrun get tasks --queue commander --limit 20",
" bun scripts/cli.ts agentrun describe task/<taskId>",
" bun scripts/cli.ts agentrun describe run/<runId> --node D601 --lane v02",
" bun scripts/cli.ts agentrun describe run/<runId> --node NC01 --lane nc01-v02",
" bun scripts/cli.ts agentrun events run/<runId> --after-seq 0 --limit 100",
" bun scripts/cli.ts agentrun logs session/<sessionId> --tail 100",
" bun scripts/cli.ts agentrun create task --aipod Artificer --prompt-stdin",
@@ -337,6 +337,6 @@ export function agentRunHelpText(args: string[]): string {
"Machine/debug output:",
" -o json|yaml emits a stable UniDesk resource object without the global JSON envelope.",
" --raw emits the direct AgentRun REST envelope.",
" --node/--lane targets a YAML-declared AgentRun runtime lane; default remains the configured public manager.",
" --node/--lane targets a YAML-declared AgentRun runtime lane; default is the configured NC01 manager.",
].join("\n");
}
scripts/src/help.ts
+48 -50
View File
@@ -60,7 +60,7 @@ export function rootHelp(): unknown {
{ command: "deploy check|plan|apply [--file deploy.json|--env dev|prod] [--service id] [--commit full-sha] [--dry-run] [--force]", description: "Reconcile services from origin/master:deploy.json environments; --commit overrides one reviewed artifact consumer such as frontend for release/v1 validation or rollback. code-queue artifact consumption is dev-only." },
{ command: "cicd status --node <NODE>", description: "Show one node's CI/CD closeout summary across current Pipelines-as-Code consumers, including PipelineRun, Argo and runtime readiness." },
{ command: "cicd gitea-actions-poc plan|status", description: "Archived read-only CI/CD migration evidence for GH-1548/GH-1549; never use as a delivery or closeout path." },
{ command: "cicd branch-follower status|events|logs", description: "Archived migration diagnostics only; PaC-migrated JD01/NC01 lanes must use cicd status and platform-infra pipelines-as-code closeout/status/history." },
{ command: "cicd branch-follower status|events|logs", description: "Archived migration diagnostics only; PaC-migrated NC01 lane must use cicd status and platform-infra pipelines-as-code closeout/status/history." },
{ command: "dev-env validate|prewarm-images", description: "Validate D601 unidesk-dev guardrails or prewarm dev foundation images into native k3s containerd through a bounded async job." },
{ command: "artifact-registry plan|render|status|health|install|deploy-backend-core|deploy-service", description: "Manage the D601 host-managed CNCF Distribution registry and run pull-only artifact CD for supported services, including D601 direct, k3s-managed, and code-queue dev-only consumers." },
{ command: "auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run", description: "Inspect the P0 Rust auth broker and CLI adapter contract without reading token values, writing GitHub, or starting services." },
@@ -68,13 +68,13 @@ export function rootHelp(): unknown {
{ command: "git github-push-fallback [--repo owner/name] [--branch branch] [--host-name host-or-ip] [--confirm]", description: "Plan or execute a one-shot GitHub push through ssh.github.com:443 without editing remotes; use only for reviewed DNS/port-22 push fallback." },
{ command: "commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run", description: "Host Codex commander skeleton contract, no-daemon smoke plan, and dry-run approval preview without live bridges or message sends." },
{ command: "web-probe run|script|observe|sentinel --node <node> --lane <lane>", description: "Run YAML-selected HWLAB Web probes, long observe/analyze sessions, project-management MDTODO commands, and Web sentinel control through the single top-level web-probe entrypoint." },
{ command: "hwlab nodes control-plane|git-mirror|hwpod-preinstall|secret|test-accounts --node <node> --lane <lane>", description: "Manage HWLAB node/lane runtime prerequisites, including D601 YAML-declared k3s infra/tools-image/Argo bootstrap, HWPOD preinstall configRefs, redacted test-account preparation, and G14 v0.3+ runtime lanes, with the node identity passed as data." },
{ command: "hwlab g14 monitor-prs | hwlab g14 control-plane status|apply|trigger-current|runtime-migration|cleanup-runs|cleanup-released-pvs | hwlab g14 git-mirror status|apply|sync|flush | hwlab g14 tools-image status|build", description: "Start the legacy G14 PR monitor, run bounded v0.2 Tekton/Argo control-plane, manual PipelineRun trigger, runtime migration, CI workspace retention, manual devops-infra git mirror/relay maintenance, or fixed HWLAB CI tools image actions; long confirmed trigger/sync/flush actions return async jobs by default." },
{ command: "hwlab nodes control-plane|git-mirror|hwpod-preinstall|secret|test-accounts --node <node> --lane <lane>", description: "Manage HWLAB node/lane runtime prerequisites, including NC01 YAML-declared k3s infra/tools-image/Argo bootstrap, HWPOD preinstall configRefs, redacted test-account preparation, and NC01 v0.3 runtime lane, with the node identity passed as data." },
{ command: "hwlab nodes control-plane|git-mirror|hwpod-preinstall|secret|test-accounts --node NC01 --lane v03", description: "Operate the NC01 HWLAB v0.3 development and deployment lane from YAML source truth." },
{ command: "agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|send|control-plane|git-mirror", description: "Use AgentRun v0.1 resource primitives with low-noise human output by default; session follow-up uses send only and the server decides internal steer vs turn." },
{ command: "platform-infra sub2api|langbot|n8n|webterm|wechat-archive ...", description: "Deploy platform-infra services such as Sub2API, LangBot, n8n and Web Terminal, manage YAML-controlled public Caddy/FRP exposure and WeChat archive workflows, and inspect status/logs without printing secrets." },
{ command: "secrets plan|sync|status", description: "Plan, push and inspect YAML-declared local secret source keys to Kubernetes Secrets without printing or reverse-engineering values." },
{ command: "platform-db postgres plan|status|export-secrets|apply", description: "Manage YAML-declared host-native PostgreSQL 16 on PK01 for Sub2API/platform state, with PostgreSQL native TLS and redacted secret exports." },
{ command: "hwlab cd audit --env dev | hwlab cd status --env dev | hwlab cd apply --env dev --dry-run", description: "Legacy D601 HWLAB DEV CD wrapper kept for explicit old-path diagnostics; current HWLAB rollout uses G14 GitOps." },
{ command: "hwlab cd audit --env dev | hwlab cd status --env dev | hwlab cd apply --env dev --dry-run", description: "Archived HWLAB DEV CD diagnostics only; current HWLAB rollout uses NC01 GitOps." },
{ command: "code-agent-sandbox", description: "Independent Code Agent Sandbox service skeleton for adapter, mode, and credential-boundary diagnostics." },
{ command: "schedule list|get|runs|run|retry-run|delete", description: "Manage backend-core scheduled tasks and run history; schedule run <id> supports --wait-ms N and retry-run reuses the failed run's schedule." },
{ command: "schedule upsert-pgdata-backup [--time HH:MM] [--remote-base /SERVER_DATA/UNIDESK_PG_DATA]", description: "Create or update the daily PGDATA physical backup task that uploads monthly rotated archives to Baidu Netdisk." },
@@ -184,7 +184,7 @@ export function sshHelp(): unknown {
"trans <providerId> skills [--scope all|wsl|windows] [--limit N]",
"trans <providerId> find <path...> [--contains TEXT] [--limit N]",
"trans <providerId> glob [--root DIR] [--pattern PATTERN]",
"trans D601:/home/ubuntu/workspace/hwlab-dev git status --short --branch",
"trans NC01:/root/hwlab git status --short --branch",
"trans D601:win ps <<'PS'",
"trans D601:win/c/test ps <<'PS'",
"trans D601:win/c/test cmd <<'CMD'",
@@ -202,22 +202,22 @@ export function sshHelp(): unknown {
"trans D601:win/c/test git diff --check",
"trans D601:win/c/test git commit -m 'fix: update docs'",
"trans D601:win skills [--scope agents|codex|all] [--limit N]",
"trans D601:k3s",
"trans D601:k3s kubectl get pods -n hwlab-dev",
"trans G14:k3s",
"trans G14:k3s kubectl get pipelineruns -n hwlab-ci",
"trans D601:k3s sh <<'SH'",
"trans D601:k3s:hwlab-dev:hwlab-cloud-api:hwlab-cloud-api exec --cwd /app -- pwd",
"trans D601:k3s:hwlab-dev:hwlab-cloud-api:hwlab-cloud-api apply-patch --cwd /app <<'PATCH'",
"trans D601:k3s:hwlab-dev:hwlab-cloud-api apply-patch-v1 <<'PATCH'",
"tar -C /path/to/files -cf - . | trans D601:k3s:unidesk:code-queue exec --cwd /root/unidesk --stdin -- tar -xf - -C /root/unidesk",
"trans NC01:k3s",
"trans NC01:k3s kubectl get pods -n hwlab-dev",
"trans NC01:k3s",
"trans NC01:k3s kubectl get pipelineruns -n hwlab-ci",
"trans NC01:k3s sh <<'SH'",
"trans NC01:k3s:hwlab-dev:hwlab-cloud-api:hwlab-cloud-api exec --cwd /app -- pwd",
"trans NC01:k3s:hwlab-dev:hwlab-cloud-api:hwlab-cloud-api apply-patch --cwd /app <<'PATCH'",
"trans NC01:k3s:hwlab-dev:hwlab-cloud-api apply-patch-v1 <<'PATCH'",
"tar -C /path/to/files -cf - . | trans NC01:k3s:unidesk:code-queue exec --cwd /root/unidesk --stdin -- tar -xf - -C /root/unidesk",
"trans D601:win/c/test apply-patch <<'PATCH'",
"trans D601:win upload ./tool.mjs F:\\Work\\hwlab\\.tmp\\tool.mjs",
"trans D601:win download F:\\Work\\hwlab\\.tmp\\tool.mjs ./tool.mjs",
"trans D601:k3s:hwlab-dev:hwlab-cloud-api node -e 'console.log(process.version)'",
"trans D601:k3s:hwlab-dev:hwlab-cloud-api sh <<'SH'",
"trans D601:k3s:hwlab-dev:hwlab-cloud-api logs --tail 80",
"trans G14:k3s logs -n agentrun-ci -l tekton.dev/pipelineRun=<run> --tail 120",
"trans D601:win upload ./tool.mjs C:\\Temp\\tool.mjs",
"trans D601:win download C:\\Temp\\tool.mjs ./tool.mjs",
"trans NC01:k3s:hwlab-dev:hwlab-cloud-api node -e 'console.log(process.version)'",
"trans NC01:k3s:hwlab-dev:hwlab-cloud-api sh <<'SH'",
"trans NC01:k3s:hwlab-dev:hwlab-cloud-api logs --tail 80",
"trans NC01:k3s logs -n agentrun-ci -l tekton.dev/pipelineRun=<run> --tail 120",
],
notes: [
"trans --help and trans <route> --help print this JSON help and never open an interactive session; the underlying ssh subcommand keeps the same help behavior.",
@@ -228,7 +228,7 @@ export function sshHelp(): unknown {
"For Windows PowerShell, use `trans <provider>:win ps <<'PS'`; the PowerShell body is written to a temporary .ps1 with UTF-8 settings and executed by powershell.exe. Do not use POSIX `sh` or `bash` for Windows PowerShell.",
"For Windows cmd.exe, use `trans <provider>:win/<drive>/<path> cmd <<'CMD'`; `cmd` with no command-line arguments reads the UTF-8 batch body from stdin, injects UTF-8/Python encoding defaults, runs it from a temp .cmd file, and deletes the temp file.",
"`argv` executes direct argv tokens only: `trans <route> argv ls -la` is valid, but `trans <route> argv 'ls -la'` is rejected because the single string would be treated as an executable path; use `sh -- 'ls -la'` or `bash -- 'ls -la'` for one-line shell logic.",
"For one-line remote shell logic without a heredoc, use `sh -- '<command && command>'` for POSIX syntax or `bash -- '<command && command>'` for Bash syntax. Outer shell operators written outside trans, such as `trans G14:/repo sed ... && sed ...`, are parsed by the local shell before UniDesk starts and therefore cannot be redirected by the CLI.",
"For one-line remote shell logic without a heredoc, use `sh -- '<command && command>'` for POSIX syntax or `bash -- '<command && command>'` for Bash syntax. Outer shell operators written outside trans, such as `trans NC01:/repo sed ... && sed ...`, are parsed by the local shell before UniDesk starts and therefore cannot be redirected by the CLI.",
"`sh --` and `bash --` accept exactly one shell command string. For direct argv commands with multiple tokens, use `argv`, `exec`, or a known direct subcommand such as `git`, `rg`, `sed`, or `cat`.",
"The removed `script` and `shell` operations intentionally fail. The operation name must declare the shell dialect: `sh` maps to target `/bin/sh`, while `bash` maps to target `bash`.",
"sh and bash helper modes inject a tiny POSIX-compatible printf wrapper before user shell text, so portable printf headings such as `printf \"--- section ---\\n\"` work consistently under dash/sh and bash. Direct argv commands are unchanged.",
@@ -241,7 +241,7 @@ export function sshHelp(): unknown {
"Use `win`, not `win32`; the win route is a Windows operation plane. `ps` and `cmd` both set UTF-8/Python encoding defaults, while `cmd` also sets `chcp 65001`.",
"`<provider>:win skills` discovers the current Windows user's `%USERPROFILE%\\.agents\\skills` by default; use `--scope all` to include `%USERPROFILE%\\.codex\\skills`.",
"Do not put operation names in any colon route segment, including nested k3s namespace/workload/container segments.",
"Do not use post-provider shorthand such as `trans G14 k3s ...`; write `trans G14:k3s ...` so location and operation stay separated.",
"Do not use post-provider shorthand such as `trans NC01 k3s ...`; write `trans NC01:k3s ...` so location and operation stay separated.",
"If an ssh-like remote command fails with timeout/kex/exit-255 friction, stderr includes one low-noise UNIDESK_SSH_HINT JSON line with the argv retry command.",
"Ordinary non-interactive ssh/trans/tran remote commands have a hard top-level runtime timeout capped at 60s. Timeout writes UNIDESK_SSH_RUNTIME_TIMEOUT or UNIDESK_TRAN_TIMEOUT_HINT and disconnects the broker; long CI/CD, trace, logs, build, or hardware work must use submit-and-poll / short query loops instead of keeping trans open. Whole-file `download` is the narrow exception: controlled async callers can pass `--inactivity-timeout-ms` for a verified progress-emitting tcp-pool transfer.",
"Only slow ssh/trans/tran runtime writes UNIDESK_SSH_TIMING JSON to stderr; operations over 10s are marked level=warning even when they succeed, because slow successful calls are a distributed performance monitoring signal. Check provider latency, remote command cost, helper bootstrap, or remote patch optimization before repeating high-frequency work. Routine short calls do not emit timing noise.",
@@ -712,22 +712,22 @@ function hwlabNodeHelpSummary(): unknown {
command: "hwlab nodes control-plane|git-mirror|hwpod-preinstall|observability|secret|test-accounts --node <node> --lane <lane>",
output: "json",
usage: [
"bun scripts/cli.ts hwlab nodes control-plane infra plan --node D601 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra status --node D601 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra tools-image status --node D601 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra argo status --node D601 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra egress-benchmark --node D601 --lane v03 --profile no-mirror --confirm",
"bun scripts/cli.ts hwlab nodes control-plane infra ci-build-benchmark --node D601 --lane v03 --profile no-mirror-full --confirm",
"bun scripts/cli.ts hwlab nodes control-plane infra ci-build-benchmark status --node D601 --lane v03 --profile no-mirror-full",
"bun scripts/cli.ts hwlab nodes control-plane status --node G14 --lane v03",
"bun scripts/cli.ts hwlab nodes git-mirror status --node G14 --lane v03",
"bun scripts/cli.ts hwlab nodes hwpod-preinstall plan --node D601 --lane v03 --dry-run",
"bun scripts/cli.ts hwlab nodes observability performance-summary --node D601 --lane v03",
"bun scripts/cli.ts hwlab nodes secret status --node G14 --lane v03 --name <secret>",
"bun scripts/cli.ts hwlab nodes test-accounts status --node D601 --lane v03",
"bun scripts/cli.ts hwlab nodes test-accounts sync --node D601 --lane v03 --confirm",
"bun scripts/cli.ts hwlab nodes control-plane infra plan --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra status --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra tools-image status --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra argo status --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane infra egress-benchmark --node NC01 --lane v03 --profile no-mirror --confirm",
"bun scripts/cli.ts hwlab nodes control-plane infra ci-build-benchmark --node NC01 --lane v03 --profile no-mirror-full --confirm",
"bun scripts/cli.ts hwlab nodes control-plane infra ci-build-benchmark status --node NC01 --lane v03 --profile no-mirror-full",
"bun scripts/cli.ts hwlab nodes control-plane status --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes git-mirror status --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes hwpod-preinstall plan --node NC01 --lane v03 --dry-run",
"bun scripts/cli.ts hwlab nodes observability performance-summary --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes secret status --node NC01 --lane v03 --name <secret>",
"bun scripts/cli.ts hwlab nodes test-accounts status --node NC01 --lane v03",
"bun scripts/cli.ts hwlab nodes test-accounts sync --node NC01 --lane v03 --confirm",
],
description: "Operate HWLAB node/lane runtime prerequisites with node and lane passed as data. The infra subcommand manages YAML-controlled node-local CI/CD, git-mirror, public Dockerfile tools image, no-mirror egress benchmarks, and declarative Argo CD prerequisites for D601 v03 while keeping cross-node work semi-automatic; hwpod-preinstall renders D601/v03 71-FREQ HWPOD/MDTODO/gateway configRefs without runtime mutation; observability reads runtime metrics and authenticated Web Performance summaries; test-accounts prepares UniDesk YAML-declared admin/test account API keys with redacted sourceRef/fingerprint output. Web probe commands moved to top-level `bun scripts/cli.ts web-probe`.",
description: "Operate NC01 HWLAB v0.3 runtime prerequisites from YAML source truth. The infra subcommand manages node-local CI/CD, git-mirror, public Dockerfile tools image, egress benchmarks, and declarative Argo CD prerequisites; hwpod-preinstall renders NC01/v03 HWPOD/MDTODO/gateway configRefs without runtime mutation; observability reads runtime metrics and authenticated Web Performance summaries; test-accounts prepares UniDesk YAML-declared admin/test account API keys with redacted sourceRef/fingerprint output. Web probe commands moved to top-level `bun scripts/cli.ts web-probe`.",
};
}
@@ -736,13 +736,13 @@ function webProbeHelpSummary(): unknown {
command: "web-probe run|script|observe|sentinel --node <node> --lane <lane>",
output: "json",
usage: [
"bun scripts/cli.ts web-probe run --node D601 --lane v03 --wait-messages-ms 1000",
"bun scripts/cli.ts web-probe observe start --node D601 --lane v03 --target-path /workbench --sample-interval-ms 5000",
"bun scripts/cli.ts web-probe run --node NC01 --lane v03 --wait-messages-ms 1000",
"bun scripts/cli.ts web-probe observe start --node NC01 --lane v03 --target-path /workbench --sample-interval-ms 5000",
"bun scripts/cli.ts web-probe observe collect webobs-xxxx --view turn-summary",
"bun scripts/cli.ts web-probe observe collect webobs-xxxx --view timeline --turn 1",
"bun scripts/cli.ts web-probe sentinel plan --node D601 --lane v03 --dry-run",
"bun scripts/cli.ts web-probe sentinel plan --node NC01 --lane v03 --dry-run",
"bun scripts/cli.ts web-probe sentinel inspect-url 'https://monitor.pikapython.com/?run=sentinel-run-xxxx'",
"bun scripts/cli.ts web-probe sentinel inspect-id trc_xxxx --node JD01 --lane v03 --sentinel jd01-web-probe-sentinel",
"bun scripts/cli.ts web-probe sentinel inspect-id trc_xxxx --node NC01 --lane v03 --sentinel jd01-web-probe-sentinel",
],
description: "Run target node/lane HWLAB Cloud Web probes, long observe/analyze sessions, project-management MDTODO commands, and Web sentinel YAML-first control through a single top-level implementation. Monitor-web links and evidence ids should enter through sentinel inspect-url/inspect-id before report or observe drill-down.",
};
@@ -762,27 +762,25 @@ function cicdHelpSummary(): unknown {
function hwlabG14HelpSummary(): unknown {
return {
command: "hwlab g14 monitor-prs|control-plane|git-mirror|tools-image|retirement",
command: "hwlab g14 retirement",
output: "json",
usage: [
"bun scripts/cli.ts hwlab g14 control-plane status --lane v02",
"bun scripts/cli.ts hwlab g14 trigger-current --lane v02 --dry-run",
"bun scripts/cli.ts hwlab g14 monitor-prs --status",
"bun scripts/cli.ts hwlab g14 retirement status",
"bun scripts/cli.ts hwlab g14 retirement plan",
],
description: "Operate the G14 HWLAB runtime lane control-plane and legacy retirement helpers.",
description: "Archived legacy helper surface. Current HWLAB development and deployment use NC01 node commands.",
};
}
function hwlabHelpSummary(): unknown {
return {
command: "hwlab g14|nodes|cd",
command: "hwlab nodes|g14|cd",
output: "json",
usage: [
"bun scripts/cli.ts hwlab g14 control-plane status --lane v02",
"bun scripts/cli.ts hwlab nodes control-plane status --node G14 --lane v03",
"bun scripts/cli.ts hwlab nodes control-plane status --node NC01 --lane v03",
"bun scripts/cli.ts hwlab cd audit --env dev",
],
description: "HWLAB operations. Current runtime work uses G14 lane commands; D601 cd is legacy diagnostics only.",
description: "HWLAB operations. Current runtime work uses NC01 node commands; old cd/g14 surfaces are archived diagnostics only.",
};
}
scripts/src/hwlab-g14/types.ts
+3 -3
View File
@@ -14,13 +14,13 @@ import { durationSeconds } from "./pr-monitor";
export const HWLAB_REPO = "pikasTech/HWLAB";
export const G14_SOURCE_BRANCH = "G14";
export const G14_SOURCE_BRANCH = "v0.3";
export const G14_PROVIDER = "G14";
export const G14_PROVIDER = "NC01";
export const G14_WORKSPACE = "/root/hwlab";
export const V02_LANE_SPEC = hwlabRuntimeLaneSpec("v02");
export const V02_LANE_SPEC = hwlabRuntimeLaneSpec("v02") ?? hwlabRuntimeLaneSpec("v03");
export const V02_SOURCE_BRANCH = V02_LANE_SPEC.sourceBranch;