@routerhub/agent-rules 1.5.211 → 1.5.212

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 (7) hide show
  1. package/AGENTS.base.md +12 -11
  2. package/package.json +1 -1
  3. package/rules/global.md +12 -11
  4. package/skills/create-doc/SKILL.md +24 -29
  5. package/skills/create-pr/SKILL.md +11 -9
  6. package/skills/forensic-report/SKILL.md +1 -1
  7. 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→PDF，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
150
+ - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
151
151
  - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
152
152
  - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
153
153
  - ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
@@ -284,7 +284,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
284
284
  - ⚠️ **副作用范围上界表：每条 DELETE / 每次写操作，都要在报告里逐条列出「动什么 / 为什么在这里动 / 最多影响多少行」，且实测影响必须 ≤ 上界。** 这条把「⚠️ 数据库 DELETE 铁律」要求的那三个问题**从代码注释搬进报告**——注释只有写代码的人看得到，报告是给用户和 reviewer 看的。上界说不清、或实测超出上界的，直接视为本次改动未完成。
285
285
  - ⚠️ **操作链必须是「真人在真实界面里点出来的」，并在报告里逐步列明。** 禁止用脚本模拟、直接改数据库、调内部接口去造出「改动后」的状态——那不是「用户这么操作会发生什么」，而是「我造了一个我希望看到的结果」。报告里要能让读者看出每一步点的是哪个按钮、点完看到什么。
286
286
  - ⚠️ **交付形式跟随交付场景，禁止一律套同一种：**
287
- - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML→PDF，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
287
+ - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description，附「下载后双击打开」指引）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
288
288
  - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**（截图 `data:image/png;base64` 内嵌、双击即开、可搜索、转发不裂图），不走私有仓库、不起本地 HTTP 服务、不用相对路径。
289
289
  - ⚠️ **与相邻铁律的分工（四者是同一条路径在时间轴上不同位置各跑一次，不可互相替代）：** 「⚠️ 缺陷复现铁律」= 改之前证明问题存在；「⚠️ 修复验证铁律」= 改之后证明问题消失；「⚠️ 跨系统真实链路验收铁律」= 整条链路成不成立（下游接住了没有）；**本铁律 = 这次改动的副作用范围有没有失控（不该动的动了吗）**。前三条全过、本铁律不过的情况真实存在——功能修好了、链路跑通了、但目录数据被顺带删了。
290
290
  - ⚠️ **具体操作流程见 `/forensic-report` skill**（三层证据怎么拍、逐像素怎么相减、差异怎么归因、可复核导航怎么组织、报告骨架长什么样）。
@@ -340,10 +340,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
340
340
  - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
341
341
  - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
342
342
  - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
343
- - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
344
- - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
345
- - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
346
- - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
343
+ - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：
344
+ - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的那份**截图版 HTML** 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 下载后打开即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
345
+ - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)（点开后请点右上角「Download raw file」下载，双击下载的 HTML 打开）`。reviewer 建议在新标签页打开，看完细节再回正文。
346
+ - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：生成自包含 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（内含本链接的制作与置顶步骤）。
347
347
  - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
348
348
  - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
349
349
  - ⚠️ PR Title / Description / Test Plan 全部中文。
@@ -615,7 +615,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
615
615
 
616
616
  ### HTML 文档截图与 curl 命令规范
617
617
 
618
- - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有仓库 PDF 等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
618
+ - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有文档仓库等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
619
619
  - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
620
620
  - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
621
621
  - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
@@ -762,11 +762,12 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
762
762
 
763
763
  ## 文档规则
764
764
 
765
- - ⚠️ **文档格式选型：能 MD 就 MD，HTML→PDF 只用于截图版报告**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；只有验证报告/截图版报告等需要内嵌截图+箭头标注的可视化文档才用 HTML→PDF（GitHub blob 视图对 HTML 显示源码不渲染，转 PDF 才能点开即看）。**类比：写便签能说清的事就不要做成一整本画册——便签（MD）贴上墙人人直接看，画册（HTML）GitHub 这面墙只显示印刷源码，还得额外转成 PDF 才能翻。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → HTML→PDF；不需要 → MD 直传。
765
+ - ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。
766
+ - ⚠️ **交付截图版 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` 再双击）。**禁止只甩一个链接、不说怎么打开。**
766
767
  - ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/index.html`**（`文档名 | 链接` 表格，链接一律 `target="_blank" rel="noopener"` 新标签页打开），**禁止在 `docs/` 存放文档正文**（HTML / PDF / MD / 截图 / 图片等大文件一律不提交进代码仓库）。
767
768
  - ⚠️ **文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
768
- - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成 HTML → 无头 Chrome 转 PDF → push 到 `<项目>-docs` 私有仓库的 `docs` 分支 → 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
769
- - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<pdf|md>`，粘贴到浏览器即可查看（GitHub 内嵌渲染 PDF / Markdown；私有仓库未登录会跳登录页）。
769
+ - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成自包含 HTML → 直接 push 到 `<项目>-docs` 私有仓库的 `docs` 分支（**不再转 PDF**）→ 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
770
+ - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>`，粘贴到浏览器即可打开（`.md` GitHub 原生渲染；`.html` 显示源码，必须按上方三步说明下载后本地打开；私有仓库未登录会跳登录页）。
770
771
  - ⚠️ **迁移项目既有文档到 `<项目>-docs` 前，先区分「纯文档」与「代码资产 / 对外服务页面」，禁止一刀切全迁**：
771
772
  - **对外服务的 API 文档站**（gateway 类项目的 `docs/`：含 `index.html` + `authentication.html` + `css/` + `js/` + `nginx.conf.template` 的整套站点）是**线上产品页面**，随模型/接口持续更新（git log 常有「添加 xxx 模型」等提交），线上 URL 可访问（如 `https://xxx/docs` 返回 200）——这类**不能迁**，迁走线上直接 404。判断标准：线上有对应 URL 且能访问 → 是对外服务页面，不是内部文档。
772
773
  - **散落文档目录**（`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 +776,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
775
776
 
776
777
  ## 文档/文件链接交付
777
778
 
778
- - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` + 一行内容说明），这就是最终交付形式。
779
+ - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。
779
780
  - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
780
781
  - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
781
782
  - ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.211",
3
+ "version": "1.5.212",
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→PDF，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
150
+ - ⚠️ **落点：PR 顶部那份「详细实现文档」（截图版 HTML，见 `/create-pr` 步骤 5）里必须有「复现步骤」一节**，按步骤编号排开截图；PR 描述里的「缺陷复现」栏目放三要素摘要 + 指向该节的链接。**禁止只在 PR 里贴一段文字步骤就算交差。**
151
151
  - ⚠️ **纯后端 / 无界面的 bug（接口、定时任务、数据链路等）同样要可视化**：把每一步的 curl 请求与响应渲染成暗色终端风格截图（带上请求 ID、时间戳），坏现象那一步单独放大标注——而不是贴一段文字日志。（取证方式见「非 UI / 后端 / 基础设施改动的效果截图获取方法」）
152
152
  - ⚠️ **复现截图必须在「改代码之前」当场拍下并存盘**（遵循「⚠️ 截图规范」：浏览器真实视口、`fullPage` 全页、URL 可见、存到临时目录），不能等改完再写文档时回头补——那时代码已经变了，补出来的不是复现。箭头标注统一走 `/screenshot-annotate` skill（坐标由 `getBoundingClientRect()` 换算，禁止肉眼看图估位）。
153
153
  - ⚠️ **复现证据必须写进 PR（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能照着那份可视化文档自己重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
@@ -284,7 +284,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
284
284
  - ⚠️ **副作用范围上界表：每条 DELETE / 每次写操作，都要在报告里逐条列出「动什么 / 为什么在这里动 / 最多影响多少行」，且实测影响必须 ≤ 上界。** 这条把「⚠️ 数据库 DELETE 铁律」要求的那三个问题**从代码注释搬进报告**——注释只有写代码的人看得到，报告是给用户和 reviewer 看的。上界说不清、或实测超出上界的，直接视为本次改动未完成。
285
285
  - ⚠️ **操作链必须是「真人在真实界面里点出来的」，并在报告里逐步列明。** 禁止用脚本模拟、直接改数据库、调内部接口去造出「改动后」的状态——那不是「用户这么操作会发生什么」，而是「我造了一个我希望看到的结果」。报告里要能让读者看出每一步点的是哪个按钮、点完看到什么。
286
286
  - ⚠️ **交付形式跟随交付场景，禁止一律套同一种：**
287
- - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML→PDF，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
287
+ - **走 PR 的改动** → 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description，附「下载后双击打开」指引）。它是那份文档里的一节，**不另起一份**——reviewer 点一个链接就该看到全部，而不是在两个链接之间来回跳。
288
288
  - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**（截图 `data:image/png;base64` 内嵌、双击即开、可搜索、转发不裂图），不走私有仓库、不起本地 HTTP 服务、不用相对路径。
289
289
  - ⚠️ **与相邻铁律的分工（四者是同一条路径在时间轴上不同位置各跑一次，不可互相替代）：** 「⚠️ 缺陷复现铁律」= 改之前证明问题存在；「⚠️ 修复验证铁律」= 改之后证明问题消失；「⚠️ 跨系统真实链路验收铁律」= 整条链路成不成立（下游接住了没有）；**本铁律 = 这次改动的副作用范围有没有失控（不该动的动了吗）**。前三条全过、本铁律不过的情况真实存在——功能修好了、链路跑通了、但目录数据被顺带删了。
290
290
  - ⚠️ **具体操作流程见 `/forensic-report` skill**（三层证据怎么拍、逐像素怎么相减、差异怎么归因、可复核导航怎么组织、报告骨架长什么样）。
@@ -340,10 +340,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
340
340
  - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
341
341
  - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
342
342
  - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
343
- - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
344
- - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
345
- - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
346
- - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
343
+ - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：
344
+ - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的那份**截图版 HTML** 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 下载后打开即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
345
+ - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)（点开后请点右上角「Download raw file」下载，双击下载的 HTML 打开）`。reviewer 建议在新标签页打开，看完细节再回正文。
346
+ - **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：生成自包含 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（内含本链接的制作与置顶步骤）。
347
347
  - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
348
348
  - **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
349
349
  - ⚠️ PR Title / Description / Test Plan 全部中文。
@@ -615,7 +615,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
615
615
 
616
616
  ### HTML 文档截图与 curl 命令规范
617
617
 
618
- - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有仓库 PDF 等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
618
+ - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有文档仓库等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
619
619
  - ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
620
620
  - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
621
621
  - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
@@ -762,11 +762,12 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
762
762
 
763
763
  ## 文档规则
764
764
 
765
- - ⚠️ **文档格式选型：能 MD 就 MD，HTML→PDF 只用于截图版报告**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；只有验证报告/截图版报告等需要内嵌截图+箭头标注的可视化文档才用 HTML→PDF（GitHub blob 视图对 HTML 显示源码不渲染，转 PDF 才能点开即看）。**类比：写便签能说清的事就不要做成一整本画册——便签（MD）贴上墙人人直接看，画册（HTML）GitHub 这面墙只显示印刷源码，还得额外转成 PDF 才能翻。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → HTML→PDF；不需要 → MD 直传。
765
+ - ⚠️ **文档格式选型：能 MD 就 MD，需要截图的用截图版 HTML（不再转 PDF）**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；验证报告/截图版报告等需要内嵌截图 + 箭头标注的可视化文档用**自包含单文件 HTML**（截图一律 `data:image/png;base64` 内嵌），**HTML 即最终交付格式，交付后由使用者下载到本地双击打开**。**为什么不再转 PDF**：① 少一道无头 Chrome 转换（大报告转换慢，且分页会把表格与截图拦腰切断、页数虚增）；② 下载后的 HTML 可全文搜索、可复制文字、链接可点、图片可放大，比 PDF 好用。**类比：报告本身就是一本能直接翻、能搜索、能点链接的画册，没必要再把它压成一本只能整页翻的影印本——压完还常把跨页的表格切成两半。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → 截图版 HTML；不需要 → MD 直传。
766
+ - ⚠️ **交付截图版 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` 再双击）。**禁止只甩一个链接、不说怎么打开。**
766
767
  - ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/index.html`**（`文档名 | 链接` 表格，链接一律 `target="_blank" rel="noopener"` 新标签页打开），**禁止在 `docs/` 存放文档正文**（HTML / PDF / MD / 截图 / 图片等大文件一律不提交进代码仓库）。
767
768
  - ⚠️ **文档正文存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
768
- - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成 HTML → 无头 Chrome 转 PDF → push 到 `<项目>-docs` 私有仓库的 `docs` 分支 → 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
769
- - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<pdf|md>`，粘贴到浏览器即可查看（GitHub 内嵌渲染 PDF / Markdown；私有仓库未登录会跳登录页）。
769
+ - 新建文档使用 `/create-doc` skill：纯文字/表格类 → 直接写 MD 直传；截图版报告 → 生成自包含 HTML → 直接 push 到 `<项目>-docs` 私有仓库的 `docs` 分支（**不再转 PDF**）→ 在代码仓库 `docs/index.html` 记录「文档名 | 链接」。
770
+ - 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>`，粘贴到浏览器即可打开（`.md` GitHub 原生渲染；`.html` 显示源码，必须按上方三步说明下载后本地打开；私有仓库未登录会跳登录页）。
770
771
  - ⚠️ **迁移项目既有文档到 `<项目>-docs` 前，先区分「纯文档」与「代码资产 / 对外服务页面」，禁止一刀切全迁**：
771
772
  - **对外服务的 API 文档站**（gateway 类项目的 `docs/`：含 `index.html` + `authentication.html` + `css/` + `js/` + `nginx.conf.template` 的整套站点）是**线上产品页面**，随模型/接口持续更新（git log 常有「添加 xxx 模型」等提交），线上 URL 可访问（如 `https://xxx/docs` 返回 200）——这类**不能迁**，迁走线上直接 404。判断标准：线上有对应 URL 且能访问 → 是对外服务页面，不是内部文档。
772
773
  - **散落文档目录**（`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 +776,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
775
776
 
776
777
  ## 文档/文件链接交付
777
778
 
778
- - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` + 一行内容说明），这就是最终交付形式。
779
+ - ⚠️ 给用户交付文档时，**直接给出可点击的 GitHub 链接**（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.<html|md>` + 一行内容说明），这就是最终交付形式。交付 `.html` 的还必须**同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（原因与话术见「⚠️ 文档规则」），禁止只给链接不说怎么打开。
779
780
  - ⚠️ **禁止为了交付文档而起本地 HTTP 服务**（`python3 -m http.server` 等）：不起服务、不占端口、不残留后台进程。
780
781
  - ⚠️ 禁止使用相对路径（如 `docs/模型xxx.html`）或 `file:///` 形式：相对路径含中文/空格时 VSCode 无法点击，`file:///` 被 VSCode webview 安全策略拦截，用户都打不开。
781
782
  - ⚠️ **交付需要用户复制/使用的本地文件路径，用 fenced code block（反引号包裹）呈现，禁止只作为行内文本/链接甩出来让用户自己拖选复制**：多数客户端（VSCode 扩展、claude.ai 网页版等）对代码块自带右上角「复制」按钮，用户点一下即复制整串路径（含中文/空格），无需鼠标滑上去选中全部再手动复制。文件如何打开（双击 / 点链接）在代码块下方补一行说明即可，不受影响。
package/skills/create-doc/SKILL.md CHANGED
@@ -11,21 +11,21 @@ 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**——交付时须附「下载后双击打开」三步说明。
15
15
  ---
16
16
 
17
- # 创建文档（MD 直传 / HTML→PDF → 私有文档仓库）
17
+ # 创建文档（MD 直传 / 截图版 HTML → 私有文档仓库）
18
18
 
19
- ⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `create-doc`，按规范生成文档（MD 直传或 HTML→PDF→私有仓库）」然后严格按照以下步骤执行，不得跳过。**
19
+ ⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `create-doc`，按规范生成文档（MD 直传或截图版 HTML→私有仓库）」然后严格按照以下步骤执行，不得跳过。**
20
20
 
21
- 生成符合项目规范的中文文档/报告。最终交付形式是 **私有文档仓库链接**（GitHub 内嵌渲染 PDF / Markdown，私有仓库仅团队成员登录可见）；代码仓库 `docs/` 只保留索引 `docs/index.html`，不存放文档正文。
21
+ 生成符合项目规范的中文文档/报告。最终交付形式是 **私有文档仓库链接**（`.md` GitHub 原生渲染；截图版 `.html` GitHub 只显示源码，需下载后本地双击打开，私有仓库仅团队成员登录可见）；代码仓库 `docs/` 只保留索引 `docs/index.html`，不存放文档正文。
22
22
 
23
23
  ## 第一步：格式选型（能 MD 就 MD）
24
24
 
25
25
  - ⚠️ **判断这份文档是否需要「截图为主、文字为辅」**：
26
26
  - **纯文字/表格类**（需求说明、操作指南、设计文档、接口文档、方案总结等）→ **MD 直传**：直接写 `.md` 文件，GitHub 原生渲染，零转换步骤。走下方「MD 直传」流程。
27
- - **截图版报告**（验证报告、需要内嵌截图+箭头标注的可视化文档）→ **HTML→PDF**：走下方「HTML 转 PDF」流程。GitHub blob 视图对 HTML 显示源码不渲染，必须转 PDF 才能点开即看。
28
- - 用户明确要求「生成 html / 截图版」的，直接走 HTML→PDF，不必再问格式。
27
+ - **截图版报告**（验证报告、需要内嵌截图+箭头标注的可视化文档）→ **截图版 HTML**：走下方「HTML 交付（不再转 PDF）」流程。**不再转 PDF**——理由：少一道无头 Chrome 转换（大报告转换慢，分页还会把表格与截图拦腰切断、页数虚增），且 HTML 下载后可全文搜索、可复制文字、链接可点、图片可放大。
28
+ - 用户明确要求「生成 html / 截图版」的，直接走截图版 HTML，不必再问格式。
29
29
 
30
30
  ## 交付流程总览
31
31
 
@@ -34,12 +34,11 @@ description: >-
34
34
  2. push MD 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支
35
35
  3. 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」
36
36
  4. 交付给用户：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.md` 链接 + 一行内容说明
37
- - **HTML→PDF 路径**：
38
- 1. 按下方「文档规范」生成 HTML 文档（**中间产物**，中文文件名）
39
- 2. 用无头 Chrome 将 HTML 转成 PDF
40
- 3. push PDF 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支
41
- 4. 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」
42
- 5. 交付给用户：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 链接 + 一行内容说明
37
+ - **截图版 HTML 路径**：
38
+ 1. 按下方「文档规范」生成自包含 HTML 文档（中文文件名、截图 `data:image/png;base64` 内嵌）
39
+ 2. push HTML 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支（**不再转 PDF**）
40
+ 3. 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」
41
+ 4. 交付给用户：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html` 链接 + 一行内容说明 + **「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**
43
42
 
44
43
  ## 确定文档仓库（从 git remote 推导）
45
44
 
@@ -54,48 +53,43 @@ description: >-
54
53
 
55
54
  ## MD 直传
56
55
 
57
- - 纯文字/表格类文档（格式选型判断为 MD 的）：直接写 `.md` 文件，**跳过 HTML 生成与 PDF 转换**，直传私有文档仓库。
56
+ - 纯文字/表格类文档（格式选型判断为 MD 的）：直接写 `.md` 文件，**跳过 HTML 生成**，直传私有文档仓库。
58
57
  - 交付文件名：中文命名（如 `模型分时段定价需求文档.md`）。
59
58
  - 上传方式与「push 到文档仓库」章节一致（clone → docs 分支 → 放入 MD → commit → push）。
60
59
  - ⚠️ MD 中需要展示截图/图片的，用相对路径引用并同时上传图片到 `assets/` 目录（或按 GitHub Markdown 内嵌方式处理），禁止引用外部链接。
61
60
 
62
- ## HTML 转 PDF
61
+ ## HTML 交付（不再转 PDF）
63
62
 
64
- - HTML 生成后存到本地临时目录（如 `screenshots/` 同级或 `/tmp`），用无头 Chrome 转换：
65
- ```bash
66
- CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
67
- "$CHROME" --headless=new --disable-gpu --no-sandbox \
68
- --print-to-pdf="/tmp/<日期>-<文档名>.pdf" \
69
- --no-pdf-header-footer \
70
- "file://$(pwd)/<HTML相对路径>"
71
- ```
72
- > 无头 Chrome 偶发 `task_policy_set ... invalid argument` 输出属 macOS 良性噪声，可忽略。
73
- - ⚠️ 转换后必须抽查 PDF 内容完整（如 `sips -s format png <pdf> --out /tmp/check.png` 渲染首页确认），禁止直接交付未验证的 PDF。
63
+ - HTML 生成后**直接交付，不做任何格式转换**（不再走无头 Chrome 转 PDF）。
64
+ - ⚠️ 交付前必须**实际打开这份 HTML 抽查内容完整**（浏览器打开或截图确认首屏正常、截图不裂、箭头标注在位），禁止交付未验证的文件。
65
+ - ⚠️ **必须确认文件是自包含的**：所有截图均为 `data:image/png;base64` 内嵌，无任何外部图片/样式依赖——对方下载单个 `.html` 文件、脱离原目录双击也能完整显示（这是「下载后打开」这条路能成立的前提）。
66
+ - ⚠️ **交付话术必须带三步操作说明**（否则对方看到源码会以为链接坏了）：GitHub 对 `.html` 任何链接形式都不渲染（blob 显示源码；`raw.githubusercontent.com` 与 `/raw/` 均以 `content-type: text/plain` 返回）。固定话术：**点链接 → 点页面右上角「Download raw file」下载 → 双击下载下来的 `.html` 打开**（若浏览器直接把源码文本打开了，改用 ⌘S / Ctrl+S 另存为 `.html` 再双击）。
74
67
 
75
68
  ## push 到文档仓库
76
69
 
77
70
  - ⚠️ PomexAITeam 组织规则要求默认分支必须走 PR，禁止直推 main；**统一推送到非默认 `docs` 分支**（直推不受限）。
78
- - 临时 clone 文档仓库 → 切到 `docs` 分支 → 放入 PDF → commit → push：
71
+ - 临时 clone 文档仓库 → 切到 `docs` 分支 → 放入 HTML → commit → push：
79
72
  ```bash
80
73
  TMP=$(mktemp -d)
81
74
  git clone git@github.com:PomexAITeam/pomexai-docs.git "$TMP"
82
75
  cd "$TMP" || exit 1
83
76
  git checkout -b docs 2>/dev/null || git checkout docs
84
- cp /tmp/<日期>-<文档名>.pdf .
77
+ cp /tmp/<日期>-<文档名>.html .
85
78
  git add .
86
79
  git commit -m "docs: 新增 <文档名>"
87
80
  git push origin docs
88
81
  cd - >/dev/null 2>&1
89
82
  rm -rf "$TMP"
90
83
  ```
91
- - PDF 文件名：`<日期>-<文档中文名>.pdf`（如 `2026-08-31-模型模块化补测验证报告.pdf`），**每次新增独立文件，禁止覆盖旧文档**。
84
+ - ⚠️ **文档仓库多为大文件仓库（PDF/HTML 动辄数 MB），clone 可能极慢甚至卡死**：优先用免 clone 推送方式——`git clone --filter=blob:none --sparse` 拉空工作区 → `git update-index --add --cacheinfo 100644,<新 blob SHA>,<文件名>` 直接把新文件挂进索引 → commit → push（避免 fetch 历史大文件）。
85
+ - HTML 文件名：`<日期>-<文档中文名>.html`（如 `2026-08-31-模型模块化补测验证报告.html`），**每次新增独立文件，禁止覆盖旧文档**。
92
86
  - 若 remote 不是 `git@github.com:...` 形态，用实际 remote URL 替换 clone 地址。
93
87
 
94
88
  ## 记录索引（代码仓库 docs/index.html）
95
89
 
96
90
  - 更新代码仓库 `docs/index.html`（HTML 表格索引，链接一律 `target="_blank" rel="noopener"` 新标签页打开），按现有 index.html 结构在表格追加一行「文档名 | 链接」，示例：
97
91
  ```html
98
- <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>
92
+ <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>
99
93
  ```
100
94
  - ⚠️ `docs/index.html` 是新标签页打开链接的 HTML 索引；GitHub 上点开会显示源码，下载后双击即可在浏览器查看渲染效果。
101
95
  - 索引随代码正常提交（feature 分支 → PR），这是代码仓库 `docs/` 里唯一的内容。
@@ -103,12 +97,13 @@ description: >-
103
97
  ## 交付给用户
104
98
 
105
99
  - 交付时给出**可点击的 GitHub 链接** + 一行内容说明。禁止用相对路径（`docs/xxx.html`）、`file:///` 或本地 HTTP 服务（不起服务、不占端口）。
100
+ - ⚠️ **交付 `.html` 时必须同时给出「怎么打开」的三步说明**：**点链接 → 点页面右上角「Download raw file」下载 → 双击下载下来的 `.html` 打开**（若浏览器直接把源码文本打开了，改用 ⌘S / Ctrl+S 另存为 `.html` 再双击）。**只甩一个链接不说怎么打开 = 对方看到一屏源码，会以为链接坏了。**
106
101
 
107
102
  ## 文档规范（HTML 生成）
108
103
 
109
104
  ### 格式要求
110
105
 
111
- - HTML 是中间产物，生成后用于转 PDF；文件名一律中文命名（如 `模型xxx.html`）
106
+ - HTML 是**最终交付产物**（不再转 PDF）；文件名一律中文命名（如 `模型xxx.html`）
112
107
  - 标题、正文、章节、说明文字全部中文；代码、命令、专有名词、接口字段可保留英文
113
108
 
114
109
  ### 可视化优先
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→PDF「详细实现文档」醒目链接（PR 正文快速浏览、链接展开每一步细节）。
8
+ 自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中，并在 Description 顶部附截图版 HTML「详细实现文档」醒目链接（PR 正文快速浏览、链接展开每一步细节）。
9
9
  ---
10
10
 
11
11
  # 创建 Pull Request
@@ -102,19 +102,21 @@ Closes #issue编号
102
102
  - ⚠️ 截图保存到本地磁盘 `docs/` 对应子目录（文件名「编号 + 英文描述」，如 `01-before.png` / `02-after.png`），上传 CDN 后按规则清理临时文件，禁止提交到 Git 仓库。
103
103
  - ⚠️ 必须展示前后对比（修复前红框，修复后绿框），标注不遮挡页面内容。
104
104
 
105
- ### 5. 制作详细实现文档（截图版 HTML→PDF）并置顶到 Description
105
+ ### 5. 制作详细实现文档（截图版 HTML）并置顶到 Description
106
106
 
107
- ⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 PDF 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
107
+ ⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 HTML 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
108
108
 
109
109
  1. **汇总素材**：本 PR 的「改了什么 + 为什么改 + 每一步怎么改/怎么验证」，以及步骤 4 产出的全部效果截图（含修复前后对比）。
110
110
  - ⚠️ **修 bug / 修故障的 PR，文档必须额外覆盖第四部分「复现步骤」**（依据「⚠️ 缺陷复现铁律」）：把复现时按步骤拍下的截图按编号排开，**每一步一张图 + 箭头标注出「这一步点哪里 / 填什么 / 坏现象出现在哪」**，让人照着走一遍就等于亲手复现了一次。⚠️ **纯后端 / 无界面的 bug 也要可视化**：每一步的 curl 请求与响应渲染成暗色终端风格截图（带请求 ID、时间戳），坏现象那一步单独放大标注。⚠️ 这些截图必须是**改代码之前**复现时当场存下来的，不是改完之后回头补的（改完代码变了，补出来的不是复现）。禁止只在 PR 描述里贴一段文字步骤就算交差。
111
111
  - ⚠️ **素材取材优先级：前端可视化优先，纯逻辑才退而用代码/接口图**：讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明**——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
112
- 2. **生成截图版 HTML → 转 PDF**：走 `/create-doc` skill 输出自包含 HTML——截图一律 `data:image/png;base64` 内嵌并自动加箭头标注（遵循「⚠️ 截图规范」「⚠️ HTML 文档截图与 curl 命令规范」），图文逐步说明每一步怎么做的；再经无头 Chrome 转 PDF。
113
- 3. **托管到私有文档仓库**：push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支（仓库名从 git remote 推导：`git@github.com:<ORG>/<项目>.git` → 文档仓库 `<ORG>/<项目>-docs`），文件名用与 PR 主题相关的英文短名。
114
- 4. **拿链接**：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。
115
- 5. **拼到 Description 顶部**：把链接作为 Description **第一条、独占一行、加粗高亮**，放在任何正文段落之前：
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
116
  ```
117
- 📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)
117
+ 📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.html)
118
+
119
+ > ⬆️ 点开后请点页面右上角「Download raw file」下载，双击下载的 `.html` 打开（GitHub 对 HTML 只显示源码，不渲染）。
118
120
  ```
119
121
  reviewer 建议以新标签页打开，看完细节再回 PR 正文。
120
122
 
@@ -184,7 +186,7 @@ gh pr checks <PR>
184
186
  - ⚠️ 必须附截图作为可视化证据
185
187
  - ⚠️ **建 PR 前先做步骤 0 的规则在场自检**：规则文件里搜不到 `详细实现文档`，或当前分支规则版本落后远程默认分支 → 先升级规则再建 PR。规则陈旧是静默故障，不报错不等于没缺东西。
186
188
  - ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
187
- - ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML→PDF，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节
189
+ - ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节；**链接旁必须同时给出「点链接 → 点右上角 Download raw file 下载 → 双击打开」三步说明**（GitHub 对 HTML 只显示源码，不说明对方会以为链接坏了）
188
190
  - ⚠️ 截图禁止提交到 Git 仓库
189
191
  - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
190
192
  - ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 8）
package/skills/forensic-report/SKILL.md CHANGED
@@ -227,7 +227,7 @@ SELECT provider_id, count(*) FROM provider_model_pricing
227
227
 
228
228
  | 场景 | 交付形式 |
229
229
  |---|---|
230
- | **走 PR 的改动** | 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML→PDF，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。**它是那份文档里的一节，不另起一份**——reviewer 点一个链接就该看到全部，不该在两个链接之间来回跳。走 `/create-doc` skill。 |
230
+ | **走 PR 的改动** | 取证报告**并入 PR 顶部那份「详细实现文档」**（截图版 HTML，托管到 `<项目>-docs` 私有仓库，链接置顶 PR Description）。**它是那份文档里的一节，不另起一份**——reviewer 点一个链接就该看到全部，不该在两个链接之间来回跳。走 `/create-doc` skill。 |
231
231
  | **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果） | 直接给**桌面上的单文件 HTML 绝对路径**（如 `/Users/<me>/Desktop/<任务名>/xxx-取证报告.html`）。截图一律 `data:image/png;base64` 内嵌，双击即开、可搜索、转发不裂图。**不走私有仓库、不起本地 HTTP 服务、不用相对路径、不用 `file:///`。** |
232
232
 
233
233
  ⚠️ **两种形式都要求截图内嵌，禁止用文件路径引用外部 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→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`）。
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` 只显示源码不渲染，只甩链接不说怎么打开，对方会以为链接坏了。
53
53
  - **不走 PR 的即时修复**（用户当场让你修个 bug、要立刻看结果）→ 直接给**桌面上的单文件 HTML 绝对路径**，截图 `data:image/png;base64` 内嵌，双击即开、可搜索、转发不裂图。不走私有仓库、不起本地 HTTP 服务、不用相对路径、不用 `file:///`。
54
54
  - ⚠️ **两种形式都要求截图内嵌**，禁止用文件路径引用外部 PNG——文档会被移动、分享，外部路径一脱离原目录就全是裂图。散落的零散 PNG 应一并清理，只保留文档本身。
55
55
  - ⚠️ 代码仓库 `docs/` 只维护索引，禁止把报告正文（HTML/PDF/截图）直接放进 `docs/`。