@autobest-ui/agent 1.0.21 → 1.0.23

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；默认是 PC 端，也可切换为 iPhone 14 Pro Max 移动端模拟。页面先正常打开并等待，点击开始后才启动 Trace，不刷新当前页面；后续用户活动经过防抖后以 `步骤N | 页面标题 | 事件类型` 的 Trace Group 写入轻量 Playwright Action，空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
+`trace-mcp-recorder` 是基于 `@modelcontextprotocol/sdk` 和 `StdioServerTransport` 的 Node.js MCP Server。它打开非无头 Chromium，并在页面左上角注入可收缩的半透明控制栏，供测试人员手动开始录制、截图、停止录制和切换设备；默认是 PC 端，也可切换为 iPhone 14 Pro Max 移动端模拟。页面先正常打开并等待，点击开始后先启动 Trace、刷新一次当前 SPA 页面并等待 DOM、CSS、字体和图片稳定，再进入正式录制；普通点击、输入和滚动不会生成自定义 Action，只有点击“截图”才会把当前渲染画面作为 Trace Group 写入官方 Viewer，截图时控制栏会临时隐藏。空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
 
 ## 安装与启动
 

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

@@ -141,8 +141,8 @@ function createRecorderPageScript() {
           :host { all: initial; }
           .toolbar {
             position: fixed;
-            left: 16px;
-            bottom: 16px;
+            left: 0;
+            top: 16px;
             z-index: 2147483647;
             display: flex;
             gap: 8px;
@@ -153,6 +153,12 @@ function createRecorderPageScript() {
             box-shadow: 0 4px 16px rgba(0, 0, 0, .2);
             backdrop-filter: blur(6px);
             font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+            transform: translateX(calc(-100% + 30px));
+            transition: transform .2s ease;
+          }
+          .toolbar:hover,
+          .toolbar:focus-within {
+            transform: translateX(0);
           }
           button {
             box-sizing: border-box;
@@ -170,32 +176,46 @@ function createRecorderPageScript() {
           button:focus-visible { outline: 2px solid #fff; outline-offset: 2px; }
           button:disabled { cursor: default; opacity: .42; }
           .start { background: rgba(22, 163, 74, .82); }
+          .screenshot { background: rgba(234, 88, 12, .82); }
           .stop { background: rgba(220, 38, 38, .82); }
           .device { background: rgba(37, 99, 235, .82); min-width: 102px; }
+          .toggle {
+            flex: 0 0 24px;
+            min-width: 24px;
+            padding: 0;
+            background: rgba(255, 255, 255, .16);
+            font-size: 20px;
+          }
         </style>
         <div class="toolbar" role="group" aria-label="Trace 录制控制">
+          <button class="toggle" type="button" aria-label="展开录制控制" data-trace-recorder-control>›</button>
           <button class="start" type="button" data-action="start" data-trace-recorder-control>开始录制</button>
+          <button class="screenshot" type="button" data-action="screenshot" 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 screenshotButton = shadow.querySelector('[data-action="screenshot"]');
       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';
+        const preparing = state === 'starting';
         startButton.disabled = !waiting;
+        screenshotButton.disabled = !recording;
         stopButton.disabled = !recording && !waiting;
         deviceButton.disabled = state === 'starting' || state === 'stopping' || state === 'uploading';
-        startButton.textContent = recording ? '录制中' : '开始录制';
+        startButton.textContent = preparing ? '准备页面' : recording ? '录制中' : '开始录制';
         stopButton.textContent = state === 'stopping' || state === 'uploading' ? '正在停止' : '停止录制';
         deviceButton.textContent = deviceMode === 'mobile' ? '切换 PC 端' : '切换移动端';
       };
       const control = async action => {
         startButton.disabled = true;
+        screenshotButton.disabled = true;
         stopButton.disabled = true;
         try {
           const result = await globalThis.__traceRecorderControl?.(action);
@@ -209,6 +229,11 @@ function createRecorderPageScript() {
         event.stopPropagation();
         void control('start');
       });
+      screenshotButton.addEventListener('click', event => {
+        event.preventDefault();
+        event.stopPropagation();
+        void control('screenshot');
+      });
       stopButton.addEventListener('click', event => {
         event.preventDefault();
         event.stopPropagation();
@@ -409,7 +434,13 @@ export class TraceRecorder {
       throw new Error('当前没有正在录制的 trace 会话');
     }
     if (session.state === 'starting') {
-      throw new Error('录制会话正在启动，请等待 start_trace_recording 返回后再停止');
+      await session.activityPromise?.catch(error => {
+        throw error;
+      });
+      if (session.state === 'failed') {
+        throw new Error('录制初始化失败，无法停止当前 trace');
+      }
+      return this.stop({ trigger, confirm });
     }
     if (session.state === 'waiting_for_start') {
       session.state = 'stopping';
@@ -489,8 +520,49 @@ export class TraceRecorder {
 
   async beginRecording(session) {
     if (session.tracingStarted || session.state !== 'waiting_for_start') return;
+    // The initial page was opened before the user clicked the button. Start the
+    // trace first, then reload once so SPA CSS, fonts, images and DOM resources
+    // are captured by Trace Viewer instead of being only browser-cache state.
+    session.state = 'starting';
     await session.context.tracing.start({ screenshots: true, snapshots: true, sources: true });
     session.tracingStarted = true;
+
+    const currentUrl = typeof session.page.url === 'function' ? session.page.url() : session.metadata.targetUrl;
+    const scrollPosition = await session.page
+      .evaluate(() => ({ x: window.scrollX, y: window.scrollY }))
+      .catch(() => ({ x: 0, y: 0 }));
+
+    await session.page.reload({ waitUntil: 'domcontentloaded' });
+    // networkidle is intentionally best-effort: SPAs with polling/websockets
+    // may never become idle, while the resource checks below remain bounded.
+    if (typeof session.page.waitForLoadState === 'function') {
+      await session.page.waitForLoadState('networkidle', { timeout: 10_000 }).catch(() => {});
+    }
+    await session.page
+      .evaluate(async () => {
+        await document.fonts?.ready?.catch?.(() => {});
+        const pendingImages = Array.from(document.images).filter(image => !image.complete);
+        await Promise.race([
+          Promise.all(pendingImages.map(image => new Promise(resolve => {
+            image.addEventListener('load', resolve, { once: true });
+            image.addEventListener('error', resolve, { once: true });
+          }))),
+          new Promise(resolve => setTimeout(resolve, 10_000))
+        ]);
+      })
+      .catch(() => {});
+    if (currentUrl && typeof session.page.url === 'function' && session.page.url() !== currentUrl) {
+      await session.page.goto(currentUrl, { waitUntil: 'domcontentloaded' });
+    }
+    await session.page
+      .evaluate(({ x, y }) => window.scrollTo(x, y), scrollPosition)
+      .catch(() => {});
+
+    session.metadata.targetUrl = currentUrl || session.metadata.targetUrl;
+    session.metadata.userAgent = await session.page
+      .evaluate(() => navigator.userAgent)
+      .catch(() => session.metadata.userAgent);
+    session.metadata.viewport = session.page.viewportSize?.() ?? session.metadata.viewport;
     session.state = 'recording';
     session.lastActivityAt = Date.now();
     session.timer = this.setTimer(() => {
@@ -555,13 +627,19 @@ export class TraceRecorder {
   handlePageControl(session, action) {
     if (action === 'status') return { state: session.state, deviceMode: session.deviceMode };
     if (action === 'toggle-device') return this.toggleDeviceMode(session);
+    if (action === 'screenshot') {
+      if (session.state !== 'recording') return { state: session.state, captured: false };
+      return this.captureScreenshot(session).then(() => ({ state: session.state, captured: true }));
+    }
     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 => this.failSession(session, error));
       }
-      return session.activityPromise.then(() => ({ state: session.state, deviceMode: session.deviceMode }));
+      // Do not hold the page binding open while reload navigates the document.
+      // The toolbar polls status and will switch to recording after the reload.
+      return { state: 'starting', deviceMode: session.deviceMode };
     }
     if (action === 'stop') {
       if (session.state !== 'recording' && session.state !== 'waiting_for_start') {
@@ -576,24 +654,52 @@ export class TraceRecorder {
     return { state: session.state };
   }
 
+  async captureScreenshot(session) {
+    if (!session.tracingStarted || session.state !== 'recording') return;
+    session.stepIndex += 1;
+    let title = '未命名页面';
+    if (typeof session.page.title === 'function') {
+      title = await session.page.title().catch(() => title) || title;
+    }
+    const label = `步骤${session.stepIndex} | ${title}`;
+    await session.context.tracing.group(label);
+    let toolbarHidden = false;
+    try {
+      // Keep the recorder controls out of the user-selected page evidence.
+      await session.page.evaluate(() => {
+        const toolbar = document.querySelector('[data-trace-recorder-toolbar-host]');
+        if (toolbar) {
+          toolbar.setAttribute('data-trace-recorder-hidden', '');
+          toolbar.style.visibility = 'hidden';
+        }
+      });
+      toolbarHidden = true;
+      // page.screenshot is intentionally used inside the Trace group so the
+      // official Viewer records this deliberate visual checkpoint.
+      await session.page.screenshot({ fullPage: false });
+      await session.page.waitForTimeout(1);
+      session.lastActivityAt = Date.now();
+      this.armIdleTimer(session);
+    } finally {
+      if (toolbarHidden) {
+        await session.page.evaluate(() => {
+          const toolbar = document.querySelector('[data-trace-recorder-toolbar-host]');
+          if (toolbar) {
+            toolbar.style.visibility = '';
+            toolbar.removeAttribute('data-trace-recorder-hidden');
+          }
+        }).catch(() => {});
+      }
+      await session.context.tracing.groupEnd();
+    }
+  }
+
   handleUserActivity(session, activity = {}) {
     if (session.state !== 'recording') return undefined;
+    // Page activity is intentionally not recorded as an Action. The operator
+    // explicitly controls collection by pressing the Screenshot button.
     session.lastActivityAt = Date.now();
-    session.pendingActivity = activity;
     this.armIdleTimer(session);
-    if (session.activityDebounceTimer) this.clearTimer(session.activityDebounceTimer);
-    session.activityDebounceTimer = this.setTimer(() => {
-      session.activityDebounceTimer = undefined;
-      const pendingActivity = session.pendingActivity;
-      session.pendingActivity = undefined;
-      session.activityRecordPromise = (session.activityRecordPromise ?? Promise.resolve())
-        .then(() => this.recordActivityStep(session, pendingActivity))
-        .catch(() => {})
-        .finally(() => {
-          session.activityRecordPromise = undefined;
-        });
-    }, USER_ACTIVITY_DEBOUNCE_DELAY);
-    session.activityDebounceTimer?.unref?.();
     return undefined;
   }
 
@@ -602,7 +708,7 @@ export class TraceRecorder {
     session.stepIndex += 1;
     const type = typeof activity.type === 'string' && activity.type ? activity.type : 'unknown';
     const title = typeof activity.title === 'string' && activity.title ? activity.title : '未命名页面';
-    const label = `步骤${session.stepIndex} | ${title} | ${type}`;
+    const label = `步骤${session.stepIndex} | ${title}`;
     await session.context.tracing.group(label);
     try {
       await session.page.waitForTimeout(1);
@@ -617,7 +723,7 @@ export class TraceRecorder {
     if (typeof session.page.title === 'function') {
       title = await session.page.title().catch(() => title) || title;
     }
-    const label = `步骤${session.stepIndex} | ${title} | stop`;
+    const label = `步骤${session.stepIndex} | ${title}`;
     await session.context.tracing.group(label);
     try {
       await session.page.waitForTimeout(1);
@@ -711,7 +817,7 @@ export class TraceRecorder {
   }
 
   async failSession(session, error) {
-    if (session.state !== 'recording' && session.state !== 'waiting_for_start') return;
+    if (!['starting', 'recording', 'waiting_for_start'].includes(session.state)) return;
     session.state = 'failed';
     this.clearTimer(session.timer);
     this.clearTimer(session.idleTimer);

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

@@ -25,6 +25,7 @@ function createFixture(options = {}) {
     reload: async options => calls.push(['reload', options]),
     evaluate: async () => 'Fixture User Agent',
     waitForTimeout: async duration => calls.push(['wait', duration]),
+    screenshot: async options => calls.push(['screenshot', options]),
     viewportSize: () => ({ width: 1280, height: 720 }),
     close: async () => calls.push(['page-close'])
   };
@@ -108,10 +109,17 @@ test('page controls start recording, record activity, upload and clean up one se
   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',
+    state: 'starting',
     deviceMode: 'desktop'
   });
-  assert.equal(calls.some(call => call[0] === 'reload'), false);
+  await recorder.activeSession.activityPromise;
+  assert.equal(recorder.activeSession.state, 'recording');
+  const screenshotResult = await bindings.__traceRecorderControl({}, 'screenshot');
+  assert.deepEqual(screenshotResult, { state: 'recording', captured: true });
+  assert.ok(calls.some(call => call[0] === 'screenshot' && call[1].fullPage === false));
+  assert.ok(calls.some(call => call[0] === 'trace-group' && call[1] === '步骤1 | 未命名页面'));
+  assert.ok(calls.some(call => call[0] === 'reload' && call[1].waitUntil === 'domcontentloaded'));
+  assert.ok(calls.findIndex(call => call[0] === 'trace-start') < calls.findIndex(call => call[0] === 'reload'));
   recorder.handleUserActivity(recorder.activeSession, {
     type: 'click',
     title: '首页功能'
@@ -130,7 +138,7 @@ test('page controls start recording, record activity, upload and clean up one se
   );
   assert.equal(stopped.metadata.title, 'bug3452');
   assert.ok(calls.some(call => call[0] === 'trace-start' && call[1].sources === true));
-  assert.ok(calls.some(call => call[0] === 'trace-group' && call[1] === '步骤1 | 首页功能 | click'));
+  assert.equal(calls.some(call => call[0] === 'trace-group' && call[1].includes('首页功能')), false);
   assert.ok(calls.some(call => call[0] === 'post' && call[1] === '/api/trace-sessions'));
   assert.ok(calls.some(call => call[0] === 'form-append' && call[1] === 'target_url'));
   assert.ok(calls.some(call => call[0] === 'remove' && call[1] === '/tmp/trace-fixture'));
@@ -168,6 +176,7 @@ test('marks the session failed and removes the local trace when upload fails', a
   const { calls, recorder } = createFixture({ uploadError: new Error('upload failed') });
   await recorder.start({ url: 'https://app.example.test' });
   await recorder.handlePageControl(recorder.activeSession, 'start');
+  await recorder.activeSession.activityPromise;
   recorder.handleUserActivity(recorder.activeSession);
 
   await recorder.stop();
@@ -179,6 +188,7 @@ test('automatically stops on timeout and returns that result on the next stop ca
   const { recorder, timer } = createFixture();
   await recorder.start({ url: 'https://app.example.test' });
   await recorder.handlePageControl(recorder.activeSession, 'start');
+  await recorder.activeSession.activityPromise;
   timer.callback();
 
   while (recorder.activeSession) await new Promise(resolve => setImmediate(resolve));
@@ -191,6 +201,7 @@ test('page stop control immediately stops and uploads, then exposes the result t
   const { bindings, recorder } = createFixture();
   await recorder.start({ url: 'https://app.example.test' });
   await bindings.__traceRecorderControl({}, 'start');
+  await recorder.activeSession.activityPromise;
 
   assert.deepEqual(await bindings.__traceRecorderControl({}, 'stop'), { state: 'stopping' });
   while (recorder.activeSession) await new Promise(resolve => setImmediate(resolve));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "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. 告知用户浏览器已打开：默认是 PC 端；如需移动端测试，先点击左下角“切换移动端”（iPhone 14 Pro Max，430×932，DPR 3），再点击“开始录制”；点击开始后才启动 Trace 和计时，不刷新当前页面；操作完成后点击“停止录制”。新打开的页面会继承当前设备模式。连续 2 分钟没有真实操作时服务会自动停止并上传。真实操作经防抖后会在官方 Trace Viewer 中以 `步骤N | 页面标题 | 事件类型` 的分组节点呈现。
+4. 告知用户浏览器已打开：默认是 PC 端；左上角控制栏默认收缩，悬停后展开，移出后自动收回。如需移动端测试，先展开并点击“切换移动端”（iPhone 14 Pro Max，430×932，DPR 3），再点击“开始录制”；点击开始后服务会先启动 Trace、刷新当前 SPA 页面一次并等待 DOM、CSS、字体和图片稳定，随后才进入正式录制计时。刷新期间不要操作页面；页面稳定后按需操作，只有点击“截图”才会保存当前渲染画面，普通点击、输入和滚动不会生成自定义 Action。截图时控制栏会临时隐藏。同一 BrowserContext 会保留 cookies、localStorage 和 sessionStorage，新打开的页面会继承当前设备模式。连续 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` 确定。