@routerhub/agent-rules 1.5.211 → 1.5.213

package/AGENTS.base.md

@@ -147,7 +147,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
 - ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
 - ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 bug 亲手复现了一次。
-  - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML→PDF，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
+  - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
   - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
   - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
 - ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
@@ -284,7 +284,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **副作用范围上界表：每条 DELETE / 每次写操作，都要在报告里逐条列出「动什么 / 为什么在这里动 / 最多影响多少行」，且实测影响必须 ≤ 上界。** 这条把「⚠️ 数据库 DELETE 铁律」要求的那三个问题**从代码注释搬进报告**——注释只有写代码的人看得到，报告是给用户和 reviewer 看的。上界说不清、或实测超出上界的，直接视为本次改动未完成。
 - ⚠️ **操作链必须是「真人在真实界面里点出来的」，并在报告里逐步列明。** 禁止用脚本模拟、直接改数据库、调内部接口去造出「改动后」的状态——那不是「用户这么操作会发生什么」，而是「我造了一个我希望看到的结果」。报告里要能让读者看出每一步点的是哪个按钮、点完看到什么。
 - ⚠️ **交付形式跟随交付场景，禁止一律套同一种：**
-  - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML→PDF，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
+  - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description，附「下载后双击打开」指引）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
   - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**（截图 `data:image/png;base64` 内嵌、双击即开、可搜索、转发不裂图），不走私有仓库、不起本地 HTTP 服务、不用相对路径。
 - ⚠️ **与相邻铁律的分工（四者是同一条路径在时间轴上不同位置各跑一次，不可互相替代）：** 「⚠️ 缺陷复现铁律」= 改之前证明问题存在；「⚠️ 修复验证铁律」= 改之后证明问题消失；「⚠️ 跨系统真实链路验收铁律」= 整条链路成不成立（下游接住了没有）；**本铁律 = 这次改动的副作用范围有没有失控（不该动的动了吗）**。前三条全过、本铁律不过的情况真实存在——功能修好了、链路跑通了、但目录数据被顺带删了。
 - ⚠️ **具体操作流程见 `/forensic-report` skill**（三层证据怎么拍、逐像素怎么相减、差异怎么归因、可复核导航怎么组织、报告骨架长什么样）。
@@ -292,7 +292,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` 会在 main 上生成「发布 vX.Y.Z」提交）。
+- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（唯一例外：发版载体仓库执行 `./release.sh` 时会在 main 上生成「发布 vX.Y.Z」提交；非发版载体仓库没有该脚本，不存在这个例外）。
 - ⚠️ **从主分支拉/建功能分支之前，必须先直接拉取远程主分支（`git pull origin main`）**，确保基于最新的远程主分支拉分支，禁止基于过期的本地主分支创建分支。
 - ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
@@ -340,10 +340,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
     - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
     - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
 - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
-- ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
-    - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
-    - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
-    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
+- ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：
+    - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的那份**截图版 HTML** 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 下载后打开即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
+    - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)（点开后请点右上角「Download raw file」下载，双击下载的 HTML 打开）`。reviewer 建议在新标签页打开，看完细节再回正文。
+    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：生成自包含 HTML（截图 `data:image/png;base64` 内嵌）→ 直接 push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html` 格式（**GitHub 对 HTML 只显示源码、不渲染，因此链接旁必须附「Download raw file 下载后双击打开」的指引**；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
     - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
     - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
 - ⚠️ PR Title / Description / Test Plan 全部中文。
@@ -359,18 +359,18 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **PR 创建即进入可评审状态**：直接创建正式 PR（非 Draft），创建完成、冲突检查与静态编译通过后即可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review。
 - ⚠️ **创建 PR 后必须先过 CI 再进入后续流程**：创建完成后第一时间执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若有任一检查 `failure`，必须先定位并修复失败项、推送新提交并复查到全部 `success`，然后才能进入循环 review、测试验证、交付 review 等后续步骤，禁止带红 CI 继续往下走。
 - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
-- ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
+- ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后交付测试环境**，三步收尾缺一不可：
 1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
 2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
-3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
-- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → **链路预演** → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，七步缺一不可，全程自动执行：
+3. **交付测试环境**：PR 合并后把最新代码交付到**测试环境**（走 `/deploy-test` skill），交付终点到此为止。⚠️ **业务仓库一律只交付测试环境，不发布生产**——`./release.sh`（patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）是**发版载体仓库自己**的机制，**仅当本仓库根目录确实存在 `./release.sh`（如 `@routerhub/agent-rules` 包自身）时才执行**；根目录没有这个脚本 = 本仓库不是发版载体，此步只做测试环境交付，**禁止据此推断出「那大概是生产部署吧」再补一个替代动作，禁止自行启动任何生产发布**（呼应「⚠️ 环境配置禁止推断」）。
+- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → **链路预演** → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 交付测试环境，七步缺一不可，全程自动执行：
 0. **先走「链路预演」（在循环 review 之前，轻量）**：PR 创建后**立刻**判断是否命中「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件。命中 → 触发 `/real-chain-verify` 的**阶段 1**：只画链路、逐环节快速过一遍，回答「**这条链路成不成立、需求口径对不对**」，**不写 6 段报告、不做截图标注**（约阶段 2 的 20~30% 工作量）。⚠️ **这一步的目的是尽早暴露「需要大改」的问题**（需求口径反转、默认值不对、跨仓库语义不成立、schema 要改）——**大改放在 review 之后发现，等于前面 N 轮 review 全白跑**。发现需大改 → 先改完再进循环 review，禁止带着「可能推翻重做」的设计去跑 review。未命中 → 本步跳过，直接进第 1 步，并在 PR 描述里勾选豁免项。
 1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。**循环 review 走完后，必须显式输出「✅ 循环 review 完成，进入发布收尾闭环」，并调用 `/pr-release-loop` skill 走完后续步骤。**
-2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 发版，必须先 `/deploy-test` 重部署。**
+2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 交付，必须先 `/deploy-test` 重部署。**
 3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。⚠️ **命中「⚠️ 跨系统真实链路验收铁律」触发条件的，本步即该铁律的「阶段 2 链路验收」**：按 `/real-chain-verify` 走完整取证与 6 段报告，把阶段 1 画出的链路逐环节补上下游可观测事实与下游真实生效证据（阶段 1 只判「通不通」，本步必须交出「下游留下了什么痕迹」）。
 4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
-5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
-6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
+5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行交付。
+6. **交付测试环境**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后把最新代码交付到测试环境（走 `/deploy-test` skill）。⚠️ **交付终点就是测试环境，不发布生产**；仅当本仓库根目录确实存在 `./release.sh`（发版载体仓库，如 `@routerhub/agent-rules` 包自身）时，才在这一步额外执行 `./release.sh` 发版。
 - ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全
@@ -615,7 +615,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ### HTML 文档截图与 curl 命令规范
 
-- ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有仓库 PDF 等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
+- ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有文档仓库等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
 - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
@@ -723,7 +723,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## 部署规则
 
-- 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
+- ⚠️ **交付终点是测试环境，不是生产**：日常需求 / 修复的交付到「部署测试环境 + 测试环境验证通过」为止，**业务仓库不发布生产**（要上生产由用户另行明确要求，按下方生产部署铁律走）。测试环境部署见下一条。
+- ⚠️ **`./release.sh` 只属于发版载体仓库**：根目录存在 `./release.sh` 的仓库（如 `@routerhub/agent-rules` 包自身——它靠 npm publish 发版、下游仓库靠依赖升级拿到新规则）才执行 `./release.sh` 发版；**业务仓库根目录没有这个脚本，禁止执行、也禁止推断出一个替代的发版动作**。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill，严禁跳过 skill 直接执行部署操作（合并/推送/部署/切回的具体流程见该 skill）。
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
 - ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
@@ -762,11 +763,12 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## 文档规则
 
-- ⚠️ **文档格式选型：能 MD 就 MD，HTML→PDF 只用于截图版报告**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；只有验证报告/截图版报告等需要内嵌截图+箭头标注的可视化文档才用 HTML→PDF（GitHub blob 视图对 HTML 显示源码不渲染，转 PDF 才能点开即看）。**类比：写便签能说清的事就不要做成一整本画册——便签（MD）贴上墙人人直接看，画册（HTML）GitHub 这面墙只显示印刷源码，还得额外转成 PDF 才能翻。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → HTML→PDF；不需要 → MD 直传。
+- ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。
+- ⚠️ **交付截图版 HTML 必须附「怎么打开」的三步说明，否则对方看到源码会以为链接坏了**：GitHub 对 `.html` **任何链接形式都不渲染**——blob 视图显示带行号的源码；`raw.githubusercontent.com` 与 `github.com/<ORG>/<REPO>/raw/<BRANCH>/<文件>` 均以 `content-type: text/plain` 返回，浏览器同样只显示源码文本（已实测确认）。因此交付话术固定为三步：**点链接 → 点页面右上角「Download raw file」下载 → 双击下载下来的 `.html` 打开**（若浏览器直接把源码文本打开了，改用 ⌘S / Ctrl+S 另存为 `.html` 再双击）。**禁止只甩一个链接、不说怎么打开。**
 - ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/index.html`**（`文档名 | 链接` 表格，链接一律 `target="_blank" rel="noopener"` 新标签页打开），**禁止在 `docs/` 存放文档正文**（HTML / PDF / MD / 截图 / 图片等大文件一律不提交进代码仓库）。
 - ⚠️ **文档正文存放到本项目对应的私有 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；私有仓库未登录会跳登录页）。
+- 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成自包含 HTML → 直接 push 到 `<项目>-docs` 私有仓库的 `docs` 分支（**不再转 PDF**）→ 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
+- 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>`，粘贴到浏览器即可打开（`.md` GitHub 原生渲染；`.html` 显示源码，必须按上方三步说明下载后本地打开；私有仓库未登录会跳登录页）。
 - ⚠️ **迁移项目既有文档到 `<项目>-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 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
@@ -775,7 +777,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## 文档/文件链接交付
 
-- ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` + 一行内容说明），这就是最终交付形式。
+- ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。
 - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
 - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
 - ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。
@@ -847,8 +849,6 @@ Chrome Helper 会越积越多，表现为“agent-browser 用着用着越来越
 
 ## 前端规则
 
-我测试下看看能不能发新版本
-
 - ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。
 - ⚠️ **依赖安装统一 `pnpm`**，禁止 `npm install` / `yarn install`（pnpm workspace 混合安装会破坏依赖结构）。
 - ⚠️ **API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径**；接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.213] - 2026-09-14
+
+### Changed
+
+- **把闭环流程的交付终点从「发新版本」改成「交付测试环境」，并把 `./release.sh` 限定为「只属于发版载体仓库」**：原规则把 PR 闭环的收尾写成「发新版本：本项目统一执行根目录 `./release.sh`（自动 patch +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）」，并且是**无条件**分发给 8 个下游业务仓库的。问题在于 `./release.sh` 是 **agent-rules 自己**的发版机制（它靠 npm publish 发版、下游靠依赖升级拿到新规则），业务仓库根目录根本没有这个脚本、也从不发布 npm 包。下游 AI 读到「七步缺一不可」后只有两条路：**要么凭空推断出一个替代动作**（实测发生过：把不存在的 `./release.sh` 猜成「那大概是生产部署吧」，进而把生产部署当成可选项提给用户），**要么卡住不动**——两种都不是规则想要的。现在明确：**业务仓库的交付终点就是测试环境**，收尾第三步是「交付测试环境（走 `/deploy-test`）」；`./release.sh` **仅当本仓库根目录确实存在该脚本时**（如 `@routerhub/agent-rules` 包自身）才执行，并显式写明**根目录没有该脚本时禁止推断替代动作、禁止自行启动生产发布**（呼应「⚠️ 环境配置禁止推断：来源都找不到的就写『待确认』，禁止自行补全」）。
+  - **`AGENTS.base.md`**：三步收尾的第 3 项、闭环七步的最后一步（第 6 步）与流程标题、「部署规则」章首、Git 规范里 main 分支「发版除外」的例外说明，全部同步改写；闭环流程内的「禁止直接发 PR 链接 / 发版」改为「/ 交付」。
+  - **`skills/pr-release-loop/SKILL.md`**：frontmatter description、完成定义清单第 10 项、第 6/7 步与「判断边界」三条边界，统一把「发版」改为「交付测试环境」。
+  - **`skills/create-pr/SKILL.md`**：步骤 7、步骤 8 标题与「③ 发新版本」小节、重要规则区两条闭环描述。
+  - **`skills/deploy-test/SKILL.md`**：**本次最自相矛盾的一处**——一个专门负责「部署测试环境」的 skill，原第 6 步部署完 test 分支后紧接着第 7 步却是「发新版本（如 `./release.sh`）」，等于自己给「测试环境交付」续了一个发版尾巴。现已改为「第 6 步部署 test 分支」即终点，并显式写明本 Skill 不碰 `./release.sh`。
+
+### Fixed
+
+- **删除 `AGENTS.base.md`「前端规则」章节里的一行残留测试文本**（`我测试下看看能不能发新版本`）：这行字原本夹在 `<!-- @domain: frontend -->` 与第一条前端规则之间，会被 `generateRulesFromBase()` 一起带进 `rules/frontend.md` 和 `.github/instructions/frontend.instructions.md`，分发给所有前端仓库——既污染规则正文，又正好是一句与发版有关的误导性内容。已随本次一并清除。
+
 ## [1.5.205] - 2026-09-10
 
 ### Changed

package/package.json

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

package/rules/frontend.md

@@ -6,8 +6,6 @@ outputName: "frontend"
 
 ## 前端规则
 
-我测试下看看能不能发新版本
-
 - ⚠️ **默认隐藏滚动条**：页面/容器出现滚动需求时，滚动条默认隐藏（内容仍可正常滚动），不得让滚动条可见。仅当用户明确说「需要滚动条」「可以有滚动条」「显示滚动条」等表述时，才允许显示。
 - ⚠️ **依赖安装统一 `pnpm`**，禁止 `npm install` / `yarn install`（pnpm workspace 混合安装会破坏依赖结构）。
 - ⚠️ **API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径**；接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。

package/rules/global.md

@@ -147,7 +147,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
 - ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
 - ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 bug 亲手复现了一次。
-  - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML→PDF，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
+  - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
   - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
   - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
 - ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
@@ -284,7 +284,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **副作用范围上界表：每条 DELETE / 每次写操作，都要在报告里逐条列出「动什么 / 为什么在这里动 / 最多影响多少行」，且实测影响必须 ≤ 上界。** 这条把「⚠️ 数据库 DELETE 铁律」要求的那三个问题**从代码注释搬进报告**——注释只有写代码的人看得到，报告是给用户和 reviewer 看的。上界说不清、或实测超出上界的，直接视为本次改动未完成。
 - ⚠️ **操作链必须是「真人在真实界面里点出来的」，并在报告里逐步列明。** 禁止用脚本模拟、直接改数据库、调内部接口去造出「改动后」的状态——那不是「用户这么操作会发生什么」，而是「我造了一个我希望看到的结果」。报告里要能让读者看出每一步点的是哪个按钮、点完看到什么。
 - ⚠️ **交付形式跟随交付场景，禁止一律套同一种：**
-  - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML→PDF，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
+  - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description，附「下载后双击打开」指引）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
   - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**（截图 `data:image/png;base64` 内嵌、双击即开、可搜索、转发不裂图），不走私有仓库、不起本地 HTTP 服务、不用相对路径。
 - ⚠️ **与相邻铁律的分工（四者是同一条路径在时间轴上不同位置各跑一次，不可互相替代）：** 「⚠️ 缺陷复现铁律」= 改之前证明问题存在；「⚠️ 修复验证铁律」= 改之后证明问题消失；「⚠️ 跨系统真实链路验收铁律」= 整条链路成不成立（下游接住了没有）；**本铁律 = 这次改动的副作用范围有没有失控（不该动的动了吗）**。前三条全过、本铁律不过的情况真实存在——功能修好了、链路跑通了、但目录数据被顺带删了。
 - ⚠️ **具体操作流程见 `/forensic-report` skill**（三层证据怎么拍、逐像素怎么相减、差异怎么归因、可复核导航怎么组织、报告骨架长什么样）。
@@ -292,7 +292,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` 会在 main 上生成「发布 vX.Y.Z」提交）。
+- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（唯一例外：发版载体仓库执行 `./release.sh` 时会在 main 上生成「发布 vX.Y.Z」提交；非发版载体仓库没有该脚本，不存在这个例外）。
 - ⚠️ **从主分支拉/建功能分支之前，必须先直接拉取远程主分支（`git pull origin main`）**，确保基于最新的远程主分支拉分支，禁止基于过期的本地主分支创建分支。
 - ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
@@ -340,10 +340,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
     - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
     - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
 - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
-- ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
-    - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
-    - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
-    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
+- ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：
+    - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的那份**截图版 HTML** 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 下载后打开即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
+    - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)（点开后请点右上角「Download raw file」下载，双击下载的 HTML 打开）`。reviewer 建议在新标签页打开，看完细节再回正文。
+    - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：生成自包含 HTML（截图 `data:image/png;base64` 内嵌）→ 直接 push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html` 格式（**GitHub 对 HTML 只显示源码、不渲染，因此链接旁必须附「Download raw file 下载后双击打开」的指引**；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
     - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
     - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
 - ⚠️ PR Title / Description / Test Plan 全部中文。
@@ -359,18 +359,18 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 - ⚠️ **PR 创建即进入可评审状态**：直接创建正式 PR（非 Draft），创建完成、冲突检查与静态编译通过后即可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review。
 - ⚠️ **创建 PR 后必须先过 CI 再进入后续流程**：创建完成后第一时间执行 `gh pr checks <PR>`（必要时轮询直到非 `pending`）。若有任一检查 `failure`，必须先定位并修复失败项、推送新提交并复查到全部 `success`，然后才能进入循环 review、测试验证、交付 review 等后续步骤，禁止带红 CI 继续往下走。
 - ⚠️ **每次修改 PR 后（含创建 PR、push 新提交、响应 review 意见重新推送等所有改动 PR 的动作之后），都必须检查与主分支（默认分支）是否有冲突**：用 `gh pr view <PR> --json mergeable -q .mergeable` 检查（`MERGEABLE`=无冲突可合并，`CONFLICTING`=存在冲突，`UNKNOWN`=GitHub 尚未判定，稍后复查）。若存在冲突，必须先解决冲突再交付 review——`git merge origin/main`（或 `git rebase origin/main`）→ 解决冲突文件 → 测试通过 → 推送，确保 PR 处于可合并状态，禁止把带冲突的 PR 抛给 reviewer。主分支随时可能前进，一个创建时无冲突的 PR 可能在后续 push 后悄悄变冲突，因此每次改动 PR 后都必须重新检查，禁止只在创建时查一次就以为高枕无忧。
-- ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后发新版本**，三步收尾缺一不可：
+- ⚠️ **每次修改 PR 后，除冲突检查外还必须检查 GitHub 静态编译是否通过，通过后交付测试环境**，三步收尾缺一不可：
 1. **与主分支冲突检查**：按上一条规则执行（`gh pr view <PR> --json mergeable -q .mergeable`），有冲突必须先解决。
 2. **GitHub 静态编译检查**：用 `gh pr checks <PR>` 查看 CI 检查状态（`success`=通过，`failure`=失败，`pending`=进行中）。存在失败项时，必须定位失败根因、修改代码并重新推送，直到全部通过，禁止把静态编译未通过的 PR 抛给 reviewer。
-3. **发新版本**：PR 合并后按项目发布流程发布新版本（本项目统一执行根目录 `./release.sh`，自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。
-- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → **链路预演** → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 发新版本，七步缺一不可，全程自动执行：
+3. **交付测试环境**：PR 合并后把最新代码交付到**测试环境**（走 `/deploy-test` skill），交付终点到此为止。⚠️ **业务仓库一律只交付测试环境，不发布生产**——`./release.sh`（patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）是**发版载体仓库自己**的机制，**仅当本仓库根目录确实存在 `./release.sh`（如 `@routerhub/agent-rules` 包自身）时才执行**；根目录没有这个脚本 = 本仓库不是发版载体，此步只做测试环境交付，**禁止据此推断出「那大概是生产部署吧」再补一个替代动作，禁止自行启动任何生产发布**（呼应「⚠️ 环境配置禁止推断」）。
+- ⚠️ **创建完 PR 后自动走完整闭环流程，未走完不算完成**：创建 PR → **链路预演** → 循环 review → 重新部署测试环境验证 → 确认没问题 → 发 PR 链接给用户 → 交付测试环境，七步缺一不可，全程自动执行：
 0. **先走「链路预演」（在循环 review 之前，轻量）**：PR 创建后**立刻**判断是否命中「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件。命中 → 触发 `/real-chain-verify` 的**阶段 1**：只画链路、逐环节快速过一遍，回答「**这条链路成不成立、需求口径对不对**」，**不写 6 段报告、不做截图标注**（约阶段 2 的 20~30% 工作量）。⚠️ **这一步的目的是尽早暴露「需要大改」的问题**（需求口径反转、默认值不对、跨仓库语义不成立、schema 要改）——**大改放在 review 之后发现，等于前面 N 轮 review 全白跑**。发现需大改 → 先改完再进循环 review，禁止带着「可能推翻重做」的设计去跑 review。未命中 → 本步跳过，直接进第 1 步，并在 PR 描述里勾选豁免项。
 1. **自动走循环 review**：创建完 PR 后自动触发 `/loop-review` skill，反复「拉取 AI review（Claude Opus + GPT 交叉验证）→ 逐条读真实代码判断哪些值得修 → 值得修的改、不值得修/误报的 Won't fix 切断 → push 触发新一轮 review」，直到某一轮不再冒出值得修的新问题才结束，禁止只跑一轮就收工。**循环 review 走完后，必须显式输出「✅ 循环 review 完成，进入发布收尾闭环」，并调用 `/pr-release-loop` skill 走完后续步骤。**
-2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 发版，必须先 `/deploy-test` 重部署。**
+2. **重新部署到测试环境（循环 review 后最容易漏掉的一步）**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。⚠️ **循环 review 期间每次修复都会 push 新 commit；不重新部署 = 测试环境跑的还是 review 之前的旧代码 = 用旧代码验证新改动 = 结论无效。因此循环 review 结束后禁止直接发 PR 链接 / 交付，必须先 `/deploy-test` 重部署。**
 3. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `screenshots/` 临时目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。⚠️ **命中「⚠️ 跨系统真实链路验收铁律」触发条件的，本步即该铁律的「阶段 2 链路验收」**：按 `/real-chain-verify` 走完整取证与 6 段报告，把阶段 1 画出的链路逐环节补上下游可观测事实与下游真实生效证据（阶段 1 只判「通不通」，本步必须交出「下游留下了什么痕迹」）。
 4. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
-5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行发版。
-6. **发新版本**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
+5. **把 PR 链接发给用户**：确认没问题后，先把 PR 链接发送给用户（`gh pr view <PR> --json url -q .url`），让用户能直接打开查看，再执行交付。
+6. **交付测试环境**：确认没问题、PR 链接已发送后，按上面三步收尾完成冲突检查与静态编译检查，PR 合并后把最新代码交付到测试环境（走 `/deploy-test` skill）。⚠️ **交付终点就是测试环境，不发布生产**；仅当本仓库根目录确实存在 `./release.sh`（发版载体仓库，如 `@routerhub/agent-rules` 包自身）时，才在这一步额外执行 `./release.sh` 发版。
 - ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全
@@ -615,7 +615,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ### HTML 文档截图与 curl 命令规范
 
-- ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有仓库 PDF 等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
+- ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有文档仓库等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
 - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
@@ -723,7 +723,8 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## 部署规则
 
-- 发版统一执行 `./release.sh`。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
+- ⚠️ **交付终点是测试环境，不是生产**：日常需求 / 修复的交付到「部署测试环境 + 测试环境验证通过」为止，**业务仓库不发布生产**（要上生产由用户另行明确要求，按下方生产部署铁律走）。测试环境部署见下一条。
+- ⚠️ **`./release.sh` 只属于发版载体仓库**：根目录存在 `./release.sh` 的仓库（如 `@routerhub/agent-rules` 包自身——它靠 npm publish 发版、下游仓库靠依赖升级拿到新规则）才执行 `./release.sh` 发版；**业务仓库根目录没有这个脚本，禁止执行、也禁止推断出一个替代的发版动作**。（自包含铁律见上方「⚠️ 可部署性自包含铁律」章节）
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill，严禁跳过 skill 直接执行部署操作（合并/推送/部署/切回的具体流程见该 skill）。
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
 - ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
@@ -762,11 +763,12 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## 文档规则
 
-- ⚠️ **文档格式选型：能 MD 就 MD，HTML→PDF 只用于截图版报告**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；只有验证报告/截图版报告等需要内嵌截图+箭头标注的可视化文档才用 HTML→PDF（GitHub blob 视图对 HTML 显示源码不渲染，转 PDF 才能点开即看）。**类比：写便签能说清的事就不要做成一整本画册——便签（MD）贴上墙人人直接看，画册（HTML）GitHub 这面墙只显示印刷源码，还得额外转成 PDF 才能翻。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → HTML→PDF；不需要 → MD 直传。
+- ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。
+- ⚠️ **交付截图版 HTML 必须附「怎么打开」的三步说明，否则对方看到源码会以为链接坏了**：GitHub 对 `.html` **任何链接形式都不渲染**——blob 视图显示带行号的源码；`raw.githubusercontent.com` 与 `github.com/<ORG>/<REPO>/raw/<BRANCH>/<文件>` 均以 `content-type: text/plain` 返回，浏览器同样只显示源码文本（已实测确认）。因此交付话术固定为三步：**点链接 → 点页面右上角「Download raw file」下载 → 双击下载下来的 `.html` 打开**（若浏览器直接把源码文本打开了，改用 ⌘S / Ctrl+S 另存为 `.html` 再双击）。**禁止只甩一个链接、不说怎么打开。**
 - ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/index.html`**（`文档名 | 链接` 表格，链接一律 `target="_blank" rel="noopener"` 新标签页打开），**禁止在 `docs/` 存放文档正文**（HTML / PDF / MD / 截图 / 图片等大文件一律不提交进代码仓库）。
 - ⚠️ **文档正文存放到本项目对应的私有 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；私有仓库未登录会跳登录页）。
+- 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成自包含 HTML → 直接 push 到 `<项目>-docs` 私有仓库的 `docs` 分支（**不再转 PDF**）→ 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
+- 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>`，粘贴到浏览器即可打开（`.md` GitHub 原生渲染；`.html` 显示源码，必须按上方三步说明下载后本地打开；私有仓库未登录会跳登录页）。
 - ⚠️ **迁移项目既有文档到 `<项目>-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 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
@@ -775,7 +777,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## 文档/文件链接交付
 
-- ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` + 一行内容说明），这就是最终交付形式。
+- ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。
 - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
 - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
 - ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。

package/skills/create-doc/SKILL.md

@@ -11,21 +11,21 @@ description: >-
   「生成一个截图版的html」「生成截图版html」「生成一个截图版」「生成截图版」「截图版文档」「截图版报告」「截图版说明」「截图版的」等任何「截图版」表述。
   「生成一个html」「生成html」「生成一个html文档」「生成html文档」「写个html」「写html」「做一个html」「做个html」「出一个html」「出个html」「搞个html」「整个html」「弄个html」「html文档」「html报告」等任何明确要求生成 HTML 的表述。
   「html」单独说且上下文在讨论产出物时也应触发。
-  自动生成符合项目规范的中文文档，存入本项目私有文档仓库（<项目>-docs），在代码仓库 docs/index.html 索引记录「文档名 | 链接」。纯文字/表格类文档用 Markdown 直传（GitHub 原生渲染、零转换）；截图版报告用 HTML 格式（中文文件名、base64 内嵌截图、lightbox 放大、截图为主文字为辅）转 PDF 后上传。
+  自动生成符合项目规范的中文文档，存入本项目私有文档仓库（<项目>-docs），在代码仓库 docs/index.html 索引记录「文档名 | 链接」。纯文字/表格类文档用 Markdown 直传（GitHub 原生渲染、零转换）；截图版报告用 HTML 格式（中文文件名、base64 内嵌截图、lightbox 放大、截图为主文字为辅）**直接上传，不再转 PDF**——交付时须附「下载后双击打开」三步说明。
 ---
 
-# 创建文档（MD 直传 / HTML→PDF → 私有文档仓库）
+# 创建文档（MD 直传 / 截图版 HTML → 私有文档仓库）
 
-⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `create-doc`，按规范生成文档（MD 直传或 HTML→PDF→私有仓库）」然后严格按照以下步骤执行，不得跳过。**
+⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `create-doc`，按规范生成文档（MD 直传或截图版 HTML→私有仓库）」然后严格按照以下步骤执行，不得跳过。**
 
-生成符合项目规范的中文文档/报告。最终交付形式是 **私有文档仓库链接**（GitHub 内嵌渲染 PDF / Markdown，私有仓库仅团队成员登录可见）；代码仓库 `docs/` 只保留索引 `docs/index.html`，不存放文档正文。
+生成符合项目规范的中文文档/报告。最终交付形式是 **私有文档仓库链接**（`.md` GitHub 原生渲染；截图版 `.html` GitHub 只显示源码，需下载后本地双击打开，私有仓库仅团队成员登录可见）；代码仓库 `docs/` 只保留索引 `docs/index.html`，不存放文档正文。
 
 ## 第一步：格式选型（能 MD 就 MD）
 
 - ⚠️ **判断这份文档是否需要「截图为主、文字为辅」**：
   - **纯文字/表格类**（需求说明、操作指南、设计文档、接口文档、方案总结等）→ **MD 直传**：直接写 `.md` 文件，GitHub 原生渲染，零转换步骤。走下方「MD 直传」流程。
-  - **截图版报告**（验证报告、需要内嵌截图+箭头标注的可视化文档）→ **HTML→PDF**：走下方「HTML 转 PDF」流程。GitHub blob 视图对 HTML 显示源码不渲染，必须转 PDF 才能点开即看。
-- 用户明确要求「生成 html / 截图版」的，直接走 HTML→PDF，不必再问格式。
+  - **截图版报告**（验证报告、需要内嵌截图+箭头标注的可视化文档）→ **截图版 HTML**：走下方「HTML 交付（不再转 PDF）」流程。**不再转 PDF**——理由：少一道无头 Chrome 转换（大报告转换慢，分页还会把表格与截图拦腰切断、页数虚增），且 HTML 下载后可全文搜索、可复制文字、链接可点、图片可放大。
+- 用户明确要求「生成 html / 截图版」的，直接走截图版 HTML，不必再问格式。
 
 ## 交付流程总览
 
@@ -34,12 +34,11 @@ description: >-
   2. push MD 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支
   3. 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」
   4. 交付给用户：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.md` 链接 + 一行内容说明
-- **HTML→PDF 路径**：
-  1. 按下方「文档规范」生成 HTML 文档（**中间产物**，中文文件名）
-  2. 用无头 Chrome 将 HTML 转成 PDF
-  3. push PDF 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支
-  4. 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」
-  5. 交付给用户：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 链接 + 一行内容说明
+- **截图版 HTML 路径**：
+  1. 按下方「文档规范」生成自包含 HTML 文档（中文文件名、截图 `data:image/png;base64` 内嵌）
+  2. push HTML 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支（**不再转 PDF**）
+  3. 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」
+  4. 交付给用户：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html` 链接 + 一行内容说明 + **「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**
 
 ## 确定文档仓库（从 git remote 推导）
 
@@ -54,48 +53,43 @@ description: >-
 
 ## MD 直传
 
-- 纯文字/表格类文档（格式选型判断为 MD 的）：直接写 `.md` 文件，**跳过 HTML 生成与 PDF 转换**，直传私有文档仓库。
+- 纯文字/表格类文档（格式选型判断为 MD 的）：直接写 `.md` 文件，**跳过 HTML 生成**，直传私有文档仓库。
 - 交付文件名：中文命名（如 `模型分时段定价需求文档.md`）。
 - 上传方式与「push 到文档仓库」章节一致（clone → docs 分支 → 放入 MD → commit → push）。
 - ⚠️ MD 中需要展示截图/图片的，用相对路径引用并同时上传图片到 `assets/` 目录（或按 GitHub Markdown 内嵌方式处理），禁止引用外部链接。
 
-## HTML 转 PDF
+## HTML 交付（不再转 PDF）
 
-- HTML 生成后存到本地临时目录（如 `screenshots/` 同级或 `/tmp`），用无头 Chrome 转换：
-  ```bash
-  CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
-  "$CHROME" --headless=new --disable-gpu --no-sandbox \
-    --print-to-pdf="/tmp/<日期>-<文档名>.pdf" \
-    --no-pdf-header-footer \
-    "file://$(pwd)/<HTML相对路径>"
-  ```
-  > 无头 Chrome 偶发 `task_policy_set ... invalid argument` 输出属 macOS 良性噪声，可忽略。
-- ⚠️ 转换后必须抽查 PDF 内容完整（如 `sips -s format png <pdf> --out /tmp/check.png` 渲染首页确认），禁止直接交付未验证的 PDF。
+- HTML 生成后**直接交付，不做任何格式转换**（不再走无头 Chrome 转 PDF）。
+- ⚠️ 交付前必须**实际打开这份 HTML 抽查内容完整**（浏览器打开或截图确认首屏正常、截图不裂、箭头标注在位），禁止交付未验证的文件。
+- ⚠️ **必须确认文件是自包含的**：所有截图均为 `data:image/png;base64` 内嵌，无任何外部图片/样式依赖——对方下载单个 `.html` 文件、脱离原目录双击也能完整显示（这是「下载后打开」这条路能成立的前提）。
+- ⚠️ **交付话术必须带三步操作说明**（否则对方看到源码会以为链接坏了）：GitHub 对 `.html` 任何链接形式都不渲染（blob 显示源码；`raw.githubusercontent.com` 与 `/raw/` 均以 `content-type: text/plain` 返回）。固定话术：**点链接 → 点页面右上角「Download raw file」下载 → 双击下载下来的 `.html` 打开**（若浏览器直接把源码文本打开了，改用 ⌘S / Ctrl+S 另存为 `.html` 再双击）。
 
 ## push 到文档仓库
 
 - ⚠️ PomexAITeam 组织规则要求默认分支必须走 PR，禁止直推 main；**统一推送到非默认 `docs` 分支**（直推不受限）。
-- 临时 clone 文档仓库 → 切到 `docs` 分支 → 放入 PDF → commit → push：
+- 临时 clone 文档仓库 → 切到 `docs` 分支 → 放入 HTML → commit → push：
   ```bash
   TMP=$(mktemp -d)
   git clone git@github.com:PomexAITeam/pomexai-docs.git "$TMP"
   cd "$TMP" || exit 1
   git checkout -b docs 2>/dev/null || git checkout docs
-  cp /tmp/<日期>-<文档名>.pdf .
+  cp /tmp/<日期>-<文档名>.html .
   git add .
   git commit -m "docs: 新增 <文档名>"
   git push origin docs
   cd - >/dev/null 2>&1
   rm -rf "$TMP"
   ```
-- PDF 文件名：`<日期>-<文档中文名>.pdf`（如 `2026-08-31-模型模块化补测验证报告.pdf`），**每次新增独立文件，禁止覆盖旧文档**。
+- ⚠️ **文档仓库多为大文件仓库（PDF/HTML 动辄数 MB），clone 可能极慢甚至卡死**：优先用免 clone 推送方式——`git clone --filter=blob:none --sparse` 拉空工作区 → `git update-index --add --cacheinfo 100644,<新 blob SHA>,<文件名>` 直接把新文件挂进索引 → commit → push（避免 fetch 历史大文件）。
+- HTML 文件名：`<日期>-<文档中文名>.html`（如 `2026-08-31-模型模块化补测验证报告.html`），**每次新增独立文件，禁止覆盖旧文档**。
 - 若 remote 不是 `git@github.com:...` 形态，用实际 remote URL 替换 clone 地址。
 
 ## 记录索引（代码仓库 docs/index.html）
 
 - 更新代码仓库 `docs/index.html`（HTML 表格索引，链接一律 `target="_blank" rel="noopener"` 新标签页打开），按现有 index.html 结构在表格追加一行「文档名 | 链接」，示例：
   ```html
-  <tr><td class="doc">文档名</td><td class="link"><a target="_blank" rel="noopener" href="https://github.com/PomexAITeam/pomexai-docs/blob/docs/<文件名>.pdf">文件名.pdf<span class="badge pdf">PDF</span></a></td></tr>
+  <tr><td class="doc">文档名</td><td class="link"><a target="_blank" rel="noopener" href="https://github.com/PomexAITeam/pomexai-docs/blob/docs/<文件名>.html">文件名.html<span class="badge html">HTML</span></a></td></tr>
   ```
 - ⚠️ `docs/index.html` 是新标签页打开链接的 HTML 索引；GitHub 上点开会显示源码，下载后双击即可在浏览器查看渲染效果。
 - 索引随代码正常提交（feature 分支 → PR），这是代码仓库 `docs/` 里唯一的内容。
@@ -103,12 +97,13 @@ description: >-
 ## 交付给用户
 
 - 交付时给出**可点击的 GitHub 链接** + 一行内容说明。禁止用相对路径（`docs/xxx.html`）、`file:///` 或本地 HTTP 服务（不起服务、不占端口）。
+- ⚠️ **交付 `.html` 时必须同时给出「怎么打开」的三步说明**：**点链接 → 点页面右上角「Download raw file」下载 → 双击下载下来的 `.html` 打开**（若浏览器直接把源码文本打开了，改用 ⌘S / Ctrl+S 另存为 `.html` 再双击）。**只甩一个链接不说怎么打开 = 对方看到一屏源码，会以为链接坏了。**
 
 ## 文档规范（HTML 生成）
 
 ### 格式要求
 
-- HTML 是中间产物，生成后用于转 PDF；文件名一律中文命名（如 `模型xxx.html`）
+- HTML 是**最终交付产物**（不再转 PDF）；文件名一律中文命名（如 `模型xxx.html`）
 - 标题、正文、章节、说明文字全部中文；代码、命令、专有名词、接口字段可保留英文
 
 ### 可视化优先

package/skills/create-pr/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   「提PR」「提个PR」「提一个PR」「提交PR」「创建PR」「发起PR」「开PR」「开个PR」「搞个PR」「弄个PR」「弄一个PR」「来一个PR」「帮我PR」「帮我提PR」「帮我提交PR」「帮我创建PR」「帮我开PR」「帮我弄PR」「帮我搞PR」「创建pull request」「提交pull request」「发起pull request」「新建PR」「新建pull request」「生成PR」「生成pull request」「做PR」「做个PR」「做一下PR」「做下PR」「整PR」「整个PR」「整一个PR」「出PR」「出个PR」「出一个PR」「搞PR」「来PR」「上PR」「上一下PR」「帮我上PR」。
   任何包含「PR」「Pull Request」「pull request」且表达创建/提交/发起语义的说法都应触发。
   以及：「把这个提交一下」「把这个提了」「提上去」「提交上去」「推到远程」「推到仓库」「发到仓库」「合到主线」「合入主线」「合并到main」「合并到master」「合并请求」「创建合并请求」「发起合并请求」「帮我合一下」「帮我合并」「帮我合了」「把这个合了」「合一下」「合了」。
-  自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中，并在 Description 顶部附截图版 HTML→PDF「详细实现文档」醒目链接（PR 正文快速浏览、链接展开每一步细节）。
+  自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中，并在 Description 顶部附截图版 HTML「详细实现文档」醒目链接（PR 正文快速浏览、链接展开每一步细节）。
 ---
 
 # 创建 Pull Request
@@ -102,19 +102,21 @@ Closes #issue编号
 - ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
 - ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。
 
-### 5. 制作详细实现文档（截图版 HTML→PDF）并置顶到 Description
+### 5. 制作详细实现文档（截图版 HTML）并置顶到 Description
 
-⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 PDF 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
+⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 HTML 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
 
 1. **汇总素材**：本 PR 的「改了什么 + 为什么改 + 每一步怎么改/怎么验证」，以及步骤 4 产出的全部效果截图（含修复前后对比）。
    - ⚠️ **修 bug / 修故障的 PR，文档必须额外覆盖第四部分「复现步骤」**（依据「⚠️ 缺陷复现铁律」）：把复现时按步骤拍下的截图按编号排开，**每一步一张图 + 箭头标注出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于亲手复现了一次。⚠️ **纯后端 / 无界面的 bug 也要可视化**：每一步的 curl 请求与响应渲染成暗色终端风格截图（带请求 ID、时间戳），坏现象那一步单独放大标注。⚠️ 这些截图必须是**改代码之前**复现时当场存下来的，不是改完之后回头补的（改完代码变了，补出来的不是复现）。禁止只在 PR 描述里贴一段文字步骤就算交差。
    - ⚠️ **素材取材优先级：前端可视化优先，纯逻辑才退而用代码/接口图**：讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明**——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
-2. **生成截图版 HTML → 转 PDF**：走 `/create-doc` skill 输出自包含 HTML——截图一律 `data:image/png;base64` 内嵌并自动加箭头标注（遵循「⚠️ 截图规范」「⚠️ HTML 文档截图与 curl 命令规范」），图文逐步说明每一步怎么做的；再经无头 Chrome 转 PDF。
-3. **托管到私有文档仓库**：push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支（仓库名从 git remote 推导：`git@github.com:<ORG>/<项目>.git` → 文档仓库 `<ORG>/<项目>-docs`），文件名用与 PR 主题相关的英文短名。
-4. **拿链接**：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。
-5. **拼到 Description 顶部**：把链接作为 Description **第一条、独占一行、加粗高亮**，放在任何正文段落之前：
+2. **生成截图版 HTML**：走 `/create-doc` skill 输出自包含 HTML——截图一律 `data:image/png;base64` 内嵌并自动加箭头标注（遵循「⚠️ 截图规范」「⚠️ HTML 文档截图与 curl 命令规范」），图文逐步说明每一步怎么做的。**HTML 就是最终交付格式，不再转 PDF**（转换慢、分页会切断表格与截图；HTML 可全文搜索、可复制文字、链接可点、图片可放大）。
+3. **托管到私有文档仓库**：push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支（仓库名从 git remote 推导：`git@github.com:<ORG>/<项目>.git` → 文档仓库 `<ORG>/<项目>-docs`），文件名用中文短名（与 `/create-doc` 命名保持一致）。
+4. **拿链接**：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html`（**GitHub 对 `.html` 任何链接形式都只显示源码、不渲染**——这是必须附下载指引的原因；私有仓库未登录会跳登录页）。
+5. **拼到 Description 顶部**：把链接作为 Description **第一条、独占一行、加粗高亮**，放在任何正文段落之前，**并紧跟着给出「怎么打开」的说明**（缺了它 reviewer 点开会看到一屏源码、以为链接坏了）：
    ```
-   📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)
+   📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)
+
+   > ⬆️ 点开后请点页面右上角「Download raw file」下载，双击下载的 `.html` 打开（GitHub 对 HTML 只显示源码，不渲染）。
    ```
    reviewer 建议以新标签页打开，看完细节再回 PR 正文。
 
@@ -151,9 +153,9 @@ gh pr create \
 4. **重新部署到测试环境**：循环 review 走完后，自动触发 `/deploy-test` skill，把最新代码重新部署到测试环境，确保测试的是循环 review 之后的最终代码。
 5. **测试环境验证 + 全程截图标注**：在测试环境用真实数据、真实页面交互测试本次改动（遵循「⚠️ 页面功能验证铁律」「⚠️ 用户视角测试铁律」）。测试过程中每一步都截图保留（遵循「⚠️ 截图规范」：真实视口 + `fullPage` 全页、URL 可见、存盘到 `docs/` 对应子目录），并在每张截图上用**坐标换算后的箭头标注**（走 `/screenshot-annotate` skill）关键改动区域/验证点，让看的人一眼看懂这张图证明了什么。⚠️ **命中链路验收触发条件的，本步即「阶段 2 链路验收」**：按 `/real-chain-verify` 走完整取证与 6 段报告，并**回填 PR 描述里的「跨系统链路验收」栏目**（阶段 1 的链路图 + 下游真实生效证据 + 默认值对照）。
 6. **确认没问题才算完成**：测试通过、截图与箭头标注齐全、功能符合预期，才算真正完成。禁止测试没跑、截图没标注就宣称完成。
-7. **发新版本**：确认没问题后，回到下方步骤 8 完成冲突检查与静态编译检查，PR 合并后执行根目录 `./release.sh` 发新版本。
+7. **交付测试环境**：确认没问题后，回到下方步骤 8 完成冲突检查与静态编译检查，PR 合并后把最新代码交付到**测试环境**（走 `/deploy-test` skill）。⚠️ **交付终点就是测试环境，不发布生产**。
 
-### 8. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 发版本）
+### 8. 每次修改 PR 后收尾检查（冲突 + 静态编译 + 交付测试环境）
 
 ⚠️ 创建 PR 后、以及每次 push 新提交/响应 review 意见重新推送后，三步收尾缺一不可，禁止改完 PR 就直接抛给 reviewer 或当作完事。
 
@@ -173,9 +175,9 @@ gh pr checks <PR>
 - 存在失败项：定位失败根因 → 修改代码 → 重新推送，直到全部通过
 - 禁止把静态编译未通过的 PR 抛给 reviewer
 
-**③ 发新版本**：
-- PR 合并后按项目发布流程发布新版本
-- 本项目统一执行根目录 `./release.sh`（自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）
+**③ 交付测试环境**：
+- PR 合并后把最新代码交付到**测试环境**（走 `/deploy-test` skill）——**业务仓库的交付终点到此为止，不发布生产**
+- ⚠️ **`./release.sh` 只属于发版载体仓库**：仅当本仓库根目录**确实存在** `./release.sh`（如 `@routerhub/agent-rules` 包自身）时，才额外执行它（自动完成 patch 版本号 +1、更新 package.json、`git commit`/`push`、打 tag、`npm publish`）。**根目录没有该脚本 = 本仓库不是发版载体，禁止执行、也禁止推断出一个替代的发版动作**（呼应 AGENTS.base.md「⚠️ 环境配置禁止推断」）
 
 ## 重要规则
 
@@ -184,11 +186,11 @@ gh pr checks <PR>
 - ⚠️ 必须附截图作为可视化证据
 - ⚠️ **建 PR 前先做步骤 0 的规则在场自检**：规则文件里搜不到 `详细实现文档`，或当前分支规则版本落后远程默认分支 → 先升级规则再建 PR。规则陈旧是静默故障，不报错不等于没缺东西。
 - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
-- ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML→PDF，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节
+- ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节；**链接旁必须同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（GitHub 对 HTML 只显示源码，不说明对方会以为链接坏了）
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
-- ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 8）
-- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 7.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → **链路预演（命中跨系统链路验收触发条件时，在循环 review 之前先跑，只为尽早暴露需要大改的问题）** → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注，命中触发条件的走 `/real-chain-verify` 阶段 2）→ 确认没问题 → 发新版本，七步缺一不可，未走完不算完成
+- ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后交付测试环境（见步骤 8）
+- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 7.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → **链路预演（命中跨系统链路验收触发条件时，在循环 review 之前先跑，只为尽早暴露需要大改的问题）** → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注，命中触发条件的走 `/real-chain-verify` 阶段 2）→ 确认没问题 → 交付测试环境，七步缺一不可，未走完不算完成。⚠️ **交付终点是测试环境，不发布生产**；仅当本仓库根目录确实存在 `./release.sh`（发版载体仓库，如 `@routerhub/agent-rules` 包自身）时才额外执行它发版。
 - ⚠️ **PR 描述里必须填「跨系统链路验收」栏目**（PR 模板已内置）：命中 4 条触发条件的填链路预演链路图 + 下游真实生效证据 + 默认值对照；未命中的勾选豁免项。**留痕是给 reviewer 看的——不填等于这一环做了也没人知道。**
 - ⚠️ **PR 描述里必须填「缺陷复现」栏目**（PR 模板已内置）：修 bug / 修故障的 PR 必须填**改动前**的复现证据（环境版本 → 可重演步骤 → 坏现象 + 可复查标识）与「同一套步骤复验后坏现象消失」；非修 bug 的勾选豁免项。⚠️ **复现的交付物是「逐步截图 + 箭头标注」的可视化走查（放在详细实现文档的「复现步骤」一节），不是一串文字步骤**——文字说不清「点在哪、界面长什么样、坏现象在屏幕哪个位置」，看的人只能自己拼图。⚠️ **动手改代码之前就要先复现并当场存图**，改完再补的不算复现。见「⚠️ 缺陷复现铁律」。
 - ⚠️ **直接创建正式 PR（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review

package/skills/deploy-test/SKILL.md

@@ -132,13 +132,11 @@ git push origin test
 
 ### 6. 部署 test 分支
 
-按项目自己的部署方式执行（Cloud Run / 容器 / npm publish 等）。
+按项目自己的部署方式执行（Cloud Run / 容器 / 静态资源等）。
 
-### 7. 发新版本
+⚠️ **本 Skill 的终点就是「测试环境部署完成」，到此为止——不发布生产、不执行 `./release.sh`。** 业务仓库的交付终点是测试环境；`./release.sh` 是**发版载体仓库自己**的机制，只有根目录确实存在该脚本的仓库（如 `@routerhub/agent-rules` 包自身）才在它自己的发版流程里执行，**本 Skill 一律不碰**（呼应 AGENTS.base.md「⚠️ 环境配置禁止推断」：根目录没有这个脚本，禁止推断出一个替代的发版/生产部署动作）。
 
-按项目发版规则执行（如 `./release.sh`）。
-
-### 8. 切回原功能分支
+### 7. 切回原功能分支
 
 ```bash
 git checkout "$ORIGINAL_BRANCH"

package/skills/forensic-report/SKILL.md

@@ -227,7 +227,7 @@ SELECT provider_id, count(*) FROM provider_model_pricing
 
 | 场景 | 交付形式 |
 |---|---|
-| **走 PR 的改动** | 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML→PDF，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。**它是那份文档里的一节，不另起一份**——reviewer 点一个链接就该看到全部，不该在两个链接之间来回跳。走 `/create-doc` skill。 |
+| **走 PR 的改动** | 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。**它是那份文档里的一节，不另起一份**——reviewer 点一个链接就该看到全部，不该在两个链接之间来回跳。走 `/create-doc` skill。 |
 | **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果） | 直接给**桌面上的单文件 HTML 绝对路径**（如 `/Users/<me>/Desktop/<任务名>/xxx-取证报告.html`）。截图一律 `data:image/png;base64` 内嵌，双击即开、可搜索、转发不裂图。**不走私有仓库、不起本地 HTTP 服务、不用相对路径、不用 `file:///`。** |
 
 ⚠️ **两种形式都要求截图内嵌，禁止用文件路径引用外部 PNG**——文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全是裂图。

package/skills/pr-release-loop/SKILL.md

@@ -3,8 +3,10 @@ name: pr-release-loop
 description: >-
   PR 发布完整闭环（循环 review 之后的收尾，也是跨系统链路验收的「阶段 2」）——创建 PR 后按 AGENTS.base.md
   「⚠️ 创建完 PR 后自动走完整闭环流程」自动走完 链路预演 → 循环 review → 重新部署测试环境 → 测试环境复测 →
-  确认 → 发 PR 链接 → 发新版本。核心防线：**循环 review 走完后，必须重新部署到测试环境并复测，确认没问题之后
-  才能发链接/发版**——这是最容易漏掉的一环（review 会改代码，跳过复测=拿旧代码下结论）。
+  确认 → 发 PR 链接 → 交付测试环境。核心防线：**循环 review 走完后，必须重新部署到测试环境并复测，确认没问题之后
+  才能发链接/交付**——这是最容易漏掉的一环（review 会改代码，跳过复测=拿旧代码下结论）。
+  ⚠️ **交付终点是测试环境，不发布生产**：业务仓库不执行 `./release.sh`；仅发版载体仓库（根目录确实存在
+  `./release.sh`，如 `@routerhub/agent-rules` 包自身）才在最后一步额外执行它发版。
   复测环节命中「跨系统真实链路验收铁律」触发条件时，自动触发 `real-chain-verify` **阶段 2**（完整验收）验到下游，
   并回填 PR 描述里的「跨系统链路验收」栏目（页面全绿 ≠ 链路跑通）。阶段 1「链路预演」应在循环 review 之前已完成，
   没做则先补做。
@@ -34,8 +36,8 @@ description: >-
   7. ✅ 与主分支无冲突（`gh pr view <PR> --json mergeable -q .mergeable` = `MERGEABLE`）
   8. ✅ GitHub 静态编译通过（`gh pr checks <PR>` 无 `failure`）
   9. ✅ PR 链接已发送给用户
-  10. ✅ 发新版本（`./release.sh`）
-- ⚠️ **循环 review 走完后，显式输出「✅ 循环 review 完成，进入发布收尾闭环」，然后逐项执行下面第 2～8 步，禁止在循环 review 结束后直接发链接/发版。** 若发现某一步没做（典型：忘了重新部署、复测是旧数据），必须停下来补齐再继续，禁止把「漏掉的第 3/4 步」带进交付。
+  10. ✅ 最新代码已交付到测试环境（`/deploy-test`）——**交付终点到此为止**；仅当本仓库根目录确实存在 `./release.sh`（发版载体仓库，如 `@routerhub/agent-rules` 包自身）时，才额外执行 `./release.sh` 发版
+- ⚠️ **循环 review 走完后，显式输出「✅ 循环 review 完成，进入发布收尾闭环」，然后逐项执行下面第 2～8 步，禁止在循环 review 结束后直接发链接/交付。** 若发现某一步没做（典型：忘了重新部署、复测是旧数据），必须停下来补齐再继续，禁止把「漏掉的第 3/4 步」带进交付。
 
 ## 核心流程
 
@@ -93,7 +95,7 @@ git push origin "$(git branch --show-current)"
 
 ### 6. 冲突检查 + 静态编译检查（三步收尾）
 
-用 `gh pr view <PR> --json mergeable -q .mergeable` 检查冲突（`CONFLICTING` 必须先解决），用 `gh pr checks <PR>` 检查 CI（有 `failure` 必须修复重推）。两者都通过后才发链接/发版。
+用 `gh pr view <PR> --json mergeable -q .mergeable` 检查冲突（`CONFLICTING` 必须先解决），用 `gh pr checks <PR>` 检查 CI（有 `failure` 必须修复重推）。两者都通过后才发链接/交付。
 
 ### 7. 发 PR 链接给用户
 
@@ -101,17 +103,19 @@ git push origin "$(git branch --show-current)"
 gh pr view <PR> --json url -q .url
 ```
 
-一般按下流程：循环 review 全部通过 → 部署测试环境复测 → 确认后**先发 PR 链接，再发版**。
+一般按下流程：循环 review 全部通过 → 部署测试环境复测 → 确认后**先发 PR 链接，再交付测试环境**。
 
-### 8. 发新版本
+### 8. 交付测试环境（不是发版）
 
-PR 合并后按项目发布流程执行根目录 `./release.sh` 发新版本（自动完成 patch 号 +1、更新 `package.json`、`git commit`/`push`、打 tag、`npm publish`）。
+PR 合并后把最新代码交付到**测试环境**（走 `/deploy-test` skill）。⚠️ **业务仓库的交付终点就是测试环境，不发布生产**。
+
+⚠️ **`./release.sh` 只属于发版载体仓库**：仅当本仓库根目录**确实存在** `./release.sh`（如 `@routerhub/agent-rules` 包自身——它靠 npm publish 发版，下游仓库靠依赖升级拿到新规则）时，才在这一步额外执行它（自动完成 patch 号 +1、更新 `package.json`、`git commit`/`push`、打 tag、`npm publish`）。**根目录没有该脚本 = 本仓库不是发版载体，此步到此结束；禁止据此推断出「那大概是生产部署吧」再补一个替代动作**（呼应 AGENTS.base.md「⚠️ 环境配置禁止推断」）。
 
 ## 判断边界
 
-- ⚠️ **如果循环 review 走完但没有重新部署测试就发链接/发版 → 直接违背闭环，必须停下并报告缺失项**（你没说过「跳过复测」，这属于该做而没做）。
-- ⚠️ **用户明确说「不用部署测试」「跳过复测，直接发版」等显式指令** → 按用户指令执行，不必拦（但要在交付时说明「本次跳过了测试环境复测」）。
-- ⚠️ **纯文档/无逻辑改动（如只改 README）** → 可以跳过复测，但发链接/发版前仍要完成冲突+编译检查。
+- ⚠️ **如果循环 review 走完但没有重新部署测试就发链接/交付 → 直接违背闭环，必须停下并报告缺失项**（你没说过「跳过复测」，这属于该做而没做）。
+- ⚠️ **用户明确说「不用部署测试」「跳过复测，直接交付」等显式指令** → 按用户指令执行，不必拦（但要在交付时说明「本次跳过了测试环境复测」）。
+- ⚠️ **纯文档/无逻辑改动（如只改 README）** → 可以跳过复测，但发链接/交付前仍要完成冲突+编译检查。
 
 ## 相关
 

package/skills/visual-report/SKILL.md

@@ -49,7 +49,7 @@ description: >-
 
 ⚠️ **交付形式分两种，禁止一律套同一种**（详见 `forensic-report` skill「交付形式」一节）：
 
-- **走 PR 的改动** → 并入 PR 顶部那份「详细实现文档」（截图版 HTML→PDF，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。⚠️ **它不是另起一份报告，而是那份文档里的一节**——reviewer 点一个链接就该看到全部，不该在两个链接之间来回跳。用 `/create-doc` skill：生成 HTML → 转 PDF → push 到 `<项目>-docs` 的 `docs` 分支 → 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」。交付给用户的是一行可点击的 GitHub 链接（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`）。
+- **走 PR 的改动** → 并入 PR 顶部那份「详细实现文档」（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。⚠️ **它不是另起一份报告，而是那份文档里的一节**——reviewer 点一个链接就该看到全部，不该在两个链接之间来回跳。用 `/create-doc` skill：生成自包含 HTML（**不再转 PDF**）→ push 到 `<项目>-docs` 的 `docs` 分支 → 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」。交付给用户的是一行可点击的 GitHub 链接（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html`）**外加「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**——GitHub 对 `.html` 只显示源码不渲染，只甩链接不说怎么打开，对方会以为链接坏了。
 - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**，截图 `data:image/png;base64` 内嵌，双击即开、可搜索、转发不裂图。不走私有仓库、不起本地 HTTP 服务、不用相对路径、不用 `file:///`。
 - ⚠️ **两种形式都要求截图内嵌**，禁止用文件路径引用外部 PNG——文档会被移动、分享，外部路径一脱离原目录就全是裂图。散落的零散 PNG 应一并清理，只保留文档本身。
 - ⚠️ 代码仓库 `docs/` 只维护索引，禁止把报告正文（HTML/PDF/截图）直接放进 `docs/`。