@guanlin4924/devflow-pi 0.1.97 → 0.1.98

package/README.md

@@ -11,7 +11,7 @@ Devflow Pi 是一个面向项目研发交付的独立 OMP 产品入口，内置
 安装与启动：
 
 ```bash
-npm install -g @guanlin4924/devflow-pi@0.1.97
+npm install -g @guanlin4924/devflow-pi@0.1.98
 cd /path/to/your-project
 devflow-pi init
 devflow-pi doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -612,6 +612,13 @@ export type ExploreHostRequest = {
   params?: Record<string, unknown>;
 };
 
+class ExploreHostError extends Error {
+  constructor(message: string, readonly code?: string) {
+    super(message);
+    this.name = "ExploreHostError";
+  }
+}
+
 /** Small JSON-lines client. The host owns Playwright; Core owns its lifetime. */
 export class ExploreHostManager {
   private child: any;
@@ -621,8 +628,10 @@ export class ExploreHostManager {
   private idleTimer?: ReturnType<typeof setTimeout>;
   private totalTimer?: ReturnType<typeof setTimeout>;
   private lastActivity = 0;
+  private exploreSecrets: Record<string, string> = {};
 
   get running(): boolean { return Boolean(this.child); }
+  get secrets(): Record<string, string> { return { ...this.exploreSecrets }; }
 
   async start(hostPath: string, cwd: string, environmentFile: string, secrets: Record<string, string>): Promise<void> {
     if (this.child) throw new Error("an explore session is already active");
@@ -635,6 +644,7 @@ export class ExploreHostManager {
     env.DEVFLOW_EXPLORE_ENVIRONMENT_FILE = environmentFile;
     for (const [name, value] of Object.entries(secrets)) env[name] = value;
     this.child = Bun.spawn(["node", hostPath], { cwd, env, stdin: "pipe", stdout: "pipe", stderr: "pipe", detached: true });
+    this.exploreSecrets = { ...secrets };
     void new Response(this.child.stderr).text();
     this.lastActivity = Date.now();
     this.readerTask = this.readResponses(this.child.stdout);
@@ -662,6 +672,7 @@ export class ExploreHostManager {
     const child = this.child;
     if (!child) return;
     this.child = undefined;
+    this.exploreSecrets = {};
     if (this.idleTimer) clearTimeout(this.idleTimer);
     if (this.totalTimer) clearTimeout(this.totalTimer);
     for (const pending of this.pending.values()) pending.reject(new Error(reason));
@@ -706,7 +717,10 @@ export class ExploreHostManager {
           if (!waiter) continue;
           this.pending.delete(response.id);
           if (response.ok === true) waiter.resolve(response.result);
-          else waiter.reject(new Error(String(response?.error?.message ?? "explore-host request failed")));
+          else waiter.reject(new ExploreHostError(
+            String(response?.error?.message ?? "explore-host request failed"),
+            typeof response?.error?.code === "string" ? response.error.code : undefined,
+          ));
         }
       }
     } finally {
@@ -1795,6 +1809,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactExploreValue(item, secrets)]));
     return value;
   };
+  const exploreScopePattern = /^(?:e\d+|aria-ref=e\d+|role=[^:\s]+(?::.+)?|testid=.+)$/;
 
   const exploreHostPath = (): string => {
     const candidates = [
@@ -4293,6 +4308,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     label: "Devflow Explore",
     description: [
       "在已批准的 environment_profile 内启动结构化页面探索会话；探索结果不是验收结论，draft 仍必须经过编译、校验和用户批准。",
+      "草稿到执行唯一经过：人工检查 review_items → regression-test-design 冻结 TC 并生成 tests.json → regression-dsl 使用 compile_dsl.py <草稿或 case-descriptions 路径>（无 --draft）编译、校验并提交 execution_plan 批准 → run-acceptance-tests 执行；草稿不能直接执行，也不能用内置浏览器重放代替验收执行。冻结 TC 若需激活合同，请通过 /devflow control → 启动当前可执行步骤进入。DSL 的 screenshot 只供用户在本地查看。",
       "凭据只按 profile.secret_env 注入 explore-host 子进程，永不写入 process.env、日志或工具输出。页面文本可能包含个人信息，本工具不做页面级个人信息脱敏。",
     ].join(" "),
     parameters: z.object({
@@ -4300,7 +4316,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       feature: z.string().min(1).optional(),
       environment_profile: z.string().min(1).optional(),
       url: z.string().min(1).optional(),
-      scope: z.string().optional(),
+      scope: z.string().regex(exploreScopePattern, "scope must be a ref, role selector, or testid selector").optional(),
       full: z.boolean().optional(),
       table_text: z.boolean().optional(),
       ref: z.string().min(1).optional(),
@@ -4316,14 +4332,15 @@ export default function devflowCore(pi: ExtensionAPI) {
     }),
     approval: args => args.action === "observe" || args.action === "stop" ? "read" : "write",
     async execute(_id, params, _signal, _onUpdate, ctx) {
+      const currentSecrets = () => exploreHost.secrets;
       const fail = (message: string, code = "invalid_request") => ({
-        content: [{ type: "text" as const, text: message }],
+        content: [{ type: "text" as const, text: String(redactExploreValue(message, currentSecrets())) }],
         details: { code },
         isError: true,
       });
-      const response = (result: unknown, secrets: Record<string, string> = {}) => ({
-        content: [{ type: "text" as const, text: JSON.stringify(redactExploreValue(result, secrets), null, 2) }],
-        details: redactExploreValue(result, secrets),
+      const response = (result: unknown) => ({
+        content: [{ type: "text" as const, text: JSON.stringify(redactExploreValue(result, currentSecrets()), null, 2) }],
+        details: redactExploreValue(result, currentSecrets()),
       });
       try {
         if (activeContract && !["regression-test-design", "regression-dsl", "generate-mainflow-cases"].includes(activeContract.step)) {
@@ -4357,16 +4374,15 @@ export default function devflowCore(pi: ExtensionAPI) {
           const result = await exploreHost.request("start", {
             feature: params.feature, environment_profile: params.environment_profile, url: params.url,
           });
-          return response(result, childSecrets);
+          return response(result);
         }
         if (!exploreHost.running) return fail("no active explore session", "session_missing");
         const requestParams: Record<string, unknown> = {};
         if (params.action === "observe") Object.assign(requestParams, { scope: params.scope, full: params.full, table_text: params.table_text });
         else if (params.action === "act") {
-          const operation = params.operation ?? params.action_name;
-          if (!params.ref || !operation) return fail("act requires ref and operation");
-          if (!["click", "fill", "check", "uncheck", "select", "press"].includes(operation)) return fail("act operation is invalid");
-          Object.assign(requestParams, { ref: params.ref, action: operation, value: params.value, value_from_secret: params.value_from_secret });
+          if (!params.ref || !params.operation) return fail("act requires ref and operation");
+          if (!["click", "fill", "check", "uncheck", "select", "press"].includes(params.operation)) return fail("act operation is invalid");
+          Object.assign(requestParams, { ref: params.ref, action: params.operation, value: params.value, value_from_secret: params.value_from_secret });
         } else if (params.action === "assert") {
           if (!params.ref || !params.kind || !["text", "visible", "value", "each_text"].includes(params.kind)) return fail("assert requires ref and a supported kind");
           Object.assign(requestParams, { ref: params.ref, kind: params.kind, match: params.match, expected: params.expected });
@@ -4376,7 +4392,10 @@ export default function devflowCore(pi: ExtensionAPI) {
         }
         return response(await exploreHost.request(params.action, requestParams));
       } catch (error) {
-        return fail(error instanceof Error ? error.message : String(error), "explore_failed");
+        if (params.action === "start") await exploreHost.stop("explore start failed");
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof ExploreHostError && error.code ? error.code : "explore_failed";
+        return fail(`[${code}] ${message}`, code);
       }
     },
   });

package/plugins/devflow-quality/runtime/playwright/explore-host.mjs

@@ -226,6 +226,7 @@ class Redactor {
 
 // plugins/devflow-quality/runtime/playwright/src/explore/view.ts
 var INTERACTIVE = new Set(["button", "link", "textbox", "searchbox", "checkbox", "radio", "combobox", "listbox", "option", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "switch", "slider", "spinbutton", "treeitem"]);
+var NAMEABLE = new Set(["dialog", "alertdialog", "region", "form", "navigation", ...INTERACTIVE]);
 var INFO = new Set(["heading", "alert", "status", "dialog", "alertdialog"]);
 var CONTEXT = new Set(["dialog", "alertdialog", "form", "navigation", "banner", "main", "region", "table", "row", "tabpanel", "menu"]);
 var TEXT_CONTAINERS = new Set(["dialog", "alertdialog", "alert", "status"]);
@@ -393,6 +394,37 @@ async function nameRows(page, nodes) {
     }
   }
 }
+async function nameContainers(page, nodes) {
+  for (const node of nodes.filter((item) => item.ref && !item.name && NAMEABLE.has(item.role))) {
+    const element = page.locator(`aria-ref=${node.ref}`);
+    if (await element.count() !== 1)
+      continue;
+    const name = await element.evaluate((item) => {
+      const ariaLabel = item.getAttribute("aria-label")?.trim();
+      if (ariaLabel)
+        return ariaLabel.replace(/\s+/g, " ").trim();
+      const ids = item.getAttribute("aria-labelledby")?.trim().split(/\s+/).filter(Boolean) ?? [];
+      return ids.map((id) => document.getElementById(id)?.textContent ?? "").join(" ").replace(/\s+/g, " ").trim();
+    });
+    if (!name)
+      continue;
+    const roleLocator = page.getByRole(node.role, { name, exact: true });
+    if (await sameUniqueElement(roleLocator, element))
+      node.name = name;
+  }
+}
+async function sameUniqueElement(candidate, element) {
+  if (await candidate.count() !== 1)
+    return false;
+  const candidateHandle = await candidate.elementHandle();
+  if (!candidateHandle)
+    return false;
+  try {
+    return await element.evaluate((node, other) => node === other, candidateHandle);
+  } finally {
+    await candidateHandle.dispose();
+  }
+}
 
 class ExplorerView {
   page;
@@ -410,22 +442,35 @@ class ExplorerView {
   node(ref) {
     return this.last?.get(ref);
   }
-  async observe(options = {}) {
+  async observe(options = {}, settled = true) {
     let scope = this.page.locator("body");
     if (options.scope) {
       const rawScope = options.scope;
-      if (/^aria-ref=e\d+$/.test(rawScope) || /^e\d+$/.test(rawScope))
-        scope = this.page.locator(rawScope.startsWith("aria-ref=") ? rawScope : `aria-ref=${rawScope}`);
-      else if (rawScope.startsWith("role="))
-        scope = this.page.getByRole(rawScope.slice(5));
-      else if (rawScope.startsWith("testid="))
+      const ref = /^(?:aria-ref=)?(e\d+)$/.exec(rawScope);
+      if (ref) {
+        if (!this.hasRef(ref[1]))
+          throw Object.assign(new Error(`unknown or stale ref ${ref[1]}`), { code: "stale_ref" });
+        scope = this.page.locator(`aria-ref=${ref[1]}`);
+      } else if (rawScope.startsWith("role=")) {
+        const value = rawScope.slice(5);
+        const [role, ...nameParts] = value.split(":");
+        if (!/^[-a-z]+$/.test(role) || nameParts.length && !nameParts.join(":").length)
+          throw Object.assign(new Error("scope must be eN, aria-ref=eN, role=<role>[:<name>], or testid=<id>"), { code: "invalid_params" });
+        scope = nameParts.length ? this.page.getByRole(role, { name: nameParts.join(":"), exact: true }) : this.page.getByRole(role);
+      } else if (rawScope.startsWith("testid=") && rawScope.slice(7))
         scope = this.page.getByTestId(rawScope.slice(7));
       else
-        scope = this.page.locator(rawScope);
+        throw Object.assign(new Error("scope must be eN, aria-ref=eN, role=<role>[:<name>], or testid=<id>"), { code: "invalid_params" });
+      const scopeCount = await scope.count();
+      if (scopeCount === 0)
+        throw Object.assign(new Error("scope does not match exactly one element"), { code: "scope_not_found" });
+      if (scopeCount > 1)
+        throw Object.assign(new Error("scope matches more than one element"), { code: "scope_ambiguous" });
     }
     const raw = await scope.ariaSnapshot({ mode: "ai" });
     const nodes = parseSnapshot(raw);
     await nameRows(this.page, nodes);
+    await nameContainers(this.page, nodes);
     const view = prune(nodes, this.redactor, await passwordRefs(this.page, nodes));
     const fullText = [...view.values()].map((node) => `  ${format(node, this.redactor)}`).join(`
 `);
@@ -451,7 +496,7 @@ class ExplorerView {
 ${await this.tableText(scope)}`;
     const text = `[page] ${this.redactor.url(url)} · ${this.redactor.text(await this.page.title())} [${mode}]
 ${body}`;
-    return { mode, text, stats: { raw: raw.length, pruned: fullText.length, sent: body.length } };
+    return { mode, text, settled, stats: { raw: raw.length, pruned: fullText.length, sent: body.length } };
   }
   async tableText(scope) {
     const rows = scope.locator("table tbody tr:visible, .el-table__body-wrapper tbody tr:visible");
@@ -490,6 +535,18 @@ function inferredRole(tag, type) {
     return;
   return { checkbox: "checkbox", radio: "radio", range: "slider" }[type ?? ""] ?? "textbox";
 }
+async function sameUnique(candidate, element) {
+  if (await candidate.count() !== 1)
+    return false;
+  const candidateHandle = await candidate.elementHandle();
+  if (!candidateHandle)
+    return false;
+  try {
+    return await element.evaluate((node, other) => node === other, candidateHandle);
+  } finally {
+    await candidateHandle.dispose();
+  }
+}
 
 class Recorder {
   page;
@@ -508,11 +565,29 @@ class Recorder {
     this.feature = feature;
     this.environmentProfile = environmentProfile;
     this.startUrl = startUrl;
-    this.steps.push({ action: "goto", url: new URL(startUrl).pathname });
+    const initial = new URL(startUrl);
+    this.steps.push({ action: "goto", url: `${initial.pathname}${initial.search}${initial.hash}` });
   }
   async unique(locator) {
     return await locator.count() === 1;
   }
+  async rowTarget(element, role, name) {
+    const row = element.locator("xpath=ancestor::tr[1]");
+    if (await row.count() !== 1)
+      return null;
+    const cells = row.locator(":scope > td:visible, :scope > th:visible");
+    for (let i = 0;i < await cells.count(); i++) {
+      const markerText = (await cells.nth(i).innerText()).replace(/\s+/g, " ").trim();
+      if (markerText.length < 2)
+        continue;
+      const rows = this.page.getByRole("row", { name: markerText, exact: false });
+      const inner = rows.getByRole(role, { name, exact: true });
+      if (await rows.count() === 1 && await sameUnique(inner, element)) {
+        return { locator: { within: { role: "row", name: markerText, exact: false }, role, name, exact: true }, data_dependent: true, reviewReasons: ["data_dependent_locator"] };
+      }
+    }
+    return null;
+  }
   async contextTarget(node, role, name) {
     const context = node.ctx.split(" > ").filter((item) => /^(dialog|alertdialog|form|navigation|banner|main|region)\b/.test(item)).pop();
     if (!context)
@@ -525,60 +600,10 @@ class Recorder {
     const within = contextName ? { role: contextRole, name: contextName, exact: true } : { role: contextRole };
     const root = contextName ? this.page.getByRole(contextRole, { name: contextName, exact: true }) : this.page.getByRole(contextRole);
     const inner = root.getByRole(role, { name, exact: true });
-    if (await this.unique(root) && await this.unique(inner))
+    if (await this.unique(root) && await sameUnique(inner, this.page.locator(`aria-ref=${node.ref}`)))
       return { locator: { within, role, name, exact: true } };
     return null;
   }
-  async elementPlusTarget(element, role, name) {
-    const row = element.locator("xpath=ancestor::tr[1]");
-    if (await row.count() !== 1)
-      return null;
-    const root = row.locator("xpath=ancestor::*[contains(concat(' ', normalize-space(@class), ' '), ' el-table ')][1]");
-    if (await root.count() !== 1)
-      return null;
-    const headers = root.locator(".el-table__header-wrapper th:visible");
-    const headerByClass = new Map;
-    for (let i = 0;i < await headers.count(); i++) {
-      const header = headers.nth(i);
-      const title = (await header.innerText()).replace(/\s+/g, " ").trim();
-      for (const className of (await header.getAttribute("class") ?? "").split(/\s+/)) {
-        if (/^el-table_\d+_column_\d+$/.test(className) && title)
-          headerByClass.set(className, title);
-      }
-    }
-    const cells = row.locator(":scope > td:visible");
-    let actionColumn = "";
-    let markerColumn = "";
-    let markerText = "";
-    for (let i = 0;i < await cells.count(); i++) {
-      const cell = cells.nth(i);
-      const text = (await cell.innerText()).replace(/\s+/g, " ").trim();
-      const className = (await cell.getAttribute("class") ?? "").split(/\s+/).find((item) => headerByClass.has(item));
-      const column = className ? headerByClass.get(className) ?? "" : "";
-      if (text && !markerText) {
-        markerText = text;
-        markerColumn = column;
-      }
-      if (column && await cell.getByRole(role, { name, exact: true }).count() > 0)
-        actionColumn = column;
-    }
-    if (!actionColumn || !markerColumn || !markerText)
-      return null;
-    const target = {
-      within: {
-        role: "row",
-        name: markerText,
-        exact: false
-      },
-      role,
-      name,
-      exact: true
-    };
-    const matchingRows = root.locator(".el-table__body-wrapper tbody tr:visible").filter({ hasText: markerText });
-    if (await matchingRows.count() !== 1 || !await this.unique(matchingRows.getByRole(role, { name, exact: true })))
-      return null;
-    return { locator: target, data_dependent: true };
-  }
   async targetFor(ref) {
     if (!this.view.hasRef(ref))
       throw Object.assign(new Error(`unknown or stale ref ${ref}`), { code: "stale_ref" });
@@ -589,27 +614,29 @@ class Recorder {
     if (await element.count() !== 1)
       throw Object.assign(new Error(`ref ${ref} is not unique`), { code: "stale_ref" });
     const testid = await element.getAttribute("data-testid");
-    if (testid && await this.unique(this.page.getByTestId(testid)))
+    if (testid && await sameUnique(this.page.getByTestId(testid), element))
       return { locator: `testid:${testid}` };
     const tag = await element.evaluate((item) => item.tagName.toLowerCase());
     const role = node.role || inferredRole(tag, await element.getAttribute("type"));
     const name = node.name;
     if (role && name) {
       const roleLocator = this.page.getByRole(role, { name, exact: true });
-      if (await this.unique(roleLocator))
-        return { locator: `role:${role}:${name}` };
+      const rowTarget = await this.rowTarget(element, role, name);
+      if (rowTarget)
+        return rowTarget;
+      if (await sameUnique(roleLocator, element)) {
+        const inRow2 = await element.locator("xpath=ancestor::tr[1]").count() === 1;
+        return { locator: `role:${role}:${name}`, ...inRow2 ? { data_dependent: true, reviewReasons: ["row_scope_missing"] } : {} };
+      }
       const within = await this.contextTarget(node, role, name);
       if (within)
         return within;
-      const tableTarget = await this.elementPlusTarget(element, role, name);
-      if (tableTarget)
-        return tableTarget;
     }
     const ariaLabel = await element.getAttribute("aria-label");
-    if (ariaLabel && await this.unique(this.page.getByLabel(ariaLabel, { exact: true })))
+    if (ariaLabel && await sameUnique(this.page.getByLabel(ariaLabel, { exact: true }), element))
       return { locator: `label:${ariaLabel}` };
     const placeholder = await element.getAttribute("placeholder");
-    if (placeholder && await this.unique(this.page.getByPlaceholder(placeholder, { exact: true })))
+    if (placeholder && await sameUnique(this.page.getByPlaceholder(placeholder, { exact: true }), element))
       return { locator: `placeholder:${placeholder}` };
     const candidates = [];
     if (testid)
@@ -618,19 +645,28 @@ class Recorder {
       candidates.push(`role:${role}:${name}`);
     if (placeholder)
       candidates.push(`placeholder:${placeholder}`);
-    return { needs_locator: true, candidates: candidates.map((candidate) => this.redactor.value(candidate)) };
+    const inRow = await element.locator("xpath=ancestor::tr[1]").count() === 1;
+    return { needs_locator: true, candidates: candidates.map((candidate) => this.redactor.value(candidate)), ...inRow ? { data_dependent: true, reviewReasons: ["row_scope_missing"] } : {} };
   }
   recordPrepared(id, action, target, extra = {}) {
     const step = { action, ...extra, locator: target.locator ?? "" };
     this.steps.push(step);
     this.explorationSteps.push({
       id,
+      action,
+      role: typeof target.locator === "object" && target.locator ? target.locator.role : undefined,
       ...target.needs_locator ? { needs_locator: true } : {},
       ...target.candidates ? { candidates: target.candidates } : {},
       ...target.data_dependent ? { data_dependent: true } : {},
+      ...target.reviewReasons ? { reviewReasons: target.reviewReasons } : {},
       ...action.startsWith("assert_") ? { oracle_hint: "characterization" } : {}
     });
   }
+  recordAssertionReview(id, kind, expectedFromPage, circular, targetName, weak = false) {
+    const item = this.explorationSteps.find((step) => step.id === id);
+    if (item)
+      Object.assign(item, { ...expectedFromPage ? { expected_from_page: true } : {}, ...circular ? { circular: true } : {}, ...weak ? { reviewReasons: [...item.reviewReasons ?? [], "weak_assertion"] } : {} });
+  }
   noteSecretVariable(name) {
     this.secretVariables.add(name);
   }
@@ -640,16 +676,40 @@ class Recorder {
     await fs.mkdir(root, { recursive: true, mode: 448 });
     const steps = this.steps.map((step, index) => ({ id: `s${String(index + 1).padStart(2, "0")}`, ...step }));
     const metadata = this.explorationSteps.map((item, index) => ({ ...item, id: `s${String(index + 2).padStart(2, "0")}` }));
-    const manual = metadata.filter((item) => item.needs_locator).map((item) => item.id);
+    const review_items = [];
+    const reviewKeys = new Set;
+    const addReview = (item) => {
+      const key = `${item.step}\x00${item.reason}`;
+      if (!reviewKeys.has(key)) {
+        reviewKeys.add(key);
+        review_items.push(item);
+      }
+    };
+    for (const item of metadata) {
+      for (const reason of item.reviewReasons ?? [])
+        addReview({ step: item.id, reason });
+      if (item.needs_locator)
+        addReview({ step: item.id, reason: "needs_locator" });
+      if (item.expected_from_page)
+        addReview({ step: item.id, reason: "expected_from_page" });
+      if (item.circular)
+        addReview({ step: item.id, reason: "circular_assertion" });
+      if (item.action === "assert_visible" && ["button", "link"].includes(item.role ?? ""))
+        addReview({ step: item.id, reason: "weak_assertion" });
+    }
+    const business = metadata.some((item) => item.action?.startsWith("assert_") && item.action !== "assert_visible" && !item.circular);
+    if (!business)
+      addReview({ step: "case", reason: "no_business_assertion" });
+    const manual = [...new Set(review_items.filter((item) => item.reason !== "expected_from_page" && item.reason !== "data_dependent_locator").map((item) => item.step))];
     const draft = {
       cases: [{ tc_id: tcId ?? "TC-0000", name: name.replace(/\.json$/, ""), variables: Object.fromEntries([...this.secretVariables].map((key) => [key, { secret: key }])), data: { setup: [], cleanup: [] }, steps }],
-      exploration: { environment_profile: this.environmentProfile, start_url: this.redactor.url(this.startUrl), recorded_steps: steps.length, needs_manual: manual, steps: metadata }
+      exploration: { environment_profile: this.environmentProfile, start_url: this.redactor.url(this.startUrl), recorded_steps: steps.length, needs_manual: manual, review_items, steps: metadata }
     };
     const output = path.join(root, fileName);
     const serialized = this.redactor.text(JSON.stringify(draft, null, 2));
     await fs.writeFile(output, `${serialized}
 `, { mode: 384 });
-    return { path: output, manual };
+    return { path: output, manual, review_items };
   }
 }
 
@@ -660,8 +720,35 @@ var page = null;
 var view = null;
 var recorder = null;
 var redactor = null;
+var profileMemory = null;
 var idleTimer = null;
 var totalTimer = null;
+var inFlightRequests = 0;
+var requestStarted = null;
+var requestFinished = null;
+function installRequestCounter(currentContext) {
+  inFlightRequests = 0;
+  requestStarted = (request) => {
+    if (["fetch", "xhr", "document"].includes(request.resourceType()))
+      inFlightRequests++;
+  };
+  requestFinished = () => {
+    inFlightRequests = Math.max(0, inFlightRequests - 1);
+  };
+  currentContext.on("request", requestStarted);
+  currentContext.on("requestfinished", requestFinished);
+  currentContext.on("requestfailed", requestFinished);
+}
+function removeRequestCounter() {
+  if (context && requestStarted && requestFinished) {
+    context.off("request", requestStarted);
+    context.off("requestfinished", requestFinished);
+    context.off("requestfailed", requestFinished);
+  }
+  requestStarted = null;
+  requestFinished = null;
+  inFlightRequests = 0;
+}
 function reply(id, result) {
   process.stdout.write(`${JSON.stringify({ id, ok: true, result })}
 `);
@@ -680,12 +767,14 @@ async function shutdown() {
     clearTimeout(totalTimer);
   idleTimer = null;
   totalTimer = null;
+  removeRequestCounter();
   await browser?.close().catch(() => {});
   browser = null;
   context = null;
   page = null;
   view = null;
   recorder = null;
+  profileMemory = null;
 }
 function touch() {
   if (idleTimer)
@@ -708,6 +797,33 @@ function secretValue(key, profile) {
     throw Object.assign(new Error(`secret ${String(key)} is unavailable`), { code: "secret_unavailable" });
   return value;
 }
+async function settle(currentPage) {
+  const deadline = Date.now() + 8000;
+  await currentPage.waitForLoadState("domcontentloaded").catch(() => {});
+  if (!context)
+    return true;
+  let quietSince = 0;
+  let previousSnapshot = null;
+  while (Date.now() < deadline) {
+    if (inFlightRequests === 0) {
+      if (!quietSince)
+        quietSince = Date.now();
+      if (Date.now() - quietSince >= 500) {
+        const snapshot = await currentPage.ariaSnapshot({ mode: "ai" }).catch(() => "");
+        if (previousSnapshot !== null && snapshot === previousSnapshot)
+          return true;
+        previousSnapshot = snapshot;
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        continue;
+      }
+    } else {
+      quietSince = 0;
+      previousSnapshot = null;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return false;
+}
 async function doStart(request) {
   if (page)
     throw Object.assign(new Error("only one explore session is allowed"), { code: "session_exists" });
@@ -715,24 +831,32 @@ async function doStart(request) {
   if (!environmentFile || !path2.isAbsolute(environmentFile)) {
     throw Object.assign(new Error("environment profile path is missing"), { code: "environment_profile_invalid" });
   }
-  const profile = JSON.parse(fs2.readFileSync(environmentFile, "utf8"));
-  const policy = buildPolicy(profile);
-  redactor = new Redactor;
-  for (const envName of Object.values(profile.secret_env ?? {})) {
-    const value = process.env[envName];
-    if (value)
-      redactor.add(value);
-  }
-  browser = await chromium.launch();
-  context = await browser.newContext();
-  await new NetworkRecorder(redactor).install(context, policy);
-  page = await context.newPage();
-  const startUrl = absoluteUrl(String(request.params?.url ?? "/"), profile);
-  await page.goto(startUrl, { waitUntil: "domcontentloaded" });
-  view = new ExplorerView(page, redactor);
-  recorder = new Recorder(page, view, redactor, String(request.params?.feature ?? "explore"), profile.profile ?? path2.basename(environmentFile, path2.extname(environmentFile)), startUrl);
-  totalTimer = setTimeout(() => void shutdown(), 60 * 60 * 1000);
-  reply(request.id, await view.observe({ full: true }));
+  try {
+    const profile = JSON.parse(fs2.readFileSync(environmentFile, "utf8"));
+    profileMemory = profile;
+    const policy = buildPolicy(profile);
+    redactor = new Redactor;
+    for (const envName of Object.values(profile.secret_env ?? {})) {
+      const value = process.env[envName];
+      if (value)
+        redactor.add(value);
+    }
+    browser = await chromium.launch();
+    context = await browser.newContext();
+    installRequestCounter(context);
+    await new NetworkRecorder(redactor).install(context, policy);
+    page = await context.newPage();
+    const startUrl = absoluteUrl(String(request.params?.url ?? "/"), profile);
+    await page.goto(startUrl, { waitUntil: "domcontentloaded" });
+    const settled = await settle(page);
+    view = new ExplorerView(page, redactor);
+    recorder = new Recorder(page, view, redactor, String(request.params?.feature ?? "explore"), profile.profile ?? path2.basename(environmentFile, path2.extname(environmentFile)), startUrl);
+    totalTimer = setTimeout(() => void shutdown(), 60 * 60 * 1000);
+    reply(request.id, await view.observe({ full: true }, settled));
+  } catch (error) {
+    await shutdown();
+    throw error;
+  }
 }
 async function doAct(request) {
   const current = session();
@@ -745,10 +869,10 @@ async function doAct(request) {
   let value = request.params?.value;
   let secretKey;
   if (request.params?.value_from_secret !== undefined) {
-    const environmentFile = process.env.DEVFLOW_EXPLORE_ENVIRONMENT_FILE;
-    const profile = JSON.parse(fs2.readFileSync(environmentFile, "utf8"));
     secretKey = request.params.value_from_secret;
-    value = secretValue(secretKey, profile);
+    if (!profileMemory)
+      throw Object.assign(new Error("explore profile is unavailable"), { code: "environment_profile_invalid" });
+    value = secretValue(secretKey, profileMemory);
     current.redactor.add(value);
     current.recorder.noteSecretVariable(String(secretKey));
   }
@@ -775,14 +899,14 @@ async function doAct(request) {
     default:
       throw Object.assign(new Error(`unknown action ${action}`), { code: "invalid_params" });
   }
-  await current.page.waitForLoadState("domcontentloaded").catch(() => {});
+  const settled = await settle(current.page);
   const id = `s${String(current.recorder.steps.length + 1).padStart(2, "0")}`;
   const extra = {};
   if (action === "fill" || action === "select" || action === "press") {
     extra.value = secretKey === undefined ? current.redactor.text(String(value ?? "")) : `\${${String(secretKey)}}`;
   }
   current.recorder.recordPrepared(id, action, prepared, extra);
-  reply(request.id, await current.view.observe());
+  reply(request.id, { ...await current.view.observe({}, settled), settled });
 }
 async function doAssert(request) {
   const current = session();
@@ -832,7 +956,16 @@ async function doAssert(request) {
     extra.case_sensitive = caseSensitive;
   }
   current.recorder.recordPrepared(`s${String(current.recorder.steps.length + 1).padStart(2, "0")}`, action, prepared, extra);
-  reply(request.id, { actual: current.redactor.value(kind === "each_text" ? await locator.allInnerTexts() : expected), view: await current.view.observe() });
+  const settled = await settle(current.page);
+  const targetName = current.view.node(ref)?.name ?? "";
+  const normalize = (value) => value.replace(/\s+/g, " ").trim();
+  const normalizedExpected = expected === undefined ? "" : normalize(expected);
+  const normalizedName = normalize(targetName);
+  const withinName = typeof prepared.locator === "object" && prepared.locator !== null ? String(prepared.locator.within?.name ?? "") : "";
+  const normalizedWithinName = normalize(withinName);
+  const circular = kind !== "visible" && Boolean(normalizedExpected && (normalizedName && (normalizedExpected.includes(normalizedName) || normalizedName.includes(normalizedExpected)) || normalizedWithinName && (normalizedExpected.includes(normalizedWithinName) || normalizedWithinName.includes(normalizedExpected))));
+  current.recorder.recordAssertionReview(`s${String(current.recorder.steps.length).padStart(2, "0")}`, kind, requested === undefined, circular, targetName, kind === "visible" && ["button", "link"].includes(current.view.node(ref)?.role ?? ""));
+  reply(request.id, { actual: current.redactor.value(kind === "each_text" ? await locator.allInnerTexts() : expected), view: await current.view.observe({}, settled), settled });
 }
 async function handle(request) {
   touch();
@@ -863,9 +996,12 @@ async function handle(request) {
   }
 }
 var input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+var requestQueue = Promise.resolve();
 input.on("line", (line) => {
   try {
-    handle(JSON.parse(line));
+    const request = JSON.parse(line);
+    requestQueue = requestQueue.then(() => handle(request)).catch((error) => process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`));
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}
 `);

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

@@ -6,7 +6,7 @@
     "runner.spec.mjs": "abf0c5c9aff43b4f233de4c44db0946001c970758ef63ab861fad1d125c1a6fc",
     "playwright.config.mjs": "301c0b97e229f83e6934994718b11b93a1da5d46ec606cfd11a8292e9d622b02",
     "reporter.mjs": "5c91d68c50a93603f583cf82345d427bcd9ce9a7cfb78fd6d0989abddbd55275",
-    "explore-host.mjs": "0973ff6be3b4a3cdd332b90cc6c09ebe96b4ea98bc1e1273be6c09b9bf79efd9",
+    "explore-host.mjs": "035ea37f40cef7399e7038537f3f03d42baffe9d2db32d9bf8add25b0d81118e",
     "devflow-test-dsl-v1.schema.json": "df07e55507697a70df214ae820403b530b04aeb04a12d0aa85715bf5e528e194"
   }
 }

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

@@ -10,6 +10,8 @@ description: "Use after code review, as the binding-phase prerequisite of run-ac
 ## Hard Rules
 
 - `devflow_explore` 只能辅助回归设计或本步骤的 DSL 绑定；它产生的视图、断言和 draft 都不是验收证据。只能消费经人工检查的草稿，仍须运行本技能的编译、目录校验、独立审查和 `execution_plan` 审批流程。
+- 草稿到执行只有一条路径：①人工检查草稿并处理 `review_items`；②回归流程先由 `regression-test-design` 冻结 TC（生成 `tests.json`，将草稿 `tc_id` 替换为冻结编号）；③本 `regression-dsl` 步骤运行 `compile_dsl.py <草稿或 case-descriptions 路径>`（没有 `--draft` 参数），通过校验后提交 `execution_plan` 批准；④由 `run-acceptance-tests` 执行。草稿不能直接执行，也不能用内置浏览器重放代替验收执行。冻结 TC 若提示需要激活合同，应通过 `/devflow control` →“启动当前可执行步骤”进入。
+- DSL 的 `screenshot` 步骤可以留存截图，截图只供用户在本地查看。
 - 探索草稿中的 secret 变量只能保持 `${KEY}` 引用，禁止读取、回填或输出凭据值；页面中的个人信息也不能被当作通用 oracle。
 
 - MUST NOT hardcode `platform-backend` or `platform-frontend`.

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

@@ -15,6 +15,8 @@ description: "Use from an idle project to derive a user-confirmed, frozen regres
 
 需要补充当前页面行为时，可在已批准的测试环境中调用 `devflow_explore`（start/observe/act/assert/draft）。探索只用于发现和录制草稿，不是验收证据；密码、密钥和凭据值不得写入描述、日志或草稿。草稿必须由后续 `workflow-generate-mainflow-cases` 编译、校验并经用户批准后才能执行。
 
+草稿到执行的唯一合法路径是：①人工检查草稿并处理 `review_items`；②在回归流程的 `regression-test-design` 中冻结 TC（生成 `tests.json`，并将草稿中的 `tc_id` 替换为冻结后的编号）；③在 `regression-dsl` 步骤使用 `compile_dsl.py <草稿或 case-descriptions 路径>` 编译（没有 `--draft` 参数），通过校验后提交 `execution_plan` 批准；④由 `run-acceptance-tests` 执行。草稿不能直接执行，也不能用内置浏览器重放代替验收执行。冻结 TC 若提示需要激活合同，应通过 `/devflow control` →“启动当前可执行步骤”进入。
+
 1. 读取 `devflow_requirement_graph(action="inspect")` 和 `.devflow/planning/code-index/`，确认当前功能、代码索引 revision、入口、接口、数据流和调用关系。
 2. 阅读实际前端与后端源码、路由/控制器、服务、权限规则、数据访问和已有测试；代码只能用于发现真实功能点与可执行入口，不能把实现细节直接当作预期。
 3. 阅读 `.devflow/planning/test-environments/*.json` 中的环境声明；需要登录或测试 token 时，只记录 `secret_env` 的变量名和所需前置，不读取或输出值。
@@ -67,3 +69,4 @@ description: "Use from an idle project to derive a user-confirmed, frozen regres
 - 不读取或使用 agent 交付自述、`SUMMARY.md` 或 git diff 来决定测试范围。
 - 不写入 `acceptance-results.json`，不生成人工通过结果，不确认执行计划或环境批准。
 - 不向模型上下文、文档或日志输出测试凭据值。
+- DSL 的 `screenshot` 步骤可以留存截图，截图只供用户在本地查看。

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.97";
+export const PRODUCT_VERSION = "0.1.98";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";