@routerhub/agent-rules 1.5.166 → 1.5.168

package/AGENTS.base.md

@@ -519,10 +519,16 @@
 
 ## 文档规则
 
-- ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/README.md`**（`文档名 | 链接` 表格），**禁止在 `docs/` 存放文档正文**（HTML / PDF / 截图 / 图片等大文件一律不提交进代码仓库）。
-- ⚠️ **文档正文以 PDF 形式存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
-- 新建文档使用 `/create-doc` skill：生成 HTML → 无头 Chrome 转 PDF → push 到 `<项目>-docs` 私有仓库的 `docs` 分支 → 在 `docs/README.md` 记录「文档名 | 链接」。
-- 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`，粘贴到浏览器即可查看（GitHub 内嵌渲染 PDF；私有仓库未登录会跳登录页）。
+- ⚠️ **文档格式选型：能 MD 就 MD，HTML→PDF 只用于截图版报告**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；只有验证报告/截图版报告等需要内嵌截图+箭头标注的可视化文档才用 HTML→PDF（GitHub blob 视图对 HTML 显示源码不渲染，转 PDF 才能点开即看）。**类比：写便签能说清的事就不要做成一整本画册——便签（MD）贴上墙人人直接看，画册（HTML）GitHub 这面墙只显示印刷源码，还得额外转成 PDF 才能翻。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → HTML→PDF；不需要 → MD 直传。
+- ⚠️ **代码仓库的 `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；私有仓库未登录会跳登录页）。
+- ⚠️ **迁移项目既有文档到 `<项目>-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 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
+  - **类比：搬书房前先分清楚「书」和「记账本」**——书（纯文档）搬进藏书库（-docs 仓库），记账本（测试脚本/被引用的配置）得留在桌上随时用；把记账本也塞进藏书库，下次算账（跑测试）就找不到本子了。
+  - 核对方法：迁移前 `grep -rn "目录名"` 搜代码/CI/脚本，确认哪些路径被引用；被引用的保留，未被引用的纯文档才迁。
 
 ## 文档/文件链接交付
 

package/package.json

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

package/rules/global.md

@@ -519,10 +519,16 @@ name: "通用规则"
 
 ## 文档规则
 
-- ⚠️ **代码仓库的 `docs/` 目录只维护一个索引文件 `docs/README.md`**（`文档名 | 链接` 表格），**禁止在 `docs/` 存放文档正文**（HTML / PDF / 截图 / 图片等大文件一律不提交进代码仓库）。
-- ⚠️ **文档正文以 PDF 形式存放到本项目对应的私有 GitHub 仓库 `<项目>-docs`**（如 `PomexAITeam/pomexai-docs`），仓库名由 git remote 推导：`git@github.com:PomexAITeam/pomexai.git` → 组织 `PomexAITeam`、项目 `pomexai` → 文档仓库 `PomexAITeam/pomexai-docs`。**私有仓库 = 仅团队成员登录后可查看**，天然满足「文档只给团队看」。
-- 新建文档使用 `/create-doc` skill：生成 HTML → 无头 Chrome 转 PDF → push 到 `<项目>-docs` 私有仓库的 `docs` 分支 → 在 `docs/README.md` 记录「文档名 | 链接」。
-- 文档链接格式：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`，粘贴到浏览器即可查看（GitHub 内嵌渲染 PDF；私有仓库未登录会跳登录页）。
+- ⚠️ **文档格式选型：能 MD 就 MD，HTML→PDF 只用于截图版报告**：需求说明、操作指南、设计文档、接口文档等纯文字/表格类文档一律用 Markdown 直接写（GitHub 原生渲染、零转换步骤）；只有验证报告/截图版报告等需要内嵌截图+箭头标注的可视化文档才用 HTML→PDF（GitHub blob 视图对 HTML 显示源码不渲染，转 PDF 才能点开即看）。**类比：写便签能说清的事就不要做成一整本画册——便签（MD）贴上墙人人直接看，画册（HTML）GitHub 这面墙只显示印刷源码，还得额外转成 PDF 才能翻。** 判断标准：文档需要「截图为主、文字为辅」吗？需要 → HTML→PDF；不需要 → MD 直传。
+- ⚠️ **代码仓库的 `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；私有仓库未登录会跳登录页）。
+- ⚠️ **迁移项目既有文档到 `<项目>-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 及被代码引用的路径 → 必须留在原位**，禁止连脚本一起搬走（搬走就破坏测试链路和运行时）。
+  - **类比：搬书房前先分清楚「书」和「记账本」**——书（纯文档）搬进藏书库（-docs 仓库），记账本（测试脚本/被引用的配置）得留在桌上随时用；把记账本也塞进藏书库，下次算账（跑测试）就找不到本子了。
+  - 核对方法：迁移前 `grep -rn "目录名"` 搜代码/CI/脚本，确认哪些路径被引用；被引用的保留，未被引用的纯文档才迁。
 
 ## 文档/文件链接交付
 

package/skills/create-doc/SKILL.md

@@ -11,22 +11,35 @@ description: >-
   「生成一个截图版的html」「生成截图版html」「生成一个截图版」「生成截图版」「截图版文档」「截图版报告」「截图版说明」「截图版的」等任何「截图版」表述。
   「生成一个html」「生成html」「生成一个html文档」「生成html文档」「写个html」「写html」「做一个html」「做个html」「出一个html」「出个html」「搞个html」「整个html」「弄个html」「html文档」「html报告」等任何明确要求生成 HTML 的表述。
   「html」单独说且上下文在讨论产出物时也应触发。
-  自动生成符合项目规范（HTML格式、中文文件名、base64内嵌图片、lightbox图片放大、截图为主文字为辅）的中文文档，转 PDF 后存入本项目私有文档仓库（<项目>-docs），在代码仓库 docs/ 索引记录「文档名 | 链接」。
+  自动生成符合项目规范的中文文档，存入本项目私有文档仓库（<项目>-docs），在代码仓库 docs/index.html 索引记录「文档名 | 链接」。纯文字/表格类文档用 Markdown 直传（GitHub 原生渲染、零转换）；截图版报告用 HTML 格式（中文文件名、base64 内嵌截图、lightbox 放大、截图为主文字为辅）转 PDF 后上传。
 ---
 
-# 创建文档（HTML → PDF → 私有文档仓库）
+# 创建文档（MD 直传 / HTML→PDF → 私有文档仓库）
 
-⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `create-doc`，按规范生成文档（HTML→PDF→私有仓库）」然后严格按照以下步骤执行，不得跳过。**
+⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `create-doc`，按规范生成文档（MD 直传或 HTML→PDF→私有仓库）」然后严格按照以下步骤执行，不得跳过。**
 
-生成符合项目规范的中文文档/报告。最终交付形式是 **PDF 链接**（GitHub 内嵌渲染，私有仓库仅团队成员登录可见）；代码仓库 `docs/` 只保留索引，不存放文档正文。
+生成符合项目规范的中文文档/报告。最终交付形式是 **私有文档仓库链接**（GitHub 内嵌渲染 PDF / Markdown，私有仓库仅团队成员登录可见）；代码仓库 `docs/` 只保留索引 `docs/index.html`，不存放文档正文。
+
+## 第一步：格式选型（能 MD 就 MD）
+
+- ⚠️ **判断这份文档是否需要「截图为主、文字为辅」**：
+  - **纯文字/表格类**（需求说明、操作指南、设计文档、接口文档、方案总结等）→ **MD 直传**：直接写 `.md` 文件，GitHub 原生渲染，零转换步骤。走下方「MD 直传」流程。
+  - **截图版报告**（验证报告、需要内嵌截图+箭头标注的可视化文档）→ **HTML→PDF**：走下方「HTML 转 PDF」流程。GitHub blob 视图对 HTML 显示源码不渲染，必须转 PDF 才能点开即看。
+- 用户明确要求「生成 html / 截图版」的，直接走 HTML→PDF，不必再问格式。
 
 ## 交付流程总览
 
-1. 按下方「文档规范」生成 HTML 文档（**中间产物**，中文文件名）
-2. 用无头 Chrome 将 HTML 转成 PDF
-3. push PDF 到本项目对应的私有文档仓库 `<项目>-docs` 的 `docs` 分支
-4. 在代码仓库 `docs/README.md` 索引记录「文档名 | 链接」
-5. 交付给用户：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 链接 + 一行内容说明
+- **MD 直传路径**：
+  1. 直接写 `.md` 文档（中文文件名）
+  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` 链接 + 一行内容说明
 
 ## 确定文档仓库（从 git remote 推导）
 
@@ -39,6 +52,13 @@ description: >-
   ```
 - remote 无法推导（非 `github.com:<ORG>/<REPO>` 形态）时，询问用户项目标识。
 
+## MD 直传
+
+- 纯文字/表格类文档（格式选型判断为 MD 的）：直接写 `.md` 文件，**跳过 HTML 生成与 PDF 转换**，直传私有文档仓库。
+- 交付文件名：中文命名（如 `模型分时段定价需求文档.md`）。
+- 上传方式与「push 到文档仓库」章节一致（clone → docs 分支 → 放入 MD → commit → push）。
+- ⚠️ MD 中需要展示截图/图片的，用相对路径引用并同时上传图片到 `assets/` 目录（或按 GitHub Markdown 内嵌方式处理），禁止引用外部链接。
+
 ## HTML 转 PDF
 
 - HTML 生成后存到本地临时目录（如 `screenshots/` 同级或 `/tmp`），用无头 Chrome 转换：
@@ -71,14 +91,13 @@ description: >-
 - PDF 文件名：`<日期>-<文档中文名>.pdf`（如 `2026-08-31-模型模块化补测验证报告.pdf`），**每次新增独立文件，禁止覆盖旧文档**。
 - 若 remote 不是 `git@github.com:...` 形态，用实际 remote URL 替换 clone 地址。
 
-## 记录索引（代码仓库 docs/README.md）
+## 记录索引（代码仓库 docs/index.html）
 
-- 更新代码仓库 `docs/README.md`（GitHub 自动渲染为 docs 目录首页），表格追加一行「文档名 | 链接」：
-  ```markdown
-  | 文档名 | 链接 |
-  |--------|------|
-  | <文档名> | https://github.com/PomexAITeam/pomexai-docs/blob/docs/<文件名>.pdf |
+- 更新代码仓库 `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>
   ```
+- ⚠️ `docs/index.html` 是新标签页打开链接的 HTML 索引；GitHub 上点开会显示源码，下载后双击即可在浏览器查看渲染效果。
 - 索引随代码正常提交（feature 分支 → PR），这是代码仓库 `docs/` 里唯一的内容。
 
 ## 交付给用户

package/skills/visual-report/SKILL.md

@@ -47,7 +47,7 @@ description: >-
 
 ## 报告格式（交付物 = 可视化报告 PDF 链接）
 
-- ⚠️ 用 `/create-doc` skill 生成可视化报告并交付为 **PDF 链接**：`/create-doc` 会生成 HTML（中间产物）→ 转 PDF → push 到本项目私有文档仓库 `<项目>-docs` 的 `docs` 分支 → 在代码仓库 `docs/README.md` 索引记录「文档名 | 链接」。交付给用户的是一行可点击的 GitHub 链接（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`），不是本地 HTML 文件。
+- ⚠️ 用 `/create-doc` skill 生成可视化报告并交付为 **PDF 链接**：`/create-doc` 会生成 HTML（中间产物）→ 转 PDF → push 到本项目私有文档仓库 `<项目>-docs` 的 `docs` 分支 → 在代码仓库 `docs/index.html` 索引记录「文档名 | 链接」。交付给用户的是一行可点击的 GitHub 链接（`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`），不是本地 HTML 文件。
 - ⚠️ 代码仓库 `docs/` 只维护索引，禁止把报告正文（HTML/PDF/截图）直接放进 `docs/`。
 - **报告骨架**（每个验证点必须有）：
   1. **结论卡**：本次改动改了什么、验证结果是对是错、用户确认没有