@autobest-ui/agent 1.0.16 → 1.0.18

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 供测试人员手动操作，页面加载后等待第一次真实用户操作才启动 Trace；后续用户活动经过防抖后以 `步骤N | 页面标题 | 事件类型` 的 Trace Group 写入轻量 Playwright Action，空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
+`trace-mcp-recorder` 是基于 `@modelcontextprotocol/sdk` 和 `StdioServerTransport` 的 Node.js MCP Server。它打开非无头 Chromium，并在页面左下角注入半透明的“开始录制”“停止录制”和设备切换按钮供测试人员手动控制 Trace；默认是 PC 端，也可切换为 iPhone 14 Pro Max 移动端模拟。后续用户活动经过防抖后以 `步骤N | 页面标题 | 事件类型` 的 Trace Group 写入轻量 Playwright Action，空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
 
 ## 安装与启动
 
@@ -38,12 +38,12 @@ npm start
 
 ## MCP 工具
 
-- `start_trace_recording`：参数为必填 `url` 和可选 `version`、`title`、`operator`。`url` 独立确定被测页面；`title` 是录制标题或功能描述，也可以直接填写 `bug3452` 这类 Bug 编号。系统不额外传递独立的 Bug 字段。MCP 认证上下文中的 `operator`、`name` 或 `preferred_username` 优先于参数。
+- `start_trace_recording`：参数为必填 `url` 和可选 `version`、`title`、`operator`。该工具打开页面，默认 PC 端；点击左下角“切换移动端”可使用 iPhone 14 Pro Max（430×932、DPR 3、触摸、iPhone User-Agent）模拟，点击“开始录制”后才真正启动 Trace。`url` 独立确定被测页面；`title` 是录制标题或功能描述，也可以直接填写 `bug3452` 这类 Bug 编号。系统不额外传递独立的 Bug 字段。MCP 认证上下文中的 `operator`、`name` 或 `preferred_username` 优先于参数。
 - `stop_trace_recording`：首次调用不传参数，只停止 trace 并询问是否上传；用户确认后传 `confirm=upload`，取消时传 `confirm=cancel`。上传成功后返回回放链接及版本、标题、操作人、浏览器版本。
 
 录制超时后服务自动停止并自动上传（无需人工确认），随后第一次人工调用 `stop_trace_recording` 会取回自动停止的结果；再调用则返回没有活动会话。
 
-Trace 在第一次真实用户操作后才开始计时。连续用户操作停止 800ms 后写入一个带自定义名称的 `tracing.group()`，组内使用 `waitForTimeout(1)` 推进官方 Viewer 播放；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。官方 Viewer 的具体显示可能是 Group 标签或 Group 内嵌 Wait 节点，取决于 Viewer 版本。
+Trace 在点击页面左下角“开始录制”后才开始计时；点击“停止录制”会立即停止并自动上传，随后可通过 `stop_trace_recording` 取回回放链接。设备切换和录制控制按钮不会写入操作步骤；新打开的页面会继承当前设备模式。连续用户操作停止 800ms 后写入一个带自定义名称的 `tracing.group()`，组内使用 `waitForTimeout(1)` 推进官方 Viewer 播放；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。官方 Viewer 的具体显示可能是 Group 标签或 Group 内嵌 Wait 节点，取决于 Viewer 版本。
 
 ## 后端接口契约
 
@@ -51,7 +51,7 @@ Trace 在第一次真实用户操作后才开始计时。连续用户操作停
 
 - `POST /api/trace-sessions`：接收 `multipart/form-data`，必填字段为 `trace`、`target_url`，可选字段为 `version`、`title`、`operator`、`browser_name`、`browser_version`、`user_agent`、`os_name`、`viewport`；后端生成 UUID，创建并上传成功后返回 `{ "uuid": "...", "fileUrl": "...", "item": { "status": "completed" } }`。
 
-`metadata` 包含浏览器版本、User-Agent、viewport、MCP 所在操作系统信息、目标 URL 和录制业务字段。上传或状态更新失败时，本地 trace 仍会被清理，会话会尽力回写为 `failed`。
+`metadata` 包含浏览器版本、当前 User-Agent、viewport、设备模式（PC 或 iPhone 14 Pro Max）、MCP 所在操作系统信息、目标 URL 和录制业务字段。上传或状态更新失败时，本地 trace 仍会被清理，会话会尽力回写为 `failed`。
 
 ## 验证
 

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

@@ -15,6 +15,15 @@ import { z } from 'zod';
 const DEFAULT_MAX_RECORD_DURATION = 1_800_000;
 const USER_ACTIVITY_DEBOUNCE_DELAY = 800;
 const IDLE_STOP_DELAY = 120_000;
+const IPHONE_14_PRO_MAX_DEVICE = {
+  name: 'iPhone 14 Pro Max',
+  width: 430,
+  height: 932,
+  deviceScaleFactor: 3,
+  userAgent:
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 ' +
+    '(KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1'
+};
 const directory = path.dirname(fileURLToPath(import.meta.url));
 
 function readConfiguration(environment = process.env) {
@@ -101,10 +110,12 @@ function toolError(error) {
   };
 }
 
-// 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() {
+// Inject an isolated recorder toolbar and emit only trusted page activity.
+// Control clicks are excluded so they never become Trace action checkpoints.
+function createRecorderPageScript() {
   return `(() => {
+    if (window !== window.top) return;
+    const controlAttribute = 'data-trace-recorder-control';
     const notify = type => Promise.resolve(globalThis.__traceRecorderUserActivity?.({
       type,
       title: document.title || '未命名页面'
@@ -112,9 +123,119 @@ function createUserActivityScript() {
     const options = { capture: true, passive: true };
     for (const type of ['click', 'keydown', 'input', 'change', 'wheel', 'touchstart']) {
       document.addEventListener(type, event => {
-        if (event.isTrusted) notify(type);
+        const isRecorderControl = event.composedPath().some(node =>
+          node instanceof Element && node.hasAttribute(controlAttribute)
+        );
+        if (event.isTrusted && !isRecorderControl) notify(type);
       }, options);
     }
+
+    const mountToolbar = () => {
+      if (!document.documentElement || document.querySelector('[data-trace-recorder-toolbar-host]')) return;
+      const host = document.createElement('div');
+      host.setAttribute('data-trace-recorder-toolbar-host', '');
+      host.setAttribute(controlAttribute, '');
+      const shadow = host.attachShadow({ mode: 'closed' });
+      shadow.innerHTML = \`
+        <style>
+          :host { all: initial; }
+          .toolbar {
+            position: fixed;
+            left: 16px;
+            bottom: 16px;
+            z-index: 2147483647;
+            display: flex;
+            gap: 8px;
+            padding: 7px;
+            border: 1px solid rgba(255, 255, 255, .38);
+            border-radius: 8px;
+            background: rgba(24, 24, 27, .58);
+            box-shadow: 0 4px 16px rgba(0, 0, 0, .2);
+            backdrop-filter: blur(6px);
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+          }
+          button {
+            box-sizing: border-box;
+            min-width: 88px;
+            height: 34px;
+            border: 1px solid rgba(255, 255, 255, .48);
+            border-radius: 6px;
+            color: #fff;
+            font: 500 14px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+            letter-spacing: 0;
+            cursor: pointer;
+            transition: opacity .15s ease, background-color .15s ease;
+          }
+          button:hover:not(:disabled) { opacity: .9; }
+          button:focus-visible { outline: 2px solid #fff; outline-offset: 2px; }
+          button:disabled { cursor: default; opacity: .42; }
+          .start { background: rgba(22, 163, 74, .82); }
+          .stop { background: rgba(220, 38, 38, .82); }
+          .device { background: rgba(37, 99, 235, .82); min-width: 102px; }
+        </style>
+        <div class="toolbar" role="group" aria-label="Trace 录制控制">
+          <button class="start" type="button" data-action="start" data-trace-recorder-control>开始录制</button>
+          <button class="stop" type="button" data-action="stop" data-trace-recorder-control>停止录制</button>
+          <button class="device" type="button" data-action="toggle-device" data-trace-recorder-control>切换移动端</button>
+        </div>
+      \`;
+      document.documentElement.append(host);
+      const startButton = shadow.querySelector('[data-action="start"]');
+      const stopButton = shadow.querySelector('[data-action="stop"]');
+      const deviceButton = shadow.querySelector('[data-action="toggle-device"]');
+
+      const render = (state, deviceMode = 'desktop') => {
+        const recording = state === 'recording';
+        const waiting = state === 'waiting_for_start';
+        startButton.disabled = !waiting;
+        stopButton.disabled = !recording && !waiting;
+        deviceButton.disabled = state === 'starting' || state === 'stopping' || state === 'uploading';
+        startButton.textContent = recording ? '录制中' : '开始录制';
+        stopButton.textContent = state === 'stopping' || state === 'uploading' ? '正在停止' : '停止录制';
+        deviceButton.textContent = deviceMode === 'mobile' ? '切换 PC 端' : '切换移动端';
+      };
+      const control = async action => {
+        startButton.disabled = true;
+        stopButton.disabled = true;
+        try {
+          const result = await globalThis.__traceRecorderControl?.(action);
+          render(result?.state, result?.deviceMode);
+        } catch {
+          render('waiting_for_start', 'desktop');
+        }
+      };
+      startButton.addEventListener('click', event => {
+        event.preventDefault();
+        event.stopPropagation();
+        void control('start');
+      });
+      stopButton.addEventListener('click', event => {
+        event.preventDefault();
+        event.stopPropagation();
+        render('stopping');
+        void control('stop');
+      });
+      deviceButton.addEventListener('click', event => {
+        event.preventDefault();
+        event.stopPropagation();
+        void control('toggle-device');
+      });
+
+      const syncState = () => {
+        void Promise.resolve(globalThis.__traceRecorderControl?.('status'))
+          .then(result => render(result?.state, result?.deviceMode))
+          .catch(() => {});
+      };
+      syncState();
+      const stateTimer = setInterval(syncState, 500);
+      window.addEventListener('pagehide', () => clearInterval(stateTimer), { once: true });
+    };
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', mountToolbar, { once: true });
+    } else {
+      mountToolbar();
+    }
   })();`;
 }
 
@@ -185,9 +306,13 @@ export class TraceRecorder {
           if (session) return this.handleUserActivity(session, activity);
           return undefined;
         });
+        await context.exposeBinding('__traceRecorderControl', (_source, action) => {
+          if (!session) return { state: 'starting' };
+          return this.handlePageControl(session, action);
+        });
       }
       if (typeof context.addInitScript === 'function') {
-        await context.addInitScript({ content: createUserActivityScript() });
+        await context.addInitScript({ content: createRecorderPageScript() });
       }
       page = await context.newPage();
       await page.goto(targetUrl);
@@ -201,6 +326,8 @@ export class TraceRecorder {
         browserVersion: browser.version(),
         userAgent: await page.evaluate(() => navigator.userAgent),
         viewport: page.viewportSize(),
+        deviceMode: 'desktop',
+        deviceName: 'Desktop',
         operatingSystem: this.platformInfo(),
         startedAt: new Date().toISOString()
       };
@@ -213,7 +340,7 @@ export class TraceRecorder {
         maxRecordDuration: configuration.maxRecordDuration,
         tracePath: path.join(temporaryDirectory, 'trace.zip'),
         temporaryDirectory,
-        state: 'waiting_for_activity',
+        state: 'waiting_for_start',
         stopPromise: undefined,
         uploadPromise: undefined,
         timer: undefined,
@@ -224,12 +351,26 @@ export class TraceRecorder {
         pendingActivity: undefined,
         stepIndex: 0,
         tracingStarted: false,
-        lastActivityAt: undefined
+        lastActivityAt: undefined,
+        deviceMode: 'desktop',
+        deviceName: 'Desktop',
+        desktopUserAgent: metadata.userAgent,
+        cdpSessions: new Map()
       };
       this.activeSession = session;
 
+      if (typeof context.on === 'function') {
+        context.on('page', openedPage => {
+          if (session.deviceMode === 'mobile') {
+            void this.applyDeviceMode(session, openedPage, 'mobile').catch(error => {
+              console.error('[trace-mcp-recorder] 新页面应用移动端模拟失败:', errorMessage(error));
+            });
+          }
+        });
+      }
+
       const failOnBrowserExit = () => {
-        if (session.state === 'recording' || session.state === 'waiting_for_activity') {
+        if (session.state === 'recording' || session.state === 'waiting_for_start') {
           session.stopPromise = this.failSession(session, new Error('Chromium 浏览器意外退出'));
           void session.stopPromise.catch(failure => {
             console.error('[trace-mcp-recorder] 浏览器异常退出:', errorMessage(failure));
@@ -239,7 +380,7 @@ export class TraceRecorder {
       browser.once('disconnected', failOnBrowserExit);
 
       return {
-        message: '浏览器已打开，等待首次真实操作后开始录制；完成后调用 stop_trace_recording',
+        message: '浏览器已打开，请点击页面左下角“开始录制”；操作完成后点击“停止录制”，服务将自动上传。',
         maxRecordDuration: configuration.maxRecordDuration,
         metadata
       };
@@ -270,7 +411,7 @@ export class TraceRecorder {
     if (session.state === 'starting') {
       throw new Error('录制会话正在启动，请等待 start_trace_recording 返回后再停止');
     }
-    if (session.state === 'waiting_for_activity') {
+    if (session.state === 'waiting_for_start') {
       session.state = 'stopping';
       this.clearTimer(session.timer);
       this.clearTimer(session.idleTimer);
@@ -286,11 +427,13 @@ export class TraceRecorder {
       }
       await this.closeResources({ page: session.page, context: session.context, browser: session.browser });
       if (this.activeSession === session) this.activeSession = undefined;
-      return {
+      const result = {
         state: 'not_started',
         uploaded: false,
-        message: '录制已停止。停止前未检测到真实用户操作，因此没有生成可上传的 trace。'
+        message: '录制已停止。停止前未点击“开始录制”，因此没有生成可上传的 trace。'
       };
+      if (trigger !== 'manual') this.lastAutomaticResult = result;
+      return result;
     }
     if (session.state === 'recording') {
       if (session.stopPromise) return session.stopPromise;
@@ -323,6 +466,11 @@ export class TraceRecorder {
     try {
       await session.activityPromise?.catch(() => {});
       await session.activityRecordPromise?.catch(() => {});
+      if (session.pendingActivity) {
+        const pendingActivity = session.pendingActivity;
+        session.pendingActivity = undefined;
+        await this.recordActivityStep(session, pendingActivity);
+      }
       if (session.tracingStarted) await this.recordFinalStep(session);
       await session.context.tracing.stop({ path: session.tracePath });
       await this.closeResources({ page: session.page, context: session.context, browser: session.browser });
@@ -339,8 +487,8 @@ export class TraceRecorder {
     }
   }
 
-  async beginRecording(session, activity = {}) {
-    if (session.tracingStarted || session.state !== 'waiting_for_activity') return;
+  async beginRecording(session) {
+    if (session.tracingStarted || session.state !== 'waiting_for_start') return;
     await session.context.tracing.start({ screenshots: true, snapshots: true, sources: true });
     session.tracingStarted = true;
     session.state = 'recording';
@@ -353,18 +501,85 @@ export class TraceRecorder {
     }, session.maxRecordDuration);
     session.timer?.unref?.();
     this.armIdleTimer(session);
-    await this.recordActivityStep(session, activity);
   }
 
-  handleUserActivity(session, activity = {}) {
-    if (session.state === 'waiting_for_activity') {
-      if (session.activityPromise) return session.activityPromise;
-      session.activityPromise = this.beginRecording(session, activity).catch(error => {
-        session.state = 'failed';
-        throw error;
+  async applyDeviceMode(session, page, mode) {
+    if (mode === 'desktop') {
+      if (typeof session.context.newCDPSession !== 'function') return;
+    }
+    if (typeof session.context.newCDPSession !== 'function') {
+      throw new Error('当前浏览器不支持移动端 CDP 模拟');
+    }
+    let cdp = session.cdpSessions.get(page);
+    if (!cdp) {
+      cdp = await session.context.newCDPSession(page);
+      session.cdpSessions.set(page, cdp);
+    }
+    if (mode === 'mobile') {
+      await cdp.send('Emulation.setDeviceMetricsOverride', {
+        width: IPHONE_14_PRO_MAX_DEVICE.width,
+        height: IPHONE_14_PRO_MAX_DEVICE.height,
+        deviceScaleFactor: IPHONE_14_PRO_MAX_DEVICE.deviceScaleFactor,
+        mobile: true,
+        screenWidth: IPHONE_14_PRO_MAX_DEVICE.width,
+        screenHeight: IPHONE_14_PRO_MAX_DEVICE.height
+      });
+      await cdp.send('Emulation.setTouchEmulationEnabled', { enabled: true, maxTouchPoints: 5 });
+      await cdp.send('Network.setUserAgentOverride', { userAgent: IPHONE_14_PRO_MAX_DEVICE.userAgent });
+      return;
+    }
+    await cdp.send('Emulation.clearDeviceMetricsOverride');
+    await cdp.send('Emulation.setTouchEmulationEnabled', { enabled: false });
+    await cdp.send('Network.setUserAgentOverride', { userAgent: session.desktopUserAgent });
+  }
+
+  async toggleDeviceMode(session) {
+    if (session.state !== 'waiting_for_start' && session.state !== 'recording') {
+      return { state: session.state, deviceMode: session.deviceMode };
+    }
+    const nextMode = session.deviceMode === 'mobile' ? 'desktop' : 'mobile';
+    await this.applyDeviceMode(session, session.page, nextMode);
+    session.deviceMode = nextMode;
+    session.deviceName = nextMode === 'mobile' ? IPHONE_14_PRO_MAX_DEVICE.name : 'Desktop';
+    session.metadata.deviceMode = session.deviceMode;
+    session.metadata.deviceName = session.deviceName;
+    session.metadata.userAgent = nextMode === 'mobile'
+      ? IPHONE_14_PRO_MAX_DEVICE.userAgent
+      : session.desktopUserAgent;
+    session.metadata.viewport = nextMode === 'mobile'
+      ? { width: IPHONE_14_PRO_MAX_DEVICE.width, height: IPHONE_14_PRO_MAX_DEVICE.height }
+      : session.page.viewportSize();
+    return { state: session.state, deviceMode: session.deviceMode, deviceName: session.deviceName };
+  }
+
+  handlePageControl(session, action) {
+    if (action === 'status') return { state: session.state, deviceMode: session.deviceMode };
+    if (action === 'toggle-device') return this.toggleDeviceMode(session);
+    if (action === 'start') {
+      if (session.state === 'recording') return { state: session.state };
+      if (session.state !== 'waiting_for_start') return { state: session.state };
+      if (!session.activityPromise) {
+        session.activityPromise = this.beginRecording(session).catch(error => {
+          session.state = 'failed';
+          throw error;
+        });
+      }
+      return session.activityPromise.then(() => ({ state: session.state, deviceMode: session.deviceMode }));
+    }
+    if (action === 'stop') {
+      if (session.state !== 'recording' && session.state !== 'waiting_for_start') {
+        return { state: session.state };
+      }
+      void this.stop({ trigger: 'page-control', confirm: 'upload' }).catch(error => {
+        this.lastAutomaticError = error;
+        console.error('[trace-mcp-recorder] 页面按钮停止录制失败:', errorMessage(error));
       });
-      return session.activityPromise;
+      return { state: 'stopping' };
     }
+    return { state: session.state };
+  }
+
+  handleUserActivity(session, activity = {}) {
     if (session.state !== 'recording') return undefined;
     session.lastActivityAt = Date.now();
     session.pendingActivity = activity;
@@ -386,7 +601,7 @@ export class TraceRecorder {
   }
 
   async recordActivityStep(session, activity = {}) {
-    if (!session.tracingStarted || session.state !== 'recording') return;
+    if (!session.tracingStarted || !['recording', 'stopping'].includes(session.state)) return;
     session.stepIndex += 1;
     const type = typeof activity.type === 'string' && activity.type ? activity.type : 'unknown';
     const title = typeof activity.title === 'string' && activity.title ? activity.title : '未命名页面';
@@ -441,7 +656,9 @@ export class TraceRecorder {
         ['browser_version', session.metadata.browserVersion],
         ['user_agent', session.metadata.userAgent],
         ['os_name', session.metadata.operatingSystem.platform],
-        ['viewport', JSON.stringify(session.metadata.viewport)]
+        ['viewport', JSON.stringify(session.metadata.viewport)],
+        ['device_mode', session.metadata.deviceMode],
+        ['device_name', session.metadata.deviceName]
       ]) {
         if (value !== undefined && value !== null) form.append(field, String(value));
       }
@@ -465,16 +682,19 @@ export class TraceRecorder {
           version: session.metadata.version,
           title: session.metadata.title,
           operator: session.metadata.operator,
-          browserVersion: session.metadata.browserVersion
+          browserVersion: session.metadata.browserVersion,
+          deviceMode: session.metadata.deviceMode,
+          deviceName: session.metadata.deviceName,
+          viewport: session.metadata.viewport
         }
       };
       session.state = 'completed';
-      if (trigger === 'timeout') this.lastAutomaticResult = result;
+      if (trigger !== 'manual') this.lastAutomaticResult = result;
       return result;
     })()
       .catch(async error => {
         session.state = 'failed';
-        if (trigger === 'timeout') this.lastAutomaticError = error;
+        if (trigger !== 'manual') this.lastAutomaticError = error;
         await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
         if (this.activeSession === session) this.activeSession = undefined;
         throw error;
@@ -494,7 +714,7 @@ export class TraceRecorder {
   }
 
   async failSession(session, error) {
-    if (session.state !== 'recording' && session.state !== 'waiting_for_activity') return;
+    if (session.state !== 'recording' && session.state !== 'waiting_for_start') return;
     session.state = 'failed';
     this.clearTimer(session.timer);
     this.clearTimer(session.idleTimer);
@@ -538,8 +758,8 @@ export function createServer(options = {}) {
     { 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.'
+        'Use start_trace_recording to open a visible Chromium window with page recording controls. ' +
+        'When the user asks to stop recording or retrieve a page-control result, call stop_trace_recording.'
     }
   );
 
@@ -547,7 +767,7 @@ export function createServer(options = {}) {
     'start_trace_recording',
     {
       title: '启动 Playwright Trace 人工录制',
-      description: '启动非无头 Chromium、开启 trace 并访问指定 URL，供测试人员在浏览器窗口中手动操作。',
+      description: '启动非无头 Chromium 并访问指定 URL；测试人员通过页面左下角按钮开始和停止 trace。',
       inputSchema: {
         url: z.string().min(1).describe('必填，被测页面的 HTTP(S) 地址'),
         version: z.string().min(1).optional().describe('可选，被测版本号，例如 v2.1.0'),

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

@@ -12,6 +12,7 @@ const sessionUuid = '123e4567-e89b-42d3-a456-426614174000';
 
 function createFixture(options = {}) {
   const calls = [];
+  const bindings = {};
   const browser = new EventEmitter();
   const tracing = {
     start: async options => calls.push(['trace-start', options]),
@@ -28,6 +29,14 @@ function createFixture(options = {}) {
   };
   const context = {
     tracing,
+    newCDPSession: async page => ({
+      send: async (method, params) => calls.push(['cdp', method, params])
+    }),
+    exposeBinding: async (name, callback) => {
+      calls.push(['expose-binding', name]);
+      bindings[name] = callback;
+    },
+    addInitScript: async script => calls.push(['init-script', script]),
     newPage: async () => page,
     close: async () => calls.push(['context-close'])
   };
@@ -77,11 +86,11 @@ function createFixture(options = {}) {
     clearTimer: value => calls.push(['clear-timer', value]),
     platformInfo: () => ({ platform: 'fixture-os' })
   });
-  return { browser, calls, recorder, timer };
+  return { bindings, browser, calls, recorder, timer };
 }
 
-test('starts, records metadata, uploads, completes and cleans up one session', async () => {
-  const { calls, recorder } = createFixture();
+test('page controls start recording, record activity, upload and clean up one session', async () => {
+  const { bindings, calls, recorder } = createFixture();
   const started = await recorder.start(
     {
       url: 'https://app.example.test/login',
@@ -95,7 +104,13 @@ 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, {
+  assert.equal(calls.some(call => call[0] === 'trace-start'), false);
+  assert.match(calls.find(call => call[0] === 'init-script')[1].content, /开始录制/);
+  assert.deepEqual(await bindings.__traceRecorderControl({}, 'start'), {
+    state: 'recording',
+    deviceMode: 'desktop'
+  });
+  recorder.handleUserActivity(recorder.activeSession, {
     type: 'click',
     title: '首页功能'
   });
@@ -131,7 +146,7 @@ test('stops waiting sessions immediately without reporting an error', async () =
   assert.deepEqual(result, {
     state: 'not_started',
     uploaded: false,
-    message: '录制已停止。停止前未检测到真实用户操作，因此没有生成可上传的 trace。'
+    message: '录制已停止。停止前未点击“开始录制”，因此没有生成可上传的 trace。'
   });
   assert.equal(recorder.activeSession, undefined);
   assert.ok(calls.some(call => call[0] === 'browser-close'));
@@ -150,7 +165,8 @@ 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.handlePageControl(recorder.activeSession, 'start');
+  recorder.handleUserActivity(recorder.activeSession);
 
   await recorder.stop();
   await assert.rejects(recorder.stop({ confirm: 'upload' }), /upload failed/);
@@ -160,7 +176,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);
+  await recorder.handlePageControl(recorder.activeSession, 'start');
   timer.callback();
 
   while (recorder.activeSession) await new Promise(resolve => setImmediate(resolve));
@@ -169,6 +185,41 @@ test('automatically stops on timeout and returns that result on the next stop ca
   await assert.rejects(recorder.stop(), /当前没有正在录制/);
 });
 
+test('page stop control immediately stops and uploads, then exposes the result to MCP', async () => {
+  const { bindings, recorder } = createFixture();
+  await recorder.start({ url: 'https://app.example.test' });
+  await bindings.__traceRecorderControl({}, 'start');
+
+  assert.deepEqual(await bindings.__traceRecorderControl({}, 'stop'), { state: 'stopping' });
+  while (recorder.activeSession) await new Promise(resolve => setImmediate(resolve));
+
+  const result = await recorder.stop();
+  assert.equal(result.stoppedBy, 'page-control');
+  assert.match(result.replayLink, /trace-viewer/);
+});
+
+test('toggles desktop and iPhone 14 Pro Max emulation in the same session', async () => {
+  const { bindings, calls, recorder } = createFixture();
+  await recorder.start({ url: 'https://app.example.test' });
+
+  const mobile = await bindings.__traceRecorderControl({}, 'toggle-device');
+  assert.deepEqual(mobile, {
+    state: 'waiting_for_start',
+    deviceMode: 'mobile',
+    deviceName: 'iPhone 14 Pro Max'
+  });
+  assert.ok(calls.some(call => call[0] === 'cdp' && call[1] === 'Emulation.setDeviceMetricsOverride'));
+  assert.deepEqual(recorder.activeSession.metadata.viewport, { width: 430, height: 932 });
+  assert.match(recorder.activeSession.metadata.userAgent, /iPhone/);
+
+  const desktop = await bindings.__traceRecorderControl({}, 'toggle-device');
+  assert.equal(desktop.deviceMode, 'desktop');
+  assert.ok(calls.some(call => call[0] === 'cdp' && call[1] === 'Emulation.clearDeviceMetricsOverride'));
+  assert.equal(recorder.activeSession.metadata.userAgent, 'Fixture User Agent');
+
+  await recorder.stop();
+});
+
 test('exposes both tools and the bundled skill over stdio', async () => {
   const client = new Client({ name: 'trace-mcp-recorder-test', version: '1.0.0' });
   const transport = new StdioClientTransport({

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

@@ -10,7 +10,9 @@
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.30.0",
         "axios": "1.20.0",
+        "fflate": "0.8.2",
         "form-data": "4.0.6",
+        "jpeg-js": "0.4.4",
         "playwright": "1.63.0",
         "uuid": "14.0.2",
         "zod": "4.4.3"
@@ -496,6 +498,11 @@
         }
       ]
     },
+    "node_modules/fflate": {
+      "version": "0.8.2",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.2.tgz",
+      "integrity": "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A=="
+    },
     "node_modules/finalhandler": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
@@ -768,6 +775,11 @@
         "url": "https://github.com/sponsors/panva"
       }
     },
+    "node_modules/jpeg-js": {
+      "version": "0.4.4",
+      "resolved": "https://registry.npmjs.org/jpeg-js/-/jpeg-js-0.4.4.tgz",
+      "integrity": "sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg=="
+    },
     "node_modules/json-schema-traverse": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -1613,6 +1625,11 @@
       "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.7.tgz",
       "integrity": "sha512-dOvZVzjdZdz7phd9v6jCbwxrBW3fK6n8Rc0CtdmM4bumzMnxywBYhuph6J819RRw/ku+rLbelwfMunktuzVVHg=="
     },
+    "fflate": {
+      "version": "0.8.2",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.2.tgz",
+      "integrity": "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A=="
+    },
     "finalhandler": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
@@ -1789,6 +1806,11 @@
       "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.12.tgz",
       "integrity": "sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw=="
     },
+    "jpeg-js": {
+      "version": "0.4.4",
+      "resolved": "https://registry.npmjs.org/jpeg-js/-/jpeg-js-0.4.4.tgz",
+      "integrity": "sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg=="
+    },
     "json-schema-traverse": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",

package/package.json

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

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

@@ -14,14 +14,16 @@ description: 通过 trace-mcp-recorder 启动或停止 Playwright Trace 人工
 1. 从原话提取 `url`、`version`、`title`、`operator`。支持 `key=value` 和自然语言表达，不改写用户给出的值。
 2. `url` 必填；缺少时只询问目标页面地址。其他字段缺失时不要阻断录制。
 3. 调用 `start_trace_recording`，只传入用户明确提供的可选字段。服务端会优先使用 MCP 上下文中的操作人身份。
-4. 告知用户浏览器已打开、正在等待首次真实操作，并保留工具返回的 `uuid` 和最大录制时长；Trace 会在第一次真实操作时开始计时，不要代替用户操作页面。连续 2 分钟没有真实操作时服务会自动停止并上传。真实操作经防抖后会在官方 Trace Viewer 中以 `步骤N | 页面标题 | 事件类型` 的分组节点呈现。
+4. 告知用户浏览器已打开：默认是 PC 端；如需移动端测试，先点击左下角“切换移动端”（iPhone 14 Pro Max，430×932，DPR 3），再点击“开始录制”；操作完成后点击“停止录制”。不要代替用户点击按钮或操作页面。点击开始后才启动 Trace 和计时；新打开的页面会继承当前设备模式。连续 2 分钟没有真实操作时服务会自动停止并上传。真实操作经防抖后会在官方 Trace Viewer 中以 `步骤N | 页面标题 | 事件类型` 的分组节点呈现。
 
 示例：`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` 确定。
 
 ## 停止录制
 
-用户表达“停止录制”“结束 trace”“完成录制”等意图时，调用 `stop_trace_recording`。第一次调用只会停止录制并询问是否上传；不要擅自上传。用户明确回答“上传”后，再次调用 `stop_trace_recording` 并传入 `confirm=upload`。用户回答“不上传”时，调用该工具并传入 `confirm=cancel`。上传成功后，将回放链接和 `version`、`title`、`operator`、`browserVersion` 整理给用户。
+页面左下角“停止录制”会立即停止并自动上传。用户随后要求获取回放链接时，调用 `stop_trace_recording` 读取这次按钮停止的结果，并整理回放链接和元数据。
 
-停止调用必须以工具本次返回结果为准，不要根据启动时的 `waiting_for_activity` 提示推断最终状态。若工具返回 `state=not_started`，应说明本次没有检测到真实操作且没有生成 trace；若返回上传结果，则只整理上传返回的回放链接。
+用户表达“停止录制”“结束 trace”“完成录制”等意图时，调用 `stop_trace_recording`。单独输入“停止录制”时首次调用不传 `confirm`，停止并询问是否上传；用户明确回答“上传”后，再次调用并传入 `confirm=upload`。用户直接输入“停止录制 & 上传”或等价表达时，停止调用直接传入 `confirm=upload`。用户回答“不上传”时，调用该工具并传入 `confirm=cancel`。上传成功后，将回放链接和 `version`、`title`、`operator`、`browserVersion` 整理给用户。
+
+停止调用必须以工具本次返回结果为准，不要根据启动时的 `waiting_for_start` 提示推断最终状态。若工具返回 `state=not_started`，应说明本次没有点击“开始录制”且没有生成 trace；若返回上传结果，则只整理上传返回的回放链接。
 
 若工具返回错误，如没有活动会话、后端不可达或上传失败，原样说明关键原因，不编造回放链接。