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

package/templates/glue/playwright.config.ts

@@ -0,0 +1,56 @@
+import { defineConfig, devices } from '@playwright/test';
+import dotenv from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const configDir = path.dirname(fileURLToPath(import.meta.url));
+
+dotenv.config({ path: path.resolve(configDir, '.env') });
+
+const numberFromEnv = (name: string, fallback: number): number => {
+  const value = Number(process.env[name]);
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+};
+
+const actionTimeout = numberFromEnv('STAGE_ACTION_TIMEOUT_MS', 30_000);
+const navigationTimeout = numberFromEnv('STAGE_NAVIGATION_TIMEOUT_MS', 60_000);
+const expectTimeout = numberFromEnv('STAGE_EXPECT_TIMEOUT_MS', 30_000);
+const slowMo = numberFromEnv('STAGE_SLOW_MO_MS', 500);
+
+export default defineConfig({
+  testDir: './src/tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  // 双报告并存：原生 HTML（查用例/trace/截图）+ stage-core 流程执行报告（流程视角，解释跳过/续测）。
+  // 编排器「报告」入口：流程报告 → /report，原生报告 → /pw-report。
+  reporter: [
+    ['html', { open: 'never' }],
+    ['@epoint-testtech/stage-core/reporter', { outputDir: 'stage-report', stateDir: '.stage-state' }],
+  ],
+  timeout: numberFromEnv('STAGE_TEST_TIMEOUT_MS', 30 * 60 * 1000),
+  expect: { timeout: expectTimeout },
+
+  use: {
+    baseURL: process.env.LOGIN_SYSTEM_URL,
+    ignoreHTTPSErrors: true,
+    actionTimeout,
+    navigationTimeout,
+    trace: 'on-first-retry',
+    headless: !!(process.env.CI || process.env.HEADLESS === 'true'),
+    launchOptions: { slowMo },
+    viewport: { width: 1800, height: 900 },
+    locale: 'zh-CN',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    permissions: ['clipboard-read'],
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1800, height: 900 } },
+    },
+  ],
+});

package/templates/glue/src/data/stage-config.yaml.tpl

@@ -0,0 +1,13 @@
+# stage-config.yaml — 项目配置
+# 由 stage-create 脚手架自动生成，按项目实际情况修改
+
+# 应用配置
+应用配置:
+  应用名称: "{{projectName}}"
+  应用版本: "0.0.1"
+
+# 菜单配置（LoginPage.navigateToMenu 使用）
+菜单配置: {}
+  # 示例：
+  # "场所窗口信息管理":
+  #   "场所窗口信息列表": "场所窗口信息管理>场所窗口信息列表"

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

@@ -0,0 +1,162 @@
+/**
+ * Gap Executor 纯函数层。
+ *
+ * 提供 resolved workflow 构建、spec 追加和运行计划生成。
+ * 真实页面操作（登录、菜单导航、按钮定位）由后续迭代接入。
+ *
+ * 真实 gap-executor runner 的执行顺序：
+ * 1. 使用 LoginPage.login() 复用登录骨架。
+ * 2. 使用 MenuPage.navigateToMenu(menuRoute) 进入模块页面。
+ * 3. 读取 planned/resolved 的 AgentInferredWorkflow。
+ * 4. 在真实页面中按 ActionCandidate.locator 或页面快照定位按钮。
+ * 5. 点击按钮后，只能基于 upstream_java_action / upstream_doc / runtime_page 证据形成断言。
+ * 6. 证据不足时写 needs_review，不生成通过断言。
+ */
+
+import type { AgentInferredWorkflow } from '@epoint-testtech/ep-stage-skill';
+import {
+  appendAgentWorkflowTest,
+  renderAgentWorkflowTest,
+  stableActionId,
+  stableWorkflowId,
+} from '@epoint-testtech/ep-stage-skill';
+
+type BuildWorkflowInput = {
+  moduleId: string;
+  pageId: string;
+  actionType: 'page_button' | 'row_action' | 'dialog_action';
+  label: string;
+  locator: string;
+  intent: string;
+  assertion: string;
+};
+
+type ResolvePlannedInput = {
+  workflow: AgentInferredWorkflow;
+  locator: string;
+  locatorStrategy: 'html_static' | 'playwright_snapshot' | 'agent_refined';
+  iframeSrcKeyword?: string;
+  exploration?: NonNullable<AgentInferredWorkflow['resolvedRuntime']>['exploration'];
+};
+
+type AppendInput = {
+  source: string;
+  moduleId: string;
+  suiteTitle: string;
+  workflow: AgentInferredWorkflow;
+};
+
+type RuntimePlanInput = {
+  moduleId: string;
+  menuRoute: string;
+  workflowIds: string[];
+};
+
+export function createGapExecutorRuntimePlan(input: RuntimePlanInput): {
+  moduleId: string;
+  menuRoute: string;
+  workflowIds: string[];
+  loginWith: 'LoginPage.login';
+  navigateWith: 'MenuPage.navigateToMenu';
+  evidenceSources: ['runtime_page', 'agent_reasoning'];
+} {
+  return {
+    moduleId: input.moduleId,
+    menuRoute: input.menuRoute,
+    workflowIds: input.workflowIds,
+    loginWith: 'LoginPage.login',
+    navigateWith: 'MenuPage.navigateToMenu',
+    evidenceSources: ['runtime_page', 'agent_reasoning'],
+  };
+}
+
+export function buildResolvedAgentWorkflow(input: BuildWorkflowInput): AgentInferredWorkflow {
+  const hashInput = {
+    moduleId: input.moduleId,
+    pageId: input.pageId,
+    actionType: input.actionType,
+    label: input.label,
+  };
+  const workflowId = stableWorkflowId(hashInput);
+  const actionId = stableActionId(hashInput);
+
+  return {
+    workflowId,
+    workflowKind: 'custom',
+    executionSource: 'agent_inferred',
+    status: 'resolved',
+    businessIntent: { status: 'resolved', value: input.intent },
+    elementActions: { status: 'resolved', value: [`点击「${input.label}」按钮`] },
+    assertionExpectation: { status: 'resolved', value: input.assertion },
+    actionCandidates: [{
+      actionId,
+      moduleId: input.moduleId,
+      pageId: input.pageId,
+      pageRole: 'list',
+      actionType: input.actionType,
+      label: input.label,
+      locator: input.locator,
+      evidence: [],
+      sourceRefs: [],
+    }],
+    triggerReason: '该动作不属于 CRUD + Export 骨架覆盖范围。',
+    evidence: [],
+    reviewReason: 'gap-executor 在真实页面确认该自定义业务动作可定位。',
+    resolvedRuntime: {
+      locator: input.locator,
+      locatorStrategy: 'html_static',
+      playwrightTestTitle: `Custom：${input.label}`,
+    },
+  };
+}
+
+/**
+ * 基于 planned workflow 和真实页面补证结果，构造 resolved workflow。
+ * @param input planned workflow 与 runtime locator 信息
+ * @returns 保留原业务语义与上游证据的 resolved workflow
+ */
+export function createResolvedWorkflowFromPlanned(input: ResolvePlannedInput): AgentInferredWorkflow {
+  if (input.workflow.status !== 'planned' && input.workflow.status !== 'resolved') {
+    throw new Error(`workflow ${input.workflow.workflowId} 状态为 ${input.workflow.status}，不能补齐为 resolved`);
+  }
+
+  const firstCandidate = input.workflow.actionCandidates[0];
+  if (!firstCandidate) {
+    throw new Error(`workflow ${input.workflow.workflowId} 缺少 actionCandidate`);
+  }
+
+  return {
+    ...input.workflow,
+    status: 'resolved',
+    actionCandidates: [
+      {
+        ...firstCandidate,
+        locator: input.locator,
+      },
+      ...input.workflow.actionCandidates.slice(1),
+    ],
+    reviewReason: input.workflow.reviewReason ?? 'gap-executor 在真实页面确认该自定义业务动作可定位。',
+    resolvedRuntime: {
+      locator: input.locator,
+      locatorStrategy: input.locatorStrategy,
+      iframeSrcKeyword: input.iframeSrcKeyword,
+      exploration: input.exploration,
+      playwrightTestTitle: `Custom：${firstCandidate.label}`,
+    },
+  };
+}
+
+export function appendResolvedAgentWorkflowToSpec(input: AppendInput): string {
+  const testSource = renderAgentWorkflowTest({
+    moduleId: input.moduleId,
+    suiteTitle: input.suiteTitle,
+    workflow: input.workflow,
+  });
+
+  return appendAgentWorkflowTest({
+    source: input.source,
+    workflowId: input.workflow.workflowId,
+    testTitle: input.workflow.resolvedRuntime?.playwrightTestTitle ?? input.workflow.workflowId,
+    testSource,
+  });
+}

package/templates/glue/src/gap-executor/gap-healer.ts

@@ -0,0 +1,50 @@
+/**
+ * 轻量 Gap Healer：分类失败、限制修复范围、生成 healer attempt 记录。
+ *
+ * 第一版只允许修复 4 类问题，不修改业务意图或凭空发明断言。
+ */
+
+import type { AgentInferredWorkflow } from '@epoint-testtech/ep-stage-skill';
+
+export type GapHealerFailureType =
+  | 'element_not_found'
+  | 'timeout'
+  | 'toast_not_found'
+  | 'click_intercepted'
+  | 'needs_review';
+
+export type GapHealerAttempt = NonNullable<AgentInferredWorkflow['healerAttempts']>[number];
+
+export function classifyGapFailure(error: unknown): GapHealerFailureType {
+  const message = error instanceof Error ? error.message : String(error);
+
+  if (/resolved to 0 elements|not found|strict mode violation/i.test(message)) {
+    return 'element_not_found';
+  }
+  if (/Timeout|timed out|超时/i.test(message)) {
+    return 'timeout';
+  }
+  if (/提示|toast|message/i.test(message)) {
+    return 'toast_not_found';
+  }
+  if (/intercepts pointer events|not visible|not enabled/i.test(message)) {
+    return 'click_intercepted';
+  }
+
+  return 'needs_review';
+}
+
+export function createGapHealerAttempt(input: {
+  attempt: number;
+  failureType: Exclude<GapHealerFailureType, 'needs_review'>;
+  change: string;
+  result: GapHealerAttempt['result'];
+}): GapHealerAttempt {
+  return {
+    attempt: input.attempt,
+    failureType: input.failureType,
+    change: input.change,
+    evidence: [],
+    result: input.result,
+  };
+}

package/templates/glue/src/gap-executor/page-structure-observer.ts

@@ -0,0 +1,102 @@
+import type { Frame, Page } from '@playwright/test';
+
+/**
+ * 运行时页面结构信号：静态结构在运行时是否可见。
+ *
+ * 与 ep-stage-skill 的 RuntimePageStructureSignal 结构同构，e2e 侧单独定义
+ * 以避免 runtime runner 反向依赖 skill 包的契约模块。
+ */
+export type RuntimePageStructureSignal = {
+  selector: string;
+  staticPresent: boolean;
+  runtimeVisible: boolean;
+  runtimeMismatch: boolean;
+  evidenceText: string;
+};
+
+/**
+ * runtime runner 关注的三类 MiniUI 核心结构选择器。
+ */
+const selectors = [
+  "div[class*='mini-datagrid']",
+  "div[class*='fui-condition']",
+  "div[class*='mini-grid-pager']",
+];
+
+/**
+ * 在 runtime runner 当前已定位的业务页面内采集 MiniUI 核心结构的运行时可见性。
+ *
+ * 优先检查业务 iframe，再回退主页面与其他 iframe。staticPresent 此处恒为 true，
+ * 静态存在性由 page-structure 抽取阶段提供；本函数只补运行时可见性证据。
+ *
+ * @param page - runtime runner 当前页面。
+ * @param iframeKeyword - 契约解析出的业务 iframe src 关键字。
+ * @returns 三类结构选择器的运行时可见性信号。
+ */
+export async function collectRuntimePageStructureSignals(
+  page: Page,
+  iframeKeyword?: string,
+): Promise<RuntimePageStructureSignal[]> {
+  const signals: RuntimePageStructureSignal[] = [];
+  for (const selector of selectors) {
+    const visibleContext = await findVisibleContext(page, selector, iframeKeyword);
+    const runtimeVisible = visibleContext !== undefined;
+    signals.push({
+      selector,
+      staticPresent: true,
+      runtimeVisible,
+      runtimeMismatch: !runtimeVisible,
+      evidenceText: runtimeVisible
+        ? `${selector} 运行时可见（${visibleContext}）`
+        : `${selector} 在主页面和业务 iframe 中均不可见或未挂载`,
+    });
+  }
+  return signals;
+}
+
+/**
+ * 查找指定选择器在哪个运行时上下文中可见。
+ *
+ * @param page - Playwright 页面。
+ * @param selector - MiniUI 结构选择器。
+ * @param iframeKeyword - 业务 iframe src 关键字。
+ * @returns 可见上下文说明；不可见时返回 undefined。
+ */
+async function findVisibleContext(
+  page: Page,
+  selector: string,
+  iframeKeyword?: string,
+): Promise<string | undefined> {
+  const contexts = listRuntimeContexts(page, iframeKeyword);
+  for (const context of contexts) {
+    const runtimeVisible = await context.target.locator(selector).first().isVisible().catch(() => false);
+    if (runtimeVisible) {
+      return context.label;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 列出运行时页面结构观察上下文，业务 iframe 优先。
+ *
+ * @param page - Playwright 页面。
+ * @param iframeKeyword - 业务 iframe src 关键字。
+ * @returns 主页面和 frame 上下文。
+ */
+function listRuntimeContexts(
+  page: Page,
+  iframeKeyword?: string,
+): Array<{ label: string; target: Page | Frame }> {
+  const frames = page.frames().filter((frame) => frame !== page.mainFrame());
+  const businessFrames = iframeKeyword
+    ? frames.filter((frame) => frame.url().includes(iframeKeyword))
+    : frames;
+  const otherFrames = frames.filter((frame) => !businessFrames.includes(frame));
+
+  return [
+    ...businessFrames.map((frame) => ({ label: `业务 iframe: ${frame.url()}`, target: frame })),
+    { label: '主页面', target: page },
+    ...otherFrames.map((frame) => ({ label: `iframe: ${frame.url()}`, target: frame })),
+  ];
+}