@autobest-ui/agent 1.0.14 → 1.0.15

package/mcp/trace-mcp-recorder/README.md

@@ -1,6 +1,6 @@
 # trace-mcp-recorder
 
-`trace-mcp-recorder` 是基于 `@modelcontextprotocol/sdk` 和 `StdioServerTransport` 的 Node.js MCP Server。它打开非无头 Chromium 供测试人员手动操作，使用 Chromium CDP 在内存中探测画面差异，仅在画面发生明显变化时调用 Playwright 截图写入原生 `trace.zip`，然后上传 trace 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
+`trace-mcp-recorder` 是基于 `@modelcontextprotocol/sdk` 和 `StdioServerTransport` 的 Node.js MCP Server。它打开非无头 Chromium 供测试人员手动操作，页面加载后等待第一次真实用户操作才启动 Trace；后续用户活动经过防抖后写入轻量 Playwright Action，空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
 
 ## 安装与启动
 
@@ -43,7 +43,7 @@ npm start
 
 录制超时后服务自动停止并自动上传（无需人工确认），随后第一次人工调用 `stop_trace_recording` 会取回自动停止的结果；再调用则返回没有活动会话。
 
-画面探测默认每 500ms 执行一次，像素差异比例达到 0.5% 后进入防抖冷却；画面连续稳定 800ms 才写入一个轻量 `waitForTimeout(1)` Trace Action，持续变化超过 3 秒时强制写入一个。Trace 自带的 screenshots/snapshots 会记录这些 Action 前后的页面状态，停止录制时会补一个最终 Action。探测截图不会写入 Trace，因此静止页面和连续滚动不会产生大量重复图片。
+Trace 在第一次真实用户操作后才开始计时。连续用户操作停止 800ms 后写入一个轻量 `waitForTimeout(1)` Trace Action；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。
 
 ## 后端接口契约
 

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

@@ -8,16 +8,13 @@ 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 USER_ACTIVITY_DEBOUNCE_DELAY = 800;
+const IDLE_STOP_DELAY = 120_000;
 const directory = path.dirname(fileURLToPath(import.meta.url));
 
 function readConfiguration(environment = process.env) {
@@ -104,30 +101,18 @@ function toolError(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;
-      }
+// Only emit a signal for trusted user input. The Node side stores no action
+// details; it uses the signal to control Trace timing and debounce checkpoints.
+function createUserActivityScript() {
+  return `(() => {
+    const notify = () => Promise.resolve(globalThis.__traceRecorderUserActivity?.()).catch(() => {});
+    const options = { capture: true, passive: true };
+    for (const type of ['pointerdown', 'keydown', 'input', 'change', 'wheel', 'touchstart']) {
+      document.addEventListener(type, event => {
+        if (event.isTrusted) notify();
+      }, options);
     }
-    return changedPixels / pixelCount;
-  } catch {
-    return 1;
-  }
+  })();`;
 }
 
 export class TraceRecorder {
@@ -148,21 +133,18 @@ export class TraceRecorder {
     this.makeTemporaryDirectory =
       options.makeTemporaryDirectory ?? (() => mkdtemp(path.join(os.tmpdir(), 'trace-mcp-recorder-')));
     this.removeTemporaryDirectory =
-      options.removeTemporaryDirectory ?? (temporaryDirectory => rm(temporaryDirectory, { recursive: true, force: true }));
+      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.platformInfo =
+      options.platformInfo ??
+      (() => ({
+        platform: os.platform(),
+        type: os.type(),
+        release: os.release(),
+        architecture: os.arch()
+      }));
     this.activeSession = undefined;
     this.lastAutomaticResult = undefined;
     this.lastAutomaticError = undefined;
@@ -194,7 +176,16 @@ export class TraceRecorder {
       temporaryDirectory = await this.makeTemporaryDirectory();
       browser = await this.launchChromium({ headless: false });
       context = await browser.newContext();
-      await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+      let session;
+      if (typeof context.exposeBinding === 'function') {
+        await context.exposeBinding('__traceRecorderUserActivity', () => {
+          if (session) return this.handleUserActivity(session);
+          return undefined;
+        });
+      }
+      if (typeof context.addInitScript === 'function') {
+        await context.addInitScript({ content: createUserActivityScript() });
+      }
       page = await context.newPage();
       await page.goto(targetUrl);
 
@@ -210,32 +201,29 @@ export class TraceRecorder {
         operatingSystem: this.platformInfo(),
         startedAt: new Date().toISOString()
       };
-      const session = {
+      session = {
         browser,
         context,
         page,
         metadata,
         baseUrl: configuration.baseUrl,
+        maxRecordDuration: configuration.maxRecordDuration,
         tracePath: path.join(temporaryDirectory, 'trace.zip'),
         temporaryDirectory,
-        state: 'recording',
+        state: 'waiting_for_activity',
         stopPromise: undefined,
         uploadPromise: undefined,
         timer: undefined,
-        visualProbeTimer: undefined,
-        visualProbePromise: undefined,
-        visualDebounceTimer: undefined,
-        visualRecordPromise: undefined,
-        visualPendingSince: undefined,
-        cdpSession: undefined,
-        previousProbeFrame: undefined,
-        lastRecordedFrameAt: Date.now()
+        idleTimer: undefined,
+        activityDebounceTimer: undefined,
+        activityPromise: undefined,
+        tracingStarted: false,
+        lastActivityAt: undefined
       };
       this.activeSession = session;
-      await this.startVisualCapture(session);
 
       const failOnBrowserExit = () => {
-        if (session.state === 'recording') {
+        if (session.state === 'recording' || session.state === 'waiting_for_activity') {
           session.stopPromise = this.failSession(session, new Error('Chromium 浏览器意外退出'));
           void session.stopPromise.catch(failure => {
             console.error('[trace-mcp-recorder] 浏览器异常退出:', errorMessage(failure));
@@ -243,16 +231,9 @@ export class TraceRecorder {
         }
       };
       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',
+        message: '浏览器已打开，等待首次真实操作后开始录制；完成后调用 stop_trace_recording',
         maxRecordDuration: configuration.maxRecordDuration,
         metadata
       };
@@ -283,10 +264,17 @@ export class TraceRecorder {
     if (session.state === 'starting') {
       throw new Error('录制会话正在启动，请等待 start_trace_recording 返回后再停止');
     }
+    if (session.state === 'waiting_for_activity') {
+      await this.closeResources({ page: session.page, context: session.context, browser: session.browser });
+      if (this.activeSession === session) this.activeSession = undefined;
+      throw new Error('尚未检测到真实用户操作，未生成 trace');
+    }
     if (session.state === 'recording') {
       if (session.stopPromise) return session.stopPromise;
       session.state = 'stopping';
       this.clearTimer(session.timer);
+      this.clearTimer(session.idleTimer);
+      this.clearTimer(session.activityDebounceTimer);
       session.stopPromise = this.prepareSession(session).finally(() => {
         session.stopPromise = undefined;
       });
@@ -310,7 +298,8 @@ export class TraceRecorder {
 
   async prepareSession(session) {
     try {
-      await this.stopVisualCapture(session, true);
+      await session.activityPromise?.catch(() => {});
+      if (session.tracingStarted) await session.page.waitForTimeout(1).catch(() => {});
       await session.context.tracing.stop({ path: session.tracePath });
       await this.closeResources({ page: session.page, context: session.context, browser: session.browser });
       session.state = 'awaiting_upload';
@@ -326,84 +315,53 @@ export class TraceRecorder {
     }
   }
 
-  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;
+  async beginRecording(session) {
+    if (session.tracingStarted || session.state !== 'waiting_for_activity') return;
+    await session.context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+    session.tracingStarted = true;
+    session.state = 'recording';
+    session.lastActivityAt = Date.now();
+    session.timer = this.setTimer(() => {
+      void this.stop({ trigger: 'timeout', confirm: 'upload' }).catch(error => {
+        this.lastAutomaticError = error;
+        console.error('[trace-mcp-recorder] 自动停止录制失败:', errorMessage(error));
       });
-    }, 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');
+    }, session.maxRecordDuration);
+    session.timer?.unref?.();
+    this.armIdleTimer(session);
+    await session.page.waitForTimeout(1);
   }
 
-  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);
+  handleUserActivity(session) {
+    if (session.state === 'waiting_for_activity') {
+      if (session.activityPromise) return session.activityPromise;
+      session.activityPromise = this.beginRecording(session).catch(error => {
+        session.state = 'failed';
+        throw error;
+      });
+      return session.activityPromise;
     }
+    if (session.state !== 'recording') return undefined;
+    session.lastActivityAt = Date.now();
+    this.armIdleTimer(session);
+    if (session.activityDebounceTimer) this.clearTimer(session.activityDebounceTimer);
+    session.activityDebounceTimer = this.setTimer(() => {
+      session.activityDebounceTimer = undefined;
+      session.activityPromise = session.page.waitForTimeout(1).catch(() => {});
+    }, USER_ACTIVITY_DEBOUNCE_DELAY);
+    session.activityDebounceTimer?.unref?.();
+    return undefined;
   }
 
-  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;
+  armIdleTimer(session) {
+    this.clearTimer(session.idleTimer);
+    session.idleTimer = this.setTimer(() => {
+      void this.stop({ trigger: 'idle', confirm: 'upload' }).catch(error => {
+        this.lastAutomaticError = error;
+        console.error('[trace-mcp-recorder] 空闲自动停止失败:', errorMessage(error));
       });
-    }, delay);
-    session.visualDebounceTimer?.unref?.();
-  }
-
-  async recordPendingVisual(session) {
-    if (session.state !== 'recording' || !session.visualPendingSince) return;
-    // waitForTimeout is a traceable Playwright action. The trace screenshots and
-    // snapshots captured around it represent the changed page state, while the
-    // native Trace Viewer can advance through this action during playback.
-    await session.page.waitForTimeout(1);
-    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.waitForTimeout(1).catch(() => {});
-    }
-    await session.cdpSession?.detach().catch(() => {});
-    session.cdpSession = undefined;
+    }, IDLE_STOP_DELAY);
+    session.idleTimer?.unref?.();
   }
 
   async uploadSession(session, trigger) {
@@ -452,16 +410,18 @@ export class TraceRecorder {
       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;
-    });
+    })()
+      .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;
   }
 
@@ -473,10 +433,11 @@ export class TraceRecorder {
   }
 
   async failSession(session, error) {
-    if (session.state !== 'recording') return;
+    if (session.state !== 'recording' && session.state !== 'waiting_for_activity') return;
     session.state = 'failed';
     this.clearTimer(session.timer);
-    await this.stopVisualCapture(session);
+    this.clearTimer(session.idleTimer);
+    this.clearTimer(session.activityDebounceTimer);
     await this.closeResources(session);
     await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
     if (this.activeSession === session) this.activeSession = undefined;
@@ -554,7 +515,10 @@ export function createServer(options = {}) {
       title: '停止 Playwright Trace 录制',
       description: '停止当前 trace 并询问上传；确认后上传 trace.zip 和浏览器元数据，返回回放链接。',
       inputSchema: {
-        confirm: z.enum(['upload', 'cancel']).optional().describe('首次停止不传；用户确认上传传 upload，拒绝上传传 cancel')
+        confirm: z
+          .enum(['upload', 'cancel'])
+          .optional()
+          .describe('首次停止不传；用户确认上传传 upload，拒绝上传传 cancel')
       },
       annotations: {
         readOnlyHint: false,

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

@@ -5,21 +5,11 @@ import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { PNG } from 'pngjs';
-import { pixelDifference, TraceRecorder } from './index.js';
+import { TraceRecorder } from './index.js';
 
 const directory = path.dirname(fileURLToPath(import.meta.url));
 const sessionUuid = '123e4567-e89b-42d3-a456-426614174000';
 
-test('calculates pixel differences for visual probes', () => {
-  const first = new PNG({ width: 2, height: 1 });
-  const second = new PNG({ width: 2, height: 1 });
-  first.data.fill(255);
-  second.data.fill(255);
-  second.data[0] = 0;
-  assert.equal(pixelDifference(PNG.sync.write(first), PNG.sync.write(second)), 0.5);
-});
-
 function createFixture(options = {}) {
   const calls = [];
   const browser = new EventEmitter();
@@ -30,6 +20,7 @@ function createFixture(options = {}) {
   const page = {
     goto: async url => calls.push(['goto', url]),
     evaluate: async () => 'Fixture User Agent',
+    waitForTimeout: async duration => calls.push(['wait', duration]),
     viewportSize: () => ({ width: 1280, height: 720 }),
     close: async () => calls.push(['page-close'])
   };
@@ -78,7 +69,7 @@ function createFixture(options = {}) {
     removeTemporaryDirectory: async temporaryDirectory => calls.push(['remove', temporaryDirectory]),
     setTimer: (callback, duration) => {
       calls.push(['timer', duration]);
-      timer.callback = callback;
+      if (duration === 1000) timer.callback = callback;
       return timer;
     },
     clearTimer: value => calls.push(['clear-timer', value]),
@@ -102,6 +93,7 @@ test('starts, records metadata, uploads, completes and cleans up one session', a
   assert.equal(started.uuid, undefined);
   assert.equal(started.metadata.operator, '上下文操作人');
   assert.equal(started.metadata.browserVersion, 'Fixture Chromium 1');
+  await recorder.handleUserActivity(recorder.activeSession);
   await assert.rejects(
     recorder.start({ url: 'https://app.example.test/another' }),
     /已有录制任务/
@@ -139,6 +131,7 @@ test('cleans up when Chromium launch fails without a backend session', async ()
 test('marks the session failed and removes the local trace when upload fails', async () => {
   const { calls, recorder } = createFixture({ uploadError: new Error('upload failed') });
   await recorder.start({ url: 'https://app.example.test' });
+  await recorder.handleUserActivity(recorder.activeSession);
 
   await recorder.stop();
   await assert.rejects(recorder.stop({ confirm: 'upload' }), /upload failed/);
@@ -148,6 +141,7 @@ test('marks the session failed and removes the local trace when upload fails', a
 test('automatically stops on timeout and returns that result on the next stop call', async () => {
   const { recorder, timer } = createFixture();
   await recorder.start({ url: 'https://app.example.test' });
+  await recorder.handleUserActivity(recorder.activeSession);
   timer.callback();
 
   while (recorder.activeSession) await new Promise(resolve => setImmediate(resolve));

package/mcp/trace-mcp-recorder/package-lock.json

@@ -12,7 +12,6 @@
         "axios": "1.20.0",
         "form-data": "4.0.6",
         "playwright": "1.63.0",
-        "pngjs": "^7.0.0",
         "uuid": "14.0.2",
         "zod": "4.4.3"
       },
@@ -961,14 +960,6 @@
         "node": ">=20"
       }
     },
-    "node_modules/pngjs": {
-      "version": "7.0.0",
-      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
-      "integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==",
-      "engines": {
-        "node": ">=14.19.0"
-      }
-    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",
@@ -1915,11 +1906,6 @@
       "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.63.0.tgz",
       "integrity": "sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg=="
     },
-    "pngjs": {
-      "version": "7.0.0",
-      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
-      "integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow=="
-    },
     "proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",

package/mcp/trace-mcp-recorder/package.json

@@ -19,7 +19,6 @@
     "axios": "1.20.0",
     "form-data": "4.0.6",
     "playwright": "1.63.0",
-    "pngjs": "^7.0.0",
     "uuid": "14.0.2",
     "zod": "4.4.3"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "private": false,
   "description": "Autobest Agent skills/plugins/mcp assets + sync cli",
   "files": [

package/skills/common/trace-recorder/SKILL.md

@@ -14,7 +14,7 @@ description: 通过 trace-mcp-recorder 启动或停止 Playwright Trace 人工
 1. 从原话提取 `url`、`version`、`title`、`operator`。支持 `key=value` 和自然语言表达，不改写用户给出的值。
 2. `url` 必填；缺少时只询问目标页面地址。其他字段缺失时不要阻断录制。
 3. 调用 `start_trace_recording`，只传入用户明确提供的可选字段。服务端会优先使用 MCP 上下文中的操作人身份。
-4. 告知用户浏览器已打开，并保留工具返回的 `uuid` 和最大录制时长；不要代替用户操作页面。
+4. 告知用户浏览器已打开、正在等待首次真实操作，并保留工具返回的 `uuid` 和最大录制时长；Trace 会在第一次真实操作时开始计时，不要代替用户操作页面。连续 2 分钟没有真实操作时服务会自动停止并上传。
 
 示例：`trace-mcp-recorder 启动Playwright trace 访问https://cpd.dev.autobestdevops.com，version=v2.1.0 title=bug3452 operator=张三`。这里 `title=bug3452` 是本次录制的标题/功能描述，页面由 `url=https://cpd.dev.autobestdevops.com` 确定。