@routerhub/agent-rules 1.5.226 → 1.5.227

package/AGENTS.base.md

@@ -260,6 +260,22 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   - ⚠️ **不命中触发条件的改动，两段都不走**（纯文案、纯展示类改动不受影响）。
 - ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、两段各自做到什么程度、证据怎么组织成报告）。
 
+## ⚠️ 结果验收清单铁律（流程跑完 ≠ 结果对了）
+
+- ⚠️ **核心认知：多步流程跑到最后一步显示成功，只证明「任务被受理并跑完了」，不证明「最终那个东西真的产出了」。** 最容易被糊弄过去的地方在于——**结果页那句「成功」是它对任务状态的渲染，不是对结果的判断**：`All steps succeeded` 读起来像「成了」，实际只是 `ok === total` 的一个三元表达式，连「有步骤失败但计数对上了」都会被它说成成功。**判断标准：本次改动有没有「用户走完 N 步 → 产生一个最终产物 / 最终状态」的形态（上线、发布、开户、迁移、批量写、异步任务……）？有 → 本次交付必须自带一节「走完之后怎么确认最终结果对了」，只交过程截图不算交付完。**
+  - **类比：水龙头拧开出水，只证明管子通；接一杯水去测，才知道滤芯到底装没装上。**
+- ⚠️ **第一步不是自己拟验收清单，是先翻产品自己有没有写。** 结果页文案、成功提示、需求文档里若已经写明「怎么确认真正生效」，**以它为准，并逐字引用出处**——产品自己写在界面上的那句，就是权威验收口径，比你另拟一套更准、也更难被 reviewer 质疑。**本次真实案例**：结果页自己写着 *"A successful launch does not mean the account is callable right away... **Check the routing list before sending traffic to this account.**"*（`components/LaunchWizardModal/LaunchStepResult.tsx:123-125`）——「去查路由列表」这个验收动作是产品自己提的，我们只是把它转成清单。
+- ⚠️ **清单必须分层，并显式点出哪一层才是决定性的。** 至少四层，从「后台自己说自己成功了」一路走到「真实请求打进去了」：
+  1. **后台状态推进**（详情页徽标 / 操作日志里那条状态变更）；
+  2. **接口里真落库了**（`GET` 回来的 `status`、关联的模型列表）；
+  3. **任务本身成功**（`GET /tasks/{id}` 的 `steps[]` 全 success）；
+  4. **下游可观测事实（决定性）**——真实打一条请求，在**下游**留下痕迹。
+  **①②③ 全是本系统自己的回显**：后台记一句 `online`、接口返回一句 `online`，都只说明「我记下了」，不代表下游认了——**只有 ④ 算数**。这句话必须写在清单明处；不写，读者就会把 ①②③ 全绿当成验收通过。
+- ⚠️ **跑不了的层如实标注，禁止用假数据把清单演示一遍。** 依赖的后端 / 服务尚未就绪时，明写「本节是 X 就绪后的验收清单」，并交代当前唯一能验的是它的反例（拿不到数据时是不是干净空态、有没有拿 `0` 或假数据冒充）。**「清单写了、一层都跑不了、却读起来像验过了」比不写更糟。**
+- ⚠️ **验不到时，先排除「还没到生效周期」再报 bug。** 这类系统的最终生效常是**周期性重载**而非提交即生效（本次：网关按周期重载路由表，RouterHub 默认 60s，同样出自结果页文案）。**顺序是硬的**：①②③ 全绿而 ④ 不出现 → 先等一个周期再查；**等过周期仍不出现，才是真问题**。反向也要防：把已经等够周期的真问题当成「再等等就好」。**「把没到期报成坏了」和「把真坏了当成没到期」，是两个方向相反、代价同样高的误判。**
+- ⚠️ **报告里指出的每一处出处（文件名 / 组件 / 注释 / 行号），落笔前必须实际打开确认「文件在、内容对得上」。** 出处是给读者的**导航锚点**，指错方向的代价比不指更大：他按图索骥点进去、扑了个空，从此不会再信报告里的其他结论（与「⚠️ 主张自带复核流程铁律」呼应——**锚点不可信，整份报告的可核实性就塌了**）。**本次真实踩坑**：报告里写着「这一条写在 `launchAdapter.ts` 与 `useLaunchJob.ts` 两个接入点的注释里」——`useLaunchJob.ts` 这个文件**根本不存在**（轮询 hook 真名是 `hooks/useTaskJob.ts`），而且那两个文件里**都没有**这条注释，真实出处是结果页的界面文案。**自查一句话：这个出处我现在打开能指给读者看吗？指不出 → 只写结论，不指路。**
+- **与相邻铁律的分工**：「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」（链路图 + 每个环节一条下游可观测事实 + 至少一条下游真实生效证据）；「⚠️ 主张自带复核流程铁律」管「报告里每条主张旁挂可照做的复核流程（含对错两种预期结果）」；**本条管的是更前置的一件事——本次改动到底有没有「最终结果」这个待验收对象，以及那个对象该在哪一层验才算数。** 三者叠加：先有本条的清单（验什么 / 哪层算数）→ 再按链路铁律取下游证据 → 最后按复核流程铁律把每一步写成读者能自己跑的形态。
+
 ## ⚠️ 报告以需求原话为骨架铁律（原文 ↔ 实现 ↔ 截图证据 三段式）
 
 - ⚠️ **核心认知：报告的读者是需求方，而他判断「做没做到」的唯一依据是需求原话。** 报告只写「我们做了什么」，等于让读者自己拿记忆里的需求去比对满篇实现描述——需求→实现之间隔着产品转述、口头对齐、中途口径变化，他拼错了图就会以为某条没做（或以为做了其实没做）。**把原话摆在每段实现旁边，读者不用回忆、不用拼图，逐句对一眼即可。**
@@ -382,6 +398,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
     - **量级与兜底**：GitHub 描述上限约 65,536 字符。实测团队常规报告体量（十余张截图 + 十余步逐步手册 + 取证说明）约 1 万字符，余量充足——**「正文装不下」在实践中不成立，不要拿它当外链的借口**。只有当内容**确实**超出承载（截图 > 80 张 / 字符逼近上限）时才拆出独立文档，此时：**必须用 Markdown**（GitHub 原生渲染、点开即看、图片内联，链接粘贴即读），**禁止用 HTML**（不渲染、又要下载）；且拆分后 PR 描述里仍要保留需求骨架与关键截图，链接只能作为「超出部分的续篇」，**不能倒过来变成「细节都在那边」**。
     - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：描述里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
     - **适用范围**：所有 PR 一律内联交付，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分，修 bug 的再加「复现走查」。
+- ⚠️ **描述的行文顺序：一句话结论 → 主流程（怎么走通的）→ 截图 → 验收 / 验证 → 其余；禁止列「改了哪些文件 / 代码」清单。** 目的是把 reviewer 的阅读成本压到最低：**他第一眼要知道的是「这东西现在能不能用、长什么样」，不是「你动了哪几个文件」**——文件清单只有写过这段代码的人看得懂，对判断改动对不对没有增量，纯占篇幅。⚠️ **注意与上一行「内容至少覆盖『改了什么』」不冲突**：要讲的是「改了什么**行为 / 功能**」，不是「改了哪些**文件**」。**一句话结论**写「这次做了什么、现在处在什么状态」（如「资源上线四步向导已交付、页面可走通，后端接口未就绪」），让人读完第一行就知道该继续往下看细节、还是可以直接跳过——**别让他读三段才知道这次的东西能不能用。**
 - ⚠️ **PR 建完后的第一个动作是自问「打开这一页，细节是不是全在上面」，不是就当场补进去**：⚠️ **细节还挂在外部文档、或正文只写了摘要的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文摘要写得很清楚」不构成豁免，内联是**必备件**而非可选优化。
 - ⚠️ PR Title / Description / Test Plan 全部中文。
 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：

package/package.json

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

package/rules/global.md

@@ -260,6 +260,22 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
   - ⚠️ **不命中触发条件的改动，两段都不走**（纯文案、纯展示类改动不受影响）。
 - ⚠️ **具体操作流程见 `/real-chain-verify` skill**（怎么画链路、每类系统怎么取证、两段各自做到什么程度、证据怎么组织成报告）。
 
+## ⚠️ 结果验收清单铁律（流程跑完 ≠ 结果对了）
+
+- ⚠️ **核心认知：多步流程跑到最后一步显示成功，只证明「任务被受理并跑完了」，不证明「最终那个东西真的产出了」。** 最容易被糊弄过去的地方在于——**结果页那句「成功」是它对任务状态的渲染，不是对结果的判断**：`All steps succeeded` 读起来像「成了」，实际只是 `ok === total` 的一个三元表达式，连「有步骤失败但计数对上了」都会被它说成成功。**判断标准：本次改动有没有「用户走完 N 步 → 产生一个最终产物 / 最终状态」的形态（上线、发布、开户、迁移、批量写、异步任务……）？有 → 本次交付必须自带一节「走完之后怎么确认最终结果对了」，只交过程截图不算交付完。**
+  - **类比：水龙头拧开出水，只证明管子通；接一杯水去测，才知道滤芯到底装没装上。**
+- ⚠️ **第一步不是自己拟验收清单，是先翻产品自己有没有写。** 结果页文案、成功提示、需求文档里若已经写明「怎么确认真正生效」，**以它为准，并逐字引用出处**——产品自己写在界面上的那句，就是权威验收口径，比你另拟一套更准、也更难被 reviewer 质疑。**本次真实案例**：结果页自己写着 *"A successful launch does not mean the account is callable right away... **Check the routing list before sending traffic to this account.**"*（`components/LaunchWizardModal/LaunchStepResult.tsx:123-125`）——「去查路由列表」这个验收动作是产品自己提的，我们只是把它转成清单。
+- ⚠️ **清单必须分层，并显式点出哪一层才是决定性的。** 至少四层，从「后台自己说自己成功了」一路走到「真实请求打进去了」：
+  1. **后台状态推进**（详情页徽标 / 操作日志里那条状态变更）；
+  2. **接口里真落库了**（`GET` 回来的 `status`、关联的模型列表）；
+  3. **任务本身成功**（`GET /tasks/{id}` 的 `steps[]` 全 success）；
+  4. **下游可观测事实（决定性）**——真实打一条请求，在**下游**留下痕迹。
+  **①②③ 全是本系统自己的回显**：后台记一句 `online`、接口返回一句 `online`，都只说明「我记下了」，不代表下游认了——**只有 ④ 算数**。这句话必须写在清单明处；不写，读者就会把 ①②③ 全绿当成验收通过。
+- ⚠️ **跑不了的层如实标注，禁止用假数据把清单演示一遍。** 依赖的后端 / 服务尚未就绪时，明写「本节是 X 就绪后的验收清单」，并交代当前唯一能验的是它的反例（拿不到数据时是不是干净空态、有没有拿 `0` 或假数据冒充）。**「清单写了、一层都跑不了、却读起来像验过了」比不写更糟。**
+- ⚠️ **验不到时，先排除「还没到生效周期」再报 bug。** 这类系统的最终生效常是**周期性重载**而非提交即生效（本次：网关按周期重载路由表，RouterHub 默认 60s，同样出自结果页文案）。**顺序是硬的**：①②③ 全绿而 ④ 不出现 → 先等一个周期再查；**等过周期仍不出现，才是真问题**。反向也要防：把已经等够周期的真问题当成「再等等就好」。**「把没到期报成坏了」和「把真坏了当成没到期」，是两个方向相反、代价同样高的误判。**
+- ⚠️ **报告里指出的每一处出处（文件名 / 组件 / 注释 / 行号），落笔前必须实际打开确认「文件在、内容对得上」。** 出处是给读者的**导航锚点**，指错方向的代价比不指更大：他按图索骥点进去、扑了个空，从此不会再信报告里的其他结论（与「⚠️ 主张自带复核流程铁律」呼应——**锚点不可信，整份报告的可核实性就塌了**）。**本次真实踩坑**：报告里写着「这一条写在 `launchAdapter.ts` 与 `useLaunchJob.ts` 两个接入点的注释里」——`useLaunchJob.ts` 这个文件**根本不存在**（轮询 hook 真名是 `hooks/useTaskJob.ts`），而且那两个文件里**都没有**这条注释，真实出处是结果页的界面文案。**自查一句话：这个出处我现在打开能指给读者看吗？指不出 → 只写结论，不指路。**
+- **与相邻铁律的分工**：「⚠️ 跨系统真实链路验收铁律」管「整条链路成不成立」（链路图 + 每个环节一条下游可观测事实 + 至少一条下游真实生效证据）；「⚠️ 主张自带复核流程铁律」管「报告里每条主张旁挂可照做的复核流程（含对错两种预期结果）」；**本条管的是更前置的一件事——本次改动到底有没有「最终结果」这个待验收对象，以及那个对象该在哪一层验才算数。** 三者叠加：先有本条的清单（验什么 / 哪层算数）→ 再按链路铁律取下游证据 → 最后按复核流程铁律把每一步写成读者能自己跑的形态。
+
 ## ⚠️ 报告以需求原话为骨架铁律（原文 ↔ 实现 ↔ 截图证据 三段式）
 
 - ⚠️ **核心认知：报告的读者是需求方，而他判断「做没做到」的唯一依据是需求原话。** 报告只写「我们做了什么」，等于让读者自己拿记忆里的需求去比对满篇实现描述——需求→实现之间隔着产品转述、口头对齐、中途口径变化，他拼错了图就会以为某条没做（或以为做了其实没做）。**把原话摆在每段实现旁边，读者不用回忆、不用拼图，逐句对一眼即可。**
@@ -382,6 +398,7 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
     - **量级与兜底**：GitHub 描述上限约 65,536 字符。实测团队常规报告体量（十余张截图 + 十余步逐步手册 + 取证说明）约 1 万字符，余量充足——**「正文装不下」在实践中不成立，不要拿它当外链的借口**。只有当内容**确实**超出承载（截图 > 80 张 / 字符逼近上限）时才拆出独立文档，此时：**必须用 Markdown**（GitHub 原生渲染、点开即看、图片内联，链接粘贴即读），**禁止用 HTML**（不渲染、又要下载）；且拆分后 PR 描述里仍要保留需求骨架与关键截图，链接只能作为「超出部分的续篇」，**不能倒过来变成「细节都在那边」**。
     - **内容取材优先级（前端可视化优先，纯逻辑才退而用代码/接口图）**：描述里讲「改了什么、效果如何」时，**凡这个功能有真实前端页面承载的（如 routerhub-ui 的 admin / 用户平台等页面），必须用真实页面截图证明——打开页面、真实数据操作、箭头标注出「这个功能在页面哪儿用、操作前后效果长什么样」，让人不写代码也能看懂；只有页面截不出来、纯后端逻辑（计费、限流、路由、数据链路等）的部分，才允许退而用代码截图 / curl 请求响应图 / 日志图代替。** 页面能截出来的就不许偷懒贴代码——前端可视化是最有说服力的证据，reviewer 要的是一眼看到改动效果，不是读代码猜。
     - **适用范围**：所有 PR 一律内联交付，无例外；内容至少覆盖「改了什么、为什么改、每一步怎么改/怎么验证的」三部分，修 bug 的再加「复现走查」。
+- ⚠️ **描述的行文顺序：一句话结论 → 主流程（怎么走通的）→ 截图 → 验收 / 验证 → 其余；禁止列「改了哪些文件 / 代码」清单。** 目的是把 reviewer 的阅读成本压到最低：**他第一眼要知道的是「这东西现在能不能用、长什么样」，不是「你动了哪几个文件」**——文件清单只有写过这段代码的人看得懂，对判断改动对不对没有增量，纯占篇幅。⚠️ **注意与上一行「内容至少覆盖『改了什么』」不冲突**：要讲的是「改了什么**行为 / 功能**」，不是「改了哪些**文件**」。**一句话结论**写「这次做了什么、现在处在什么状态」（如「资源上线四步向导已交付、页面可走通，后端接口未就绪」），让人读完第一行就知道该继续往下看细节、还是可以直接跳过——**别让他读三段才知道这次的东西能不能用。**
 - ⚠️ **PR 建完后的第一个动作是自问「打开这一页，细节是不是全在上面」，不是就当场补进去**：⚠️ **细节还挂在外部文档、或正文只写了摘要的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文摘要写得很清楚」不构成豁免，内联是**必备件**而非可选优化。
 - ⚠️ PR Title / Description / Test Plan 全部中文。
 - ⚠️ **PR 必须附效果截图作为可视化证据，且逐条满足以下硬性要求（缺一不可，禁止跳过）**：