docs: align v0.2 reference specs

2026-05-28 20:04:04 +08:00
parent 74905f9d22
commit 256866b024
6 changed files with 16 additions and 17 deletions
@@ -39,7 +39,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥
 - 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、不要重启服务。
+- 交付路径按变更风险选择：单纯文档、CLI/helper 轻量变更直接提交并 push 到当前工作线的 source branch，G14 默认 `origin/G14`，`v0.2` 默认 `origin/v0.2`；业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或其他高风险变更走 PR 工作流，PR base 必须匹配当前工作线，不能默认投向 `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，不能进入源码仓库。

@@ -25,7 +25,7 @@
 - G14 人工/指挥官开发必须先在固定 repo `/root/hwlab` 做 `pwd`、`git status --short --branch`、`git remote -v` 和 `fetch` 预检，再在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建任务专属 worktree；代码、文档、测试补丁、提交和 PR 准备都在该独立 worktree 中完成。
 - G14 `v0.2` 固定 workspace 是 `/root/hwlab-v02`，固定跟踪 `origin/v0.2`。所有 `v0.2` 文档、计划、CI/CD lane 和 namespace 设计必须在该 workspace 或其明确创建的 `v0.2` worktree 中完成；不得使用 `/root/hwlab` 根目录或现有 `hwlab-dev`/`hwlab-prod` 运行面作为 `v0.2` scratch 区。
 - 固定 repo `/root/hwlab` 是 source truth 和 worktree 管理入口，不是并行任务 scratch 区；不要在固定 repo 根目录堆叠未提交改动，也不要复用其他任务遗留 `.worktree/<task>`。
- D601 发布和 rollout 工作区是 `/home/ubuntu/workspace/hwlab`。
+- D601 `/home/ubuntu/workspace/hwlab` 只作为 legacy 事故回放和迁移对照工作区；当前 G14 DEV/PROD 与 `v0.2` 发布、rollout 和验收不使用 D601 作为运行面真相。
 - 不要清理、reset 或复用无关 runner worktree 作为发布真相。

 ## 分支和交付工作流
@@ -35,13 +35,13 @@
 - 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD、重启服务、CI/CD 控制面高风险变更或其他影响 runtime truth 的变更默认走 PR 工作流。
 - 用户或指挥官给出最新交付纠偏时，以最新要求为准，删除旧断言或旧门禁，不用 feature flag、legacy mode 或双路径长期并存绕开最新要求。

- 从最新 `origin/main` 创建短分支。
- 不要直推 `main`。
+- G14 线需要 PR 时，从最新 `origin/G14` 创建短分支，PR base 指向 `pikasTech/HWLAB:G14`；`v0.2` 线需要 PR 时，从最新 `origin/v0.2` 创建短分支，PR base 指向 `pikasTech/HWLAB:v0.2`。
+- `origin/main` / `main` 不再是当前 G14 或 `v0.2` 默认开发、PR 或发布 base；只有显式 branch-governance 或 D601 legacy 任务才可使用。
 - 不要修改 PROD。
 - 除非任务明确授权，不要重启服务。
- 需要 PR 时向 `pikasTech/HWLAB:main` 创建 PR。
+- 需要 PR 时，目标分支必须匹配当前工作线的 source branch；不要把 G14 或 `v0.2` 变更默认投向 `main`。
 - runner 默认不合并自己的 PR；用户或指挥官可以对单个 PR 明确授权 runner 自合并。
- 自合并前必须同时满足：PR 为 `MERGEABLE/CLEAN` 或等价无冲突状态；required checks 没有失败；D601/CI 或指定运行态验证证据已贴到 PR/issue；变更不涉及 PROD、Secret、权限提升、数据迁移或未授权重启；runner 在最终评论中列出提交 SHA、验证命令和回滚边界。
+- 自合并前必须同时满足：PR 为 `MERGEABLE/CLEAN` 或等价无冲突状态；required checks 没有失败；G14/`v0.2` CI 或当前 issue 显式指定的 legacy/runtime 验证证据已贴到 PR/issue；变更不涉及 PROD、Secret、权限提升、数据迁移或未授权重启；runner 在最终评论中列出提交 SHA、验证命令和回滚边界。
 - 当前 GitHub 写入仍优先走 UniDesk CLI 或 repo-owned GitHub 路径；若当前 CLI 不支持 merge，必须使用可审计的授权路径，不能用无记录的本地绕行来规避审计。
 - PR 冲突由指挥官审阅并处理；runner 不做大范围冲突手术，除非被明确分配。
 - 指挥官合并 PR 时必须同时 review，确认方向没有偏离 `#7`、`#78`、`#99` 和当前用户反馈。
@@ -50,9 +50,9 @@ tran G14:k3s kubectl -n hwlab-v02 get deploy,svc,pod -o wide

 Do not use D601 kubeconfig, D601 `dev-cd-apply`, old JS `ci-publish`, Docker Desktop Kubernetes, or master-server local checks as G14 runtime acceptance evidence. D601 remains a legacy migration/reference surface until the branch-role migration is complete.

-## Branch Role Migration
+## Branch Role Boundary

-The target branch model is: G14 becomes the `main` runtime source branch, and the former D601-oriented `main` behavior moves to a D601 legacy/maintenance line. Until that branch governance operation is explicitly completed and verified, `/root/hwlab` on G14 continues to use the `G14` branch and must merge the latest `origin/main` business updates before G14-specific runtime work. The `v0.2` expansion does not complete or replace that governance operation; it adds a separate `v0.2` branch and `hwlab-v02` runtime lane beside the existing G14 DEV/PROD lanes.
+Current runtime work uses explicit branch lines: G14 DEV/PROD uses `origin/G14`, and the additive `v0.2` lane uses `origin/v0.2` plus `hwlab-v02`. Do not merge `origin/main` as a routine precondition for G14 or `v0.2` runtime work. Treat `main` only as a historical branch-governance or D601 legacy reference unless a current issue explicitly assigns a `main` migration task. The `v0.2` lane remains separate from G14 DEV/PROD; its CI/CD branch, runtime path and acceptance rules are authoritative in [spec-v02-cicd.md](spec-v02-cicd.md).

 ## Distributed Passthrough Hygiene

@@ -127,13 +127,12 @@ node scripts/dev-runtime-hotfix-audit.mjs --collect-readonly --pretty

 优先回滚方式是用源码化 artifact/CD 覆盖 runtime hotfix：#460/#461 合并并发布后，Deployment 应消费正式镜像，不再通过 ConfigMap 覆盖 `/app/internal/cloud/code-agent-chat.mjs`。注意 `kubectl apply -k` 可能保留运行面 patch 写入、且源码 desired-state 不拥有的 hotfix `volumes`、`volumeMounts` 或 template annotations；正式 DEV CD apply 应先识别这种 unmanaged hotfix 覆盖，删除对应 desired Deployment，再由同一次 apply 从源码重新创建。

-只读确认口径是：
+只读确认口径是通过当前 G14 k3s route 读取目标对象；不要从 master server 裸跑 `kubectl`，也不要把 D601 kubeconfig 当作当前 DEV/v0.2 控制面：

 ```sh
-export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
-kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
-kubectl -n hwlab-dev get deployment hwlab-cloud-api -o json
-kubectl -n hwlab-dev get configmap hwlab-cloud-api-code-agent-hotfix -o json
+bun scripts/cli.ts ssh G14:k3s kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
+bun scripts/cli.ts ssh G14:k3s kubectl -n hwlab-dev get deployment hwlab-cloud-api -o json
+bun scripts/cli.ts ssh G14:k3s kubectl -n hwlab-dev get configmap hwlab-cloud-api-code-agent-hotfix -o json
 node scripts/dev-runtime-hotfix-audit.mjs --collect-readonly --pretty
 ```

@@ -144,7 +143,7 @@ node scripts/dev-runtime-hotfix-audit.mjs --collect-readonly --pretty
 - `hwlab.pikastech.local/pc-gateway-shell-hotfix` 等 hotfix annotation；
 - 不再需要的 `hwlab-cloud-api-code-agent-hotfix` ConfigMap。

-直接 `kubectl patch`、`kubectl delete configmap`、`kubectl rollout status` 或等价写操作必须由明确授权的 DEV 操作者执行，并且仍要使用 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml` 与节点 `d601` 确认。本 runbook 的审计脚本不执行这些写操作。回滚后再次运行 `scripts/dev-runtime-hotfix-audit.mjs --collect-readonly`，期望分类包含 `no-hotfix-detected`，且不包含 `deployment-mounts-hotfix`、`pod-loads-hotfix-marker` 或 `rollback-required`。
+直接 `kubectl patch`、`kubectl delete configmap`、`kubectl rollout status` 或等价写操作必须由明确授权的 DEV 操作者执行，并且当前 G14 DEV/v0.2 运行面必须通过 UniDesk route `G14:k3s` 操作。D601 kubeconfig 和节点确认只适用于显式 D601 legacy 事故回放，不能作为当前 G14 DEV/v0.2 hotfix 控制面。本 runbook 的审计脚本不执行这些写操作。回滚后再次运行 `scripts/dev-runtime-hotfix-audit.mjs --collect-readonly`，期望分类包含 `no-hotfix-detected`，且不包含 `deployment-mounts-hotfix`、`pod-loads-hotfix-marker` 或 `rollback-required`。

 ## 禁止误用

@@ -7,7 +7,7 @@
 - `hwlab-gateway` 运行在用户 PC 或本地环境，主动访问 `hwlab-cloud-api`；cloud 不需要也不应入站访问 gateway。
 - demo 采用普通 HTTP poll/result：gateway 调 `POST /v1/gateway/poll` 拉取命令，执行后调 `POST /v1/gateway/result` 回传 JSON-RPC response。
 - `hardware.invoke.shell` 仍是 cloud-api 对外 RPC 方法；有在线 gateway 时通过主动出站链路派发，没有在线 gateway 时保留 `not_connected` 降级返回。
- 当前命令执行能力只用于受限 demo；正式真实硬件控制仍应沿用统一 capability、audit、evidence 和后续 WebSocket/设备身份设计。
+- 当前命令执行能力只用于受限 demo；正式真实硬件控制以 [spec-device-pod.md](spec-device-pod.md) 和 [spec-user-access.md](spec-user-access.md) 为权威：用户权限由 `cloud-api` 的 `admin/user` 与 device pod grant 判断，不拆 capability；设备执行收敛到 `cloud-api -> hwlab-device-pod -> gateway`，硬件 trace/evidence/audit 只作为硬件证据链，不作为用户权限模型。

 ## Cloud API 入口

@@ -146,9 +146,9 @@

 GitOps branch 已更新、source branch render 通过、PipelineRun 名称存在或 `G14` DEV/PROD health 正常，都不能单独代表 `v0.2` CI/CD 通过。

-## 扩容坑点与后续建议
+## 平行 lane 运维边界

-后续新增 `v0.x` 或其他平行 runtime lane 时，优先复用本节的判定顺序和排障边界，避免把一次性补丁沉淀成新的宽泛门禁。
+后续新增 `v0.x` 或其他平行 runtime lane 时，优先复用本节的判定顺序和排障边界，避免把一次性补丁沉淀成新的宽泛门禁。本节只保留可复用的运维边界；具体执行记录、排障流水和一次性证据应放在 issue、PR 或 `docs/plan/` 中。

 ### Secret 导入与重启边界