@routerhub/agent-rules 1.5.186 → 1.5.188

package/AGENTS.base.md

@@ -49,14 +49,9 @@
 
 ## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
 
-「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——新建定时任务（cron / Cloud Scheduler / Job）并安排首次触发、只能在云平台控制台手动操作、跨仓库的部署顺序依赖、需先通知下游团队等，代码与脚本天然覆盖不到。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
-
-- ⚠️ **判断标准：只登记「自包含兜不住」的。** 能写成代码/部署脚本自动完成的准备，仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。常见「兜不住」类别：
-    - **定时/后台任务**：新建 cron / Cloud Scheduler / Job、上线后需首次手动触发、频率/开关需与生产环境人工核对（代码里通常只有任务定义，没有「谁去建、何时触发」）
-    - **云平台手动操作**：无法 IaC 化的资源、需人工在控制台点选确认
-    - **部署顺序依赖**：必须先升级/先就位某外部依赖（常跨仓库，本次 git 历史看不出）
-    - **跨团队/跨系统动作**：上线前需通知/协调下游仓库、运营、其他团队；共享基础设施变更需先获确认
-    - **上线后观察点**：上线后需盯的指标、需手动跑一遍的验证
+「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——凡是「上线前需要额外动作去做的准备」都可能属此类：新建的定时任务需要手动触发首次初跑、某资源得先在云平台控制台开通、另一个服务得先升级、得提前通知下游团队……这些代码与脚本天然覆盖不到（**上文仅是示例，判断标准见下条，不构成类别边界**）。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
+
+- ⚠️ **判断标准：凡是「上线前需要做、但写不进代码/部署脚本」的操作都登记，不受类别限定。** 判断只问一句——「这个改动上线时，有没有一个需要额外动作去做的准备？」（新建了定时任务要手动触发初跑 / 要开通或操作云平台资源 / 要联动升级别的服务 / 要提前通知运营或下游团队 / 上线后要盯某个指标……有，就登记）。能写成代码/部署脚本自动完成的准备仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。
 - ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
 - ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
     - 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
@@ -64,10 +59,11 @@
     - 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
 - ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
 - ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
-- ⚠️ **发版前扫查流程（每次上线/发版必做，禁止用「我记得这期改动」替代）**：
-    1. 用 `git log $(git describe --tags --abbrev=0)..HEAD --format=%B`（无 tag 时改用上一个「发布 vX.Y.Z」commit）列出本次全部提交；
-    2. 扫描其中的 `release-prep` 标记，逐个找到清单对应条目核对（无清单文件且无标记 = 本期无特殊准备，正常放行）；
-    3. 通读 `RELEASE_CHECKLIST.md`（若存在）全文，逐项确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因），确认无遗漏后才允许发版。
+- ⚠️ **发版前扫查流程（只看「上次发版 → 本次」的 git 增量，禁止全文通读，也禁止用「我记得这期改动」替代）**：清单随代码走、每次发版都打 tag，因此「本次上线要核对哪些注意项」天然等于清单文件在上次发版与本次之间的 git 增量——用 git 精确界定区间，只核对区间内新增/更新的条目，历史条目（上次及更早已核对过）不在本次范围，无需从头看。步骤：
+    1. **定界**：`PREV=$(git describe --tags --abbrev=0)`（取上一个发版 tag；无 tag 时改用上一个「发布 vX.Y.Z」commit）；
+    2. **列提交**：`git log $PREV..HEAD --oneline` 列出本次全部提交，先对本期改动有个整体认识；
+    3. **取增量条目**：`git diff $PREV..HEAD -- RELEASE_CHECKLIST.md`——本次需要核对的上线准备项只在这些新增/更新的条目里，逐条确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因）；`$PREV..HEAD` 之间该文件无改动 = 本期没有随代码登记的上线准备，直接放行；
+    4. **兜底扫 commit 标记**：`git log $PREV..HEAD --format=%B | grep release-prep`——若某个提交标了 `release-prep` 却在清单 diff 里找不到对应条目（标了没登记），当场补齐登记后再发版。
 - ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
 
 **清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
@@ -616,6 +612,7 @@
 - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` + 一行内容说明），这就是最终交付形式。
 - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
 - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
+- ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。
 - 交付时同时给出链接 + 简要内容说明，方便用户确认。
 
 ## Figma 还原

package/package.json

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

package/rules/global.md

@@ -49,14 +49,9 @@ name: "通用规则"
 
 ## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
 
-「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——新建定时任务（cron / Cloud Scheduler / Job）并安排首次触发、只能在云平台控制台手动操作、跨仓库的部署顺序依赖、需先通知下游团队等，代码与脚本天然覆盖不到。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
-
-- ⚠️ **判断标准：只登记「自包含兜不住」的。** 能写成代码/部署脚本自动完成的准备，仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。常见「兜不住」类别：
-    - **定时/后台任务**：新建 cron / Cloud Scheduler / Job、上线后需首次手动触发、频率/开关需与生产环境人工核对（代码里通常只有任务定义，没有「谁去建、何时触发」）
-    - **云平台手动操作**：无法 IaC 化的资源、需人工在控制台点选确认
-    - **部署顺序依赖**：必须先升级/先就位某外部依赖（常跨仓库，本次 git 历史看不出）
-    - **跨团队/跨系统动作**：上线前需通知/协调下游仓库、运营、其他团队；共享基础设施变更需先获确认
-    - **上线后观察点**：上线后需盯的指标、需手动跑一遍的验证
+「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——凡是「上线前需要额外动作去做的准备」都可能属此类：新建的定时任务需要手动触发首次初跑、某资源得先在云平台控制台开通、另一个服务得先升级、得提前通知下游团队……这些代码与脚本天然覆盖不到（**上文仅是示例，判断标准见下条，不构成类别边界**）。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
+
+- ⚠️ **判断标准：凡是「上线前需要做、但写不进代码/部署脚本」的操作都登记，不受类别限定。** 判断只问一句——「这个改动上线时，有没有一个需要额外动作去做的准备？」（新建了定时任务要手动触发初跑 / 要开通或操作云平台资源 / 要联动升级别的服务 / 要提前通知运营或下游团队 / 上线后要盯某个指标……有，就登记）。能写成代码/部署脚本自动完成的准备仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。
 - ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
 - ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
     - 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
@@ -64,10 +59,11 @@ name: "通用规则"
     - 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
 - ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
 - ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
-- ⚠️ **发版前扫查流程（每次上线/发版必做，禁止用「我记得这期改动」替代）**：
-    1. 用 `git log $(git describe --tags --abbrev=0)..HEAD --format=%B`（无 tag 时改用上一个「发布 vX.Y.Z」commit）列出本次全部提交；
-    2. 扫描其中的 `release-prep` 标记，逐个找到清单对应条目核对（无清单文件且无标记 = 本期无特殊准备，正常放行）；
-    3. 通读 `RELEASE_CHECKLIST.md`（若存在）全文，逐项确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因），确认无遗漏后才允许发版。
+- ⚠️ **发版前扫查流程（只看「上次发版 → 本次」的 git 增量，禁止全文通读，也禁止用「我记得这期改动」替代）**：清单随代码走、每次发版都打 tag，因此「本次上线要核对哪些注意项」天然等于清单文件在上次发版与本次之间的 git 增量——用 git 精确界定区间，只核对区间内新增/更新的条目，历史条目（上次及更早已核对过）不在本次范围，无需从头看。步骤：
+    1. **定界**：`PREV=$(git describe --tags --abbrev=0)`（取上一个发版 tag；无 tag 时改用上一个「发布 vX.Y.Z」commit）；
+    2. **列提交**：`git log $PREV..HEAD --oneline` 列出本次全部提交，先对本期改动有个整体认识；
+    3. **取增量条目**：`git diff $PREV..HEAD -- RELEASE_CHECKLIST.md`——本次需要核对的上线准备项只在这些新增/更新的条目里，逐条确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因）；`$PREV..HEAD` 之间该文件无改动 = 本期没有随代码登记的上线准备，直接放行；
+    4. **兜底扫 commit 标记**：`git log $PREV..HEAD --format=%B | grep release-prep`——若某个提交标了 `release-prep` 却在清单 diff 里找不到对应条目（标了没登记），当场补齐登记后再发版。
 - ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
 
 **清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
@@ -616,6 +612,7 @@ name: "通用规则"
 - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` + 一行内容说明），这就是最终交付形式。
 - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
 - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
+- ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。
 - 交付时同时给出链接 + 简要内容说明，方便用户确认。
 
 ## Figma 还原