@autobest-ui/agent 1.0.11 → 1.0.13

package/mcp/trace-mcp-recorder/index.js

@@ -0,0 +1,594 @@
+#!/usr/bin/env node
+
+import { createReadStream, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import axios from 'axios';
+import FormData from 'form-data';
+import { chromium } from 'playwright';
+import { PNG } from 'pngjs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const DEFAULT_MAX_RECORD_DURATION = 1_800_000;
+const VISUAL_PROBE_INTERVAL = 500;
+const VISUAL_DIFF_THRESHOLD = 0.005;
+const VISUAL_DEBOUNCE_DELAY = 800;
+const VISUAL_MAX_PENDING_DELAY = 3_000;
+const directory = path.dirname(fileURLToPath(import.meta.url));
+
+function readConfiguration(environment = process.env) {
+  const configuredBaseUrl = environment.BACKEND_BASE_URL?.trim();
+  if (!configuredBaseUrl) {
+    throw new Error('BACKEND_BASE_URL 未配置，无法创建录制会话');
+  }
+
+  let baseUrl;
+  try {
+    baseUrl = new URL(configuredBaseUrl);
+  } catch {
+    throw new Error('BACKEND_BASE_URL 必须是有效的 URL');
+  }
+  if (!['http:', 'https:'].includes(baseUrl.protocol)) {
+    throw new Error('BACKEND_BASE_URL 必须使用 http 或 https 协议');
+  }
+
+  const durationText = environment.MAX_RECORD_DURATION ?? String(DEFAULT_MAX_RECORD_DURATION);
+  const maxRecordDuration = Number(durationText);
+  if (!Number.isSafeInteger(maxRecordDuration) || maxRecordDuration <= 0) {
+    throw new Error('MAX_RECORD_DURATION 必须是正整数毫秒值');
+  }
+
+  return {
+    baseUrl: baseUrl.toString().replace(/\/$/, ''),
+    maxRecordDuration
+  };
+}
+
+function validateTargetUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('url 必须是有效的网页地址');
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('url 必须使用 http 或 https 协议');
+  }
+  return url.toString();
+}
+
+function optionalTrimmed(value) {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+/** Prefer authenticated/request MCP identity data, then the explicit tool argument. */
+function resolveOperator(extra, suppliedOperator) {
+  const authExtra = extra?.authInfo?.extra;
+  const requestMeta = extra?._meta;
+  const candidates = [
+    authExtra?.operator,
+    authExtra?.name,
+    authExtra?.preferred_username,
+    requestMeta?.operator,
+    requestMeta?.user?.name,
+    suppliedOperator
+  ];
+  return candidates.find(value => typeof value === 'string' && value.trim())?.trim();
+}
+
+function errorMessage(error) {
+  if (axios.isAxiosError(error)) {
+    const responseData = error.response?.data;
+    const details =
+      typeof responseData === 'string' ? responseData : responseData ? JSON.stringify(responseData) : error.message;
+    return `后端请求失败${error.response?.status ? ` (HTTP ${error.response.status})` : ''}: ${details}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+function toolText(payload) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }]
+  };
+}
+
+function toolError(error) {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: errorMessage(error) }]
+  };
+}
+
+// Compare decoded PNG pixels. A small tolerance avoids frames caused only by
+// anti-aliasing noise being written to the Trace.
+export function pixelDifference(previousBuffer, currentBuffer, channelTolerance = 12) {
+  if (!previousBuffer || !currentBuffer) return 1;
+  try {
+    const previous = PNG.sync.read(previousBuffer);
+    const current = PNG.sync.read(currentBuffer);
+    if (previous.width !== current.width || previous.height !== current.height) return 1;
+    const pixelCount = previous.width * previous.height;
+    let changedPixels = 0;
+    for (let offset = 0; offset < previous.data.length; offset += 4) {
+      if (
+        Math.abs(previous.data[offset] - current.data[offset]) > channelTolerance ||
+        Math.abs(previous.data[offset + 1] - current.data[offset + 1]) > channelTolerance ||
+        Math.abs(previous.data[offset + 2] - current.data[offset + 2]) > channelTolerance ||
+        Math.abs(previous.data[offset + 3] - current.data[offset + 3]) > channelTolerance
+      ) {
+        changedPixels += 1;
+      }
+    }
+    return changedPixels / pixelCount;
+  } catch {
+    return 1;
+  }
+}
+
+export class TraceRecorder {
+  constructor(options = {}) {
+    this.environment = options.environment ?? process.env;
+    this.launchChromium = options.launchChromium ?? (launchOptions => chromium.launch(launchOptions));
+    this.createHttpClient =
+      options.createHttpClient ??
+      (baseURL =>
+        axios.create({
+          baseURL,
+          timeout: 120_000,
+          maxBodyLength: Infinity,
+          maxContentLength: Infinity
+        }));
+    this.createFormData = options.createFormData ?? (() => new FormData());
+    this.createReadStream = options.createReadStream ?? createReadStream;
+    this.makeTemporaryDirectory =
+      options.makeTemporaryDirectory ?? (() => mkdtemp(path.join(os.tmpdir(), 'trace-mcp-recorder-')));
+    this.removeTemporaryDirectory =
+      options.removeTemporaryDirectory ?? (temporaryDirectory => rm(temporaryDirectory, { recursive: true, force: true }));
+    this.setTimer = options.setTimer ?? setTimeout;
+    this.clearTimer = options.clearTimer ?? clearTimeout;
+    this.setInterval = options.setInterval ?? setInterval;
+    this.clearInterval = options.clearInterval ?? clearInterval;
+    this.visualProbeInterval = options.visualProbeInterval ?? VISUAL_PROBE_INTERVAL;
+    this.visualDiffThreshold = options.visualDiffThreshold ?? VISUAL_DIFF_THRESHOLD;
+    this.visualDebounceDelay = options.visualDebounceDelay ?? VISUAL_DEBOUNCE_DELAY;
+    this.visualMaxPendingDelay = options.visualMaxPendingDelay ?? VISUAL_MAX_PENDING_DELAY;
+    this.platformInfo = options.platformInfo ?? (() => ({
+      platform: os.platform(),
+      type: os.type(),
+      release: os.release(),
+      architecture: os.arch()
+    }));
+    this.activeSession = undefined;
+    this.lastAutomaticResult = undefined;
+    this.lastAutomaticError = undefined;
+  }
+
+  async start(input, extra = {}) {
+    if (this.activeSession) {
+      throw new Error(`已有录制任务正在运行 (uuid: ${this.activeSession.uuid})，请先停止当前录制`);
+    }
+
+    const configuration = readConfiguration(this.environment);
+    const targetUrl = validateTargetUrl(input.url.trim());
+    const sessionInput = {
+      url: targetUrl,
+      version: optionalTrimmed(input.version),
+      title: optionalTrimmed(input.title),
+      operator: resolveOperator(extra, input.operator)
+    };
+    const reservation = { uuid: 'pending', state: 'starting' };
+    this.activeSession = reservation;
+    this.lastAutomaticResult = undefined;
+    this.lastAutomaticError = undefined;
+    let temporaryDirectory;
+    let browser;
+    let context;
+    let page;
+
+    try {
+      temporaryDirectory = await this.makeTemporaryDirectory();
+      browser = await this.launchChromium({ headless: false });
+      context = await browser.newContext();
+      await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+      page = await context.newPage();
+      await page.goto(targetUrl);
+
+      const metadata = {
+        version: sessionInput.version,
+        title: sessionInput.title,
+        operator: sessionInput.operator,
+        targetUrl,
+        browserName: 'Chromium',
+        browserVersion: browser.version(),
+        userAgent: await page.evaluate(() => navigator.userAgent),
+        viewport: page.viewportSize(),
+        operatingSystem: this.platformInfo(),
+        startedAt: new Date().toISOString()
+      };
+      const session = {
+        browser,
+        context,
+        page,
+        metadata,
+        baseUrl: configuration.baseUrl,
+        tracePath: path.join(temporaryDirectory, 'trace.zip'),
+        temporaryDirectory,
+        state: 'recording',
+        stopPromise: undefined,
+        uploadPromise: undefined,
+        timer: undefined,
+        visualProbeTimer: undefined,
+        visualProbePromise: undefined,
+        visualDebounceTimer: undefined,
+        visualRecordPromise: undefined,
+        visualPendingSince: undefined,
+        cdpSession: undefined,
+        previousProbeFrame: undefined,
+        lastRecordedFrameAt: Date.now()
+      };
+      this.activeSession = session;
+      await this.startVisualCapture(session);
+
+      const failOnBrowserExit = () => {
+        if (session.state === 'recording') {
+          session.stopPromise = this.failSession(session, new Error('Chromium 浏览器意外退出'));
+          void session.stopPromise.catch(failure => {
+            console.error('[trace-mcp-recorder] 浏览器异常退出:', errorMessage(failure));
+          });
+        }
+      };
+      browser.once('disconnected', failOnBrowserExit);
+      session.timer = this.setTimer(() => {
+        void this.stop({ trigger: 'timeout', confirm: 'upload' }).catch(error => {
+          this.lastAutomaticError = error;
+          console.error('[trace-mcp-recorder] 自动停止录制失败:', errorMessage(error));
+        });
+      }, configuration.maxRecordDuration);
+      session.timer?.unref?.();
+
+      return {
+        message: '浏览器已打开，请手动操作页面，完成后调用 stop_trace_recording',
+        maxRecordDuration: configuration.maxRecordDuration,
+        metadata
+      };
+    } catch (error) {
+      await this.closeResources({ browser, context, page, temporaryDirectory });
+      if (this.activeSession === reservation) {
+        this.activeSession = undefined;
+      }
+      throw error;
+    }
+  }
+
+  async stop({ trigger = 'manual', confirm } = {}) {
+    const session = this.activeSession;
+    if (!session) {
+      if (trigger === 'manual' && this.lastAutomaticError) {
+        const error = this.lastAutomaticError;
+        this.lastAutomaticError = undefined;
+        throw error;
+      }
+      if (trigger === 'manual' && this.lastAutomaticResult) {
+        const result = this.lastAutomaticResult;
+        this.lastAutomaticResult = undefined;
+        return result;
+      }
+      throw new Error('当前没有正在录制的 trace 会话');
+    }
+    if (session.state === 'starting') {
+      throw new Error('录制会话正在启动，请等待 start_trace_recording 返回后再停止');
+    }
+    if (session.state === 'recording') {
+      if (session.stopPromise) return session.stopPromise;
+      session.state = 'stopping';
+      this.clearTimer(session.timer);
+      session.stopPromise = this.prepareSession(session).finally(() => {
+        session.stopPromise = undefined;
+      });
+      const prepared = await session.stopPromise;
+      if (trigger === 'timeout' || confirm === 'upload') return this.uploadSession(session, trigger);
+      return prepared;
+    }
+    if (session.state === 'stopping' && session.stopPromise) return session.stopPromise;
+    if (session.state === 'awaiting_upload') {
+      if (confirm === 'upload') return this.uploadSession(session, trigger);
+      if (confirm === 'cancel') return this.cancelSession(session);
+      return {
+        uuid: undefined,
+        message: 'trace.zip 已生成，是否上传录制内容并创建回放记录？请确认“上传”或“不上传”。',
+        metadata: session.metadata
+      };
+    }
+    if (session.state === 'uploading' && session.uploadPromise) return session.uploadPromise;
+    throw new Error('当前录制会话不可停止');
+  }
+
+  async prepareSession(session) {
+    try {
+      await this.stopVisualCapture(session, true);
+      await session.context.tracing.stop({ path: session.tracePath });
+      await this.closeResources({ page: session.page, context: session.context, browser: session.browser });
+      session.state = 'awaiting_upload';
+      return {
+        message: 'trace.zip 已生成，是否上传录制内容并创建回放记录？请确认“上传”或“不上传”。',
+        metadata: session.metadata
+      };
+    } catch (error) {
+      session.state = 'failed';
+      await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+      if (this.activeSession === session) this.activeSession = undefined;
+      throw error;
+    }
+  }
+
+  async startVisualCapture(session) {
+    if (typeof session.context.newCDPSession !== 'function') return;
+    session.cdpSession = await session.context.newCDPSession(session.page);
+    await session.cdpSession.send('Page.enable');
+    session.previousProbeFrame = await this.captureProbeFrame(session);
+    session.visualProbeTimer = this.setInterval(() => {
+      if (session.visualProbePromise) return;
+      session.visualProbePromise = this.probeAndRecordVisualChange(session).catch(error => {
+        if (session.state === 'recording') {
+          console.error('[trace-mcp-recorder] 画面差异探测失败:', errorMessage(error));
+        }
+      }).finally(() => {
+        session.visualProbePromise = undefined;
+      });
+    }, this.visualProbeInterval);
+    session.visualProbeTimer?.unref?.();
+  }
+
+  async captureProbeFrame(session) {
+    const result = await session.cdpSession.send('Page.captureScreenshot', {
+      format: 'png',
+      fromSurface: true
+    });
+    return Buffer.from(result.data, 'base64');
+  }
+
+  async probeAndRecordVisualChange(session) {
+    const currentFrame = await this.captureProbeFrame(session);
+    const difference = pixelDifference(session.previousProbeFrame, currentFrame);
+    session.previousProbeFrame = currentFrame;
+    if (difference >= this.visualDiffThreshold) {
+      this.scheduleVisualRecord(session);
+    }
+  }
+
+  scheduleVisualRecord(session) {
+    const now = Date.now();
+    session.visualPendingSince ??= now;
+    if (session.visualDebounceTimer) this.clearTimer(session.visualDebounceTimer);
+    const pendingFor = now - session.visualPendingSince;
+    const delay = pendingFor >= this.visualMaxPendingDelay ? 0 : this.visualDebounceDelay;
+    session.visualDebounceTimer = this.setTimer(() => {
+      session.visualDebounceTimer = undefined;
+      session.visualRecordPromise = this.recordPendingVisual(session).finally(() => {
+        session.visualRecordPromise = undefined;
+      });
+    }, delay);
+    session.visualDebounceTimer?.unref?.();
+  }
+
+  async recordPendingVisual(session) {
+    if (session.state !== 'recording' || !session.visualPendingSince) return;
+    await session.page.screenshot();
+    session.lastRecordedFrameAt = Date.now();
+    session.visualPendingSince = undefined;
+  }
+
+  async stopVisualCapture(session, recordFinalFrame = false) {
+    if (!session.cdpSession) return;
+    if (session.visualProbeTimer) {
+      this.clearInterval(session.visualProbeTimer);
+      session.visualProbeTimer = undefined;
+    }
+    await session.visualProbePromise?.catch(() => {});
+    if (session.visualDebounceTimer) {
+      this.clearTimer(session.visualDebounceTimer);
+      session.visualDebounceTimer = undefined;
+    }
+    await session.visualRecordPromise?.catch(() => {});
+    session.visualPendingSince = undefined;
+    if (recordFinalFrame && session.page) {
+      await session.page.screenshot().catch(() => {});
+    }
+    await session.cdpSession?.detach().catch(() => {});
+    session.cdpSession = undefined;
+  }
+
+  async uploadSession(session, trigger) {
+    if (session.uploadPromise) return session.uploadPromise;
+    session.state = 'uploading';
+    session.uploadPromise = (async () => {
+      const configuration = readConfiguration(this.environment);
+      const http = this.createHttpClient(configuration.baseUrl);
+      const form = this.createFormData();
+      form.append('target_url', session.metadata.targetUrl);
+      for (const [field, value] of [
+        ['version', session.metadata.version],
+        ['title', session.metadata.title],
+        ['operator', session.metadata.operator],
+        ['browser_name', session.metadata.browserName],
+        ['browser_version', session.metadata.browserVersion],
+        ['user_agent', session.metadata.userAgent],
+        ['os_name', session.metadata.operatingSystem.platform],
+        ['viewport', JSON.stringify(session.metadata.viewport)]
+      ]) {
+        if (value !== undefined && value !== null) form.append(field, String(value));
+      }
+      form.append('trace', this.createReadStream(session.tracePath), {
+        filename: 'trace.zip',
+        contentType: 'application/zip'
+      });
+      const uploadResponse = await http.post('/api/trace-sessions', form, {
+        headers: form.getHeaders()
+      });
+      const fileUrl = uploadResponse.data?.fileUrl;
+      if (typeof fileUrl !== 'string' || !fileUrl.trim()) throw new Error('上传响应缺少 fileUrl');
+      const replayLink = `${session.baseUrl}/trace-viewer/?trace=${fileUrl}`;
+      const result = {
+        uuid: uploadResponse.data?.uuid,
+        message: `✅录制完成，回放链接：${replayLink}`,
+        replayLink,
+        fileUrl,
+        stoppedBy: trigger,
+        metadata: {
+          version: session.metadata.version,
+          title: session.metadata.title,
+          operator: session.metadata.operator,
+          browserVersion: session.metadata.browserVersion
+        }
+      };
+      session.state = 'completed';
+      if (trigger === 'timeout') this.lastAutomaticResult = result;
+      return result;
+    })().catch(async error => {
+      session.state = 'failed';
+      if (trigger === 'timeout') this.lastAutomaticError = error;
+      await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+      if (this.activeSession === session) this.activeSession = undefined;
+      throw error;
+    }).finally(async () => {
+      await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+      if (this.activeSession === session && session.state === 'completed') this.activeSession = undefined;
+    });
+    return session.uploadPromise;
+  }
+
+  async cancelSession(session) {
+    session.state = 'cancelled';
+    await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+    if (this.activeSession === session) this.activeSession = undefined;
+    return { message: '已取消上传，本地 trace.zip 已删除。' };
+  }
+
+  async failSession(session, error) {
+    if (session.state !== 'recording') return;
+    session.state = 'failed';
+    this.clearTimer(session.timer);
+    await this.stopVisualCapture(session);
+    await this.closeResources(session);
+    await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+    if (this.activeSession === session) this.activeSession = undefined;
+    throw error;
+  }
+
+  async closeResources({ browser, context, page, temporaryDirectory }) {
+    // Each cleanup step is independent so one closed/crashed Playwright object cannot block the rest.
+    await page?.close().catch(() => {});
+    await context?.close().catch(() => {});
+    await browser?.close().catch(() => {});
+    if (temporaryDirectory) await this.removeTemporaryDirectory(temporaryDirectory).catch(() => {});
+  }
+}
+
+function registerSkillResources(server) {
+  const skillPath = path.join(directory, '../../skills/common/trace-recorder/SKILL.md');
+  if (!existsSync(skillPath)) return;
+  const uri = 'skill://trace-recorder/SKILL.md';
+  server.registerResource(
+    'trace-recorder',
+    uri,
+    {
+      title: 'Skill: trace-recorder',
+      description: 'trace-mcp-recorder 的自然语言调用说明',
+      mimeType: 'text/markdown'
+    },
+    async () => ({
+      contents: [{ uri, mimeType: 'text/markdown', text: readFileSync(skillPath, 'utf8') }]
+    })
+  );
+}
+
+export function createServer(options = {}) {
+  const recorder = options.recorder ?? new TraceRecorder(options);
+  const server = new McpServer(
+    { name: 'trace-mcp-recorder', version: '1.0.0' },
+    {
+      instructions:
+        'Use start_trace_recording to open a visible Chromium window for manual testing. ' +
+        'When the user asks to stop recording, always call stop_trace_recording and return its replay link.'
+    }
+  );
+
+  server.registerTool(
+    'start_trace_recording',
+    {
+      title: '启动 Playwright Trace 人工录制',
+      description: '启动非无头 Chromium、开启 trace 并访问指定 URL，供测试人员在浏览器窗口中手动操作。',
+      inputSchema: {
+        url: z.string().min(1).describe('必填，被测页面的 HTTP(S) 地址'),
+        version: z.string().min(1).optional().describe('可选，被测版本号，例如 v2.1.0'),
+        title: z.string().min(1).optional().describe('可选，录制标题，例如登录页面'),
+        operator: z.string().min(1).optional().describe('可选，操作人；MCP 上下文中的身份优先')
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async (input, extra) => {
+      try {
+        return toolText(await recorder.start(input, extra));
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    'stop_trace_recording',
+    {
+      title: '停止 Playwright Trace 录制',
+      description: '停止当前 trace 并询问上传；确认后上传 trace.zip 和浏览器元数据，返回回放链接。',
+      inputSchema: {
+        confirm: z.enum(['upload', 'cancel']).optional().describe('首次停止不传；用户确认上传传 upload，拒绝上传传 cancel')
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async ({ confirm } = {}) => {
+      try {
+        return toolText(await recorder.stop({ confirm }));
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+
+  registerSkillResources(server);
+  return server;
+}
+
+async function main() {
+  await createServer().connect(new StdioServerTransport());
+}
+
+let isCommandEntry = false;
+if (process.argv[1]) {
+  try {
+    isCommandEntry = realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    isCommandEntry = false;
+  }
+}
+
+if (isCommandEntry) {
+  main().catch(error => {
+    console.error('[trace-mcp-recorder] 服务启动失败:', errorMessage(error));
+    process.exitCode = 1;
+  });
+}