@autobest-ui/agent 1.0.21 → 1.0.22

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，并在页面左下角注入半透明的“开始录制”“停止录制”和设备切换按钮供测试人员手动控制 Trace；默认是 PC 端，也可切换为 iPhone 14 Pro Max 移动端模拟。页面先正常打开并等待，点击开始后先启动 Trace、刷新一次当前 SPA 页面并等待 DOM、CSS、字体和图片稳定，再进入正式录制；后续用户活动经过防抖后以 `步骤N | 页面标题 | 事件类型` 的 Trace Group 写入轻量 Playwright Action，空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
 
 ## 安装与启动
 

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

@@ -187,10 +187,11 @@ function createRecorderPageScript() {
       const render = (state, deviceMode = 'desktop') => {
         const recording = state === 'recording';
         const waiting = state === 'waiting_for_start';
+        const preparing = state === 'starting';
         startButton.disabled = !waiting;
         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 端' : '切换移动端';
       };
@@ -409,7 +410,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 +496,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(() => {
@@ -561,7 +609,9 @@ export class TraceRecorder {
       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') {
@@ -711,7 +761,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

@@ -108,10 +108,13 @@ 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');
+  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: '首页功能'
@@ -168,6 +171,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 +183,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 +196,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.22",
   "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、字体和图片稳定，随后才进入正式录制计时。刷新期间不要操作页面；完成后点击“停止录制”。同一 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` 确定。