@routerhub/agent-rules 1.5.107 → 1.5.108

package/AGENTS.base.md

@@ -56,6 +56,12 @@
 - ⚠️ **截图是可视化证据，图注必须写清「这张图证明了什么」**，并标注关键行/关键数据（红框、箭头放在空白区，不遮挡原内容）。
 - ⚠️ **结论用「证据并列」呈现**：逐条列出每类证据的关键数值和可复查标识（执行 ID / 时间戳），最后一句量化修复效果（如"陈旧窗口从约 30 分钟压缩到 ≈0"）。
 
+## ⚠️ 验证结论溯源铁律
+
+- ⚠️ **验证结论必须基于运行时真实数据，禁止用「配置里写了这个字段」代替实际调用结果作为验证依据。** 配置字段存在 ≠ 运行时该字段有值——中间任何一层（序列化、转发、反序列化）丢弃了它，下游就是空的。正确做法：调一次真实接口 → 看返回体/日志里的实际值 → 确认数据通路完整。
+- ⚠️ **数据对不上时，去代码里溯源计算逻辑，禁止凭感觉猜。** 例：Gateway 返回的某个字段值不对 → `grep` 找到该字段的赋值/计算位置 → 逐层追溯到数据源头，找到具体在哪一步被改坏或丢弃。不要跳过中间层直接猜「可能是 A 模块的问题」。
+- ⚠️ **能用浏览器查看的后台页面（Log 详情、Admin 面板、监控大盘、API 文档页等），必须截图验证**，禁止只靠终端 curl 输出下结论。浏览器能看到完整的渲染结果、关联数据展开、错误详情折叠等，curl 只能看到原始文本——信息密度差一个数量级。
+
 ## ⚠️ 页面功能验证铁律（真实数据 + 真实交互）
 
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
@@ -141,6 +147,12 @@
 - 后端接口、基础设施类改动没有传统的前后端 UI diff 时，效果截图可以是：(a) 实际打开受影响页面截图，证明功能正常渲染真实数据；(b) 将 curl 请求/响应对比结果渲染成一个简单的本地 HTML（暗色终端风格），用浏览器截图工具截出来，作为"请求响应"证据图。两者都满足"必须附功能效果截图"的强制要求。
 - ⚠️ **`gh` CLI 没有原生的图片上传能力，禁止把截图提交进功能分支来获取图片链接，也禁止用 `gh gist create --public` 等公开托管服务代替**（未经授权的公开发布）。正确做法：用已登录 GitHub 的 agent-browser CDP 会话打开目标 PR 页面 → 在 PR Description 编辑区直接拖拽/粘贴图片（或定位编辑区的隐藏 `input[type=file]` 上传）→ GitHub 自动将图片转为 `https://github.com/user-attachments/assets/...` 的 CDN 地址并插入 Description 正文 → 保存 PR Description 使图片持久化。**禁止走评论区上传再搬运 URL**，评论区图片评论会干扰 reviewer 阅读。详细操作步骤见 `/create-pr` skill。
 
+### HTML 文档截图与 curl 命令规范
+
+- ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
+- ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token（用占位符 `${API_KEY}` 或真实值标注）、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
+- ⚠️ **测试用的图片等静态资源统一放到 `docs/images/` 目录，curl 命令中用相对路径引用**（如 `@docs/images/test.jpg`），确保命令在项目根目录下可直接执行。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。

package/package.json

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

package/rules/global.md

@@ -56,6 +56,12 @@ name: "通用规则"
 - ⚠️ **截图是可视化证据，图注必须写清「这张图证明了什么」**，并标注关键行/关键数据（红框、箭头放在空白区，不遮挡原内容）。
 - ⚠️ **结论用「证据并列」呈现**：逐条列出每类证据的关键数值和可复查标识（执行 ID / 时间戳），最后一句量化修复效果（如"陈旧窗口从约 30 分钟压缩到 ≈0"）。
 
+## ⚠️ 验证结论溯源铁律
+
+- ⚠️ **验证结论必须基于运行时真实数据，禁止用「配置里写了这个字段」代替实际调用结果作为验证依据。** 配置字段存在 ≠ 运行时该字段有值——中间任何一层（序列化、转发、反序列化）丢弃了它，下游就是空的。正确做法：调一次真实接口 → 看返回体/日志里的实际值 → 确认数据通路完整。
+- ⚠️ **数据对不上时，去代码里溯源计算逻辑，禁止凭感觉猜。** 例：Gateway 返回的某个字段值不对 → `grep` 找到该字段的赋值/计算位置 → 逐层追溯到数据源头，找到具体在哪一步被改坏或丢弃。不要跳过中间层直接猜「可能是 A 模块的问题」。
+- ⚠️ **能用浏览器查看的后台页面（Log 详情、Admin 面板、监控大盘、API 文档页等），必须截图验证**，禁止只靠终端 curl 输出下结论。浏览器能看到完整的渲染结果、关联数据展开、错误详情折叠等，curl 只能看到原始文本——信息密度差一个数量级。
+
 ## ⚠️ 页面功能验证铁律（真实数据 + 真实交互）
 
 - ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
@@ -141,6 +147,12 @@ name: "通用规则"
 - 后端接口、基础设施类改动没有传统的前后端 UI diff 时，效果截图可以是：(a) 实际打开受影响页面截图，证明功能正常渲染真实数据；(b) 将 curl 请求/响应对比结果渲染成一个简单的本地 HTML（暗色终端风格），用浏览器截图工具截出来，作为"请求响应"证据图。两者都满足"必须附功能效果截图"的强制要求。
 - ⚠️ **`gh` CLI 没有原生的图片上传能力，禁止把截图提交进功能分支来获取图片链接，也禁止用 `gh gist create --public` 等公开托管服务代替**（未经授权的公开发布）。正确做法：用已登录 GitHub 的 agent-browser CDP 会话打开目标 PR 页面 → 在 PR Description 编辑区直接拖拽/粘贴图片（或定位编辑区的隐藏 `input[type=file]` 上传）→ GitHub 自动将图片转为 `https://github.com/user-attachments/assets/...` 的 CDN 地址并插入 Description 正文 → 保存 PR Description 使图片持久化。**禁止走评论区上传再搬运 URL**，评论区图片评论会干扰 reviewer 阅读。详细操作步骤见 `/create-pr` skill。
 
+### HTML 文档截图与 curl 命令规范
+
+- ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
+- ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token（用占位符 `${API_KEY}` 或真实值标注）、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
+- ⚠️ **测试用的图片等静态资源统一放到 `docs/images/` 目录，curl 命令中用相对路径引用**（如 `@docs/images/test.jpg`），确保命令在项目根目录下可直接执行。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。