@routerhub/agent-rules 1.5.99 → 1.5.101

package/AGENTS.base.md

@@ -36,17 +36,21 @@
 - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
 - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
 - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
+- ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
+- ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- `test` 分支禁止直接提交代码，代码必须通过 PR 合入。commit 必须中文，禁止 `git push --force`。
+- ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
+- ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
 ## PR 核心要求
 
 - ⚠️ PR Title / Description / Test Plan 全部中文。一个 PR 只做一件事。
 - ⚠️ 必须附截图作为可视化证据（前后对比、标注改动区域）。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
+- ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全
 
@@ -60,6 +64,11 @@
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
 - ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
+## ⚠️ 数据链路改动核对铁律
+
+- ⚠️ **给一个数据结构（interface/struct/DTO）新增或修改字段后，必须顺着这份数据流转的每一个转发/序列化点逐一核对，不能只改了数据结构定义或链路两端就算完成**。典型漏改位置是中间层"手写请求体字面量"（如 `JSON.stringify({ a, b })`、手动拼接的 `params`/`payload`），新增字段不会自动带过去，也不会报错，只会表现为"下游一直是空的"这种沉默失败。
+- ⚠️ **排查"某个字段一直是空/没生效"类问题时，从数据源头开始逐层核对该字段的值（采集处 → 每一层转发处 → 最终落地处），找到具体在哪一层被丢弃**，禁止只查最终存储位置就下结论。
+
 ## ⚠️ E2E 回归测试铁律
 
 ### 一、登记用例：双文件同步，缺一不可
@@ -102,6 +111,11 @@
 - ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
 - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
 
+### 非 UI / 后端 / 基础设施改动的效果截图获取方法
+
+- 后端接口、基础设施类改动没有传统的前后端 UI diff 时，效果截图可以是：(a) 实际打开受影响页面截图，证明功能正常渲染真实数据；(b) 将 curl 请求/响应对比结果渲染成一个简单的本地 HTML（暗色终端风格），用浏览器截图工具截出来，作为"请求响应"证据图。两者都满足"必须附功能效果截图"的强制要求。
+- ⚠️ **`gh` CLI 没有原生的图片上传能力，禁止把截图提交进功能分支来获取图片链接，也禁止用 `gh gist create --public` 等公开托管服务代替**（未经授权的公开发布）。正确做法：用已登录 GitHub 的 agent-browser CDP 会话打开目标 PR 页面 → 找到评论框下的隐藏 `input[type=file]` → 上传图片 → GitHub 会自动转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并写入评论框文本 → 提交评论使图片持久化（必须先提交评论，图片链接才长期有效）→ 用 `gh pr edit --body-file` 把这些 CDN URL 替换进 PR Description 的占位符位置。详细操作步骤（选择器、提交按钮定位、受控组件输入注意事项）见 `/create-pr` skill。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
@@ -134,16 +148,44 @@
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。
-- ⚠️ 禁止修改 GCLB 配置。
+- ⚠️ 禁止修改 GCLB 配置（原因和替代方案见下方「共享基础设施变更铁律」）。
 - 禁止修改核心业务文件和 API 相关代码。
 - `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。
 
+## ⚠️ 共享基础设施变更铁律
+
+- ⚠️ **问题根因是"某个被多个服务/项目共用的基础设施配置（网关、负载均衡器、DNS、Ingress、防火墙规则、共享中间件/代理配置、共享配置中心 namespace 等）转发或配置错了"时，禁止把"直接改这个共享配置"当作默认修复方案**。共享基础设施上的改动会波及所有依赖它的其他流量/服务，波及范围和风险几乎总是大于当前这一个问题本身。优先方案是在自己服务的边界内收敛解决——如直连正确后端的独立地址、加一层自己控制的适配/转发，而不触碰上游共享设施。
+- ⚠️ **评估后确认必须改共享基础设施本身才能修复时，必须先向用户说明改动内容和影响范围（这份配置还被哪些其他服务/流量依赖），得到明确确认后才能执行**，禁止在诊断过程中把"顺手改一下共享配置"当成常规修复步骤直接执行——这类改动一旦出错，影响的不是一个功能，而是所有依赖这份共享配置的系统。
+
+## 网关/负载均衡 404 排查规范
+
+- ⚠️ **域名访问 404 时，禁止优先假设是 DNS 问题**。DNS 只负责把域名解析到 IP，能解析到正确 IP 但仍 404，说明问题在 IP 之后的路由链路上（负载均衡 / API 网关 / 反向代理的路由规则），必须先排查这一层，而不是重新配置 DNS。
+- 排查顺序（以 GCP GCLB 为例，其他云 / Nginx / API Gateway 同理）：
+  1. 确认域名解析到的 IP 由哪个转发规则（forwarding rule）监听
+  2. 找到该转发规则挂的 target-proxy → url-map
+  3. `describe` 该 url-map，重点看 `defaultService` 和 `hostRules`/`pathMatchers`——**404 常见根因是 url-map 只有 defaultService，指向的后端服务根本没部署这条路径**，而不是网络层不通
+  4. 直连后端服务（跳过网关）验证该路径本身是否存在，确认问题就在"网关路由配置"而非"服务本身"
+- ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。
+- 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。
+
+## 基础设施修复后代码 Workaround 清理规范
+
+- ⚠️ **临时绕过基础设施问题写入代码的 workaround（如硬编码直连地址、绕过网关/域名），修复根因基础设施问题后必须回退代码**，禁止让 workaround 永久留在代码里。基础设施修复完成后应主动排查代码里是否存在对应的临时绕过逻辑并清理。
+- 清理 workaround 时必须新增一条自动化回归测试守住这个退回动作（例如断言代码中不再出现临时硬编码的地址/值），防止未来又因为遇到类似问题而不经排查基础设施就重新引入同样的 workaround。
+- 判断测试失败是否由自己的改动引入：**禁止凭感觉判断**，必须用 `git stash` 暂存改动 → `git checkout` 到基线分支（如 `main`）→ 重跑同一批失败用例 → 对比结果，确认基线分支是否有同样的失败；确认后 `git checkout` 回功能分支 + `git stash pop` 还原改动。只有在基线分支上复现不出的失败，才能认定是自己的改动引入的。
+
 ## 部署规则
 
 - 发版统一执行 `./release.sh`。
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill。任何包含「部署测试」「发布测试」「上线测试」「部署test」「推到test」「部署到测试环境」等表述的需求，必须先调用 `Skill` 工具加载 `deploy-test`，严禁跳过 skill 直接执行部署操作。
 - ⚠️ 部署测试环境的正确流程是：当前分支 → 合并到 test 分支 → 推送 test → 触发部署 → 切回原分支。禁止直接在 test 分支上提交代码，禁止跳过合并步骤直接部署功能分支。
 
+## ⚠️ 配置中心变更生效铁律
+
+- ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。
+- ⚠️ **重启生产服务前必须获得用户明确确认**，即使目的只是"让配置生效"这种听起来很轻量的操作——重启本身对生产可用性是有影响的，不能因为动机温和就跳过确认。
+- ⚠️ **读取/核对含密钥的配置文件（生产环境尤其）时，禁止 `cat` 或任何会把文件全文打印到终端/日志的方式**，改用程序化方式核对（脚本读取后只处理/打印特定字段名，或用 diff 比较修改前后），避免密钥明文出现在终端记录或对话历史里。
+
 ## 文档规则
 
 - 新建文档使用 HTML 格式（`.html`）、中文文件名，存到 `docs/` 目录。

package/package.json

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

package/rules/global.md

@@ -36,17 +36,21 @@ name: "通用规则"
 - ⚠️ **定位并修复根因后，必须清理诊断过程中留下的临时改动**（调试代码、临时开关、测试脚本），不要把绕过方案的残留物留在代码里。
 - **某个工具/脚本报错时，先检查是否有残留的锁文件、临时文件、缓存导致的问题**，清理后重试；仍失败再切换备用方案，不要一遇报错就直接换路子。
 - **长任务或涉及截图等大内容的操作，注意控制单次传入的数据量**（压缩、降低分辨率等），避免不必要地占满上下文。
+- ⚠️ **用户反馈"看起来没生效/没写入"时，先用权威数据源核实**（直连数据库/调对应 API 查，而不是只信一次前端页面截图），前端页面可能存在多个同名视图、未展开的关联表、缓存等歧义，容易把"看错了地方"误判成"修复失败"，也可能反过来把真的失败误判成"看错了"——两种方向都要用权威数据源排除，不能靠肉眼猜。
+- ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
 
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- `test` 分支禁止直接提交代码，代码必须通过 PR 合入。commit 必须中文，禁止 `git push --force`。
+- ⚠️ **可评审 PR 的合并目标永远是仓库默认分支（如 `main`/`master`），不是 `test`**。`test` 分支只用于部署测试环境，只能通过 `/deploy-test` skill 直接 `merge` 更新（见「部署规则」），不发 PR、不走 code review；`test` 分支同样禁止直接提交代码。commit 必须中文，禁止 `git push --force`。
+- ⚠️ **提交并推送代码后，若发现与主分支存在冲突，必须主动解决**，不能推送完就算完事、把冲突留给别人处理。
 
 ## PR 核心要求
 
 - ⚠️ PR Title / Description / Test Plan 全部中文。一个 PR 只做一件事。
 - ⚠️ 必须附截图作为可视化证据（前后对比、标注改动区域）。
 - ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
+- ⚠️ **私有仓库的 PR/Issue 正文中插入截图，禁止使用 `raw.githubusercontent.com` 链接，必须使用 `github.com/OWNER/REPO/blob/BRANCH/path?raw=true` 格式。** 原因：`raw.githubusercontent.com` 不识别 GitHub 网页端的登录态（session cookie），GitHub 渲染 PR/Issue 正文图片时走的是 camo 图片代理服务器端匿名拉取——对私有仓库该链接返回 404，导致图片框显示为普通文字链接而非图片；`github.com/.../blob/...?raw=true` 走的是 github.com 主域名，能通过登录态正确鉴权，图片才能正常渲染。凡是「先 `git add -f` 把截图提交进 `screenshots/` 目录、再在 PR 描述里用 Markdown 引用」的流程，图片链接一律拼接为后一种格式。
 
 ## 安全
 
@@ -60,6 +64,11 @@ name: "通用规则"
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
 - ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
+## ⚠️ 数据链路改动核对铁律
+
+- ⚠️ **给一个数据结构（interface/struct/DTO）新增或修改字段后，必须顺着这份数据流转的每一个转发/序列化点逐一核对，不能只改了数据结构定义或链路两端就算完成**。典型漏改位置是中间层"手写请求体字面量"（如 `JSON.stringify({ a, b })`、手动拼接的 `params`/`payload`），新增字段不会自动带过去，也不会报错，只会表现为"下游一直是空的"这种沉默失败。
+- ⚠️ **排查"某个字段一直是空/没生效"类问题时，从数据源头开始逐层核对该字段的值（采集处 → 每一层转发处 → 最终落地处），找到具体在哪一层被丢弃**，禁止只查最终存储位置就下结论。
+
 ## ⚠️ E2E 回归测试铁律
 
 ### 一、登记用例：双文件同步，缺一不可
@@ -102,6 +111,11 @@ name: "通用规则"
 - ⚠️ **截图中必须能看到当前页面 URL**（浏览器地址栏，或页面顶部叠加 URL 标注），确保证据可追溯。
 - **保存到磁盘文件**（`page.screenshot({ path, fullPage: true })`），禁止只用内联展示的截图工具——内联的不落盘，用户无法在 Markdown / HTML 文档里查看。路径统一放 `docs/` 对应功能子目录，文件名用「编号 + 英文描述」（如 `01-login-page.png`）。
 
+### 非 UI / 后端 / 基础设施改动的效果截图获取方法
+
+- 后端接口、基础设施类改动没有传统的前后端 UI diff 时，效果截图可以是：(a) 实际打开受影响页面截图，证明功能正常渲染真实数据；(b) 将 curl 请求/响应对比结果渲染成一个简单的本地 HTML（暗色终端风格），用浏览器截图工具截出来，作为"请求响应"证据图。两者都满足"必须附功能效果截图"的强制要求。
+- ⚠️ **`gh` CLI 没有原生的图片上传能力，禁止把截图提交进功能分支来获取图片链接，也禁止用 `gh gist create --public` 等公开托管服务代替**（未经授权的公开发布）。正确做法：用已登录 GitHub 的 agent-browser CDP 会话打开目标 PR 页面 → 找到评论框下的隐藏 `input[type=file]` → 上传图片 → GitHub 会自动转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并写入评论框文本 → 提交评论使图片持久化（必须先提交评论，图片链接才长期有效）→ 用 `gh pr edit --body-file` 把这些 CDN URL 替换进 PR Description 的占位符位置。详细操作步骤（选择器、提交按钮定位、受控组件输入注意事项）见 `/create-pr` skill。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
@@ -134,16 +148,44 @@ name: "通用规则"
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。
-- ⚠️ 禁止修改 GCLB 配置。
+- ⚠️ 禁止修改 GCLB 配置（原因和替代方案见下方「共享基础设施变更铁律」）。
 - 禁止修改核心业务文件和 API 相关代码。
 - `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。
 
+## ⚠️ 共享基础设施变更铁律
+
+- ⚠️ **问题根因是"某个被多个服务/项目共用的基础设施配置（网关、负载均衡器、DNS、Ingress、防火墙规则、共享中间件/代理配置、共享配置中心 namespace 等）转发或配置错了"时，禁止把"直接改这个共享配置"当作默认修复方案**。共享基础设施上的改动会波及所有依赖它的其他流量/服务，波及范围和风险几乎总是大于当前这一个问题本身。优先方案是在自己服务的边界内收敛解决——如直连正确后端的独立地址、加一层自己控制的适配/转发，而不触碰上游共享设施。
+- ⚠️ **评估后确认必须改共享基础设施本身才能修复时，必须先向用户说明改动内容和影响范围（这份配置还被哪些其他服务/流量依赖），得到明确确认后才能执行**，禁止在诊断过程中把"顺手改一下共享配置"当成常规修复步骤直接执行——这类改动一旦出错，影响的不是一个功能，而是所有依赖这份共享配置的系统。
+
+## 网关/负载均衡 404 排查规范
+
+- ⚠️ **域名访问 404 时，禁止优先假设是 DNS 问题**。DNS 只负责把域名解析到 IP，能解析到正确 IP 但仍 404，说明问题在 IP 之后的路由链路上（负载均衡 / API 网关 / 反向代理的路由规则），必须先排查这一层，而不是重新配置 DNS。
+- 排查顺序（以 GCP GCLB 为例，其他云 / Nginx / API Gateway 同理）：
+  1. 确认域名解析到的 IP 由哪个转发规则（forwarding rule）监听
+  2. 找到该转发规则挂的 target-proxy → url-map
+  3. `describe` 该 url-map，重点看 `defaultService` 和 `hostRules`/`pathMatchers`——**404 常见根因是 url-map 只有 defaultService，指向的后端服务根本没部署这条路径**，而不是网络层不通
+  4. 直连后端服务（跳过网关）验证该路径本身是否存在，确认问题就在"网关路由配置"而非"服务本身"
+- ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。
+- 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。
+
+## 基础设施修复后代码 Workaround 清理规范
+
+- ⚠️ **临时绕过基础设施问题写入代码的 workaround（如硬编码直连地址、绕过网关/域名），修复根因基础设施问题后必须回退代码**，禁止让 workaround 永久留在代码里。基础设施修复完成后应主动排查代码里是否存在对应的临时绕过逻辑并清理。
+- 清理 workaround 时必须新增一条自动化回归测试守住这个退回动作（例如断言代码中不再出现临时硬编码的地址/值），防止未来又因为遇到类似问题而不经排查基础设施就重新引入同样的 workaround。
+- 判断测试失败是否由自己的改动引入：**禁止凭感觉判断**，必须用 `git stash` 暂存改动 → `git checkout` 到基线分支（如 `main`）→ 重跑同一批失败用例 → 对比结果，确认基线分支是否有同样的失败；确认后 `git checkout` 回功能分支 + `git stash pop` 还原改动。只有在基线分支上复现不出的失败，才能认定是自己的改动引入的。
+
 ## 部署规则
 
 - 发版统一执行 `./release.sh`。
 - ⚠️ 部署测试环境必须使用 `/deploy-test` skill。任何包含「部署测试」「发布测试」「上线测试」「部署test」「推到test」「部署到测试环境」等表述的需求，必须先调用 `Skill` 工具加载 `deploy-test`，严禁跳过 skill 直接执行部署操作。
 - ⚠️ 部署测试环境的正确流程是：当前分支 → 合并到 test 分支 → 推送 test → 触发部署 → 切回原分支。禁止直接在 test 分支上提交代码，禁止跳过合并步骤直接部署功能分支。
 
+## ⚠️ 配置中心变更生效铁律
+
+- ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。
+- ⚠️ **重启生产服务前必须获得用户明确确认**，即使目的只是"让配置生效"这种听起来很轻量的操作——重启本身对生产可用性是有影响的，不能因为动机温和就跳过确认。
+- ⚠️ **读取/核对含密钥的配置文件（生产环境尤其）时，禁止 `cat` 或任何会把文件全文打印到终端/日志的方式**，改用程序化方式核对（脚本读取后只处理/打印特定字段名，或用 diff 比较修改前后），避免密钥明文出现在终端记录或对话历史里。
+
 ## 文档规则
 
 - 新建文档使用 HTML 格式（`.html`）、中文文件名，存到 `docs/` 目录。

package/skills/create-pr/SKILL.md

@@ -57,9 +57,15 @@ Closes #issue编号
 
 1. **截修复后**：浏览器打开改动页面 → 滚动到改动区域 → 全页截图
 2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
+   - ⚠️ **若线上数据已变化，导致无法在真实页面复现"修复前"效果**：允许改用等价的纯逻辑对比代替（用新旧两版逻辑代码跑同样的输入数据，把输出结果差异渲染成对比图），但必须在 Description 里明确写清楚"为什么无法复现 + 用了什么替代方案"，禁止因此省略截图或假装能复现。
 3. **生成对比图**：用 sharp 拼接 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域矩形框圈选
-4. **上传 GitHub CDN**：打开 PR 页面 → 评论区 file input 上传 → 获取 `user-attachments` CDN URL
-5. **写入 Description**：`![](CDN_URL)` 内嵌，清理临时评论
+4. **上传 GitHub CDN**：
+   - 打开目标 PR 页面 → 找到评论框下隐藏的 `input[type=file]`（GitHub 当前实现选择器通常是 `#fc-new_comment_field`，选择器失效时用 `snapshot`/`eval` 重新定位，不要死等固定选择器）
+   - 用 `agent-browser upload` 上传本地图片 → GitHub 自动把图片转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并写入评论框文本
+   - 读取评论框内容拿到 CDN URL → 找到并点击提交按钮（`type=submit` 且文本为 `Comment` 的 `button`，例如 `Array.from(document.querySelectorAll('button')).find(b => b.textContent.trim() === 'Comment' && b.type === 'submit')`）**提交评论使图片持久化**（必须先提交评论，图片链接才长期有效）
+   - 若需要在评论框里追加/编辑文字（而非只上传图片），优先用 `agent-browser type` 模拟真实键盘输入——评论框是受控组件，直接用 `eval` 设置 `.value` 不会触发 React 状态更新，提交按钮会一直保持 disabled
+   - ⚠️ **禁止用 `gh gist create --public` 等公开托管服务代替**——这属于未经授权的公开发布
+5. **写入 Description**：`gh pr edit --body-file` 把 CDN URL 替换进占位符位置，`![](CDN_URL)` 内嵌
 
 **截图规范**：
 - ⚠️ 截图禁止提交到 Git 仓库
@@ -69,11 +75,15 @@ Closes #issue编号
 
 ### 5. 创建 PR
 
+⚠️ **`--base` 必须是仓库默认分支，不能硬编码 `main`**——不同仓库默认分支名不同（如 `master`），且可评审 PR 的合并目标永远是默认分支，不是 `test`（`test` 只通过 `/deploy-test` skill 直接 merge 部署，不走 PR review）：
+
 ```bash
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
+
 gh pr create \
   --title "中文标题" \
   --body "中文 Description（含截图 CDN URL）" \
-  --base main \
+  --base "$DEFAULT_BRANCH" \
   --head "$(git branch --show-current)"
 ```