docs: split agent entrypoint index

2026-06-22 08:27:43 +08:00
parent e6571938c4
commit 74395d0582
2 changed files with 104 additions and 144 deletions
@@ -1,158 +1,54 @@
-# HWLAB Agent 顶级索引
+# HWLAB Agent Index

-HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥官和 runner 进入本仓库时的顶级索引，只放入口、一句话规则和长期参考链接；细则统一维护在 `docs/reference/`。
+HWLAB 是硬件实验室运行面和控制面项目。本文件只作为低噪声顶级索引，详细规则统一进入 `docs/reference/` 或对应 skill；远端读取 `AGENTS.md` 不应超过 UniDesk CLI 默认输出阈值。

-## P0 CaseRun 无服务与单步调试规则
+## P0 当前任务定位

- P0: HWPOD CaseRun、case registry 产物整理、trace 语义化、harness 诊断、短连接 CLI 和目标 node/lane host 上可直接运行的 runner 调试，默认是无服务工作流；目标 node 和 lane 以 issue、PR、CLI 参数或 `deploy/deploy.yaml` 的明确声明为准。只要不需要变更 cloud-api、web、gateway、GitOps、k3s runtime 或其他常驻服务，就必须直接无服务运行和验证，禁止为了运行 CaseRun 触发 CI/CD、rollout 或服务发布。
- P0: CaseRun 卡在 hwpod-node、workspace prepare、编译、下载、串口、artifact 收集或其他基础设施步骤时，必须先把卡点拆成同一目标运行面的单步命令验证；禁止用反复全量 CaseRun 大回环替代单步定位。
- P0: 只有单步卡点已经验证通过，且需要验证完整编排、trace 和 registry 产物时，才启动一次完整 CaseRun；完整 CaseRun 仍必须按 cli-spec 异步启动、短轮询状态、收集 trace，不得加入 evidence 自动评价、门禁或自动判断。
+- 先按 issue、PR、CLI 参数或受控 lane 配置解析目标 `node + lane`；没有明确目标时才读取受控配置，禁止把 G14、v0.2、D601 legacy 或任意历史路径写成全局默认。
+- D601 v0.3 的固定 workspace 是 `/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `origin/v0.3`；它是当前 D601/v03 source truth，不是 legacy 对照面。
+- k3s 操作必须通过 UniDesk route，例如 `D601:k3s` 或 `G14:k3s`；不要使用另一节点 kubeconfig、Docker Desktop Kubernetes、master server 本地构建或旧 JS CD 结果作为当前 lane 证据。
+- `hyueapi.com` / `.hyueapi.com` 必须保留在 `NO_PROXY` / `no_proxy`，Codex API 通道不得被 HTTP/SOCKS proxy 劫持。

-## P0 文档/CLI 直接主 worktree 规则
+## P0 文档与可见性

- P0: 单纯文档、AGENTS.md、docs/reference、SPEC、短连接 CLI、trans/tran/helper 这类轻量变更，禁止为了“隔离开发”新建 git worktree；必须在当前 issue/CLI 明确的 node + lane 固定主 worktree 直接修改、提交并 push 到对应 remote 分支。没有明确目标时才读取受控配置解析默认值，禁止把 G14、D601 legacy 或 v0.2 写成全局默认。
- P0: 只有业务代码、运行面、发布链路、CI/CD、Secret、权限、数据迁移、PROD 或明确高风险改动，才按项目规则创建隔离 worktree 或走 PR；不要把重型开发流程套到文档/CLI 轻量变更上。
- P0: 若固定主 worktree 因并行 dirty 文件无法快进，先保留并行变更，只提交当前文档/CLI相关文件；必要时使用非破坏性 rebase/autostash 或等价方式对齐 remote 后直接 push，禁止绕到新 worktree 掩盖主 worktree 状态。
+- `AGENTS.md` 只保留项目索引、一句话规则和交叉引用；细则写入 `docs/reference/`，通用操作写入对应 skill，避免远端读取触发 dump。
+- 如果远端 `AGENTS.md`、CLI help 或默认命令输出超过 UniDesk dump 阈值，先改可见性：拆分文档、改简洁表格输出或补 drill-down，不用长 dump 当常态入口。
+- 编辑 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，先遵循 `docs-spec`；单纯文档/CLI/helper 轻量变更可在当前 node/lane 固定主 worktree 直接提交并 push。
+- GitHub issue/PR 正式写入走 UniDesk CLI；不要用原生 `gh` 或手写 GitHub API 写长期看板、反馈 issue 或 PR closeout。

-## P0 最高优先级：最新要求与旧门禁清除
+## P0 交付边界

- P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言、旧 guard 和旧 gate；开发过程中遇到任何阻碍最新目标的旧测试、旧门禁、旧预检或旧断言，一律拆除，禁止继续维护、修补、叠例外或用兼容路径绕行。
- P0: 短连接 CLI、临时工具、文档和轻量 helper 不套用常驻服务、镜像、Job、GitOps、PR、CI/CD 或重型发布流程的旧门禁；如果旧流程要求与最新架构定位冲突，以最新架构定位为准并删除旧流程入口。
- P0: 任何测试、预检或自检只允许表达当前最新目标行为；旧历史断言不得作为回归保护保留，避免把旧路线固化成长期摩擦。
+- CaseRun、case registry、trace 语义化、harness 诊断和短连接 runner 调试默认是无服务工作流；先单步定位卡点，再决定是否跑完整 CaseRun。
+- 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流；PR base 必须匹配当前 node/lane source branch。
+- 当前发布只走受控 node/lane Tekton/GitOps/Argo CD 控制面；旧 D601 `ci-publish`、`dev-cd-apply`、`dev-deploy-apply`、`dev-artifact-publish` 不得恢复。
+- 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言和旧 guard；阻碍最新目标的旧入口直接删除或迁移，不做兼容绕行。

-## P0 CLI 鉴权边界
+## Skill 路由

- P0: HWLAB CLI 和 AgentRun/HWPOD runner 只允许从 `HWLAB_API_KEY` 读取用户 API key；不得新增或复活 `API_KEY`、`HWLAB_BEARER_TOKEN`、`--api-key`、`--bearer-token` 等别名入口。HTTP `Authorization: Bearer` 只是 CLI 从 `HWLAB_API_KEY` 生成的协议 header，不是第二个配置来源。
- P0: Web 只走 `hwlab_session` Web session；CLI 保护命令缺少 `HWLAB_API_KEY` 时必须返回 `api_key_required` 或 `unsupported_api_key_source`，不得回退 Web session、cookie、password login 或 Keycloak token。
- P0: 处理 HWLAB CLI、Code Agent、HWPOD、trace/result、Web 等价 CLI 或 runtime 验收前，必须先按当前 issue/CLI 明确的 node + lane 读取对应 API key sourceRef 或受控本地 env 文件；禁止先把问题定性为缺少 API key，也禁止把某个节点或 v0.2 的路径写成全局默认。
- P0: 若当前进程没有继承 `HWLAB_API_KEY`，先确认目标 node/lane 的受控来源、`~/.bashrc` / `BASH_ENV` 注入和 CLI status 输出；不得改走别名、token、cookie、password login 或临时 fallback。
- P0: 查询 `HWLAB_API_KEY` 时只能输出 `present/missing`、source path、sourceRef 或 redacted prefix；禁止在 stdout、issue、trace、日志、AGENTS 或 docs 中打印完整 key。目标 runtime 中环境变量缺失不代表 key 不存在，应先通过同一受控来源注入再继续排查。
+- Code Agent session/trace/result/inspect/send：使用 `hwlab-code-agent` skill。
+- HWPOD CaseRun：使用 `hwlab-caserun` skill。
+- HWPOD node/cloud-api 注册与节点运维：使用 `hwpod-ops` skill。
+- DAD 跨节点修复、运行面实测和 PR/rollout 验收：使用 `dad-dev` skill。
+- GitHub issue/PR 写入：使用 UniDesk `unidesk-gh` skill 和 `bun scripts/cli.ts gh ...`。
+- OTel/Tempo 链路追踪：使用 UniDesk `unidesk-otel` skill。
+- Node/lane CI/CD、trigger-current、git mirror、Argo/Tekton：使用 UniDesk `unidesk-cicd` skill。

-## P0 node/lane 运行面归一
+## 长期参考索引

- HWLAB 当前开发、发布和验收目标必须先从 issue、PR、CLI 参数或受控 lane 配置解析 node + lane；例如 issue 明确 `目标节点：D601`、`目标分支：HWLAB v0.3` 时，D601 v0.3 就是当前运行面真相，不得回退到 G14、v0.2 或 D601 legacy。
- 每个 lane 的 source branch、开发 workspace、CI/CD source repo、namespace、公网入口、Secret sourceRef 和 route 由 `deploy/deploy.yaml` 及 UniDesk `hwlab nodes ... --node <node> --lane <lane>` 控制面解析；长期文档只能记录解析规则和专项规格，不能把某个 node/lane 的数值写成全局默认。
- `v0.2` 的人写 deploy/runtime 配置单一出处是 `deploy/deploy.yaml`；`deploy/deploy.json` 不再是 v0.2 兼容源。所有脚本、renderer、planner 和 CLI 必须通过 `scripts/src/structured-config.mjs` / `scripts/src/deploy-config.mjs` 这类格式无关读写层消费配置，禁止把 YAML parser import 或 ad hoc YAML 解析散落到业务脚本里。
- Node GitOps render 若改变 Argo Application、AppProject、runtime path 或 lane 拆分目录，必须同步应用对应 node/lane 的 GitOps 文件；只推 GitOps 分支不等于 Argo 已切到新 path。
- D601 旧 DEV、`dev-cd-apply`、`ci-publish` 和旧 `main` JS 脚本式 CI/CD 只属于 legacy 路径；D601 的 node-scoped runtime lane（例如 D601 v0.3）不属于 legacy。新开发、发布、验收、文档和运行面实验不得把 legacy 脚本 CD 当作当前 HWLAB runtime source-of-truth。
- k3s 操作必须通过当前目标 node 的 UniDesk route 执行，例如 `D601:k3s` 或 `G14:k3s`；不得用另一个节点的 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为当前 node/lane 的通过证据。
-
-## P0 HyueAPI Direct NO_PROXY 规则
-
- `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 子命令或文档入口。
- 当前发布只走受控 node/lane 的 Tekton/GitOps/Argo CD 控制面；镜像构建 helper 是 `scripts/artifact-publish.mjs`，desired state 由 `scripts/gitops-render.mjs` 或 node/lane 控制面生成，细则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。
- 发现旧脚本、旧文档或旧 `hwlab-cli cicd` 再次进入当前 node/lane Pipeline、AGENTS 或长期参考时，优先删除旧入口并把调用方改到受控 GitOps 路径，不再做兼容保留。
-
-## P0 门禁最小化纪律
-
- 架构迁移时，过时的自检、预检、guard、gate 优先拆除；不要在旧门禁上继续加例外、加复杂度或制造噪声。
- 新增自检、预检、guard、gate 必须遵循最小原则，只覆盖明确高价值风险；禁止乱加门禁导致系统僵化、难迁移、难调试或产生大量误报和摩擦。
-
-## P0 v0.2 文档治理
-
- `AGENTS.md` 是唯一顶级入口；`README.md`、`docs/*.md`、`docs/*.json` 和 `docs/plan/*.md` 不再作为 v0.2 仓库内文档形态保留。
- 计划、里程碑、阶段迁移、一次性排障和旧报告全文迁入 GitHub issue；长期参考只吸收稳定结论并引用对应 issue。
- v0.2 文档树收敛、D601/G14 旧口径处理和 JSON 放置边界见 [docs/reference/spec-v02-documentation-governance.md](docs/reference/spec-v02-documentation-governance.md)。
-
-## 工作区
-
- 当前工作区必须由 issue、PR、CLI 或受控 lane 配置解析，预检内容至少包括 `pwd`、`git status --short --branch`、`git remote -v` 和目标 node/lane control-plane status；不满足目标时先停止并修正 workspace。
- D601 v0.3 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/hwlab-v03`，固定跟踪 `origin/v0.3`；当 issue 明确 D601 v0.3 时，这个 workspace 是当前 source truth，不是 legacy 对照面。
- G14 v0.2、G14 DEV/PROD 或其他 lane 的固定 workspace 只在当前任务明确选择对应 node/lane 时使用；不得把它们写成所有 HWLAB 任务的默认入口，也不得用一个 lane 的 dirty、stale 或 untracked `.worktree/` 状态阻塞另一个 lane 的 CI/CD source commit 选择。
- 业务代码、运行面或高风险变更按当前 node/lane 的固定 workspace 创建独立 worktree；固定 repo 不作为并行任务 scratch 区，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
- k3s 操作必须通过目标 node 的 UniDesk SSH route 执行，例如 `D601:k3s` 或 `G14:k3s`；禁止使用 `ssh <node> k3s ...`。不要把 `/workspace/hwlab`、`/root/HWLAB`、master-server checkout、另一个节点 workspace 或临时 clone 当作当前 node/lane source truth。
- Runner 和指挥常用工作区是 `/workspace/hwlab`；进入仓库先检查分支与工作树状态，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
- CI/CD 由当前 node/lane 的 source branch、CI/CD source repo、Tekton/GitOps branch 和 Argo Application 驱动；需要构建、Playwright、check、发布预检或运行面验证时放到目标 node/k3s/runner/CI/CD，不在 master server 跑重型验证。
- 远端验证必须用短连接触发后台 job、PipelineRun、脚本任务或 `trans <node> playwright`，再用短连接轮询 status/tail/exit code；不要用 UniDesk SSH/tran 长连接等待 check、layout、Playwright、Tekton/Argo 或发布动作完整结束。
- D601 legacy 只指旧 DEV/CD 回放路径；D601 node-scoped runtime lane 由当前 issue/CLI 明确选择时是正式开发、发布和验收入口，当前入口见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。
- 交付路径按变更风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前工作线的 source branch；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，PR base 必须匹配当前 node/lane source branch，不能默认投向 `main`、G14 或 v0.2。默认不要合并自己的 PR，用户或指挥官明确授权且满足门禁时可按长期参考自合并，不要改 PROD、不要重启服务。
- `DC-DCSN-P0-2026-003` / [pikasTech/HWLAB#78](https://github.com/pikasTech/HWLAB/issues/78) 是当前 M3 虚拟硬件可信闭环的上位约束；其他任务不得把 SOURCE、LOCAL、DRY-RUN、fixture 或前端状态误报为 M3 DEV-LIVE。
- 仓库禁止创建或提交 repo report 目录；验收、进展和结论只承载在 #7、专题 issue、每日简报或 PR/issue 评论。临时 JSON 只能写入 `/tmp`、`.state` 或 CI artifact，不能进入源码仓库。
-
-## 固定入口
-
- Runtime Web/API/live 入口必须从当前 issue/CLI 明确的 node + lane control-plane status 读取；没有明确目标时才从受控 lane 配置解析，不得把 G14、v0.2、DEV/PROD 或 D601 legacy 端口写成所有任务默认入口。
- D601 v0.3、G14 v0.2 和其他 node/lane 的公网入口、namespace、route 与 GitOps 应分别由 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md) 和受控 CLI 输出确认。
- Cloud Workbench 默认首页与 UX 约束见 [docs/reference/cloud-workbench.md](docs/reference/cloud-workbench.md)。
-
-## 规格
-
- HWLAB Cloud M1 需求规格正文统一由 UniDesk OA 管理，入口是 [PJ2026-01 HWLAB 总规格](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md)。代码开发、测试补充和 issue 拆分应先对齐 UniDesk OA 对应规格，再回到本仓实现。
- 本仓库 `docs/reference/spec*.md`、`spec-v03-*.md` 和曾承担规格职责的长期参考只保留历史链接兼容 stub，不再承载需求正文、测试大纲、验收流水或治理规则；需要改规格时更新 UniDesk OA `project-management/PJ2026-01/specs/`。
- 总规格和 L1 入口：
-  - [PJ2026-0101 硬件池](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md)
-  - [PJ2026-0102 Agent编排](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md)
-  - [PJ2026-0103 HarnessRL](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md)
-  - [PJ2026-0104 客户端](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0104-client.md)
-  - [PJ2026-0105 用户管理](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md)
-  - [PJ2026-0106 平台运维](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md)
- 高频旧路径映射：`spec-v02-hwlab-cli.md` -> [PJ2026-010402 HWLAB CLI](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-010402-hwlab-cli.md)；`spec-v02-hwlab-cloud-web.md` 和 `spec-v03-workbench-vue-migration.md` -> [PJ2026-010401 Web工作台](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md)；`spec-v02-hwlab-cloud-api.md` -> [PJ2026-010403 API契约](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md)；`spec-v03-user-billing.md` -> [PJ2026-0105 用户管理](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md)；HWPOD/CaseRun 旧规格分别归 [硬件池](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md) 和 [HarnessRL](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md)。
- hwpod-node 运维（G14/D601 启停、cloud-api 注册、源码同步、故障排查）见 `hwpod-ops` skill；Code Agent session/trace/result/inspect/steer 操作见 `hwlab-code-agent` skill；CaseRun 无服务入口见 `hwlab-caserun` skill。
-
-## 长期参考
-
- 唯一入口纪律：`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)
+- Agent 入口拆分、输出预算、skill/reference 归属：[docs/reference/agent-entrypoint.md](docs/reference/agent-entrypoint.md)
+- 指挥官协作、worktree、PR、自合并和 prompt handoff：[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
+- Node GitOps CI/CD、当前受控发布边界：[docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)
+- DEV/runtime 边界与禁止误判：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md)
+- Cloud Workbench 默认首页与 UX 约束：[docs/reference/cloud-workbench.md](docs/reference/cloud-workbench.md)
+- Code Agent 真实回复、provider blocker 与 readiness：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
+- AgentRun 手动调度与 UniDesk SSH passthrough：[docs/reference/agentrun-code-agent-dispatch.md](docs/reference/agentrun-code-agent-dispatch.md)
 - 文档治理与 docs-spec 本地权威：[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md)
- v0.2 文档治理规格、过程文档迁 issue、`docs/` 根目录清理和 D601/G14 旧口径收敛：[docs/reference/spec-v02-documentation-governance.md](docs/reference/spec-v02-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/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)、[docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)
- G14 GitOps CI/CD、Tekton/Argo CD、集群内 registry 和无锁镜像化发布：[docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)
- G14 CI/CD 性能基线、根因分析和加速收益估算：[docs/reference/node-cicd-performance.md](docs/reference/node-cicd-performance.md)
- Code Agent 对话就绪与真实回复判定：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md)
- AgentRun 手动调度装配、UniDesk SSH passthrough 与 GitHub tool credential 边界：[docs/reference/agentrun-code-agent-dispatch.md](docs/reference/agentrun-code-agent-dispatch.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)
+- 中文优先规则：[docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md)
+- 用户反馈分流：[docs/reference/user-feedback-triage.md](docs/reference/user-feedback-triage.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 到当前 node/lane 的 source branch；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，详见 [docs/reference/commander-collaboration.md](docs/reference/commander-collaboration.md)。
-
-## 常用轻量命令
-
- 静态合同校验：`npm run validate`
- Cloud Web worktree 依赖准备：`npm run worktree:deps`；新 `.worktree/<task>` 内需要 Web 检查时先复用固定 workspace 的共享依赖，`web:check` 和 `web:build` 会自动调用。
- Cloud Web 静态检查：`npm run web:check`
- Cloud Web 构建：`npm run web:build`
- Cloud Web M3 只读护栏：`npm run web:m3-readonly`
- G14 artifact build helper：`node scripts/artifact-publish.mjs --publish ...`，只能由 G14 Tekton task 携带 CI artifact identity 调用；人工发布走 G14 poller/GitOps，不走 legacy CLI CD。
- G14 monorepo 组件计划：`node scripts/ci-plan.mjs --base-ref <ref> --target-ref <ref> --pretty`，只读分析 affected/reused services，基于内建 service-path component model 与 `deploy/deploy.yaml`；细则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。
- G14 GitOps 渲染：`npm run gitops:render`；source 分支不再运行生成物 drift check，发布态由 Tekton 写入 `G14-gitops`。
- 平行 lane 配置扩容：`npm run lane:expand -- configure --lane v03 --from v02 --write`，只写 `deploy/deploy.yaml` 的新 lane 声明，后续 `v04`/`v05`/`v06` 复用同一入口。
- GitOps lane 严格 TS 检查：`npm run gitops:ts:check`；新拆 GitOps 模块直接进入 `scripts/src/*.ts` 和 `tsconfig.gitops.json`，不要继续堆进单个 `.mjs`。
- DEV 依赖 runtime base 构建：`npm run dev-runtime-base:build`
- Legacy D601 DEV CD：旧脚本入口已删除；事故回放只读历史 issue/commit，不恢复旧命令。
- WEB 等价短连接 CLI：在当前 node/lane 固定 workspace 直接运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client ... --base-url <target-web-url>`，默认走 Cloud Web 同源 API；能力规格见 UniDesk OA [PJ2026-010402 HWLAB CLI](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-010402-hwlab-cli.md)，操作细则见 `hwlab-code-agent` skill 和本仓实现。
- Code Agent session/trace/result/inspect/steer 操作见 `hwlab-code-agent` skill。
- HWPOD CaseRun 无服务入口：用法见 `hwlab-caserun` skill；HWPOD 能力规格见 UniDesk OA [硬件池](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md)，CaseRun 语义见 [HarnessRL](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md)。
- 目标 k3s 只读观测：使用当前 node/lane 的 UniDesk route，例如 `D601:k3s` 或 `G14:k3s`；D601 legacy 事故复盘只在任务明确选择旧路径时使用。
- DEV runtime hotfix 只读审计计划：`npm run dev-runtime:hotfix-audit`
- Gateway 主动出站本地 smoke：`npm run gateway:demo:smoke`；经本地 edge-proxy 验证用 `npm run gateway:demo:edge-smoke`。
-
-## D601 legacy 与 D601 node-scoped lane
-
-`D601 legacy` 只指旧 DEV/CD、迁移对比、事故回放和历史证据查询路径。D601 上的 node-scoped runtime lane（例如 issue/CLI 明确的 D601 v0.3）是正式当前目标，不得被 legacy 规则排除；需要观察当前运行态时使用该 node/lane 的 UniDesk route，例如 `D601:k3s`，细则见 [docs/reference/node-gitops-cicd.md](docs/reference/node-gitops-cicd.md)。
-
-## 禁止误判
-
- `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)。
+- 当前 node/lane 状态由 UniDesk 受控 CLI 查询，例如 `bun scripts/cli.ts hwlab nodes control-plane status --node D601 --lane v03`。
+- Web 等价短连接 CLI 在当前 node/lane 固定 workspace 运行 `bun tools/hwlab-cli/bin/hwlab-cli.ts client ... --base-url <target-web-url>`。
+- Cloud Web 检查需要依赖时先跑 `npm run worktree:deps`；随后按任务需要跑 `npm run web:check` 或 `npm run web:build`。
+- G14/D601 发布和 git mirror 操作以 UniDesk `hwlab nodes ...` / `hwlab g14 ...` 受控入口为准，不使用旧脚本 CD。