@autobest-ui/agent 1.0.15 → 1.0.17

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 链接。同一进程同一时间只允许一个录制任务。
 
 ## 安装与启动
 
@@ -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`。该工具打开页面，但点击页面左下角“开始录制”后才真正启动 Trace。`url` 独立确定被测页面；`title` 是录制标题或功能描述，也可以直接填写 `bug3452` 这类 Bug 编号。系统不额外传递独立的 Bug 字段。MCP 认证上下文中的 `operator`、`name` 或 `preferred_username` 优先于参数。
 - `stop_trace_recording`：首次调用不传参数，只停止 trace 并询问是否上传；用户确认后传 `confirm=upload`，取消时传 `confirm=cancel`。上传成功后返回回放链接及版本、标题、操作人、浏览器版本。
 
 录制超时后服务自动停止并自动上传（无需人工确认），随后第一次人工调用 `stop_trace_recording` 会取回自动停止的结果；再调用则返回没有活动会话。
 
-Trace 在第一次真实用户操作后才开始计时。连续用户操作停止 800ms 后写入一个轻量 `waitForTimeout(1)` Trace Action；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。
+Trace 在点击页面左下角“开始录制”后才开始计时；点击“停止录制”会立即停止并自动上传，随后可通过 `stop_trace_recording` 取回回放链接。控制按钮的点击不会写入操作步骤。连续用户操作停止 800ms 后写入一个带自定义名称的 `tracing.group()`，组内使用 `waitForTimeout(1)` 推进官方 Viewer 播放；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。官方 Viewer 的具体显示可能是 Group 标签或 Group 内嵌 Wait 节点，取决于 Viewer 版本。
 
 ## 后端接口契约
 

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

@@ -101,17 +101,122 @@ 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 `(() => {
-    const notify = () => Promise.resolve(globalThis.__traceRecorderUserActivity?.()).catch(() => {});
+    if (window !== window.top) return;
+    const controlAttribute = 'data-trace-recorder-control';
+    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();
+        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); }
+        </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>
+        </div>
+      \`;
+      document.documentElement.append(host);
+      const startButton = shadow.querySelector('[data-action="start"]');
+      const stopButton = shadow.querySelector('[data-action="stop"]');
+
+      const render = state => {
+        const recording = state === 'recording';
+        const waiting = state === 'waiting_for_start';
+        startButton.disabled = !waiting;
+        stopButton.disabled = !recording && !waiting;
+        startButton.textContent = recording ? '录制中' : '开始录制';
+        stopButton.textContent = state === 'stopping' || state === 'uploading' ? '正在停止' : '停止录制';
+      };
+      const control = async action => {
+        startButton.disabled = true;
+        stopButton.disabled = true;
+        try {
+          const result = await globalThis.__traceRecorderControl?.(action);
+          render(result?.state);
+        } catch {
+          render('waiting_for_start');
+        }
+      };
+      startButton.addEventListener('click', event => {
+        event.preventDefault();
+        event.stopPropagation();
+        void control('start');
+      });
+      stopButton.addEventListener('click', event => {
+        event.preventDefault();
+        event.stopPropagation();
+        render('stopping');
+        void control('stop');
+      });
+
+      const syncState = () => {
+        void Promise.resolve(globalThis.__traceRecorderControl?.('status'))
+          .then(result => render(result?.state))
+          .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();
+    }
   })();`;
 }
 
@@ -178,13 +283,17 @@ 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;
         });
+        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);
@@ -210,20 +319,23 @@ 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,
         idleTimer: undefined,
         activityDebounceTimer: undefined,
         activityPromise: undefined,
+        activityRecordPromise: undefined,
+        pendingActivity: undefined,
+        stepIndex: 0,
         tracingStarted: false,
         lastActivityAt: undefined
       };
       this.activeSession = session;
 
       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));
@@ -233,7 +345,7 @@ export class TraceRecorder {
       browser.once('disconnected', failOnBrowserExit);
 
       return {
-        message: '浏览器已打开，等待首次真实操作后开始录制；完成后调用 stop_trace_recording',
+        message: '浏览器已打开，请点击页面左下角“开始录制”；操作完成后点击“停止录制”，服务将自动上传。',
         maxRecordDuration: configuration.maxRecordDuration,
         metadata
       };
@@ -264,10 +376,29 @@ 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);
+      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');
+      const result = {
+        state: 'not_started',
+        uploaded: false,
+        message: '录制已停止。停止前未点击“开始录制”，因此没有生成可上传的 trace。'
+      };
+      if (trigger !== 'manual') this.lastAutomaticResult = result;
+      return result;
     }
     if (session.state === 'recording') {
       if (session.stopPromise) return session.stopPromise;
@@ -299,7 +430,13 @@ 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.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 });
       session.state = 'awaiting_upload';
@@ -316,7 +453,7 @@ export class TraceRecorder {
   }
 
   async beginRecording(session) {
-    if (session.tracingStarted || session.state !== 'waiting_for_activity') return;
+    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';
@@ -329,30 +466,84 @@ export class TraceRecorder {
     }, session.maxRecordDuration);
     session.timer?.unref?.();
     this.armIdleTimer(session);
-    await session.page.waitForTimeout(1);
   }
 
-  handleUserActivity(session) {
-    if (session.state === 'waiting_for_activity') {
-      if (session.activityPromise) return session.activityPromise;
-      session.activityPromise = this.beginRecording(session).catch(error => {
-        session.state = 'failed';
-        throw error;
+  handlePageControl(session, action) {
+    if (action === 'status') return { state: session.state };
+    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 }));
+    }
+    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;
     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 || !['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 : '未命名页面';
+    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(() => {
@@ -408,12 +599,12 @@ export class TraceRecorder {
         }
       };
       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;
@@ -433,7 +624,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);
@@ -477,8 +668,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.'
     }
   );
 
@@ -486,7 +677,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,10 +12,13 @@ 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]),
-    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]),
@@ -26,6 +29,11 @@ function createFixture(options = {}) {
   };
   const context = {
     tracing,
+    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'])
   };
@@ -75,11 +83,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',
@@ -93,7 +101,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' });
+  recorder.handleUserActivity(recorder.activeSession, {
+    type: 'click',
+    title: '首页功能'
+  });
   await assert.rejects(
     recorder.start({ url: 'https://app.example.test/another' }),
     /已有录制任务/
@@ -108,6 +122,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 +133,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 () => {
@@ -131,7 +159,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/);
@@ -141,7 +170,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));
@@ -150,6 +179,19 @@ 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('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/package.json

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

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

@@ -14,12 +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 分钟没有真实操作时服务会自动停止并上传。
+4. 告知用户浏览器已打开：先点击页面左下角“开始录制”，操作完成后点击“停止录制”。不要代替用户点击按钮或操作页面。点击开始后才启动 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` 读取这次按钮停止的结果，并整理回放链接和元数据。
+
+用户表达“停止录制”“结束 trace”“完成录制”等意图时，调用 `stop_trace_recording`。单独输入“停止录制”时首次调用不传 `confirm`，停止并询问是否上传；用户明确回答“上传”后，再次调用并传入 `confirm=upload`。用户直接输入“停止录制 & 上传”或等价表达时，停止调用直接传入 `confirm=upload`。用户回答“不上传”时，调用该工具并传入 `confirm=cancel`。上传成功后，将回放链接和 `version`、`title`、`operator`、`browserVersion` 整理给用户。
+
+停止调用必须以工具本次返回结果为准，不要根据启动时的 `waiting_for_start` 提示推断最终状态。若工具返回 `state=not_started`，应说明本次没有点击“开始录制”且没有生成 trace；若返回上传结果，则只整理上传返回的回放链接。
 
 若工具返回错误，如没有活动会话、后端不可达或上传失败，原样说明关键原因，不编造回放链接。