docs: require task worktrees for distributed development

2026-05-26 13:40:09 +00:00
parent c976310463
commit 6a596bc452
2 changed files with 5 additions and 1 deletions
@@ -20,6 +20,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - 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 或部署。
+- G14 HWLAB 开发必须先以 `/root/hwlab` 做固定 repo 预检，再在 `/root/hwlab/.worktree/<task>` 从最新 `origin/G14` 创建独立 worktree 修改和提交；不要把固定 repo 当作并行任务 scratch 区，细则见 `docs/reference/g14.md`。
 - P0: G14 已有节点本地 GitHub/Google/DockerHub/npm 等 bootstrap 加速 proxy；在 G14 host、临时 pod、构建 pod 或透传 pod 里拉 GitHub/Google 资源前必须优先使用该 proxy，避免把网络直连失败当作代码阻塞。主入口：HTTP/HTTPS `http://127.0.0.1:10808`、SOCKS `socks5h://127.0.0.1:10808`，备份入口和 NO_PROXY 规则见 `docs/reference/g14.md`。
 - 禁止把 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`，两处口径必须保持一致。
@@ -39,6 +40,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - P0: 每次开始 `D601:UniDesk` 分布式开发、切换任务、恢复中断或上下文压缩后，必须重新读取目标 workspace 的 `/home/ubuntu/workspace/unidesk-dev/AGENTS.md`，并以该文件和其引用的 UniDesk repo 内规则为当前任务约束；禁止只凭压缩摘要或主 server 记忆继续改代码。
 - `/home/ubuntu/cq-deploy`、`/root/unidesk`、`/app`、Code Queue pod 内 `/root/unidesk` 和 `/tmp/unidesk-*` 都是运行副本、部署副本或一次性实验面，不是 `D601:UniDesk` 日常开发 source truth；运行面热修可以直接作用于 pod/容器，但必须随后把持久化修复落回 fixed workspace 和 Git remote。
 - 每次开始 `D601:UniDesk` 工作前必须通过 UniDesk SSH 桥执行 `cd /home/ubuntu/workspace/unidesk-dev && git status --short --branch && git remote -v`；若路径、分支、remote 或权限不符合预期，必须先修正固定 workspace，再继续开发、测试或发布。
+- D601 UniDesk 开发必须先以 `/home/ubuntu/workspace/unidesk-dev` 做固定 repo 预检，再在 `/home/ubuntu/workspace/unidesk-dev/.worktree/<task>` 从最新 `origin/master` 创建独立 worktree 修改和提交；不要把固定 repo 当作并行任务 scratch 区，细则见 `docs/reference/dev-environment.md`。
 - D601 上 UniDesk 验证必须通过 UniDesk 透传在 D601 执行，禁止回到 master server 跑仓库级 check、Playwright/browser smoke、镜像构建或其他重型验证。Code Queue/tran 运行面验证应优先直达 D601 原生 k3s pod，k3s 操作使用 route 语法 `D601:k3s ...`。
 - 长期细节见 `docs/reference/dev-environment.md`。

@@ -25,6 +25,8 @@ tran D601:/home/ubuntu/workspace/unidesk-dev git remote -v

 若路径、分支或 remote 不符合预期，先修正 fixed workspace，再继续。`/home/ubuntu/cq-deploy`、Code Queue pod 内 `/root/unidesk`/`/app`、D601 上的 `/root/unidesk` 和 `/tmp/unidesk-*` 只作为部署副本、运行副本或临时实验面；运行面热修可以直接作用在 pod/容器，但必须随后把持久化修复提交到 Git remote，并在 fixed workspace 中复验。

+固定 workspace 只作为 source truth 预检、fetch、worktree 管理和最终同步入口。实际开发、文档修改、测试补丁和 PR 准备应在固定 repo 下的独立 worktree 中完成，例如 `/home/ubuntu/workspace/unidesk-dev/.worktree/<task>`；该 worktree 必须从最新 `origin/master` 创建，使用任务专属分支或按当前 master-only 规则完成提交，结束前用 `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 操作、状态观察和受控调度。

 ## Public Dev Frontend Port
@@ -106,7 +108,7 @@ The persistent dev environment follows the shared Git-backed deployment hygiene

 Use this sequence for backend-core Rust and frontend dev work:

-1. Develop in the current `master` worktree and keep unrelated parallel changes separated with `git status`/`git diff`.
+1. Preflight the fixed workspace, then develop in a task-scoped `.worktree/<task>` created from the latest `origin/master`; keep unrelated parallel changes separated with `git status`/`git diff`.
 2. Run local non-Rust checks on the master server, for example `bun scripts/cli.ts check --files --scripts-typecheck --compose --logs`.
 3. Commit and push the code to `origin master`; `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.