@routerhub/agent-rules 1.5.185 → 1.5.187
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 +35 -0
- package/package.json +1 -1
- package/rules/global.md +35 -0
package/AGENTS.base.md
CHANGED
|
@@ -47,6 +47,41 @@
|
|
|
47
47
|
- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
|
|
48
48
|
- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
|
|
49
49
|
|
|
50
|
+
## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
|
|
51
|
+
|
|
52
|
+
「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——凡是「上线前需要额外动作去做的准备」都可能属此类：新建的定时任务需要手动触发首次初跑、某资源得先在云平台控制台开通、另一个服务得先升级、得提前通知下游团队……这些代码与脚本天然覆盖不到（**上文仅是示例，判断标准见下条，不构成类别边界**）。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
|
|
53
|
+
|
|
54
|
+
- ⚠️ **判断标准：凡是「上线前需要做、但写不进代码/部署脚本」的操作都登记，不受类别限定。** 判断只问一句——「这个改动上线时，有没有一个需要额外动作去做的准备？」（新建了定时任务要手动触发初跑 / 要开通或操作云平台资源 / 要联动升级别的服务 / 要提前通知运营或下游团队 / 上线后要盯某个指标……有，就登记）。能写成代码/部署脚本自动完成的准备仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。
|
|
55
|
+
- ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
|
|
56
|
+
- ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
|
|
57
|
+
- 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
|
|
58
|
+
- 已有文件 → AI 追加/更新对应条目（含状态）；
|
|
59
|
+
- 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
|
|
60
|
+
- ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
|
|
61
|
+
- ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
|
|
62
|
+
- ⚠️ **发版前扫查流程（只看「上次发版 → 本次」的 git 增量，禁止全文通读，也禁止用「我记得这期改动」替代）**：清单随代码走、每次发版都打 tag，因此「本次上线要核对哪些注意项」天然等于清单文件在上次发版与本次之间的 git 增量——用 git 精确界定区间，只核对区间内新增/更新的条目，历史条目（上次及更早已核对过）不在本次范围，无需从头看。步骤：
|
|
63
|
+
1. **定界**：`PREV=$(git describe --tags --abbrev=0)`（取上一个发版 tag；无 tag 时改用上一个「发布 vX.Y.Z」commit）；
|
|
64
|
+
2. **列提交**：`git log $PREV..HEAD --oneline` 列出本次全部提交，先对本期改动有个整体认识；
|
|
65
|
+
3. **取增量条目**：`git diff $PREV..HEAD -- RELEASE_CHECKLIST.md`——本次需要核对的上线准备项只在这些新增/更新的条目里，逐条确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因）；`$PREV..HEAD` 之间该文件无改动 = 本期没有随代码登记的上线准备，直接放行；
|
|
66
|
+
4. **兜底扫 commit 标记**：`git log $PREV..HEAD --format=%B | grep release-prep`——若某个提交标了 `release-prep` 却在清单 diff 里找不到对应条目（标了没登记），当场补齐登记后再发版。
|
|
67
|
+
- ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
|
|
68
|
+
|
|
69
|
+
**清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
|
|
70
|
+
|
|
71
|
+
```markdown
|
|
72
|
+
# 上线前准备清单
|
|
73
|
+
|
|
74
|
+
> 登记「代码/部署脚本里体现不了、但上线时必须有动作」的上线准备项（机制见 AGENTS.base.md「上线前准备清单」章节）。
|
|
75
|
+
> 有上线准备项的 PR，写代码的 AI 随代码在同一个 PR 更新下方表格并提交，commit 带 `release-prep: <一句话>`。
|
|
76
|
+
|
|
77
|
+
| 日期 | 相关 PR/commit | 类别 | 上线准备项（含如何手动触发 / 在哪看 / 找谁） | 状态 | 备注 |
|
|
78
|
+
|---|---|---|---|---|---|
|
|
79
|
+
| YYYY-MM-DD | #PR / commit | 定时任务 | 新建 cron 并手动触发首次初跑 | ✅ | |
|
|
80
|
+
|
|
81
|
+
<!-- 维护约定：待办必须写在状态列，形如 `| ⬜ |`（发版脚本只扫描带管道边界的 ⬜，说明性文字不触发）。
|
|
82
|
+
无待办时全文件不得存在 `| ⬜ |` 行 -->
|
|
83
|
+
```
|
|
84
|
+
|
|
50
85
|
## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
|
|
51
86
|
|
|
52
87
|
- ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
|
package/package.json
CHANGED
package/rules/global.md
CHANGED
|
@@ -47,6 +47,41 @@ name: "通用规则"
|
|
|
47
47
|
- ⚠️ **部署完成的定义 = 脚本执行完 → 功能直接可用 → 期间零人工补操作。** 未满足「零人工补操作」的部署不算完成，禁止在还需手动补步骤时宣称部署完成。
|
|
48
48
|
- ⚠️ **「部署可用」≠「功能已验证」**：部署自动化到位只保证环境就绪、功能直接可操作；功能是否正确，仍需按既有验证铁律用真实数据验证，两者不冲突。
|
|
49
49
|
|
|
50
|
+
## ⚠️ 上线前准备清单（AI 写代码时自动登记「代码里体现不了的上线准备」）
|
|
51
|
+
|
|
52
|
+
「可部署性自包含铁律」要求所有上线准备内嵌部署脚本、上线只跑脚本零人工补操作。但**并非所有上线准备都能写进代码/部署脚本**——凡是「上线前需要额外动作去做的准备」都可能属此类：新建的定时任务需要手动触发首次初跑、某资源得先在云平台控制台开通、另一个服务得先升级、得提前通知下游团队……这些代码与脚本天然覆盖不到（**上文仅是示例，判断标准见下条，不构成类别边界**）。这类准备不登记，上线必漏。**本规则把登记动作交给写代码的 AI 自动完成：规则随发版分发到各仓库后，AI 每次写需求/改代码都会自查是否引入此类准备并当场登记——不需要仓库预置任何文件、不需要任何人拷贝模板。**
|
|
53
|
+
|
|
54
|
+
- ⚠️ **判断标准：凡是「上线前需要做、但写不进代码/部署脚本」的操作都登记，不受类别限定。** 判断只问一句——「这个改动上线时，有没有一个需要额外动作去做的准备？」（新建了定时任务要手动触发初跑 / 要开通或操作云平台资源 / 要联动升级别的服务 / 要提前通知运营或下游团队 / 上线后要盯某个指标……有，就登记）。能写成代码/部署脚本自动完成的准备仍按自包含铁律内嵌脚本，禁止偷懒登记进清单当借口——两条机制互补、不重叠。
|
|
55
|
+
- ⚠️ **登记是 AI 写需求/改代码流程的一部分（本规则执行者 = 写代码的 AI，不是人的手工职责）**：实现需求时逐项自查「本次改动上线时，有没有一个写不进代码/部署脚本、但上线时必须有动作去做的准备？」命中 → **当场登记，禁止留到发版时靠回忆补**（过了写代码那一刻，连当事人都容易忘）。条目须含可执行信息：什么动作 / 怎么手动触发 / 在哪看 / 找谁。
|
|
56
|
+
- ⚠️ **载体：仓库根目录 `RELEASE_CHECKLIST.md`，由 AI 自动创建与维护，无需预置**：
|
|
57
|
+
- 仓库尚无该文件且本次命中 → AI 按本节末尾「清单格式」自动生成，随**同一个 PR** 提交；
|
|
58
|
+
- 已有文件 → AI 追加/更新对应条目（含状态）；
|
|
59
|
+
- 无任何此类项的仓库 → 不生成该文件，发版时扫不到即代表本期无特殊准备。
|
|
60
|
+
- ⚠️ **commit 标记约定（发版索引通道）**：改动引入需登记的上线准备项时，commit message 必须带 `release-prep: <一句话>` 标记，使发版时能用 `git log 上次发版tag..HEAD --format=%B | grep release-prep` 机械扫出全部需注意的提交——把「发版时读代码猜」换成「写代码的 AI 当场写、发版机械扫」，来源可靠、不会漏。
|
|
61
|
+
- ⚠️ **code review 有义务核对登记**：reviewer 读 PR 时须确认「本次改动是否引入了需登记的上线准备项」；引入了而 PR 未同步更新 `RELEASE_CHECKLIST.md`、commit 未带 `release-prep:` → 报错。
|
|
62
|
+
- ⚠️ **发版前扫查流程（只看「上次发版 → 本次」的 git 增量，禁止全文通读，也禁止用「我记得这期改动」替代）**：清单随代码走、每次发版都打 tag，因此「本次上线要核对哪些注意项」天然等于清单文件在上次发版与本次之间的 git 增量——用 git 精确界定区间，只核对区间内新增/更新的条目，历史条目（上次及更早已核对过）不在本次范围，无需从头看。步骤：
|
|
63
|
+
1. **定界**：`PREV=$(git describe --tags --abbrev=0)`（取上一个发版 tag；无 tag 时改用上一个「发布 vX.Y.Z」commit）；
|
|
64
|
+
2. **列提交**：`git log $PREV..HEAD --oneline` 列出本次全部提交，先对本期改动有个整体认识；
|
|
65
|
+
3. **取增量条目**：`git diff $PREV..HEAD -- RELEASE_CHECKLIST.md`——本次需要核对的上线准备项只在这些新增/更新的条目里，逐条确认状态（✅ 已完成 / 本次上线执行 / 🚫 跳过并注明原因）；`$PREV..HEAD` 之间该文件无改动 = 本期没有随代码登记的上线准备，直接放行；
|
|
66
|
+
4. **兜底扫 commit 标记**：`git log $PREV..HEAD --format=%B | grep release-prep`——若某个提交标了 `release-prep` 却在清单 diff 里找不到对应条目（标了没登记），当场补齐登记后再发版。
|
|
67
|
+
- ⚠️ **发版脚本硬闸（有发版/上线脚本的仓库）**：脚本应内置检查——`RELEASE_CHECKLIST.md` 存在时不得有待办条目（状态列为 `| ⬜ |`），否则中止发版。agent-rules 仓库 `release.sh` 已示范实现（`check_release_prep`，与「规则漂移检查」同层，在版本号递增前执行），各仓库照此内嵌，不做预置要求。
|
|
68
|
+
|
|
69
|
+
**清单格式（AI 首次登记时照此在仓库根目录自动创建 `RELEASE_CHECKLIST.md`，表格列固定）：**
|
|
70
|
+
|
|
71
|
+
```markdown
|
|
72
|
+
# 上线前准备清单
|
|
73
|
+
|
|
74
|
+
> 登记「代码/部署脚本里体现不了、但上线时必须有动作」的上线准备项（机制见 AGENTS.base.md「上线前准备清单」章节）。
|
|
75
|
+
> 有上线准备项的 PR，写代码的 AI 随代码在同一个 PR 更新下方表格并提交，commit 带 `release-prep: <一句话>`。
|
|
76
|
+
|
|
77
|
+
| 日期 | 相关 PR/commit | 类别 | 上线准备项（含如何手动触发 / 在哪看 / 找谁） | 状态 | 备注 |
|
|
78
|
+
|---|---|---|---|---|---|
|
|
79
|
+
| YYYY-MM-DD | #PR / commit | 定时任务 | 新建 cron 并手动触发首次初跑 | ✅ | |
|
|
80
|
+
|
|
81
|
+
<!-- 维护约定：待办必须写在状态列，形如 `| ⬜ |`（发版脚本只扫描带管道边界的 ⬜，说明性文字不触发）。
|
|
82
|
+
无待办时全文件不得存在 `| ⬜ |` 行 -->
|
|
83
|
+
```
|
|
84
|
+
|
|
50
85
|
## ⚠️ 测试环境功能验证前置铁律（防止缺表报错误判为代码问题）
|
|
51
86
|
|
|
52
87
|
- ⚠️ **在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。** 测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建。跳过这一步直接验证，报出的缺表/缺字段错误是环境问题，不是代码问题，极易误判。
|