@routerhub/agent-rules 1.5.167 → 1.5.169

package/AGENTS.base.md

@@ -117,6 +117,17 @@
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ 处理其他项目/副本时统一用 worktree 隔离（不改别人正在用的分支）
+
+- ⚠️ **需要修改某个仓库，而该仓库是多副本（A-/B-/C-/M- 前缀）且当前分支可能正被其他开发任务占用时，默认用临时 git worktree 隔离操作，禁止直接在当前工作副本上 `git checkout` 切换分支。** 多副本仓库中同一个克隆往往同时被多个任务使用：直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。实例：`c-pomex-gateway` 正被 `feature/timeslot-pricing` 开发任务占用（落后 main 10 个提交），此时要做文档迁移，就用 `git worktree` 从 `origin/main` 检出到独立目录操作，feature 分支工作区完全不动。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add -b <任务分支> ../<任务>-work <基础分支>`（基础分支用 `origin/main` 或具体目标分支），独立目录检出并新建分支，当前工作副本完全不动。
+  2. 在 worktree 目录内完成改动 → 编译/测试通过 → `git push -u origin <任务分支>`。
+  3. 创建 PR（合并目标为仓库默认分支）。
+  4. 操作完成后 `git worktree remove ../<任务>-work` 清理，原副本分支状态不受影响。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## ⚠️ PR 冲突修复统一用临时 worktree
 
 - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。
@@ -524,6 +535,11 @@
 - ⚠️ **文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
 - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成 HTML → 无头 Chrome 转 PDF → push 到 `<项目>-docs` 私有仓库的 `docs` 分支 → 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
 - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<pdf|md>`，粘贴到浏览器即可查看（GitHub 内嵌渲染 PDF / Markdown；私有仓库未登录会跳登录页）。
+- ⚠️ **迁移项目既有文档到 `<项目>-docs` 前，先区分「纯文档」与「代码资产 / 对外服务页面」，禁止一刀切全迁**：
+  - **对外服务的 API 文档站**（gateway 类项目的 `docs/`：含 `index.html` + `authentication.html` + `css/` + `js/` + `nginx.conf.template` 的整套站点）是**线上产品页面**，随模型/接口持续更新（git log 常有「添加 xxx 模型」等提交），线上 URL 可访问（如 `https://xxx/docs` 返回 200）——这类**不能迁**，迁走线上直接 404。判断标准：线上有对应 URL 且能访问 → 是对外服务页面，不是内部文档。
+  - **散落文档目录**（`inter_docs/`、`local_docs/`、`design_docs/`、`internal/xxx/docs/`）里常**混着代码**：需求/设计/测试说明（.md）旁边就有集成测试脚本（.sh）、用例（.sql/.json）、env 模板、甚至被 Go 代码运行时引用的路径（如 `filepath.Join(repoRoot, "inter_docs", ...)`）。迁移前必须逐目录核对：**纯 .md 文档 → 迁；.sh/.sql/.json/.env 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
+  - **类比：搬书房前先分清楚「书」和「记账本」**——书（纯文档）搬进藏书库（-docs 仓库），记账本（测试脚本/被引用的配置）得留在桌上随时用；把记账本也塞进藏书库，下次算账（跑测试）就找不到本子了。
+  - 核对方法：迁移前 `grep -rn "目录名"` 搜代码/CI/脚本，确认哪些路径被引用；被引用的保留，未被引用的纯文档才迁。
 
 ## 文档/文件链接交付
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.167",
+  "version": "1.5.169",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -117,6 +117,17 @@ name: "通用规则"
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
 - ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
+## ⚠️ 处理其他项目/副本时统一用 worktree 隔离（不改别人正在用的分支）
+
+- ⚠️ **需要修改某个仓库，而该仓库是多副本（A-/B-/C-/M- 前缀）且当前分支可能正被其他开发任务占用时，默认用临时 git worktree 隔离操作，禁止直接在当前工作副本上 `git checkout` 切换分支。** 多副本仓库中同一个克隆往往同时被多个任务使用：直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。实例：`c-pomex-gateway` 正被 `feature/timeslot-pricing` 开发任务占用（落后 main 10 个提交），此时要做文档迁移，就用 `git worktree` 从 `origin/main` 检出到独立目录操作，feature 分支工作区完全不动。
+- ⚠️ **标准操作流程**：
+  1. 在仓库根目录执行 `git worktree add -b <任务分支> ../<任务>-work <基础分支>`（基础分支用 `origin/main` 或具体目标分支），独立目录检出并新建分支，当前工作副本完全不动。
+  2. 在 worktree 目录内完成改动 → 编译/测试通过 → `git push -u origin <任务分支>`。
+  3. 创建 PR（合并目标为仓库默认分支）。
+  4. 操作完成后 `git worktree remove ../<任务>-work` 清理，原副本分支状态不受影响。
+- ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
+- ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
+
 ## ⚠️ PR 冲突修复统一用临时 worktree
 
 - ⚠️ **修复 PR 与主分支的冲突时，一律使用临时 git worktree，禁止直接在当前工作副本上切换分支（`git checkout`）解题。** 原因：A-/B-/C-/M- 多副本仓库中，同一个克隆往往同时被其他开发任务占用；直接切分支会破坏别人正在进行的代码、或把自己卡在非主分支上。
@@ -524,6 +535,11 @@ name: "通用规则"
 - ⚠️ **文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
 - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成 HTML → 无头 Chrome 转 PDF → push 到 `<项目>-docs` 私有仓库的 `docs` 分支 → 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
 - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<pdf|md>`，粘贴到浏览器即可查看（GitHub 内嵌渲染 PDF / Markdown；私有仓库未登录会跳登录页）。
+- ⚠️ **迁移项目既有文档到 `<项目>-docs` 前，先区分「纯文档」与「代码资产 / 对外服务页面」，禁止一刀切全迁**：
+  - **对外服务的 API 文档站**（gateway 类项目的 `docs/`：含 `index.html` + `authentication.html` + `css/` + `js/` + `nginx.conf.template` 的整套站点）是**线上产品页面**，随模型/接口持续更新（git log 常有「添加 xxx 模型」等提交），线上 URL 可访问（如 `https://xxx/docs` 返回 200）——这类**不能迁**，迁走线上直接 404。判断标准：线上有对应 URL 且能访问 → 是对外服务页面，不是内部文档。
+  - **散落文档目录**（`inter_docs/`、`local_docs/`、`design_docs/`、`internal/xxx/docs/`）里常**混着代码**：需求/设计/测试说明（.md）旁边就有集成测试脚本（.sh）、用例（.sql/.json）、env 模板、甚至被 Go 代码运行时引用的路径（如 `filepath.Join(repoRoot, "inter_docs", ...)`）。迁移前必须逐目录核对：**纯 .md 文档 → 迁；.sh/.sql/.json/.env 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
+  - **类比：搬书房前先分清楚「书」和「记账本」**——书（纯文档）搬进藏书库（-docs 仓库），记账本（测试脚本/被引用的配置）得留在桌上随时用；把记账本也塞进藏书库，下次算账（跑测试）就找不到本子了。
+  - 核对方法：迁移前 `grep -rn "目录名"` 搜代码/CI/脚本，确认哪些路径被引用；被引用的保留，未被引用的纯文档才迁。
 
 ## 文档/文件链接交付