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

package/templates/glue/src/report/glue-report.ts

@@ -0,0 +1,855 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// ============================================================================
+// 类型定义（详见 docs/superpowers/specs/2026-06-09-glue-execution-report-design.md §5）
+// ============================================================================
+
+/** 工作流执行来源：胶水编码生成或 Agent 推理 */
+export type GlueWorkflowExecutionSource = 'glue_code' | 'agent_inferred';
+
+/** 工作流执行状态 */
+export type GlueWorkflowStatus =
+  | 'passed'
+  | 'failed'
+  | 'needs_review'
+  | 'blocked'
+  | 'skipped'
+  | 'unresolved';
+
+/** 工作流业务类型 */
+export type GlueWorkflowKind =
+  | 'create'
+  | 'read'
+  | 'update'
+  | 'delete'
+  | 'export'
+  | 'custom';
+
+/** 证据来源类型 */
+export type GlueEvidenceSource =
+  | 'crud_flow_slots'
+  | 'module_hints'
+  | 'upstream_html'
+  | 'upstream_java_action'
+  | 'upstream_doc'
+  | 'runtime_page'
+  | 'agent_reasoning';
+
+/** 工作流内部步骤 */
+export type GlueWorkflowStep = {
+  name: string;
+  elementAction: string;
+  assertionExpectation?: string;
+  status?: GlueWorkflowStatus;
+};
+
+/** 证据引用 */
+export type GlueEvidenceRef = {
+  source: GlueEvidenceSource;
+  file?: string;
+  selector?: string;
+  text?: string;
+  note: string;
+};
+
+/**
+ * 调用方提交给 recorder 的工作流输入。
+ * status / startedAt / endedAt / durationMs / errorMessage 由 recorder 自动管理；
+ * 调用方仍可在 input 中预置 status（例如 'needs_review'）以覆盖默认 'passed'。
+ */
+export type GlueWorkflowRecordInput = {
+  workflowId: string;
+  moduleId: string;
+  pageName?: string;
+  workflowKind: GlueWorkflowKind;
+  workflowName: string;
+  executionSource: GlueWorkflowExecutionSource;
+  status?: GlueWorkflowStatus;
+  businessIntent: string;
+  elementActions: string[];
+  assertionExpectation: string;
+  steps?: GlueWorkflowStep[];
+  evidenceSources: GlueEvidenceSource[];
+  evidenceRefs: GlueEvidenceRef[];
+  playwrightSuiteTitle?: string;
+  playwrightTestTitle?: string;
+  playwrightTestId?: string;
+  reviewReason?: string;
+};
+
+/** 最终落盘的工作流记录 */
+export type GlueWorkflowRecord = {
+  workflowId: string;
+  moduleId: string;
+  pageName?: string;
+  workflowKind: GlueWorkflowKind;
+  workflowName: string;
+  executionSource: GlueWorkflowExecutionSource;
+  status: GlueWorkflowStatus;
+  businessIntent: string;
+  elementActions: string[];
+  assertionExpectation: string;
+  steps?: GlueWorkflowStep[];
+  evidenceSources: GlueEvidenceSource[];
+  evidenceRefs: GlueEvidenceRef[];
+  startedAt?: string;
+  endedAt?: string;
+  durationMs?: number;
+  errorMessage?: string;
+  playwrightSuiteTitle?: string;
+  playwrightTestTitle?: string;
+  playwrightTestId?: string;
+  reviewReason?: string;
+};
+
+/** 运行环境信息 */
+export type GlueExecutionEnvironment = {
+  endpointName?: string;
+  operatingSystem?: string;
+  osLocale?: string;
+  browserName?: string;
+  browserVersion?: string;
+  viewport?: {
+    width: number;
+    height: number;
+  };
+  screen?: {
+    width: number;
+    height: number;
+  };
+  nodeVersion?: string;
+  playwrightVersion?: string;
+};
+
+/** 执行报告整体结构 */
+export type GlueExecutionReport = {
+  schemaVersion: 'glue-execution-report/v1';
+  runTimestamp: string;
+  moduleId: string;
+  moduleName?: string;
+  generatedSpecFile?: string;
+  suiteTitle?: string;
+  startedAt: string;
+  endedAt?: string;
+  durationMs?: number;
+  environment: GlueExecutionEnvironment;
+  summary: {
+    totalWorkflows: number;
+    glueCodeWorkflows: number;
+    agentInferredWorkflows: number;
+    passed: number;
+    failed: number;
+    blocked: number;
+    warnings: number;
+    needsReview: number;
+    unresolved: number;
+  };
+  workflows: GlueWorkflowRecord[];
+  playwrightReport?: {
+    title: string;
+    url: string;
+    path?: string;
+  };
+};
+
+// ============================================================================
+// Recorder 构造选项
+// ============================================================================
+
+/** GlueWorkflowRecorder 构造选项 */
+export type GlueWorkflowRecorderOptions = {
+  /** 报告产物根目录，例如 `e2e/glue-code-mvp` */
+  outputRoot: string;
+  /** 本次运行时间戳，格式 `YYYYMMDDHHmmss`；缺省时优先取环境变量 `STAGE_REPORT_TIMESTAMP` */
+  runTimestamp?: string;
+  moduleId: string;
+  moduleName?: string;
+  suiteTitle?: string;
+  generatedSpecFile?: string;
+  /** Playwright 原生报告入口；缺省时指向同批次目录下的 `./playwright-report/index.html` */
+  playwrightReportUrl?: string;
+  playwrightReportPath?: string;
+  playwrightReportTitle?: string;
+  /** 调用方可显式覆盖部分环境字段；其余字段从 os / process 自动采集 */
+  environment?: Partial<GlueExecutionEnvironment>;
+};
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+
+/**
+ * 把数字补齐到指定位数，便于生成 YYYYMMDDHHmmss 时间戳。
+ */
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, '0');
+}
+
+/**
+ * 按本地时间生成 `YYYYMMDDHHmmss` 格式时间戳。
+ */
+function formatLocalTimestamp(date: Date): string {
+  return `${date.getFullYear()}${pad(date.getMonth() + 1, 2)}${pad(date.getDate(), 2)}${pad(date.getHours(), 2)}${pad(date.getMinutes(), 2)}${pad(date.getSeconds(), 2)}`;
+}
+
+/**
+ * 读取 playwright.config.ts 在测试启动时写入的 run-info.json，确保跨进程时间戳一致。
+ * 文件位于 glue-report/run-info.json，不存在时返回 undefined（回退到 formatLocalTimestamp）。
+ */
+function readRunInfoTimestamp(outputRoot: string): string | undefined {
+  try {
+    const filePath = path.join(outputRoot, 'glue-report', 'run-info.json');
+    const content = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    return content.runTimeStamp ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * HTML 转义，避免 workflow 内的业务文本注入 `<script>` 或破坏布局。
+ */
+function escapeHtml(value: unknown): string {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  const text = String(value);
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * 把 executionSource 转为业务人员可读的中文描述。
+ */
+function executionSourceLabel(source: GlueWorkflowExecutionSource): string {
+  return source === 'glue_code' ? '胶水编码执行' : 'Agent 推理执行';
+}
+
+/**
+ * 把工作流状态转为中文标签，便于报告展示。
+ */
+function statusLabel(status: GlueWorkflowStatus): string {
+  switch (status) {
+    case 'passed':
+      return '通过';
+    case 'failed':
+      return '失败';
+    case 'needs_review':
+      return '待审阅';
+    case 'blocked':
+      return '阻塞';
+    case 'skipped':
+      return '跳过';
+    case 'unresolved':
+      return '未解析';
+    default:
+      return status;
+  }
+}
+
+/**
+ * 自动采集运行环境字段，结果会与调用方传入的覆盖项合并。
+ */
+function detectEnvironment(
+  override: Partial<GlueExecutionEnvironment> | undefined,
+): GlueExecutionEnvironment {
+  const detected: GlueExecutionEnvironment = {
+    endpointName: os.hostname(),
+    operatingSystem: `${os.type()} ${os.release()} (${os.platform()} ${os.arch()})`,
+    osLocale:
+      process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES || undefined,
+    nodeVersion: process.versions?.node ? `v${process.versions.node}` : undefined,
+  };
+  return { ...detected, ...(override ?? {}) };
+}
+
+// ============================================================================
+// GlueWorkflowRecorder
+// ============================================================================
+
+/**
+ * 工作流级胶水执行报告记录器。
+ *
+ * 调用方通过 `runRecordedWorkflow()` 包装真实工作流执行，recorder 负责打时间戳、
+ * 累积 workflow record，最后通过 `writeReport()` 一次性落盘 JSON + HTML 报告。
+ *
+ * 设计约束：第一版只服务 `e2e/glue-code-mvp`，不进 `stage-core` 或 `stage-web`。
+ */
+export class GlueWorkflowRecorder {
+  private readonly options: GlueWorkflowRecorderOptions;
+  private readonly runTimestamp: string;
+  private readonly startedAt: string;
+  private readonly startedAtMs: number;
+  private readonly environment: GlueExecutionEnvironment;
+  private readonly workflows: GlueWorkflowRecord[] = [];
+
+  constructor(options: GlueWorkflowRecorderOptions) {
+    this.options = options;
+    this.runTimestamp =
+      options.runTimestamp ??
+      process.env.STAGE_REPORT_TIMESTAMP ??
+      readRunInfoTimestamp(options.outputRoot) ??
+      formatLocalTimestamp(new Date());
+    const now = new Date();
+    this.startedAt = now.toISOString();
+    this.startedAtMs = now.getTime();
+    this.environment = detectEnvironment(options.environment);
+  }
+
+  /** 暴露本次运行的时间戳，便于外部组织日志或产物路径 */
+  getRunTimestamp(): string {
+    return this.runTimestamp;
+  }
+
+  /**
+   * 追加一条已完成的 workflow 记录。
+   * 一般由 `runRecordedWorkflow()` 调用，调用方也可以直接 push 静态记录。
+   */
+  addRecord(record: GlueWorkflowRecord): void {
+    this.workflows.push(record);
+  }
+
+  /**
+   * 浅 merge 部分环境字段到当前 environment，便于运行中途补全浏览器等信息。
+   */
+  updateEnvironment(partial: Partial<GlueExecutionEnvironment>): void {
+    Object.assign(this.environment, partial);
+  }
+
+  /**
+   * 落盘 JSON + HTML 报告。
+   *
+   * @returns 报告根目录、JSON 路径、HTML 路径以及最终 report 对象
+   */
+  writeReport(): {
+    reportRoot: string;
+    jsonPath: string;
+    htmlPath: string;
+    report: GlueExecutionReport;
+  } {
+    const endDate = new Date();
+    const endedAt = endDate.toISOString();
+    const durationMs = endDate.getTime() - this.startedAtMs;
+
+    const report: GlueExecutionReport = {
+      schemaVersion: 'glue-execution-report/v1',
+      runTimestamp: this.runTimestamp,
+      moduleId: this.options.moduleId,
+      moduleName: this.options.moduleName,
+      generatedSpecFile: this.options.generatedSpecFile,
+      suiteTitle: this.options.suiteTitle,
+      startedAt: this.startedAt,
+      endedAt,
+      durationMs,
+      environment: this.environment,
+      summary: this.buildSummary(),
+      workflows: this.workflows,
+      playwrightReport: {
+        title: this.options.playwrightReportTitle ?? '打开 Playwright 原生报告',
+        url: this.options.playwrightReportUrl ?? './playwright-report/index.html',
+        path: this.options.playwrightReportPath,
+      },
+    };
+
+    const glueReportRoot = path.join(this.options.outputRoot, 'glue-report', this.runTimestamp);
+    fs.mkdirSync(glueReportRoot, { recursive: true });
+
+    const jsonPath = path.join(glueReportRoot, `stage-glue-${this.runTimestamp}.json`);
+    const htmlPath = path.join(glueReportRoot, `stage-glue-${this.runTimestamp}.html`);
+
+    fs.writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
+    fs.writeFileSync(htmlPath, renderReportHtml(report), 'utf-8');
+
+    return { reportRoot: glueReportRoot, jsonPath, htmlPath, report };
+  }
+
+  /** 根据当前累积的 workflow 列表汇总统计字段 */
+  private buildSummary(): GlueExecutionReport['summary'] {
+    let glueCodeWorkflows = 0;
+    let agentInferredWorkflows = 0;
+    let passed = 0;
+    let failed = 0;
+    let blocked = 0;
+    let needsReview = 0;
+    let unresolved = 0;
+
+    for (const w of this.workflows) {
+      if (w.executionSource === 'glue_code') {
+        glueCodeWorkflows += 1;
+      } else {
+        agentInferredWorkflows += 1;
+      }
+      switch (w.status) {
+        case 'passed':
+          passed += 1;
+          break;
+        case 'failed':
+          failed += 1;
+          break;
+        case 'blocked':
+          blocked += 1;
+          break;
+        case 'needs_review':
+          needsReview += 1;
+          break;
+        case 'unresolved':
+          unresolved += 1;
+          break;
+        default:
+          break;
+      }
+    }
+
+    return {
+      totalWorkflows: this.workflows.length,
+      glueCodeWorkflows,
+      agentInferredWorkflows,
+      passed,
+      failed,
+      blocked,
+      warnings: needsReview + unresolved,
+      needsReview,
+      unresolved,
+    };
+  }
+}
+
+// ============================================================================
+// runRecordedWorkflow
+// ============================================================================
+
+/**
+ * 在 recorder 上下文中执行 workflow body 并自动记录开始 / 结束 / 失败时间。
+ *
+ * - 执行成功时若调用方未预置状态，则置为 `passed`。
+ * - 执行失败时置为 `failed`、写 `errorMessage`，并 re-throw 让 Playwright 仍然识别失败。
+ * - 当 `executionSource === 'agent_inferred'` 时，会在进入 body 之前校验
+ *   `evidenceSources` 必须包含 `agent_reasoning` 且 `reviewReason` 必填。
+ *
+ * @param recorder 工作流记录器实例
+ * @param input 工作流输入元数据
+ * @param body 工作流业务体（异步）
+ */
+export async function runRecordedWorkflow(
+  recorder: GlueWorkflowRecorder,
+  input: GlueWorkflowRecordInput,
+  body: () => Promise<void>,
+): Promise<void> {
+  if (input.executionSource === 'agent_inferred') {
+    if (!input.evidenceSources.includes('agent_reasoning')) {
+      throw new Error(
+        `[glue-report] workflow ${input.workflowId} executionSource=agent_inferred 时 evidenceSources 必须包含 'agent_reasoning'`,
+      );
+    }
+    if (!input.reviewReason || input.reviewReason.trim() === '') {
+      throw new Error(
+        `[glue-report] workflow ${input.workflowId} executionSource=agent_inferred 时 reviewReason 必填`,
+      );
+    }
+  }
+
+  const startDate = new Date();
+  const startedAt = startDate.toISOString();
+  const startedAtMs = startDate.getTime();
+
+  try {
+    await body();
+    const endDate = new Date();
+    recorder.addRecord({
+      ...input,
+      status: input.status ?? 'passed',
+      startedAt,
+      endedAt: endDate.toISOString(),
+      durationMs: endDate.getTime() - startedAtMs,
+    });
+  } catch (error) {
+    const endDate = new Date();
+    const message = error instanceof Error ? error.message : String(error);
+    recorder.addRecord({
+      ...input,
+      status: 'failed',
+      startedAt,
+      endedAt: endDate.toISOString(),
+      durationMs: endDate.getTime() - startedAtMs,
+      errorMessage: message,
+    });
+    // 抛出原错误，确保 Playwright 仍然把该 test 标记为失败
+    throw error;
+  }
+}
+
+// ============================================================================
+// HTML 渲染
+// ============================================================================
+
+/**
+ * 把毫秒转换为人类可读的耗时字符串（毫秒 / 秒 / 分秒）。
+ */
+function formatDuration(ms: number | undefined): string {
+  if (ms === undefined || Number.isNaN(ms)) {
+    return '-';
+  }
+  if (ms < 1000) {
+    return `${ms} ms`;
+  }
+  const totalSeconds = ms / 1000;
+  if (totalSeconds < 60) {
+    return `${totalSeconds.toFixed(2)} s`;
+  }
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = (totalSeconds - minutes * 60).toFixed(1);
+  return `${minutes} m ${seconds} s`;
+}
+
+/**
+ * 格式化为人类友好的显示时间戳，月/日/时不补零，分/秒补零。
+ * 例如 `2026-6-10 9:05:03`。
+ */
+function formatDisplayTimestamp(date: Date): string {
+  const y = date.getFullYear();
+  const m = date.getMonth() + 1;
+  const d = date.getDate();
+  const h = date.getHours();
+  const min = String(date.getMinutes()).padStart(2, '0');
+  const sec = String(date.getSeconds()).padStart(2, '0');
+  return `${y}-${m}-${d} ${h}:${min}:${sec}`;
+}
+
+/**
+ * 以毫秒精度格式化耗时，避免 55 秒被进位显示成 1 分钟。
+ */
+function formatPreciseDuration(ms: number | undefined): string {
+  if (ms === undefined || ms <= 0) {
+    return '-';
+  }
+
+  if (ms < 1_000) {
+    return `${ms} 毫秒`;
+  }
+
+  const hours = Math.floor(ms / 3_600_000);
+  const minutes = Math.floor((ms % 3_600_000) / 60_000);
+  const seconds = Math.floor((ms % 60_000) / 1_000);
+  const milliseconds = ms % 1_000;
+
+  if (hours > 0) {
+    return `${hours} 小时 ${minutes} 分 ${seconds}.${pad(milliseconds, 3)} 秒`;
+  }
+  if (minutes > 0) {
+    return `${minutes} 分 ${seconds}.${pad(milliseconds, 3)} 秒`;
+  }
+  return `${seconds}.${pad(milliseconds, 3)} 秒`;
+}
+
+/**
+ * 格式化浏览器标签：chromium 映射为 `Chrome For Testing`，其他原样输出。
+ */
+function formatBrowserLabel(env: GlueExecutionEnvironment): string {
+  if (env.browserName === 'chromium') {
+    return `Chrome For Testing ${env.browserVersion ?? '-'}`;
+  }
+  return `${env.browserName ?? '-'} ${env.browserVersion ?? ''}`;
+}
+
+/**
+ * 渲染顶部环境/统计概览段。
+ */
+function renderHeaderSection(report: GlueExecutionReport): string {
+  const env = report.environment;
+
+  const overviewRows: Array<[string, string]> = [
+    ['测试套件', report.suiteTitle ?? report.moduleName ?? report.moduleId],
+    ['执行时间', formatDisplayTimestamp(new Date(report.startedAt))],
+    ['执行耗时', formatPreciseDuration(report.durationMs)],
+    ['浏览器', formatBrowserLabel(env)],
+  ];
+
+  const overviewHtml = overviewRows
+    .map(
+      ([label, value]) =>
+        `<tr><th>${escapeHtml(label)}</th><td>${escapeHtml(value)}</td></tr>`,
+    )
+    .join('');
+
+  const summary = report.summary;
+
+  // 卡片数据结构：[标签, 数值, CSS kind, 筛选值]
+  const strategyCards: Array<[string, number, string, string]> = [
+    ['总测试流程', summary.totalWorkflows, 'total', ''],
+    ['胶水编码执行', summary.glueCodeWorkflows, 'glue', 'glue_code'],
+    ['Agent推理执行', summary.agentInferredWorkflows, 'agent', 'agent_inferred'],
+  ];
+
+  const resultCards: Array<[string, number, string, string]> = [
+    ['通过', summary.passed, 'passed', 'passed'],
+    ['失败', summary.failed, 'failed', 'failed'],
+    ['阻塞', summary.blocked, 'blocked', 'blocked'],
+    ['待审阅', summary.needsReview, 'review', 'needs_review'],
+    ['未解析', summary.unresolved, 'unresolved', 'unresolved'],
+  ];
+
+  const renderCards = (cards: Array<[string, number, string, string]>, filterGroup: string): string =>
+    cards
+      .map(
+        ([label, value, kind, filterValue]) => `
+        <div class="summary-card summary-card--${kind}" data-filter-group="${filterGroup}" data-filter-value="${filterValue}" role="button" tabindex="0">
+          <div class="summary-card__value">${escapeHtml(value)}</div>
+          <div class="summary-card__label">${escapeHtml(label)}</div>
+        </div>`,
+      )
+      .join('');
+
+  return `
+    <section class="overview">
+      <h1>胶水编码-测试执行</h1>
+      <table class="overview-table">${overviewHtml}</table>
+      <h3 class="summary-section-title">执行策略</h3>
+      <div class="summary-grid summary-grid--strategy">${renderCards(strategyCards, 'strategy')}</div>
+      <h3 class="summary-section-title">执行结果</h3>
+      <div class="summary-grid summary-grid--result">${renderCards(resultCards, 'status')}</div>
+    </section>
+  `;
+}
+
+/**
+ * 渲染单个工作流卡片。
+ */
+function renderWorkflowCard(record: GlueWorkflowRecord): string {
+  const actionsHtml = record.elementActions.length
+    ? `<ul class="actions">${record.elementActions
+        .map((a) => `<li>${escapeHtml(a)}</li>`)
+        .join('')}</ul>`
+    : '<p class="muted">（无）</p>';
+
+  const evidenceHtml = record.evidenceRefs.length
+    ? `<ul class="evidence">${record.evidenceRefs
+        .map(
+          (ref) => `<li>
+            <span class="evidence-source">${escapeHtml(ref.source)}</span>
+            ${ref.selector ? `<code>${escapeHtml(ref.selector)}</code>` : ''}
+            ${ref.file ? `<span class="evidence-file">${escapeHtml(ref.file)}</span>` : ''}
+            ${ref.text ? `<span class="evidence-text">${escapeHtml(ref.text)}</span>` : ''}
+            <span class="evidence-note">${escapeHtml(ref.note)}</span>
+          </li>`,
+        )
+        .join('')}</ul>`
+    : '<p class="muted">（无证据引用）</p>';
+
+  const stepsHtml = record.steps?.length
+    ? `<ol class="steps">${record.steps
+        .map(
+          (step) =>
+            `<li><strong>${escapeHtml(step.name)}</strong>：${escapeHtml(step.elementAction)}${
+              step.assertionExpectation
+                ? ` <em>断言：${escapeHtml(step.assertionExpectation)}</em>`
+                : ''
+            }${step.status ? ` <span class="step-status">[${escapeHtml(statusLabel(step.status))}]</span>` : ''}</li>`,
+        )
+        .join('')}</ol>`
+    : '';
+
+  const errorHtml = record.errorMessage
+    ? `<div class="error"><strong>错误信息：</strong><pre>${escapeHtml(record.errorMessage)}</pre></div>`
+    : '';
+
+  const reviewHtml = record.reviewReason
+    ? `<div class="review"><strong>审阅原因：</strong>${escapeHtml(record.reviewReason)}</div>`
+    : '';
+
+  const pwHtml =
+    record.playwrightSuiteTitle || record.playwrightTestTitle
+      ? `<div class="pw-ref">Playwright：${escapeHtml(record.playwrightSuiteTitle ?? '')} / ${escapeHtml(record.playwrightTestTitle ?? '')}</div>`
+      : '';
+
+  return `
+    <article class="workflow workflow--${escapeHtml(record.status)}" data-strategy="${escapeHtml(record.executionSource)}" data-status="${escapeHtml(record.status)}">
+      <header class="workflow__header">
+        <div class="workflow__title">
+          <h2>${escapeHtml(record.workflowName)}</h2>
+          <code class="workflow__id">${escapeHtml(record.workflowId)}</code>
+        </div>
+        <div class="workflow__meta">
+          <span class="badge badge--kind">${escapeHtml(record.workflowKind)}</span>
+          <span class="badge badge--source">${escapeHtml(executionSourceLabel(record.executionSource))}</span>
+          <span class="badge badge--status badge--${escapeHtml(record.status)}">${escapeHtml(statusLabel(record.status))}</span>
+        </div>
+      </header>
+      <dl class="workflow__body">
+        <dt>业务意图</dt><dd>${escapeHtml(record.businessIntent)}</dd>
+        <dt>断言预期</dt><dd>${escapeHtml(record.assertionExpectation)}</dd>
+        <dt>元素动作</dt><dd>${actionsHtml}</dd>
+        <dt>证据引用</dt><dd>${evidenceHtml}</dd>
+        ${stepsHtml ? `<dt>内部步骤</dt><dd>${stepsHtml}</dd>` : ''}
+      </dl>
+      ${errorHtml}
+      ${reviewHtml}
+      ${pwHtml}
+    </article>
+  `;
+}
+
+/**
+ * 渲染底部 Playwright 原生报告入口区。
+ */
+function renderFooterSection(report: GlueExecutionReport): string {
+  const inner = report.playwrightReport
+    ? `<a class="pw-link" href="${escapeHtml(report.playwrightReport.url)}" target="_blank" rel="noopener">${escapeHtml(report.playwrightReport.title)}</a>`
+    : '<p class="muted">本次未发现 Playwright 原生报告产物</p>';
+  return `
+    <footer class="footer">
+      ${inner}
+    </footer>
+  `;
+}
+
+/**
+ * 渲染整份 HTML 报告（单文件、内联样式、无外部依赖）。
+ * @internal 测试专用导出，外部请勿直接调用。
+ */
+export function renderReportHtml(report: GlueExecutionReport): string {
+  const workflowsHtml =
+    report.workflows.length > 0
+      ? report.workflows.map(renderWorkflowCard).join('\n')
+      : '<p class="muted">（本次运行未记录任何工作流）</p>';
+
+  const style = `
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif; background: #f7f8fa; color: #1f2933; margin: 0; padding: 24px; }
+    h1 { margin: 0 0 16px; font-size: 22px; }
+    h2 { font-size: 16px; margin: 16px 0 8px; }
+    section.overview { background: #fff; border-radius: 8px; padding: 20px; box-shadow: 0 1px 3px rgba(0,0,0,0.05); margin-bottom: 24px; }
+    .overview-table { width: 100%; border-collapse: collapse; margin-bottom: 16px; }
+    .overview-table th, .overview-table td { text-align: left; padding: 6px 12px; border-bottom: 1px solid #eee; font-size: 13px; }
+    .overview-table th { width: 140px; color: #52606d; font-weight: 600; }
+    .summary-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(140px, 1fr)); gap: 12px; }
+    .summary-card { background: #f0f4f8; border-radius: 6px; padding: 12px; text-align: center; cursor: pointer; transition: box-shadow 0.15s, transform 0.1s; }
+    .summary-card:hover { box-shadow: 0 2px 6px rgba(0,0,0,0.1); transform: translateY(-1px); }
+    .summary-card--active { box-shadow: 0 0 0 2px #2563eb; }
+    .summary-card__value { font-size: 22px; font-weight: 600; }
+    .summary-card__label { font-size: 12px; color: #52606d; margin-top: 4px; }
+    .summary-card--passed { background: #e3fcec; }
+    .summary-card--failed { background: #ffe3e3; }
+    .summary-card--review { background: #fff4d6; }
+    .summary-card--unresolved { background: #f0e8ff; }
+    .summary-card--blocked { background: #ffe7d6; }
+    article.workflow { background: #fff; border-radius: 8px; padding: 16px 20px; margin-bottom: 16px; box-shadow: 0 1px 3px rgba(0,0,0,0.05); border-left: 4px solid #cbd2d9; }
+    article.workflow--passed { border-left-color: #2f9e44; }
+    article.workflow--failed { border-left-color: #e03131; }
+    article.workflow--needs_review { border-left-color: #f59f00; }
+    article.workflow--blocked { border-left-color: #d9480f; }
+    article.workflow--unresolved { border-left-color: #7048e8; }
+    .workflow__header { display: flex; justify-content: space-between; align-items: flex-start; flex-wrap: wrap; gap: 12px; }
+    .workflow__title h2 { margin: 0; font-size: 16px; }
+    .workflow__id { font-size: 12px; color: #52606d; }
+    .workflow__meta { display: flex; gap: 8px; flex-wrap: wrap; }
+    .badge { display: inline-block; padding: 2px 8px; font-size: 12px; border-radius: 12px; background: #e4e7eb; color: #1f2933; }
+    .badge--passed { background: #2f9e44; color: #fff; }
+    .badge--failed { background: #e03131; color: #fff; }
+    .badge--needs_review { background: #f59f00; color: #fff; }
+    .badge--blocked { background: #d9480f; color: #fff; }
+    .badge--unresolved { background: #7048e8; color: #fff; }
+    dl.workflow__body { display: grid; grid-template-columns: 100px 1fr; gap: 6px 12px; margin: 12px 0 4px; font-size: 13px; }
+    dl.workflow__body dt { color: #52606d; font-weight: 600; }
+    ul.actions, ul.evidence, ol.steps { margin: 0; padding-left: 18px; }
+    code { background: #f0f4f8; padding: 1px 4px; border-radius: 3px; font-size: 12px; }
+    .evidence-source { font-weight: 600; color: #334e68; margin-right: 4px; }
+    .evidence-note { color: #52606d; margin-left: 6px; }
+    .error pre { background: #fff5f5; color: #c92a2a; padding: 8px; border-radius: 4px; overflow-x: auto; font-size: 12px; }
+    .review { background: #fff9db; padding: 8px 12px; border-radius: 4px; margin-top: 8px; font-size: 13px; }
+    .pw-ref { font-size: 12px; color: #52606d; margin-top: 8px; }
+    .muted { color: #829ab1; font-size: 13px; }
+    footer.footer { background: #fff; border-radius: 8px; padding: 16px 20px; margin-top: 16px; box-shadow: 0 1px 3px rgba(0,0,0,0.05); }
+    .pw-link { display: inline-block; padding: 8px 16px; background: #2563eb; color: #fff; border-radius: 4px; text-decoration: none; font-size: 14px; }
+    .pw-link:hover { background: #1d4ed8; }
+    .workflow-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 12px; flex-wrap: wrap; margin: 16px 0 8px; }
+    .workflow-toolbar h2 { margin: 0; }
+    .workflow-filters { display: flex; gap: 8px; }
+    .workflow-filters select { padding: 4px 8px; font-size: 13px; border: 1px solid #cbd2d9; border-radius: 4px; background: #fff; color: #1f2933; }
+    .summary-section-title { font-size: 13px; color: #52606d; margin: 12px 0 4px; font-weight: 600; }
+  `;
+
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1.0" />
+  <title>胶水编码-测试执行</title>
+  <style>${style}</style>
+</head>
+<body>
+  ${renderHeaderSection(report)}
+  <section class="workflows">
+    <div class="workflow-toolbar">
+      <h2>场景工作流</h2>
+      <div class="workflow-filters">
+        <select id="filter-strategy">
+          <option value="">全部执行策略</option>
+          <option value="glue_code">胶水编码执行</option>
+          <option value="agent_inferred">Agent推理执行</option>
+        </select>
+        <select id="filter-status">
+          <option value="">全部执行结果</option>
+          <option value="passed">通过</option>
+          <option value="failed">失败</option>
+          <option value="blocked">阻塞</option>
+          <option value="needs_review">待审阅</option>
+          <option value="unresolved">未解析</option>
+        </select>
+      </div>
+    </div>
+    ${workflowsHtml}
+  </section>
+  ${renderFooterSection(report)}
+  <script>
+    (function() {
+      var fs = document.getElementById('filter-strategy');
+      var fst = document.getElementById('filter-status');
+      var cards = document.querySelectorAll('article.workflow');
+      var summaryCards = document.querySelectorAll('.summary-card');
+
+      function apply() {
+        var s = fs.value, st = fst.value;
+        for (var i = 0; i < cards.length; i++) {
+          var c = cards[i];
+          var show = (!s || c.dataset.strategy === s) && (!st || c.dataset.status === st);
+          c.style.display = show ? '' : 'none';
+        }
+        updateCardHighlight();
+      }
+
+      function updateCardHighlight() {
+        for (var i = 0; i < summaryCards.length; i++) {
+          var card = summaryCards[i];
+          var group = card.dataset.filterGroup;
+          var value = card.dataset.filterValue;
+          var select = group === 'strategy' ? fs : fst;
+          var active = select.value !== '' && select.value === value;
+          card.classList.toggle('summary-card--active', active);
+        }
+      }
+
+      fs.addEventListener('change', apply);
+      fst.addEventListener('change', apply);
+
+      for (var i = 0; i < summaryCards.length; i++) {
+        (function(card) {
+          card.addEventListener('click', function() {
+            var group = card.dataset.filterGroup;
+            var value = card.dataset.filterValue;
+            var select = group === 'strategy' ? fs : fst;
+            select.value = select.value === value ? '' : value;
+            apply();
+          });
+        })(summaryCards[i]);
+      }
+    })();
+  </script>
+</body>
+</html>
+`;
+}