@autobest-ui/agent 1.0.10 → 1.0.11

package/plugins/autobest-delivery/mcp-server/src/fast-runner.mjs

@@ -0,0 +1,470 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveArtifactPath, resolveWorkspaceOutputPaths } from './paths.mjs';
+
+const fastSessions = new Map();
+const requirementIdPattern = /^REQ-[A-Z][A-Z0-9]{1,15}-\d{3}$/;
+const reportGroupPattern = /^[a-z0-9][a-z0-9._-]*$/;
+const captureNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.png$/;
+const defaultBrowserRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '.runtime',
+  'ms-playwright'
+);
+process.env.PLAYWRIGHT_BROWSERS_PATH =
+  process.env.AUTOBEST_DELIVERY_BROWSERS_PATH || defaultBrowserRoot;
+
+async function loadPlaywright() {
+  return import('@playwright/test');
+}
+
+function errorDetail(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function toEvidencePath(root, absolutePath) {
+  return path.relative(root, absolutePath).split(path.sep).join('/');
+}
+
+async function sha256(filePath) {
+  const content = await fs.readFile(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function requireSession(sessionId) {
+  const session = fastSessions.get(sessionId);
+  if (!session) throw new Error(`快速验收会话不存在或已结束：${sessionId}`);
+  return session;
+}
+
+function validateReportFields(input) {
+  for (const field of ['reportModule', 'reportGroup', 'reportTitle', 'reportMethod']) {
+    if (typeof input[field] !== 'string' || !input[field].trim()) {
+      throw new TypeError(`${field} 必须是非空字符串`);
+    }
+  }
+  if (!reportGroupPattern.test(input.reportGroup)) {
+    throw new TypeError('reportGroup 必须是稳定的 ASCII ID');
+  }
+  if (input.requirementId && !requirementIdPattern.test(input.requirementId)) {
+    throw new TypeError(`无效需求 ID：${input.requirementId}`);
+  }
+}
+
+function validateRequirement(session, requirementId) {
+  if (!requirementId || session.requirementIds.size === 0) return;
+  if (!session.requirementIds.has(requirementId)) {
+    throw new TypeError(`引用了未声明的需求 ID：${requirementId}`);
+  }
+}
+
+async function closeSession(session) {
+  clearTimeout(session.timeoutId);
+  await session.context?.close().catch(() => undefined);
+  await session.browser?.close().catch(() => undefined);
+}
+
+function installPageEvidence(session, page) {
+  page.on('console', message => {
+    if (message.type() === 'error') session.consoleErrors.push(message.text());
+  });
+  page.on('requestfailed', request => {
+    session.networkFailures.push({
+      url: request.url(),
+      method: request.method(),
+      errorText: request.failure()?.errorText || 'unknown'
+    });
+  });
+  page.on('response', response => {
+    const request = response.request();
+    session.apiCalls.push({
+      url: response.url(),
+      method: request.method(),
+      status: response.status()
+    });
+  });
+}
+
+export async function startFastCheck({
+  workspaceRoot,
+  baseUrl,
+  outputDir,
+  apiMode = 'none',
+  iteration = 1,
+  headed = false,
+  viewport = { width: 1400, height: 1000 },
+  requirementIds = [],
+  sessionTtlMs = 3600000
+}) {
+  if (requirementIds.some(requirementId => !requirementIdPattern.test(requirementId))) {
+    throw new TypeError('requirementIds 包含格式错误的需求 ID');
+  }
+  if (new Set(requirementIds).size !== requirementIds.length) {
+    throw new TypeError('requirementIds 不得重复');
+  }
+  const { root, output } = await resolveWorkspaceOutputPaths({ workspaceRoot, outputDir });
+  const { chromium } = await loadPlaywright();
+  const browser = await chromium.launch({ headless: !headed });
+  const context = await browser.newContext({ viewport });
+  await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
+  const page = await context.newPage();
+  const sessionId = crypto.randomUUID();
+  const session = {
+    sessionId,
+    root,
+    output,
+    baseUrl,
+    apiMode,
+    iteration,
+    headed,
+    viewport,
+    browser,
+    context,
+    page,
+    requirementIds: new Set(requirementIds),
+    checks: [],
+    captures: [],
+    actions: [],
+    apiCalls: [],
+    consoleErrors: [],
+    networkFailures: [],
+    blockers: [],
+    startedAt: new Date().toISOString()
+  };
+  installPageEvidence(session, page);
+  session.timeoutId = setTimeout(async () => {
+    fastSessions.delete(sessionId);
+    await closeSession(session);
+  }, sessionTtlMs);
+  session.timeoutId.unref?.();
+  fastSessions.set(sessionId, session);
+  try {
+    await page.goto(baseUrl);
+    session.actions.push({ action: 'navigate', url: page.url(), success: true });
+  } catch (error) {
+    session.actions.push({ action: 'navigate', url: baseUrl, success: false, error: errorDetail(error) });
+  }
+  return {
+    sessionId,
+    url: page.url(),
+    title: await page.title().catch(() => ''),
+    browserMode: headed ? 'headed' : 'headless',
+    outputDir: toEvidencePath(root, output),
+    expiresInMs: sessionTtlMs
+  };
+}
+
+export async function fastBrowserSnapshot({ sessionId, timeoutMs = 10000 }) {
+  const session = requireSession(sessionId);
+  const snapshot = await session.page.locator('body').ariaSnapshot({ timeout: timeoutMs });
+  return {
+    sessionId,
+    url: session.page.url(),
+    title: await session.page.title(),
+    snapshot: snapshot.slice(0, 30000)
+  };
+}
+
+export async function fastBrowserAction({
+  sessionId,
+  action,
+  locator,
+  value,
+  url,
+  width,
+  height,
+  timeoutMs = 10000
+}) {
+  const session = requireSession(sessionId);
+  const page = session.page;
+  try {
+    if (['click', 'fill', 'select', 'press', 'wait'].includes(action) && !locator) {
+      throw new TypeError(`${action} 操作必须提供 locator`);
+    }
+    if (action === 'viewport' && (!width || !height)) {
+      throw new TypeError('viewport 操作必须提供 width 和 height');
+    }
+    if (action === 'navigate') {
+      await page.goto(new URL(url || session.baseUrl, session.baseUrl).toString(), { timeout: timeoutMs });
+    } else if (action === 'click') {
+      await page.locator(locator).click({ timeout: timeoutMs });
+    } else if (action === 'fill') {
+      await page.locator(locator).fill(value ?? '', { timeout: timeoutMs });
+    } else if (action === 'select') {
+      await page.locator(locator).selectOption(value ?? '', { timeout: timeoutMs });
+    } else if (action === 'press') {
+      await page.locator(locator).press(value ?? '', { timeout: timeoutMs });
+    } else if (action === 'wait') {
+      await page.locator(locator).waitFor({ state: 'visible', timeout: timeoutMs });
+    } else if (action === 'viewport') {
+      await page.setViewportSize({ width, height });
+      session.viewport = { width, height };
+    } else {
+      throw new TypeError(`不支持的快速浏览器操作：${action}`);
+    }
+    const result = { action, locator: locator || null, value: value ?? null, url: page.url(), success: true };
+    session.actions.push(result);
+    return { sessionId, ...result };
+  } catch (error) {
+    const result = {
+      action,
+      locator: locator || null,
+      value: value ?? null,
+      url: page.url(),
+      success: false,
+      error: errorDetail(error)
+    };
+    session.actions.push(result);
+    return { sessionId, ...result };
+  }
+}
+
+export async function mockFastCheckRoute({ sessionId, method = 'GET', pathname, status = 200, body = {} }) {
+  const session = requireSession(sessionId);
+  if (session.apiMode !== 'mock') throw new Error('只有 mock 模式可以安装请求响应');
+  await session.page.route(`**${pathname}`, async route => {
+    if (route.request().method() !== method) return route.fallback();
+    await route.fulfill({ status, contentType: 'application/json', body: JSON.stringify(body) });
+  });
+  return { sessionId, method, pathname, status, success: true };
+}
+
+async function evaluateCheck(session, input) {
+  const page = session.page;
+  const target = input.locator ? page.locator(input.locator) : null;
+  if (input.checkType !== 'url' && !target) {
+    throw new TypeError(`${input.checkType} 检查必须提供 locator`);
+  }
+  if (['text', 'value', 'url', 'attribute', 'css'].includes(input.checkType) && typeof input.expected !== 'string') {
+    throw new TypeError(`${input.checkType} 检查必须提供 expected`);
+  }
+  if (input.checkType === 'count' && !Number.isInteger(input.expectedNumber)) {
+    throw new TypeError('count 检查必须提供 expectedNumber');
+  }
+  if (['attribute', 'css'].includes(input.checkType) && !input.property) {
+    throw new TypeError(`${input.checkType} 检查必须提供 property`);
+  }
+  if (input.checkType === 'visible') return target.isVisible({ timeout: input.timeoutMs });
+  if (input.checkType === 'hidden') return !(await target.isVisible({ timeout: input.timeoutMs }));
+  if (input.checkType === 'text') {
+    const actual = (await target.textContent({ timeout: input.timeoutMs })) || '';
+    return { actual, isPass: input.exact ? actual.trim() === input.expected : actual.includes(input.expected) };
+  }
+  if (input.checkType === 'value') {
+    const actual = await target.inputValue({ timeout: input.timeoutMs });
+    return { actual, isPass: actual === input.expected };
+  }
+  if (input.checkType === 'count') {
+    const actual = await target.count();
+    return { actual, isPass: actual === input.expectedNumber };
+  }
+  if (input.checkType === 'url') {
+    const actual = page.url();
+    return { actual, isPass: input.exact ? actual === input.expected : actual.includes(input.expected) };
+  }
+  if (input.checkType === 'attribute') {
+    const actual = await target.getAttribute(input.property, { timeout: input.timeoutMs });
+    return { actual, isPass: actual === input.expected };
+  }
+  if (input.checkType === 'css') {
+    const actual = await target.evaluate((element, property) => getComputedStyle(element).getPropertyValue(property), input.property);
+    return { actual, isPass: actual.trim() === input.expected };
+  }
+  throw new TypeError(`不支持的检查类型：${input.checkType}`);
+}
+
+export async function fastBrowserCheck(input) {
+  const session = requireSession(input.sessionId);
+  validateReportFields(input);
+  validateRequirement(session, input.requirementId);
+  if (session.checks.some(check => check.id === input.id)) {
+    throw new TypeError(`检查 ID 不得重复：${input.id}`);
+  }
+  let actual;
+  let isPass;
+  try {
+    const evaluated = await evaluateCheck(session, input);
+    if (typeof evaluated === 'boolean') {
+      actual = evaluated ? '条件满足' : '条件不满足';
+      isPass = evaluated;
+    } else {
+      actual = evaluated.actual;
+      isPass = evaluated.isPass;
+    }
+  } catch (error) {
+    actual = errorDetail(error);
+    isPass = false;
+  }
+  const check = {
+    id: input.id,
+    requirementId: input.requirementId || null,
+    specSnippet: input.specSnippet,
+    reportModule: input.reportModule,
+    reportGroup: input.reportGroup,
+    reportTitle: input.reportTitle,
+    reportMethod: input.reportMethod,
+    checkType: input.checkType,
+    locator: input.locator || null,
+    expect: input.expect,
+    actual: actual === null || actual === undefined ? '' : String(actual),
+    isPass
+  };
+  session.checks.push(check);
+  return { sessionId: input.sessionId, check };
+}
+
+export async function captureFastCheck(input) {
+  const session = requireSession(input.sessionId);
+  validateReportFields(input);
+  validateRequirement(session, input.requirementId);
+  if (!captureNamePattern.test(input.capture)) {
+    throw new TypeError('capture 必须是简单的 PNG 文件名');
+  }
+  if (!['desktop', 'mobile'].includes(input.reportDevice)) {
+    throw new TypeError('reportDevice 必须是 desktop 或 mobile');
+  }
+  if (session.captures.some(capture => capture.capture === input.capture)) {
+    throw new TypeError(`截图文件名不得重复：${input.capture}`);
+  }
+  const capturePath = resolveArtifactPath(session.output, path.join('captures', input.capture));
+  await fs.mkdir(path.dirname(capturePath), { recursive: true });
+  if (input.locator) {
+    await session.page.locator(input.locator).screenshot({ path: capturePath });
+  } else {
+    await session.page.screenshot({ path: capturePath, fullPage: input.fullPage !== false });
+  }
+  const evidencePath = toEvidencePath(session.root, capturePath);
+  const capture = {
+    requirementId: input.requirementId || null,
+    capture: input.capture,
+    locator: input.locator || 'page',
+    reportModule: input.reportModule,
+    reportGroup: input.reportGroup,
+    reportTitle: input.reportTitle,
+    reportMethod: input.reportMethod,
+    reportDevice: input.reportDevice,
+    path: evidencePath,
+    sha256: await sha256(capturePath)
+  };
+  session.captures.push(capture);
+  return { sessionId: input.sessionId, capture };
+}
+
+function fastResultMarkdown(result) {
+  const lines = [
+    '# 快速 Playwright 自测结果',
+    '',
+    `- 状态：${result.status}`,
+    `- 证据来源：交互式 Playwright 自测`,
+    `- 迭代：${result.iteration}`,
+    `- API 模式：${result.apiMode}`,
+    '',
+    '## 检查结果',
+    '',
+    '| 检查 | 预期 | 实际 | 状态 |',
+    '| --- | --- | --- | --- |',
+    ...result.checks.map(check =>
+      `| ${check.reportTitle} | ${check.expect} | ${String(check.actual).replaceAll('|', '\\|')} | ${check.isPass ? '通过' : '不通过'} |`
+    ),
+    '',
+    '## 截图',
+    '',
+    ...result.captureRecords.map(capture => `- ${capture.reportTitle}（${capture.reportDevice}）：${capture.path}`),
+    ''
+  ];
+  return lines.join('\n');
+}
+
+export async function finishFastCheck({ sessionId }) {
+  const session = requireSession(sessionId);
+  fastSessions.delete(sessionId);
+  const tracePath = resolveArtifactPath(session.output, 'trace.zip');
+  try {
+    await session.context.tracing.stop({ path: tracePath });
+  } catch (error) {
+    session.blockers.push({ kind: 'trace', detail: errorDetail(error) });
+  }
+  if (session.checks.length === 0) session.blockers.push({ kind: 'evidence', detail: '没有记录检查项' });
+  if (session.captures.length === 0) session.blockers.push({ kind: 'evidence', detail: '没有记录报告截图' });
+  const coveredRequirementIds = new Set(
+    session.checks.map(check => check.requirementId).filter(Boolean)
+  );
+  for (const requirementId of session.requirementIds) {
+    if (!coveredRequirementIds.has(requirementId)) {
+      session.blockers.push({ kind: 'traceability', detail: `需求 ${requirementId} 没有检查证据` });
+    }
+  }
+  const capturedGroups = new Set(session.captures.map(capture => capture.reportGroup));
+  for (const reportGroup of new Set(session.checks.map(check => check.reportGroup))) {
+    if (!capturedGroups.has(reportGroup)) {
+      session.blockers.push({ kind: 'report-capture', detail: `报告功能组 ${reportGroup} 没有截图` });
+    }
+  }
+  const status = session.blockers.length > 0
+    ? 'blocked'
+    : session.checks.some(check => !check.isPass) ? 'failed' : 'passed';
+  const resultPath = resolveArtifactPath(session.output, 'fast-check-result.json');
+  const markdownPath = resolveArtifactPath(session.output, 'fast-check-result.md');
+  const result = {
+    evidenceSchemaVersion: 1,
+    evidenceSource: 'interactive-playwright',
+    status,
+    iteration: session.iteration,
+    scenarioPath: null,
+    scenarioSha256: null,
+    metadata: {
+      apiMode: session.apiMode,
+      requirementIds: [...session.requirementIds],
+      reportCaptures: session.captures.map(({ path: _path, sha256: _sha256, ...capture }) => capture),
+      visualMappings: []
+    },
+    apiMode: session.apiMode,
+    apiCalls: session.apiCalls,
+    checks: session.checks,
+    captures: session.captures.map(capture => capture.path),
+    captureRecords: session.captures,
+    actions: session.actions,
+    tracePath: session.blockers.some(blocker => blocker.kind === 'trace') ? null : toEvidencePath(session.root, tracePath),
+    consoleErrors: session.consoleErrors,
+    networkFailures: session.networkFailures,
+    blockers: session.blockers,
+    browserMode: session.headed ? 'headed' : 'headless',
+    startedAt: session.startedAt,
+    finishedAt: new Date().toISOString(),
+    resultPath: toEvidencePath(session.root, resultPath)
+  };
+  try {
+    await writeJson(resultPath, result);
+    await fs.writeFile(markdownPath, fastResultMarkdown(result), 'utf8');
+    return { ...result, markdownPath: toEvidencePath(session.root, markdownPath) };
+  } finally {
+    await closeSession(session);
+  }
+}
+
+export async function abortFastCheck({ sessionId }) {
+  const session = fastSessions.get(sessionId);
+  if (!session) return { status: 'not-found', sessionId };
+  fastSessions.delete(sessionId);
+  await closeSession(session);
+  return { status: 'aborted', sessionId };
+}
+
+export async function closeAllFastChecks() {
+  const sessions = [...fastSessions.values()];
+  fastSessions.clear();
+  await Promise.all(sessions.map(closeSession));
+}
+
+export function activeFastCheckCount() {
+  return fastSessions.size;
+}

package/plugins/autobest-delivery/mcp-server/src/paths.mjs

@@ -13,14 +13,9 @@ function isInside(root, target) {
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
 
-export async function resolveWorkspacePaths({ workspaceRoot, scenarioPath, outputDir }) {
+export async function resolveWorkspaceOutputPaths({ workspaceRoot, outputDir }) {
   const root = await fs.realpath(path.resolve(workspaceRoot));
-  const scenario = await fs.realpath(path.resolve(root, scenarioPath));
   const output = path.resolve(root, outputDir);
-
-  if (!isInside(root, scenario)) {
-    throw new PathPolicyError('scenarioPath 必须位于 workspaceRoot 内');
-  }
   if (!isInside(root, output)) {
     throw new PathPolicyError('outputDir 必须位于 workspaceRoot 内');
   }
@@ -30,8 +25,18 @@ export async function resolveWorkspacePaths({ workspaceRoot, scenarioPath, outpu
   if (!isInside(root, realOutput)) {
     throw new PathPolicyError('outputDir 解析后的路径位于 workspaceRoot 外');
   }
+  return { root, output: realOutput };
+}
 
-  return { root, scenario, output: realOutput };
+export async function resolveWorkspacePaths({ workspaceRoot, scenarioPath, outputDir }) {
+  const root = await fs.realpath(path.resolve(workspaceRoot));
+  const scenario = await fs.realpath(path.resolve(root, scenarioPath));
+
+  if (!isInside(root, scenario)) {
+    throw new PathPolicyError('scenarioPath 必须位于 workspaceRoot 内');
+  }
+  const resolved = await resolveWorkspaceOutputPaths({ workspaceRoot: root, outputDir });
+  return { root, scenario, output: resolved.output };
 }
 
 export function resolveArtifactPath(outputDir, relativePath) {

package/plugins/autobest-delivery/mcp-server/src/report.mjs

@@ -135,6 +135,27 @@ async function findLatestRunnerResult(featureDir) {
   return null;
 }
 
+async function findLatestFastCheckResult(featureDir) {
+  const runsDir = path.join(featureDir, 'fast-check', 'runs');
+  let entries;
+  try {
+    entries = await readdir(runsDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const candidates = entries
+    .filter(entry => entry.isDirectory() && /^iteration-\d+$/.test(entry.name))
+    .map(entry => ({
+      iteration: Number(entry.name.slice('iteration-'.length)),
+      filePath: path.join(runsDir, entry.name, 'fast-check-result.json')
+    }))
+    .sort((left, right) => right.iteration - left.iteration);
+  for (const candidate of candidates) {
+    if (await fileExists(candidate.filePath)) return candidate.filePath;
+  }
+  return null;
+}
+
 async function selectRunnerResult(checker, context) {
   if (checker.runnerResult) {
     const declared = resolveEvidencePath(checker.runnerResult, context);
@@ -249,7 +270,7 @@ function resolveApiMode(runner) {
   const resultMode = nonEmptyString(runner.apiMode);
   const metadataMode = nonEmptyString(runner.metadata?.apiMode);
   for (const mode of [resultMode, metadataMode].filter(Boolean)) {
-    if (!['real', 'mock'].includes(mode)) {
+    if (!['real', 'mock', 'none'].includes(mode)) {
       throw new Error(`Runner 包含无效 apiMode：${mode}`);
     }
   }
@@ -267,6 +288,9 @@ function reportMethodWithApiMode(group, apiMode) {
   if (apiMode === 'mock') {
     return `API 数据：模拟 API。\n${method}`;
   }
+  if (apiMode === 'none') {
+    return `API 数据：本次未指定业务 API。\n${method}`;
+  }
   return method;
 }
 
@@ -560,16 +584,35 @@ export async function exportDeliveryReport(options) {
   if (!(await fileExists(specPath))) {
     throw new Error(`缺少 spec.md：${specPath}`);
   }
-  if (!(await fileExists(checkerPath))) {
-    throw new Error(`缺少 Checker 结果：${checkerPath}`);
-  }
   const specText = await readFile(specPath, 'utf8');
-  const checker = await readJson(checkerPath, 'Checker 结果');
-  const runnerPath = await selectRunnerResult(checker, context);
-  if (!runnerPath) {
-    throw new Error(`缺少 Runner 结果：${path.join(featureDir, 'e2e', 'runs')}`);
+  let checker;
+  let runnerPath;
+  let evidenceSource;
+  if (await fileExists(checkerPath)) {
+    checker = await readJson(checkerPath, 'Checker 结果');
+    runnerPath = await selectRunnerResult(checker, context);
+    evidenceSource = 'independent-checker';
+    if (!runnerPath) {
+      throw new Error(`缺少 Runner 结果：${path.join(featureDir, 'e2e', 'runs')}`);
+    }
+  } else {
+    runnerPath = await findLatestFastCheckResult(featureDir);
+    if (!runnerPath) {
+      throw new Error(`缺少 Checker 或快速自测结果：${checkerPath}`);
+    }
+    const fastResult = await readJson(runnerPath, '快速自测结果');
+    if (fastResult.evidenceSource !== 'interactive-playwright') {
+      throw new Error(`快速自测结果包含无效 evidenceSource：${fastResult.evidenceSource}`);
+    }
+    checker = {
+      status: fastResult.status,
+      iteration: fastResult.iteration,
+      scenarioSha256: null,
+      checks: []
+    };
+    evidenceSource = 'interactive-playwright';
   }
-  const runner = await readJson(runnerPath, 'Runner 结果');
+  const runner = await readJson(runnerPath, evidenceSource === 'interactive-playwright' ? '快速自测结果' : 'Runner 结果');
   const apiMode = resolveApiMode(runner);
   const checks = mergeChecks(checker, runner);
   const stories = parseSpecItems(specText, checks);
@@ -649,14 +692,16 @@ export async function exportDeliveryReport(options) {
   return {
     outputPath,
     iteration: runner.iteration ?? checker.iteration ?? null,
-    checkerStatus: checker.status,
-    runnerStatus: runner.status,
+    checkerStatus: evidenceSource === 'independent-checker' ? checker.status : null,
+    runnerStatus: evidenceSource === 'independent-checker' ? runner.status : null,
+    fastCheckStatus: evidenceSource === 'interactive-playwright' ? runner.status : null,
     rows: groups.length,
     statuses: counts,
     embeddedScreenshots,
     screenshotPlacements,
     groupingSource: grouping.source,
     groupingPath: grouping.groupingPath,
-    apiMode
+    apiMode,
+    evidenceSource
   };
 }