diff --git a/AGENTS.md b/AGENTS.md index a1b3fb45..0ea57e71 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,20 +10,20 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文 ## 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 修复都必须以该目录为准。 +- 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: 每次开始 `G14:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后,必须重新读取目标 workspace 的 `/root/hwlab/AGENTS.md`,并以该文件和其引用的 HWLAB repo 内规则为当前任务约束;禁止只凭压缩摘要或主 server 记忆继续改代码。 - 操作入口必须通过 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 HWLAB Workspace Rule +## Critical D601 HWLAB Legacy And Hardware Bridge Rule -- P0: `D601:HWLAB` 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/hwlab-dev`,固定使用 `main` 分支和 `origin git@github.com:pikasTech/HWLAB.git`;所有需要在 D601 上改 HWLAB 代码、跑 `node --test`、`web:check`、Playwright/browser smoke 或分布式敏捷实验补丁收敛的工作,都必须优先使用这个目录。 -- P0: 每次开始 `D601:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后,必须重新读取目标 workspace 的 `/home/ubuntu/workspace/hwlab-dev/AGENTS.md`,并以该文件和其引用的 HWLAB repo 内规则为当前任务约束;禁止只凭压缩摘要或主 server 记忆继续改代码。 -- `/home/ubuntu/workspace/hwlab` 是 D601 上的部署/构建/CD 副本,不是日常开发 source workspace;`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*` 一次性目录、`/home/ubuntu/hwlab` runner 历史目录和 master-server checkout 都不能作为 `D601:HWLAB` 开发真相。 -- 每次开始 `D601:HWLAB` 工作前必须通过 UniDesk SSH 桥执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v`;若路径、分支、remote 或权限不符合预期,必须先修正固定 workspace,再继续开发、测试或发布。 -- D601 上 HWLAB 验证必须通过 UniDesk 透传在 D601 执行,禁止回到 master server 跑 HWLAB check、Playwright/browser smoke、镜像构建或其他重型验证。k3s 操作使用 route 语法 `D601:k3s ...`,默认 D601 原生 k3s kubeconfig。 +- P0: `D601:HWLAB` 不再是 HWLAB 默认开发主阵地或运行面真相;`/home/ubuntu/workspace/hwlab-dev` 只作为历史迁移、D601 legacy 回滚、显式指定的 D601 补丁收敛和故障对照 workspace 使用。 +- P0: 新的 HWLAB 代码、文档、render、polling、CI/CD、GitOps、DEV/PROD runtime 和验收默认必须走 `G14:HWLAB`;只有用户明确指定 D601 legacy 或 D601 Windows 硬件桥接时,才进入 D601 HWLAB 路径。 +- D601 仍是 ConStart/71-FREQ 等 Windows 硬件与 Keil/串口资源的 bridge host;最小 device-agent 实验中,D601 Windows `hwlab-gateway` 可以作为外部 gateway 连接到 G14 `hwlab-dev` cloud-api,而不改变 HWLAB source/runtime truth。 +- 每次确需进入 D601 legacy HWLAB workspace 前,仍必须通过 UniDesk SSH 桥执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v`,并重新读取 `/home/ubuntu/workspace/hwlab-dev/AGENTS.md`;发现 D601 口径与 G14 `/root/hwlab/AGENTS.md` 冲突时,以 G14 当前规则为准。 +- `/home/ubuntu/workspace/hwlab`、`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*` 一次性目录、`/home/ubuntu/hwlab` runner 历史目录和 master-server checkout 都不能作为 HWLAB 当前开发真相。 - 长期细节见 `docs/reference/hwlab.md`。 ## Critical D601 UniDesk Workspace Rule @@ -38,7 +38,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文 ## 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)。 -- D601 上裸 `kubectl` 不可信:`/home/ubuntu/.kube/config` 可能仍残留 `docker-desktop` / `127.0.0.1:11700`。所有 D601 k3s 读写、Tekton、Code Queue、HWLAB/UniDesk DEV 部署与排障必须显式使用 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml`,并在写操作前确认节点名是 `d601`。 +- D601 上裸 `kubectl` 不可信:`/home/ubuntu/.kube/config` 可能仍残留 `docker-desktop` / `127.0.0.1:11700`。所有 D601 k3s 读写、Tekton、Code Queue、UniDesk DEV 和显式 D601 legacy HWLAB 排障必须显式使用 `KUBECONFIG=/etc/rancher/k3s/k3s.yaml`,并在写操作前确认节点名是 `d601`。 - 写操作的实际目标 context/server/nodes 出现 `desktop-control-plane`、`docker-desktop` 或 `127.0.0.1:11700`,发现 Docker Desktop Kubernetes namespace、旧 direct Docker `code-queue-backend`,或同一服务被 Docker Desktop k8s 与原生 k3s 同时承载时,必须立即停止部署动作并按 #138 处理;裸 `kubectl` 默认 context 只作为诊断,不能把第二控制面的状态当作恢复证据。 ## Critical GitHub Issue Write Rule @@ -58,8 +58,8 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文 ## Critical Master Server Build Ban - Master server 是生产入口和控制面,不得当作构建机使用;严厉禁止在 master server 上执行 Docker 镜像构建、`docker build`、`docker buildx build`、`docker compose build`、`docker compose up --build`、Rust 编译/测试(`cargo build`、`cargo test`、`rustc`)、Go 编译/测试(`go build`、`go test`)以及其他高 CPU/高内存编译构建任务。这类任务可能拖垮生产服务器,造成 UniDesk 整体不可用。 -- Master server 资源也不足以承载仓库级 `check`/`test`/smoke 验证;禁止在 master server 上运行 `bun scripts/cli.ts check`、`node --test`、`node web/hwlab-cloud-web/scripts/check.mjs`、Playwright/browser smoke 或其他会遍历大仓库、启动浏览器、长时间占用 CPU/内存的校验命令。正式验证必须改在 D601 原生 k3s 侧 worktree、CI runner 或其他获批外部执行面完成。 -- 镜像和编译产物必须通过标准 CI/CD 在外部构建资源上生成,通常是 D601 原生 k3s/Tekton 或经过批准的外部 builder;源码以 Git remote 为 source of truth,CI 产出 commit-pinned image/artifact。 +- Master server 资源也不足以承载仓库级 `check`/`test`/smoke 验证;禁止在 master server 上运行 `bun scripts/cli.ts check`、`node --test`、`node web/hwlab-cloud-web/scripts/check.mjs`、Playwright/browser smoke 或其他会遍历大仓库、启动浏览器、长时间占用 CPU/内存的校验命令。HWLAB 正式验证必须改在 G14 `/root/hwlab`、G14 k3s/Tekton 或其他获批外部执行面完成;非 HWLAB 的 D601 服务仍按各自 reference 使用 D601 原生 k3s/CI runner。 +- 镜像和编译产物必须通过标准 CI/CD 在外部构建资源上生成;HWLAB 默认使用 G14 k3s/Tekton/GitOps 或经过批准的外部 builder,非 HWLAB 服务按各自 reference 使用 D601 原生 k3s/Tekton 或其他获批外部 builder;源码以 Git remote 为 source of truth,CI 产出 commit-pinned image/artifact。 - Prod 发布必须走 CD pull-only 流程:由 `deploy.json` 声明期望服务版本,生产侧 CD 拉取已经构建好的镜像或 artifact 并按 `deploy.json` 部署;禁止把 master server 本地 Docker image、临时容器层或本地编译产物作为部署真相。 - 在 master server 上只允许轻量源码编辑、Git 操作、状态/健康/日志/诊断、JSON CLI 控制面操作和受控 CD 观察;一旦步骤需要构建镜像或编译 Rust/Go 等重型产物,必须停止在 master server 执行并改走 CI/CD 或 D601 构建路径。 @@ -100,7 +100,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台;本文 - `bun scripts/cli.ts auth-broker contract|health --dry-run|credential-request --dry-run|pr-preflight --dry-run`:查看 Auth Broker P0 Rust skeleton 与 CLI adapter contract,runner 无 `GH_TOKEN`/`GITHUB_TOKEN` 时返回结构化 `auth-missing`/`broker-needed`,不读取或打印 token 值,规则见 `docs/reference/auth-broker.md`。 - `bun scripts/cli.ts gh preflight|auth status|issue ...|pr list|files|diff --stat|read|view|preflight|closeout|create|edit|update|comment` / `bun scripts/code-queue-pr-preflight-example.ts`:通过 REST 执行安全 GitHub issue 读写、脱敏 auth/status 诊断、body-file Markdown 写入、当日滚动简报时间线 ClaudeQQ 通知、escape 扫描、只读 cleanup-plan 和 #20 board-audit、PR changed-file/stat summary、PR 创建/评论 dry-run、REST-only 低噪声 PR title/body 编辑、PR 收口元数据观察(含 merged/closed 区分与 merge commit)、低噪声 PR 收口 preflight 与 runner PR preflight;`gh issue/pr read|view` 支持 `owner/repo#number` shorthand,`--raw|--full` 是显式完整披露别名,`gh pr diff` 仅支持 `--stat` 紧凑 JSON,`gh pr merge` 当前仍结构化拒绝但普通 PR 可按任务边界用 repo-owned GitHub 路径收口,规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 - `bun scripts/cli.ts commander contract|plan --dry-run|smoke --dry-run|approval request --dry-run|prompt-lint --kind gpt55-pr`:查看 host Codex 指挥官直管微服务 skeleton 的 source/contract、无 daemon smoke 验证计划、.state/commander/ 状态模型、trace summary 聚合、ClaudeQQ 高风险请示草案和 GPT-5.5 PR prompt 边界辅助 lint;当前只返回 dry-run 计划和 backend-core `microservice proxy claudeqq` 授权后候选命令,不接 live bridge、不接管人工指挥官,不发送消息,`prompt-lint` 不作为业务 PR 门禁也不改变 `codex submit` 默认行为,规则见 `docs/reference/host-codex-commander.md`。 -- `bun scripts/cli.ts hwlab cd audit --env dev` / `status|preflight|apply --dry-run`:HWLAB DEV CD 指挥侧 wrapper,通过 D601 provider SSH 调用 HWLAB repo-owned `scripts/dev-cd-apply.mjs` 并强制原生 k3s kubeconfig;`audit` 在 CD 恢复后只读分类 control-plane、SecretRef、registry、Lease、artifact/workload、16666/16667 和 DB/runtime durability 阻塞,真实 apply 只暴露 host-commander-only 命令形状,规则见 `docs/reference/hwlab.md`。 +- `bun scripts/cli.ts hwlab cd audit --env dev` / `status|preflight|apply --dry-run`:旧 D601 HWLAB DEV CD 指挥侧 wrapper,仅用于显式 legacy 诊断和迁移对照;当前 HWLAB DEV/PROD source/runtime truth 已迁到 G14 `/root/hwlab` 与 G14 k3s/GitOps,规则见 `docs/reference/hwlab.md`。 - `bun scripts/cli.ts ci install/status/run/publish-backend-core/publish-user-service/run-dev-e2e/logs`:在 D601 原生 k3s 上安装和运行 Tekton CI,支持每 commit 检查、Code Queue 只读性能门禁、`CI.json` catalog 驱动的 backend-core 与 user-service commit-pinned 镜像发布和手动触发的 `origin/master:deploy.json#environments.dev` 临时 namespace e2e;catalog/producer/consumer 分工见 `docs/reference/cicd-standardization.md`,`run-dev-e2e` 的 Git 控制 runner、短 launcher 和 no-CD 边界见 `docs/reference/dev-ci-runner.md`,Tekton 规则见 `docs/reference/ci.md`。 - `bun scripts/cli.ts codex deploy `:旧 Code Queue 兼容部署入口已禁用,原因是它会绕过受控部署边界直连 D601 部署 Code Queue;规则见 `docs/reference/codex-deploy.md`。 - `bun scripts/cli.ts codex prompt-lint [prompt|--prompt-file path|--prompt-stdin]` / `codex submit [prompt] [--prompt-file path|--prompt-stdin] [--queue ]` / `codex execution-plane [--full|--raw]` / `codex pr-preflight [--remote]`:`prompt-lint` 在派发/steer 前 dry-run 检查 runner prompt 的 DEV 测试授权分级(`read-only`/`live-read`/`live-mutating`)且不回显 prompt;`submit --dry-run` 同时给出 MiniMax/GPT/人工路由建议、该 lint 结果和 requested/effective execution mode;真实提交成功只返回写入确认、task id、服务级 runnerPermissions 和后续查看命令,不回显 prompt;`execution-plane` 只读比较 D601 原生 k3s 正式 Code Queue 执行面、旧 Compose 残留、commit/digest/worktree/probe drift;`pr-preflight` 只读检查 D601 scheduler/runner 的 GitHub token、egress 和 PR 能力,PR 型派单前必须使用,规则见 `docs/reference/cli.md` 和 `docs/reference/code-queue-supervision.md`。 @@ -134,8 +134,8 @@ 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 入口、DEV CD wrapper 和受控发布边界。 -- `docs/reference/g14.md`:G14 provider 节点、k3s 控制桥、HWLAB DEV 旁路 staging、Code Queue/CI 候选目标和节点本地 VPN proxy bootstrap 边界。 +- `docs/reference/hwlab.md`:HWLAB 指挥侧固定 workspace、G14 主运行面、D601 legacy/硬件桥接边界、最小 device-agent/gateway 桥接模型和受控发布边界。 +- `docs/reference/g14.md`:G14 provider 节点、k3s 控制桥、当前 HWLAB DEV/PROD source/runtime truth、device-agent 手动实验边界、Code Queue/CI 候选目标和节点本地 VPN proxy bootstrap 边界。 - `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 的长期规则。 diff --git a/docs/reference/g14.md b/docs/reference/g14.md index 597557a2..08cc9946 100644 --- a/docs/reference/g14.md +++ b/docs/reference/g14.md @@ -1,40 +1,36 @@ # G14 Provider Node -G14 is a UniDesk provider node for staging infrastructure workloads. Its UniDesk provider id is `G14`; the local UniDesk worktree is `/root/unidesk`, and the native k3s kubeconfig is `/etc/rancher/k3s/k3s.yaml`. +G14 is the current HWLAB DEV/PROD source and k3s/GitOps runtime truth, and it remains a UniDesk provider node for staging other infrastructure workloads. Its UniDesk provider id is `G14`; the local UniDesk worktree is `/root/unidesk`, and the native k3s kubeconfig is `/etc/rancher/k3s/k3s.yaml`. G14's long-lived k3s control bridge is `k3sctl-adapter-g14`, a UniDesk direct service outside the k3s fault domain. It listens on the G14 host loopback port `127.0.0.1:4266` and is registered separately from the D601 `k3sctl-adapter`, so G14 infrastructure services can be built and tested without taking over user services that still run on D601. -For Code Queue and CI/CD migration preparation, G14 uses native k3s labels `unidesk.ai/node-id=G14` and `unidesk.ai/provider-id=G14`. The G14 Code Queue manifests `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k8s.yaml` and `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k3s.json` are candidate staging artifacts only until an explicit production cutover is approved. Production Code Queue, CI/CD and user-service execution must remain on D601 while D601 is carrying production. +For Code Queue and non-HWLAB CI/CD migration preparation, G14 uses native k3s labels `unidesk.ai/node-id=G14` and `unidesk.ai/provider-id=G14`. The G14 Code Queue manifests `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k8s.yaml` and `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k3s.json` are candidate staging artifacts only until an explicit production cutover is approved. Non-HWLAB production Code Queue, CI/CD and user-service execution must remain on D601 while D601 is carrying those services. -## HWLAB DEV Staging +## HWLAB DEV/PROD Runtime -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`. +G14 hosts the current HWLAB DEV runtime in native k3s namespace `hwlab-dev`, and the same node/GitOps line is the HWLAB PROD target unless a newer HWLAB repo rule says otherwise. The canonical G14 HWLAB source workspace is `/root/hwlab` on branch `G14`, with `origin` set to `git@github.com:pikasTech/HWLAB.git`; HWLAB source edits, CI/CD/GitOps script changes, render work, manual polling and runtime validation must be done from that workspace through UniDesk SSH passthrough. Do not use `/root/HWLAB`, `/home/ubuntu/hwlab`, `/workspace/hwlab`, D601 workspace or a master-server checkout as persistent HWLAB 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 +tran G14:/root/hwlab script -- git status --short --branch +tran G14 apply-patch < patch.diff +tran G14:k3s kubectl get pods -n hwlab-dev ``` `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: +The G14 HWLAB runtime boundary is: -- Do not switch public traffic, DNS, FRP, UniDesk microservice routing or Code Queue/CI/CD control from D601 to G14 during staging. -- Keep `hwlab-tunnel-client` scaled to `0` replicas unless a separate cutover approval explicitly enables a public tunnel. -- Keep G14 HWLAB Services as `ClusterIP`; use `kubectl port-forward --address 127.0.0.1` or in-cluster probes for smoke tests. +- Current DEV public endpoints are `http://74.48.78.17:17666/` and `http://74.48.78.17:17667/health/live`. D601 `16666/16667` is legacy/migration evidence only. +- Keep HWLAB Services as `ClusterIP` unless a repo-owned G14 GitOps rule explicitly exposes them. Public exposure should stay in the approved G14 edge/proxy path, not ad hoc NodePort or local port-forward. - Use a G14-local PostgreSQL instance such as `hwlab-g14-postgres` and a G14-local `hwlab-cloud-api-dev-db` Secret for cloud-api durable runtime tests. Do not copy D601 database credentials. -- 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. +- Use only G14-local Codex auth material and k8s Secrets authorized for HWLAB on G14; do not copy D601 or production auth material by hand. - 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. +- `HWLAB_PUBLIC_ENDPOINT` and health/live evidence must describe the G14 endpoint, not the old 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. +- Manual device-agent experiments for real hardware must be standalone resources in `hwlab-dev` such as `device-agent-71-freq` and must not patch existing HWLAB Deployments, Services, ArgoCD Applications, FRP, CD desired-state or public frontend routing unless a separate HWLAB change authorizes it. +- A D601 Windows `hwlab-gateway` may connect outbound to G14 DEV cloud-api as an external host bridge for Keil/serial/workspace access. That bridge does not make D601 the HWLAB runtime truth; it is only a hardware access provider behind the G14 device-agent/cloud-api path. After the G14-local database is provisioned, run the HWLAB migration CLI only against the G14 DEV database with explicit non-production confirmations: @@ -44,7 +40,7 @@ kubectl -n hwlab-dev exec deploy/hwlab-cloud-api -- \ --apply --confirm-dev --confirmed-non-production ``` -Healthy G14 HWLAB staging means the main Deployments and StatefulSets are Ready, `cloud-api` and `edge-proxy` return `/health/live` with `status=ok`, and `hwlab-tunnel-client` still has `replicas=0` and no Pods. `hwlab-agent-mgr` can report `degraded` while no skills manifest commit/version is wired; treat that as an agent-runtime metadata gap, not as a traffic switch signal. +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. ## Node-Local VPN Proxy diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 3f047726..e857a20b 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -5,16 +5,13 @@ ## 固定入口 - 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` 固定开发 workspace:通过 `bun scripts/cli.ts ssh D601 script` 进入 `/home/ubuntu/workspace/hwlab-dev`,固定使用 `main` 分支和 `origin git@github.com:pikasTech/HWLAB.git`。所有 D601 侧 HWLAB 代码修改、`node --test`、`web:check`、Playwright/browser smoke、分布式敏捷实验补丁收敛和 PR 前验证都优先在这个目录执行。开始前必须执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v`,确认分支是 `main...origin/main` 且 remote 正确。 -- 开始 `D601:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后,必须重新读取 `/home/ubuntu/workspace/hwlab-dev/AGENTS.md`;该文件和 HWLAB repo 内 `docs/reference/` 是代码修改、测试和 PR 的当前约束来源。 -- D601 HWLAB 部署/构建/CD 副本:`/home/ubuntu/workspace/hwlab` 只作为部署、构建、CI/CD 或发布读数副本使用,开始前也要 `git -C /home/ubuntu/workspace/hwlab pull --ff-only origin main`;不要把它和 `/home/ubuntu/workspace/hwlab-dev` 的开发职责混用。 -- D601 临时目录边界:禁止把 `/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*` 一次性目录、master-server checkout 或其他 runner clone 当作 `D601:HWLAB` source truth。确需一次性 repo 的 CD wrapper 会自行创建并清理;人工开发和测试必须回到 `/home/ubuntu/workspace/hwlab-dev`。 -- 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:HWLAB` 分布式开发、切换任务、恢复中断或上下文压缩后,必须重新读取 `/root/hwlab/AGENTS.md`;不能只凭主 server 的压缩上下文继续操作 G14 source workspace。 -- 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。 +- 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 项目内长期规则入口:`/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。 +- `D601:HWLAB` 已降级为 legacy/migration 对照和 D601 Windows 硬件 bridge 入口,不再是默认开发主阵地或运行面真相。只有用户明确指定 D601 legacy、D601 回滚对照或 D601 Windows/Keil/串口硬件桥接时,才使用 `/home/ubuntu/workspace/hwlab-dev`;进入前仍要执行 `cd /home/ubuntu/workspace/hwlab-dev && git status --short --branch && git remote -v` 并读取该目录的 `AGENTS.md`。 +- D601 上 `/home/ubuntu/workspace/hwlab`、`/home/ubuntu/hwlab`、`/tmp/hwlab-*`、`/home/ubuntu/workspace/hwlab-*`、master-server checkout 或其他 runner clone 都不能作为当前 HWLAB source truth。发现 D601 口径与 G14 `/root/hwlab/AGENTS.md` 冲突时,以 G14 当前规则为准。 +- `/root/HWLAB`、`/workspace/hwlab`、D601 workspace、master-server checkout 或临时 clone 都不能作为 `G14:HWLAB` source truth。 ## 关键 GitHub 入口 @@ -29,31 +26,54 @@ ## DEV 入口 -- DEV 前端入口固定为 `http://74.48.78.17:16666/`。 -- DEV API/live 入口固定为 `http://74.48.78.17:16667/health/live`。 +- 当前 G14 DEV 前端入口固定为 `http://74.48.78.17:17666/`。 +- 当前 G14 DEV API/live 入口固定为 `http://74.48.78.17:17667/health/live`。 +- 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` 作为服务端口。 -- `16666` 由 master 侧 `hwlab-frps-dev` 接收 D601 `hwlab-frpc` 的反向代理流量;不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。 +- 当前 G14 入口由 G14 侧公开代理承担;不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 的 FRP 说明只用于历史对照。 + +## 最小 Device Agent/Gateway 桥接模型 + +最小打通目标是只新增桥接面,不改动既有 HWLAB 应用、GitOps、FRP、CD 或前端路径: + +- 在 `G14:k3s` 的 `hwlab-dev` namespace 手动建立一个 standalone `device-agent-71-freq` Pod/Deployment 和 ClusterIP Service。它暴露设备语义入口,例如 `/health`、`/skills`、`/workspace/*`、`/run`,并把真实硬件调用转成 HWLAB cloud-api 的 gateway operation,而不是在 Pod 内直接访问 Windows 硬件。 +- 在 `D601:win` 上启动 `hwlab-gateway`,作为 71-FREQ/ConStart/Keil/串口资源的外部 host bridge。gateway 通过公网或受控网络出站连接当前 G14 DEV cloud-api:`http://74.48.78.17:17667`,注册稳定的 `gatewaySessionId`、`resourceId` 和 `capabilityId`。 +- D601 Windows gateway 的最小配置必须来自 profile 或环境变量,核心字段是 `HWLAB_GATEWAY_CLOUD_URL=http://74.48.78.17:17667`、`HWLAB_GATEWAY_ID`、`HWLAB_GATEWAY_SESSION_ID`、`HWLAB_GATEWAY_RESOURCE_ID`、`HWLAB_GATEWAY_CMD_CAPABILITY_ID`、`HWLAB_GATEWAY_CMD_EXEC_ENABLED=1`、`HWLAB_GATEWAY_DEMO_OPEN=1`、`HWLAB_GATEWAY_MAX_INFLIGHT` 和 `HWLAB_GATEWAY_CMD_TIMEOUT_MS`。这些值用于声明能力和执行边界,不得散落在 device-agent 代码里。 +- device-agent 访问 G14 集群内 cloud-api 时优先使用 `http://hwlab-cloud-api.hwlab-dev.svc.cluster.local:6667`。Node/undici `fetch` 会按 Fetch bad-port 规则拒绝 `6667`,因此 Node 实现必须使用 `node:http`/`node:https`、已有 repo-owned HTTP helper,或改用不触发 bad-port 的受控代理端口。 +- 71-FREQ 的 device profile 必须配置化保存,至少包含工程根目录、Keil project/target、默认串口波特率、gateway/resource/capability 选择器和 workspace 根。不得把 `F:\Work\ConStart`、工程名、串口号或 probe UID 硬编码进 device-agent 镜像。 +- 最小验收顺序是:G14 `hwlab-dev` cloud-api `/health/live` ready;D601 Windows 能访问 `http://74.48.78.17:17667/health/live`;D601 `hwlab-gateway` 注册后 cloud-api 能看到 gateway session/resource/capability;G14 `device-agent-71-freq` `/health` 和 `/skills` 返回 ready;通过 device-agent 发起一条只读或 `echo` 级 gateway shell operation,并返回 operation/evidence/trace 摘要。 +- 这个模型只证明 `device-agent Pod -> G14 cloud-api -> D601 hwlab-gateway -> Windows host` 的控制链路。Keil 编译下载、串口日志抓取和 workspace CRUD 可以作为后续 device-agent skill 子命令逐步接入;未接入前不能把 device-agent 标成完整 71-FREQ 硬件代理。 ## Master Server 校验边界 - master server 是 UniDesk/HWLAB 的生产入口且资源紧张;它只能承担轻量源码编辑、Git 操作、日志/健康观察、JSON CLI 指挥和受控 CD 审阅,不能承担正式校验执行面。 - 禁止在 master server 上运行 HWLAB 或 UniDesk 的仓库级 `check`/`test`/smoke 命令,包括但不限于 `bun scripts/cli.ts check`、`node --test`、`node web/hwlab-cloud-web/scripts/check.mjs`、`node scripts/dev-cloud-workbench-smoke.mjs`、Playwright/browser layout smoke,以及其他会长时间占用 CPU/内存、启动浏览器或遍历大仓库的校验流程。 -- 需要正式验证时,固定切到 D601 原生 k3s 侧 worktree、HWLAB repo-owned CI 或其他获批外部执行面;master server 只负责发起、观察和记录,不负责实际跑 check。 -- 如果为了排障必须从 master server 生成命令或查看源码,后续验证命令也必须显式改到 D601 路径执行,例如 `/home/ubuntu/workspace/hwlab` 或临时 hotfix worktree,而不是直接在 `/root/unidesk` 或 master server 上本地运行。 +- 需要正式验证时,固定切到 G14 `/root/hwlab`、G14 k3s/Tekton、HWLAB repo-owned CI 或其他获批外部执行面;master server 只负责发起、观察和记录,不负责实际跑 check。 +- 如果为了排障必须从 master server 生成命令或查看源码,后续验证命令也必须显式改到 G14 路径执行,例如 `tran G14:/root/hwlab script -- ...` 或 `tran G14:k3s ...`,而不是直接在 `/root/unidesk` 或 master server 上本地运行。 -## D601 k3s 口径 +## G14 运行面与 D601 Legacy 口径 -HWLAB 的真实 DEV runtime 在 D601 原生 k3s 中,必须显式使用: +HWLAB 当前真实 DEV/PROD runtime 在 G14 原生 k3s 中。只读观察使用: + +```sh +tran G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide +``` + +`hwlab-cloud-api` 和 `hwlab-edge-proxy` 在集群内使用 `6667` Service 端口,对外 DEV API 使用 `17667`。G14 local details 见 `docs/reference/g14.md` 和 G14 节点 `/root/docs/hwlab-g14-workspace.md`。 + +D601 原生 k3s 口径只用于 legacy 对照、迁移排障或明确指定的 D601 回滚任务。此时必须显式使用: ```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`。 +D601 上不要直接相信默认 `kubectl` context。默认 context 可能是 `docker-desktop`,它会展示另一套与公网 legacy `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`。 +历史 D601 `frpc` 配置不是 D601 host `/etc/frp/frpc.toml`,而是 D601 legacy `hwlab-dev` namespace 里的 `hwlab-frpc-config` ConfigMap 和 `hwlab-frpc` Deployment。master 侧 legacy `frps` 配置由 `hwlab-frps-dev` 容器挂载 `/opt/hwlab-frp/frps.dev.toml`。 -## UniDesk HWLAB DEV CD Wrapper +## D601 Legacy HWLAB DEV CD Wrapper + +以下 UniDesk wrapper 是旧 D601 DEV CD 指挥入口,只用于显式 legacy 诊断和迁移对照。当前 G14 DEV/PROD 发布、GitOps 和运行面收敛必须优先按 G14 `/root/hwlab` 与 HWLAB repo-owned 规则执行;不要把下面的 D601 wrapper 当作当前 HWLAB release truth。 UniDesk 指挥侧固定入口: @@ -97,9 +117,9 @@ node scripts/dev-cd-apply.mjs --apply --confirm-dev --confirmed-non-production - - HWLAB runtime truth 必须回写到 HWLAB 仓库自己的 issue、`AGENTS.md`、`docs/reference/`、部署配置或 secret 管理入口;UniDesk 只保留指挥侧边界和交叉引用。 - 热修后必须说明 durable source fix 如何进入 HWLAB 的 CLI、manifest、`deploy/deploy.json` 或等价发布路径;如果尚未完成,要保留 HWLAB issue 追踪。 -## 已验证的 Cloud Web 手动 DEV 发布路径 +## D601 Legacy Cloud Web 手动 DEV 发布路径 -当只需要发布 `hwlab-cloud-web` 到 DEV 时,使用以下路径;它是当前手动 CD 的基准,后续自动化应收敛到 HWLAB `deploy/deploy.json` 和 CLI,而不是重新发明路径。 +以下路径是 D601 legacy DEV 的历史手动发布基准,只用于迁移对照或显式 D601 回滚排障。当前 G14 DEV/PROD 发布必须优先按 G14 `/root/hwlab`、G14 GitOps 和 HWLAB repo-owned 规则执行;不要把这里的 D601 命令当作当前发布入口。 1. 更新 D601 部署副本: