@routerhub/agent-rules 1.5.203 → 1.5.204
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 +18 -0
- package/CHANGELOG.md +12 -0
- package/PULL_REQUEST_TEMPLATE.md +24 -0
- package/package.json +1 -1
- package/rules/global.md +18 -0
- package/skills/create-pr/SKILL.md +8 -0
- package/skills/pr-release-loop/SKILL.md +6 -5
package/AGENTS.base.md
CHANGED
|
@@ -133,8 +133,26 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
|
|
|
133
133
|
- ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
|
|
134
134
|
- ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
|
|
135
135
|
|
|
136
|
+
## ⚠️ 缺陷复现铁律（先复现，再动手改）
|
|
137
|
+
|
|
138
|
+
- ⚠️ **核心认知：不复现就改 = 你不知道原来到底有没有这个问题、是不是这个原因。** 照着描述直接改代码，改完无法区分三种情况：① 真修好了；② 问题根本不在这、改动与真问题无关；③ 问题本来就不复现（描述有误 / 已被别的改动顺手修掉 / 环境或数据不同）。这三种情况从「改完看起来没事」里分辨不出来——**没有复现，「修好了」这句话就没有依据**。判断标准：**凡本次改动是为了修一个 bug / 故障 / 线上异常（而不是新增功能、重构、文案、依赖升级），动手改代码之前必须先复现；复现不出来不许改。**
|
|
139
|
+
- ⚠️ **顺序是硬的，禁止颠倒：① 复现 → ② 留证并写下来 → ③ 改代码 → ④ 用同一条路径复验。** 跳过 ①② 直接 ③，就是拿「想象中的问题」当修复目标。
|
|
140
|
+
- ⚠️ **复现必须在「改动前的代码」上做**（线上 / 测试环境当前版本，或打补丁前的那个 commit）。改完之后跑出来的现象证明不了改动前有同样的问题——**改完再回来说「我复现过了」不算数**。
|
|
141
|
+
- ⚠️ **复现三要素缺一不可，这就是要「非常详细地写上去」的内容：**
|
|
142
|
+
1. **环境与版本**：哪个环境（生产 / 测试 / 本地）、哪个 commit 或 revision、用哪个账号 / 哪条数据（具体到 ID）；
|
|
143
|
+
2. **可被别人照着做的操作步骤**：点哪个按钮、发哪条请求（参数写全，禁止用 `...` 省略）、按什么顺序——**标准是别人拿到这几行就能一步步重演**，而不是只有你自己看得懂；
|
|
144
|
+
3. **观测到的坏现象**：报错原文、HTTP 状态码、日志片段、页面截图，带时间戳或 request id 之类可复查的标识。**「有时候会出问题」「偶尔失败」不合格——必须能指出出问题的是哪一次。**
|
|
145
|
+
- ⚠️ **复现步骤与修复后的验证步骤必须是同一套——这是 A/B 对照能成立的唯一前提。** 同一条路径跑两遍：第一遍看到坏现象（A = 改动前），第二遍看到好现象（B = 改动后），两者之间只差你这次改动，这才证明了「是这个改动修好的」。两次走的路径不一样 = 没对照（详见「⚠️ 修复验证铁律」）。
|
|
146
|
+
- ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
|
|
147
|
+
- ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
|
|
148
|
+
- ⚠️ **复现证据必须写进 PR 描述（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能自己照着重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
|
|
149
|
+
- **类比：看病。医生不会听你说一句「我头疼」就直接开止痛药——先做检查（复现）确认到底是什么病、是不是这个病，拿到检查报告（证据），再开药（改代码）。检查下来一切正常，那说明你说的「头疼」可能不是你以为的那个原因，得回去问清楚，而不是照着头疼开药；照着症状开药，病没治好，还耽误了真病因。**
|
|
150
|
+
- ⚠️ **与相邻铁律的分工**：本铁律管「改之前证明问题存在」；「⚠️ 修复验证铁律」管「改之后证明问题消失」；「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」。三者是**同一条路径**在时间轴上不同位置各跑一次：复现（改前）→ 复验（改后）→ 链路验收（上线前整条链路）。
|
|
151
|
+
- ⚠️ **例外（可以不先复现的只有这几类，除此之外一律先复现）**：① 本次不是修 bug 的改动（新增功能、重构、文案、依赖升级）；② 问题现象本身已带完整证据（用户给的截图里有报错原文 + 时间戳 + 账号，等同于已复现——此时仍需按上面三要素把它整理成「可重演步骤」写进 PR）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。
|
|
152
|
+
|
|
136
153
|
## ⚠️ 修复验证铁律
|
|
137
154
|
|
|
155
|
+
- ⚠️ **本铁律管「改之后」，「改之前」见「⚠️ 缺陷复现铁律」——先复现拿到改动前的坏现象证据，改完用同一条路径复验，A/B 对照才成立。**
|
|
138
156
|
- ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
|
|
139
157
|
- ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
|
|
140
158
|
- ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。
|
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
|
|
4
4
|
|
|
5
|
+
## [1.5.204] - 2026-09-10
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **新增「缺陷复现铁律（先复现，再动手改）」**：补上原有验证体系缺的一半——「⚠️ 修复验证铁律」管的是「改之后证明问题消失」，但没有任何规则要求「改之前先证明问题存在」。后果是照着描述直接改代码，改完分不清三种情况：① 真修好了；② 问题根本不在这、改动与真问题无关；③ 问题本来就不复现（描述有误 / 已被别的改动顺手修掉 / 环境数据不同）——**这三种从「改完看起来没事」里分辨不出来，没有复现，「修好了」就没有依据**。规则给出硬顺序（① 复现 → ② 留证并写下来 → ③ 改代码 → ④ 用同一条路径复验）、复现三要素（环境与版本 / 可被别人照着重演的操作步骤 / 带时间戳或 request id 的坏现象）、三条关键约束：**必须在改动前的代码上复现**（改完再补的不算）、**复现步骤与修复后验证步骤必须同一套**（否则 A/B 对照不成立）、**复现不出来必须回去对口径，禁止「按理解先改」**（按想象改 = 改动与真问题无关、PR 里却写着已修复）。另附与相邻两条铁律的分工（复现管改前 / 修复验证管改后 / 链路验收管整条链路，同一条路径在时间轴不同位置各跑一次）。
|
|
10
|
+
- **PR 模板新增「缺陷复现」栏目**（置于 Description 之后）：修 bug / 修故障的 PR 必须填 ① 复现证据（改动前的代码上跑出来的：环境与版本、可重演步骤、带可复查标识的坏现象）② 用同一套步骤复验后坏现象消失；非修 bug 的（新增功能 / 重构 / 文案 / 依赖升级）勾选豁免项。Checklist 同步新增一项。**作用与「跨系统链路验收」栏目一致：把复现从「作者本机跑过一次」变成 PR 里留痕、reviewer 能看见并自己重跑一遍确认。**
|
|
11
|
+
- `create-pr` skill 的 Description 模板新增「缺陷复现」段；`pr-release-loop` skill 完成定义清单新增一项（修 bug 的 PR 必须已填「缺陷复现」栏目）。
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- **`create-pr` skill 步骤 4 收紧「截修复前」的做法**：原文允许「临时回退代码 → 截图」得到修复前效果，但**修 bug 的 PR 这样做只是摆拍**——它证明的是「代码改回去长这样」，不是「用户当时遇到的就是这个」。现在明确：修 bug 的「修复前」截图必须来自在未改动代码上的真实复现（同时就是「缺陷复现」栏目的证据），回退代码截图仅用于把界面位置截对齐，不能替代复现。
|
|
16
|
+
|
|
5
17
|
## [1.5.203] - 2026-09-10
|
|
6
18
|
|
|
7
19
|
### Changed
|
package/PULL_REQUEST_TEMPLATE.md
CHANGED
|
@@ -7,6 +7,29 @@
|
|
|
7
7
|
|
|
8
8
|
Closes #
|
|
9
9
|
|
|
10
|
+
## 缺陷复现
|
|
11
|
+
|
|
12
|
+
<!-- 仅「修 bug / 修故障 / 修线上异常」的 PR 需要填（新增功能、重构、文案、依赖升级直接勾豁免项）。
|
|
13
|
+
依据 AGENTS.base.md「⚠️ 缺陷复现铁律」：必须先复现、留证、写下来，再动手改。
|
|
14
|
+
⚠️ 复现必须在【改动前的代码】上做（线上/测试环境当前版本，或打补丁前的 commit），改完再补的「复现」不算。 -->
|
|
15
|
+
|
|
16
|
+
- [ ] 本次 PR **不是**修 bug（新增功能 / 重构 / 文案 / 依赖升级），无需缺陷复现
|
|
17
|
+
|
|
18
|
+
**① 复现证据（改动前的代码上跑出来的）**
|
|
19
|
+
|
|
20
|
+
- **环境与版本**：<环境（生产/测试/本地） + commit 或 revision + 账号 / 数据 ID>
|
|
21
|
+
- **操作步骤**（别人照着能一步步重演，禁止省略参数）：
|
|
22
|
+
1.
|
|
23
|
+
2.
|
|
24
|
+
3.
|
|
25
|
+
- **观测到的坏现象**：<报错原文 / HTTP 状态码 / 日志片段 / 截图，带时间戳或 request id>
|
|
26
|
+
- ⚠️「偶尔会出问题」不合格——必须能指出出问题的是哪一次。
|
|
27
|
+
|
|
28
|
+
**② 修复后用同一条路径复验**
|
|
29
|
+
|
|
30
|
+
- [ ] 已用 ① 的**同一套步骤**重跑一遍，坏现象消失（两次路径不一致 = A/B 对照不成立）
|
|
31
|
+
- **复验结果**：<改后观测到什么，同样带可复查标识>
|
|
32
|
+
|
|
10
33
|
## 跨系统链路验收
|
|
11
34
|
|
|
12
35
|
<!-- 先判断是否命中 AGENTS.base.md「⚠️ 跨系统真实链路验收铁律」的 4 条触发条件（改动跨系统/跨仓库、新增默认值类字段、涉及金额/路由/权限/限流、新增表字段参与对外可见判定）。 -->
|
|
@@ -46,6 +69,7 @@ Closes #
|
|
|
46
69
|
- [ ] 一个 PR 只做一件事，无夹带无关改动
|
|
47
70
|
- [ ] Description 已说明 What / Why / How
|
|
48
71
|
- [ ] Test Plan 完整且带证据
|
|
72
|
+
- [ ] 修 bug 的 PR 已按「缺陷复现」栏目写下改动前的复现证据（非修 bug 的已勾选豁免项）
|
|
49
73
|
- [ ] 跨系统链路验收已按上方栏目填完（未命中触发条件则勾选豁免项）
|
|
50
74
|
- [ ] UI 改动已贴截图（或注明无界面变化）
|
|
51
75
|
- [ ] 本地编译 / lint / 测试通过，CI 全绿
|
package/package.json
CHANGED
package/rules/global.md
CHANGED
|
@@ -133,8 +133,26 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
|
|
|
133
133
|
- ⚠️ **停用/归档任何仍可能被其他配置引用的共享资源（数据库、开关、服务实例、旧接口等）前，必须先确认所有引用方已经完成切换**，禁止先下线资源、后补救引用；正确顺序是「新资源就位 → 所有引用方切到新资源并验证 → 确认无引用后才下线旧资源」。
|
|
134
134
|
- ⚠️ **对「只增不改」的追加型数据表（日志表、流水表）做分批消费时，禁止用「每次从头查 + LIMIT 截断 + 幂等去重」的无状态写法**。无断点的全量查询每次都会返回最早的一批行（早已消费、被幂等跳过、不产生任何效果），而新行永远排在 LIMIT 之外——扣款/同步在数据量超过单批上限后静默停滞，不报错、不崩溃，余额/进度「悄悄不涨不降」，是最阴险的静默 bug（offset-pagination 饥荒）。正确写法是带「进度断点」的增量查询：**按业务排序键（如时间+ID）记录上次消费位置（游标），下轮用 `WHERE 排序键 > 断点` 的严格排他下界续拉，消费成功后游标单调推进到批次末尾**，保证不重也不漏。判断标准：只要处理逻辑会「跳过已处理的记录」且「数据量可能超过单批上限」，就必须用游标/断点，而非从头扫。
|
|
135
135
|
|
|
136
|
+
## ⚠️ 缺陷复现铁律（先复现，再动手改）
|
|
137
|
+
|
|
138
|
+
- ⚠️ **核心认知：不复现就改 = 你不知道原来到底有没有这个问题、是不是这个原因。** 照着描述直接改代码，改完无法区分三种情况：① 真修好了；② 问题根本不在这、改动与真问题无关；③ 问题本来就不复现（描述有误 / 已被别的改动顺手修掉 / 环境或数据不同）。这三种情况从「改完看起来没事」里分辨不出来——**没有复现，「修好了」这句话就没有依据**。判断标准：**凡本次改动是为了修一个 bug / 故障 / 线上异常（而不是新增功能、重构、文案、依赖升级），动手改代码之前必须先复现；复现不出来不许改。**
|
|
139
|
+
- ⚠️ **顺序是硬的，禁止颠倒：① 复现 → ② 留证并写下来 → ③ 改代码 → ④ 用同一条路径复验。** 跳过 ①② 直接 ③，就是拿「想象中的问题」当修复目标。
|
|
140
|
+
- ⚠️ **复现必须在「改动前的代码」上做**（线上 / 测试环境当前版本，或打补丁前的那个 commit）。改完之后跑出来的现象证明不了改动前有同样的问题——**改完再回来说「我复现过了」不算数**。
|
|
141
|
+
- ⚠️ **复现三要素缺一不可，这就是要「非常详细地写上去」的内容：**
|
|
142
|
+
1. **环境与版本**：哪个环境（生产 / 测试 / 本地）、哪个 commit 或 revision、用哪个账号 / 哪条数据（具体到 ID）；
|
|
143
|
+
2. **可被别人照着做的操作步骤**：点哪个按钮、发哪条请求（参数写全，禁止用 `...` 省略）、按什么顺序——**标准是别人拿到这几行就能一步步重演**，而不是只有你自己看得懂；
|
|
144
|
+
3. **观测到的坏现象**：报错原文、HTTP 状态码、日志片段、页面截图，带时间戳或 request id 之类可复查的标识。**「有时候会出问题」「偶尔失败」不合格——必须能指出出问题的是哪一次。**
|
|
145
|
+
- ⚠️ **复现步骤与修复后的验证步骤必须是同一套——这是 A/B 对照能成立的唯一前提。** 同一条路径跑两遍：第一遍看到坏现象（A = 改动前），第二遍看到好现象（B = 改动后），两者之间只差你这次改动，这才证明了「是这个改动修好的」。两次走的路径不一样 = 没对照（详见「⚠️ 修复验证铁律」）。
|
|
146
|
+
- ⚠️ **复现不出来 → 停下来回到描述方对口径，禁止「复现不出来那我按理解先改」。** 按描述的步骤复现不出来，说明「问题到底是什么」这件事本身还没对齐：可能理解错了现象、可能真正的触发入口是另一个、可能已经被别的改动修掉、可能环境或数据形态不同。此时正确动作是带着证据回去对齐——**「我按你说的步骤做了，看到的是 X 而不是 Y，能不能确认下当时的环境 / 账号 / 时间点」**——而不是照着自己想象改一遍交差。按想象改的后果：改动与真问题无关，PR 里却写着「已修复」，等用户再碰到时，这一轮排查和后面所有 review 全部白费。
|
|
147
|
+
- ⚠️ **复现要用真实触发场景的数据和路径，禁止自己造一个顺手能触发的输入。** 造出来的输入只能复现你想象的那个问题，不是用户真实碰到的那个——真实数据的边界形态（空值、超长文本、特殊字符、异常关联、旧状态记录）恰恰是问题的来源（呼应「⚠️ 验证功能是否修复时，要用真实存在的数据/路径去测试」）。
|
|
148
|
+
- ⚠️ **复现证据必须写进 PR 描述（PR 模板已内置「缺陷复现」栏目），不写等于没复现。** 这一栏是给 reviewer 看的：他据此判断「这个改动确实是对着这个现象去的」，也能自己照着重跑一遍确认修好了。只有作者本机跑过一次、PR 里一个字没有 = 这一环做了也没人知道。
|
|
149
|
+
- **类比：看病。医生不会听你说一句「我头疼」就直接开止痛药——先做检查（复现）确认到底是什么病、是不是这个病，拿到检查报告（证据），再开药（改代码）。检查下来一切正常，那说明你说的「头疼」可能不是你以为的那个原因，得回去问清楚，而不是照着头疼开药；照着症状开药，病没治好，还耽误了真病因。**
|
|
150
|
+
- ⚠️ **与相邻铁律的分工**：本铁律管「改之前证明问题存在」；「⚠️ 修复验证铁律」管「改之后证明问题消失」；「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」。三者是**同一条路径**在时间轴上不同位置各跑一次：复现（改前）→ 复验（改后）→ 链路验收（上线前整条链路）。
|
|
151
|
+
- ⚠️ **例外（可以不先复现的只有这几类，除此之外一律先复现）**：① 本次不是修 bug 的改动（新增功能、重构、文案、依赖升级）；② 问题现象本身已带完整证据（用户给的截图里有报错原文 + 时间戳 + 账号，等同于已复现——此时仍需按上面三要素把它整理成「可重演步骤」写进 PR）；③ 用户明确说「不用复现，直接改」——按用户指令执行，但交付时必须说明本次跳过了复现。
|
|
152
|
+
|
|
136
153
|
## ⚠️ 修复验证铁律
|
|
137
154
|
|
|
155
|
+
- ⚠️ **本铁律管「改之后」，「改之前」见「⚠️ 缺陷复现铁律」——先复现拿到改动前的坏现象证据，改完用同一条路径复验，A/B 对照才成立。**
|
|
138
156
|
- ⚠️ **验证方法必须"可确定性复现"，优先选最直白的路径。** 不要依赖真实流量、后台任务或时序巧合去凑出被验证的状态（反直觉、难复现、别人无法照做）。判断顺序：先问「本次修复的唯一改动是什么」，把它精确映射成一个可手动触发的原子操作，再做 A/B 对照。例：验证"余额变更后网关缓存立即失效"，不要靠真实计费请求养缓存，而是直接 `SET` 种一个已知值 → `GET`（有值 = 修复前）→ `DEL`（= 失效动作）→ `GET`（nil = 修复后）。
|
|
139
157
|
- ⚠️ **报告开头必带一张「为什么这样验证成立」的原理说明卡。** 先讲清楚 bug 前后差异的本质是哪一个动作，再论证"手动模拟该动作 = 真实场景"，让不了解背景的人也能信服。配一张修复前 vs 修复后的 A/B 对照表（代码行为 / 等价操作 / 观测结果三列并排）。
|
|
140
158
|
- ⚠️ **每个验证步骤必须三要素齐全**：① 怎么做的（可复制粘贴的完整命令）② 结果（含可复查标识：执行 ID、时间戳、返回码）③ 这一步证明了什么（一句话点明证据含义，如"DEL 返回 1 = 删除前 key 确实存在"）。
|
|
@@ -40,6 +40,12 @@ git diff origin/main...HEAD --stat
|
|
|
40
40
|
## 改动
|
|
41
41
|
（改了什么，采用什么方案）
|
|
42
42
|
|
|
43
|
+
## 缺陷复现
|
|
44
|
+
（⚠️ 仅修 bug / 修故障的 PR 必填，其余 PR 写「N/A（非修 bug）」。
|
|
45
|
+
依据「⚠️ 缺陷复现铁律」：填的是【改动前的代码】上跑出来的复现证据——
|
|
46
|
+
环境与版本 → 可被别人照着重演的操作步骤 → 观测到的坏现象（报错原文/状态码/日志/截图 + 时间戳或 request id），
|
|
47
|
+
再附「用同一套步骤复验后坏现象消失」。这一步不做 = 不知道原来到底是不是这个问题。）
|
|
48
|
+
|
|
43
49
|
## 方案取舍
|
|
44
50
|
（为什么选这个方案，考虑过什么替代方案）
|
|
45
51
|
|
|
@@ -58,6 +64,7 @@ Closes #issue编号
|
|
|
58
64
|
1. **截修复后**：浏览器打开改动页面 → 滚动到改动区域 → 全页截图
|
|
59
65
|
2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
|
|
60
66
|
- ⚠️ **若线上数据已变化，导致无法在真实页面复现"修复前"效果**：允许改用等价的纯逻辑对比代替（用新旧两版逻辑代码跑同样的输入数据，把输出结果差异渲染成对比图），但必须在 Description 里明确写清楚"为什么无法复现 + 用了什么替代方案"，禁止因此省略截图或假装能复现。
|
|
67
|
+
- ⚠️ **修 bug 的 PR：这张"修复前"截图必须来自真实复现，不是回退代码摆拍出来的。** 正确做法是先按「⚠️ 缺陷复现铁律」在**未改动的代码**上复现出坏现象、截下这一张（它同时就是「缺陷复现」栏目的证据），再去改代码；回退代码截图只是辅助，**唯一目的是把同一处界面截得位置对齐**，不能替代复现——否则截图证明的只是"代码改回去长这样"，不是"用户当时遇到的就是这个"。无法在改动前复现的，按上一条写明原因，禁止默认走回退摆拍。
|
|
61
68
|
3. **生成对比图**：用 `annotate.js`（截图标注统一脚本，见 `/screenshot-annotate` skill）拼接并标注 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域用坐标精确换算后的箭头 + 红/绿框圈选
|
|
62
69
|
4. **上传 GitHub CDN**（在 PR Description 编辑区直接上传）：
|
|
63
70
|
- 打开目标 PR 页面 → 在 **Description 编辑区**直接上传图片（拖拽/粘贴，或定位 Description 编辑区的隐藏 `input[type=file]` 上传），GitHub 会自动把图片转成 `https://github.com/user-attachments/assets/...` 的 CDN 地址并插入 Description 正文，`` 内嵌
|
|
@@ -159,5 +166,6 @@ gh pr checks <PR>
|
|
|
159
166
|
- ⚠️ 每次修改 PR 后（含创建、push 新提交、响应 review 意见）都必须做三步收尾：冲突检查 → 静态编译检查 → PR 合并后发新版本（见步骤 8）
|
|
160
167
|
- ⚠️ **创建完 PR 后必须自动走完整闭环流程（见步骤 7.5）**：创建 PR → 先做 CI 闸门检查并修复失败项 → **链路预演（命中跨系统链路验收触发条件时，在循环 review 之前先跑，只为尽早暴露需要大改的问题）** → 自动循环 review → 重新部署测试环境验证（全程截图 + 箭头标注，命中触发条件的走 `/real-chain-verify` 阶段 2）→ 确认没问题 → 发新版本，七步缺一不可，未走完不算完成
|
|
161
168
|
- ⚠️ **PR 描述里必须填「跨系统链路验收」栏目**（PR 模板已内置）：命中 4 条触发条件的填链路预演链路图 + 下游真实生效证据 + 默认值对照；未命中的勾选豁免项。**留痕是给 reviewer 看的——不填等于这一环做了也没人知道。**
|
|
169
|
+
- ⚠️ **PR 描述里必须填「缺陷复现」栏目**（PR 模板已内置）：修 bug / 修故障的 PR 必须填**改动前**的复现证据（环境版本 → 可重演步骤 → 坏现象 + 可复查标识）与「同一套步骤复验后坏现象消失」；非修 bug 的勾选豁免项。⚠️ **动手改代码之前就要先复现**——复现不出来先回去对口径，禁止「按理解先改、改完补个复现描述」。见「⚠️ 缺陷复现铁律」。
|
|
162
170
|
- ⚠️ **直接创建正式 PR（非 Draft）**：PR 创建完成即进入可评审状态，可直接交付 review，禁止先开 Draft PR、后续再手动标记 Ready for review
|
|
163
171
|
- 作者不能 Approve 自己的 PR
|
|
@@ -29,11 +29,12 @@ description: >-
|
|
|
29
29
|
2. ✅ 最新代码已提交并推送到 PR 分支
|
|
30
30
|
3. ✅ 已通过 `/deploy-test` 重新部署到测试环境（部署的是 review 之后的最终代码）
|
|
31
31
|
4. ✅ 测试环境用真实数据 + 真实交互复测通过，**且命中的跨系统链路环节已按 `/real-chain-verify` 阶段 2 验完下游**（每张截图浏览器真实视口全页、箭头标注、URL 可见）
|
|
32
|
-
5. ✅ PR
|
|
33
|
-
6. ✅
|
|
34
|
-
7. ✅
|
|
35
|
-
8. ✅ PR
|
|
36
|
-
9. ✅
|
|
32
|
+
5. ✅ 修 bug 的 PR，PR 描述里的「缺陷复现」栏目已填完（改动前的复现证据 + 同一套步骤复验结果；非修 bug 的已勾选豁免项）
|
|
33
|
+
6. ✅ PR 描述里的「跨系统链路验收」栏目已填完（未命中触发条件的已勾选豁免项）
|
|
34
|
+
7. ✅ 与主分支无冲突（`gh pr view <PR> --json mergeable -q .mergeable` = `MERGEABLE`）
|
|
35
|
+
8. ✅ GitHub 静态编译通过（`gh pr checks <PR>` 无 `failure`）
|
|
36
|
+
9. ✅ PR 链接已发送给用户
|
|
37
|
+
10. ✅ 发新版本（`./release.sh`）
|
|
37
38
|
- ⚠️ **循环 review 走完后，显式输出「✅ 循环 review 完成，进入发布收尾闭环」，然后逐项执行下面第 2～8 步，禁止在循环 review 结束后直接发链接/发版。** 若发现某一步没做（典型：忘了重新部署、复测是旧数据），必须停下来补齐再继续，禁止把「漏掉的第 3/4 步」带进交付。
|
|
38
39
|
|
|
39
40
|
## 核心流程
|