@autobest-ui/agent 1.0.15 → 1.0.16

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；后续用户活动经过防抖后写入轻量 Playwright Action，空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
+`trace-mcp-recorder` 是基于 `@modelcontextprotocol/sdk` 和 `StdioServerTransport` 的 Node.js MCP Server。它打开非无头 Chromium 供测试人员手动操作，页面加载后等待第一次真实用户操作才启动 Trace；后续用户活动经过防抖后以 `步骤N | 页面标题 | 事件类型` 的 Trace Group 写入轻量 Playwright Action，空闲超过 2 分钟自动结束，然后上传原生 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
 
 ## 安装与启动
 
@@ -43,7 +43,7 @@ npm start
 
 录制超时后服务自动停止并自动上传（无需人工确认），随后第一次人工调用 `stop_trace_recording` 会取回自动停止的结果；再调用则返回没有活动会话。
 
-Trace 在第一次真实用户操作后才开始计时。连续用户操作停止 800ms 后写入一个轻量 `waitForTimeout(1)` Trace Action；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。
+Trace 在第一次真实用户操作后才开始计时。连续用户操作停止 800ms 后写入一个带自定义名称的 `tracing.group()`，组内使用 `waitForTimeout(1)` 推进官方 Viewer 播放；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。官方 Viewer 的具体显示可能是 Group 标签或 Group 内嵌 Wait 节点，取决于 Viewer 版本。
 
 ## 后端接口契约
 

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

@@ -105,11 +105,14 @@ function toolError(error) {
 // details; it uses the signal to control Trace timing and debounce checkpoints.
 function createUserActivityScript() {
   return `(() => {
-    const notify = () => Promise.resolve(globalThis.__traceRecorderUserActivity?.()).catch(() => {});
+    const notify = type => Promise.resolve(globalThis.__traceRecorderUserActivity?.({
+      type,
+      title: document.title || '未命名页面'
+    })).catch(() => {});
     const options = { capture: true, passive: true };
-    for (const type of ['pointerdown', 'keydown', 'input', 'change', 'wheel', 'touchstart']) {
+    for (const type of ['click', 'keydown', 'input', 'change', 'wheel', 'touchstart']) {
       document.addEventListener(type, event => {
-        if (event.isTrusted) notify();
+        if (event.isTrusted) notify(type);
       }, options);
     }
   })();`;
@@ -178,8 +181,8 @@ export class TraceRecorder {
       context = await browser.newContext();
       let session;
       if (typeof context.exposeBinding === 'function') {
-        await context.exposeBinding('__traceRecorderUserActivity', () => {
-          if (session) return this.handleUserActivity(session);
+        await context.exposeBinding('__traceRecorderUserActivity', (_source, activity) => {
+          if (session) return this.handleUserActivity(session, activity);
           return undefined;
         });
       }
@@ -217,6 +220,9 @@ export class TraceRecorder {
         idleTimer: undefined,
         activityDebounceTimer: undefined,
         activityPromise: undefined,
+        activityRecordPromise: undefined,
+        pendingActivity: undefined,
+        stepIndex: 0,
         tracingStarted: false,
         lastActivityAt: undefined
       };
@@ -265,9 +271,26 @@ export class TraceRecorder {
       throw new Error('录制会话正在启动，请等待 start_trace_recording 返回后再停止');
     }
     if (session.state === 'waiting_for_activity') {
+      session.state = 'stopping';
+      this.clearTimer(session.timer);
+      this.clearTimer(session.idleTimer);
+      this.clearTimer(session.activityDebounceTimer);
+      await session.activityPromise?.catch(() => {});
+      if (session.tracingStarted) {
+        session.stopPromise = this.prepareSession(session).finally(() => {
+          session.stopPromise = undefined;
+        });
+        const prepared = await session.stopPromise;
+        if (trigger === 'timeout' || confirm === 'upload') return this.uploadSession(session, trigger);
+        return prepared;
+      }
       await this.closeResources({ page: session.page, context: session.context, browser: session.browser });
       if (this.activeSession === session) this.activeSession = undefined;
-      throw new Error('尚未检测到真实用户操作，未生成 trace');
+      return {
+        state: 'not_started',
+        uploaded: false,
+        message: '录制已停止。停止前未检测到真实用户操作，因此没有生成可上传的 trace。'
+      };
     }
     if (session.state === 'recording') {
       if (session.stopPromise) return session.stopPromise;
@@ -299,7 +322,8 @@ export class TraceRecorder {
   async prepareSession(session) {
     try {
       await session.activityPromise?.catch(() => {});
-      if (session.tracingStarted) await session.page.waitForTimeout(1).catch(() => {});
+      await session.activityRecordPromise?.catch(() => {});
+      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 });
       session.state = 'awaiting_upload';
@@ -315,7 +339,7 @@ export class TraceRecorder {
     }
   }
 
-  async beginRecording(session) {
+  async beginRecording(session, activity = {}) {
     if (session.tracingStarted || session.state !== 'waiting_for_activity') return;
     await session.context.tracing.start({ screenshots: true, snapshots: true, sources: true });
     session.tracingStarted = true;
@@ -329,13 +353,13 @@ export class TraceRecorder {
     }, session.maxRecordDuration);
     session.timer?.unref?.();
     this.armIdleTimer(session);
-    await session.page.waitForTimeout(1);
+    await this.recordActivityStep(session, activity);
   }
 
-  handleUserActivity(session) {
+  handleUserActivity(session, activity = {}) {
     if (session.state === 'waiting_for_activity') {
       if (session.activityPromise) return session.activityPromise;
-      session.activityPromise = this.beginRecording(session).catch(error => {
+      session.activityPromise = this.beginRecording(session, activity).catch(error => {
         session.state = 'failed';
         throw error;
       });
@@ -343,16 +367,53 @@ export class TraceRecorder {
     }
     if (session.state !== 'recording') return undefined;
     session.lastActivityAt = Date.now();
+    session.pendingActivity = activity;
     this.armIdleTimer(session);
     if (session.activityDebounceTimer) this.clearTimer(session.activityDebounceTimer);
     session.activityDebounceTimer = this.setTimer(() => {
       session.activityDebounceTimer = undefined;
-      session.activityPromise = session.page.waitForTimeout(1).catch(() => {});
+      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;
   }
 
+  async recordActivityStep(session, activity = {}) {
+    if (!session.tracingStarted || session.state !== 'recording') 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 : '未命名页面';
+    const label = `步骤${session.stepIndex} | ${title} | ${type}`;
+    await session.context.tracing.group(label);
+    try {
+      await session.page.waitForTimeout(1);
+    } finally {
+      await session.context.tracing.groupEnd();
+    }
+  }
+
+  async recordFinalStep(session) {
+    session.stepIndex += 1;
+    let title = '未命名页面';
+    if (typeof session.page.title === 'function') {
+      title = await session.page.title().catch(() => title) || title;
+    }
+    const label = `步骤${session.stepIndex} | ${title} | stop`;
+    await session.context.tracing.group(label);
+    try {
+      await session.page.waitForTimeout(1);
+    } finally {
+      await session.context.tracing.groupEnd();
+    }
+  }
+
   armIdleTimer(session) {
     this.clearTimer(session.idleTimer);
     session.idleTimer = this.setTimer(() => {

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

@@ -15,7 +15,9 @@ function createFixture(options = {}) {
   const browser = new EventEmitter();
   const tracing = {
     start: async options => calls.push(['trace-start', options]),
-    stop: async options => calls.push(['trace-stop', options])
+    stop: async options => calls.push(['trace-stop', options]),
+    group: async label => calls.push(['trace-group', label]),
+    groupEnd: async () => calls.push(['trace-group-end'])
   };
   const page = {
     goto: async url => calls.push(['goto', url]),
@@ -93,7 +95,10 @@ 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 recorder.handleUserActivity(recorder.activeSession, {
+    type: 'click',
+    title: '首页功能'
+  });
   await assert.rejects(
     recorder.start({ url: 'https://app.example.test/another' }),
     /已有录制任务/
@@ -108,6 +113,7 @@ test('starts, records metadata, uploads, completes and cleans up one session', a
   );
   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.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'));
@@ -118,6 +124,19 @@ test('rejects missing configuration before contacting the backend', async () =>
   await assert.rejects(recorder.start({ url: 'https://app.example.test' }), /BACKEND_BASE_URL/);
 });
 
+test('stops waiting sessions immediately without reporting an error', async () => {
+  const { recorder, calls } = createFixture();
+  await recorder.start({ url: 'https://app.example.test' });
+  const result = await recorder.stop();
+  assert.deepEqual(result, {
+    state: 'not_started',
+    uploaded: false,
+    message: '录制已停止。停止前未检测到真实用户操作，因此没有生成可上传的 trace。'
+  });
+  assert.equal(recorder.activeSession, undefined);
+  assert.ok(calls.some(call => call[0] === 'browser-close'));
+});
+
 test('cleans up when Chromium launch fails without a backend session', async () => {
   const { calls, recorder } = createFixture();
   recorder.launchChromium = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "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` 和最大录制时长；Trace 会在第一次真实操作时开始计时，不要代替用户操作页面。连续 2 分钟没有真实操作时服务会自动停止并上传。
+4. 告知用户浏览器已打开、正在等待首次真实操作，并保留工具返回的 `uuid` 和最大录制时长；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` 确定。
 
@@ -22,4 +22,6 @@ description: 通过 trace-mcp-recorder 启动或停止 Playwright Trace 人工
 
 用户表达“停止录制”“结束 trace”“完成录制”等意图时，调用 `stop_trace_recording`。第一次调用只会停止录制并询问是否上传；不要擅自上传。用户明确回答“上传”后，再次调用 `stop_trace_recording` 并传入 `confirm=upload`。用户回答“不上传”时，调用该工具并传入 `confirm=cancel`。上传成功后，将回放链接和 `version`、`title`、`operator`、`browserVersion` 整理给用户。
 
+停止调用必须以工具本次返回结果为准，不要根据启动时的 `waiting_for_activity` 提示推断最终状态。若工具返回 `state=not_started`，应说明本次没有检测到真实操作且没有生成 trace；若返回上传结果，则只整理上传返回的回放链接。
+
 若工具返回错误，如没有活动会话、后端不可达或上传失败，原样说明关键原因，不编造回放链接。