@guanlin4924/devflow-pi 0.1.93 → 0.1.95

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/references/project-dsl-contract.md

@@ -1,190 +1,115 @@
-# Project DSL Contract
+# Runtime DSL Contract (`devflow-test-dsl/v1`)
 
-Legacy normalization input is an object with metadata and cases:
+`compile_dsl.py` 为每个冻结的自动化 `ui` / `api_flow` TC 写一个 DSL 文件：
 
-```json
-{
-  "metadata": {
-    "feature": "Feature name",
-    "phase": "01-Feature",
-    "generated_by": "workflow-generate-mainflow-cases",
-    "project_id": 1
-  },
-  "cases": [
-    {
-      "project_id": 1,
-      "name": "Case name",
-      "description": "Positive mainflow purpose and traceability.",
-      "tags": ["api-mainflow"],
-      "dsl_json": {
-        "name": "Case name",
-        "description": "Same behavior summary.",
-        "tags": ["api-mainflow"],
-        "variables": {},
-        "steps": []
-      },
-      "source_evidence": [
-        {
-          "path": ".planning/features/Feature/后端技术方案.md",
-          "line": 120,
-          "reason": "API contract source"
-        }
-      ]
-    }
-  ]
-}
+```text
+.devflow/planning/generated-cases/{feature}/TC-xxxx.json
 ```
 
-`cases[*]` must be compatible with backend `CaseCreate` after normalization:
+DSL 是纯数据，由 Devflow Playwright Runtime 解释执行，Core 用同一份 Schema 校验。权威定义：`plugins/devflow-quality/runtime/playwright/devflow-test-dsl-v1.schema.json`（JSON Schema 2020-12，`additionalProperties: false`）；Python 侧实现是 Core `dsl_v1.py`（Schema + 语义）与 `dsl_coverage.py`（`covers` 结构覆盖）。AI 不直接写这个文件，而是写 `case-descriptions.json`（`intermediate-format.md`），由编译器生成。
 
-- `project_id`: integer. If no project id is known, use `metadata.project_id` or `1` and record an import note.
-- `name`: non-empty string.
-- `description`: optional string.
-- `dsl_json`: object.
-- `tags`: exactly one of `["api-mainflow"]` or `["ui-mainflow"]` unless the case is intentionally mixed UI flow with API setup; mixed UI flows still use `["ui-mainflow"]`.
+## 文件与门禁的关系
 
-`source_evidence` is allowed in drafts. Normalization moves it to metadata and removes it from import payload cases.
+- 一 TC 一文件，文件名必须是 `<tc_id>.json`，与 `acceptance-test-bindings.json` 里 `devflow_playwright` 绑定的 `dsl_file` 对应；
+- `tc_sha256` = 冻结 TC `data` 的 JCS SHA-256（Core `tc_hash.py` 计算，编译器不接受 AI 提供的值）；TC 变化后 DSL 必须重新编译；
+- `dsl_sha256` = 该文件**原始字节**的 SHA-256。用户在 `/devflow` → “待审批”中批准的是这个具体文件：文件任何变化都会使对应 TC 的 `execution_plan` 批准失效；
+- 没有有效 `execution_plan` 批准的 DSL 永远 `blocked(dsl_not_approved)`，不会执行、不会进入收口；
+- 校验入口是整个 `generated-cases/{feature}` 目录（`validate_case_payloads.py`），目录里只有 `TC-xxxx.json` 被当作 DSL。`case-descriptions.json`、`codebase-discovery.json`、`source-map.md` 等是辅助文件，不是 DSL。
 
-## DSL Step Shape
+## 顶层结构
 
-Each step needs:
+```json
+{
+  "schema_version": "devflow-test-dsl/v1",
+  "tc_id": "TC-0001",
+  "tc_sha256": "<64 hex>",
+  "name": "登录后显示欢迎语",
+  "variables": {
+    "user": { "value": "qa-user" },
+    "password": { "secret": "QA_PASSWORD" }
+  },
+  "data": { "namespace": "${execution_id}", "setup": [], "cleanup": [] },
+  "steps": [ ]
+}
+```
 
-- `id`
-- `name`
-- `driver`: `api`, `web`, or `ui`
-- `action`
-- `params`
-- `depends_on`
-- `assertions`
-- `timeout_ms`
-- `on_failure`
+- 上述 7 个顶层键全部必填，不允许其他键；
+- `variables`：`{ "value": <string|number|boolean>, "sensitive"?: bool }` 或 `{ "secret": "<ENV_KEY>" }`（运行时取自已批准 profile 的 `secret_env`，永远敏感）。不允许重定义内置变量 `execution_id`/`namespace`；
+- `data.namespace` 必填，缺省由编译器写成 `${execution_id}`；`owner`、`accounts[]`、`repeatable` 可选；
+- `data.setup[]` / `data.cleanup[]` **只允许 API 步骤**；`cleanup` 步骤不得带 `covers`；
+- `steps[]`：1–200 个步骤，按序执行；任一步失败即停止主流程，cleanup 仍会执行，cleanup 失败使结果变为 blocked。
 
-API steps require `params.url`. Prefer variable placeholders such as `${base_url}` instead of environment-specific hosts when possible.
+## 步骤
 
-UI steps with `driver: "ui"` require:
+公共键：`id`（`[A-Za-z0-9][A-Za-z0-9_-]{0,63}`，全 DSL 唯一）、`driver`（`ui`|`api`）、`action`、`covers`、`timeout_ms`（100–600000）。
 
-- `strategy`: depends on step type (see below)
-- `target`: non-empty unless `strategy.mode` is `ai_only`
+### UI（`driver: "ui"`）
 
-### Strategy Selection
+| action | 键 |
+|---|---|
+| `goto` | `url` |
+| `click`、`check`、`uncheck`、`assert_visible` | `target` |
+| `fill` | `target`、`value`（字符串） |
+| `select` | `target`、`value`（字符串或字符串数组） |
+| `wait_for` | `target`、`state`（`visible`\|`hidden`\|`attached`\|`detached`）；只做条件等待，无固定 sleep |
+| `assert_text` | `target`、`match`（`exact`\|`contains`）、`expected`，可选 `normalize_whitespace`（缺省 true）、`case_sensitive`（缺省 true） |
+| `assert_url` | `match`、`expected` |
+| `screenshot` | 可选 `name`（`[A-Za-z0-9_-]{1,64}`）、`full_page` |
+
+**不存在**：`hover`、`assert_url_contains`、`assert_any_visible`、固定等待、`evaluate_js`、任意脚本、`strategy`、`prompt`、`params`、`depends_on`、`on_failure`。
 
-**Action steps** (click, fill, select, hover) — `structured_first` + midscene fallback:
+### target（六选一，strict：多于一个匹配即失败）
 
 ```json
-{ "strategy": { "mode": "structured_first", "fallback": "midscene" } }
+{ "testid": "login-submit" }
+{ "role": "button", "name": "登录", "exact": true }
+{ "label": "用户名", "exact": true }
+{ "placeholder": "请输入名称", "exact": true }
+{ "text": "欢迎", "exact": true }
+{ "css": "[data-qa='welcome']" }
 ```
 
-**Verification steps** (assert_text, assert_visible, wait for success/result) — prefer `ai_only`. Visual verification of transient UI (toast messages, success prompts, dialog confirmations) is an AI task:
+`testid` 与 `css` 不带 `exact`。`xpath`、`near_text`、`by/value` 形式、AI 视觉定位均不存在。
 
-```json
-{ "strategy": { "mode": "ai_only" } }
-```
+### API（`driver: "api"`, `action: "request"`）
 
 ```json
 {
-  "id": "s06",
-  "name": "验证编辑成功",
-  "driver": "ui",
-  "action": "act",
-  "target": { "label": "操作成功" },
-  "strategy": { "mode": "ai_only" },
-  "prompt": "检查页面是否出现'操作成功'的提示消息，确认编辑操作已成功完成",
-  "depends_on": ["s05"],
-  "timeout_ms": 15000
+  "id": "a02", "driver": "api", "action": "request", "method": "GET",
+  "url": "/api/orders/${order_id}", "query": { "verbose": true },
+  "expect_status": 200,
+  "assertions": [ { "pointer": "/data/status", "op": "equals", "value": "created" } ],
+  "extract": { "order_id": { "pointer": "/data/id" } },
+  "covers": { "oracle": true }
 }
 ```
 
-### Target Field Specification
-
-`target` is a **flat key-value object**. The key IS the locator type. The system resolves them in this priority: `css → xpath → label → placeholder → role+name → near_text`.
-
-**There is NO `by` field. Do NOT invent `{"by": "...", "value": "..."}` format.**
-
-#### Decision Table: Which Key for Which Scenario
-
-| 场景 | 选哪个 key | 示例 | 原因 |
-|---|---|---|---|
-| 页面唯一按钮/菜单/tab | `label` + `exact` | `{"label": "新增项目库", "exact": true}` | 文本最稳定，不受CSS重构影响 |
-| 表格行操作按钮（每行重复） | `css` 精确定位 | `{"css": "tr:nth-child(2) .edit-btn"}` | 必须定位到具体行，"编辑"不唯一 |
-| 对话框底部确定/取消 | `css` 限定作用域 | `{"css": ".el-dialog__footer .el-button--primary"}` | 防止dialog外也有同名按钮 |
-| 输入框（有唯一placeholder） | `placeholder` | `{"placeholder": "请输入后台名称"}` | 语义清晰，自动scope内唯一 |
-| 表单项旁边控件 | `near_text` | `{"near_text": "后台名称"}` | label文本定位，控件自动匹配 |
-| ARIA友好的按钮/组件 | `role` + `name` | `{"role": "button", "name": "确定"}` | 无障碍属性，可访问性最好 |
-| 无他法定位时 | `xpath` | `{"xpath": "//button[text()='确定']"}` | 最后的结构化手段 |
-| 以上均不稳定 | `ai_only` strategy | 不走target，用AI视觉识别 | 放弃结构化，交AI处理 |
+- `method`：`GET`/`POST`/`PUT`/`PATCH`/`DELETE`；`url` 以 `/` 开头相对 profile 的 `api_base_url`（缺省 `base_url`），绝对 URL 的 origin 须在 profile `api_origins` 中；不自动跟随重定向；
+- `headers`、`query`（标量）、`json`（任意 JSON，字符串叶子可引用变量）；
+- `expect_status`（100–599）；`assertions[]` 的 `op` 为 `equals`/`not_equals`/`contains`/`exists`/`not_exists`，`pointer` 为 JSON Pointer，`exists`/`not_exists` 不带 `value`，其余必须带；
+- `extract`：`{ name: { pointer, sensitive? } }`，之后的步骤可用 `${name}`，不得重定义已存在变量；
+- `retry: { max_attempts: 2–5, on: [connection_error|timeout|rate_limited] }`，只重试传输失败；POST/PATCH 需 `idempotent: true`；默认不重试；
+- 通过页面同一 BrowserContext 发送，与 UI 登录态共享 cookie；
+- `Authorization`、`Cookie`、`X-Api-Key` 等敏感请求头只能由 secret/sensitive 变量拼成，如 `"Bearer ${auth_token}"`。
 
-#### Key Selection Priority for Generation
+变量引用 `${name}` 必须已定义（内置、`variables`、先前 `extract`）。不得出现凭据字面量：真实密码、token、cookie 用 `{ "secret": ... }` 变量，`validate_case_payloads.py` 会拒绝形似密钥的字面值。
 
-1. **先看唯一性**：页面只有一个"新增项目库"按钮 → `label`；每行都有"编辑" → 不能只用 `label`
-2. **再看作用域**：对话框内用 `css` 限定 `.el-dialog__footer .el-button--primary`
-3. **input/textarea 优先用** `placeholder`
-4. **表单项控件用** `near_text`
-5. **都不行再用** `xpath` **或** `ai_only`
-
-#### Correct Format Examples
+## covers
 
 ```json
-// 页面唯一按钮 → label
-{ "label": "新增项目库", "exact": true }
-
-// 表格行按钮 → css 精确定位
-{ "css": "tr:nth-child(2) .edit-btn" }
-
-// 对话框确定按钮 → css 限定作用域
-{ "css": ".el-dialog__footer .el-button--primary" }
-
-// 输入框 → placeholder
-{ "placeholder": "请输入后台名称" }
+{ "covers": { "preconditions": [1], "steps": [2, 3], "oracle": true } }
 ```
 
-### Assertion Rules
-
-**API steps** (`driver: "api"`) use `assertions[]` with these types:
-
-| Type | Behavior |
-|---|---|
-| `equals` | `actual == expected` |
-| `status_code` | HTTP 状态码 |
-| `contains` | `expected in actual` |
-| `json_path_equals` | JSONPath 取值相等 |
-| `json_path_exists` | JSONPath 路径存在 |
-| `regex` | 正则匹配 |
-| `not_equals` / `not_contains` / `greater_than` / `less_than` / `in` / `not_in` / `is_empty` / `is_not_empty` |
-
-**`"text"` is NOT a valid assertion type.** It will raise `ValueError: unsupported assertion type: text`.
+下标从 1 开始，指向冻结 TC 的 `preconditions[]` / `steps[]`。Core 硬校验：每个前置条件和步骤都被至少一个步骤覆盖；`oracle` 被至少一个非弱断言的主流程断言步骤覆盖（`wait_for`、`screenshot` 不是断言；弱断言指仅断言静态入口元素可见、断言自己刚操作的元素、仅检查 2xx 无响应体断言）。这只发现遗漏和明显弱断言，语义是否充分由独立 AI 审查（建议性）与人工批准（权威）判断。
 
-**Web/UI steps** (`driver: "web"` / `"ui"`) do NOT use `assertions[]` for text/visibility checks. Use assertion **actions** instead:
+## 校验命令
 
-```json
-// UI verification — use AI-only, not structured
-{
-  "id": "s06",
-  "name": "验证操作成功",
-  "driver": "ui",
-  "action": "act",
-  "target": { "label": "操作成功" },
-  "strategy": { "mode": "ai_only" },
-  "prompt": "检查页面是否出现'操作成功'的提示消息，确认操作已成功完成",
-  "depends_on": ["s05"],
-  "timeout_ms": 15000
-}
+```text
+devflow_mainflow(action="validate", args=[".devflow/planning/generated-cases/{feature}", "--suite", ".devflow/planning/requirements/{feature}/tests.json", "--output", ".devflow/planning/generated-cases/{feature}/validation-report.md"])
 ```
 
-Valid assertion actions for web/ui (use ai_only for these): `assert_text`, `assert_visible`, `assert_url_contains`, `assert_any_visible`.
-
-For API steps, assertion example:
+校验是纯数据操作，不 import、不执行被测项目的任何代码（`--discovery` 已废弃并被忽略）。检查项：Schema、语义（唯一 ID、变量作用域、重试安全、敏感头）、密钥字面量、`tc_id` 存在于冻结 suite、文件名与 `tc_id` 一致、`tc_sha256` 与冻结 TC 一致、`covers` 结构覆盖、每个 TC 至多一个 DSL。目录内缺少 DSL 的自动化 `ui`/`api_flow` TC 会以警告列出（它们会在门禁被 `dsl_not_approved` 阻断）。
 
-```json
-{
-  "id": "api-login",
-  "driver": "api",
-  "action": "post",
-  "params": { "url": "${base_url}/auth/login", "json": { "userid": "${userid}", "password": "${password}" } },
-  "assertions": [
-    { "type": "status_code", "expected": 200 },
-    { "type": "json_path_exists", "path": "headers.X-Jwt-Token" }
-  ]
-}
-```
+## 旧 TestAgent 导入格式
 
-Do not include real credentials, tokens, cookies, passwords, API keys, or production secrets. Use variables like `${auth_token}` or placeholders like `<token>` only.
+旧的 TestAgent 导入载荷（`project_id` + `dsl_json`、`strategy`/Midscene、`params`、`depends_on`、xpath/near_text 等）**不是** Runtime DSL，不参与门禁，本 Skill 不再教授。仅当开发者明确要求 TestAgent 导入文件时，才运行 `scripts/export_legacy_testagent.py`；其产物不能绑定到 `devflow_playwright`、不能被批准为执行计划、不能计入验收结果，也不得写成 `TC-xxxx.json`。`case-import-payloads.json` 这个名字只属于该 legacy 导出，绝不是 Runtime DSL 产物。

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/references/ui-mainflow-rules.md

@@ -1,110 +1,63 @@
 # UI Mainflow Rules
 
-UI cases validate successful user journeys through importable DSL.
+UI 用例把冻结的、自动化的 `execution_surface: ui` TC（含存量推导为 `ui` 的 `page` TC）落成确定性的 `devflow-test-dsl/v1`。AI 写 `case-descriptions.json`（格式见 `intermediate-format.md`），`compile_dsl.py` 生成 `TC-xxxx.json`（形状见 `project-dsl-contract.md`）。
 
 ## Hard Rule: Source-Backed Terminology
 
-**All UI text in locators, step names, and descriptions MUST be exact strings from source code.** Never invent, translate, guess, or "improve" the text. If the code says "查询" (query button text), the step name and locator must say "查询" — not "搜索", not "查找".
+**locator 与断言里的界面文本必须逐字来自源码。** 不得编造、翻译、猜测或“改进”。源码写“查询”就写“查询”，不写“搜索”“查找”。
 
-Extract locator values from:
-- Template/JSX: `<el-button>查询</el-button>` → `locator: "text:查询"`
-- Placeholder attrs: `placeholder="请输入名称"` → `locator: "placeholder:请输入名称"`
-- Dialog titles: `<el-dialog title="新增项目">` → verify text "新增项目"
-- Menu/router config: `{ path: '/Project/List', meta: { title: '项目管理' } }`
+- 模板/JSX：`<el-button>查询</el-button>` → `role:button:查询` 或 `text:查询`
+- placeholder：`placeholder="请输入名称"` → `placeholder:请输入名称`
+- `data-testid`：`data-testid="save-btn"` → `testid:save-btn`
+- 提示/标题文案：`<el-dialog title="新增项目">` → `assert_text` 的 `expected: "新增项目"`
+- 菜单/路由配置：`{ path: '/Project/List', meta: { title: '项目管理' } }` → `goto` 的 `url` 与断言文案
 
-### List Page Patterns: Query vs Search
+列表页“查询/筛选”（表格上方表单、不跳转）与全局“搜索”（header/侧边栏、触发路由）是不同模式，一律以源码文本为准，不按 URL 或行为重新命名。
 
-| 模式 | 按钮文本(源码) | URL特征 | 行为 |
-|---|---|---|---|
-| 列表查询/筛选 | "查询" 或 "筛选" | `/List`, `/list`, `/index` | 表格上方表单,过滤不跳转 |
-| 全局搜索 | "搜索" | header/侧边栏 | 触发路由跳转 |
+## TC 忠实性
 
-**Do not reclassify**: 源码写"查询"就生成"查询",源码写"搜索"就生成"搜索"。不要根据URL或行为推断应该叫什么。
+- 一个 TC 一个 case；TC 的每个 `preconditions[i]`、`steps[i]` 都必须被某个 DSL 步骤的 `covers` 覆盖，`oracle` 必须被断言步骤覆盖（`covers: ["oracle"]`）。DSL 不得增删或改写 TC 的步骤与 oracle，源码只用来补充入口 URL、locator、测试数据。
+- oracle 断言要断言**结果**：`assert_text`（`match: exact` 或 `contains`）、`assert_url`、对流程刚产生的元素做 `assert_visible`。只断言静态入口元素可见、或断言自己刚点过的元素，会被 Core 判为弱断言而拒绝。
+- 生成范围是正向主流程：打开路由、创建/编辑/执行主记录、查看成功结果、保存预期状态。异常、权限、响应式/a11y、空状态、浏览器兼容、性能、纯视觉判断、无稳定 locator 或无法准备/隔离数据的 TC 不生成 DSL，改为在绑定阶段降级为 `manual`（需 `mode_override` 批准）或 `blocked`，并向用户说明。
 
 ## Step Rules
 
-- Prefer `driver: "ui"` for structured UI operations.
-- Use `driver: "web"` only for plain browser actions that do not need structured target dispatch.
-- `target` must be non-empty unless `strategy.mode` is `ai_only`.
-- Use API setup steps only when needed to make the UI journey deterministic.
+- 只用 v1 UI 动作：`goto`、`click`、`fill`、`select`、`check`、`uncheck`、`wait_for`、`assert_visible`、`assert_text`、`assert_url`、`screenshot`。没有 `hover`、`wait`（固定/加载等待）、`verify`、`act`、`assert_url_contains`、`inject_token`、`evaluate_js`。
+- 动作后需要等待时用 `wait_for`（locator + `state`），不要用固定 sleep；“URL 包含 X”用 `assert_url` + `match: "contains"`。
+- 需要预置数据或登录态时，用 `data.setup` 的 API 请求步骤，或显式 UI 登录步骤（`goto` + `fill` + `click`）；没有 `auth` 快捷方式。凭据写成 `variables` 里的 `{ "secret": "ENV_KEY" }`，绝不写字面量。
+- 需要清理时写 `data.cleanup` 的 API 步骤。测试数据使用 `${namespace}`/`${execution_id}` 命名，避免多次运行互相污染。
+- API 步骤也可以穿插在 UI 主流程里做旁路校验（共享 BrowserContext cookie）。
 
-### Strategy Selection: Action vs Verification
+## Locator 决策
 
-**Operating steps** (click, fill, select, hover): use `structured_first` + midscene fallback.
+顺序：`testid` → `role` → `label` / `placeholder` → `text` → `css`（最后手段）。
 
-```json
-{ "strategy": { "mode": "structured_first", "fallback": "midscene" } }
-```
-
-**Verification steps** (assert_text, assert_visible, wait for success/result): prefer `ai_only`. Visual verification is inherently an AI task — toast messages, success prompts, dialog confirmations are transient and their DOM structure varies. Structured locators waste time on the fallback path.
-
-```json
-{ "strategy": { "mode": "ai_only" } }
-```
-
-```json
-// CORRECT: AI-only verification after critical action
-{
-  "id": "s06",
-  "name": "验证编辑成功",
-  "driver": "ui",
-  "action": "act",
-  "target": { "label": "操作成功" },
-  "strategy": { "mode": "ai_only" },
-  "prompt": "检查页面上是否出现'操作成功'的提示消息，确认编辑操作已成功完成",
-  "depends_on": ["s05"],
-  "timeout_ms": 15000
-}
-```
-
-Use `structured` only when runtime validation proves the locator is unique and stable. Do NOT use `structured` for verification steps.
+1. 源码里有 `data-testid` 就用 `testid:`。没有而该元素是主流程的关键控件时，在 `source-map.md` 里记录“缺少 testid”，并建议开发者补上，不要靠猜。
+2. 有明确 ARIA 角色和可访问名称：`role:button:确定`。
+3. 表单控件：`label:用户名` 或 `placeholder:请输入名称`。
+4. 页面内唯一的可见文本：`text:xxx`。
+5. `css:` 只能用源码里确实存在的选择器，并在 `source-map.md` 注明出处；编译器对 `css` 及所有非 testid locator 打印警告。
 
-### Target Format: Scenario → Key Decision Table
+locator 是 strict 的：匹配多个元素就失败。表格每行重复的“编辑/删除/查看”、对话框里的“确定/取消”这类文本，`text:`/`role:` 几乎一定多匹配，编译器会警告；应改用行级/对话框内的 `data-testid`。`xpath:`、`near:`、`scope: row:N`/`dialog` 均不支持。禁止编造 CSS（含 `%`、纯容器类如 `.el-form-item__content`、`:nth-child` 位置选择器、过短选择器都会被拒绝）。
 
-`target` is a **flat key-value object** (no `by` field). The system resolves in priority: `css → xpath → label → placeholder → role+name → near_text`. Choose the right key based on the scenario:
+## Assertion Rules
 
-| 场景 | key | 示例 |
-|---|---|---|
-| 页面唯一按钮/菜单/tab | `label` + `exact` | `{"label": "新增项目库", "exact": true}` |
-| 表格行操作按钮（每行重复） | `css` 精确定位 | `{"css": "tr:nth-child(2) .edit-btn"}` |
-| 对话框底部确定/取消 | `css` 限定dialog | `{"css": ".el-dialog__footer .el-button--primary"}` |
-| 输入框（有唯一placeholder） | `placeholder` | `{"placeholder": "请输入后台名称"}` |
-| 表单项旁边控件 | `near_text` | `{"near_text": "后台名称"}` |
-| ARIA友好的按钮/组件 | `role` + `name` | `{"role": "button", "name": "确定"}` |
-| 无他法 | `xpath` 或 `ai_only` | `{"xpath": "//button[text()='确定']"}` |
-
-**Decision rule**: 先看唯一性（page-level唯一用label，行级重复用css），再看作用域（dialog内用css限定），input优先placeholder。不存在 `{"by": "xxx", "value": "yyy"}` 这种格式。
-
-### Assertion Rules
-
-**Web/UI steps use assertion ACTIONS, not `assertions[]`:**
+UI 断言只用断言动作，没有 `assertions[]`：
 
 ```json
-// CORRECT: 文本断言用 action
-{ "action": "assert_text", "target": { "label": "操作成功" }, "params": { "text": "操作成功" } }
-{ "action": "assert_visible", "target": { "css": ".el-dialog" } }
-{ "action": "assert_url_contains", "params": { "text": "/sadmin/a/org/Project/Gift" } }
+{ "action": "assert_text", "locator": "testid:toast", "match": "contains", "expected": "保存成功", "covers": ["oracle"] }
+{ "action": "assert_url", "expected": "/projects/list", "match": "contains" }
+{ "action": "assert_visible", "locator": "testid:result-panel" }
 ```
 
-```json
-// WRONG: "text" 不是合法断言类型，web/ui 不走 assertions[]
-{ "assertions": [{ "type": "text", "expected": "礼物库" }] }
-{ "assertions": [{ "type": "visible", "target": { "by": "css", "selector": ".el-dialog" } }] }
-```
-
-Valid assertion actions: `assert_text`, `assert_visible`, `assert_url_contains`, `assert_any_visible`.
-
-API steps use `assertions[]` with types: `equals`, `contains`, `status_code`, `json_path_equals`, `json_path_exists`, `regex`, etc. See `project-dsl-contract.md` for the full list.
+- 确定性：断言期望必须是源码/需求给出的确切文案，不使用 AI 视觉判断（`ai_only`、Midscene、prompt 都不存在）。
+- 短暂提示（toast）可能一闪而过：先 `wait_for` 它 `visible`，再 `assert_text`；或改为断言持久化的结果（列表行文本、URL、详情页字段）。
+- `wait_for` 与 `screenshot` 不算断言。
 
 ## Source Evidence
 
-Cite at least one planning artifact and one code artifact per case:
-
-- Planning: UI spec, frontend tech spec, feature breakdown, or change list.
-- Code: router, page/view, API client, and relevant component/store/hook files.
-
-## Positive Mainflow Boundary
+每个 case 在 `source-map.md` 里至少引用一份规划产物（UI-SPEC、前端技术方案、功能点梳理或变更清单）和一份代码产物（路由、页面/视图、API client、相关组件/store）。证据放在 `source-map.md` 与 `source_evidence` 备注中；它不写入 DSL。
 
-Allowed: open route, create/edit/run primary record, view success result, save expected state.
+## After compile
 
-Not allowed: validation errors, permission differences, responsive/a11y-only checks, empty state checks, browser compatibility, performance timing, or destructive cleanup beyond normal test setup.
+编译通过后仍要：整个目录校验 → 独立 AI 审查每个 DSL（对照 TC oracle，建议性）→ 用 `devflow_approval` 提交 `execution_plan` → 用户在 `/devflow` → “待审批”逐 TC 批准。没有批准的 DSL 不会执行。见 `SKILL.md`。