规则11截图策略定稿：每个蓝本模块第1个场景加1张screenshot，规则12改为按功能模块拆分

Author: zcj220

docs/blueprint-prompt-golden-rules.md

@@ -159,34 +159,25 @@
 
 ## 规则11：截图策略（省钱省时）
 
-截图会消耗视觉大模型费用和测试时间，必须精确控制使用场景。
-
-### 断言 vs 截图能力对比
-
-| Bug类型 | 检测方式 | 需要截图？ |
-|---------|---------|-----------|
-| 文本值错误（价格、状态） | `assert_text` | ❌ 不需要 |
-| 元素缺失/隐藏 | `assert_visible` | ❌ 不需要 |
-| 计算逻辑错误（优惠、运费） | `assert_text` | ❌ 不需要 |
-| **布局溢出**（文字超出容器） | 视觉检查 | ✅ 需要 |
-| **元素遮挡/重叠** | 视觉检查 | ✅ 需要 |
-| **样式错乱**（颜色、字号） | 视觉检查 | ✅ 需要 |
-| **响应式适配崩坏** | 视觉检查 | ✅ 需要 |
-| **图片加载失败** | 视觉检查 | ✅ 需要 |
-
-### 截图使用规则
-
-- ❌ **禁止**在每个场景末尾无脑加 `screenshot`
-- ✅ 只在以下3种场景使用：
-  1. **断言失败时**：引擎自动截图留证，蓝本不用写
-  2. **关键业务流程最终结果页**：如下单成功页，每个模块最多1张
-  3. **专门的视觉测试场景**：布局溢出、遮挡、适配——这类Bug只有截图能发现
-
-## 规则12：蓝本按功能拆分
-
-- 项目超过3个页面时，必须按功能模块拆分为多个蓝本文件
-- 命名规范：`testpilot/<模块名>.testpilot.json`（如 `auth.testpilot.json`、`cart.testpilot.json`）
-- 每个蓝本文件独立可运行，场景开头都要从 `navigate` 开始
+截图用于发现**视觉Bug**（布局溢出、元素遮挡、样式错乱、响应式崩坏、图片加载失败），断言无法检测这类问题。
+
+### 截图规则
+
+- **每个蓝本模块的第1个场景末尾加1张 `screenshot`**，其余场景不加
+  - `auth.testpilot.json` 第1个场景末尾 → `screenshot`（覆盖登录页视觉）
+  - `cart.testpilot.json` 第1个场景末尾 → `screenshot`（覆盖购物车视觉）
+  - 同模块的第2、3、4…个场景 → 不加
+- 断言失败时引擎会自动截图留证，蓝本不用额外写
+- ❌ **禁止**每个场景末尾都加 `screenshot`（浪费视觉大模型费用和时间）
+
+## 规则12：蓝本按功能模块拆分
+
+- 按**业务功能模块**拆分蓝本，不要把所有场景塞进一个文件
+- 拆分原则：**一个功能模块 = 一个蓝本文件**，改了哪个功能就只跑哪个蓝本
+  - 例：`auth`（登录注册）、`cart`（购物车）、`checkout`（结算支付）、`profile`（个人中心）
+  - 跨页面的端到端流程归属到终点功能模块（如"加购→结算→下单"归入 `checkout`）
+- 命名规范：`testpilot/<模块名>.testpilot.json`
+- 每个蓝本独立可运行，场景开头都要从 `navigate` 开始
 - 全量测试时通过 `run_blueprint_batch` 批量运行所有蓝本
 
 ## 规则13：蓝本增量修改（省Token）

extension/src/sidebarProvider.ts

@@ -490,17 +490,21 @@ export class SidebarProvider implements vscode.WebviewViewProvider {
 - 如果没有文档，则从代码注释、变量命名、函数名中推断业务意图，对比实际行为是否一致
 
 【规则11：截图策略（省钱省时）】
-- ❌ 禁止在每个场景末尾无脑加 screenshot，这会浪费视觉大模型费用和测试时间
-- ✅ 只在以下3种情况使用 screenshot：
-  1. 断言失败时（引擎会自动截图留证，蓝本不用写）
-  2. 关键业务流程的最终结果页（如下单成功页、支付结果页，每个模块最多1张）
-  3. 专门的视觉测试场景：布局溢出、遮挡重叠、响应式适配、图片加载等——这类Bug只有截图能发现
-- 普通的文本断言、元素可见性断言场景，绝对不要加 screenshot
-
-【规则12：蓝本按功能拆分】
-- 项目超过3个页面时，必须按功能模块拆分为多个蓝本文件
-- 命名规范：testpilot/ 目录下 <模块名>.testpilot.json（如 auth.testpilot.json、cart.testpilot.json）
-- 每个蓝本文件独立可运行，场景开头都要从 navigate 开始
+- 截图用于发现视觉Bug（布局溢出、元素遮挡、样式错乱、响应式崩坏），断言无法检测这类问题
+- 规则：每个蓝本模块的第1个场景末尾加1张 screenshot，其余场景不加
+  * 例：auth.testpilot.json 的第1个场景末尾 → screenshot（覆盖登录页视觉）
+  * 例：cart.testpilot.json 的第1个场景末尾 → screenshot（覆盖购物车视觉）
+  * 同模块的第2、3、4…个场景 → 不加 screenshot
+- 断言失败时引擎会自动截图留证，蓝本不用额外写
+- ❌ 禁止每个场景末尾都加 screenshot（浪费视觉大模型费用和时间）
+
+【规则12：蓝本按功能模块拆分】
+- 按业务功能模块拆分蓝本，不要把所有场景塞进一个文件
+- 拆分原则：一个功能模块 = 一个蓝本文件，改了哪个功能就只跑哪个蓝本
+  * 例：auth（登录注册）、cart（购物车）、checkout（结算支付）、profile（个人中心）
+  * 跨页面的端到端流程归属到终点功能模块（如"加购→结算→下单"归入 checkout）
+- 命名规范：testpilot/<模块名>.testpilot.json
+- 每个蓝本独立可运行，场景开头都要从 navigate 开始
 - 全量测试时通过 run_blueprint_batch 批量运行所有蓝本
 
 【规则13：蓝本增量修改（省Token）】

mobile-demo/testpilot/auth.testpilot.json

@@ -26,7 +26,8 @@
             {"action": "fill", "target": "#loginPass", "value": "123456"},
             {"action": "click", "target": "#loginBtn"},
             {"action": "assert_visible", "target": "#tabHome", "description": "验证跳转到首页"},
-            {"action": "assert_visible", "target": ".product-card", "description": "验证商品列表显示"}
+            {"action": "assert_visible", "target": ".product-card", "description": "验证商品列表显示"},
+            {"action": "screenshot"}
           ]
         },
         {

mobile-demo/testpilot/cart.testpilot.json

@@ -16,7 +16,8 @@
             {"action": "click", "target": "#guestBtn"},
             {"action": "click", "target": "#navCart"},
             {"action": "assert_visible", "target": "#cartEmpty"},
-            {"action": "assert_text", "target": ".empty-text", "expected": "购物车是空的"}
+            {"action": "assert_text", "target": ".empty-text", "expected": "购物车是空的"},
+            {"action": "screenshot"}
           ]
         },
         {

mobile-demo/testpilot/checkout.testpilot.json

@@ -28,7 +28,8 @@
             {"action": "assert_text", "target": "#checkoutDelivery", "expected": "¥8.00"},
             {"action": "click", "target": "#submitOrderBtn"},
             {"action": "assert_visible", "target": "#orderResultPage"},
-            {"action": "assert_text", "target": "#resultTitle", "expected": "下单成功"}
+            {"action": "assert_text", "target": "#resultTitle", "expected": "下单成功"},
+            {"action": "screenshot"}
           ]
         },
         {

mobile-demo/testpilot/home.testpilot.json

@@ -27,7 +27,8 @@
             {"action": "assert_visible", "target": ".product-card"},
             {"action": "assert_text", "target": "#pname-1", "expected": "红富士苹果"},
             {"action": "assert_text", "target": "#pname-2", "expected": "进口香蕉"},
-            {"action": "assert_text", "target": "#pstock-3", "expected": "已售罄"}
+            {"action": "assert_text", "target": "#pstock-3", "expected": "已售罄"},
+            {"action": "screenshot"}
           ]
         },
         {

mobile-demo/testpilot/me.testpilot.json

@@ -20,7 +20,8 @@
             {"action": "assert_text", "target": "#userName", "expected": "用户8000"},
             {"action": "assert_text", "target": "#userPhone", "expected": "13800138000"},
             {"action": "assert_text", "target": "#couponCount", "expected": "2"},
-            {"action": "assert_visible", "target": "#logoutBtn"}
+            {"action": "assert_visible", "target": "#logoutBtn"},
+            {"action": "screenshot"}
           ]
         },
         {

src/core/prompts.py

@@ -571,17 +571,21 @@
 - 如果没有文档，则从代码注释、变量命名、函数名中推断业务意图，对比实际行为是否一致
 
 【规则11：截图策略（省钱省时）】
-- ❌ 禁止在每个场景末尾无脑加 screenshot，这会浪费视觉大模型费用和测试时间
-- ✅ 只在以下3种情况使用 screenshot：
-  1. 断言失败时（引擎会自动截图留证，蓝本不用写）
-  2. 关键业务流程的最终结果页（如下单成功页、支付结果页，每个模块最多1张）
-  3. 专门的视觉测试场景：布局溢出、遮挡重叠、响应式适配、图片加载等——这类Bug只有截图能发现
-- 普通的文本断言、元素可见性断言场景，绝对不要加 screenshot
-
-【规则12：蓝本按功能拆分】
-- 项目超过3个页面时，必须按功能模块拆分为多个蓝本文件
-- 命名规范：testpilot/ 目录下 <模块名>.testpilot.json（如 auth.testpilot.json、cart.testpilot.json）
-- 每个蓝本文件独立可运行，场景开头都要从 navigate 开始
+- 截图用于发现视觉Bug（布局溢出、元素遮挡、样式错乱、响应式崩坏），断言无法检测这类问题
+- 规则：每个蓝本模块的第1个场景末尾加1张 screenshot，其余场景不加
+  * 例：auth.testpilot.json 的第1个场景末尾 → screenshot（覆盖登录页视觉）
+  * 例：cart.testpilot.json 的第1个场景末尾 → screenshot（覆盖购物车视觉）
+  * 同模块的第2、3、4…个场景 → 不加 screenshot
+- 断言失败时引擎会自动截图留证，蓝本不用额外写
+- ❌ 禁止每个场景末尾都加 screenshot（浪费视觉大模型费用和时间）
+
+【规则12：蓝本按功能模块拆分】
+- 按业务功能模块拆分蓝本，不要把所有场景塞进一个文件
+- 拆分原则：一个功能模块 = 一个蓝本文件，改了哪个功能就只跑哪个蓝本
+  * 例：auth（登录注册）、cart（购物车）、checkout（结算支付）、profile（个人中心）
+  * 跨页面的端到端流程归属到终点功能模块（如"加购→结算→下单"归入 checkout）
+- 命名规范：testpilot/<模块名>.testpilot.json
+- 每个蓝本独立可运行，场景开头都要从 navigate 开始
 - 全量测试时通过 run_blueprint_batch 批量运行所有蓝本
 
 【规则13：蓝本增量修改（省Token）】