@routerhub/agent-rules 1.5.170 → 1.5.171

package/AGENTS.base.md

@@ -139,6 +139,20 @@
 - ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
 - ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
 
+## ⚠️ 会话级 worktree 隔离铁律（一个代码任务 = 一个独立 worktree）
+
+- **目标效果**：同一仓库、同一目录允许同时开多个窗口/会话，各自在不同 worktree 里做不同任务，互不干扰——各会话的文件、暂存区（index）、git 操作互相不可见，共享的只有 `.git` 历史对象与远程。**类比：同一栋楼（同一个 `.git`）给每个任务开独立房间（worktree）——你的衣服不会跑进别人房间，但大家共用同一套电梯（历史、远程）。**
+- ⚠️ **新开会话/任务，只要涉及「改代码 / 写文件 / 跑验证」的实质工作，必须先创建独立的 git worktree 再动手，禁止直接在可能正被其他会话共用的工作区上写代码。** 判定标准：本次会话会「改动任何文件」（新建、修改、删除、改配置、跑构建验证）→ 必须进；仅只读问答、查资料、复盘、看代码（不写文件）→ 不必进。
+- **检测优先**：动手前先 `git worktree list`，若当前路径已在某个 worktree 内 → 直接用当前 worktree，禁止再套一层嵌套 worktree；只有不在 worktree 里且要写代码 → 按下面流程新建。
+- **复用场景（不新建）**：明确是「接着上一次会话/任务的未提交工作继续干」→ 回到原来的 worktree 目录继续，禁止另开新的而把未提交工作丢在原处。
+- ⚠️ **标准操作流程**：
+  1. `git fetch origin main`，确保基于最新远程主分支（`fetch` 不动主工作区，避免与其他会话占用冲突，比 `pull` 更安全）。
+  2. `git worktree add -b feature/<任务简称> ../<会话标识>-work origin/main`——从 `origin/main` 检出到独立目录并新建分支，当前工作区完全不动。目录名用英文小写中划线（含会话唯一标识），进入前先确认该路径不存在。
+  3. 在 worktree 目录内完成改动 → 编译/验证通过 → `git commit` → `git push -u origin feature/<任务简称>`。
+  4. 任务结束（提交完成 / PR 合并）后 `git worktree remove ../<会话标识>-work` 清理。一个会话全程只对应一个 worktree。
+- ⚠️ **多副本仓库（A-/B-/C-/M- 前缀）叠加生效**：worktree 建在当前会话所在副本内（选哪个副本由「⚠️ 处理其他项目/副本时统一用 worktree 隔离」规则决定），本条规则负责副本内部的会话隔离，两者不冲突。
+- ⚠️ **worktree 只隔离「文件与 git」这一层**：端口、数据库、构建缓存、浏览器标签页等外部资源仍按各自规则隔离（如 agent-browser `--namespace`）。两个会话若改同一批文件，编辑阶段互不可见，冲突会推迟到合并回主分支时显式暴露——改动明显重叠的任务应合成一个会话完成，不要拆成两个 worktree 并行。
+
 ## PR 核心要求
 
 - ⚠️ PR Title / Description / Test Plan 全部中文。

package/package.json

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

package/rules/global.md

@@ -139,6 +139,20 @@ name: "通用规则"
 - ⚠️ **worktree 与主副本共享同一套本地 `.git`**，但工作目录、索引、当前分支状态完全独立，不会干扰正在 main 或其他分支上改动代码的协作者。
 - ⚠️ **worktree 目录默认在仓库根目录同级（`../`）**，避免被误当成子文件夹进 git；进入前先确认该路径不存在同名文件夹。
 
+## ⚠️ 会话级 worktree 隔离铁律（一个代码任务 = 一个独立 worktree）
+
+- **目标效果**：同一仓库、同一目录允许同时开多个窗口/会话，各自在不同 worktree 里做不同任务，互不干扰——各会话的文件、暂存区（index）、git 操作互相不可见，共享的只有 `.git` 历史对象与远程。**类比：同一栋楼（同一个 `.git`）给每个任务开独立房间（worktree）——你的衣服不会跑进别人房间，但大家共用同一套电梯（历史、远程）。**
+- ⚠️ **新开会话/任务，只要涉及「改代码 / 写文件 / 跑验证」的实质工作，必须先创建独立的 git worktree 再动手，禁止直接在可能正被其他会话共用的工作区上写代码。** 判定标准：本次会话会「改动任何文件」（新建、修改、删除、改配置、跑构建验证）→ 必须进；仅只读问答、查资料、复盘、看代码（不写文件）→ 不必进。
+- **检测优先**：动手前先 `git worktree list`，若当前路径已在某个 worktree 内 → 直接用当前 worktree，禁止再套一层嵌套 worktree；只有不在 worktree 里且要写代码 → 按下面流程新建。
+- **复用场景（不新建）**：明确是「接着上一次会话/任务的未提交工作继续干」→ 回到原来的 worktree 目录继续，禁止另开新的而把未提交工作丢在原处。
+- ⚠️ **标准操作流程**：
+  1. `git fetch origin main`，确保基于最新远程主分支（`fetch` 不动主工作区，避免与其他会话占用冲突，比 `pull` 更安全）。
+  2. `git worktree add -b feature/<任务简称> ../<会话标识>-work origin/main`——从 `origin/main` 检出到独立目录并新建分支，当前工作区完全不动。目录名用英文小写中划线（含会话唯一标识），进入前先确认该路径不存在。
+  3. 在 worktree 目录内完成改动 → 编译/验证通过 → `git commit` → `git push -u origin feature/<任务简称>`。
+  4. 任务结束（提交完成 / PR 合并）后 `git worktree remove ../<会话标识>-work` 清理。一个会话全程只对应一个 worktree。
+- ⚠️ **多副本仓库（A-/B-/C-/M- 前缀）叠加生效**：worktree 建在当前会话所在副本内（选哪个副本由「⚠️ 处理其他项目/副本时统一用 worktree 隔离」规则决定），本条规则负责副本内部的会话隔离，两者不冲突。
+- ⚠️ **worktree 只隔离「文件与 git」这一层**：端口、数据库、构建缓存、浏览器标签页等外部资源仍按各自规则隔离（如 agent-browser `--namespace`）。两个会话若改同一批文件，编辑阶段互不可见，冲突会推迟到合并回主分支时显式暴露——改动明显重叠的任务应合成一个会话完成，不要拆成两个 worktree 并行。
+
 ## PR 核心要求
 
 - ⚠️ PR Title / Description / Test Plan 全部中文。