@routerhub/agent-rules 1.5.178 → 1.5.180

package/AGENTS.base.md

@@ -27,7 +27,7 @@
 
 ## ⚠️ 环境配置禁止推断
 
-- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交��确认：
+- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交���确认：
 1. 项目内的部署脚本、Dockerfile、CI 配置
 2. 实际 DNS 解析（`dig`/`nslookup`）
 3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
@@ -43,8 +43,8 @@
 1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
 2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
 3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
-- ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
-- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
+- ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是��线遗漏的根源**（测试环境做了、生产环境容易忘）。
+- ⚠️ **部署完成的定义 = 脚本执行完 �� 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
 - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
 
 ## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
@@ -66,7 +66,7 @@
 - ⚠️ **验证功能是否修复时，要用真实存在的数据/路径去测试**，避免用虚构的测试数据得出「失败」的假结论。
 - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
 - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
-- **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
+- **长任务或涉及截图等大内容的操���，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
 - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
@@ -88,7 +88,7 @@
 
 ## ⚠️ 页面功能验证铁律（真实数据 + 真实交互）
 
-- ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
+- ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些���测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
 ## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
@@ -111,7 +111,7 @@
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` 会在 main 上生成「发布 vX.Y.Z」提交）。
+- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` ��在 main 上生成「发布 vX.Y.Z」提交）。
 - ⚠️ **从主分支拉/建功能分支之前，必须先直接拉取远程主分支（`git pull origin main`）**，确保基于最新的远程主分支拉分支，禁止基于过期的本地主分支创建分支。
 - ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
@@ -205,7 +205,7 @@
 - 禁止重复实现，发现重复必须提取封装。同一数据/配置只在一处维护。禁止硬编码数字。
 - 前端：Tailwind CSS 禁止原生 CSS，尺寸单位必须 `rem` 禁止 `px`（1rem=16px）。
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
-- ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）���，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
+- ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
 ## 代码质量（一次写对，为结果负责）
 
@@ -353,7 +353,7 @@
 - ⚠️ **路由/解析 switch default 分支禁止静默 skip+warn**：静默跳过会让路由表悄悄缺模型/缺路由；应显式报错或强告警。路由收窄/拆池前先查全量数据分布。**依赖「客户端/上游不会这么发」假设的丢弃/忽略分支，必须打日志**：假设一旦被打破（上游发来畸形数据），生产可诊断，禁止静默丢弃。
 - ⚠️ **失败路径也要补全归属字段**：成功/失败覆盖一致（失败 usage 事件也要回填 ProviderAccountId 等），否则某个账号持续失败时按账号排查不出来。
 - ⚠️ **清理/剥离函数必须清「实际被填充」的字段**：核对写入方填哪个字段、清理方清哪个字段，二者对齐；只清自己认识的字段、漏掉写入方真正填的，等于没清。
-- ⚠️ **等效路径行为必须对齐**：同一语义的多条路径（chat/responses、流式/非流式、compat/非 compat）改一条的过滤/剥除逻辑必须同步所有等效路径，否则出现「改前隐藏、改后泄漏」的��默回归。
+- ⚠️ **等效路径行为必须对齐**：同一语义的多条路径（chat/responses、流式/非流式、compat/非 compat）改一条的过滤/剥除逻辑必须同步所有等效路径，否则出现「改前隐藏、改后泄漏」的静默回归。
 - ⚠️ **流式发出首块后失败必须补发显式错误结束事件**：禁止只静默关闭连接——客户端会误判为网络断开或永远等待。
 - ⚠️ **客户端已断开后禁止再向连接写错误响应**：写前检查断开状态；已断开只做结算与上报，不做无用写。
 - ⚠️ **带副作用的函数先判空/前置校验后写**：先写后判空，nil 入参会 panic。
@@ -423,7 +423,7 @@
 ### HTML 文档截图与 curl 命令规范
 
 - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有仓库 PDF 等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
-- ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主��、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
+- ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
 - ⚠️ **敏感值内嵌真实值（有意为之的既定规则）：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。**

package/package.json

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

package/rules/global.md

@@ -27,7 +27,7 @@ name: "通用规则"
 
 ## ⚠️ 环境配置禁止推断
 
-- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交��确认：
+- ⚠️ **写代码或注释涉及环境相关的值（域名、地址、端口、密钥、外部服务 URL 等）时，禁止根据已知值类推未知值**（例如「测试是 api-test.xxx，那生产应该就是 api.xxx」）。必须从以下来源至少一处交���确认：
 1. 项目内的部署脚本、Dockerfile、CI 配置
 2. 实际 DNS 解析（`dig`/`nslookup`）
 3. 云平台控制台（Cloud Run 域名映射、GCLB、Ingress 等）
@@ -43,8 +43,8 @@ name: "通用规则"
 1. **改数据库了吗？** 新增/修改表、字段或数据 → 部署脚本必须有幂等 schema 确保逻辑（如 `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`、`ensure_xxx()` 前置函数），加列/建表失败即停止部署。
 2. **改配置了吗？** 新增/修改环境变量、Nacos 配置、部署脚本值 → 具体值必须已落地部署脚本或配置中心，禁止只写占位符或"待确认"。
 3. **要初始化/搬运数据吗？** 需要初始化、导入、转换数据 → 必须脚本化进部署流程自动完成。
-- ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是上线遗漏的根源**（测试环境做了、生产环境容易忘）。
-- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
+- ⚠️ **发现「部署后还需要手动补步骤」= 部署流程有缺口**：一旦某次部署发现还要人工执行迁移、导数据、改配置等步骤功能才能用，必须当场把该步骤自动化进部署脚本，禁止继续靠记性每次手动补。**人为手动步骤是��线遗漏的根源**（测试环境做了、生产环境容易忘）。
+- ⚠️ **部署完成的定义 = 脚本执行完 �� 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
 - ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
 
 ## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
@@ -66,7 +66,7 @@ name: "通用规则"
 - ⚠️ **验证功能是否修复时，要用真实存在的数据/路径去测试**，避免用虚构的测试数据得出「失败」的假结论。
 - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
 - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
-- **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
+- **长任务或涉及截图等大内容的操���，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
 - ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
 - ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 - ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
@@ -88,7 +88,7 @@ name: "通用规则"
 
 ## ⚠️ 页面功能验证铁律（真实数据 + 真实交互）
 
-- ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些。测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
+- ⚠️ **编写 HTML 页面或前端功能后，必须用测试环境的真实数据验证，禁止用虚构/mock 数据自测。** 虚构数据只能验证「代码不报错」，无法验证「功能在真实场景下正常工作」——真实数据会暴露边界情况（空值、超长文本、特殊字符、异常关联关系等），虚构数据碰不到这些���测试环境有真实数据时优先用测试环境；测试环境数据不足时，从生产环境脱敏导出。
 - ⚠️ **页面功能验证必须通过实际的页面交互操作来完成**（打开浏览器、点击按钮、填写表单、观察渲染结果），模拟真实用户操作路径。禁止只靠代码审查、单元测试断言或静态分析代替实际页面操作验证——用户最终是通过页面交互使用功能的，不是通过测试断言。能用浏览器手动操作的，就用浏览器手动操作一遍。
 
 ## ⚠️ 可视化验证铁律（默认不写测试用例，用证据说话）
@@ -111,7 +111,7 @@ name: "通用规则"
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` 会在 main 上生成「发布 vX.Y.Z」提交）。
+- ⚠️ **一般情况下，主分支（`main`）不允许直接提交代码**：日常改动必须先直接拉取远程主分支 → 创建功能分支 → 提交 → 推送 → PR 合并回主分支，禁止直接 commit/push 到 main（发版除外：`./release.sh` ��在 main 上生成「发布 vX.Y.Z」提交）。
 - ⚠️ **从主分支拉/建功能分支之前，必须先直接拉取远程主分支（`git pull origin main`）**，确保基于最新的远程主分支拉分支，禁止基于过期的本地主分支创建分支。
 - ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
 - ⚠️ **已推送到远程的提交需要撤销时，必须用 `git revert`，禁止用 `git push --force` 覆盖远程历史。** `git revert` 会创建一条新的撤销提交，保留完整的操作记录，不影响其他协作者的本地分支；`git push --force` 会破坏远程历史，导致其他人的本地分支与远程脱节，极易引发合并冲突或丢失他人提交。
@@ -205,7 +205,7 @@ name: "通用规则"
 - 禁止重复实现，发现重复必须提取封装。同一数据/配置只在一处维护。禁止硬编码数字。
 - 前端：Tailwind CSS 禁止原生 CSS，尺寸单位必须 `rem` 禁止 `px`（1rem=16px）。
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
-- ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）���，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
+- ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
 ## 代码质量（一次写对，为结果负责）
 
@@ -353,7 +353,7 @@ name: "通用规则"
 - ⚠️ **路由/解析 switch default 分支禁止静默 skip+warn**：静默跳过会让路由表悄悄缺模型/缺路由；应显式报错或强告警。路由收窄/拆池前先查全量数据分布。**依赖「客户端/上游不会这么发」假设的丢弃/忽略分支，必须打日志**：假设一旦被打破（上游发来畸形数据），生产可诊断，禁止静默丢弃。
 - ⚠️ **失败路径也要补全归属字段**：成功/失败覆盖一致（失败 usage 事件也要回填 ProviderAccountId 等），否则某个账号持续失败时按账号排查不出来。
 - ⚠️ **清理/剥离函数必须清「实际被填充」的字段**：核对写入方填哪个字段、清理方清哪个字段，二者对齐；只清自己认识的字段、漏掉写入方真正填的，等于没清。
-- ⚠️ **等效路径行为必须对齐**：同一语义的多条路径（chat/responses、流式/非流式、compat/非 compat）改一条的过滤/剥除逻辑必须同步所有等效路径，否则出现「改前隐藏、改后泄漏」的��默回归。
+- ⚠️ **等效路径行为必须对齐**：同一语义的多条路径（chat/responses、流式/非流式、compat/非 compat）改一条的过滤/剥除逻辑必须同步所有等效路径，否则出现「改前隐藏、改后泄漏」的静默回归。
 - ⚠️ **流式发出首块后失败必须补发显式错误结束事件**：禁止只静默关闭连接——客户端会误判为网络断开或永远等待。
 - ⚠️ **客户端已断开后禁止再向连接写错误响应**：写前检查断开状态；已断开只做结算与上报，不做无用写。
 - ⚠️ **带副作用的函数先判空/前置校验后写**：先写后判空，nil 入参会 panic。
@@ -423,7 +423,7 @@ name: "通用规则"
 ### HTML 文档截图与 curl 命令规范
 
 - ⚠️ **HTML 页面/文档中的外部链接默认用新标签页打开**：所有指向外部资源（其他网站、GitHub 文档、私有仓库 PDF 等）的链接一律写成 `<a target="_blank" rel="noopener" href="...">`，禁止不加 `target` 让用户点击后直接跳出当前页面。**类比：逛商场拿着一份导购地图，每个店名都标着「在新窗口查看」——点一家店不会把你从地图里踢出去，地图还在，能连续逛好几家；不新开窗口的话，每点一家店整张地图就没了，得反复按返回。** `rel="noopener"` 是安全兜底，防止新页面通过 `window.opener` 反向控制当前页（tabnabbing 钓鱼攻击）。
-- ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主��、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
+- ⚠️ **截图版 HTML 文档中的截图必须自动加箭头标注**：当用户要求写「截图版 HTML」文档（以截图为主体、图文结合说明实现/操作步骤的文档，如部署实现说明、操作指南等）时，嵌入的每张截图都必须自动用醒目的箭头 + 简短文字标签标注出关键区域/验证点/操作位置，让读者一眼看懂这张图对应文档的哪一步、证明了什么，禁止只贴裸图不标注。箭头标注放在不遮挡原内容的位置。
 - ⚠️ **HTML 文档中的截图必须以 `data:image/png;base64,...` 内嵌，禁止用文件路径或相对链接引用外部 PNG 文件。** 文档会被打开、移动、分享，外部图片路径一旦脱离原目录就全部失效，文档里全是裂图。生成文档后，散落的零散 PNG 文件应一并清理，只保留 HTML 本身。
 - ⚠️ **curl 命令必须完整可复制执行，禁止省略关键参数。** 包括但不限于：API Key / Token、请求体中的图片数据、完整的 URL。禁止用 `...` 或「省略其余参数」代替——看的人无法区分「这里不重要所以省略了」还是「这里我不会写所以跳过了」，前者让命令不可执行，后者掩盖了潜在的错误。
 - ⚠️ **敏感值内嵌真实值（有意为之的既定规则）：示例命令 / 文档（含截图版 HTML）中的 Token、密钥、环境变量等敏感值，直接内嵌真实值，禁止抽离成占位符（如 `${API_KEY}`）或省略号代替。**