@routerhub/agent-rules 1.5.184 → 1.5.186
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.
- package/AGENTS.base.md +40 -0
- package/package.json +1 -1
- package/rules/global.md +40 -0
- package/skills/create-pr/SKILL.md +1 -0
package/AGENTS.base.md
CHANGED
|
@@ -47,6 +47,45 @@
|
|
|
47
47
|
- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
|
|
48
48
|
- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
|
|
49
49
|
|
|
50
|
+
## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
|
|
51
|
+
|
|
52
|
+
「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——新建定时任务（cron / Cloud Scheduler / Job）并安排首次触发、只能在云平台控制台手动操作、跨仓库的部署顺序依赖、需先通知下游团队等，代码与脚本天然覆盖不到。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
|
|
53
|
+
|
|
54
|
+
- ⚠️ **判断标准：只登记「自包含兜不住」的。** 能写成代码/部署脚本自动完成的准备，仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。常见「兜不住」类别：
|
|
55
|
+
- **定时/后台任务**：新建 cron / Cloud Scheduler / Job、上线后需首次手动触发、频率/开关需与生产环境人工核对（代码里通常只有任务定义，没有「谁去建、何时触发」）
|
|
56
|
+
- **云平台手动操作**：无法 IaC 化的资源、需人工在控制台点选确认
|
|
57
|
+
- **部署顺序依赖**：必须先升级/先就位某外部依赖（常跨仓库，本次 git 历史看不出）
|
|
58
|
+
- **跨团队/跨系统动作**：上线前需通知/协调下游仓库、运营、其他团队；共享基础设施变更需先获确认
|
|
59
|
+
- **上线后观察点**：上线后需盯的指标、需手动跑一遍的验证
|
|
60
|
+
- ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
|
|
61
|
+
- ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
|
|
62
|
+
- 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
|
|
63
|
+
- 已有文件 → AI 追加/更新对应条目（含状态）；
|
|
64
|
+
- 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
|
|
65
|
+
- ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
|
|
66
|
+
- ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
|
|
67
|
+
- ⚠️ **发版前扫查流程（每次上线/发版必做，禁止用「我记得这期改动」替代）**：
|
|
68
|
+
1. 用 `git log $(git describe --tags --abbrev=0)..HEAD --format=%B`（无 tag 时改用上一个「发布 vX.Y.Z」commit）列出本次全部提交；
|
|
69
|
+
2. 扫描其中的 `release-prep` 标记，逐个找到清单对应条目核对（无清单文件且无标记 = 本期无特殊准备，正常放行）；
|
|
70
|
+
3. 通读 `RELEASE_CHECKLIST.md`（若存在）全文，逐项确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因），确认无遗漏后才允许发版。
|
|
71
|
+
- ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
|
|
72
|
+
|
|
73
|
+
**清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
|
|
74
|
+
|
|
75
|
+
```markdown
|
|
76
|
+
# 上线前准备清单
|
|
77
|
+
|
|
78
|
+
> 登记「代码/部署脚本里体现不了、但上线时必须有动作」的上线准备项（机制见 AGENTS.base.md「上线前准备清单」章节）。
|
|
79
|
+
> 有上线准备项的 PR，写代码的 AI 随代码在同一个 PR 更新下方表格并提交，commit 带 `release-prep: <一句话>`。
|
|
80
|
+
|
|
81
|
+
| 日期 | 相关 PR/commit | 类别 | 上线准备项（含如何手动触发 / 在哪看 / 找谁） | 状态 | 备注 |
|
|
82
|
+
|---|---|---|---|---|---|
|
|
83
|
+
| YYYY-MM-DD | #PR / commit | 定时任务 | 新建 cron 并手动触发首次初跑 | ✅ | |
|
|
84
|
+
|
|
85
|
+
<!-- 维护约定：待办必须写在状态列，形如 `| ⬜ |`（发版脚本只扫描带管道边界的 ⬜，说明性文字不触发）。
|
|
86
|
+
无待办时全文件不得存在 `| ⬜ |` 行 -->
|
|
87
|
+
```
|
|
88
|
+
|
|
50
89
|
## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
|
|
51
90
|
|
|
52
91
|
- ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
|
|
@@ -159,6 +198,7 @@
|
|
|
159
198
|
- **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
|
|
160
199
|
- **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
|
|
161
200
|
- **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
|
|
201
|
+
- **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
|
|
162
202
|
- **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
|
|
163
203
|
- ⚠️ PR Title / Description / Test Plan 全部中文。
|
|
164
204
|
- ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：
|
package/package.json
CHANGED
package/rules/global.md
CHANGED
|
@@ -47,6 +47,45 @@ name: "通用规则"
|
|
|
47
47
|
- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
|
|
48
48
|
- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
|
|
49
49
|
|
|
50
|
+
## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
|
|
51
|
+
|
|
52
|
+
「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——新建定时任务（cron / Cloud Scheduler / Job）并安排首次触发、只能在云平台控制台手动操作、跨仓库的部署顺序依赖、需先通知下游团队等，代码与脚本天然覆盖不到。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
|
|
53
|
+
|
|
54
|
+
- ⚠️ **判断标准：只登记「自包含兜不住」的。** 能写成代码/部署脚本自动完成的准备，仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。常见「兜不住」类别：
|
|
55
|
+
- **定时/后台任务**：新建 cron / Cloud Scheduler / Job、上线后需首次手动触发、频率/开关需与生产环境人工核对（代码里通常只有任务定义，没有「谁去建、何时触发」）
|
|
56
|
+
- **云平台手动操作**：无法 IaC 化的资源、需人工在控制台点选确认
|
|
57
|
+
- **部署顺序依赖**：必须先升级/先就位某外部依赖（常跨仓库，本次 git 历史看不出）
|
|
58
|
+
- **跨团队/跨系统动作**：上线前需通知/协调下游仓库、运营、其他团队；共享基础设施变更需先获确认
|
|
59
|
+
- **上线后观察点**：上线后需盯的指标、需手动跑一遍的验证
|
|
60
|
+
- ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
|
|
61
|
+
- ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
|
|
62
|
+
- 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
|
|
63
|
+
- 已有文件 → AI 追加/更新对应条目（含状态）；
|
|
64
|
+
- 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
|
|
65
|
+
- ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
|
|
66
|
+
- ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
|
|
67
|
+
- ⚠️ **发版前扫查流程（每次上线/发版必做，禁止用「我记得这期改动」替代）**：
|
|
68
|
+
1. 用 `git log $(git describe --tags --abbrev=0)..HEAD --format=%B`（无 tag 时改用上一个「发布 vX.Y.Z」commit）列出本次全部提交；
|
|
69
|
+
2. 扫描其中的 `release-prep` 标记，逐个找到清单对应条目核对（无清单文件且无标记 = 本期无特殊准备，正常放行）；
|
|
70
|
+
3. 通读 `RELEASE_CHECKLIST.md`（若存在）全文，逐项确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因），确认无遗漏后才允许发版。
|
|
71
|
+
- ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
|
|
72
|
+
|
|
73
|
+
**清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
|
|
74
|
+
|
|
75
|
+
```markdown
|
|
76
|
+
# 上线前准备清单
|
|
77
|
+
|
|
78
|
+
> 登记「代码/部署脚本里体现不了、但上线时必须有动作」的上线准备项（机制见 AGENTS.base.md「上线前准备清单」章节）。
|
|
79
|
+
> 有上线准备项的 PR，写代码的 AI 随代码在同一个 PR 更新下方表格并提交，commit 带 `release-prep: <一句话>`。
|
|
80
|
+
|
|
81
|
+
| 日期 | 相关 PR/commit | 类别 | 上线准备项（含如何手动触发 / 在哪看 / 找谁） | 状态 | 备注 |
|
|
82
|
+
|---|---|---|---|---|---|
|
|
83
|
+
| YYYY-MM-DD | #PR / commit | 定时任务 | 新建 cron 并手动触发首次初跑 | ✅ | |
|
|
84
|
+
|
|
85
|
+
<!-- 维护约定：待办必须写在状态列，形如 `| ⬜ |`（发版脚本只扫描带管道边界的 ⬜，说明性文字不触发）。
|
|
86
|
+
无待办时全文件不得存在 `| ⬜ |` 行 -->
|
|
87
|
+
```
|
|
88
|
+
|
|
50
89
|
## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
|
|
51
90
|
|
|
52
91
|
- ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
|
|
@@ -159,6 +198,7 @@ name: "通用规则"
|
|
|
159
198
|
- **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
|
|
160
199
|
- **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。
|
|
161
200
|
- **制作与托管**：文档按「⚠️ 文档规则」章节流程生成与托管：截图版 HTML → 无头 Chrome 转 PDF → push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支，链接统一用 `https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf` 格式（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。文档生成统一走 `/create-doc` skill，PR 创建统一走 `/create-pr` skill（内含本链接的制作与置顶步骤）。
|
|
201
|
+
- **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：文档里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
|
|
162
202
|
- **适用范围**：所有 PR 一律附此链接，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分。
|
|
163
203
|
- ⚠️ PR Title / Description / Test Plan 全部中文。
|
|
164
204
|
- ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：
|
|
@@ -79,6 +79,7 @@ Closes #issue编号
|
|
|
79
79
|
⚠️ **每个 PR 的 Description 顶部必须附一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：PR 正文只承载 What / Why / Test Plan 精华 + 关键效果截图（几十秒看懂这次改了什么）；链接指向的 PDF 承载「做了什么 + 为什么这样做 + 每一步怎么做的」完整过程，并配上带箭头标注的真实截图。想深入细节的 reviewer 点开链接即看；禁止在正文里翻流水账，也禁止只有正文、缺详细文档链接。
|
|
80
80
|
|
|
81
81
|
1. **汇总素材**：本 PR 的「改了什么 + 为什么改 + 每一步怎么改/怎么验证」，以及步骤 4 产出的全部效果截图（含修复前后对比）。
|
|
82
|
+
- ⚠️ **素材取材优先级：前端可视化优先，纯逻辑才退而用代码/接口图**：讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明**——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
|
|
82
83
|
2. **生成截图版 HTML → 转 PDF**：走 `/create-doc` skill 输出自包含 HTML——截图一律 `data:image/png;base64` 内嵌并自动加箭头标注（遵循「⚠️ 截图规范」「⚠️ HTML 文档截图与 curl 命令规范」），图文逐步说明每一步怎么做的；再经无头 Chrome 转 PDF。
|
|
83
84
|
3. **托管到私有文档仓库**：push 到该项目的 `<项目>-docs` 私有仓库 `docs` 分支（仓库名从 git remote 推导：`git@github.com:<ORG>/<项目>.git` → 文档仓库 `<ORG>/<项目>-docs`），文件名用与 PR 主题相关的英文短名。
|
|
84
85
|
4. **拿链接**：`https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf`（GitHub 原生渲染 PDF；私有仓库未登录会跳登录页）。
|