@routerhub/agent-rules 1.5.224 → 1.5.225

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/AGENTS.base.md +19 -16
  2. package/CHANGELOG.md +12 -0
  3. package/PULL_REQUEST_TEMPLATE.md +7 -6
  4. package/package.json +1 -1
  5. package/rules/global.md +19 -16
  6. package/skills/create-doc/SKILL.md +3 -1
  7. package/skills/create-pr/SKILL.md +19 -22
  8. package/skills/forensic-report/SKILL.md +1 -1
  9. package/skills/visual-report/SKILL.md +1 -1
package/AGENTS.base.md CHANGED
@@ -147,7 +147,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
147
147
  - ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
148
148
  - ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
149
149
  - ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 bug 亲手复现了一次。
150
- - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
150
+ - ⚠️ **落点：PR 描述里的「缺陷复现」栏目下必须有「逐步截图走查」一节**（PR 模板已内置该栏目），按步骤编号排开截图 + 箭头标注；截图直接上传到 PR 描述编辑区自动转 CDN 内嵌（见 `/create-pr`）。**禁止只在 PR 里贴一段文字步骤就算交差，也禁止把走查甩到外部文档只留一个链接**——reviewer 多点一步就少一个人看（见「PR 核心要求 → PR 描述即完整交付」）。
151
151
  - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
152
152
  - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
153
153
  - ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
@@ -266,10 +266,12 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
266
266
  - **类比：报销单不能只写「我花了多少钱」，得把发票贴在你填的每一个数字旁边——审核的人对着发票核你填的数，而不是凭你的口头描述签字。**
267
267
  - ⚠️ **硬性要求（交付任何需求实现 / 修复验证 / 取证报告时逐条满足，缺一不算完成）：**
268
268
  1. **逐字引用需求原文**：从需求单（Jira / Notion / 需求文档）**原样摘录**，保留原文用词与标点，**禁止润色、提炼、转述**。原文有错别字 / 用词不统一（如「装填维度」实为「筛选维度」）也照抄，旁边用括号注明「此处逐字保留原文」——**改写会让读者无法确认你引的是不是他要的那句**。
269
- 2. **按句拆解，三列并排：「需求原文（逐字） / 我们的实现 / 截图证据」**——每句原文独占一行；中间列写明这句对应改了哪块代码 / 哪个页面；**最右列把对应的证据直接内嵌在同一行里**（能截图的一律放带箭头标注的截图，纯后端的放命令输出 / 关键数字），让「原话 ↔ 实现 ↔ 证据」横向对齐，读者一行一行对过去即可。禁止把多句原文压成一段再笼统配一句「已实现」；也禁止右列只写一句「证据见下图 3」把读者支使到别处去翻——**翻过去就断了「这句配这张图」的对应关系，等于没配。**
269
+ 2. **按句拆解，逐句成块：「需求原文 → 我们的实现 → 截图证据」紧挨着排**——每句原文独占一个块，用引用块起头（`> 需求原文…`），紧接一段「我们的实现」写明这句对应改了哪块代码 / 哪个页面，**再紧接内嵌证据**（能截图的一律放带箭头标注的截图，纯后端的放命令输出 / 关键数字）。三部分在同一屏内自上而下挨着排，读者一句一句对过去即可。**载体不同、形态不同，但「原话 ↔ 实现 ↔ 证据」的紧邻对应关系一致**：Markdown（PR 描述）用「引用块 + 段落 + 内嵌图」的纵向块（Markdown 表格塞大图会被压到看不清，不用表格做三列）；HTML 文档才用三列并排的横向表。禁止把多句原文压成一段再笼统配一句「已实现」；也禁止证据只写一句「见下图 3」把读者支使到别处去翻——**翻过去就断了「这句配这张图」的对应关系，等于没配。**
270
270
  3. **原文之外我们额外做的必须单列并回连原文**：自研 / 顺带修的部分另起一张表（两列：「原文之外我们额外做的 / 它服务于原文的哪一句」），**逐条说明它服务于原文哪一句**。禁止让自研内容脱离原文独立成章——读者看不出它跟需求的关系，就会当成「夹带私货」或「跑偏了」。
271
271
  4. **原话出处给到可点链接**：需求单号 + URL 写在引用块头部（如 `MP-160 · https://.../browse/MP-160`），让读者能自己回去核对原话，而不是只能信你摘的这段。
272
- 5. **右列截图必须「点击即放大」**：三列排版下截图只占版心约 1/3 宽，缩略图仅够「对上号」，细节根本看不清——所以每张截图必须支持点击放大到全屏（lightbox 遮罩层：点图 → 半透明黑底居中大图 → ESC / 点背景关闭）。**这是硬要求，不是加分项**：放不大 = 读者拿到一张看不清的图 = 证据链断在最后一步。
272
+ 5. **截图必须「点击即放大」**：证据图无论排多宽，缩略状态下都只够「对上号」，细节看不清——所以每张图必须能点开放大。**这是硬要求，不是加分项**：放不大 = 读者拿到一张看不清的图 = 证据链断在最后一步。
273
+ - **PR 描述（Markdown）**：GitHub 对正文内嵌图片自带点击放大，`![](CDN_URL)` 内嵌即满足，不需要额外做任何事。
274
+ - **HTML 文档**：必须自带 lightbox 遮罩层（点图 → 半透明黑底居中大图 → ESC / 点背景关闭）——三列并排时截图只占版心约 1/3 宽，不放大根本看不了。
273
275
  - ⚠️ **禁止用 `<a href="data:image/png;base64,...">` 包一层冒充「可放大」**：主流浏览器（Chrome 60+ / Firefox 59+）为防钓鱼**拦截 data: URI 的顶层导航**，点了毫无反应——看着写了，实际等于没做。必须用内联 JS lightbox。
274
276
  - ⚠️ **lightbox 的 CSS 与 JS 必须内联写在文档里**：文档是离线双击打开的自包含单文件，引 CDN 一断网就失效。
275
277
  - **类比：把发票缩印在报销单那一行旁边是为了「对得上」，但缩印件看不清金额——所以还得能拿起来凑近看。给不了这个动作，缩印就只是个装饰。**
@@ -318,7 +320,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
318
320
  - ⚠️ **副作用范围上界表：每条 DELETE / 每次写操作，都要在报告里逐条列出「动什么 / 为什么在这里动 / 最多影响多少行」，且实测影响必须 ≤ 上界。** 这条把「⚠️ 数据库 DELETE 铁律」要求的那三个问题**从代码注释搬进报告**——注释只有写代码的人看得到，报告是给用户和 reviewer 看的。上界说不清、或实测超出上界的，直接视为本次改动未完成。
319
321
  - ⚠️ **操作链必须是「真人在真实界面里点出来的」，并在报告里逐步列明。** 禁止用脚本模拟、直接改数据库、调内部接口去造出「改动后」的状态——那不是「用户这么操作会发生什么」，而是「我造了一个我希望看到的结果」。报告里要能让读者看出每一步点的是哪个按钮、点完看到什么。
320
322
  - ⚠️ **交付形式跟随交付场景，禁止一律套同一种：**
321
- - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description，附「下载后双击打开」指引）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
323
+ - **走 PR 的改动** → 取证报告**直接平铺进 PR 描述**，作为其中一节（截图上传到描述编辑区、走 CDN 内嵌）。**禁止只放一个链接把细节甩到外部文档**——reviewer 打开 PR 就该看到全部，不该在链接之间来回跳、更不该还要先下载才能看（见「PR 核心要求 → PR 描述即完整交付」）。
322
324
  - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**（截图 `data:image/png;base64` 内嵌、双击即开、可搜索、转发不裂图），不走私有仓库、不起本地 HTTP 服务、不用相对路径。
323
325
  - ⚠️ **与相邻铁律的分工（四者是同一条路径在时间轴上不同位置各跑一次，不可互相替代）：** 「⚠️ 缺陷复现铁律」= 改之前证明问题存在；「⚠️ 修复验证铁律」= 改之后证明问题消失；「⚠️ 跨系统真实链路验收铁律」= 整条链路成不成立（下游接住了没有）；**本铁律 = 这次改动的副作用范围有没有失控（不该动的动了吗）**。前三条全过、本铁律不过的情况真实存在——功能修好了、链路跑通了、但目录数据被顺带删了。
324
326
  - ⚠️ **具体操作流程见 `/forensic-report` skill**（三层证据怎么拍、逐像素怎么相减、差异怎么归因、可复核导航怎么组织、报告骨架长什么样）。
@@ -371,16 +373,16 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
371
373
 
372
374
  ## PR 核心要求
373
375
 
374
- - ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `详细实现文档`（`grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条置顶链接规则自 `@routerhub/agent-rules` **v1.5.183** 起生效），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
376
+ - ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `PR 描述即完整交付`（`grep -l 'PR 描述即完整交付' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条内联交付规则自 `@routerhub/agent-rules` **v1.5.225** 起生效；**手里还搜得到 `详细实现文档` 的一定是旧规则**——那正是被本条替换掉的旧做法），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
375
377
  - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
376
378
  - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
377
- - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
378
- - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：
379
- - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的那份**截图版 HTML** 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 下载后打开即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
380
- - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)（点开后请点右上角「Download raw file」下载，双击下载的 HTML 打开）`。reviewer 建议在新标签页打开，看完细节再回正文。
381
- - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：生成自包含 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（内含本链接的制作与置顶步骤）。
382
- - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
383
- - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
379
+ - ⚠️ **PR 描述即完整交付：本次改动的全部信息必须平铺在 Description 正文里，禁止只放链接把 reviewer 支使到外部文档。** 逐步操作手册、箭头标注截图、复现走查、取证报告——全部内联进 Description（截图走 PR 描述编辑区直接上传、自动转 CDN，`![](CDN_URL)` 当即渲染成图）。**禁止再产出一份「详细实现文档」往外链**：那要 reviewer 多点好几步才能看到细节，而**多一分摩擦就少一个人看**；也禁止「正文只写摘要、细节见链接」的两层拆分——**打开一页就该看全**。
380
+ - **判断标准一句话**：reviewer 打开这个 PR 页面，本次改动的全部信息（做了什么 / 为什么这么做 / 每一步怎么改的 / 怎么验证的 / 全部证据）是不是都在这页上？**要跳到别处才算看全 = 没交付完。**
381
+ - **由来（2026-09 改为内联的真实原因，不要再「优化」回外链）**：此前要求把细节放进 `<项目>-docs` 私有仓库的截图版 HTML、Description 顶部挂链接。实测那条链路是「点链接 → GitHub 只显示 HTML 源码 → 点 Download raw file → 双击打开」共三步，**一个必须配「三步打开说明」才能看的东西，本身就在劝退**；而且正文与文档内容高度重复、要维护两处（改了一处忘另一处必然 drift，PR #203 就是正文与文档几乎同构）。私有仓库还有个隐性代价：**未登录的人连源码都看不到**。改为全量内联后，reviewer 打开即见，且只剩单一事实源。
382
+ - **量级与兜底**：GitHub 描述上限约 65,536 字符。实测团队常规报告体量（十余张截图 + 十余步逐步手册 + 取证说明）约 1 万字符，余量充足——**「正文装不下」在实践中不成立，不要拿它当外链的借口**。只有当内容**确实**超出承载（截图 > 80 张 / 字符逼近上限）时才拆出独立文档，此时：**必须用 Markdown**（GitHub 原生渲染、点开即看、图片内联，链接粘贴即读），**禁止用 HTML**（不渲染、又要下载）；且拆分后 PR 描述里仍要保留需求骨架与关键截图，链接只能作为「超出部分的续篇」，**不能倒过来变成「细节都在那边」**。
383
+ - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：描述里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
384
+ - **适用范围**：所有 PR 一律内联交付，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分，修 bug 的再加「复现走查」。
385
+ - ⚠️ **PR 建完后的第一个动作是自问「打开这一页，细节是不是全在上面」，不是就当场补进去**：⚠️ **细节还挂在外部文档、或正文只写了摘要的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文摘要写得很清楚」不构成豁免，内联是**必备件**而非可选优化。
384
386
  - ⚠️ PR Title / Description / Test Plan 全部中文。
385
387
  - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：
386
388
  - **全页图**：用浏览器真实视口（`window.innerWidth` 即截图宽度，4K 屏自然宽 3840）`fullPage` 截完整页面，禁止只截视口一屏。⚠️ **禁止强制把视口硬拉成 3840 宽**——浏览器视口宽由屏幕实际分辨率决定，硬拉宽会让内容按比例缩小（看不清），且与截图像素发生缩放错位，是标注不准的根因之一。若要更高清晰度，用 `set viewport <W> <H> 2`（DPR 倍率）提高渲染精度（CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
@@ -857,10 +859,11 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
857
859
 
858
860
  ## 文档规则
859
861
 
860
- - ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。
861
- - ⚠️ **交付截图版 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` 再双击）。**禁止只甩一个链接、不说怎么打开。**
862
+ - ⚠️ **PR 的交付面是 PR 描述本身，不是文档**：走 PR 的改动，全部细节（逐步手册 / 箭头标注截图 / 复现走查 / 取证报告）一律内联进 Description，**禁止再产出一份「详细实现文档」挂到 PR 上**（原因、由来与兜底见「PR 核心要求 → PR 描述即完整交付」）。本节余下规则适用于**独立文档**——需求说明、操作指南、独立报告、以及确实超过描述承载量时拆出的续篇。
863
+ - ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。⚠️ **例外：拆给 PR 作续篇的，一律用 Markdown 而非 HTML**（HTML 在 GitHub 上不渲染、又要下载，等于把已内联掉的那道摩擦又搬回来）。
864
+ - ⚠️ **交付「独立」截图版 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` 再双击）。**禁止只甩一个链接、不说怎么打开。**（本条只针对独立交付的 HTML 文档；PR 描述已全量内联，不存在这个环节。）
862
865
  - ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/index.html`**（`文档名 | 链接` 表格，链接一律 `target="_blank" rel="noopener"` 新标签页打开），**禁止在 `docs/` 存放文档正文**（HTML / PDF / MD / 截图 / 图片等大文件一律不提交进代码仓库）。
863
- - ⚠️ **文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
866
+ - ⚠️ **独立文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。⚠️ **该仓库的用途是独立文档，不再承担「PR 细节存放处」的角色**——PR 的细节在 PR 描述里，不要再往这里放一份然后挂链接。
864
867
  - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成自包含 HTML → 直接 push 到 `<项目>-docs` 私有仓库的 `docs` 分支（**不再转 PDF**）→ 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
865
868
  - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>`，粘贴到浏览器即可打开（`.md` GitHub 原生渲染；`.html` 显示源码，必须按上方三步说明下载后本地打开；私有仓库未登录会跳登录页）。
866
869
  - ⚠️ **迁移项目既有文档到 `<项目>-docs` 前，先区分「纯文档」与「代码资产 / 对外服务页面」，禁止一刀切全迁**：
@@ -871,7 +874,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
871
874
 
872
875
  ## 文档/文件链接交付
873
876
 
874
- - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。
877
+ - ⚠️ 给用户交付**独立文档**时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。（**PR 的交付面不适用本条**——PR 描述即完整交付，细节内联、不给外链，见「PR 核心要求」。）
875
878
  - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
876
879
  - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
877
880
  - ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。
package/CHANGELOG.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
4
4
 
5
+ ## [1.5.225] - 2026-09-18
6
+
7
+ ### Changed
8
+
9
+ - **PR 交付形态由「描述挂外链 + 独立截图版 HTML 文档」改为「PR 描述即完整交付」——所有细节平铺内联进 Description，取消外链文档**：起因是用户看完 PR #203 后提出「这份详细实现文档逐步操作手册 + 箭头标注，和 PR 描述里的内容好像重复了」。实测证实了这一点：该 PR 描述本身 9,751 字符（GitHub 上限 65,536 的 15%），里面**已经内联了 12 张 CDN 截图和完整的 12 步逐步手册**——独立文档不是补充，是重复。更关键的是打开成本：那条链路是「点链接 → GitHub 只显示 HTML 源码 → 点 Download raw file → 双击打开」共三步，**一个必须配「三步打开说明」才能看的东西，本身就在劝退**（用户原话：「其他人应该相对来说多操作几步会不那么愿意去看」）。私有仓库还有个隐性代价：**未登录的人连源码都看不到**。此外内容维护在两处，改了一处忘另一处必然 drift。
10
+ - **新判据（一句话）**：reviewer 打开这个 PR 页面，本次改动的全部信息（做了什么 / 为什么 / 每一步怎么做的 / 怎么验证的 / 全部证据）是不是都在这页上？**要跳到别处才算看全 = 没交付完。**
11
+ - **量级实测与兜底**：GitHub 描述上限约 65,536 字符，团队常规报告体量约 1 万字符，余量充足——**「正文装不下」在实践中不成立**。只有确实超出承载（截图 > 80 张 / 字符逼近上限）时才拆续篇，且**必须用 Markdown**（GitHub 原生渲染、点开即看），**禁止用 HTML**（不渲染、又要下载）。
12
+ - **⚠️ 版本闸门 token 必须同步替换（漏改则闸门静默失效）**：`create-pr` 步骤 0 的「规则在场自检」原本靠 `grep '详细实现文档'` 判断手里的规则集新旧。本次一并换成 `PR 描述即完整交付`（`AGENTS.base.md` L376 + `skills/create-pr/SKILL.md` 步骤 0），并**加了反向确认**——规则文件里仍能搜到 `详细实现文档` 即判为旧规则、强制先升级。不改 token 的话，下游仓库拿着旧规则建 PR 时闸门会照常"通过"、静默放行。
13
+ - **`AGENTS.base.md` 同步改动落点**：① PR 核心要求——「每个 PR 的 Description 最顶部必须放一条醒目的详细实现文档链接」整条重写为「PR 描述即完整交付」；② 缺陷复现铁律——复现走查的落点由「详细实现文档的复现步骤一节」改为「PR 描述『缺陷复现』栏目下的逐步截图走查」；③ 报告以需求原话为骨架铁律——由「三列并排」改为「逐句成块」（Markdown 表格塞大图会被压到看不清，PR 描述用「引用块 + 段落 + 内嵌图」的纵向块，三列并排只留给独立 HTML 文档）；④ 同节第 5 条 lightbox——拆成「PR 描述用 GitHub 自带点击放大，无需额外做」与「独立 HTML 文档才需自带 lightbox」；⑤ 取证报告铁律交付形式——走 PR 的改为直接平铺进描述；⑥ 文档规则 / 文档链接交付——明确 `<项目>-docs` 私有仓库降级为「只放独立文档」，不再承担「PR 细节存放处」的角色；⑦ 保留原有的「内容取材优先级（前端可视化优先）」要求，未改动。
14
+ - **skill 同步**：`create-pr` 步骤 5 由「制作截图版 HTML 并置顶 Description」整段重写为「把全部细节内联进 Description」（含 Markdown 纵向块排法、截图走描述编辑区上传取 CDN、GitHub 自带放大、量级与兜底）；`visual-report` / `forensic-report` 交付形式表中「走 PR 的改动」一行改为「直接平铺进 PR 描述」；`create-doc` 顶部加范围说明（只产出独立文档，PR 细节不生成文档）。
15
+ - **`.github/PULL_REQUEST_TEMPLATE.md`（源文件 `PULL_REQUEST_TEMPLATE.md`）同步**：「缺陷复现」栏目由「摘要 + 链接」改为「本栏目就是完整走查本身，截图直接内联」；「取证报告」栏目同样去掉外链说法；Checklist 增加「本次改动全部细节都在这页上，没有靠外链文档承载细节」一项。
16
+
5
17
  ## [1.5.221] - 2026-09-16
6
18
 
7
19
  ### Fixed
package/PULL_REQUEST_TEMPLATE.md CHANGED
@@ -12,14 +12,14 @@ Closes #
12
12
  <!-- 仅「修 bug / 修故障 / 修线上异常」的 PR 需要填（新增功能、重构、文案、依赖升级直接勾豁免项）。
13
13
  依据 AGENTS.base.md「⚠️ 缺陷复现铁律」：必须先复现、留证、写下来，再动手改。
14
14
  ⚠️ 复现必须在【改动前的代码】上做（线上/测试环境当前版本，或打补丁前的 commit），改完再补的「复现」不算。
15
- ⚠️ 本栏目是「摘要 + 链接」：完整的逐步截图走查放在 PR 顶部那份「详细实现文档」的「复现步骤」一节里。 -->
15
+ ⚠️ 本栏目就是完整走查本身：逐步截图 + 箭头标注直接内联在下方（截图拖拽到编辑区即转 CDN），禁止只写一串文字步骤、也禁止甩外链文档。 -->
16
16
 
17
17
  - [ ] 本次 PR **不是**修 bug（新增功能 / 重构 / 文案 / 依赖升级），无需缺陷复现
18
18
 
19
19
  **① 复现证据（改动前的代码上跑出来的）**
20
20
 
21
- - **逐步截图走查（必填）**：详细实现文档「复现步骤」一节 → `<链接>`
22
- - ⚠️ 必须**每一步一张截图 + 箭头标注**（标出「点哪里 / 填什么 / 坏现象在哪」），不是一串文字步骤；纯后端 bug 用暗色终端风格的请求响应截图。
21
+ - **逐步截图走查（必填，直接内联在下面）**：每一步一张图，按编号平铺开
22
+ - ⚠️ 必须**每一步一张截图 + 箭头标注**（标出「点哪里 / 填什么 / 坏现象在哪」），不是一串文字步骤；纯后端 bug 用暗色终端风格的请求响应截图。截图拖拽到本编辑区即自动转 CDN 内嵌，GitHub 自带点击放大。
23
23
  - **环境与版本**：<环境（生产/测试/本地） + commit 或 revision + 账号 / 数据 ID>
24
24
  - **操作步骤**（别人照着能一步步重演，禁止省略参数）：
25
25
  1.
@@ -64,8 +64,9 @@ Closes #
64
64
  ⚠️ 证据强度按改动类型自动分级（三层：动了数据本身 / 两层：普通业务逻辑 / 一层：纯文案样式）。
65
65
  ⚠️ 可复核导航一级都不可降级——它是所有级别必带项。
66
66
  ⚠️ 每条主张还必须自带「你自己怎么复核」的流程面板（AGENTS.base.md「⚠️ 主张自带复核流程铁律」），
67
- 就近嵌在三列表那一行正下方——只给结论、只给 A/B 截图，用户只会问「这个我咋验证呢？光看到你写的 A/B 对照了」。
68
- ⚠️ 本栏目是「摘要 + 链接」：完整报告并入 PR 顶部那份「详细实现文档」；不走 PR 的即时修复给桌面 HTML 绝对路径。 -->
67
+ 就近嵌在该条主张的正下方——只给结论、只给 A/B 截图，用户只会问「这个我咋验证呢？光看到你写的 A/B 对照了」。
68
+ ⚠️ 本栏目就是完整报告本身：直接内联在本栏目下方（Markdown 纵向块 + 内嵌截图），禁止甩外链文档；
69
+ 不走 PR 的即时修复则给桌面 HTML 绝对路径。 -->
69
70
 
70
71
  - [ ] 本次为**一层**改动（纯文案 / 纯样式 / 无数据变化），只需功能证据 + 可复核导航，无需三层取证
71
72
 
@@ -101,7 +102,7 @@ Closes #
101
102
  - [ ] 修 bug 的 PR 已按「缺陷复现」栏目写下改动前的复现证据（非修 bug 的已勾选豁免项）
102
103
  - [ ] 跨系统链路验收已按上方栏目填完（未命中触发条件则勾选豁免项）
103
104
  - [ ] 已按「取证报告」栏目给出取证数据（或勾选一层豁免项）
104
- - [ ] 详细实现文档里，**每条主张旁都挂了「你自己怎么复核」的流程面板**（可复制命令 + 对错两种预期结果 + 这一步证明了什么；就近嵌在三列表该行正下方）——只给结论 / 只给 A/B 截图 = 用户没法自己验证，等于没交付
105
+ - [ ] 本次改动**全部细节都在这页上**：逐步手册 / 箭头标注截图 / 复现走查 / 取证报告均已内联在描述正文，**没有靠外链文档承载细节**；其中**每条主张旁都挂了「你自己怎么复核」的流程面板**（可复制命令 + 对错两种预期结果 + 这一步证明了什么）——只给结论 / 只给 A/B 截图 = 用户没法自己验证，等于没交付
105
106
  - [ ] UI 改动已贴截图（或注明无界面变化）
106
107
  - [ ] 截图与证据取自测试环境（无截图 / 本地例外已注明原因），且每张图里都写了文字版完整 URL（不是只靠地址栏），该 URL 是别人能直接打开的地址（非 localhost）
107
108
  - [ ] 本地编译 / lint / 测试通过，CI 全绿
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.224",
3
+ "version": "1.5.225",
4
4
  "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
5
5
  "main": "AGENTS.base.md",
6
6
  "bin": {
package/rules/global.md CHANGED
@@ -147,7 +147,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
147
147
  - ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
148
148
  - ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
149
149
  - ⚠️ **复现的交付物必须是「逐步截图 + 箭头标注」的可视化文档，不能只是一串文字步骤。** 文字步骤只说得清「点了什么」，说不清「点在哪、界面长什么样、坏现象出现在屏幕哪个位置」——看的人得自己在心里拼图，拼错了就以为复现不出来，或者以为自己复现的是另一回事。正确做法：**每一步一张截图，图上用箭头 + 短标签标出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于把 bug 亲手复现了一次。
150
- - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
150
+ - ⚠️ **落点：PR 描述里的「缺陷复现」栏目下必须有「逐步截图走查」一节**（PR 模板已内置该栏目），按步骤编号排开截图 + 箭头标注；截图直接上传到 PR 描述编辑区自动转 CDN 内嵌（见 `/create-pr`）。**禁止只在 PR 里贴一段文字步骤就算交差，也禁止把走查甩到外部文档只留一个链接**——reviewer 多点一步就少一个人看（见「PR 核心要求 → PR 描述即完整交付」）。
151
151
  - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
152
152
  - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
153
153
  - ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
@@ -266,10 +266,12 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
266
266
  - **类比：报销单不能只写「我花了多少钱」，得把发票贴在你填的每一个数字旁边——审核的人对着发票核你填的数，而不是凭你的口头描述签字。**
267
267
  - ⚠️ **硬性要求（交付任何需求实现 / 修复验证 / 取证报告时逐条满足，缺一不算完成）：**
268
268
  1. **逐字引用需求原文**：从需求单（Jira / Notion / 需求文档）**原样摘录**，保留原文用词与标点，**禁止润色、提炼、转述**。原文有错别字 / 用词不统一（如「装填维度」实为「筛选维度」）也照抄，旁边用括号注明「此处逐字保留原文」——**改写会让读者无法确认你引的是不是他要的那句**。
269
- 2. **按句拆解，三列并排：「需求原文（逐字） / 我们的实现 / 截图证据」**——每句原文独占一行；中间列写明这句对应改了哪块代码 / 哪个页面；**最右列把对应的证据直接内嵌在同一行里**（能截图的一律放带箭头标注的截图，纯后端的放命令输出 / 关键数字），让「原话 ↔ 实现 ↔ 证据」横向对齐，读者一行一行对过去即可。禁止把多句原文压成一段再笼统配一句「已实现」；也禁止右列只写一句「证据见下图 3」把读者支使到别处去翻——**翻过去就断了「这句配这张图」的对应关系，等于没配。**
269
+ 2. **按句拆解，逐句成块：「需求原文 → 我们的实现 → 截图证据」紧挨着排**——每句原文独占一个块，用引用块起头（`> 需求原文…`），紧接一段「我们的实现」写明这句对应改了哪块代码 / 哪个页面，**再紧接内嵌证据**（能截图的一律放带箭头标注的截图，纯后端的放命令输出 / 关键数字）。三部分在同一屏内自上而下挨着排，读者一句一句对过去即可。**载体不同、形态不同，但「原话 ↔ 实现 ↔ 证据」的紧邻对应关系一致**：Markdown（PR 描述）用「引用块 + 段落 + 内嵌图」的纵向块（Markdown 表格塞大图会被压到看不清，不用表格做三列）；HTML 文档才用三列并排的横向表。禁止把多句原文压成一段再笼统配一句「已实现」；也禁止证据只写一句「见下图 3」把读者支使到别处去翻——**翻过去就断了「这句配这张图」的对应关系，等于没配。**
270
270
  3. **原文之外我们额外做的必须单列并回连原文**：自研 / 顺带修的部分另起一张表（两列：「原文之外我们额外做的 / 它服务于原文的哪一句」），**逐条说明它服务于原文哪一句**。禁止让自研内容脱离原文独立成章——读者看不出它跟需求的关系，就会当成「夹带私货」或「跑偏了」。
271
271
  4. **原话出处给到可点链接**：需求单号 + URL 写在引用块头部（如 `MP-160 · https://.../browse/MP-160`），让读者能自己回去核对原话，而不是只能信你摘的这段。
272
- 5. **右列截图必须「点击即放大」**：三列排版下截图只占版心约 1/3 宽，缩略图仅够「对上号」，细节根本看不清——所以每张截图必须支持点击放大到全屏（lightbox 遮罩层：点图 → 半透明黑底居中大图 → ESC / 点背景关闭）。**这是硬要求，不是加分项**：放不大 = 读者拿到一张看不清的图 = 证据链断在最后一步。
272
+ 5. **截图必须「点击即放大」**：证据图无论排多宽，缩略状态下都只够「对上号」，细节看不清——所以每张图必须能点开放大。**这是硬要求，不是加分项**：放不大 = 读者拿到一张看不清的图 = 证据链断在最后一步。
273
+ - **PR 描述（Markdown）**：GitHub 对正文内嵌图片自带点击放大，`![](CDN_URL)` 内嵌即满足，不需要额外做任何事。
274
+ - **HTML 文档**：必须自带 lightbox 遮罩层（点图 → 半透明黑底居中大图 → ESC / 点背景关闭）——三列并排时截图只占版心约 1/3 宽，不放大根本看不了。
273
275
  - ⚠️ **禁止用 `<a href="data:image/png;base64,...">` 包一层冒充「可放大」**：主流浏览器（Chrome 60+ / Firefox 59+）为防钓鱼**拦截 data: URI 的顶层导航**，点了毫无反应——看着写了，实际等于没做。必须用内联 JS lightbox。
274
276
  - ⚠️ **lightbox 的 CSS 与 JS 必须内联写在文档里**：文档是离线双击打开的自包含单文件，引 CDN 一断网就失效。
275
277
  - **类比：把发票缩印在报销单那一行旁边是为了「对得上」，但缩印件看不清金额——所以还得能拿起来凑近看。给不了这个动作，缩印就只是个装饰。**
@@ -318,7 +320,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
318
320
  - ⚠️ **副作用范围上界表：每条 DELETE / 每次写操作，都要在报告里逐条列出「动什么 / 为什么在这里动 / 最多影响多少行」，且实测影响必须 ≤ 上界。** 这条把「⚠️ 数据库 DELETE 铁律」要求的那三个问题**从代码注释搬进报告**——注释只有写代码的人看得到，报告是给用户和 reviewer 看的。上界说不清、或实测超出上界的，直接视为本次改动未完成。
319
321
  - ⚠️ **操作链必须是「真人在真实界面里点出来的」，并在报告里逐步列明。** 禁止用脚本模拟、直接改数据库、调内部接口去造出「改动后」的状态——那不是「用户这么操作会发生什么」，而是「我造了一个我希望看到的结果」。报告里要能让读者看出每一步点的是哪个按钮、点完看到什么。
320
322
  - ⚠️ **交付形式跟随交付场景，禁止一律套同一种：**
321
- - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description，附「下载后双击打开」指引）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
323
+ - **走 PR 的改动** → 取证报告**直接平铺进 PR 描述**，作为其中一节（截图上传到描述编辑区、走 CDN 内嵌）。**禁止只放一个链接把细节甩到外部文档**——reviewer 打开 PR 就该看到全部，不该在链接之间来回跳、更不该还要先下载才能看（见「PR 核心要求 → PR 描述即完整交付」）。
322
324
  - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**（截图 `data:image/png;base64` 内嵌、双击即开、可搜索、转发不裂图），不走私有仓库、不起本地 HTTP 服务、不用相对路径。
323
325
  - ⚠️ **与相邻铁律的分工（四者是同一条路径在时间轴上不同位置各跑一次，不可互相替代）：** 「⚠️ 缺陷复现铁律」= 改之前证明问题存在；「⚠️ 修复验证铁律」= 改之后证明问题消失；「⚠️ 跨系统真实链路验收铁律」= 整条链路成不成立（下游接住了没有）；**本铁律 = 这次改动的副作用范围有没有失控（不该动的动了吗）**。前三条全过、本铁律不过的情况真实存在——功能修好了、链路跑通了、但目录数据被顺带删了。
324
326
  - ⚠️ **具体操作流程见 `/forensic-report` skill**（三层证据怎么拍、逐像素怎么相减、差异怎么归因、可复核导航怎么组织、报告骨架长什么样）。
@@ -371,16 +373,16 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
371
373
 
372
374
  ## PR 核心要求
373
375
 
374
- - ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `详细实现文档`（`grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条置顶链接规则自 `@routerhub/agent-rules` **v1.5.183** 起生效），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
376
+ - ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `PR 描述即完整交付`（`grep -l 'PR 描述即完整交付' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条内联交付规则自 `@routerhub/agent-rules` **v1.5.225** 起生效；**手里还搜得到 `详细实现文档` 的一定是旧规则**——那正是被本条替换掉的旧做法），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
375
377
  - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
376
378
  - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
377
- - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
378
- - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：
379
- - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的那份**截图版 HTML** 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 下载后打开即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
380
- - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)（点开后请点右上角「Download raw file」下载，双击下载的 HTML 打开）`。reviewer 建议在新标签页打开，看完细节再回正文。
381
- - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：生成自包含 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（内含本链接的制作与置顶步骤）。
382
- - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
383
- - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
379
+ - ⚠️ **PR 描述即完整交付：本次改动的全部信息必须平铺在 Description 正文里，禁止只放链接把 reviewer 支使到外部文档。** 逐步操作手册、箭头标注截图、复现走查、取证报告——全部内联进 Description（截图走 PR 描述编辑区直接上传、自动转 CDN，`![](CDN_URL)` 当即渲染成图）。**禁止再产出一份「详细实现文档」往外链**：那要 reviewer 多点好几步才能看到细节，而**多一分摩擦就少一个人看**；也禁止「正文只写摘要、细节见链接」的两层拆分——**打开一页就该看全**。
380
+ - **判断标准一句话**：reviewer 打开这个 PR 页面，本次改动的全部信息（做了什么 / 为什么这么做 / 每一步怎么改的 / 怎么验证的 / 全部证据）是不是都在这页上？**要跳到别处才算看全 = 没交付完。**
381
+ - **由来（2026-09 改为内联的真实原因，不要再「优化」回外链）**：此前要求把细节放进 `<项目>-docs` 私有仓库的截图版 HTML、Description 顶部挂链接。实测那条链路是「点链接 → GitHub 只显示 HTML 源码 → 点 Download raw file → 双击打开」共三步，**一个必须配「三步打开说明」才能看的东西，本身就在劝退**；而且正文与文档内容高度重复、要维护两处（改了一处忘另一处必然 drift，PR #203 就是正文与文档几乎同构）。私有仓库还有个隐性代价：**未登录的人连源码都看不到**。改为全量内联后，reviewer 打开即见，且只剩单一事实源。
382
+ - **量级与兜底**：GitHub 描述上限约 65,536 字符。实测团队常规报告体量（十余张截图 + 十余步逐步手册 + 取证说明）约 1 万字符，余量充足——**「正文装不下」在实践中不成立，不要拿它当外链的借口**。只有当内容**确实**超出承载（截图 > 80 张 / 字符逼近上限）时才拆出独立文档，此时：**必须用 Markdown**（GitHub 原生渲染、点开即看、图片内联，链接粘贴即读），**禁止用 HTML**（不渲染、又要下载）；且拆分后 PR 描述里仍要保留需求骨架与关键截图，链接只能作为「超出部分的续篇」，**不能倒过来变成「细节都在那边」**。
383
+ - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：描述里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
384
+ - **适用范围**：所有 PR 一律内联交付，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分，修 bug 的再加「复现走查」。
385
+ - ⚠️ **PR 建完后的第一个动作是自问「打开这一页，细节是不是全在上面」，不是就当场补进去**：⚠️ **细节还挂在外部文档、或正文只写了摘要的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文摘要写得很清楚」不构成豁免，内联是**必备件**而非可选优化。
384
386
  - ⚠️ PR Title / Description / Test Plan 全部中文。
385
387
  - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：
386
388
  - **全页图**：用浏览器真实视口（`window.innerWidth` 即截图宽度，4K 屏自然宽 3840）`fullPage` 截完整页面，禁止只截视口一屏。⚠️ **禁止强制把视口硬拉成 3840 宽**——浏览器视口宽由屏幕实际分辨率决定，硬拉宽会让内容按比例缩小（看不清），且与截图像素发生缩放错位，是标注不准的根因之一。若要更高清晰度，用 `set viewport <W> <H> 2`（DPR 倍率）提高渲染精度（CSS 宽不变、像素更密），而不是拉宽 CSS 视口。
@@ -857,10 +859,11 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
857
859
 
858
860
  ## 文档规则
859
861
 
860
- - ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。
861
- - ⚠️ **交付截图版 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` 再双击）。**禁止只甩一个链接、不说怎么打开。**
862
+ - ⚠️ **PR 的交付面是 PR 描述本身，不是文档**：走 PR 的改动，全部细节（逐步手册 / 箭头标注截图 / 复现走查 / 取证报告）一律内联进 Description，**禁止再产出一份「详细实现文档」挂到 PR 上**（原因、由来与兜底见「PR 核心要求 → PR 描述即完整交付」）。本节余下规则适用于**独立文档**——需求说明、操作指南、独立报告、以及确实超过描述承载量时拆出的续篇。
863
+ - ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。⚠️ **例外：拆给 PR 作续篇的，一律用 Markdown 而非 HTML**（HTML 在 GitHub 上不渲染、又要下载，等于把已内联掉的那道摩擦又搬回来）。
864
+ - ⚠️ **交付「独立」截图版 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` 再双击）。**禁止只甩一个链接、不说怎么打开。**（本条只针对独立交付的 HTML 文档；PR 描述已全量内联，不存在这个环节。）
862
865
  - ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/index.html`**（`文档名 | 链接` 表格，链接一律 `target="_blank" rel="noopener"` 新标签页打开），**禁止在 `docs/` 存放文档正文**（HTML / PDF / MD / 截图 / 图片等大文件一律不提交进代码仓库）。
863
- - ⚠️ **文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
866
+ - ⚠️ **独立文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。⚠️ **该仓库的用途是独立文档，不再承担「PR 细节存放处」的角色**——PR 的细节在 PR 描述里，不要再往这里放一份然后挂链接。
864
867
  - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成自包含 HTML → 直接 push 到 `<项目>-docs` 私有仓库的 `docs` 分支（**不再转 PDF**）→ 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
865
868
  - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>`，粘贴到浏览器即可打开（`.md` GitHub 原生渲染；`.html` 显示源码，必须按上方三步说明下载后本地打开；私有仓库未登录会跳登录页）。
866
869
  - ⚠️ **迁移项目既有文档到 `<项目>-docs` 前，先区分「纯文档」与「代码资产 / 对外服务页面」，禁止一刀切全迁**：
@@ -871,7 +874,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
871
874
 
872
875
  ## 文档/文件链接交付
873
876
 
874
- - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。
877
+ - ⚠️ 给用户交付**独立文档**时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。（**PR 的交付面不适用本条**——PR 描述即完整交付，细节内联、不给外链，见「PR 核心要求」。）
875
878
  - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
876
879
  - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
877
880
  - ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。
package/skills/create-doc/SKILL.md CHANGED
@@ -11,7 +11,7 @@ description: >-
11
11
  「生成一个截图版的html」「生成截图版html」「生成一个截图版」「生成截图版」「截图版文档」「截图版报告」「截图版说明」「截图版的」等任何「截图版」表述。
12
12
  「生成一个html」「生成html」「生成一个html文档」「生成html文档」「写个html」「写html」「做一个html」「做个html」「出一个html」「出个html」「搞个html」「整个html」「弄个html」「html文档」「html报告」等任何明确要求生成 HTML 的表述。
13
13
  「html」单独说且上下文在讨论产出物时也应触发。
14
- 自动生成符合项目规范的中文文档，存入本项目私有文档仓库（<项目>-docs），在代码仓库 docs/index.html 索引记录「文档名 | 链接」。纯文字/表格类文档用 Markdown 直传（GitHub 原生渲染、零转换）；截图版报告用 HTML 格式（中文文件名、base64 内嵌截图、lightbox 放大、截图为主文字为辅）**直接上传，不再转 PDF**——交付时须附「下载后双击打开」三步说明。
14
+ 自动生成符合项目规范的中文文档，存入本项目私有文档仓库（<项目>-docs），在代码仓库 docs/index.html 索引记录「文档名 | 链接」。纯文字/表格类文档用 Markdown 直传（GitHub 原生渲染、零转换）；截图版报告用 HTML 格式（中文文件名、base64 内嵌截图、lightbox 放大、截图为主文字为辅）**直接上传，不再转 PDF**——交付时须附「下载后双击打开」三步说明。⚠️ 只用于**独立文档**；走 PR 的改动不生成文档，细节一律内联在 PR 描述里（见 AGENTS.base.md「PR 描述即完整交付」）。
15
15
  ---
16
16
 
17
17
  # 创建文档（MD 直传 / 截图版 HTML → 私有文档仓库）
@@ -29,6 +29,8 @@ description: >-
29
29
 
30
30
  ## 交付流程总览
31
31
 
32
+ ⚠️ **本 skill 只产出「独立文档」**（需求说明、操作指南、设计文档、独立报告）。⚠️ **走 PR 的改动不走这里**——PR 的逐步手册 / 箭头标注截图 / 复现走查 / 取证报告一律**内联在 PR 描述正文里**，不生成文档、不挂外链（原因与由来见 `AGENTS.base.md`「PR 核心要求 → PR 描述即完整交付」）；只有内容确实超出描述承载量（截图 > 80 张 / 字符逼近上限）时，才用本 skill 产出一份**Markdown**续篇。
33
+
32
34
  - **MD 直传路径**：
33
35
  1. 直接写 `.md` 文档（中文文件名）
34
36
  2. push MD 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支
package/skills/create-pr/SKILL.md CHANGED
@@ -5,7 +5,7 @@ description: >-
5
5
  「提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」。
6
6
  任何包含「PR」「Pull Request」「pull request」且表达创建/提交/发起语义的说法都应触发。
7
7
  以及：「把这个提交一下」「把这个提了」「提上去」「提交上去」「推到远程」「推到仓库」「发到仓库」「合到主线」「合入主线」「合并到main」「合并到master」「合并请求」「创建合并请求」「发起合并请求」「帮我合一下」「帮我合并」「帮我合了」「把这个合了」「合一下」「合了」。
8
- 自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中，并在 Description 顶部附截图版 HTML「详细实现文档」醒目链接（PR 正文快速浏览、链接展开每一步细节）。
8
+ 自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、把逐步操作手册 / 箭头标注截图 / 复现走查 / 取证报告**全部内联平铺进 Description 正文**（PR 描述即完整交付，不给外链文档）。
9
9
  ---
10
10
 
11
11
  # 创建 Pull Request
@@ -21,8 +21,8 @@ description: >-
21
21
  ⚠️ **建 PR 之前先跑一遍，确认手里的规则集不是旧的。** 旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。**
22
22
 
23
23
  ```bash
24
- # ① 铁律是否在场：三个规则文件里任意一个能搜到「详细实现文档」即通过
25
- grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md 2>/dev/null
24
+ # ① 铁律是否在场：三个规则文件里任意一个能搜到「PR 描述即完整交付」即通过
25
+ grep -l 'PR 描述即完整交付' CLAUDE.md AGENTS.md .github/copilot-instructions.md 2>/dev/null
26
26
 
27
27
  # ② 规则版本新鲜度：当前分支 vs 远程默认分支（默认分支名不写死，从 origin/HEAD 取）
28
28
  base=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)
@@ -33,8 +33,9 @@ echo "当前分支: ${cur:-未声明} / $base: ${ref:-未声明}"
33
33
 
34
34
  - ① 无输出（三个文件都搜不到），或 ② 当前分支版本落后于远程默认分支 → **中止，先升级规则再建 PR**：合并/变基远程默认分支后重装依赖（`pnpm install`），postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`。**发现落后要整批升级，不要只补这一条——陈旧时你手里少的不止这一条。**
35
35
  - 两边一致 → 通过，继续步骤 1。
36
+ - ⚠️ **顺带反向确认**：如果规则文件里还能搜到 `详细实现文档`，说明手里是被本条替换掉的旧做法，同样按陈旧处理，先升级。
36
37
 
37
- ⚠️ **本步骤的由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶「详细实现文档」链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 `@routerhub/agent-rules` v1.5.170**，而这条规则自 **v1.5.183** 起才生效，**比手里的规则集晚出生**——读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**一条铁律无法防止「这条铁律本身没被加载」**，所以必须用这一步主动去搜。
38
+ ⚠️ **本步骤的由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶交付链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 `@routerhub/agent-rules` v1.5.170**，而这条规则自 **v1.5.183** 起才生效，**比手里的规则集晚出生**——读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**一条铁律无法防止「这条铁律本身没被加载」**，所以必须用这一步主动去搜。（自 **v1.5.225** 起该规则已由「Description 置顶外链文档」改为「PR 描述即完整交付」——闸门 token 随之换成 `PR 描述即完整交付`，判据同步更新。）
38
39
 
39
40
  ### 1. 收集改动信息
40
41
 
@@ -102,25 +103,21 @@ Closes #issue编号
102
103
  - ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
103
104
  - ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。
104
105
 
105
- ### 5. 制作详细实现文档（截图版 HTML）并置顶到 Description
106
+ ### 5. 把全部细节内联进 Description（PR 描述即完整交付）
106
107
 
107
- ⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 HTML 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
108
+ ⚠️ **PR 描述就是唯一交付面：本次改动的全部信息必须平铺在 Description 正文里，禁止只放链接把 reviewer 支使到外部文档。** 逐步操作手册、箭头标注截图、复现走查、取证报告——全部内联（截图走描述编辑区直接上传、自动转 CDN，`![](CDN_URL)` 当即渲染成图）。**禁止再产出一份「详细实现文档」HTML 往外链**：那条链路要 reviewer 走「点链接 → 只看到 HTML 源码 → Download raw file → 双击打开」三步，**一个必须配三步说明才能看的东西本身就在劝退**；也禁止「正文只写摘要、细节见链接」的两层拆分。
108
109
 
109
110
  1. **汇总素材**：本 PR 的「改了什么 + 为什么改 + 每一步怎么改/怎么验证」，以及步骤 4 产出的全部效果截图（含修复前后对比）。
110
- - ⚠️ **修 bug / 修故障的 PR，文档必须额外覆盖第四部分「复现步骤」**（依据「⚠️ 缺陷复现铁律」）：把复现时按步骤拍下的截图按编号排开，**每一步一张图 + 箭头标注出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于亲手复现了一次。⚠️ **纯后端 / 无界面的 bug 也要可视化**：每一步的 curl 请求与响应渲染成暗色终端风格截图（带请求 ID、时间戳），坏现象那一步单独放大标注。⚠️ 这些截图必须是**改代码之前**复现时当场存下来的，不是改完之后回头补的（改完代码变了，补出来的不是复现）。禁止只在 PR 描述里贴一段文字步骤就算交差。
111
+ - ⚠️ **修 bug / 修故障的 PR，必须额外覆盖「复现走查」一节**（依据「⚠️ 缺陷复现铁律」）：把复现时按步骤拍下的截图按编号平铺开，**每一步一张图 + 箭头标注出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于亲手复现了一次。⚠️ **纯后端 / 无界面的 bug 也要可视化**：每一步的 curl 请求与响应渲染成暗色终端风格截图（带请求 ID、时间戳），坏现象那一步单独放大标注。⚠️ 这些截图必须是**改代码之前**复现时当场存下来的，不是改完之后回头补的（改完代码变了，补出来的不是复现）。禁止只在 PR 描述里贴一段文字步骤就算交差。
111
112
  - ⚠️ **素材取材优先级：前端可视化优先，纯逻辑才退而用代码/接口图**：讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明**——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
112
- 2. **生成截图版 HTML**：走 `/create-doc` skill 输出自包含 HTML——截图一律 `data:image/png;base64` 内嵌并自动加箭头标注（遵循「⚠️ 截图规范」「⚠️ HTML 文档截图与 curl 命令规范」），图文逐步说明每一步怎么做的。**HTML 就是最终交付格式，不再转 PDF**（转换慢、分页会切断表格与截图；HTML 可全文搜索、可复制文字、链接可点、图片可放大）。
113
- 3. **托管到私有文档仓库**：push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支（仓库名从 git remote 推导：`git@github.com:<ORG>/<项目>.git` → 文档仓库 `<ORG>/<项目>-docs`），文件名用中文短名（与 `/create-doc` 命名保持一致）。
114
- 4. **拿链接**：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html`（**GitHub 对 `.html` 任何链接形式都只显示源码、不渲染**——这是必须附下载指引的原因；私有仓库未登录会跳登录页）。
115
- 5. **拼到 Description 顶部**：把链接作为 Description **第一条、独占一行、加粗高亮**，放在任何正文段落之前，**并紧跟着给出「怎么打开」的说明**（缺了它 reviewer 点开会看到一屏源码、以为链接坏了）：
116
- ```
117
- 📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)
113
+ 2. **组织成 Description 正文**（Markdown，按 PR 模板栏目排）：需求原话骨架（逐句「原话 → 实现 → 证据」紧挨着排，见「⚠️ 报告以需求原话为骨架铁律」）→ 逐步操作手册 → 箭头标注截图 → 复现走查（修 bug 时）→ 取证报告（见「⚠️ 取证报告铁律」）。
114
+ - ⚠️ **Markdown 下用「纵向块」而非三列表格**：引用块写需求原文 → 紧接一段「我们的实现」→ 再紧接内嵌证据图。Markdown 表格会把大图压到看不清，**禁止用表格承载截图**。
115
+ - ⚠️ **每条主张旁就近挂「你自己怎么复核」的流程面板**（可复制命令 + 对错两种预期结果 + 这一步证明了什么），见「⚠️ 主张自带复核流程铁律」。
116
+ 3. **上传截图取 CDN URL**：走步骤 4 的 PR 描述编辑区上传（拖拽 / 粘贴 / 编辑区文件选择按钮）——GitHub 自动转 `https://github.com/user-attachments/assets/{uuid}` 并插入正文。**禁止走评论区 `input[type=file]` 上传再搬运 URL**（多一步、且临时图片评论留在对话里干扰阅读）。
117
+ 4. **点击即放大已自动满足**：GitHub 对正文内嵌图片自带点击放大，`![](CDN_URL)` 内嵌即可，**不需要额外做 lightbox**。
118
+ 5. **量级与兜底**：GitHub 描述上限约 65,536 字符；团队常规报告体量（十余张截图 + 十余步手册 + 取证说明）约 1 万字符，余量充足——**「正文装不下」不成立，不要拿它当外链的借口**。只有**确实**超出承载（截图 > 80 张 / 字符逼近上限）时才拆出续篇，且：**必须用 Markdown**（GitHub 原生渲染、点开即看），**禁止用 HTML**（不渲染、又要下载）；PR 描述里仍要保留需求骨架与关键截图，链接只能作为「超出部分的续篇」，**不能倒过来变成「细节都在那边」**。
118
119
 
119
- > ⬆️ 点开后请点页面右上角「Download raw file」下载，双击下载的 `.html` 打开（GitHub 对 HTML 只显示源码，不渲染）。
120
- ```
121
- reviewer 建议以新标签页打开，看完细节再回 PR 正文。
122
-
123
- **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。⚠️ **修 bug / 修故障的 PR 还必须有第四部分「复现步骤」**——逐步截图 + 箭头标注的复现走查（见上方第 1 点）。后续步骤 6 创建 PR 时，此链接已作为 body 第一条。
120
+ **适用范围**：所有 PR 一律内联交付，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。⚠️ **修 bug / 修故障的 PR 还必须有「复现走查」一节**——逐步截图 + 箭头标注（见上方第 1 点）。**建完 PR 后的第一个自检动作**：打开这一页，本次改动的全部信息是不是都在这页上？要跳到别处才算看全 = 还没交付完，当场补进来。
124
121
 
125
122
  ### 6. 创建 PR
126
123
 
@@ -184,14 +181,14 @@ gh pr checks <PR>
184
181
  - ⚠️ 一个 PR 只做一件事
185
182
  - ⚠️ PR 所有文字内容必须中文
186
183
  - ⚠️ 必须附截图作为可视化证据
187
- - ⚠️ **建 PR 前先做步骤 0 的规则在场自检**：规则文件里搜不到 `详细实现文档`，或当前分支规则版本落后远程默认分支 → 先升级规则再建 PR。规则陈旧是静默故障，不报错不等于没缺东西。
188
- - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
189
- - ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节；**链接旁必须同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（GitHub 对 HTML 只显示源码，不说明对方会以为链接坏了）
184
+ - ⚠️ **建 PR 前先做步骤 0 的规则在场自检**：规则文件里搜不到 `PR 描述即完整交付`，或当前分支规则版本落后远程默认分支 → 先升级规则再建 PR。规则陈旧是静默故障，不报错不等于没缺东西。
185
+ - ⚠️ **PR 建完后的第一个动作是自问「打开这一页，细节是不是全在上面」，不是就当场补进去**：⚠️ **细节还挂在外部文档、或正文只写了摘要的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文摘要写得很清楚」不构成豁免，内联是**必备件**而非可选优化。
186
+ - ⚠️ **PR 描述即完整交付（见步骤 5）**：本次改动的全部细节必须平铺在 Description 正文里——逐步手册、箭头标注截图、复现走查、取证报告全部内联；**禁止只放链接把 reviewer 支使到外部文档**，也禁止「正文只写摘要、细节见链接」。截图走描述编辑区上传转 CDN，GitHub 自带点击放大，无需额外 lightbox。
190
187
  - ⚠️ 截图禁止提交到 Git 仓库
191
188
  - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
192
189
  - ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后交付测试环境（见步骤 8）
193
190
  - ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 7.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → **链路预演（命中跨系统链路验收触发条件时，在循环 review 之前先跑，只为尽早暴露需要大改的问题）** → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注，命中触发条件的走 `/real-chain-verify` 阶段 2）→ 确认没问题 → 交付测试环境，七步缺一不可，未走完不算完成。⚠️ **交付终点是测试环境，不发布生产**；仅当本仓库根目录确实存在 `./release.sh`（发版载体仓库，如 `@routerhub/agent-rules` 包自身）时才额外执行它发版。
194
191
  - ⚠️ **PR 描述里必须填「跨系统链路验收」栏目**（PR 模板已内置）：命中 4 条触发条件的填链路预演链路图 + 下游真实生效证据 + 默认值对照；未命中的勾选豁免项。**留痕是给 reviewer 看的——不填等于这一环做了也没人知道。**
195
- - ⚠️ **PR 描述里必须填「缺陷复现」栏目**（PR 模板已内置）：修 bug / 修故障的 PR 必须填**改动前**的复现证据（环境版本 → 可重演步骤 → 坏现象 + 可复查标识）与「同一套步骤复验后坏现象消失」；非修 bug 的勾选豁免项。⚠️ **复现的交付物是「逐步截图 + 箭头标注」的可视化走查（放在详细实现文档的「复现步骤」一节），不是一串文字步骤**——文字说不清「点在哪、界面长什么样、坏现象在屏幕哪个位置」，看的人只能自己拼图。⚠️ **动手改代码之前就要先复现并当场存图**，改完再补的不算复现。见「⚠️ 缺陷复现铁律」。
192
+ - ⚠️ **PR 描述里必须填「缺陷复现」栏目**（PR 模板已内置）：修 bug / 修故障的 PR 必须填**改动前**的复现证据（环境版本 → 可重演步骤 → 坏现象 + 可复查标识）与「同一套步骤复验后坏现象消失」；非修 bug 的勾选豁免项。⚠️ **复现的交付物是「逐步截图 + 箭头标注」的可视化走查（平铺在 PR 描述的「缺陷复现」栏目下，见步骤 5），不是一串文字步骤**——文字说不清「点在哪、界面长什么样、坏现象在屏幕哪个位置」，看的人只能自己拼图。⚠️ **动手改代码之前就要先复现并当场存图**，改完再补的不算复现。见「⚠️ 缺陷复现铁律」。
196
193
  - ⚠️ **直接创建正式 PR（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review
197
194
  - 作者不能 Approve 自己的 PR
package/skills/forensic-report/SKILL.md CHANGED
@@ -271,7 +271,7 @@ SELECT provider_id, count(*) FROM provider_model_pricing
271
271
 
272
272
  | 场景 | 交付形式 |
273
273
  |---|---|
274
- | **走 PR 的改动** | 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。**它是那份文档里的一节，不另起一份**——reviewer 点一个链接就该看到全部，不该在两个链接之间来回跳。走 `/create-doc` skill。 |
274
+ | **走 PR 的改动** | 取证报告**直接平铺进 PR 描述**，作为其中一节（Markdown，截图走描述编辑区上传、自动转 CDN 内嵌）。**不另起一份文档、不挂外链**——reviewer 打开 PR 就该看到全部，不该多点一次跳到别处、更不该还要先下载才能看（原因与由来见「PR 核心要求 → PR 描述即完整交付」）。 |
275
275
  | **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果） | 直接给**桌面上的单文件 HTML 绝对路径**（如 `/Users/<me>/Desktop/<任务名>/xxx-取证报告.html`）。截图一律 `data:image/png;base64` 内嵌，双击即开、可搜索、转发不裂图。**不走私有仓库、不起本地 HTTP 服务、不用相对路径、不用 `file:///`。** |
276
276
 
277
277
  ⚠️ **两种形式都要求截图内嵌，禁止用文件路径引用外部 PNG**——文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全是裂图。
package/skills/visual-report/SKILL.md CHANGED
@@ -49,7 +49,7 @@ description: >-
49
49
 
50
50
  ⚠️ **交付形式分两种，禁止一律套同一种**（详见 `forensic-report` skill「交付形式」一节）：
51
51
 
52
- - **走 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` 只显示源码不渲染，只甩链接不说怎么打开，对方会以为链接坏了。
52
+ - **走 PR 的改动** → 可视化报告**直接平铺进 PR 描述**，作为其中一节（逐步操作手册 + 箭头标注截图全部内联，截图走 PR 描述编辑区上传、自动转 CDN）。⚠️ **不是另起一份文档挂链接**——reviewer 打开 PR 就该看到全部，不该多一点击跳到别处、更不该还要先下载才能看（原因与由来见「PR 核心要求 → PR 描述即完整交付」）。GitHub 对正文内嵌图片自带点击放大，无需额外 lightbox。
53
53
  - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**，截图 `data:image/png;base64` 内嵌，双击即开、可搜索、转发不裂图。不走私有仓库、不起本地 HTTP 服务、不用相对路径、不用 `file:///`。
54
54
  - ⚠️ **两种形式都要求截图内嵌**，禁止用文件路径引用外部 PNG——文档会被移动、分享，外部路径一脱离原目录就全是裂图。散落的零散 PNG 应一并清理，只保留文档本身。
55
55
  - ⚠️ 代码仓库 `docs/` 只维护索引，禁止把报告正文（HTML/PDF/截图）直接放进 `docs/`。