@guanlin4924/devflow-pi 0.1.96 → 0.1.97

package/plugins/devflow-quality/runtime/playwright/runner.spec.mjs

@@ -218,6 +218,8 @@ var UI_ACTIONS = new Set([
   "wait_for",
   "assert_visible",
   "assert_text",
+  "assert_each_text",
+  "assert_value",
   "assert_url",
   "screenshot"
 ]);
@@ -225,6 +227,13 @@ var API_ACTIONS = new Set(["request"]);
 var BUILTIN_VARIABLES = new Set(["execution_id", "namespace"]);
 var VAR_REF = /\$\{([^}]*)\}/g;
 var VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+var FRAGILE_CSS = [
+  /el-table_\d+(?:_column_\d+)?/,
+  /:nth-(?:last-)?(?:child|of-type)\(/,
+  /\[data-v-[0-9a-fA-F]{8}\]/,
+  /[A-Za-z]+[-_][0-9a-fA-F]{6,}/,
+  /_[A-Za-z0-9]{5,}_/
+];
 function collectRefs(value, out = new Set) {
   if (typeof value === "string") {
     for (const m of value.matchAll(VAR_REF))
@@ -305,11 +314,54 @@ function semanticIssues(dsl) {
           }
           defined.add(name);
         }
+      } else if (step.target && typeof step.target === "object") {
+        semanticTargetIssues(step.target, `${at}/target`, issues, step.action);
       }
     });
   }
   return issues;
 }
+function semanticTargetIssues(target, at, issues, action, depth = 0) {
+  const locatorKeys = ["testid", "role", "label", "placeholder", "text", "css"].filter((key) => (key in target));
+  if (locatorKeys.length > 1)
+    issues.push({ path: at, message: "target must contain exactly one locator form" });
+  if ("role" in target && !("name" in target))
+    issues.push({ path: at, message: "role target requires name" });
+  if ("name" in target && !("role" in target))
+    issues.push({ path: at, message: "name is only valid with role" });
+  if (typeof target.css === "string" && FRAGILE_CSS.some((pattern) => pattern.test(target.css))) {
+    issues.push({ path: `${at}/css`, message: "fragile generated/structural CSS is not allowed; use table/column, within, row, or a mapping anchor" });
+  }
+  if ("table" in target) {
+    const table = target.table;
+    const choices = table && typeof table === "object" ? ["near_heading", "testid", "only"].filter((key) => (key in table)) : [];
+    if (choices.length !== 1)
+      issues.push({ path: `${at}/table`, message: "table requires exactly one of near_heading, testid, or only" });
+    if (!("column" in target) && !("row" in target))
+      issues.push({ path: at, message: "table target requires column or row" });
+    if (target.table_kind !== undefined && target.table_kind !== "html" && target.table_kind !== "element-plus") {
+      issues.push({ path: `${at}/table_kind`, message: "table_kind must be html or element-plus" });
+    }
+  }
+  if ("column" in target && !("table" in target))
+    issues.push({ path: `${at}/column`, message: "column requires table" });
+  if (target.row && typeof target.row === "object") {
+    const row = target.row;
+    if ("equals" in row === "contains" in row)
+      issues.push({ path: `${at}/row`, message: "row requires exactly one of equals or contains" });
+    if (!("column" in row))
+      issues.push({ path: `${at}/row`, message: "row requires column" });
+  }
+  if ("table" in target && !("row" in target) && action !== "assert_each_text") {
+    issues.push({ path: at, message: "table/column targets require assert_each_text or a row restriction" });
+  }
+  if (target.within !== undefined) {
+    if (depth >= 2)
+      issues.push({ path: `${at}/within`, message: "within nesting exceeds maximum depth 2" });
+    else if (target.within && typeof target.within === "object")
+      semanticTargetIssues(target.within, `${at}/within`, issues, action, depth + 1);
+  }
+}
 
 class UnsetVariableError extends Error {
   variable;
@@ -697,13 +749,22 @@ async function executeApi(step, ctx) {
     }
   }
   for (const [name, spec] of Object.entries(step.extract ?? {})) {
-    const found = parsed ? jsonPointer(json, spec.pointer) : { found: false };
-    if (!found.found) {
-      throw new StepFailure("failed", "extract_missing", `extract ${name}: pointer ${spec.pointer} not found`, details);
+    let value;
+    if (spec.header !== undefined) {
+      const headers2 = response.headers();
+      const header = Object.entries(headers2).find(([key]) => key.toLowerCase() === spec.header.toLowerCase());
+      if (!header)
+        throw new StepFailure("failed", "extract_missing", `extract ${name}: header ${spec.header} not found`, details);
+      value = header[1];
+    } else {
+      const found = parsed ? jsonPointer(json, spec.pointer ?? "") : { found: false };
+      if (!found.found)
+        throw new StepFailure("failed", "extract_missing", `extract ${name}: pointer ${spec.pointer} not found`, details);
+      value = found.value;
     }
-    if (spec.sensitive)
-      ctx.redactor.add(found.value);
-    ctx.vars.set(name, found.value);
+    if (spec.header !== undefined ? spec.sensitive !== false : spec.sensitive === true)
+      ctx.redactor.add(value);
+    ctx.vars.set(name, value);
   }
   return details;
 }
@@ -712,31 +773,198 @@ async function executeApi(step, ctx) {
 import path from "node:path";
 import fs from "node:fs";
 var POLL_MS = 100;
-function buildLocator(page, target, ctx) {
+var normalized = (value) => value.replace(/\s+/g, " ").trim();
+var rootLocator = (root, selector) => root.locator(selector);
+function baseLocator(root, target, ctx) {
   const text = (key) => interpolate(String(target[key]), ctx.vars);
   const exact = target.exact === true;
   const q = (s) => `'${ctx.redactor.text(s).replace(/'/g, "\\'")}'`;
   const exactSuffix = exact ? ", { exact: true }" : "";
   if ("testid" in target)
-    return { locator: page.getByTestId(text("testid")), description: `getByTestId(${q(text("testid"))})` };
+    return { locator: root.getByTestId(text("testid")), description: `getByTestId(${q(text("testid"))})`, strategy: "testid" };
   if ("role" in target) {
     const name = text("name");
     return {
-      locator: page.getByRole(target.role, { name, exact }),
-      description: `getByRole('${String(target.role)}', { name: ${q(name)}${exact ? ", exact: true" : ""} })`
+      locator: root.getByRole(target.role, { name, exact }),
+      description: `getByRole('${String(target.role)}', { name: ${q(name)}${exact ? ", exact: true" : ""} })`,
+      strategy: "role"
     };
   }
   if ("label" in target)
-    return { locator: page.getByLabel(text("label"), { exact }), description: `getByLabel(${q(text("label"))}${exactSuffix})` };
+    return { locator: root.getByLabel(text("label"), { exact }), description: `getByLabel(${q(text("label"))}${exactSuffix})`, strategy: "label" };
   if ("placeholder" in target) {
-    return { locator: page.getByPlaceholder(text("placeholder"), { exact }), description: `getByPlaceholder(${q(text("placeholder"))}${exactSuffix})` };
+    return { locator: root.getByPlaceholder(text("placeholder"), { exact }), description: `getByPlaceholder(${q(text("placeholder"))}${exactSuffix})`, strategy: "placeholder" };
   }
   if ("text" in target)
-    return { locator: page.getByText(text("text"), { exact }), description: `getByText(${q(text("text"))}${exactSuffix})` };
+    return { locator: root.getByText(text("text"), { exact }), description: `getByText(${q(text("text"))}${exactSuffix})`, strategy: "text" };
   if ("css" in target)
-    return { locator: page.locator(text("css")), description: `locator(${q(text("css"))})` };
+    return { locator: root.locator(text("css")), description: `locator(${q(text("css"))})`, strategy: "css" };
   throw new StepFailure("blocked", "invalid_target", "target has no supported locator form");
 }
+async function visibleLogicalTables(root, kind) {
+  const selector = kind === "element-plus" ? ".el-table:visible" : "table:visible";
+  const tables = rootLocator(root, selector);
+  return Array.from({ length: await tables.count() }, (_, i) => tables.nth(i));
+}
+async function chooseTable(root, target, ctx) {
+  const kind = target.table_kind === "element-plus" ? "element-plus" : "html";
+  let tables = await visibleLogicalTables(root, kind);
+  const ref = target.table ?? { only: true };
+  if (ref.testid !== undefined) {
+    const candidate = root.getByTestId(interpolate(String(ref.testid), ctx.vars));
+    const count = await candidate.count();
+    if (count === 0)
+      throw new StepFailure("failed", "table_not_found", `no table matches testid '${ref.testid}'`, { locator_strategy: "table_column", locator_details: { table: "testid", match_count: 0 } });
+    if (count > 1)
+      throw new StepFailure("failed", "table_ambiguous", `multiple tables match testid '${ref.testid}'`, { locator_strategy: "table_column", locator_details: { table: "testid", match_count: count } });
+    const candidateTag = await candidate.evaluate((el) => el.tagName.toLowerCase());
+    if (kind === "html" && candidateTag === "table")
+      return { table: candidate, index: 0, kind };
+    const table = candidate.locator(kind === "element-plus" ? ".el-table__header-wrapper" : "table").first();
+    if (await table.count() === 0)
+      throw new StepFailure("blocked", "table_adapter_mismatch", "table testid does not contain the expected table structure");
+    return { table: candidate, index: 0, kind };
+  }
+  if (ref.near_heading !== undefined) {
+    const heading = interpolate(String(ref.near_heading), ctx.vars);
+    const headings = root.getByRole("heading", { name: heading, exact: true });
+    if (await headings.count() === 0)
+      throw new StepFailure("failed", "table_not_found", `no visible heading '${heading}' identifies a table`, { locator_strategy: "table_column", locator_details: { near_heading: heading } });
+    if (await headings.count() > 1)
+      throw new StepFailure("failed", "table_ambiguous", `multiple headings '${heading}' identify tables`, { locator_strategy: "table_column", locator_details: { near_heading: heading, heading_matches: await headings.count() } });
+    const headingHandle = await headings.elementHandle();
+    const index = await rootLocator(root, kind === "element-plus" ? ".el-table:visible" : "table:visible").evaluateAll((els, h) => {
+      if (!h)
+        return -1;
+      const after = els.map((el, i) => ({ el, i })).filter(({ el }) => Boolean(h.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING));
+      return after.length ? after[0].i : -1;
+    }, headingHandle);
+    await headingHandle?.dispose();
+    if (index < 0)
+      throw new StepFailure("failed", "table_not_found", `no visible table follows heading '${heading}'`, { locator_strategy: "table_column", locator_details: { near_heading: heading } });
+    return { table: tables[index], index, kind };
+  }
+  if (tables.length === 0)
+    throw new StepFailure("failed", "table_not_found", "no visible table found", { locator_strategy: "table_column", locator_details: { table: "only", match_count: 0 } });
+  if (tables.length > 1)
+    throw new StepFailure("failed", "table_ambiguous", `expected one visible table, found ${tables.length}`, { locator_strategy: "table_column", locator_details: { table: "only", match_count: tables.length } });
+  return { table: tables[0], index: 0, kind };
+}
+async function tableLocator(root, target, ctx) {
+  const selected = await chooseTable(root, target, ctx);
+  const column = target.column ?? target.row?.column;
+  if (typeof column !== "string")
+    throw new StepFailure("blocked", "invalid_target", "table target requires a column");
+  const headingText = interpolate(column, ctx.vars);
+  let cells;
+  let bodyRows;
+  if (selected.kind === "element-plus") {
+    const headerWrappers = selected.table.locator(":scope > .el-table__header-wrapper, :scope > .el-table__inner-wrapper > .el-table__header-wrapper");
+    const bodyWrappers = selected.table.locator(":scope > .el-table__body-wrapper, :scope > .el-table__inner-wrapper > .el-table__body-wrapper");
+    if (await headerWrappers.count() !== 1 || await bodyWrappers.count() !== 1) {
+      throw new StepFailure("blocked", "table_adapter_mismatch", "Element Plus table must have exactly one header and body wrapper", { locator_strategy: "table_column", locator_details: { table_kind: selected.kind } });
+    }
+    const headers = headerWrappers.locator("th:visible");
+    const matches = [];
+    for (let i = 0;i < await headers.count(); i++) {
+      if (normalized(await headers.nth(i).innerText()) === normalized(headingText))
+        matches.push(i);
+    }
+    if (matches.length === 0)
+      throw new StepFailure("failed", "column_header_not_found", `no visible table header equals '${headingText}'`, { locator_strategy: "table_column", locator_details: { column: headingText, header_matches: 0 } });
+    if (matches.length > 1)
+      throw new StepFailure("failed", "column_header_ambiguous", `multiple visible table headers equal '${headingText}'`, { locator_strategy: "table_column", locator_details: { column: headingText, header_matches: matches.length } });
+    const th = headers.nth(matches[0]);
+    const classes = (await th.getAttribute("class") ?? "").split(/\s+/).filter((name) => /^el-table_\d+_column_\d+$/.test(name));
+    if (classes.length !== 1)
+      throw new StepFailure("blocked", "table_adapter_mismatch", `header '${headingText}' does not have one Element Plus column class`);
+    const className = classes[0];
+    cells = bodyWrappers.locator(`td.${className}:visible`);
+    bodyRows = bodyWrappers.locator("tbody tr:visible");
+  } else {
+    const headers = selected.table.locator("thead th:visible");
+    if (await headers.count() === 0)
+      throw new StepFailure("blocked", "table_adapter_mismatch", "HTML table has no visible thead headers");
+    let columnIndex = -1;
+    let offset = 0;
+    for (let i = 0;i < await headers.count(); i++) {
+      const th = headers.nth(i);
+      const span = Number(await th.getAttribute("colspan") ?? "1");
+      if (normalized(await th.innerText()) === normalized(headingText)) {
+        if (columnIndex >= 0)
+          throw new StepFailure("failed", "column_header_ambiguous", `multiple table headers equal '${headingText}'`);
+        columnIndex = offset;
+      }
+      offset += Number.isFinite(span) && span > 0 ? span : 1;
+    }
+    if (columnIndex < 0)
+      throw new StepFailure("failed", "column_header_not_found", `no table header equals '${headingText}'`, { locator_strategy: "table_column", locator_details: { column: headingText, header_matches: 0 } });
+    bodyRows = selected.table.locator("tbody tr:visible");
+    cells = selected.table.locator(`tbody tr:visible > td:visible:nth-child(${columnIndex + 1})`);
+  }
+  const rowSpec = target.row;
+  if (rowSpec) {
+    const matchingRows = [];
+    for (let i = 0;i < await bodyRows.count(); i++) {
+      const row2 = bodyRows.nth(i);
+      const cell = selected.kind === "element-plus" ? row2.locator(`td.${(await cells.first().getAttribute("class") ?? "").split(/\s+/).find((x) => /^el-table_\d+_column_\d+$/.test(x)) ?? "__missing__"}`).first() : row2.locator("td:visible").nth(await cells.first().evaluate((el) => Array.from(el.parentElement?.children ?? []).indexOf(el)));
+      const value = normalized(await cell.innerText().catch(() => ""));
+      const expected = normalized(interpolate(String(rowSpec.equals ?? rowSpec.contains), ctx.vars));
+      if (rowSpec.equals !== undefined ? value === expected : value.includes(expected))
+        matchingRows.push(i);
+    }
+    if (matchingRows.length === 0)
+      throw new StepFailure("failed", "row_not_found", `no row has ${rowSpec.equals !== undefined ? "value" : "text"} '${rowSpec.equals ?? rowSpec.contains}'`, { locator_strategy: "row", locator_details: { row_matches: 0, column: rowSpec.column } });
+    if (matchingRows.length > 1)
+      throw new StepFailure("failed", "row_ambiguous", `multiple rows match '${rowSpec.equals ?? rowSpec.contains}'`, { locator_strategy: "row", locator_details: { row_matches: matchingRows.length, column: rowSpec.column } });
+    const row = bodyRows.nth(matchingRows[0]);
+    if (target.role || target.testid || target.label || target.placeholder || target.text || target.css) {
+      const inner = baseLocator(row, target, ctx);
+      return { ...inner, strategy: "row", details: { row_matches: 1, column: rowSpec.column } };
+    }
+    cells = selected.kind === "element-plus" ? row.locator(`td.${(await cells.first().getAttribute("class") ?? "").split(/\s+/).find((x) => /^el-table_\d+_column_\d+$/.test(x)) ?? "__missing__"}`).first() : row.locator("td:visible").nth(await cells.first().evaluate((el) => Array.from(el.parentElement?.children ?? []).indexOf(el)));
+  }
+  const quoted = `'${ctx.redactor.text(headingText).replace(/'/g, "\\'")}'`;
+  return { locator: cells, description: `table column ${quoted}`, strategy: "table_column", details: { table_kind: selected.kind, column: headingText, table_index: selected.index, data_dependent: Boolean(rowSpec) } };
+}
+var STRUCTURED_RETRY_CODES = new Set([
+  "element_not_found",
+  "strict_locator_violation",
+  "table_not_found",
+  "table_ambiguous",
+  "column_header_not_found",
+  "column_header_ambiguous",
+  "row_not_found",
+  "row_ambiguous",
+  "table_adapter_mismatch"
+]);
+async function buildLocator(page, target, ctx, deadline = Date.now() + DEFAULT_UI_TIMEOUT_MS) {
+  if (!target.within && !target.table)
+    return buildLocatorOnce(page, target, ctx, deadline);
+  for (;; ) {
+    try {
+      return await buildLocatorOnce(page, target, ctx, deadline);
+    } catch (error) {
+      const retryable = error instanceof StepFailure && STRUCTURED_RETRY_CODES.has(error.code);
+      if (!retryable || Date.now() >= deadline)
+        throw error;
+      await sleep(POLL_MS);
+    }
+  }
+}
+async function buildLocatorOnce(page, target, ctx, deadline) {
+  if (target.within) {
+    const scope = await buildLocator(page, target.within, ctx, deadline);
+    const count = await scope.locator.count();
+    if (count !== 1)
+      throw new StepFailure("failed", count === 0 ? "element_not_found" : "strict_locator_violation", `within target must match exactly one element`, { locator: scope.description, match_count: count });
+    const inner = target.table ? await tableLocator(scope.locator, target, ctx) : baseLocator(scope.locator, target, ctx);
+    return { ...inner, strategy: "within", details: { within: scope.description, ...inner.details ?? {} } };
+  }
+  if (target.table)
+    return tableLocator(page, target, ctx);
+  return baseLocator(page, target, ctx);
+}
 async function resolveStrict(locator, description, deadline) {
   let count = 0;
   for (;; ) {
@@ -784,9 +1012,11 @@ async function executeUi(step, ctx) {
   const details = {};
   let locator = null;
   if (step.target) {
-    const built = buildLocator(page, step.target, ctx);
+    const built = await buildLocator(page, step.target, ctx, deadline);
     locator = built.locator;
     details.locator = built.description;
+    details.locator_strategy = built.strategy;
+    details.locator_details = built.details;
   }
   const withDetails = (err) => {
     if (err instanceof StepFailure)
@@ -877,6 +1107,58 @@ async function executeUi(step, ctx) {
         details.assertion = { match, expected: ctx.redactor.text(expectedRaw), actual: ctx.redactor.text(actualRaw) };
         break;
       }
+      case "assert_each_text": {
+        const minCount = Number(step.min_count ?? 1);
+        const normalizeWhitespace = step.normalize_whitespace !== false;
+        const caseSensitive = step.case_sensitive !== false;
+        const match = String(step.match);
+        const expectedRaw = interpolate(String(step.expected), ctx.vars);
+        const expected = normalizeText(expectedRaw, normalizeWhitespace, caseSensitive);
+        let count = 0;
+        let actualRaw = "";
+        for (;; ) {
+          count = await locator.count();
+          if (count >= minCount) {
+            const texts = await locator.allInnerTexts();
+            const firstBad = texts.find((value) => !textMatches(normalizeText(value, normalizeWhitespace, caseSensitive), expected, match));
+            if (!firstBad) {
+              details.match_count = count;
+              actualRaw = texts[0] ?? "";
+              break;
+            }
+            actualRaw = firstBad;
+          }
+          if (Date.now() >= deadline) {
+            details.match_count = count;
+            details.assertion = { match, expected: ctx.redactor.text(expectedRaw), actual: ctx.redactor.text(actualRaw) };
+            throw new StepFailure("failed", "assertion_failed", `each text ${match} assertion failed`);
+          }
+          await sleep(POLL_MS);
+        }
+        details.assertion = { match, expected: ctx.redactor.text(expectedRaw), actual: ctx.redactor.text(actualRaw) };
+        break;
+      }
+      case "assert_value": {
+        details.match_count = await resolveStrict(locator, details.locator, deadline);
+        const normalizeWhitespace = step.normalize_whitespace !== false;
+        const caseSensitive = step.case_sensitive !== false;
+        const match = String(step.match);
+        const expectedRaw = interpolate(String(step.expected), ctx.vars);
+        const expected = normalizeText(expectedRaw, normalizeWhitespace, caseSensitive);
+        let actualRaw = "";
+        for (;; ) {
+          actualRaw = await locator.inputValue({ timeout: Math.max(remaining(deadline), 1000) });
+          if (textMatches(normalizeText(actualRaw, normalizeWhitespace, caseSensitive), expected, match))
+            break;
+          if (Date.now() >= deadline) {
+            details.assertion = { match, expected: ctx.redactor.text(expectedRaw), actual: ctx.redactor.text(actualRaw) };
+            throw new StepFailure("failed", "assertion_failed", `value ${match} assertion failed`);
+          }
+          await sleep(POLL_MS);
+        }
+        details.assertion = { match, expected: ctx.redactor.text(expectedRaw), actual: ctx.redactor.text(actualRaw) };
+        break;
+      }
       case "assert_url": {
         const match = String(step.match);
         const raw = interpolate(String(step.expected), ctx.vars);

package/plugins/devflow-quality/runtime/playwright/runtime-manifest.json

@@ -3,9 +3,10 @@
   "runtime_version": "0.1.0",
   "playwright_version": "1.63.0",
   "files": {
-    "runner.spec.mjs": "5612cde9ddef5a203829d86ab45788d65cbe83891ff7dbb73c308aa9345ead83",
+    "runner.spec.mjs": "abf0c5c9aff43b4f233de4c44db0946001c970758ef63ab861fad1d125c1a6fc",
     "playwright.config.mjs": "301c0b97e229f83e6934994718b11b93a1da5d46ec606cfd11a8292e9d622b02",
     "reporter.mjs": "5c91d68c50a93603f583cf82345d427bcd9ce9a7cfb78fd6d0989abddbd55275",
-    "devflow-test-dsl-v1.schema.json": "21ce608adcaf60ac138b532b7731f3b74c3e2749cba26dfeb12fc12ce0b6e5f3"
+    "explore-host.mjs": "0973ff6be3b4a3cdd332b90cc6c09ebe96b4ea98bc1e1273be6c09b9bf79efd9",
+    "devflow-test-dsl-v1.schema.json": "df07e55507697a70df214ae820403b530b04aeb04a12d0aa85715bf5e528e194"
   }
 }

package/plugins/devflow-quality/skills/workflow-acceptance-test-design/SKILL.md

@@ -48,11 +48,15 @@ description: "Use after integration verification and before change planning to d
   "preconditions": ["身份、数据和环境前置条件"],
   "steps": ["测试操作"],
   "oracle": "可观察的预期结果",
+  "oracle_source": "requirement|contract|invariant|characterization",
+  "oracle_evidence": "非 requirement 来源的约定、不变量说明或观察记录",
   "automation_mode": "automated|manual|blocked",
   "evidence_strategy": "replay|causal|observation"
 }
 ```
 
+`oracle_source` 是冻结 TC 的判定标准来源。功能开发工作流缺省为 `requirement`；回归验收工作流必须显式填写。`contract`、`invariant`、`characterization` 必须同时填写 `oracle_evidence`，且回归用例可以省略 `acceptance_refs`。`characterization` 只证明行为未变化，不证明行为正确；不得把依赖环境数据的具体值写成判定标准。
+
 - `execution_surface` 必须显式填写：单个 Core HTTP 请求且断言来自 `execution` 用 `http`；真实页面交互用 `ui`；受限 DSL 中的多步骤 API 或 UI/API 组合用 `api_flow`；项目自有测试命令、权限、边界、韧性、迁移和性能专项用 `project_test`。`page` 必须对应 `ui`，带 `execution.protocol: http` 的 Core API TC 必须对应 `http`；新冻结 TC 缺失或冲突会被 CP-3 拒绝。
 - `automated` 的 `ui` / `api_flow` TC 在 `run-acceptance-tests` 绑定阶段必须有 v1 DSL（`workflow-generate-mainflow-cases` 生成，`covers` 逐条映射 `preconditions[i]`、`steps[i]` 和 `oracle`）并经用户批准 `execution_plan`，否则只会 blocked。因此每个前置条件和步骤要写成可单独映射的原子条目，oracle 要写成确定性的可观察结果（具体文案、URL、响应字段）；需要纯视觉判断、缺少稳定 locator 或无法准备/隔离数据的场景，现在就标 `manual` 或 `blocked`，不要标 `automated`。
 - `manual` 额外写 `manual_reason` 和 `owner`；`blocked` 额外写 `blocked_by` 和 `owner`。

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/SKILL.md

@@ -9,23 +9,31 @@ description: "Use after code review, as the binding-phase prerequisite of run-ac
 
 ## Hard Rules
 
+- `devflow_explore` 只能辅助回归设计或本步骤的 DSL 绑定；它产生的视图、断言和 draft 都不是验收证据。只能消费经人工检查的草稿，仍须运行本技能的编译、目录校验、独立审查和 `execution_plan` 审批流程。
+- 探索草稿中的 secret 变量只能保持 `${KEY}` 引用，禁止读取、回填或输出凭据值；页面中的个人信息也不能被当作通用 oracle。
+
 - MUST NOT hardcode `platform-backend` or `platform-frontend`.
 - MUST derive code roots from `.devflow/planning/navigation` and `.devflow/context/spec`.
 - MUST use `.devflow/planning/code-index/` for fine-grained entrypoint, route, component, API, call, import, and data-flow evidence when present.
 - MUST read the frozen `.devflow/planning/requirements/{feature}/tests.json` before selecting scope. Only frozen, `confirmed`, `automation_mode: automated` TCs whose `execution_surface` is `ui` or `api_flow` get a DSL (legacy `page` TCs derive to `ui`). `http` TCs (including Core-generated API TCs with `execution.expect.error_code`) and `project_test` TCs are executed by their own adapters, not here.
 - MUST NOT read `SUMMARY.md`, delivery self-reports, or diffs to decide what to test. Current code is allowed only to bind an already frozen TC to an entrypoint, `data-testid`/locator, request path, or test data; it must never change the TC's steps or oracle.
 - MUST NOT hand-write or hand-edit `TC-xxxx.json`. Write `case-descriptions.json` and run `compile_dsl.py`; the compiler owns `tc_sha256`, target/driver generation, and hard rejections (`ai_only`, Midscene, xpath, scripts, token injection, fixed waits).
+- MUST resolve `anchor:<page-key>/<anchor-name>` locators from `.devflow/planning/test-locators/<page-key>.json` during compilation. Missing anchors and cycles block generation; generated steps retain `source_anchor` for the internal locator-stability report. Runtime never reads mapping files.
+- MUST prefer an existing `data-testid`, then mapping anchor, then role/name, label/placeholder, structured table/within/row target, text, and finally restricted CSS. Never require a frontend change to make generation pass.
 - MUST run `compile_dsl.py`, then `validate_case_payloads.py` on the whole `generated-cases/{feature}` directory, before reporting success. Block if either exits non-zero.
 - MUST block if codebase discovery fails.
 - MUST get an independent AI review of every DSL against its TC oracle (advisory) before proposing approvals. The reviewer must not be the agent that wrote the descriptions.
 - MUST propose one `execution_plan` approval per automated TC with `devflow_approval`; only the user can approve it, in `/devflow` → “待审批”. The agent cannot confirm, must not write approval records, and must not treat an unapproved DSL as accepted.
+- MUST inspect `.devflow/planning/features/{feature}/locator-stability.md` after compilation; it is an internal record of locator strategy, risk, reason, and optional frontend improvements.
 - MUST NOT create `case-import-payloads.json`. That name belongs only to the explicit legacy TestAgent export and is never a Runtime DSL artifact (see Legacy export).
 
 ## Workflow Position
 
-This skill is not a workflow step and must not appear in `pending_steps` or participate in main-chain ordering. It runs inside the binding phase of `run-acceptance-tests`:
+功能开发工作流中，本技能的前置条件是代码审查已完成；回归验收工作流中，它只在 `regression-dsl` 步骤运行。本技能不得把功能开发的代码审查加入回归主链：
+
+`feature-development: execute -> code-review -> [human acceptance] -> generate DSL -> bind + user approves execution plans -> run-acceptance-tests`
 
-`execute -> code-review -> [human acceptance] -> generate DSL (this skill) -> bind + user approves execution plans -> run-acceptance-tests -> release closeout`
+`regression-acceptance: regression-test-design -> regression-dsl (this skill) -> bind + user approves execution plans -> run-acceptance-tests`
 
 Before running, verify that the current feature's `code-review` is completed and the frozen TC suite is fresh (`devflow_acceptance_tests(feature)`). A generation, validation, or approval failure means the affected TCs cannot run as `devflow_playwright`; report it and either fix it or downgrade the TC (`manual` with a `mode_override` approval, or `blocked` with owner/reason). It never mutates workflow state itself.
 

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/references/intermediate-format.md

@@ -1,6 +1,8 @@
 # Case Descriptions Format (`case-descriptions.json`)
 
-`case-descriptions.json` 是 AI 写给 `scripts/compile_dsl.py` 的输入，编译产物是每个冻结 TC 一个 `devflow-test-dsl/v1` 文件 `.devflow/planning/generated-cases/{feature}/TC-xxxx.json`（形状见 `project-dsl-contract.md`）。**不要手写 DSL**：locator 写成 `"type:value"` 字符串，其余键与 DSL 同名，编译器负责生成 `target`、`driver`、`tc_sha256`、步骤默认 ID 并校验。
+`case-descriptions.json` 是 AI 写给 `scripts/compile_dsl.py` 的输入，编译产物是每个冻结 TC 一个 `devflow-test-dsl/v1` 文件 `.devflow/planning/generated-cases/{feature}/TC-xxxx.json`（形状见 `project-dsl-contract.md`）。**不要手写 DSL**：普通 locator 写成 `"type:value"` 字符串；稳定定位映射可写成 `"anchor:<page-key>/<anchor-name>"`，表格、区域和行目标可直接写结构化 locator 对象。编译器负责生成 `target`、`driver`、`tc_sha256`、步骤默认 ID 并校验。
+
+映射文件放在 `.devflow/planning/test-locators/<page-key>.json`。锚点引用会在编译时严格展开，循环、缺失锚点、非法目标都会拒绝；生成步骤保留 `source_anchor` 供内部报告追溯。映射修改后必须重新编译并重新审批 DSL。
 
 本文件描述的是 `compile_dsl.py` 实际接受的格式；出现任何不在此列的键都会被拒绝（不会静默丢弃）。
 
@@ -85,6 +87,8 @@
 | `select` | `locator`、`value`（字符串或字符串数组，多选） | `exact` |
 | `wait_for` | `locator` | `state`（`visible`\|`hidden`\|`attached`\|`detached`，缺省 `visible`）、`exact` |
 | `assert_text` | `locator`、`expected` | `match`（`exact`\|`contains`，缺省 `exact`）、`normalize_whitespace`、`case_sensitive`、`exact` |
+| `assert_each_text` | `locator`、`expected` | `match`、`min_count`（最小 1）、`normalize_whitespace`、`case_sensitive`、`exact` |
+| `assert_value` | `locator`、`expected` | `match`、`normalize_whitespace`、`case_sensitive`、`exact`；expected 可为空 |
 | `assert_url` | `expected` | `match`（`exact`\|`contains`，缺省 `contains`） |
 | `screenshot` | — | `full_page` |
 
@@ -100,7 +104,7 @@
 | `headers`、`query`、`json` | 请求头、查询参数（标量）、JSON 请求体；字符串叶子可用 `${var}` |
 | `expect_status` | 期望 HTTP 状态码 |
 | `assertions` | `[ { "pointer": "/data/status", "op": "equals", "value": "created" } ]`；`op` 为 `equals`/`not_equals`/`contains`/`exists`/`not_exists`（后两者不带 `value`）；`pointer` 是 JSON Pointer |
-| `extract` | `{ "order_id": "/data/id" }` 或 `{ "token": { "pointer": "/t", "sensitive": true } }`；只支持 JSON Pointer |
+| `extract` | `{ "order_id": "/data/id" }` 或 `{ "token": { "pointer": "/t", "sensitive": true } }`；也支持 `{ "jwt": { "header": "x-jwt-token" } }`，header 默认敏感且大小写不敏感 |
 | `retry`、`idempotent` | `retry: { "max_attempts": 2-5, "on": ["connection_error"\|"timeout"\|"rate_limited"] }`；POST/PATCH 重试必须 `idempotent: true`；默认不重试 |
 
 API 步骤通过页面同一个 BrowserContext 发送，与 UI 登录态共享 cookie。`HEAD`/`OPTIONS` 不支持。响应体断言只能用 `assertions` 里的 JSON Pointer，不能用 JSONPath、`status_code`/`json_path_exists` 之类旧断言类型。

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

@@ -53,6 +53,8 @@ DSL 是纯数据，由 Devflow Playwright Runtime 解释执行，Core 用同一
 | `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_each_text` | 多元素 `target`，每个元素都满足 `match`/`expected`；可选 `min_count`（缺省 1） |
+| `assert_value` | 唯一 input/textarea/select 的当前值；`expected` 可为空字符串 |
 | `assert_url` | `match`、`expected` |
 | `screenshot` | 可选 `name`（`[A-Za-z0-9_-]{1,64}`）、`full_page` |
 
@@ -87,7 +89,7 @@ DSL 是纯数据，由 Devflow Playwright Runtime 解释执行，Core 用同一
 - `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}`，不得重定义已存在变量；
+- `extract`：`{ name: { pointer, sensitive? } }` 或 `{ name: { header, sensitive? } }`，二选一；header 名大小写不敏感且缺失失败，header 默认 `sensitive: true`，之后的步骤可用 `${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}"`。

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

@@ -22,7 +22,7 @@ UI 用例把冻结的、自动化的 `execution_surface: ui` TC（含存量推
 
 ## Step Rules
 
-- 只用 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`。
+- 只用 v1 UI 动作：`goto`、`click`、`fill`、`select`、`check`、`uncheck`、`wait_for`、`assert_visible`、`assert_text`、`assert_each_text`、`assert_value`、`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}` 命名，避免多次运行互相污染。
@@ -30,7 +30,9 @@ UI 用例把冻结的、自动化的 `execution_surface: ui` TC（含存量推
 
 ## Locator 决策
 
-顺序：`testid` → `role` → `label` / `placeholder` → `text` → `css`（最后手段）。
+顺序：已有 `testid` → 映射锚点 → `role` → `label` / `placeholder` → `table`+`column` / `within` / `row` → `text` → `css`（最后手段）。
+
+映射锚点写为 `anchor:<page-key>/<anchor-name>`，由编译器展开为完整目标；运行时不读取映射文件。表格、区域和行目标可直接写结构化 locator，例如 `{ "table": { "near_heading": "店铺列表" }, "column": "店铺名称", "table_kind": "element-plus" }`。`row` 是数据依赖定位，`within` 和表格列都必须满足严格唯一性。
 
 1. 源码里有 `data-testid` 就用 `testid:`。没有而该元素是主流程的关键控件时，在 `source-map.md` 里记录“缺少 testid”，并建议开发者补上，不要靠猜。
 2. 有明确 ARIA 角色和可访问名称：`role:button:确定`。