docs: document master-first tool usage

2026-06-22 06:54:25 +00:00
parent 8ffe9e3249
commit 5e966fb06d
1 changed files with 1 additions and 0 deletions
@@ -182,6 +182,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文

 - UniDesk 同时存在 main server、D601 `~/cq-deploy` 和其他 provider worktree 等多个开发/部署实例；Git remote 是长期 source of truth，本地部署实例只能视为运行副本或缓存。
 - 任何开发、文档或部署配置变更开始前，必须先在当前 worktree 执行 `git status` 并从主线拉取最新源码：`git pull --ff-only origin master`；若本地并行变更或远端推进导致不能快进，必须当即分清来源并解决冲突后再继续。
+- UniDesk 工具链自身修复必须先合并到 `master`，再把实际执行工具命令的 checkout 更新到包含该 merge 的最新 `master` 后继续使用；若当前 checkout 有并行脏改或非 master 分支导致不能安全 fast-forward，禁止 reset、stash、checkout 或删除来清理，改用干净 `origin/master` worktree 运行工具并明确回报当前 checkout 未更新原因。
 - 任何需要保留的代码、文档或配置变更，在完成必要自测/部署验证后必须立刻按 `git-spec` 提交并 push 到 remote；禁止让未推送的本地修改成为部署真相或后续任务依赖。
 - 提交前必须用 `git status` 和 `git diff` 确认工作区状态；UniDesk 默认集成线是 `master`，但 agent 开发必须优先在从最新 `origin/master` 创建的独立 `.worktree/<task>` 和任务分支中完成，避免污染固定主 repo；长期规则见 `docs/reference/arch.md`。
 - P0: 单纯文档或 UniDesk CLI/trans/tran/helper 变更属于轻量交付，默认仍以 `master` 为合入目标；可按任务风险直接合入/push，也可走短生命周期 PR，禁止在固定主 repo 根目录直接当 scratch 区修改。