@epoint-testtech/stage-create 0.0.3-alpha.1

package/templates/glue/src/gap-executor/runtime-runner.ts

@@ -0,0 +1,817 @@
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+import { chromium, type Browser, type Dialog, type Frame, type Locator, type Page, type Response } from '@playwright/test';
+import type { AgentInferredWorkflow, CrudBusinessModuleContract, GapExplorationResult, GapInferDraft } from '@epoint-testtech/ep-stage-skill';
+import { listGapWorkflows } from '@epoint-testtech/ep-stage-skill';
+import dotenv from 'dotenv';
+
+import { LoginPage } from '../skeletons/login.skeleton';
+import { MenuPage } from '../skeletons/menu.skeleton';
+import {
+  appendResolvedAgentWorkflowToSpec,
+  createResolvedWorkflowFromPlanned,
+} from './gap-executor';
+import {
+  collectRuntimePageStructureSignals,
+  type RuntimePageStructureSignal,
+} from './page-structure-observer.js';
+
+export type GapRuntimeRunnerInput = {
+  contractPath: string;
+  specPath: string;
+  projectDir: string;
+  menuRoute: string;
+  moduleId: string;
+  workflowIds: string[];
+  headless?: boolean;
+};
+
+export type GapRuntimeRunnerResult = {
+  resolvedWorkflows: string[];
+  skippedWorkflows: string[];
+  needsReviewWorkflows: string[];
+  needsReviewWorkflowReasons?: Array<{
+    workflowId: string;
+    reason: string;
+  }>;
+  specPath: string;
+  pageStructureSignals?: RuntimePageStructureSignal[];
+  runtimePageStructureStatus?: 'collected' | 'environment_unavailable';
+};
+
+type LocatorResolution = {
+  locator: string;
+  locatorStrategy: 'html_static' | 'agent_refined';
+};
+
+/**
+ * 读取 contract 中可进入 runtime resolve 的 planned workflows。
+ * @param contract CRUD 业务模块契约
+ * @param workflowIds 目标 workflowId 列表；为空时默认使用全部 planned workflows
+ * @returns 过滤后的 planned workflows
+ */
+export function pickPlannedWorkflows(
+  contract: CrudBusinessModuleContract,
+  workflowIds: string[],
+): AgentInferredWorkflow[] {
+  const allowed = new Set(workflowIds);
+  return (contract.agentInferredWorkflows ?? []).filter((workflow) => {
+    if (workflow.status !== 'planned') {
+      return false;
+    }
+    return allowed.size === 0 || allowed.has(workflow.workflowId);
+  });
+}
+
+/**
+ * 生成 runtime runner 结果结构，便于测试和 CLI 输出复用。
+ * @param input 运行结果输入
+ * @returns 原样返回的结果对象
+ */
+export function summarizeRuntimeRunnerResult(input: GapRuntimeRunnerResult): GapRuntimeRunnerResult {
+  return input;
+}
+
+async function waitUntilVisible(locator: Locator, timeout = 5_000): Promise<boolean> {
+  try {
+    await locator.first().waitFor({ state: 'visible', timeout });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function listSearchContexts(page: Page, iframeKeyword?: string): Array<Page | Frame> {
+  const contexts: Array<Page | Frame> = [page];
+  for (const frame of page.frames()) {
+    if (!iframeKeyword || frame.url().includes(iframeKeyword)) {
+      contexts.push(frame);
+    }
+  }
+  return contexts;
+}
+
+function formatRuntimeError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message.split('\n')[0] ?? error.message;
+  }
+  return String(error);
+}
+
+function fallbackLocatorByLabel(label: string): string {
+  return `xpath=//a[contains(@class,'mini-button')][normalize-space()='${label}']`;
+}
+
+async function resolveWorkflowLocator(
+  page: Page,
+  workflow: AgentInferredWorkflow,
+  iframeKeyword?: string,
+): Promise<LocatorResolution> {
+  const candidateLocator = workflow.actionCandidates[0]?.locator;
+  for (const context of listSearchContexts(page, iframeKeyword)) {
+    if (candidateLocator) {
+      const candidate = context.locator(candidateLocator);
+      if (await waitUntilVisible(candidate)) {
+        return {
+          locator: candidateLocator,
+          locatorStrategy: 'html_static',
+        };
+      }
+    }
+
+    const label = workflow.actionCandidates[0]?.label ?? workflow.workflowId;
+    const fallbackLocator = fallbackLocatorByLabel(label);
+    const fallback = context.locator(fallbackLocator);
+    if (await waitUntilVisible(fallback)) {
+      return {
+        locator: fallbackLocator,
+        locatorStrategy: 'agent_refined',
+      };
+    }
+  }
+
+  const label = workflow.actionCandidates[0]?.label ?? workflow.workflowId;
+  throw new Error(`workflow ${workflow.workflowId} 未能在真实页面定位到按钮「${label}」`);
+}
+
+async function openModule(page: Page, menuRoute: string): Promise<void> {
+  const loginPage = new LoginPage(page);
+  const menuPage = new MenuPage(page);
+  await loginPage.login();
+  await menuPage.navigateToMenu(menuRoute);
+}
+
+export type GapExploreInput = {
+  contractPath: string;
+  projectDir: string;
+  menuRoute: string;
+  moduleId: string;
+  workflowIds: string[];
+  headless?: boolean;
+  /** 是否进一步点击确认框的确认按钮。默认 false，先只探到确认框文案，避免触发真实业务副作用。 */
+  confirmExecute?: boolean;
+};
+
+/** 探索时定位到目标按钮所在的运行态上下文与 locator。 */
+type ExploreLocation = {
+  context: Page | Frame;
+  locator: string;
+  locatorStrategy: 'html_static' | 'agent_refined';
+};
+
+/** MiniUI 运行态浮层选择器集合，采用“或抓宽”策略覆盖确认框 / 提示框 / 业务弹窗 / 轻提示。 */
+const OVERLAY_SELECTORS = [
+  '.mini-messagebox',
+  '[class*="messagebox"]',
+  '[class*="msgbox"]',
+  '[class*="toast"]',
+  '[class*="tip-"]',
+  '.mini-window:visible',
+];
+
+/**
+ * 在 page 及候选 iframe 中定位 gap 按钮，返回命中的上下文与 locator。
+ * @param page Playwright 页面
+ * @param workflow 目标 gap workflow
+ * @param iframeKeyword 列表页 iframe 关键字
+ * @returns 命中的上下文与 locator；未命中返回 undefined
+ */
+async function locateWorkflowButton(
+  page: Page,
+  workflow: AgentInferredWorkflow,
+  iframeKeyword?: string,
+): Promise<ExploreLocation | undefined> {
+  const candidateLocator = workflow.actionCandidates[0]?.locator;
+  const label = workflow.actionCandidates[0]?.label ?? workflow.workflowId;
+  const fallbackLocator = fallbackLocatorByLabel(label);
+
+  for (const context of listSearchContexts(page, iframeKeyword)) {
+    if (candidateLocator) {
+      const candidate = context.locator(candidateLocator);
+      if (await waitUntilVisible(candidate)) {
+        return { context, locator: candidateLocator, locatorStrategy: 'html_static' };
+      }
+    }
+    const fallback = context.locator(fallbackLocator);
+    if (await waitUntilVisible(fallback)) {
+      return { context, locator: fallbackLocator, locatorStrategy: 'agent_refined' };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 广谱捕获各上下文中可见浮层的文本，用于识别确认框 / 提示框文案。
+ * @param page Playwright 页面
+ * @param iframeKeyword 列表页 iframe 关键字
+ * @returns 去重后的可见浮层文本数组
+ */
+async function captureOverlayTexts(page: Page, iframeKeyword?: string): Promise<string[]> {
+  const texts: string[] = [];
+  for (const context of listSearchContexts(page, iframeKeyword)) {
+    for (const selector of OVERLAY_SELECTORS) {
+      const locator = context.locator(selector);
+      const count = await locator.count().catch(() => 0);
+      for (let index = 0; index < count; index += 1) {
+        const element = locator.nth(index);
+        if (await element.isVisible().catch(() => false)) {
+          const text = (await element.innerText().catch(() => '')).trim();
+          if (text) {
+            texts.push(text);
+          }
+        }
+      }
+    }
+  }
+  return Array.from(new Set(texts));
+}
+
+/**
+ * 在指定上下文注入 MutationObserver，记录后续新增/变更节点的可见文本。
+ *
+ * 用于捕获“点确定后”可能瞬时出现又快速消失的 toast / 异常提示——
+ * 即使元素随后被移除，其文本已被记录到 window.__stageObservedTexts。
+ *
+ * @param context 运行态上下文（page 或 frame）
+ */
+async function installOverlayObserver(context: Page | Frame): Promise<void> {
+  await context
+    .evaluate(() => {
+      const w = window as unknown as { __stageObservedTexts?: string[]; __stageObserver?: MutationObserver };
+      w.__stageObservedTexts = [];
+      const seen = new Set<string>();
+      const record = (node: Node): void => {
+        if (!(node instanceof HTMLElement)) {
+          return;
+        }
+        const text = (node.innerText || '').trim();
+        if (text && !seen.has(text)) {
+          seen.add(text);
+          w.__stageObservedTexts!.push(text);
+        }
+      };
+      const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          mutation.addedNodes.forEach(record);
+          if (mutation.type === 'attributes') {
+            record(mutation.target);
+          }
+        }
+      });
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['style', 'class'],
+      });
+      w.__stageObserver = observer;
+    })
+    .catch(() => undefined);
+}
+
+/**
+ * 读取指定上下文中 MutationObserver 记录到的全部文本。
+ * @param context 运行态上下文（page 或 frame）
+ * @returns 观测到的文本数组
+ */
+async function collectObserverTexts(context: Page | Frame): Promise<string[]> {
+  return context
+    .evaluate(() => {
+      const w = window as unknown as { __stageObservedTexts?: string[] };
+      return w.__stageObservedTexts ?? [];
+    })
+    .catch(() => [] as string[]);
+}
+
+/**
+ * 在确认框出现时点击其确认按钮，触发真实业务执行。
+ * @param page Playwright 页面
+ * @param iframeKeyword 列表页 iframe 关键字
+ * @returns 是否成功点击了确认按钮
+ */
+async function clickConfirmButton(page: Page, iframeKeyword?: string): Promise<boolean> {
+  for (const context of listSearchContexts(page, iframeKeyword)) {
+    const confirmButton = context
+      .locator("xpath=//*[contains(@class,'mini-messagebox')]//a[normalize-space()='确定' or normalize-space()='确认']")
+      .first();
+    if (await confirmButton.isVisible().catch(() => false)) {
+      await confirmButton.click().catch(() => undefined);
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * 在真实页面探索单个 gap 按钮点击后的运行态行为，产出结构化探索事实。
+ *
+ * 探索只观测“真实发生了什么”，不生成正式断言；confirmExecute 为 false 时不点击确认框，
+ * 保证零业务副作用即可拿到“是否有确认框 + 确认框文案”这一关键事实。
+ *
+ * @param page Playwright 页面
+ * @param workflow 目标 gap workflow
+ * @param options 探索选项（iframe 关键字、是否执行确认）
+ * @returns 单个 workflow 的探索结果
+ */
+async function exploreWorkflow(
+  page: Page,
+  workflow: AgentInferredWorkflow,
+  options: { iframeKeyword?: string; confirmExecute: boolean },
+): Promise<GapExplorationResult> {
+  const label = workflow.actionCandidates[0]?.label ?? workflow.workflowId;
+  const result: GapExplorationResult = {
+    workflowId: workflow.workflowId,
+    buttonLabel: label,
+    locator: '',
+    locatorStrategy: 'html_static',
+    buttonVisible: false,
+    buttonClickable: false,
+    confirmDialogPresent: false,
+    confirmExecuted: false,
+    signalType: 'none',
+    pageChanged: false,
+    downloadTriggered: false,
+    networkResponses: [],
+    confidence: 'low',
+    exploredAt: new Date().toISOString(),
+  };
+
+  const location = await locateWorkflowButton(page, workflow, options.iframeKeyword);
+  if (!location) {
+    return { ...result, notes: `未能在真实页面定位按钮「${label}」` };
+  }
+  result.locator = location.locator;
+  result.locatorStrategy = location.locatorStrategy;
+  result.buttonVisible = true;
+
+  const target = location.context.locator(location.locator).first();
+  result.buttonClickable = await target.isEnabled().catch(() => false);
+
+  const dialogMessages: string[] = [];
+  const networkResponses: string[] = [];
+  let downloadTriggered = false;
+  const onDialog = (dialog: Dialog): void => {
+    dialogMessages.push(dialog.message());
+    dialog.dismiss().catch(() => undefined);
+  };
+  const onDownload = (): void => {
+    downloadTriggered = true;
+  };
+  const onResponse = (response: Response): void => {
+    const resourceType = response.request().resourceType();
+    if (!['xhr', 'fetch', 'document'].includes(resourceType) || networkResponses.length >= 20) {
+      return;
+    }
+    networkResponses.push(`${response.status()} ${response.url()}`);
+  };
+  page.on('dialog', onDialog);
+  page.on('download', onDownload);
+  page.on('response', onResponse);
+
+  const urlBefore = page.url();
+  const overlayBefore = await captureOverlayTexts(page, options.iframeKeyword);
+
+  try {
+    await target.click({ timeout: 5_000 });
+  } catch {
+    // 点击失败也保留已观测事实，交由人工判断。
+  }
+  await page.waitForTimeout(2_000);
+
+  const overlayAfterClick = await captureOverlayTexts(page, options.iframeKeyword);
+  const newOverlaysAfterClick = overlayAfterClick.filter((text) => !overlayBefore.includes(text));
+  if (newOverlaysAfterClick.length > 0) {
+    result.confirmDialogPresent = true;
+    result.confirmText = newOverlaysAfterClick.join(' | ');
+  }
+
+  // 点确定后可能出现瞬时 toast（尤其异常提示消失很快）。
+  // 因此在点确定前装好 observer，点确定后高频轮询，确保捕获“出现过即记录”的文本。
+  const postConfirmTexts = new Set<string>();
+  if (options.confirmExecute && result.confirmDialogPresent) {
+    const contexts = listSearchContexts(page, options.iframeKeyword);
+    for (const context of contexts) {
+      await installOverlayObserver(context);
+    }
+
+    result.confirmExecuted = await clickConfirmButton(page, options.iframeKeyword);
+
+    const deadline = Date.now() + 6_000;
+    while (Date.now() < deadline) {
+      for (const context of contexts) {
+        for (const text of await collectObserverTexts(context)) {
+          postConfirmTexts.add(text.trim());
+        }
+      }
+      for (const text of await captureOverlayTexts(page, options.iframeKeyword)) {
+        postConfirmTexts.add(text);
+      }
+      await page.waitForTimeout(150);
+    }
+  }
+
+  page.off('dialog', onDialog);
+  page.off('download', onDownload);
+  page.off('response', onResponse);
+
+  result.pageChanged = page.url() !== urlBefore;
+  result.downloadTriggered = downloadTriggered;
+  result.networkResponses = networkResponses;
+
+  // 点确定后的“新增信号文本” = 捕获到的全部文本 - 点击前已存在 - 确认框自身文案碎片。
+  const confirmFragments = new Set(newOverlaysAfterClick);
+  const finalSignalTexts = Array.from(postConfirmTexts).filter(
+    (text) => text && !overlayBefore.includes(text) && !confirmFragments.has(text),
+  );
+
+  if (downloadTriggered) {
+    result.signalType = 'download';
+  } else if (dialogMessages.length > 0) {
+    result.signalType = 'alert';
+    result.observedMessage = dialogMessages.join(' | ');
+  } else if (result.confirmExecuted && finalSignalTexts.length > 0) {
+    // 确认执行后出现的轻提示，归类为 toast（同步结果/异常提示的典型形态）。
+    result.signalType = 'toast';
+    result.observedMessage = finalSignalTexts.join(' | ');
+  } else if (result.confirmExecuted && finalSignalTexts.length === 0) {
+    // 确认执行后无任何新提示，确认框消失即视为静默完成。
+    result.signalType = 'none';
+  } else if (result.confirmDialogPresent) {
+    result.signalType = 'confirm';
+  } else if (result.pageChanged) {
+    result.signalType = 'page_change';
+  } else {
+    result.signalType = 'none';
+  }
+
+  result.suggestedIntent = workflow.businessIntent.status === 'resolved'
+    ? workflow.businessIntent.value
+    : `点击「${label}」并完成对应业务操作`;
+  result.suggestedAssertion = result.observedMessage ?? result.confirmText;
+  result.confidence = result.observedMessage ? 'medium' : result.confirmDialogPresent ? 'medium' : 'low';
+  result.notes = [
+    `dialogMessages=${JSON.stringify(dialogMessages)}`,
+    `newOverlaysAfterClick=${JSON.stringify(newOverlaysAfterClick)}`,
+    `postConfirmSignals=${JSON.stringify(finalSignalTexts)}`,
+    `networkResponses=${JSON.stringify(networkResponses)}`,
+  ].join('; ');
+
+  return result;
+}
+
+/**
+ * 探索模式入口：对 contract 中目标 gap 在真实页面逐个探索，落袋结构化探索结果。
+ *
+ * 与 resolve 不同，探索模式不要求 workflow 已具备 intent/assertion，candidate 也可进入；
+ * 探索结果写入 glue-report/exploration 供人工确认，不直接追加测试。
+ *
+ * @param input 探索输入（contract 路径、菜单、目标 workflowId 等）
+ * @returns 全部目标 workflow 的探索结果
+ */
+export async function runGapRuntimeExplore(input: GapExploreInput): Promise<GapExplorationResult[]> {
+  dotenv.config({ path: path.join(input.projectDir, '.env') });
+
+  process.env.STAGE_PROJECT_ROOT_DIR_PATH = input.projectDir;
+  process.env.STAGE_AUTH_FILE_PATH = path.join(input.projectDir, 'glue-report', 'stage-auth.json');
+
+  const contract = JSON.parse(fs.readFileSync(input.contractPath, 'utf8')) as CrudBusinessModuleContract;
+  const allowed = new Set(input.workflowIds);
+  const targets = (contract.agentInferredWorkflows ?? []).filter(
+    (workflow) => allowed.size === 0 || allowed.has(workflow.workflowId),
+  );
+  const iframeKeyword = contract.pages.list.iframeSrcKeyword;
+
+  const results: GapExplorationResult[] = [];
+  let browser: Browser | undefined;
+  try {
+    browser = await chromium.launch({ headless: input.headless ?? true, slowMo: 300 });
+    const page = await browser.newPage({ viewport: { width: 1800, height: 900 }, ignoreHTTPSErrors: true });
+    await openModule(page, input.menuRoute);
+
+    for (const workflow of targets) {
+      const explored = await exploreWorkflow(page, workflow, {
+        iframeKeyword,
+        confirmExecute: input.confirmExecute ?? false,
+      });
+      results.push(explored);
+    }
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+
+  const exploreDir = path.join(input.projectDir, 'glue-report', 'exploration');
+  fs.mkdirSync(exploreDir, { recursive: true });
+  const outputPath = path.join(exploreDir, `${input.moduleId}.exploration.json`);
+  fs.writeFileSync(outputPath, JSON.stringify(results, null, 2), 'utf8');
+
+  return results;
+}
+
+export type GapInferInput = {
+  contractPath: string;
+  projectDir: string;
+  menuRoute: string;
+  moduleId: string;
+  workflowIds: string[];
+  headless?: boolean;
+  /** 是否点击确认框执行业务以观测真实结果。引导模式需要验证真实反馈，默认 true。 */
+  confirmExecute?: boolean;
+};
+
+/** 运行态反馈是否“未实现”类的关键词。 */
+const FEATURE_INCOMPLETE_PATTERN = /未实现|暂未|未开发|未配置|敬请期待|联系管理员/;
+
+/**
+ * 对比人工预期与真机观测，判定引导推理草案的功能缺口结论。
+ * @param guidedAssertion 人工给定的断言预期
+ * @param exploration 真实页面观测结果
+ * @returns intentSatisfied 与建议的功能缺口结论
+ */
+function judgeInferDraft(
+  guidedAssertion: string,
+  exploration: GapExplorationResult,
+): Pick<GapInferDraft, 'intentSatisfied' | 'suggestedGapFinding'> {
+  const observed = exploration.observedMessage ?? exploration.confirmText ?? '';
+  const satisfied =
+    Boolean(guidedAssertion) &&
+    (observed.includes(guidedAssertion) ||
+      (exploration.signalType === 'toast' && (observed.includes('成功') || observed.includes('完成'))));
+
+  if (satisfied) {
+    return { intentSatisfied: true };
+  }
+
+  const incomplete = FEATURE_INCOMPLETE_PATTERN.test(observed);
+  return {
+    intentSatisfied: false,
+    suggestedGapFinding: {
+      kind: incomplete ? 'feature_incomplete' : 'behavior_mismatch',
+      summary: incomplete
+        ? `功能未实现：人工预期「${guidedAssertion}」，真机反馈未达成。`
+        : `行为与预期不符：人工预期「${guidedAssertion}」，真机反馈与预期不同。`,
+      observed: observed || undefined,
+    },
+  };
+}
+
+/**
+ * 引导模式入口：对 planned（人工已给业务意图）的 gap 在真实页面推理验证，产出待确认草案。
+ *
+ * 与 explore 不同，infer 要求 workflow 已具备人工业务意图/断言（planned），并对比
+ * 「人工预期 vs 真机观测」给出落袋建议；草案写入 glue-report/exploration 供人工确认，不直接落袋。
+ *
+ * @param input 引导推理输入
+ * @returns 全部 planned workflow 的引导推理草案
+ */
+export async function runGapRuntimeInfer(input: GapInferInput): Promise<GapInferDraft[]> {
+  dotenv.config({ path: path.join(input.projectDir, '.env') });
+
+  process.env.STAGE_PROJECT_ROOT_DIR_PATH = input.projectDir;
+  process.env.STAGE_AUTH_FILE_PATH = path.join(input.projectDir, 'glue-report', 'stage-auth.json');
+
+  const contract = JSON.parse(fs.readFileSync(input.contractPath, 'utf8')) as CrudBusinessModuleContract;
+  const targets = pickPlannedWorkflows(contract, input.workflowIds);
+  const iframeKeyword = contract.pages.list.iframeSrcKeyword;
+
+  const drafts: GapInferDraft[] = [];
+  let browser: Browser | undefined;
+  try {
+    browser = await chromium.launch({ headless: input.headless ?? true, slowMo: 300 });
+    const page = await browser.newPage({ viewport: { width: 1800, height: 900 }, ignoreHTTPSErrors: true });
+    await openModule(page, input.menuRoute);
+
+    for (const workflow of targets) {
+      const exploration = await exploreWorkflow(page, workflow, {
+        iframeKeyword,
+        confirmExecute: input.confirmExecute ?? true,
+      });
+      const guidedIntent = workflow.businessIntent.status === 'resolved' ? workflow.businessIntent.value ?? '' : '';
+      const guidedAssertion =
+        workflow.assertionExpectation.status === 'resolved' ? workflow.assertionExpectation.value ?? '' : '';
+      const judged = judgeInferDraft(guidedAssertion, exploration);
+      drafts.push({
+        workflowId: workflow.workflowId,
+        buttonLabel: exploration.buttonLabel,
+        guidedIntent,
+        guidedAssertion,
+        exploration,
+        intentSatisfied: judged.intentSatisfied,
+        suggestedGapFinding: judged.suggestedGapFinding,
+        confidence: exploration.confidence,
+      });
+    }
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+
+  const exploreDir = path.join(input.projectDir, 'glue-report', 'exploration');
+  fs.mkdirSync(exploreDir, { recursive: true });
+  const outputPath = path.join(exploreDir, `${input.moduleId}.infer.json`);
+  fs.writeFileSync(outputPath, JSON.stringify(drafts, null, 2), 'utf8');
+
+  return drafts;
+}
+
+/**
+ * 在真实页面中把 planned workflows 补齐为 resolved，并追加到目标 spec。
+ * @param input runtime runner 输入
+ * @returns resolved / skipped / needs_review 汇总结果
+ */
+export async function runGapRuntimeResolve(input: GapRuntimeRunnerInput): Promise<GapRuntimeRunnerResult> {
+  dotenv.config({ path: path.join(input.projectDir, '.env') });
+
+  process.env.STAGE_PROJECT_ROOT_DIR_PATH = input.projectDir;
+  process.env.STAGE_AUTH_FILE_PATH = path.join(input.projectDir, 'glue-report', 'stage-auth.json');
+
+  const contract = JSON.parse(fs.readFileSync(input.contractPath, 'utf8')) as CrudBusinessModuleContract;
+  const plannedWorkflows = pickPlannedWorkflows(contract, input.workflowIds);
+  let specSource = fs.readFileSync(input.specPath, 'utf8');
+  const listIframeKeyword = contract.pages.list.iframeSrcKeyword;
+
+  if (plannedWorkflows.length === 0) {
+    return summarizeRuntimeRunnerResult({
+      resolvedWorkflows: [],
+      skippedWorkflows: [],
+      needsReviewWorkflows: [],
+      needsReviewWorkflowReasons: [],
+      specPath: input.specPath,
+      pageStructureSignals: [],
+      runtimePageStructureStatus: 'environment_unavailable',
+    });
+  }
+
+  let browser: Browser | undefined;
+  const resolvedWorkflows: string[] = [];
+  const skippedWorkflows: string[] = [];
+  const needsReviewWorkflows: string[] = [];
+  const needsReviewWorkflowReasons: Array<{ workflowId: string; reason: string }> = [];
+  let pageStructureSignals: RuntimePageStructureSignal[] = [];
+  let runtimePageStructureStatus: 'collected' | 'environment_unavailable' = 'collected';
+
+  try {
+    browser = await chromium.launch({ headless: input.headless ?? true, slowMo: 500 });
+    const page = await browser.newPage({ viewport: { width: 1800, height: 900 }, ignoreHTTPSErrors: true });
+    await openModule(page, input.menuRoute);
+
+    // 打开模块页面后采集 MiniUI 核心结构运行时可见性；采集失败标记环境不可用，不阻断 workflow 推理。
+    try {
+      pageStructureSignals = await collectRuntimePageStructureSignals(page, listIframeKeyword);
+    } catch {
+      runtimePageStructureStatus = 'environment_unavailable';
+    }
+
+    for (const workflow of plannedWorkflows) {
+      try {
+        const resolution = await resolveWorkflowLocator(page, workflow, listIframeKeyword);
+        const exploration = await exploreWorkflow(page, workflow, {
+          iframeKeyword: listIframeKeyword,
+          confirmExecute: true,
+        });
+        const resolved = createResolvedWorkflowFromPlanned({
+          workflow,
+          locator: resolution.locator,
+          locatorStrategy: resolution.locatorStrategy,
+          iframeSrcKeyword: listIframeKeyword,
+          exploration,
+        });
+
+        specSource = appendResolvedAgentWorkflowToSpec({
+          source: specSource,
+          moduleId: input.moduleId,
+          suiteTitle: `${contract.module.label} CRUD + Export`,
+          workflow: resolved,
+        });
+        resolvedWorkflows.push(workflow.workflowId);
+      } catch (error) {
+        needsReviewWorkflows.push(workflow.workflowId);
+        needsReviewWorkflowReasons.push({
+          workflowId: workflow.workflowId,
+          reason: formatRuntimeError(error),
+        });
+      }
+    }
+  } finally {
+    if (browser) {
+      await browser.close();
+    }
+  }
+
+  fs.writeFileSync(input.specPath, specSource, 'utf8');
+
+  return summarizeRuntimeRunnerResult({
+    resolvedWorkflows,
+    skippedWorkflows,
+    needsReviewWorkflows,
+    needsReviewWorkflowReasons,
+    specPath: input.specPath,
+    pageStructureSignals,
+    runtimePageStructureStatus,
+  });
+}
+
+/**
+ * 解析 `--k v` 形式的命令行参数为键值表。
+ * @param argv 去除解释器与脚本路径后的参数数组
+ * @returns 参数键值表
+ */
+function parseRawArgs(argv: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  const normalizedArgv = argv.filter((arg) => arg !== '--');
+  for (let index = 0; index < normalizedArgv.length; index += 2) {
+    const key = normalizedArgv[index];
+    const value = normalizedArgv[index + 1];
+    if (!key?.startsWith('--') || !value) {
+      throw new Error(`无效的参数对，靠近 ${key ?? '<empty>'}`);
+    }
+    result[key.slice(2)] = value;
+  }
+  return result;
+}
+
+/** 校验必填参数存在，缺失时抛错。 */
+function assertRequired(raw: Record<string, string>, required: string[]): void {
+  for (const key of required) {
+    if (!raw[key]) {
+      throw new Error(`Missing required argument --${key}`);
+    }
+  }
+}
+
+function toResolveInput(raw: Record<string, string>): GapRuntimeRunnerInput {
+  assertRequired(raw, ['contract', 'spec', 'project-dir', 'menu', 'module-id']);
+  return {
+    contractPath: raw.contract,
+    specPath: raw.spec,
+    projectDir: raw['project-dir'],
+    menuRoute: raw.menu,
+    moduleId: raw['module-id'],
+    workflowIds: raw['workflow-ids'] ? raw['workflow-ids'].split(',').filter(Boolean) : [],
+    headless: raw.headless === 'true',
+  };
+}
+
+function toExploreInput(raw: Record<string, string>): GapExploreInput {
+  assertRequired(raw, ['contract', 'project-dir', 'menu', 'module-id']);
+  return {
+    contractPath: raw.contract,
+    projectDir: raw['project-dir'],
+    menuRoute: raw.menu,
+    moduleId: raw['module-id'],
+    workflowIds: raw['workflow-ids'] ? raw['workflow-ids'].split(',').filter(Boolean) : [],
+    headless: raw.headless === 'true',
+    confirmExecute: raw['confirm-execute'] === 'true',
+  };
+}
+
+function toInferInput(raw: Record<string, string>): GapInferInput {
+  assertRequired(raw, ['contract', 'project-dir', 'menu', 'module-id']);
+  return {
+    contractPath: raw.contract,
+    projectDir: raw['project-dir'],
+    menuRoute: raw.menu,
+    moduleId: raw['module-id'],
+    workflowIds: raw['workflow-ids'] ? raw['workflow-ids'].split(',').filter(Boolean) : [],
+    headless: raw.headless === 'true',
+    // 引导模式默认点确定验证真实结果；显式传 --confirm-execute false 可只探到确认框。
+    confirmExecute: raw['confirm-execute'] !== 'false',
+  };
+}
+
+async function main(): Promise<void> {
+  const raw = parseRawArgs(process.argv.slice(2));
+  const mode = raw.mode ?? 'resolve';
+
+  if (mode === 'gaps') {
+    // gap 人工筛选 gate：纯读 contract 打印 gap 清单，不连真机。
+    assertRequired(raw, ['contract']);
+    const contract = JSON.parse(fs.readFileSync(raw.contract, 'utf8')) as CrudBusinessModuleContract;
+    const items = listGapWorkflows(contract);
+    process.stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+    return;
+  }
+
+  if (mode === 'explore') {
+    const results = await runGapRuntimeExplore(toExploreInput(raw));
+    process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+    return;
+  }
+
+  if (mode === 'infer') {
+    const drafts = await runGapRuntimeInfer(toInferInput(raw));
+    process.stdout.write(`${JSON.stringify(drafts, null, 2)}\n`);
+    return;
+  }
+
+  const result = await runGapRuntimeResolve(toResolveInput(raw));
+  process.stdout.write(`@@EP_STAGE_RUNTIME_SUMMARY@@\n${JSON.stringify(result, null, 2)}\n`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}