pikasTech-HWLAB/AGENTS.md

# HWLAB Agent 顶级索引

HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥官和 runner 进入本仓库时的顶级索引，只放入口、一句话规则和长期参考链接；细则统一维护在 `docs/reference/`。

## P0 G14 原生 k8s/GitOps 运行面归一

- G14 是当前 HWLAB DEV/PROD 原生 k8s 与 GitOps 运行面真相；`hwlab-dev` 与 `hwlab-prod` 均由 G14 k3s、Tekton、`G14-gitops` 和 Argo CD 管理，详见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。
- D601 HWLAB DEV、D601 `dev-cd-apply`、`ci-publish` 和旧 `main` JS 脚本式 CI/CD 只作为 legacy 迁移来源和事故参考；新开发、发布、验收、文档和运行面实验不得把 D601 当作当前 HWLAB runtime source-of-truth。
- G14 k3s 操作必须通过 UniDesk route `G14:k3s` 执行；不得用 D601 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为 G14 DEV/PROD 通过证据。

## P0 GitHub Issue 写入纪律

- HWLAB #7、用户反馈、长期看板和指挥简报的 GitHub issue 正文写入必须走 UniDesk CLI：`cd /root/unidesk && bun scripts/cli.ts gh ...`；禁止直接用原生 `gh issue edit/create/comment` 写这些 issue。事故和工具补强需求见 [pikasTech/unidesk#142](https://github.com/pikasTech/unidesk/issues/142)。
- 在 UniDesk CLI 局部替换、写前备份和写后 hash 验证能力完成前，不要对 #7 做无 guard 的整篇 body replace；必须先保留 before body、确认维护纪律 heading 仍存在，再写入。

## P0 DEV CD Promotion 顺序

- `ci-publish` 只证明镜像已经为 publish report 的 `artifactPublish.sourceCommitId` 构建并推送；它不会改变 rollout 目标。禁止在 `ci-publish` 成功后直接把 `dev-cd-apply` 的旧 desired-state 输出当作新版本上线成功。
- 正式 DEV CD 前必须用刚成功的 publish report 刷新三份 repo desired-state：`node scripts/refresh-artifact-catalog.mjs --target-ref <published-sourceCommitId> --publish-report <ci-publish-report.json>`，再执行 `node scripts/deploy-desired-state-plan.mjs --promotion-commit <published-sourceCommitId> --check`，确认 `deploy/deploy.json`、`deploy/artifact-catalog.dev.json` 和 `deploy/k8s/base/workloads.yaml` 全部指向同一个已发布 commit。
- 只有刷新后的 desired-state 已提交/推送，并且 CD 报告与 `16666/16667` live health 都观测到该短 commit，才能声明 DEV 上线完成；如果 CD report 里 `commitId` 仍是旧值，必须先修 desired-state，不要重复跑 CD。长期细节见 [docs/reference/deployment-publish.md](docs/reference/deployment-publish.md)。

## 工作区

- G14 分支固定 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。在 G14 上进行代码、文档、GitOps render、Tekton/poller/Argo CD 修复或 CI/CD 验证前，必须先确认 `pwd` 为 `/root/hwlab` 且 `git status --short --branch` 为 `G14...origin/G14`；不满足时先停止并修正 workspace。
- G14 k3s 操作必须通过 UniDesk SSH route `G14:k3s` 执行，例如 `bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci`；禁止使用 `ssh G14 k3s ...`。不要把 `/workspace/hwlab`、`/root/HWLAB`、D601 workspace、master-server checkout 或临时 clone 当作 G14 分支 source truth。
- Runner 和指挥常用工作区是 `/workspace/hwlab`；进入仓库先检查分支与工作树状态，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
- G14 CI/CD 由 `G14` source branch、G14 k3s Tekton 和 `G14-gitops` branch 驱动；需要构建、Playwright、check、发布预检或运行面验证时放到 G14 k3s/runner/CI/CD，不在 master server 跑重型验证。
- D601 发布/构建 worktree 纪律只适用于 legacy 路径回溯，不再作为当前 HWLAB 发布默认入口；当前入口见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。
- 当前一律走 PR 工作流；不要直推 `main`，默认不要合并自己的 PR；用户或指挥官明确授权且满足门禁时可按长期参考自合并，不要改 PROD、不要重启服务。
- `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78) 是当前 M3 虚拟硬件可信闭环的上位约束；其他任务不得把 SOURCE、LOCAL、DRY-RUN、fixture 或前端状态误报为 M3 DEV-LIVE。
- 仓库禁止创建或提交 repo report 目录；验收、进展和结论只承载在 #7、专题 issue、每日简报或 PR/issue 评论。临时 JSON 只能写入 `/tmp`、`.state` 或 CI artifact，不能进入源码仓库。

## 固定入口

- G14 DEV Cloud Web：`http://74.48.78.17:17666/`，规则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。
- G14 DEV API/edge/live：`http://74.48.78.17:17667/health/live`，规则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。
- G14 PROD 预留入口：`http://74.48.78.17:18666/` 与 `http://74.48.78.17:18667/health/live`，规则见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。
- Cloud Workbench 默认首页与 UX 约束见 [docs/reference/cloud-workbench.md](docs/reference/cloud-workbench.md)。

## 长期参考

- 唯一入口纪律：`AGENTS.md` 是 agent、指挥官和 runner 的唯一入口；不要新增、维护或引用 `README.md`、`docs/reference/README.md` 作为入口或索引，长期参考直接在本节索引。
- 中文优先规则：[docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)
- 用户反馈分流规则：[docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md)
- 文档治理与 docs-spec 本地权威：[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md)
- 架构和 M3 主线：[docs/reference/architecture.md](docs/reference/architecture.md)
- DEV 运行态、端口、k3s 和 DB DNS 边界：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)
- 部署正规化、`deploy.json` DEV CD 路径、SecretRef preflight、runner/host 边界和镜像发布：[docs/reference/deployment-publish.md](docs/reference/deployment-publish.md)
- G14 GitOps CI/CD、Tekton/Argo CD、集群内 registry 和无锁镜像化发布：[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)
- Code Agent 对话就绪与真实回复判定：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
- DEV runtime hotfix runbook 与只读审计：[docs/reference/dev-runtime-hotfix-runbook.md](docs/reference/dev-runtime-hotfix-runbook.md)
- Gateway 主动出站 demo、poll/result 和本地 smoke：[docs/reference/gateway-outbound-demo.md](docs/reference/gateway-outbound-demo.md)
- MVP E2E 验收测试与带编号测试报告 issue 规则：[docs/reference/MVP-e2e-acceptance.md](docs/reference/MVP-e2e-acceptance.md)
- 指挥官协作、PR 和 runner 交接：[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
- M3 闭环发布运行手册：[docs/reference/m3-loop-rollout-runbook.md](docs/reference/m3-loop-rollout-runbook.md)
- runner issue 可见性与 prompt 交接：[docs/reference/runner-issue-visibility-handoff.md](docs/reference/runner-issue-visibility-handoff.md)

## 工作优先级

- 中文优先：issue、PR 正文、长期参考文档和用户可见说明默认用中文；英文术语只在命令、协议、接口、ID、路径和标准名需要保真时保留，详见 [docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)。
- 用户反馈优先：用户和参谋提出的问题默认按高优先级用户反馈处理，blocker 状态不能替代反馈分流，必须挂到 [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7) 醒目位置，详见 [docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.md)。
- docs-spec 本地权威优先：涉及 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，先按 [docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) 执行，不另建同级规则副本。
- PR 工作流优先：从最新 `origin/main` 创建短分支，提交 PR 到 `pikasTech/HWLAB:main`，runner 不直推 `main`，默认不自合并；显式授权且满足门禁时按协作规则收口，不改 PROD、不重启服务，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。

## 常用轻量命令

- 静态合同校验：`npm run validate`
- Cloud Web 静态检查：`npm run web:check`
- Cloud Web 构建：`npm run web:build`
- Cloud Web M3 只读护栏：`npm run web:m3-readonly`
- Cloud Workbench 布局/遮挡 smoke：`npm run web:layout`；local-build 用 `npm run web:layout:build`；DEV deploy 后用 `npm run web:layout:live`。
- DEV artifact 发布预检：`npm run dev-artifact:preflight`
- DEV artifact CI 发布：`node tools/hwlab-cli/bin/hwlab-cli.mjs cicd submit --kind ci-publish --concurrency 4`
- G14 GitOps 渲染：`npm run g14:gitops:render`；检查已生成 Tekton/Argo CD manifests：`npm run g14:gitops:check`
- DEV 依赖 runtime base 构建：`npm run dev-runtime-base:build`
- DEV CD 单事务发布/应用/验证：`node tools/hwlab-cli/bin/hwlab-cli.mjs cicd submit --kind dev-cd-apply --confirm-dev --confirmed-non-production --concurrency 4`
- CI/CD job 查询：`node tools/hwlab-cli/bin/hwlab-cli.mjs cicd status|logs|report <jobId>`
- runner GitHub 可见性预检：`npm run runner:issue-visibility:preflight`
- D601 k3s 只读观测：legacy 回溯入口，仅在确认需要 D601 事故复盘时使用；当前 G14 运行面观察使用 UniDesk route `G14:k3s`。
- DEV runtime hotfix 只读审计计划：`npm run dev-runtime:hotfix-audit`
- Gateway 主动出站本地 smoke：`npm run gateway:demo:smoke`；经本地 edge-proxy 验证用 `npm run gateway:demo:edge-smoke`。

## D601 k3s 只读观测

HWLAB DEV runtime（运行态）在 D601 原生 k3s；只读诊断或手动发布必须显式使用 `/etc/rancher/k3s/k3s.yaml`，详见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。

## 禁止误判

- `SOURCE`、`LOCAL`、`DRY-RUN`、fixture 和只读报告不能被称为 `DEV-LIVE`；证据分级见 [docs/reference/architecture.md](docs/reference/architecture.md)。
- Cloud Workbench、Gate、诊断页、发布路径修复都是支撑任务，不等同于 M3 PASS；M3 判定见 [docs/reference/m3-loop-rollout-runbook.md](docs/reference/m3-loop-rollout-runbook.md)。
- UniDesk 只作为调度、CI 或 CD 基础设施，不能替代 HWLAB runtime；运行态边界见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。