csspilot 0.5.0 → 0.7.0

package/dist/skills/testpilot/SKILL.md

@@ -1,78 +1,84 @@
-# TestPilot
-
-## What is TestPilot
-
-TestPilot is an AI Native cross-platform testing infrastructure.
-
-It lets AI understand, generate, validate and run business tests for Web and Mini Program apps.
-
-TestPilot is a **tool, not a business test project**. Business cases always belong to the project (`tests/e2e/cases/`), never to TestPilot itself.
-
-## When to use
-
-Use TestPilot when the user wants to:
-
-- review test requirements for testability
-- create business test cases
-- validate test cases
-- run tests
-- inspect test results
-
-## Core workflow
-
-1. Understand user requirement
-2. Review requirements & produce test points (`workflows/test-requirements-review.md`)
-3. Inspect project
-4. Identify test target
-5. Create TestPilot Case (`tests/e2e/cases/*.yaml`, linked to test point IDs)
-6. Validate Case (`npx csspilot validate`)
-7. Run Case (`npx csspilot run`)
-8. Analyze result (`npx csspilot report`)
-
-## Important rules
-
-- Never directly control Playwright.
-- Never directly control WeChatIDE.
-- Use TestPilot DSL to describe tests.
-- Business cases belong to the project.
-- Prefer existing project conventions.
-- Never invent locators without evidence.
-- Validate before running.
-
-## CLI
-
-```bash
-npx csspilot init      # install TestPilot into the current project
-npx csspilot validate  # validate cases against the DSL
-npx csspilot list      # list cases (--tag smoke)
-npx csspilot run       # run cases (file paths / --tag)
-npx csspilot report    # generate JSON + HTML report
-npx csspilot doctor    # health check (config / cases / adapters / env / server)
-npx csspilot ci init   # generate TestPilot CI workflow template
-npx csspilot sync-metadata  # sync case metadata to TestPilot Server (CI, after git push)
-```
-
-## Project context
-
-Read `references/` first (generated by `csspilot init` for this project):
-
-- `references/project.md` — project name / type / test dirs / available adapters
-- `references/test-conventions.md` — the testing rules this project enforces
-- `references/adapters.md` — detected adapter status
-
-
-## Directory map (business project)
-
-- `.agents/skills/testpilot/` — this skill (AI usage spec)
-- `.testpilot/` — TestPilot runtime state and artifacts
-- `tests/e2e/cases/` — business cases
-- `testpilot.yaml` — project-level TestPilot config
-
-## Further reading
-
-- `rules/case-design.md` — what a case is, evidence-first generation
-- `rules/dsl.md` — case structure and the V0.1 action set
-- `rules/locator.md` — locator forms and the no-invention rule
-- `rules/assertion.md` — assertions and variable references
-- `workflows/test-requirements-review.md` — requirements review, test point checklist
-- `workflows/` — step-by-step workflows (review / create / validate / run / analyze)
+# TestPilot
+
+## What is TestPilot
+
+TestPilot is an AI Native cross-platform testing infrastructure.
+
+It lets AI understand, generate, validate and run business tests for Web and Mini Program apps.
+
+TestPilot is a **tool, not a business test project**. Business cases always belong to the project (`tests/e2e/cases/`), never to TestPilot itself.
+
+## When to use
+
+Use TestPilot when the user wants to:
+
+- review test requirements for testability
+- create business test cases
+- validate test cases
+- run tests
+- inspect test results
+
+## Core workflow
+
+1. Understand user requirement
+2. Review requirements, expand the rule matrix, and map QA coverage (`workflows/test-requirements-review.md`)
+3. Inspect project
+4. Identify test target
+5. Create TestPilot Case (`tests/e2e/cases/*.yaml`, linked to test point IDs)
+6. Validate Case (`npx csspilot validate`)
+7. Run Case (`npx csspilot run`)
+8. Analyze result (`npx csspilot report`)
+
+## Important rules
+
+- Never directly control Playwright.
+- Never directly control WeChatIDE.
+- Use TestPilot DSL to describe tests.
+- Business cases belong to the project.
+- Prefer existing project conventions.
+- Never invent locators without evidence.
+- Validate before running.
+- Generate only evidence-backed `requires`; never assume every project has accounts, coupons, promotions, or PPM.
+- Use data-driven Case groups only when the steps are the same and each row remains one decidable rule/data point.
+
+## CLI
+
+```bash
+npx csspilot init      # install TestPilot into the current project
+npx csspilot validate  # validate cases against the DSL
+npx csspilot list      # list cases (--tag smoke)
+npx csspilot run       # run cases (file paths / --tag)
+npx csspilot report    # generate JSON + HTML report
+npx csspilot doctor    # health check (config / cases / adapters / env / server)
+npx csspilot ci init   # generate TestPilot CI workflow template
+npx csspilot sync-metadata  # sync case metadata to TestPilot Server (CI, after git push)
+```
+
+`run` exit codes encode a three-way verdict: `1` = product regression or inconclusive (assertion / prerequisite variable missing), `2` = blocked by environment or missing fixture/account (NOT a product regression — fix the environment, do not file a bug), `0` = pass or skipped. Unknown error codes always count as product failure. In CI, treat **both 1 and 2 as failures** (2 only routes to environment debugging); a case with a missing fixture is blocked while the remaining cases in the same run still execute.
+
+## Project context
+
+Read `references/` first (generated by `csspilot init` for this project):
+
+- `references/project.md` — project name / type / test dirs / available adapters
+- `references/test-conventions.md` — the testing rules this project enforces
+- `references/adapters.md` — detected adapter status
+
+
+## Directory map (business project)
+
+- `.agents/skills/testpilot/` — this skill (AI usage spec)
+- `.testpilot/` — TestPilot runtime state and artifacts
+- `tests/e2e/cases/` — business cases
+- `tests/e2e/data/` — YAML/JSON fixtures and dataset rows
+- `tests/e2e/reviews/` — requirement matrix and QA coverage artifacts
+- `testpilot.yaml` — project-level TestPilot config
+
+## Further reading
+
+- `rules/case-design.md` — what a case is, evidence-first generation
+- `rules/dsl.md` — case structure and the V0.1 action set
+- `rules/locator.md` — locator forms and the no-invention rule
+- `rules/assertion.md` — assertions and variable references
+- `workflows/test-requirements-review.md` — requirements review, test point checklist
+- `workflows/` — step-by-step workflows (review / create / validate / run / analyze)

package/dist/skills/testpilot/manifest.yaml

@@ -2,7 +2,7 @@
 # `npx csspilot init` 会把整个 skills/testpilot/ 安装到业务项目 .agents/skills/testpilot/
 id: testpilot
 name: TestPilot
-version: 0.5.0
+version: 0.6.0
 
 description: >
   AI Native cross-platform testing skill.

package/dist/skills/testpilot/rules/assertion.md

@@ -4,3 +4,11 @@
 - `expected` 支持 `${variable}` 变量引用,变量来自之前的 `extract` 步骤(存于 ExecutionContext,可跨端传递,如小程序提取订单号 → Web 端断言)。
 - 断言必须对应真实业务预期(如订单号出现在 Web 后台),不写恒真断言。
 - 断言失败不一定是 Case 错误:先分析 Evidence(截图 / trace / log),判断是用例问题还是产品 bug,再决定修改 Case 还是上报问题。
+
+## 请求次数断言
+
+- UI 操作需要验证“只请求一次”时使用 `expectRequests`,不要用 wait 或页面文案间接推断。
+- 匹配条件是可选 `method` + 必填 `urlContains`;`count` 是精确次数,不是最小次数。
+- `windowMs` 是动作完成后的观察窗口,应取业务可合理完成的最小值。
+- Web 和 MiniApp 观察器必须透明调用真实请求,不得 mock 响应或改变业务行为。
+- URL 证据会隐藏 query 值;Case 中不要把 token 等秘密直接写入 `urlContains`。

package/dist/skills/testpilot/rules/case-design.md

@@ -1,29 +1,47 @@
-# Case 设计规范
-
-## Case 属于业务项目
-
-- Case 只存在于业务项目的 `tests/e2e/cases/`,永远不要写进 TestPilot 仓库的 `packages/`。
-- 一个 Case 描述一条完整的业务流程(如:创建订单、提交退款),不是单个页面操作。
-- `id` 使用 kebab-case,与文件名一致:`order-create.yaml` → `id: order-create`。
-
-## AI 不能凭空生成测试
-
-正确路径:
-
-```text
-用户需求 → 代码 / 页面 / 配置 → Evidence → 测试步骤 → Case
-```
-
-禁止路径:
-
-```text
-用户需求 → AI 猜 → Case
-```
-
-看到"测试登录"就直接写 `locator: { text: 登录 }` 是错误的。
-必须先阅读项目真实页面/代码,确认元素存在、文案准确,再生成步骤。
-
-## 业务数据
-
-- 不要把业务账号、密码硬编码进 Case。
-- 测试数据放业务项目 `tests/e2e/fixtures/` 或 `tests/e2e/data/`,Case 中通过变量引用。
+# Case 设计规范
+
+## Case 属于业务项目
+
+- Case 只存在于业务项目的 `tests/e2e/cases/`,永远不要写进 TestPilot 仓库的 `packages/`。
+- 一个 Case 描述一条完整的业务流程(如:创建订单、提交退款),不是单个页面操作。
+- `id` 使用 kebab-case,与文件名一致:`order-create.yaml` → `id: order-create`。
+
+## Case 与数据行
+
+- 默认一条独立业务流程一个 Case。
+- 多个测试点的步骤模板完全相同、差异仅为输入数据和可判定预期时,允许合并为一个 data-driven Case。
+- 每个 dataset 行必须有稳定唯一的 rowId,并仍保持“一个可判定规则/数据点”粒度。
+- 不同页面路径、不同角色权限流程、不同清理策略或不同断言结构不得为了减少 Case 数量而强行合并。
+- 报告按 `caseId#rowId` 标识执行结果;统计时每个数据行算一次执行。
+
+## AI 不能凭空生成测试
+
+正确路径:
+
+```text
+用户需求 → 代码 / 页面 / 配置 → Evidence → 测试步骤 → Case
+```
+
+禁止路径:
+
+```text
+用户需求 → AI 猜 → Case
+```
+
+看到"测试登录"就直接写 `locator: { text: 登录 }` 是错误的。
+必须先阅读项目真实页面/代码,确认元素存在、文案准确,再生成步骤。
+
+## 业务数据
+
+- 不要把业务账号、密码硬编码进 Case。
+- 测试参数统一放业务项目 `tests/e2e/data/` 的 YAML/JSON 文件,Case 通过 `${fixture.*}` / `${dataset.*}` 引用。
+- `requires` 只声明当前 Case 有证据支持的静态依赖。AI 必须从 PRD/Spec、代码、配置、已有 Case 或 QA 用例识别,不得因为业务名称自动发明账号、优惠券、PPM 等字段。
+- `.env` 提供当前环境的实际值;只有 `testpilot.yaml variables` 白名单映射的值可通过 `${variable.*}` 暴露给 Case。
+- 缺失依赖会使该数据行 `skipped(dependency-not-ready)`,这只表示静态值未就绪,不保证远端业务对象有效。
+- setup/teardown 优先使用 API 造数和清理;teardown 必须可重复执行。
+
+## charter:* 视角标签
+
+- `charter:` 前缀为评审视角保留标签(命名固定,勿作他用):`charter:persona` / `charter:edge-input` / `charter:numbers-copy` / `charter:state-recovery` / `charter:error-path`。
+- 由需求评审的视角覆盖表驱动写入(见 `workflows/create-case.md`);视角在需求内不适用时不打对应 tag。
+- 按视角抽查覆盖:`npx csspilot list --tag charter:error-path`。

package/dist/skills/testpilot/rules/dsl.md

@@ -6,11 +6,29 @@ Case 是 YAML 文件,V0.1 顶层结构:
 id: order-create      # kebab-case,与文件名一致
 name: 用户创建订单      # 人类可读名称
 accountRef: test-user # 可选:引用环境凭据,用 ${account.username} 等变量,禁止明文密码
+fixtures:             # 可选:项目相对路径,仅允许 tests/e2e/data 下的 YAML/JSON
+  - tests/e2e/data/products.yaml
+datasets:             # 可选:同一 steps 按对象数组逐行执行
+  file: tests/e2e/data/checkout-rows.yaml
+  idField: id
+requires:             # 可选:逐行执行前的静态依赖契约
+  - fixture.product.styleNo
+  - dataset.expectedTotal
+  - variable.ppmProjectId
+setup:                # 可选:主步骤前执行
+  - target: api
+    action: request
+    url: /test-support/cart/clear
 steps:                # 有序步骤列表
   - target: miniapp   # 执行端:miniapp | web | api
     action: click     # 见下方 Action 表
     locator:          # 定位器(见 rules/locator.md)
       text: 提交订单
+teardown:             # 可选:setup 开始后始终执行
+  - target: api
+    action: request
+    url: /test-support/cart
+    method: DELETE
 ```
 
 ## V0.1 稳定 Action
@@ -30,6 +48,50 @@ steps:                # 有序步骤列表
 
 字段定义最终以 `packages/dsl` 的 zod schema 为准;不要使用表中之外的字段。
 
+## Data-driven、fixture 与 variables
+
+- fixture 文件根必须是对象;多个文件按顺序深合并,字段冲突直接校验失败。
+- dataset 文件根必须是对象数组;`idField` 默认 `id`,每行值必须非空且唯一。
+- 每个数据行有独立 ExecutionContext,同一 Case 的行之间不能共享 extract 变量。
+- 可用作用域:
+  - `${fixture.*}`:合并后的共享 fixture
+  - `${dataset.*}`:当前数据行
+  - `${account.*}`:`accountRef` 对应凭据
+  - `${variable.*}`:`testpilot.yaml variables` 白名单
+  - `${name}`:之前 `extract` 产生的运行时变量
+- 禁止 `${env.*}` 或其他方式任意读取进程环境变量。
+
+`requires` 只检查路径存在且不是 `null`、空字符串或未解析的 `${ENV_VAR}`。缺失时该行不执行任何阶段,结果为 `skipped`,原因 `dependency-not-ready`。
+
+## setup / steps / teardown
+
+执行顺序固定:
+
+1. `requires` 预检
+2. `setup`
+3. `steps`
+4. `teardown`
+
+setup 失败时主结果 failed、跳过主步骤并执行 teardown;主步骤失败也执行 teardown。teardown 失败记 warning,不改变主结果。
+
+## UI 请求次数断言
+
+`expectRequests` 可附在 web/miniapp 的 `navigate`、`click`、`input`、`select`:
+
+```yaml
+- target: web
+  action: click
+  locator:
+    css: .submit
+  expectRequests:
+    - method: POST
+      urlContains: /api/orders
+      count: 1
+      windowMs: 1000
+```
+
+它只观察并计数,不拦截、不修改响应。断言失败时报告实际次数和已脱敏的匹配 URL。
+
 ## api 端(HTTP 接口测试与造数)
 
 `target: api` 走 HTTP 执行端:相对 `url` 按 `testpilot.yaml` 的 `api.baseUrl` 解析。典型用法:API 造数 → UI 操作 → API/JSON 断言的混合编排。

package/dist/skills/testpilot/workflows/analyze-result.md

@@ -2,7 +2,7 @@
 
 1. 执行 `npx csspilot report` 生成报告。
 2. 产物位于 `.testpilot/artifacts/runs/<run-id>/`:
-   - `report.json` —— 结构化结果,AI 优先读这个:`{ generatedAt, summary: { runId, status, totals, cases: [{ caseId, status, steps: [{ index, target, action, status, durationMs, error?, screenshot?, extracted? }] }] }, history(最近 12 次运行趋势), failures(失败分类明细:category / caseId / message) }`;失败步骤的 `category` ∈ assert / element / adapter / env / timeout / other
+   - `report.json` —— 结构化结果,AI 优先读这个:`{ generatedAt, summary: { runId, status, totals, cases: [{ caseId, rowId, status, skipReason?, missingDependencies?, warnings?, steps: [{ phase, index, target, action, status, durationMs, error?, screenshot?, extracted?, requestAssertions? }] }] }, history(最近 12 次运行趋势), failures(失败分类明细:category / caseId / message) }`;失败步骤的 `category` ∈ assert / element / adapter / env / timeout / other
    - `report.html` —— 交互式报告(步骤树、失败分类筛选、历史趋势)
    - `screenshots/`、`videos/`、`traces/`、`logs/` —— 失败取证
 3. 失败分析顺序:report.json 中失败步骤的 `category` 与 `error` → 对应 `screenshot` → `logs/run.log` → `events.ndjson`。
@@ -10,4 +10,6 @@
    - Case 问题(locator 过期、步骤错误)→ 修改 Case,重新 validate → run
    - 产品 bug → 停止修改 Case,向用户报告证据与结论
 5. 历史趋势中出现反复失败的用例(intermittent / flaky)要在结论中单独标注。
-6. 不要在未分析 Evidence 的情况下盲目重跑或修改 Case。
+6. `skipped(dependency-not-ready)` 先按 missingDependencies 补数据,不归类为产品 bug;teardown warning 单独报告,不把已通过主流程改判 failed。
+7. 请求次数断言失败时比较 `actualCount/count` 和匹配请求摘要,排查重复绑定、重试或双击。
+8. 不要在未分析 Evidence 的情况下盲目重跑或修改 Case。

package/dist/skills/testpilot/workflows/create-case.md

@@ -1,16 +1,33 @@
-# Workflow:创建测试 Case
-
-输入:用户需求,或 `test-requirements-review` 产出的**测试点清单**(推荐先做需求评审)。
-
-1. 尚无测试点清单时,先执行 `workflows/test-requirements-review.md`;已有清单则直接使用。
-2. 阅读本 Skill:`rules/dsl.md`、`rules/case-design.md`、`rules/locator.md`。
-3. 分析项目结构:确定被测端(miniapp / web)与业务入口页面。
-4. 针对测试点收集证据(读代码 / DOM / 现有测试),确定业务路径:从入口到业务结果页的完整步骤。
-5. 按 DSL 规范生成 Case,写入 `tests/e2e/cases/<case-id>.yaml`:
-   - 一条 Case 覆盖一个测试点(或一组强关联测试点)
-   - Case 的 `description` 注明关联的测试点编号(如 `测试点: TP-001`),保持需求可溯源
-   - 按评审产出的平台执行信息声明 `accountRef` / `workspace`;发现 `.env` 缺少某平台的地址或凭据变量时,向用户索取后写入 `.env`,**不写进 Case**
-6. 执行 `npx csspilot validate tests/e2e/cases/<case-id>.yaml`。
-7. 校验失败则修复 Case 后重新 validate,直到通过。
-
-禁止:跳过第 3-4 步直接生成 Case(AI 不能凭空生成测试)。
+# Workflow:创建测试 Case
+
+输入:用户需求,或 `test-requirements-review` 产出的**测试点清单**(推荐先做需求评审)。
+
+1. 尚无测试点清单时,先执行 `workflows/test-requirements-review.md`;已有清单则直接使用。
+2. 阅读本 Skill:`rules/dsl.md`、`rules/case-design.md`、`rules/locator.md`。
+3. 分析项目结构:确定被测端(miniapp / web)与业务入口页面。
+4. 针对测试点收集证据(读代码 / DOM / 现有测试),确定业务路径:从入口到业务结果页的完整步骤。
+5. 按 DSL 规范生成 Case,写入 `tests/e2e/cases/<case-id>.yaml`:
+   - 一条 Case 覆盖一个测试点(或一组强关联测试点)
+   - 多个测试点步骤完全一致、仅数据和预期不同,使用 `datasets` 形成 data-driven Case;否则保持独立 Case
+   - Case 的 `description` 注明关联的测试点编号(如 `测试点: TP-001`),保持需求可溯源
+   - 按评审产出的平台执行信息声明 `accountRef` / `workspace`;发现 `.env` 缺少某平台的地址或凭据变量时,向用户索取后写入 `.env`,**不写进 Case**
+   - 从需求与项目证据中识别最小 `requires`;项目没有账号/优惠/PPM 等概念时不要生成对应依赖
+   - 公共参数写入 `tests/e2e/data/` fixture;环境参数先加入 `testpilot.yaml variables` 白名单
+   - 造数与清理使用 `setup` / `teardown`;UI 动作需验证接口调用次数时使用 `expectRequests`
+   - 把该 Case 关联 TP 的每个 charter 视角写入 `tags`,与既有 tag(如 `smoke`)共存;一个 TP 多视角则多 tag。映射(视角定义见 `test-requirements-review` 步骤 6):
+
+     | 评审视角 | case tag |
+     | --- | --- |
+     | persona | `charter:persona` |
+     | 边界输入 | `charter:edge-input` |
+     | 数字与文案 | `charter:numbers-copy` |
+     | 状态恢复 | `charter:state-recovery` |
+     | 错误路径 | `charter:error-path` |
+
+     ```yaml
+     tags: [smoke, charter:persona, charter:error-path]
+     ```
+6. 执行 `npx csspilot validate tests/e2e/cases/<case-id>.yaml`。
+7. 校验失败则修复 Case 后重新 validate,直到通过。
+
+禁止:跳过第 3-4 步直接生成 Case(AI 不能凭空生成测试)。

package/dist/skills/testpilot/workflows/run-case.md

@@ -17,4 +17,7 @@ CLI → Case Loader → DSL Validator → Execution Engine → Adapter(Playwrigh
 - 只通过 testpilot CLI 执行测试,不要直接调用 playwright 或 wechat-devtools。
 - 被测服务需先就绪(如业务后端、本地页面服务),`navigate` 的相对 url 基于 testpilot.yaml 的 `web.baseUrl` 解析。
 - 环境变量来源:shell / CI secrets,或项目根目录 `.env` 文件(CLI 自动加载,真实环境变量优先);`.env` 含敏感信息,确认已加入 .gitignore。
+- Case 只能读取 `testpilot.yaml variables` 白名单映射后的 `${variable.*}`,不能直接访问任意环境变量。
+- 运行前按 dataset 行展开并预检 `requires`;依赖缺失的行显示 `skipped(dependency-not-ready)`,不是产品失败。
+- 每行按 setup → steps → teardown 执行;teardown warning 不改变主结果。
 - 运行产物写入 `.testpilot/artifacts/runs/<run-id>/`(screenshots / traces / logs)。

package/dist/skills/testpilot/workflows/test-requirements-review.md

@@ -1,61 +1,143 @@
-# Workflow:测试需求评审(可测性评审 + 测试点分析)
-
-输入:需求文档 / PRD / 用户的一句话(如"帮我测试用户下单")。
-产出:**测试点清单** + **平台执行信息表** + 澄清问题 + 评审结论。测试点清单是 `create-case` 的正式输入。
-
-## 步骤
-
-1. **复述理解**:用自己的话列出需求覆盖的功能点与业务流程,向用户确认理解偏差。
-2. **平台盘点**:识别需求涉及的执行端(miniapp / web / api)。跨端需求(如"小程序下单、Web 后台验证")必须逐平台澄清执行信息,见下方"多平台"一节。
-3. **可测性检查清单**(逐项过):
-   - 验收标准是否明确:输入 / 操作步骤 / 预期结果是否可判定
-   - 边界与异常:空值、极值、重复提交、并发、权限、网络异常
-   - 数据准备可行性:测试账号、mock 数据、上下游依赖是否可用
-   - 平台与入口:miniapp / web 的页面路径与入口是否真实存在(不确定时先看项目代码)
-   - 回归范围:改动是否影响现有功能,需要哪些已有 Case 回归
-4. **输出测试点清单**,每条包含:
-
-   | 字段 | 说明 |
-   | --- | --- |
-   | 编号 | `TP-001` 格式,Case 需回链 |
-   | 模块 | 所属功能模块 |
-   | 场景 | 一句话描述验证什么 |
-   | 类型 | 正向 / 边界 / 异常 |
-   | 优先级 | P0 / P1 / P2 |
-   | 平台 | miniapp / web / 双端 |
-
-5. **澄清阻塞项**:需求缺失、矛盾、不可判定时,列出问题向用户提问。**不猜测**。
-6. **给出评审结论**:
-   - 可测:测试点清单完整,直接进入 `create-case`
-   - 有条件可测:部分测试点依赖澄清,先对可执行部分建 Case
-   - 不可测:说明缺口,等待需求补充
-
-## 多平台:平台执行信息澄清
-
-需求涉及多个平台时,**每个平台都必须澄清以下三项**;缺任何一项,该平台相关测试点只能标记"有条件可测",不得开始写 Case:
-
-| 平台 | 必须澄清 | 落地位置 |
-| --- | --- | --- |
-| web | 测试地址(baseUrl)+ 页面入口路由 + 登录角色 | `.env` 的 `WEB_BASE_URL` / `TEST_BASE_URL`;`accountRef` |
-| miniapp | 小程序项目路径 + 起始页面路由 + 登录角色(连哪个环境后端) | `.env` 的 `MINIAPP_PROJECT_PATH`;`accountRef` |
-| api | 服务 baseUrl + 鉴权方式(token / session)+ 账号角色 | `.env` 的 `API_BASE_URL`;`accountRef` |
-
-规则:
-
-- **登录角色**:每个平台确认用什么角色(普通用户 / 管理员 / 游客),映射为 `accountRef`(如 `admin` / `test-user`);真实凭据放 `TESTPILOT_ACCOUNT_<REF大写>` 环境变量或 Server Secrets,**禁止写进 Case**
-- **测试地址**:一律指向测试环境,写入 `.env`(如 `WEB_BASE_URL`);**禁止把内网 / 生产地址写进 Case 或 testpilot.yaml**
-- **使用 Workspace 的项目**:以上信息应登记为 Workspace 的绑定(项目 → 环境),Case 用 `workspace: <名称>` 声明,不逐条硬编码
-
-### 澄清问题示例(多平台需求)
-
-- Web 后台的测试地址是什么?订单查询页面的入口路由是?
-- 小程序连接哪个环境的后端?小程序项目目录在本机哪里?
-- 各平台分别用什么角色登录(普通用户 / 管理员)?该角色是否有完成流程所需的权限?
-- 这些地址和账号是否已写入 `.env`?缺哪个我来补?
-
-## 铁律
-
-- 没有测试点清单,不要进入 `create-case`。
-- 涉及多平台但执行信息(地址 / 入口 / 登录角色)不全时,结论只能是"有条件可测",先澄清再建 Case。
-- 评审基于需求 + 项目代码/页面证据;两项都没有时先收集证据,不空谈。
-- 每个测试点必须可验证:都能回答"怎么判定通过"。
+# Workflow:测试需求评审(可测性评审 + 测试点分析)
+
+输入:需求文档 / PRD / 用户的一句话(如"帮我测试用户下单")。
+产出:**原子规则清单** + **规则矩阵** + **测试点清单** + **视角覆盖表** + **QA → TestPilot Coverage Map** + **平台执行信息表** + 澄清问题 + 评审结论。测试点清单是 `create-case` 的正式输入。
+
+## 步骤
+
+1. **复述理解**:用自己的话列出需求覆盖的功能点与业务流程,向用户确认理解偏差。
+2. **平台盘点**:识别需求涉及的执行端(miniapp / web / api)。跨端需求(如"小程序下单、Web 后台验证")必须逐平台澄清执行信息,见下方"多平台"一节。
+3. **可测性检查清单**(逐项过):
+   - 验收标准是否明确:输入 / 操作步骤 / 预期结果是否可判定
+   - 边界与异常:空值、极值、重复提交、并发、权限、网络异常
+   - 数据准备可行性:测试账号、mock 数据、上下游依赖是否可用
+   - 平台与入口:miniapp / web 的页面路径与入口是否真实存在(不确定时先看项目代码)
+   - 回归范围:改动是否影响现有功能,需要哪些已有 Case 回归
+4. **拆解原子规则**:从验收标准中提取一条条可独立判定的规则或数据点。粒度必须是“一个输入/条件组合对应一个可判断预期”,不能把多个折扣、角色或状态变化塞进一个测试点。
+5. **建立规则矩阵**:
+   - 识别需求中的“类型 × 组合”维度,如折扣类型 × 账号等级 × 门槛边界 × 是否叠加
+   - 列出每个维度的值域、来源证据和约束
+   - 展开全部有效组合,每个有效组合至少生成一个测试点
+   - 互斥、不适用或业务禁止的组合不能静默删除,必须记录排除理由及需求证据
+   - 项目没有账号、优惠、PPM 等概念时不得自动添加这些维度
+6. **套用 charter 视角矩阵**(固定 5 视角,逐视角过 checklist,为每个 TP 标注视角,可多个):
+
+   | 视角 | tag | 判定问题 |
+   | --- | --- | --- |
+   | persona | `charter:persona` | 首次用户 / 未登录 / 无权限角色走这个流程会怎样? |
+   | 边界输入 | `charter:edge-input` | 空值 / 极值 / 特殊字符 / 超长输入? |
+   | 数字与文案 | `charter:numbers-copy` | 金额计算、计数、提示文案是否正确一致? |
+   | 状态恢复 | `charter:state-recovery` | reload / 中断 / 返回后状态是否保持? |
+   | 错误路径 | `charter:error-path` | 网络失败 / 服务端错误 / 非法操作的表现? |
+
+   - 规则:每个测试点至少标注一个视角;某视角在本需求内无任何测试点时,**必须显式记录「不适用 + 需求证据」,禁止静默跳过**。
+   - **三分判定规则**:视角问题想到需求未覆盖的场景(如重复点击、非法输入、文案细节)时,按「需求是否给出预期结果」当场归类,三选一,禁止静默丢弃:
+
+     | 去向 | 条件 | 动作 |
+     | --- | --- | --- |
+     | 纳入 TP | 需求已有该场景的预期结果 | 进步骤 7 测试点清单,打视角 tag,正常进 `create-case` |
+     | 澄清问题 | 需求无预期,且出问题伤业务(资损 / 核心流程 / 数据一致性) | 列入澄清问题(步骤 9),标注视角与风险等级;整单结论至多「有条件可测」 |
+     | 暂缓 | 需求无预期,且不伤业务 | 视角覆盖表记「暂缓 + 理由」 |
+
+     澄清问题得到需求方答复后,回流为新 TP 再进 `create-case`。
+
+7. **输出测试点清单**,每条包含:
+
+   | 字段 | 说明 |
+   | --- | --- |
+   | 编号 | `TP-001` 格式,Case 需回链 |
+   | 模块 | 所属功能模块 |
+   | 场景 | 一句话描述验证什么 |
+   | 类型 | 正向 / 边界 / 异常 |
+   | 优先级 | P0 / P1 / P2 |
+   | 平台 | miniapp / web / 双端 |
+   | 视角 | 步骤 6 标注的 charter 视角(可多个) |
+
+8. **对标 QA 用例库**(用户提供时):
+   - 将每条 QA 用例映射到一个或多个 TP
+   - 标记 `covered` / `partial` / `missing` / `conflict`
+   - QA 有而 TestPilot 无的覆盖形成待补 checklist
+   - TestPilot 有而 QA 无的覆盖保留并说明来源,不得为追求一致而删除
+   - 将完整结果写入 `tests/e2e/reviews/<需求-slug>-coverage.md`,回复中只给摘要和文件路径
+9. **澄清阻塞项**:需求缺失、矛盾、不可判定时,列出问题向用户提问。**不猜测**。charter 三分判定产生的澄清问题(带视角与风险等级)一并在此列出。
+10. **给出评审结论**:
+   - 可测:测试点清单完整,直接进入 `create-case`
+   - 有条件可测:部分测试点依赖澄清,先对可执行部分建 Case
+   - 不可测:说明缺口,等待需求补充
+
+## 规则矩阵模板
+
+```markdown
+| 维度 | 值域 | 来源证据 | 约束 |
+| --- | --- | --- | --- |
+| discountType | percentage / fixed | PRD §3.2 | fixed 不参与 VIP 加码 |
+| accountLevel | normal / vip | account.ts:L10-L16 | 游客不可下单 |
+
+| 组合 ID | discountType | accountLevel | 有效性 | 预期 / 排除理由 | TP |
+| --- | --- | --- | --- | --- | --- |
+| C-001 | percentage | vip | 有效 | 折扣后再加 VIP 优惠 | TP-001 |
+| C-002 | fixed | vip | 排除 | PRD §3.2 明确 fixed 不叠加 | — |
+```
+
+矩阵只使用需求、代码、配置、已有 Case 或 QA 用例中的真实维度。缺少证据时提出问题,不得套用电商默认字段。
+
+## QA → TestPilot Coverage Map 模板
+
+```markdown
+| QA Case | 对应 TP | 覆盖状态 | 差异 / 冲突 | 行动 |
+| --- | --- | --- | --- | --- |
+| QA-101 | TP-001 | covered | — | 无 |
+| QA-102 | TP-004 | partial | 缺少上边界 | 补 dataset 行 |
+| QA-103 | — | missing | TestPilot 无对应 TP | 新增 TP 和 Case |
+
+## Missing coverage checklist
+- [ ] QA-103: 新增……
+```
+
+## 视角覆盖表模板
+
+写入评审产物 `tests/e2e/reviews/<需求-slug>-coverage.md` 末尾:
+
+```markdown
+## 视角覆盖表
+
+| 视角 | 测试点 | 说明 |
+| --- | --- | --- |
+| persona | TP-001, TP-003 | 覆盖首次用户与无权限角色 |
+| edge-input | TP-002 | 覆盖空值与超长输入 |
+| numbers-copy | TP-001 | 金额计算 |
+| state-recovery | 暂缓 | 需求无跨刷新状态(PRD §2 未涉及),不伤业务 |
+| error-path | TP-004 | 支付失败回退;连点提交无预期且涉资损 → 澄清 Q-2 |
+```
+
+## 多平台:平台执行信息澄清
+
+需求涉及多个平台时,**每个平台都必须澄清以下三项**;缺任何一项,该平台相关测试点只能标记"有条件可测",不得开始写 Case:
+
+| 平台 | 必须澄清 | 落地位置 |
+| --- | --- | --- |
+| web | 测试地址(baseUrl)+ 页面入口路由 + 登录角色 | `.env` 的 `WEB_BASE_URL` / `TEST_BASE_URL`;`accountRef` |
+| miniapp | 小程序项目路径 + 起始页面路由 + 登录角色(连哪个环境后端) | `.env` 的 `MINIAPP_PROJECT_PATH`;`accountRef` |
+| api | 服务 baseUrl + 鉴权方式(token / session)+ 账号角色 | `.env` 的 `API_BASE_URL`;`accountRef` |
+
+规则:
+
+- **登录角色**:每个平台确认用什么角色(普通用户 / 管理员 / 游客),映射为 `accountRef`(如 `admin` / `test-user`);真实凭据放 `TESTPILOT_ACCOUNT_<REF大写>` 环境变量或 Server Secrets,**禁止写进 Case**
+- **测试地址**:一律指向测试环境,写入 `.env`(如 `WEB_BASE_URL`);**禁止把内网 / 生产地址写进 Case 或 testpilot.yaml**
+- **使用 Workspace 的项目**:以上信息应登记为 Workspace 的绑定(项目 → 环境),Case 用 `workspace: <名称>` 声明,不逐条硬编码
+
+### 澄清问题示例(多平台需求)
+
+- Web 后台的测试地址是什么?订单查询页面的入口路由是?
+- 小程序连接哪个环境的后端?小程序项目目录在本机哪里?
+- 各平台分别用什么角色登录(普通用户 / 管理员)?该角色是否有完成流程所需的权限?
+- 这些地址和账号是否已写入 `.env`?缺哪个我来补?
+
+## 铁律
+
+- 没有测试点清单,不要进入 `create-case`。
+- 涉及多平台但执行信息(地址 / 入口 / 登录角色)不全时,结论只能是"有条件可测",先澄清再建 Case。
+- 评审基于需求 + 项目代码/页面证据;两项都没有时先收集证据,不空谈。
+- 每个测试点必须可验证:都能回答"怎么判定通过"。
+- 视角覆盖表缺任意一行(含不适用 / 暂缓行)不得给出评审结论。
+- charter 三分判定判为「澄清问题」的场景,必须出现在澄清问题清单中(带视角与风险等级),否则不得给出评审结论。