Codex
108 lines
14 KiB
Markdown
108 lines
14 KiB
Markdown
# 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)。
|
||
- `v0.2` 是 G14 上的加法扩容线：固定分支 `v0.2`、固定 workspace `G14:/root/hwlab-v02`、固定 namespace `hwlab-v02`、FRP 入口 `74.48.78.17:19666/19667`；创建和集成 `v0.2` 不得删除、重命名、复用或改义现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口。
|
||
- G14 GitOps render 若改变 Argo Application、AppProject、runtime path 或 DEV/PROD 拆分目录，必须同步应用 `deploy/gitops/g14/argocd/project.yaml`、`application-dev.yaml` 和 `application-prod.yaml`；只推 `G14-gitops` 分支不等于 Argo 已切到新 path。
|
||
- D601 HWLAB DEV、D601 `dev-cd-apply`、`ci-publish` 和旧 `main` JS 脚本式 CI/CD 已退出 G14 发布入口；G14 Tekton 只能通过 `scripts/g14-artifact-publish.mjs` 作为集群内 build/push helper，再由 GitOps/Argo CD rollout，新开发、发布、验收、文档和运行面实验不得把 D601 或 legacy 脚本 CD 当作当前 HWLAB runtime source-of-truth。
|
||
- G14 k3s 操作必须通过 UniDesk route `G14:k3s` 执行；不得用 D601 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为 G14 DEV/PROD 通过证据。
|
||
|
||
## P0 HyueAPI Direct NO_PROXY 规则
|
||
|
||
- `hyueapi.com` / `.hyueapi.com` 是 Codex API 通道的直连域名，必须始终保留在 `NO_PROXY` / `no_proxy` 中；DeepSeek、Codex API 或其他 provider profile 切换、G14 proxy 注入、旧 D601 egress 迁移和 pod/env render 都不得把 hyueapi 流量改成走 HTTP/SOCKS proxy。
|
||
|
||
## 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 Legacy CD 删除纪律
|
||
|
||
- 旧 D601 `ci-publish`、`dev-cd-apply`、`dev-deploy-apply` 和 `dev-artifact-publish` 脚本入口已经从当前发布面删除；不要恢复这些文件、CLI 子命令或文档入口。
|
||
- 当前发布只走 G14 k3s Tekton + `G14-gitops` + Argo CD；镜像构建 helper 是 `scripts/g14-artifact-publish.mjs`，desired state 由 `scripts/g14-gitops-render.mjs` 生成，细则见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。
|
||
- 发现旧脚本、旧文档或旧 `hwlab-cli cicd` 再次进入 G14 Pipeline、AGENTS 或长期参考时，优先删除旧入口并把调用方改到 G14 GitOps 路径，不再做兼容保留。
|
||
|
||
## P0 门禁最小化纪律
|
||
|
||
- 架构迁移时，过时的自检、预检、guard、gate 优先拆除；不要在旧门禁上继续加例外、加复杂度或制造噪声。
|
||
- 新增自检、预检、guard、gate 必须遵循最小原则，只覆盖明确高价值风险；禁止乱加门禁导致系统僵化、难迁移、难调试或产生大量误报和摩擦。
|
||
|
||
## 工作区
|
||
|
||
- G14 分支固定 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。在 G14 上进行代码、文档、GitOps render、Tekton/poller/Argo CD 修复或 CI/CD 验证前，必须先确认 `pwd` 为 `/root/hwlab` 且 `git status --short --branch` 为 `G14...origin/G14`；不满足时先停止并修正 workspace。
|
||
- `v0.2` 固定 source workspace 是 G14 节点上的 `/root/hwlab-v02`，固定使用 `v0.2` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。`/root/hwlab-v02` 只能作为 `v0.2` 长期工作区，不得作为 `G14` scratch 区或 DEV/PROD 热修目录。
|
||
- G14 开发默认先以 `/root/hwlab` 做固定 repo 预检，再在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建独立 worktree 修改和提交；固定 repo 不作为并行任务 scratch 区，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
|
||
- G14 k3s 操作必须通过 UniDesk SSH route `G14:k3s` 执行，例如 `bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci`；禁止使用 `ssh G14 k3s ...`。不要把 `/workspace/hwlab`、`/root/HWLAB`、D601 workspace、master-server checkout 或临时 clone 当作 G14 分支 source truth。
|
||
- 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)。
|
||
- 交付路径按变更风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到 `origin/G14`，不开 PR；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 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)。
|
||
- G14 `v0.2` 规划入口：`http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`，只能指向 `hwlab-v02` namespace，规则见 [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)
|
||
- G14 GitOps 发布、SecretRef preflight、runner/host 边界、镜像发布和单纯文档/CLI 直推规则：[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)、[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
|
||
- G14 GitOps CI/CD、Tekton/Argo CD、集群内 registry 和无锁镜像化发布：[docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)
|
||
- G14 CI/CD 性能基线、根因分析和加速收益估算：[docs/reference/g14-cicd-performance.md](docs/reference/g14-cicd-performance.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)
|
||
- Device Pod 四要素、profile、HWLAB coder 预装合同与 CLI/server 分阶段计划：[docs/reference/device-pod.md](docs/reference/device-pod.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) 执行，不另建同级规则副本。
|
||
- 交付路径按风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到 `origin/G14`，不开 PR；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，详见 [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`。
|
||
- G14 artifact build helper：`node scripts/g14-artifact-publish.mjs --publish ...`，只能由 G14 Tekton task 携带 CI artifact identity 调用；人工发布走 G14 poller/GitOps，不走 legacy CLI CD。
|
||
- G14 monorepo 组件计划：`node scripts/g14-ci-plan.mjs --base-ref <ref> --target-ref <ref> --pretty`，只读分析 affected/reused services，基于内建 service-path component model 与 `deploy/deploy.json`；细则见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。
|
||
- G14 GitOps 渲染：`npm run g14:gitops:render`；source 分支不再运行生成物 drift check，发布态由 Tekton 写入 `G14-gitops`。
|
||
- DEV 依赖 runtime base 构建：`npm run dev-runtime-base:build`
|
||
- Legacy D601 DEV CD：旧脚本入口已删除；事故回放只读历史 issue/commit，不恢复旧命令。
|
||
- 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 legacy 只读回溯
|
||
|
||
当前 HWLAB DEV/PROD runtime（运行态）以 G14 原生 k3s 与 GitOps 为准；D601 只保留 legacy 事故回放、迁移对比和历史证据查询，不作为当前开发、发布、验收或 hotfix 目标。需要观察当前运行态时使用 UniDesk route `G14:k3s`，细则见 [docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)。
|
||
|
||
## 禁止误判
|
||
|
||
- `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)。
|