diff --git a/AGENTS.md b/AGENTS.md index 3524df59..cac87a3b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,20 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文件是项目顶级索引,也承担 `scripts/cli.ts` 的 CLI 使用说明入口。 +## Critical Long-Term Reference Docs Rule + +- P0: 任何新增、修改或蒸馏 `docs/reference/*.md` 长期参考文档的动作,必须遵循 `docs-spec` 规范;禁止绕过 `docs-spec` 凭临时习惯改写长期参考。 +- `AGENTS.md` 只做顶级索引和一句话规则摘要;长期稳定、可复用的约束、入口、判定标准必须落到 `docs/reference/`,再由 `AGENTS.md` 提供索引。 +- 过程记录、一次性排障、临时结论、带日期的流水账不得直接写成长期参考;需要沉淀时必须按 `docs-spec` 先蒸馏,再写入 `docs/reference/`。 + +## Critical G14 HWLAB Workspace Rule + +- P0: `G14:HWLAB` 的唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`,固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`;所有 G14 侧 HWLAB 代码、文档、render、polling、CI/CD 修复都必须以该目录为准。 +- 操作入口必须通过 UniDesk SSH 维护桥:host/source 操作用 `bun scripts/cli.ts ssh G14 script` 或 `bun scripts/cli.ts ssh G14 apply-patch`,k3s 操作用 `bun scripts/cli.ts ssh G14:k3s ...`;禁止使用 `ssh G14 k3s ...`,定位必须写在第一个 route token,后续 token 才是 operation。 +- 每次开始 `G14:HWLAB` 工作前必须先通过 SSH 桥在 G14 执行 `cd /root/hwlab && git status --short --branch && git remote -v`;若分支不是 `G14...origin/G14`、remote 不是 `git@github.com:pikasTech/HWLAB.git`,或当前路径不是 `/root/hwlab`,必须停止并先修正 workspace,不得继续开发、render、polling 或部署。 +- 禁止把 master server、D601、`/root/HWLAB`、`/home/ubuntu/hwlab`、`/workspace/hwlab` 或临时 clone 当作 `G14:HWLAB` source truth;master server 也不得运行 HWLAB check、Playwright/browser smoke、镜像构建或其他重型验证,验证必须走 G14 `/root/hwlab`、G14 k3s/Tekton 或其他获批外部执行面。 +- 长期细节见 `docs/reference/g14.md`;G14 节点本地也保留 `/root/docs/hwlab-g14-workspace.md`,两处口径必须保持一致。 + ## Critical D601 Kubernetes Control-Plane Rule - P0: D601 上的 Kubernetes 运行面只能以自部署原生 k3s 为准;Docker Desktop Kubernetes 已经停用并清理数据,任何人不得重新启用或把它作为 UniDesk/HWLAB 部署、CI/CD、诊断或验收目标。跟踪 issue: [pikasTech/unidesk#138](https://github.com/pikasTech/unidesk/issues/138),热修复背景见 [pikasTech/unidesk#118](https://github.com/pikasTech/unidesk/issues/118)。 diff --git a/docs/reference/g14.md b/docs/reference/g14.md index 841468ba..597557a2 100644 --- a/docs/reference/g14.md +++ b/docs/reference/g14.md @@ -8,7 +8,22 @@ For Code Queue and CI/CD migration preparation, G14 uses native k3s labels `unid ## HWLAB DEV Staging -G14 can host a build-only HWLAB DEV staging cluster in the native k3s namespace `hwlab-dev`. The source checkout is `/root/hwlab`, and images should be built on G14 with the HWLAB repo-owned artifact script in build-only mode, then loaded or pushed to the G14-local registry before applying Kubernetes manifests. +G14 can host a parallel HWLAB DEV staging cluster in the native k3s namespace `hwlab-dev`. The canonical G14 HWLAB source workspace is `/root/hwlab` on branch `G14`, with `origin` set to `git@github.com:pikasTech/HWLAB.git`; G14 source edits, CI/CD script changes, render work and manual polling must be done from that workspace through UniDesk SSH passthrough. Do not use `/root/HWLAB`, `/home/ubuntu/hwlab`, `/workspace/hwlab` or a master-server checkout as persistent G14 source truth. G14-local details are mirrored on the node in `/root/docs/hwlab-g14-workspace.md`. + +The standard entry forms are: + +```bash +bun scripts/cli.ts ssh G14 script <<'SCRIPT' +set -eu +cd /root/hwlab +git status --short --branch +SCRIPT + +bun scripts/cli.ts ssh G14 apply-patch < patch.diff +bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci +``` + +`G14:k3s` is the only supported k3s route form. Do not use `ssh G14 k3s ...`; the first token must locate the distributed target, and the following tokens must be the operation. The G14 HWLAB DEV boundary is: @@ -19,6 +34,7 @@ The G14 HWLAB DEV boundary is: - Use only G14-local placeholder Codex auth for mount/readiness tests unless real Code Agent execution on G14 has been separately authorized; do not copy D601 or production auth material. - Set `HWLAB_CLOUD_API_PORT=6667` explicitly in the G14 cloud-api Deployment. Kubernetes otherwise injects a `HWLAB_CLOUD_API_PORT=tcp://...` Service environment variable that breaks the Node port parser. - Override `HWLAB_PUBLIC_ENDPOINT` to a cluster-local G14 endpoint while no public tunnel is active, so staging services do not advertise the D601 production endpoint. +- Do not run HWLAB repository `check`, Playwright/browser smoke, image builds or other heavy validation on the master server. Run those through G14 `/root/hwlab`, G14 k3s/Tekton, or another explicitly approved external execution plane. After the G14-local database is provisioned, run the HWLAB migration CLI only against the G14 DEV database with explicit non-production confirmations: diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index cf590221..f5486434 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -9,6 +9,8 @@ - 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。 +- `G14:HWLAB` 固定 workspace:只能通过 UniDesk SSH 桥进入 G14 的 `/root/hwlab`,固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。每次开始 G14 工作前必须执行 `cd /root/hwlab && git status --short --branch && git remote -v`,期望分支是 `G14...origin/G14`;若不满足,先修正 workspace,不能继续开发、render、polling 或部署。 +- G14 k3s 操作必须使用 route 语法 `G14:k3s`,例如 `bun scripts/cli.ts ssh G14:k3s kubectl get pods -n hwlab-ci`;禁止写成 `ssh G14 k3s ...`。`/root/HWLAB`、`/home/ubuntu/hwlab`、`/workspace/hwlab`、D601 workspace、master-server checkout 或临时 clone 都不能作为 `G14:HWLAB` source truth。 ## 关键 GitHub 入口