From 8abcf9998b1ab3762910f1d07aacba6556b34d66 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 28 May 2026 06:14:44 +0000 Subject: [PATCH] docs: record HWLAB v0.2 G14 expansion line --- AGENTS.md | 1 + docs/reference/g14.md | 19 +++++++++++++++++++ docs/reference/hwlab.md | 2 ++ 3 files changed, 22 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e0d17a4f..b2eba420 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 ## Critical G14 HWLAB Workspace Rule - P0: `G14:HWLAB` 是当前 HWLAB DEV/PROD source workspace 和 k3s/GitOps 运行面真相；唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`；所有 HWLAB 新开发、文档、render、polling、CI/CD/GitOps 修复默认都必须以该目录和 G14 运行面为准。 +- P0: HWLAB `v0.2` 是在 G14 上的加法扩容线，不改变、删除或重命名现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口；`v0.2` 固定使用分支 `v0.2`、workspace `G14:/root/hwlab-v02`、namespace `hwlab-v02` 和 19666/19667 FRP 入口，长期细则见 `docs/reference/g14.md`。 - P0: 每次开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的 `/root/hwlab/AGENTS.md`，并以该文件和其引用的 HWLAB repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。 - 操作入口必须通过 UniDesk SSH 维护桥：host/source 操作用 `bun scripts/cli.ts ssh G14 script` 或 workspace route 加 `apply-patch`，远端文本 patch 默认使用 `apply-patch` 的 v2 引擎、旧 helper 仅通过 `apply-patch-v1` 显式调用；k3s 操作用 `bun scripts/cli.ts ssh G14:k3s ...`；禁止使用 `ssh G14 k3s ...`，定位必须写在第一个 route token，后续 token 才是 operation。 - P0: 每次开始 `G14:HWLAB` 工作前，固定仓库 `/root/hwlab` 必须先即时快进到 `origin/G14` 最新；先通过 SSH 桥执行 `cd /root/hwlab && git fetch origin G14 && git pull --ff-only origin G14 && git status --short --branch && git remote -v`。若有未提交并行变更阻碍快进，必须先判断是否能与最新 `origin/G14` 快速合并；能合并则立即合并，禁止默认 stash、丢弃或绕到落后 worktree；只有确实无法自动合并时才隔离保存并停止交给人工决策。禁止用落后的固定仓库继续预检、创建 worktree、开发、render、polling 或部署。 diff --git a/docs/reference/g14.md b/docs/reference/g14.md index 36fd058a..c9f2e8a3 100644 --- a/docs/reference/g14.md +++ b/docs/reference/g14.md @@ -44,6 +44,25 @@ kubectl -n hwlab-dev exec deploy/hwlab-cloud-api -- \ Healthy G14 HWLAB runtime means the main Deployments and StatefulSets are Ready, `cloud-api` and `edge-proxy` return `/health/live` with `status=ok`, durable runtime checks pass, and the public G14 DEV endpoints report the expected revision. For a device-agent smoke, health also requires the standalone device-agent Service to answer in-cluster and the D601 Windows gateway session/resource/capability to be visible through G14 cloud-api. +## HWLAB v0.2 Expansion Line + +HWLAB `v0.2` is an additive G14 expansion line. It must not rename, delete, repurpose, or mutate the existing `G14` source branch, `G14-gitops` branch, `hwlab-dev` namespace, `hwlab-prod` namespace, DEV public ports `17666/17667`, or PROD public ports `18666/18667`. Existing DEV/PROD CI/CD remains the stability baseline while `v0.2` is introduced beside it. + +The fixed `v0.2` source branch is `v0.2`, forked from the current `G14` branch after the G14 long-term reference docs record this decision. The fixed G14 workspace for that branch is: + +```bash +tran G14:/root/hwlab-v02 script -- 'git status --short --branch && git remote -v' +``` + +`/root/hwlab-v02` is the long-lived `v0.2` source workspace, not a scratch clone. It must track `origin/v0.2` with `origin git@github.com:pikasTech/HWLAB.git`. Existing `G14` work continues to use `/root/hwlab`; do not reuse `/root/hwlab` or `/root/hwlab/.worktree/*` as the `v0.2` fixed workspace. + +The fixed `v0.2` runtime namespace is `hwlab-v02`. The intended public FRP allocation is: + +- Cloud Web browser entry: `http://74.48.78.17:19666/`. +- API/edge entry and live health: `http://74.48.78.17:19667/health/live`. + +The `v0.2` CI/CD integration must be additive: add a `v0.2` source watcher, GitOps desired-state lane, Argo CD Application, namespace resources, artifact catalog, and `deploy.json` environment only when they target `v0.2`/`hwlab-v02` explicitly. Do not retarget the existing `G14` poller, DEV/PROD Argo Applications, DEV/PROD runtime paths, or existing namespace resources to bootstrap `v0.2`. + ## Node-Local VPN Proxy G14 has a node-local VPN/proxy stack for infrastructure bootstrap and recovery downloads: diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index a4f30e2d..b945a318 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -6,6 +6,7 @@ - UniDesk 指挥侧 workspace：`/root/unidesk`，固定使用 `master`，开始前执行 `git status` 和 `git pull --ff-only origin master`。 - HWLAB 当前主阵地：`G14:HWLAB`，唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。新开发、文档、render、polling、CI/CD、GitOps、DEV/PROD runtime 和验收默认都以这个 workspace 和 G14 k3s 为准。 +- HWLAB `v0.2` 是 G14 上的加法扩容线，固定分支为 `v0.2`，固定 workspace 为 `G14:/root/hwlab-v02`，固定 namespace 为 `hwlab-v02`，公网入口规划为 `http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`。创建和集成 `v0.2` 时不得删除、重命名或改义现有 `G14`/`G14-gitops` 分支、`hwlab-dev`/`hwlab-prod` namespace 或 17666/17667、18666/18667 入口；细则见 `docs/reference/g14.md`。 - HWLAB 项目内长期规则入口：`/root/hwlab/AGENTS.md`。开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取该文件；不能只凭主 server 的压缩上下文继续操作。 - 每次开始 G14 工作前必须通过 UniDesk SSH 桥执行 `cd /root/hwlab && git status --short --branch && git remote -v`，期望分支是 `G14...origin/G14`；若不满足，先修正 workspace，不能继续开发、render、polling 或部署。 - G14 k3s 操作必须使用 route 语法 `G14:k3s`，例如 `tran G14:k3s kubectl get pods -n hwlab-dev`；禁止写成 `ssh G14 k3s ...`。第一个 route token 必须定位分布式目标，后续 token 才是 operation。 @@ -28,6 +29,7 @@ - 当前 G14 DEV 前端入口固定为 `http://74.48.78.17:17666/`。 - 当前 G14 DEV API/live 入口固定为 `http://74.48.78.17:17667/health/live`。 +- 规划中的 G14 `v0.2` 前端/API 入口固定为 `http://74.48.78.17:19666/` 和 `http://74.48.78.17:19667/health/live`，只能指向 `hwlab-v02` namespace，不得复用或覆盖 DEV/PROD 入口。 - D601 legacy DEV 前端/API 入口曾使用 `http://74.48.78.17:16666/` 和 `http://74.48.78.17:16667/health/live`；只在显式 D601 legacy 排障或迁移对照时使用，不能作为当前 HWLAB DEV 运行面证据。 - 旧公网 `:6666` 和 `:6667` 不是浏览器验收入口；内部 k3s service 仍可使用 `6667` 作为服务端口。 - 当前 G14 入口由 G14 侧公开代理承担；不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 的 FRP 说明只用于历史对照。