@autobest-ui/agent 1.0.22 → 1.0.24

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、刷新一次当前 SPA 页面并等待 DOM、CSS、字体和图片稳定，再进入正式录制；后续用户活动经过防抖后以 `步骤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，临时禁用 Chromium 缓存并刷新一次当前 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;
@@ -172,15 +178,37 @@ function createRecorderPageScript() {
           .start { background: rgba(22, 163, 74, .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;
+          }
+          .screenshot {
+            position: fixed;
+            top: 16px;
+            right: 16px;
+            z-index: 2147483647;
+            min-width: 76px;
+            height: 34px;
+            padding: 0 12px;
+            background: rgba(234, 88, 12, .68);
+            box-shadow: 0 4px 16px rgba(0, 0, 0, .18);
+            backdrop-filter: blur(6px);
+          }
         </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="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>
+        <button class="screenshot" type="button" data-action="screenshot" data-trace-recorder-control>截图</button>
       \`;
       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"]');
 
@@ -189,6 +217,7 @@ function createRecorderPageScript() {
         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 = preparing ? '准备页面' : recording ? '录制中' : '开始录制';
@@ -197,6 +226,7 @@ function createRecorderPageScript() {
       };
       const control = async action => {
         startButton.disabled = true;
+        screenshotButton.disabled = true;
         stopButton.disabled = true;
         try {
           const result = await globalThis.__traceRecorderControl?.(action);
@@ -210,6 +240,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();
@@ -508,25 +543,44 @@ export class TraceRecorder {
       .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(() => {});
+    // The first page load may have populated Chromium's HTTP cache before
+    // tracing started. Disable cache only for this reload so CSS, images and
+    // fonts produce fresh response bodies inside trace.zip.
+    let cacheSession;
+    let cacheWasDisabled = false;
+    try {
+      if (typeof session.context.newCDPSession === 'function') {
+        cacheSession = session.cdpSessions.get(session.page) ?? await session.context.newCDPSession(session.page);
+        session.cdpSessions.set(session.page, cacheSession);
+        await cacheSession.send('Network.enable');
+        await cacheSession.send('Network.setCacheDisabled', { cacheDisabled: true });
+        cacheWasDisabled = true;
+      }
+
+      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(() => {});
+    } finally {
+      if (cacheWasDisabled) {
+        await cacheSession.send('Network.setCacheDisabled', { cacheDisabled: false }).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' });
     }
@@ -603,6 +657,10 @@ 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 };
@@ -626,24 +684,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;
   }
 
@@ -652,7 +738,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);
@@ -667,7 +753,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);

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'])
   };
@@ -113,8 +114,17 @@ test('page controls start recording, record activity, upload and clean up one se
   });
   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'));
+  const cacheOnIndex = calls.findIndex(call => call[0] === 'cdp' && call[1] === 'Network.setCacheDisabled' && call[2].cacheDisabled === true);
+  const reloadIndex = calls.findIndex(call => call[0] === 'reload');
+  const cacheOffIndex = calls.findIndex(call => call[0] === 'cdp' && call[1] === 'Network.setCacheDisabled' && call[2].cacheDisabled === false);
+  assert.ok(cacheOnIndex < reloadIndex);
+  assert.ok(reloadIndex < cacheOffIndex);
   recorder.handleUserActivity(recorder.activeSession, {
     type: 'click',
     title: '首页功能'
@@ -133,7 +143,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'));

package/package.json

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