docs(dev): prefer NC01 for general builds

docs/reference/cli.md

@@ -430,7 +430,21 @@ HWLAB Cloud Web Workbench 或 Code Agent 装配类 issue 的 CLI 验证必须贴
 
 `trans D518` 应表现为登录 D518 WSL 的 shell；`trans D518 hostname` 应像 `ssh D518 hostname` 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，`-p`、`-i`、`-l`、`-o` 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。指挥官、CI 预检和其他非交互流程不要依赖 ssh-like 自由拼接；单进程标准写法是 `trans D601 argv true`，多行 shell 逻辑标准写法是 quoted heredoc 单步调用 `trans D601 sh <<'SH'`。
 
-UniDesk CLI/trans/tran 客户端改进本身是 master server 高频控制入口维护，可以直接在 `/root/unidesk` 轻量开发、提交并推送 `origin/master`；不要为这类客户端小改强制迁移到 D601 worktree。该例外不改变 master server 禁重型验证规则：仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译、Code Queue runner 实测仍必须在 D601、CI runner 或目标运行面执行，backend-core 主 server 上线受控编译例外按 `docs/reference/dev-environment.md` 单独处理。若 `trans`/`tran`/SSH 文件传输遇到 provider-gateway 单次 stdin、argv 或 stdout 限制，先在 CLI 客户端做分块、SHA-256 校验、失败可观测输出和最小真实闭环；只有 client 侧不能解决且有证据时，才改 provider-gateway。文件传输默认按 1MiB raw chunk 读写，避免 100MiB 大文件被 45KiB 小块和 base64 全量暂存拖慢；`upload`/`download` 成功 JSON 中的 `verified=true`、`verification.automatic=true`、`verification.verified=true` 和 `verification.match.{bytes,sha256}=true` 就是端到端完整性证明，调用方不需要再额外手写 `sha256sum` 比对。
+- UniDesk CLI/trans/tran 客户端改进属于 Master server 高频控制入口维护：
+  - 可以直接在 `/root/unidesk` 轻量开发、提交并推送 `origin/master`；
+  - 不为这类客户端小改强制迁移到 D601 worktree。
+- 该例外不改变 Master server 禁止重型验证的规则：
+  - 仓库级 check 和 Playwright/browser smoke 默认在 NC01、CI runner 或目标运行面执行；
+  - 镜像构建、Rust/Go 编译和 Code Queue runner 实测遵循同一执行面边界；
+  - 只有 owning pipeline 或目标运行面固定属于 D601 时才使用 D601；
+  - backend-core 主服务上线的受控编译例外按 `docs/reference/dev-environment.md` 单独处理。
+- `trans`/`tran`/SSH 文件传输出现 provider-gateway 单次 stdin、argv 或 stdout 限制时：
+  - 先在 CLI 客户端实现分块、SHA-256 校验、失败可观测输出和最小真实闭环；
+  - 只有客户端无法解决且已有证据时，才修改 provider-gateway；
+  - 文件传输默认按 1 MiB raw chunk 读写；
+  - 避免 100 MiB 文件被 45 KiB 小块和 base64 全量暂存拖慢；
+  - `upload`/`download` 成功 JSON 的自动验证字段是端到端完整性证明；
+  - 调用方不需要额外手写 `sha256sum` 比对。
 
 `scripts/src/ssh.ts` 只承担 route/operation parser、共享远端命令构造、broker 调用和顶层 dispatch。新增或扩展高频 operation 不得继续把完整实现堆进 `ssh.ts`；应按能力拆到专门模块，例如整文件传输放在 `scripts/src/ssh-file-transfer.ts`，再由 `ssh.ts` 和 frontend remote transport 传入共享 command builder/bridge executor。后续新增 operation 也按 `scripts/src/ssh-<capability>.ts` 或等价专门模块组织，帮助文本、端到端 CLI 交互验证和 reference 与代码同一变更集更新。
 

docs/reference/dev-environment.md

@@ -1,18 +1,48 @@
-# D601 Dev Environment
+# 开发与构建执行环境
 
-This document is the authoritative source for the persistent `unidesk-dev` environment, the public dev frontend port, `deploy apply --env dev`, and the Rust backend-core build boundary. Release-line and dev-lane governance is owned by `docs/reference/release-governance.md` and [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6). If the same dev-environment rule would need edits in `AGENTS.md`, `docs/reference/cli.md`, `docs/reference/deploy.md`, `docs/reference/ci.md`, `docs/reference/deployment.md`, `docs/reference/e2e.md` or `TEST.md`, keep the detailed rule here and leave only a short cross-reference elsewhere.
+本文档是以下事项的权威出处：
 
-## Goal
+- NC01、D601 与 Master server 的构建执行面边界；
+- 持久化 `unidesk-dev` 环境；
+- 公开开发前端端口；
+- `deploy apply --env dev`；
+- Rust backend-core 构建边界。
 
-The dev environment lets users experience the next UniDesk version without interrupting production:
+发布线和开发 lane 治理由 `docs/reference/release-governance.md` 与
+[GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6) 负责。
+同一规则需要出现在其他入口时，详细规则保留在本文档，其他文档只留简短交叉引用。
 
-- Production stays on the normal public frontend at `http://74.48.78.17:18081/`.
-- Dev is exposed through a separate main-server public port at `http://74.48.78.17:18083/`.
-- Dev backend/frontend workloads run in D601 native k3s namespace `unidesk-dev`, not in the main-server Compose stack.
-- Dev backend-core and frontend rollout use pushed Git commits from `origin/master:deploy.json#environments.dev`, not dirty local worktrees.
-- Rust backend-core check/build defaults to D601 CI through `ci publish-backend-core`; dev CD consumes the published image and must not compile Rust. The only master-server build exception is a reviewed backend-core main-server online operation with explicit concurrency limiting.
+## 目标
 
-## D601 UniDesk Workspace
+开发环境用于在不干扰生产环境的前提下体验下一版本 UniDesk：
+
+- 生产环境继续使用 `http://74.48.78.17:18081/` 的正常公开前端。
+- 开发环境通过独立的 Master server 端口 `http://74.48.78.17:18083/` 暴露。
+- 开发后端和前端工作负载：
+  - 运行在 D601 原生 k3s 的 `unidesk-dev` namespace；
+  - 不运行在 Master server Compose stack。
+- 开发 backend-core 和前端 rollout：
+  - 使用 `origin/master:deploy.json#environments.dev` 中已推送的 Git commit；
+  - 不使用脏 worktree。
+- Rust backend-core 检查和构建：
+  - 仍通过 `ci publish-backend-core` 使用其拥有的 D601 CI；
+  - 开发 CD 只消费已发布镜像，不编译 Rust。
+- Master server 唯一的构建例外是经过审查并显式限制并发的 backend-core 主服务上线操作。
+
+## 通用构建执行面
+
+- Master server 只负责轻量源码编辑、Git 操作、状态观察和受控调度。
+- 通用 Docker 镜像、仓库级检查、浏览器验证及 Rust/Go/前端重型构建默认使用 NC01。
+- D601 不再是通用构建首选，只在以下事实明确成立时使用：
+  - owning CI 或 Tekton 流水线固定运行在 D601；
+  - 目标产物必须进入 D601 node-local registry 或原生 k3s；
+  - 任务需要 D601 自有硬件、workspace 或运行面；
+  - 用户明确指定 D601。
+- D601 离线不得阻塞与 D601 无关的通用镜像构建；此类任务直接切到 NC01。
+- NC01 上的临时构建目录和容器只用于验证，不成为源码或部署真相。
+- 构建产物必须回到项目声明的镜像标签、registry、Git 或可审计交付路径。
+
+## D601 UniDesk 工作区
 
 `D601:UniDesk` 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/unidesk-dev`，固定使用 `master` 分支和 `origin git@github.com:pikasTech/unidesk.git`。所有需要在 D601 上改 UniDesk 代码、做轻量语法/命令形态验证、验证 `trans`/`tran`/Code Queue runner、收敛分布式敏捷实验补丁的工作，都应先进入这个目录。
 
@@ -27,7 +57,15 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v
 
 固定 workspace 只作为 source truth 预检、fetch、受控 worktree 创建和最终同步入口。实际开发、文档修改、测试补丁和 PR 准备应在固定 repo 下的独立 worktree 中完成，例如 `/home/ubuntu/workspace/unidesk-dev/.worktree/<task>`；该 worktree 必须通过 `bun scripts/cli.ts dev-env worktree add .worktree/<task> --branch <branch> --from origin/master` 从最新 `origin/master` 创建，让 `.worktreecopy` 中声明的本地配置白名单自动复制到新 worktree。使用任务专属分支或 detached worktree 隔离当前改动，结束前用 `git status` 确认只包含本任务文件。不要把 `/home/ubuntu/workspace/unidesk-dev` 根目录当作并行任务 scratch 区，也不要复用其他任务遗留 worktree。
 
-Master server 不作为 UniDesk 重型验证机。仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译和 Code Queue runner 实测必须放到 D601、CI runner 或其他获批执行面；master server 只做轻量源码编辑、Git 操作、状态观察和受控调度。唯一例外是 backend-core 主 server 上线：当用户或 issue 明确要求把当前 backend-core 修复上线到主 server 时，可以用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价限流执行 backend-core 专属编译，并必须用异步 job/status/health 证据回写 issue。
+- Master server 不作为 UniDesk 重型验证机：
+  - 默认执行面是 NC01、CI runner 或目标运行面；
+  - 重型验证包括仓库级 check 和 Playwright/browser smoke；
+  - 重型构建包括镜像构建和 Rust/Go 编译；
+  - Code Queue runner 实测也遵循同一执行面边界；
+  - 只有 owning pipeline 或目标运行面固定属于 D601 时才使用 D601；
+  - 唯一例外是用户或 issue 明确要求的 backend-core 主服务上线；
+  - 该例外使用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价方式限制并发；
+  - 结果必须用异步 job/status/health 证据回写 issue。
 
 `scripts/cli.ts`、`scripts/trans`、`scripts/tran`、`scripts/src/ssh.ts` 和相邻的 `trans`/`tran`/SSH helper 是主 server 上人工与 Codex 高频使用的控制入口；这类客户端工具链改进可以直接在 master server `/root/unidesk` 轻量修改、提交并推送到 `origin/master`。该例外只覆盖 CLI/trans/tran 客户端源码、帮助、语法/命令形态验证和对应 reference 文档，不覆盖 `src/components/provider-gateway` 行为变更、镜像构建、仓库级 check、浏览器 smoke 或其他重型验证。除非用户明确要求，CLI 改动不做单元测试、合同测试或新增测试脚本。涉及 provider-gateway 代码时仍必须遵循 provider-gateway 版本和远程升级规则。
 
@@ -116,7 +154,11 @@ The persistent dev environment follows the shared Git-backed deployment hygiene
 Use this sequence for backend-core Rust and frontend dev work:
 
 1. Preflight the fixed workspace, then create the task-scoped worktree with `bun scripts/cli.ts dev-env worktree add .worktree/<task> --branch <branch> --from origin/master`; keep unrelated parallel changes separated with `git status`/`git diff`.
-2. On the master server, limit validation to diff review and concrete-file lightweight syntax checks such as `bun --check <specific-file>`. Run repository-level checks, type checks, Compose checks, frontend checks and all Rust checks on D601, CI or another approved execution surface.
+2. Master server 只执行 diff 审查和具体文件的轻量语法检查。
+   - 轻量语法检查示例是 `bun --check <specific-file>`。
+   - 仓库级检查和类型检查默认在 NC01、CI 或目标运行面执行。
+   - Compose 检查、前端检查和 Rust 检查遵循同一执行面边界。
+   - 仅 D601 owning pipeline 使用 D601。
 3. Commit the code from the task worktree and merge/push it to `origin/master` through the chosen lightweight PR or direct integration path; `deploy apply --env dev` cannot deploy unpushed local changes.
 4. Update `deploy.json` `environments.dev.services` so `backend-core` and `frontend` point at the pushed commit, then commit and push that manifest update.
 5. Preflight backend-core publication: `bun scripts/cli.ts ci publish-backend-core --commit <full-sha> --dry-run`. The result must have no `blockedScopes`, `wouldBuildOnD601=true`, D601 `unidesk-ci` Tekton runner metadata, D601 registry target `127.0.0.1:5000/unidesk/backend-core`, required labels for service id/source repo/source commit/Dockerfile, and `recommendedAction` pointing to the real publish command.