docs: add HWLAB commander reference
This commit is contained in:
Codex
@@ -78,6 +78,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
|
||||
- `docs/reference/staff-reference.md`：幕僚长期参考、决策过程和用户偏好摘要；与 `strategy-governance`、`code-queue-supervision` 配套。
|
||||
- `docs/reference/secretary-reference.md`：秘书日程管理、时间盒、短期待办捕获和 Todo Note / Decision Center 分流规则。
|
||||
- `docs/reference/code-queue-supervision.md`：Code Queue 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。
|
||||
- `docs/reference/hwlab.md`：HWLAB 指挥侧固定 workspace、D601 原生 k3s 口径、16666/16667 DEV 入口和已验证手动发布路径。
|
||||
- `docs/reference/observability.md`：服务日志、任务活性、通用性能指标 API 和性能面板的可观测性规则。
|
||||
- `docs/reference/microservices.md`：用户服务（兼容命名 `microservice`）的配置、代理、安全边界、unidesk-direct/k3sctl-managed 部署模式、Todo Note/Baidu Netdisk on main-server、k3s Control/Code Queue/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 和验证规则。
|
||||
- `docs/reference/windows-passthrough.md`：WSL provider 通过 SSH 透传调用 Windows cmd/PowerShell、Keil、COM 串口和 Windows 侧 skill 的长期规则。
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
# HWLAB 指挥侧参考
|
||||
|
||||
本文定义 UniDesk 指挥官推进 `pikasTech/HWLAB` 时的固定入口、workspace、上线口径和常见误判边界。HWLAB 的项目内操作细则以 HWLAB 仓库自己的 `AGENTS.md` 和 `docs/reference/` 为准；本文只记录 UniDesk 侧如何进入和监督。
|
||||
|
||||
## 固定入口
|
||||
|
||||
- UniDesk 指挥侧 workspace：`/root/unidesk`，固定使用 `master`，开始前执行 `git status` 和 `git pull --ff-only origin master`。
|
||||
- HWLAB 指挥侧 workspace：`/workspace/hwlab`，固定使用 `main`，开始前执行 `git status` 和 `git pull --ff-only origin main`。
|
||||
- HWLAB 项目内长期规则入口：`/workspace/hwlab/AGENTS.md`。
|
||||
- D601 HWLAB 运行副本：通过 `bun scripts/cli.ts ssh D601` 进入，优先使用 `/home/ubuntu/workspace/hwlab`；该目录是 D601 上的部署/构建副本，开始前也要 `git -C /home/ubuntu/workspace/hwlab pull --ff-only origin main`。
|
||||
- D601 上 `/home/ubuntu/hwlab` 可能是 runner 或并行任务工作区。指挥官不能把它当作部署真相，也不能清理、reset 或复用其中的 runner worktree。
|
||||
|
||||
## 关键 GitHub 入口
|
||||
|
||||
- UniDesk 总看板：`pikasTech/unidesk#20`。
|
||||
- HWLAB 总看板：`pikasTech/HWLAB#7`。
|
||||
- HWLAB 上位会议/冻结规则：`pikasTech/HWLAB#78`，当前 P0 是 M3 虚拟硬件可信闭环。
|
||||
- HWLAB Cloud Workbench 用户界面：`pikasTech/HWLAB#99`。
|
||||
- HWLAB 用户反馈入口：`pikasTech/HWLAB#108`。
|
||||
- HWLAB 手动发布复盘与自动化收敛：`pikasTech/HWLAB#61`。
|
||||
|
||||
## DEV 入口
|
||||
|
||||
- DEV 前端入口固定为 `http://74.48.78.17:16666/`。
|
||||
- DEV API/live 入口固定为 `http://74.48.78.17:16667/health/live`。
|
||||
- 旧公网 `:6666` 和 `:6667` 不是浏览器验收入口；内部 k3s service 仍可使用 `6667` 作为服务端口。
|
||||
- `16666` 由 master 侧 `hwlab-frps-dev` 接收 D601 `hwlab-frpc` 的反向代理流量；不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。
|
||||
|
||||
## D601 k3s 口径
|
||||
|
||||
HWLAB 的真实 DEV runtime 在 D601 原生 k3s 中，必须显式使用：
|
||||
|
||||
```sh
|
||||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev get deploy,svc,pod -o wide
|
||||
```
|
||||
|
||||
不要直接相信默认 `kubectl` context。D601 上默认 context 可能是 `docker-desktop`，它会展示另一套与公网 `16666/16667` 无关的状态，并可能给出误导性的 `ImagePullBackOff`。
|
||||
|
||||
`frpc` 配置不是 D601 host `/etc/frp/frpc.toml`，而是 `hwlab-dev` namespace 里的 `hwlab-frpc-config` ConfigMap 和 `hwlab-frpc` Deployment。master 侧 `frps` 配置由 `hwlab-frps-dev` 容器挂载 `/opt/hwlab-frp/frps.dev.toml`。
|
||||
|
||||
## 已验证的 Cloud Web 手动 DEV 发布路径
|
||||
|
||||
当只需要发布 `hwlab-cloud-web` 到 DEV 时，使用以下路径；它是当前手动 CD 的基准，后续自动化应收敛到 HWLAB `deploy/deploy.json` 和 CLI，而不是重新发明路径。
|
||||
|
||||
1. 更新 D601 部署副本：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh D601 'cd /home/ubuntu/workspace/hwlab && git pull --ff-only origin main'
|
||||
```
|
||||
|
||||
2. 刷新 Cloud Web 静态构建产物。运行时 wrapper 优先读取 `web/hwlab-cloud-web/dist`，如果该目录残留旧内容，即使源码已经更新，镜像仍可能继续服务旧页面：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh D601 'cd /home/ubuntu/workspace/hwlab && node web/hwlab-cloud-web/scripts/build.mjs'
|
||||
```
|
||||
|
||||
3. 发布镜像到 D601 本地 registry：
|
||||
|
||||
```sh
|
||||
bun scripts/cli.ts ssh 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
|
||||
bun scripts/cli.ts ssh 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
|
||||
bun scripts/cli.ts ssh 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 和 `deploy/deploy.json`。
|
||||
Reference in New Issue
Block a user