@autobest-ui/agent 1.0.0

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

@@ -0,0 +1,489 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'node:path';
+import { resolveArtifactPath, resolveWorkspacePaths } from './paths.mjs';
+
+const serverRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const defaultBrowserRoot = path.join(serverRoot, '.runtime', 'ms-playwright');
+const blockedSessions = new Map();
+process.env.PLAYWRIGHT_BROWSERS_PATH =
+  process.env.AUTOBEST_DELIVERY_BROWSERS_PATH || defaultBrowserRoot;
+
+async function loadPlaywright() {
+  return import('@playwright/test');
+}
+
+async function sha256(filePath) {
+  const content = await fs.readFile(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+async function validateScenarioSource(filePath) {
+  const source = await fs.readFile(filePath, 'utf8');
+  const forbidden = [
+    { pattern: /(^|\n)\s*import(?:\s|\()/, label: 'import' },
+    { pattern: /\brequire\s*\(/, label: 'require' },
+    {
+      pattern: /\b(process|__dirname|__filename|globalThis)\b/,
+      label: 'Node 全局变量'
+    }
+  ];
+  const violation = forbidden.find(item => item.pattern.test(source));
+  if (violation) {
+    throw new TypeError(`冻结场景不得使用 ${violation.label}`);
+  }
+}
+
+function toEvidencePath(workspaceRoot, absolutePath) {
+  return path.relative(workspaceRoot, absolutePath).split(path.sep).join('/');
+}
+
+function errorDetail(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+async function closeBlockedSession(session) {
+  clearTimeout(session.timeoutId);
+  await session.context?.close().catch(() => undefined);
+  await session.browser?.close().catch(() => undefined);
+}
+
+function decisionEffect(decision) {
+  return {
+    retry: 'retry-checker',
+    accept: 'continue-with-waiver',
+    skip: 'continue-with-waiver',
+    implementation_defect: 'maker',
+    test_defect: 'test-author',
+    stop: 'terminal-blocked',
+    expired: 'retry-checker'
+  }[decision];
+}
+
+async function recordBlockedDecision(session, decision, note) {
+  const result = {
+    status: 'resolved',
+    sessionId: session.sessionId,
+    decision,
+    effect: decisionEffect(decision),
+    note,
+    runnerResult: session.runnerResult,
+    decidedAt: new Date().toISOString()
+  };
+  await writeJson(session.decisionPath, result);
+  return {
+    ...result,
+    decisionPath: toEvidencePath(session.root, session.decisionPath)
+  };
+}
+
+export async function resolveBlockedRun({ sessionId, decision, note = '' }) {
+  const session = blockedSessions.get(sessionId);
+  if (!session) {
+    return {
+      status: 'not-found',
+      sessionId,
+      decision,
+      effect: null,
+      note,
+      runnerResult: null,
+      decisionPath: null,
+      decidedAt: new Date().toISOString()
+    };
+  }
+
+  blockedSessions.delete(sessionId);
+  try {
+    return await recordBlockedDecision(session, decision, note);
+  } finally {
+    await closeBlockedSession(session);
+  }
+}
+
+export async function closeAllBlockedRuns() {
+  const sessions = [...blockedSessions.values()];
+  blockedSessions.clear();
+  await Promise.all(sessions.map(closeBlockedSession));
+}
+
+export function activeBlockedRunCount() {
+  return blockedSessions.size;
+}
+
+export async function checkEnvironment({ headed = false, load = loadPlaywright } = {}) {
+  const packageJson = JSON.parse(
+    await fs.readFile(path.join(serverRoot, 'package.json'), 'utf8')
+  );
+
+  try {
+    const { chromium } = await load();
+    const browser = await chromium.launch({ headless: !headed });
+    const browserVersion = browser.version();
+    await browser.close();
+    return {
+      ready: true,
+      nodeVersion: process.version,
+      runnerVersion: packageJson.version,
+      playwrightVersion: packageJson.dependencies['@playwright/test'],
+      browserMode: headed ? 'headed' : 'headless',
+      browserVersion,
+      browserPath: chromium.executablePath(),
+      browserStorage: process.env.PLAYWRIGHT_BROWSERS_PATH
+    };
+  } catch (error) {
+    return {
+      ready: false,
+      nodeVersion: process.version,
+      runnerVersion: packageJson.version,
+      playwrightVersion: packageJson.dependencies['@playwright/test'],
+      browserMode: headed ? 'headed' : 'headless',
+      browserStorage: process.env.PLAYWRIGHT_BROWSERS_PATH,
+      error: errorDetail(error)
+    };
+  }
+}
+
+export async function runFeatureE2E({
+  workspaceRoot,
+  scenarioPath,
+  baseUrl,
+  outputDir,
+  iteration = 1,
+  timeoutMs = 300000,
+  headed = false,
+  keepBrowserOpenOnBlock = false,
+  blockedSessionTtlMs = 1800000
+}) {
+  const startedAt = new Date().toISOString();
+  const { root, scenario, output } = await resolveWorkspacePaths({
+    workspaceRoot,
+    scenarioPath,
+    outputDir
+  });
+  const resultPath = resolveArtifactPath(output, 'runner-result.json');
+  const tracePath = resolveArtifactPath(output, 'trace.zip');
+  const beforeHash = await sha256(scenario);
+  const checks = [];
+  const captures = [];
+  const scenarioBlockers = [];
+  const consoleErrors = [];
+  const networkFailures = [];
+  const invokedScenes = new Set();
+  let browser;
+  let context;
+  let page;
+  let blockedPage;
+  let metadata = {};
+  let timeoutId;
+  let traceStarted = false;
+  let traceError;
+  let result;
+
+  try {
+    const { chromium, expect } = await loadPlaywright();
+    await validateScenarioSource(scenario);
+    const scenarioUrl = `${pathToFileURL(scenario).href}?sha256=${beforeHash}`;
+    const scenarioModule = await import(scenarioUrl);
+    if (typeof scenarioModule.default !== 'function') {
+      throw new TypeError('冻结场景必须导出一个默认异步函数');
+    }
+    metadata = scenarioModule.metadata || {};
+    const reportSchemaVersion = metadata.reportSchemaVersion;
+    if (reportSchemaVersion !== undefined && reportSchemaVersion !== 1) {
+      throw new TypeError('metadata.reportSchemaVersion 仅支持 1');
+    }
+    if (reportSchemaVersion === 1) {
+      for (const mapping of metadata.visualMappings || []) {
+        for (const field of ['reportModule', 'reportGroup', 'reportTitle', 'reportDevice']) {
+          if (!mapping || typeof mapping[field] !== 'string' || !mapping[field].trim()) {
+            throw new TypeError(`visualMapping 必须包含非空字符串字段 ${field}`);
+          }
+        }
+        if (!['desktop', 'mobile'].includes(mapping.reportDevice)) {
+          throw new TypeError('visualMapping.reportDevice 必须是 desktop 或 mobile');
+        }
+        if (!/^[a-z0-9][a-z0-9._-]*$/.test(mapping.reportGroup)) {
+          throw new TypeError('visualMapping.reportGroup 必须是稳定的 ASCII ID');
+        }
+      }
+    }
+
+    browser = await chromium.launch({ headless: !headed });
+    context = await browser.newContext();
+    await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+    traceStarted = true;
+    const createPage = async () => {
+      const currentPage = await context.newPage();
+      currentPage.on('console', message => {
+        if (message.type() === 'error') {
+          consoleErrors.push(message.text());
+        }
+      });
+      currentPage.on('requestfailed', request => {
+        networkFailures.push({
+          url: request.url(),
+          error: request.failure()?.errorText || '未知请求失败'
+        });
+      });
+      return currentPage;
+    };
+    page = await createPage();
+
+    const check = async (definition, assertion) => {
+      const required = ['id', 'specSnippet', 'scene', 'errorType', 'expect'];
+      if (reportSchemaVersion === 1) {
+        required.push('reportModule', 'reportGroup', 'reportTitle', 'reportMethod');
+      }
+      for (const field of required) {
+        if (!definition || typeof definition[field] !== 'string' || !definition[field].trim()) {
+          throw new TypeError(`check 定义必须包含非空字符串字段 ${field}`);
+        }
+      }
+      if (reportSchemaVersion === 1 && !/^[a-z0-9][a-z0-9._-]*$/.test(definition.reportGroup)) {
+        throw new TypeError('check.reportGroup 必须是稳定的 ASCII ID');
+      }
+      try {
+        const actual = await assertion();
+        checks.push({ ...definition, actual: actual ?? '符合预期', isPass: true });
+        return true;
+      } catch (error) {
+        checks.push({ ...definition, actual: errorDetail(error), isPass: false });
+        return false;
+      }
+    };
+
+    const capture = async (locator, filename) => {
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.png$/.test(filename)) {
+        throw new TypeError('capture 文件名必须是简单的 PNG 文件名');
+      }
+      const capturePath = resolveArtifactPath(output, path.join('captures', filename));
+      await fs.mkdir(path.dirname(capturePath), { recursive: true });
+      await locator.screenshot({ path: capturePath });
+      const evidencePath = toEvidencePath(root, capturePath);
+      captures.push(evidencePath);
+      return evidencePath;
+    };
+
+    const artifact = async (filename, value) => {
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.json$/.test(filename)) {
+        throw new TypeError('artifact 文件名必须是简单的 JSON 文件名');
+      }
+      const artifactPath = resolveArtifactPath(output, path.join('artifacts', filename));
+      await writeJson(artifactPath, value);
+      return toEvidencePath(root, artifactPath);
+    };
+
+    let scene;
+    const injectedApi = currentPage => ({
+      page: currentPage,
+      expect,
+      check,
+      scene,
+      route: (pattern, handler) => currentPage.route(pattern, handler),
+      capture,
+      artifact,
+      baseUrl,
+      parseUrl: value => new URL(value),
+      metadata
+    });
+    scene = async (sceneId, executeScene) => {
+      if (typeof sceneId !== 'string' || sceneId.length === 0) {
+        throw new TypeError('scene id 必须是非空字符串');
+      }
+      if (typeof executeScene !== 'function') {
+        throw new TypeError(`scene ${sceneId} 必须提供异步执行函数`);
+      }
+      if (invokedScenes.has(sceneId)) {
+        throw new TypeError(`scene ${sceneId} 不得重复执行`);
+      }
+      if (Array.isArray(metadata.scenes) && !metadata.scenes.includes(sceneId)) {
+        throw new TypeError(`scene ${sceneId} 未在 metadata.scenes 中声明`);
+      }
+
+      invokedScenes.add(sceneId);
+      const scenePage = await createPage();
+      try {
+        await executeScene(injectedApi(scenePage));
+        await scenePage.close();
+        return true;
+      } catch (error) {
+        scenarioBlockers.push({
+          kind: 'scenario',
+          scene: sceneId,
+          detail: errorDetail(error)
+        });
+        blockedPage ||= scenePage;
+        return false;
+      }
+    };
+
+    const execute = scenarioModule.default(injectedApi(page));
+    const deadline = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        const error = new Error(`场景执行超过 ${timeoutMs}ms 超时限制`);
+        error.name = 'DeliveryTimeoutError';
+        reject(error);
+      }, timeoutMs);
+    });
+    await Promise.race([execute, deadline]);
+
+    const afterHash = await sha256(scenario);
+    if (afterHash !== beforeHash) {
+      throw new Error('冻结场景在执行过程中发生了变化');
+    }
+    if (checks.length === 0 && scenarioBlockers.length === 0) {
+      throw new Error('冻结场景执行完成，但没有记录原子检查项');
+    }
+    if (invokedScenes.size > 0 && Array.isArray(metadata.scenes)) {
+      for (const sceneId of metadata.scenes) {
+        if (!invokedScenes.has(sceneId)) {
+          scenarioBlockers.push({
+            kind: 'scenario',
+            scene: sceneId,
+            detail: `metadata.scenes 声明的 ${sceneId} 未执行`
+          });
+        }
+      }
+    }
+    if (blockedPage && !blockedPage.isClosed()) {
+      await blockedPage.bringToFront().catch(() => undefined);
+      page = blockedPage;
+    }
+
+    result = {
+      status: scenarioBlockers.length > 0
+        ? 'blocked'
+        : checks.every(item => item.isPass) ? 'passed' : 'failed',
+      iteration,
+      scenarioPath: toEvidencePath(root, scenario),
+      scenarioSha256: beforeHash,
+      metadata,
+      checks,
+      captures,
+      tracePath: toEvidencePath(root, tracePath),
+      consoleErrors,
+      networkFailures,
+      blockers: scenarioBlockers,
+      browserMode: headed ? 'headed' : 'headless',
+      blockedSessionId: null,
+      blockedSessionExpiresAt: null,
+      decisionPath: null,
+      startedAt,
+      finishedAt: new Date().toISOString()
+    };
+  } catch (error) {
+    result = {
+      status: 'blocked',
+      iteration,
+      scenarioPath: toEvidencePath(root, scenario),
+      scenarioSha256: beforeHash,
+      metadata,
+      checks,
+      captures,
+      tracePath: traceStarted ? toEvidencePath(root, tracePath) : null,
+      consoleErrors,
+      networkFailures,
+      blockers: [
+        {
+          kind: error?.name === 'DeliveryTimeoutError' ? 'environment' : 'scenario',
+          scene: 'runner',
+          detail: errorDetail(error)
+        }
+      ],
+      browserMode: headed ? 'headed' : 'headless',
+      blockedSessionId: null,
+      blockedSessionExpiresAt: null,
+      decisionPath: null,
+      startedAt,
+      finishedAt: new Date().toISOString()
+    };
+  } finally {
+    clearTimeout(timeoutId);
+    if (traceStarted && context) {
+      try {
+        await context.tracing.stop({ path: tracePath });
+      } catch (error) {
+        traceError = error;
+      }
+    }
+    const preserveBrowser =
+      result?.status === 'blocked' &&
+      keepBrowserOpenOnBlock &&
+      browser &&
+      context &&
+      page &&
+      !page.isClosed();
+
+    if (preserveBrowser) {
+      const sessionId = crypto.randomUUID();
+      const expiresAt = new Date(Date.now() + blockedSessionTtlMs).toISOString();
+      const decisionPath = resolveArtifactPath(output, 'human-decision.json');
+      const session = {
+        sessionId,
+        root,
+        browser,
+        context,
+        page,
+        decisionPath,
+        runnerResult: toEvidencePath(root, resultPath),
+        timeoutId: null
+      };
+      session.timeoutId = setTimeout(async () => {
+        if (!blockedSessions.delete(sessionId)) {
+          return;
+        }
+        await recordBlockedDecision(
+          session,
+          'expired',
+          'Blocked browser session expired before a user decision.'
+        ).catch(() => undefined);
+        await closeBlockedSession(session);
+      }, blockedSessionTtlMs);
+      session.timeoutId.unref?.();
+      blockedSessions.set(sessionId, session);
+      result.blockedSessionId = sessionId;
+      result.blockedSessionExpiresAt = expiresAt;
+      result.decisionPath = toEvidencePath(root, decisionPath);
+    } else {
+      await context?.close().catch(() => undefined);
+      await browser?.close().catch(() => undefined);
+    }
+  }
+
+  const finalHash = await sha256(scenario);
+  if (finalHash !== beforeHash) {
+    result.status = 'blocked';
+    result.blockers = [
+      {
+        kind: 'evidence',
+        scene: 'runner',
+        detail: '冻结场景的哈希在执行期间发生变化'
+      }
+    ];
+  }
+  if (traceStarted) {
+    try {
+      await fs.access(tracePath);
+    } catch (error) {
+      traceError ||= error;
+    }
+  }
+  if (traceError) {
+    result.status = 'blocked';
+    result.blockers = [
+      {
+        kind: 'evidence',
+        scene: 'runner',
+        detail: `无法完成 Trace 证据写入：${errorDetail(traceError)}`
+      }
+    ];
+  }
+  await writeJson(resultPath, result);
+  return { ...result, resultPath: toEvidencePath(root, resultPath) };
+}

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

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import {
+  checkEnvironment,
+  closeAllBlockedRuns,
+  resolveBlockedRun,
+  runFeatureE2E
+} from './runner.mjs';
+
+const server = new McpServer(
+  {
+    name: 'autobest-delivery',
+    version: '0.1.0'
+  },
+  {
+    instructions:
+      '调用 run_feature_e2e 前先调用 check_environment。headed 运行在 Blocked 时可保留浏览器，随后通过 resolve_blocked_run 记录人工决议并关闭会话。'
+  }
+);
+
+server.registerTool(
+  'check_environment',
+  {
+    title: '检查隔离 E2E 环境',
+    description:
+      '在启动交付闭环前，验证插件自带的 Playwright 运行器和 Chromium。',
+    inputSchema: {
+      headed: z.boolean().default(false)
+    },
+    outputSchema: {
+      ready: z.boolean(),
+      nodeVersion: z.string(),
+      runnerVersion: z.string(),
+      playwrightVersion: z.string(),
+      browserMode: z.enum(['headed', 'headless']),
+      browserVersion: z.string().optional(),
+      browserPath: z.string().optional(),
+      browserStorage: z.string(),
+      error: z.string().optional()
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    }
+  },
+  async input => {
+    const result = await checkEnvironment({ headed: input.headed });
+    return {
+      structuredContent: result,
+      content: [{ type: 'text', text: JSON.stringify(result) }]
+    };
+  }
+);
+
+server.registerTool(
+  'run_feature_e2e',
+  {
+    title: '执行冻结的功能 E2E 场景',
+    description:
+      '使用插件自带的 Playwright 运行器执行无依赖冻结场景；scene 隔离可在单个场景阻塞后继续执行其余场景，并在功能目录下写入结构化证据。',
+    inputSchema: {
+      workspaceRoot: z.string().min(1),
+      scenarioPath: z.string().min(1),
+      baseUrl: z.string().url(),
+      outputDir: z.string().min(1),
+      iteration: z.number().int().positive().default(1),
+      timeoutMs: z.number().int().min(1000).max(900000).default(300000),
+      headed: z.boolean().default(false),
+      keepBrowserOpenOnBlock: z.boolean().default(false),
+      blockedSessionTtlMs: z.number().int().min(60000).max(3600000).default(1800000)
+    },
+    outputSchema: {
+      status: z.enum(['passed', 'failed', 'blocked']),
+      iteration: z.number().int().positive(),
+      scenarioPath: z.string(),
+      scenarioSha256: z.string().nullable(),
+      metadata: z.record(z.string(), z.unknown()),
+      checks: z.array(z.record(z.string(), z.unknown())),
+      captures: z.array(z.string()),
+      tracePath: z.string().nullable(),
+      consoleErrors: z.array(z.string()),
+      networkFailures: z.array(z.record(z.string(), z.unknown())),
+      blockers: z.array(
+        z.object({
+          kind: z.string(),
+          scene: z.string(),
+          detail: z.string()
+        })
+      ),
+      browserMode: z.enum(['headed', 'headless']),
+      blockedSessionId: z.string().nullable(),
+      blockedSessionExpiresAt: z.string().nullable(),
+      decisionPath: z.string().nullable(),
+      resultPath: z.string().nullable(),
+      startedAt: z.string().optional(),
+      finishedAt: z.string().optional()
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: false
+    }
+  },
+  async input => {
+    try {
+      const result = await runFeatureE2E(input);
+      return {
+        structuredContent: result,
+        content: [{ type: 'text', text: JSON.stringify(result) }]
+      };
+    } catch (error) {
+      const result = {
+        status: 'blocked',
+        iteration: input.iteration,
+        scenarioPath: input.scenarioPath,
+        scenarioSha256: null,
+        metadata: {},
+        checks: [],
+        captures: [],
+        tracePath: null,
+        consoleErrors: [],
+        networkFailures: [],
+        blockers: [
+          {
+            kind: 'tool',
+            scene: 'runner',
+            detail: error instanceof Error ? error.message : String(error)
+          }
+        ],
+        browserMode: input.headed ? 'headed' : 'headless',
+        blockedSessionId: null,
+        blockedSessionExpiresAt: null,
+        decisionPath: null,
+        resultPath: null
+      };
+      return {
+        structuredContent: result,
+        content: [{ type: 'text', text: JSON.stringify(result) }]
+      };
+    }
+  }
+);
+
+server.registerTool(
+  'resolve_blocked_run',
+  {
+    title: '处理 Blocked E2E 会话',
+    description:
+      '记录用户对可见 Blocked 浏览器会话的决定并关闭会话。skip 仅接受阻塞场景的缺失证据，不会从异常语句恢复执行；其余独立 scene 已由运行器继续执行。',
+    inputSchema: {
+      sessionId: z.string().uuid(),
+      decision: z.enum([
+        'retry',
+        'accept',
+        'skip',
+        'implementation_defect',
+        'test_defect',
+        'stop'
+      ]),
+      note: z.string().max(2000).default('')
+    },
+    outputSchema: {
+      status: z.enum(['resolved', 'not-found']),
+      sessionId: z.string(),
+      decision: z.string(),
+      effect: z.string().nullable(),
+      note: z.string(),
+      runnerResult: z.string().nullable(),
+      decisionPath: z.string().nullable(),
+      decidedAt: z.string()
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: false
+    }
+  },
+  async input => {
+    const result = await resolveBlockedRun(input);
+    return {
+      structuredContent: result,
+      content: [{ type: 'text', text: JSON.stringify(result) }]
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.once(signal, async () => {
+    await closeAllBlockedRuns();
+    process.exit(0);
+  });
+}