@autobest-ui/agent 1.0.28 → 1.0.29

package/mcp/trace-mcp-recorder/README.md

@@ -27,6 +27,93 @@ npm start
 
 配套 Skill 位于 `../../skills/common/trace-recorder/`，由 `autobest-agent-sync common` 安装，并作为 `skill://trace-recorder/SKILL.md` MCP 资源提供。Skill 的 `agents/openai.yaml` 声明了对 `trace-mcp-recorder` 的工具依赖。
 
+### Skill 如何使用
+
+Skill 不是需要单独运行的服务。完成 MCP 配置并重启 Codex 后，在对话中使用 `$trace-recorder` 或直接描述录制意图，Codex 会按照 Skill 规则调用 `trace-mcp-recorder` 的 MCP 工具。
+
+启动示例：
+
+```text
+$trace-recorder 启动 Playwright trace，访问 https://cpd.dev.autobestdevops.com，version=v2.1.0，title=首页功能02，operator=张三
+```
+
+也可以不写 Skill 名称：
+
+```text
+请打开 https://cpd.dev.autobestdevops.com 进行 Trace 录制，版本 v2.1.0，标题为首页功能02，操作人张三
+```
+
+Codex 会调用 `start_trace_recording`，打开可见 Chromium。浏览器打开后：
+
+1. 默认使用 PC viewport `1400×740`；需要移动端时点击“切换移动端”。
+2. 点击“开始录制”，服务会启动 Trace、临时禁用缓存并刷新页面，等待页面资源稳定。
+3. 页面稳定后手动操作。普通点击、输入和滚动不会生成自定义步骤。
+4. 需要保留某个页面状态时，点击“画笔”标注，再点击“截图”；截图步骤显示为 `步骤N | 页面标题`。
+5. 录制完成后点击“停止录制”，或在 Codex 中发送停止命令。
+
+停止示例：
+
+```text
+$trace-recorder 停止录制
+```
+
+首次停止会生成 trace 并询问是否上传：
+
+```text
+$trace-recorder 上传录制内容
+```
+
+也可以一步完成：
+
+```text
+$trace-recorder 停止录制并上传
+```
+
+Skill 会把上传返回的回放链接以及版本、标题、操作人、浏览器版本整理返回。若用户只点击页面上的“停止录制”，服务会自动上传，随后在 Codex 中发送“获取回放链接”即可取回结果。
+
+### MCP 工具直接调用
+
+需要绕过自然语言 Skill 时，可直接调用两个 MCP 工具：
+
+```json
+{
+  "name": "start_trace_recording",
+  "arguments": {
+    "url": "https://cpd.dev.autobestdevops.com",
+    "version": "v2.1.0",
+    "title": "首页功能02",
+    "operator": "张三"
+  }
+}
+```
+
+停止并先询问上传：
+
+```json
+{
+  "name": "stop_trace_recording",
+  "arguments": {}
+}
+```
+
+确认上传：
+
+```json
+{
+  "name": "stop_trace_recording",
+  "arguments": { "confirm": "upload" }
+}
+```
+
+取消上传：
+
+```json
+{
+  "name": "stop_trace_recording",
+  "arguments": { "confirm": "cancel" }
+}
+```
+
 ## 环境变量
 
 | 变量 | 默认值 | 说明 |
@@ -34,16 +121,18 @@ npm start
 | `BACKEND_BASE_URL` | 无，必填 | 私有后端基础地址，必须为 HTTP(S) URL |
 | `MAX_RECORD_DURATION` | `1800000` | 最大录制时长，单位毫秒；超时后自动停止并上传 |
 
+页面初始导航、录制开始后的刷新以及路由恢复导航超时均为 1 小时；`MAX_RECORD_DURATION` 只控制录制时长，不控制页面导航。
+
 回放链接按 `${BACKEND_BASE_URL}/trace-viewer/?trace=${fileUrl}` 生成。服务地址、域名和端口均来自 `BACKEND_BASE_URL`。
 
 ## MCP 工具
 
-- `start_trace_recording`：参数为必填 `url` 和可选 `version`、`title`、`operator`。该工具打开页面，默认 PC 端；点击左下角“切换移动端”可使用 iPhone 14 Pro Max（430×932、DPR 3、触摸、iPhone User-Agent）模拟，点击“开始录制”后才真正启动 Trace。`url` 独立确定被测页面；`title` 是录制标题或功能描述，也可以直接填写 `bug3452` 这类 Bug 编号。系统不额外传递独立的 Bug 字段。MCP 认证上下文中的 `operator`、`name` 或 `preferred_username` 优先于参数。
+- `start_trace_recording`：参数为必填 `url` 和可选 `version`、`title`、`operator`。该工具打开页面，默认 PC 端；点击左下角按钮可在 PC 与 iPhone 14 Pro Max（430×932、DPR 3、触摸、iPhone User-Agent）之间来回切换。切换可以发生在录制过程中，当前页面会立即调整为对应 viewport，后续截图按当前模式生成。点击“开始录制”后才真正启动 Trace。`url` 独立确定被测页面；`title` 是录制标题或功能描述，也可以直接填写 `bug3452` 这类 Bug 编号。系统不额外传递独立的 Bug 字段。MCP 认证上下文中的 `operator`、`name` 或 `preferred_username` 优先于参数。
 - `stop_trace_recording`：首次调用不传参数，只停止 trace 并询问是否上传；用户确认后传 `confirm=upload`，取消时传 `confirm=cancel`。上传成功后返回回放链接及版本、标题、操作人、浏览器版本。
 
 录制超时后服务自动停止并自动上传（无需人工确认），随后第一次人工调用 `stop_trace_recording` 会取回自动停止的结果；再调用则返回没有活动会话。
 
-Trace 在点击页面左下角“开始录制”后先刷新页面，再开始计时；点击“停止录制”会立即停止并自动上传，随后可通过 `stop_trace_recording` 取回回放链接。设备切换和录制控制按钮不会写入操作步骤；新打开的页面会继承当前设备模式。连续用户操作停止 800ms 后写入一个带自定义名称的 `tracing.group()`，组内使用 `waitForTimeout(1)` 推进官方 Viewer 播放；连续 2 分钟没有真实用户操作时自动停止并上传。停止录制时会补一个最终 Action。页面自身的轮播、动画和图片加载不会触发录制节点。官方 Viewer 的具体显示可能是 Group 标签或 Group 内嵌 Wait 节点，取决于 Viewer 版本。
+Trace 在点击页面左下角“开始录制”后先临时禁用缓存并刷新页面，等待资源稳定后再开始计时；点击“停止录制”会停止并自动上传，随后可通过 `stop_trace_recording` 取回回放链接。设备切换和录制控制按钮不会写入操作步骤；新打开的页面会继承当前设备模式。普通点击、输入、滚动、动画和图片加载不会生成自定义步骤，只有点击“截图”才会创建一个 `tracing.group()`，组名为 `步骤N | 页面标题`，组内保存当前页面截图并使用 `waitForTimeout(1)` 推进官方 Viewer 播放。画笔使用 SVG 路径覆盖层，截图时会带上标注；退出画笔会清空已有标注。连续 2 分钟没有页面活动时自动停止并上传。官方 Viewer 的具体显示可能是 Group 标签或 Group 内嵌 screenshot/Wait 节点，取决于 Viewer 版本。
 
 ## 后端接口契约
 

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

@@ -13,6 +13,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 
 const DEFAULT_MAX_RECORD_DURATION = 1_800_000;
+const PAGE_NAVIGATION_TIMEOUT = 3_600_000;
 const USER_ACTIVITY_DEBOUNCE_DELAY = 800;
 const IDLE_STOP_DELAY = 120_000;
 const DESKTOP_VIEWPORT = { width: 1400, height: 740 };
@@ -313,10 +314,12 @@ function createRecorderPageScript() {
       toolbar.addEventListener('pointercancel', stopDragging);
       renderAnnotation();
 
-      const render = (state, deviceMode = 'desktop') => {
+      let currentDeviceMode = 'desktop';
+      const render = (state, deviceMode) => {
         const recording = state === 'recording';
         const waiting = state === 'waiting_for_start';
         const preparing = state === 'starting';
+        currentDeviceMode = deviceMode ?? currentDeviceMode;
         annotationEnabled = recording;
         if (!annotationEnabled) penEnabled = false;
         renderAnnotation();
@@ -326,7 +329,7 @@ function createRecorderPageScript() {
         deviceButton.disabled = state === 'starting' || state === 'stopping' || state === 'uploading';
         startButton.textContent = preparing ? '准备页面' : recording ? '录制中' : '开始录制';
         stopButton.textContent = state === 'stopping' || state === 'uploading' ? '正在停止' : '停止录制';
-        deviceButton.textContent = deviceMode === 'mobile' ? '切换 PC 端' : '切换移动端';
+        deviceButton.textContent = currentDeviceMode === 'mobile' ? '移动端已启用' : '切换移动端';
       };
       const control = async action => {
         startButton.disabled = true;
@@ -336,7 +339,7 @@ function createRecorderPageScript() {
           const result = await globalThis.__traceRecorderControl?.(action);
           render(result?.state, result?.deviceMode);
         } catch {
-          render('waiting_for_start', 'desktop');
+        render('waiting_for_start');
         }
       };
       startButton.addEventListener('click', event => {
@@ -455,7 +458,7 @@ export class TraceRecorder {
         await context.addInitScript({ content: createRecorderPageScript() });
       }
       page = await context.newPage();
-      await page.goto(targetUrl);
+      await page.goto(targetUrl, { timeout: PAGE_NAVIGATION_TIMEOUT });
 
       const metadata = {
         version: sessionInput.version,
@@ -661,7 +664,7 @@ export class TraceRecorder {
         cacheWasDisabled = true;
       }
 
-      await session.page.reload({ waitUntil: 'domcontentloaded' });
+      await session.page.reload({ waitUntil: 'domcontentloaded', timeout: PAGE_NAVIGATION_TIMEOUT });
       // 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') {
@@ -686,7 +689,12 @@ export class TraceRecorder {
       }
     }
     if (currentUrl && typeof session.page.url === 'function' && session.page.url() !== currentUrl) {
-      await session.page.goto(currentUrl, { waitUntil: 'domcontentloaded' });
+      await session.page.goto(currentUrl, { waitUntil: 'domcontentloaded', timeout: PAGE_NAVIGATION_TIMEOUT });
+    }
+    // A reload can reset parts of Chromium's emulation state. Re-apply the
+    // selected device after all navigation and resource loading has finished.
+    if (session.deviceMode === 'mobile') {
+      await this.applyDeviceMode(session, session.page, 'mobile');
     }
     await session.page
       .evaluate(({ x, y }) => window.scrollTo(x, y), scrollPosition)
@@ -711,8 +719,17 @@ export class TraceRecorder {
 
   async applyDeviceMode(session, page, mode) {
     if (mode === 'desktop') {
+      await page.setViewportSize?.({ ...DESKTOP_VIEWPORT });
       if (typeof session.context.newCDPSession !== 'function') return;
     }
+    if (mode === 'mobile') {
+      // CDP changes the mobile UA/touch model; setViewportSize also changes
+      // Playwright's screenshot dimensions from the desktop context size.
+      await page.setViewportSize?.({
+        width: IPHONE_14_PRO_MAX_DEVICE.width,
+        height: IPHONE_14_PRO_MAX_DEVICE.height
+      });
+    }
     if (typeof session.context.newCDPSession !== 'function') {
       throw new Error('当前浏览器不支持移动端 CDP 模拟');
     }
@@ -763,7 +780,11 @@ export class TraceRecorder {
     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 }));
+      return this.captureScreenshot(session).then(() => ({
+        state: session.state,
+        deviceMode: session.deviceMode,
+        captured: true
+      }));
     }
     if (action === 'start') {
       if (session.state === 'recording') return { state: session.state };
@@ -790,6 +811,12 @@ export class TraceRecorder {
 
   async captureScreenshot(session) {
     if (!session.tracingStarted || session.state !== 'recording') return;
+    // Re-assert the live device mode immediately before capture. This is
+    // needed when the user switches devices after recording has started.
+    await this.applyDeviceMode(session, session.page, session.deviceMode);
+    session.metadata.viewport = session.deviceMode === 'mobile'
+      ? { width: IPHONE_14_PRO_MAX_DEVICE.width, height: IPHONE_14_PRO_MAX_DEVICE.height }
+      : { ...DESKTOP_VIEWPORT };
     session.stepIndex += 1;
     let title = '未命名页面';
     if (typeof session.page.title === 'function') {

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

@@ -21,8 +21,9 @@ function createFixture(options = {}) {
     groupEnd: async () => calls.push(['trace-group-end'])
   };
   const page = {
-    goto: async url => calls.push(['goto', url]),
+    goto: async (url, options) => calls.push(['goto', url, options]),
     reload: async options => calls.push(['reload', options]),
+    setViewportSize: async viewport => calls.push(['viewport', viewport]),
     evaluate: async () => 'Fixture User Agent',
     waitForTimeout: async duration => calls.push(['wait', duration]),
     screenshot: async options => calls.push(['screenshot', options]),
@@ -42,7 +43,10 @@ function createFixture(options = {}) {
     newPage: async () => page,
     close: async () => calls.push(['context-close'])
   };
-  browser.newContext = async () => context;
+  browser.newContext = async options => {
+    calls.push(['new-context', options]);
+    return context;
+  };
   browser.version = () => 'Fixture Chromium 1';
   browser.close = async () => calls.push(['browser-close']);
 
@@ -106,6 +110,9 @@ test('page controls start recording, record activity, upload and clean up one se
   assert.equal(started.uuid, undefined);
   assert.equal(started.metadata.operator, '上下文操作人');
   assert.equal(started.metadata.browserVersion, 'Fixture Chromium 1');
+  assert.equal(calls.find(call => call[0] === 'goto')[1], 'https://app.example.test/login');
+  assert.equal(calls.find(call => call[0] === 'goto')[2].timeout, 3_600_000);
+  assert.deepEqual(calls.find(call => call[0] === 'new-context')[1].viewport, { width: 1400, height: 740 });
   assert.equal(calls.some(call => call[0] === 'trace-start'), false);
   assert.match(calls.find(call => call[0] === 'init-script')[1].content, /开始录制/);
   assert.match(calls.find(call => call[0] === 'init-script')[1].content, /data-trace-recorder-annotation/);
@@ -118,7 +125,7 @@ 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.deepEqual(screenshotResult, { state: 'recording', deviceMode: 'desktop', 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'));
@@ -219,7 +226,7 @@ test('page stop control immediately stops and uploads, then exposes the result t
   assert.match(result.replayLink, /trace-viewer/);
 });
 
-test('toggles desktop and iPhone 14 Pro Max emulation in the same session', async () => {
+test('switches between PC and iPhone 14 Pro Max during one session', async () => {
   const { bindings, calls, recorder } = createFixture();
   await recorder.start({ url: 'https://app.example.test' });
 
@@ -230,6 +237,7 @@ test('toggles desktop and iPhone 14 Pro Max emulation in the same session', asyn
     deviceName: 'iPhone 14 Pro Max'
   });
   assert.ok(calls.some(call => call[0] === 'cdp' && call[1] === 'Emulation.setDeviceMetricsOverride'));
+  assert.ok(calls.some(call => call[0] === 'viewport' && call[1].width === 430 && call[1].height === 932));
   assert.deepEqual(recorder.activeSession.metadata.viewport, { width: 430, height: 932 });
   assert.match(recorder.activeSession.metadata.userAgent, /iPhone/);
 
@@ -237,6 +245,7 @@ test('toggles desktop and iPhone 14 Pro Max emulation in the same session', asyn
   assert.equal(desktop.deviceMode, 'desktop');
   assert.ok(calls.some(call => call[0] === 'cdp' && call[1] === 'Emulation.clearDeviceMetricsOverride'));
   assert.equal(recorder.activeSession.metadata.userAgent, 'Fixture User Agent');
+  assert.deepEqual(recorder.activeSession.metadata.viewport, { width: 1400, height: 740 });
 
   await recorder.stop();
 });

package/package.json

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

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

@@ -14,10 +14,40 @@ description: 通过 trace-mcp-recorder 启动或停止 Playwright Trace 人工
 1. 从原话提取 `url`、`version`、`title`、`operator`。支持 `key=value` 和自然语言表达，不改写用户给出的值。
 2. `url` 必填；缺少时只询问目标页面地址。其他字段缺失时不要阻断录制。
 3. 调用 `start_trace_recording`，只传入用户明确提供的可选字段。服务端会优先使用 MCP 上下文中的操作人身份。
-4. 告知用户浏览器已打开：默认是 PC 端（viewport 1400×740）；左下角显示可拖拽的 2×2 半透明控制栏，第一行是“开始录制”“停止录制”，第二行是“切换移动端”“截图”，下方提供“画笔”“撤销”“清空”。画笔使用 SVG 路径覆盖层，开启后可用鼠标或触摸标注页面；点击“退出画笔”会立即关闭并清空已有标注，避免后续页面操作继续带着旧标注，截图会带上标注。先点击“切换移动端”（iPhone 14 Pro Max，430×932，DPR 3）或保持 PC 端，再点击“开始录制”；点击开始后服务会先启动 Trace，临时禁用 Chromium 缓存并刷新当前 SPA 页面，等待 DOM、CSS、字体和图片稳定后恢复缓存，随后才进入正式录制计时。刷新期间不要操作页面；页面稳定后按需操作，只有点击“截图”才会保存当前渲染画面，普通点击、输入和滚动不会生成自定义 Action。截图时所有控制按钮会临时隐藏。同一 BrowserContext 会保留 cookies、localStorage 和 sessionStorage，新打开的页面会继承当前设备模式。连续 2 分钟没有页面活动时服务会自动停止并上传。人工截图在官方 Trace Viewer 中显示为 `步骤N | 页面标题`。
+4. 告知用户浏览器已打开：默认是 PC 端（viewport 1400×740）；左下角显示可拖拽的 2×2 半透明控制栏，第一行是“开始录制”“停止录制”，第二行是“切换移动端”“截图”，下方提供“画笔”“撤销”“清空”。画笔使用 SVG 路径覆盖层，开启后可用鼠标或触摸标注页面；点击“退出画笔”会立即关闭并清空已有标注，避免后续页面操作继续带着旧标注，截图会带上标注。“切换移动端 / 切换 PC 端”可以在录制过程中来回切换：移动端为 iPhone 14 Pro Max（430×932，DPR 3），PC 端为 1400×740；切换后当前页面立即调整 viewport，截图按当前模式生成。再点击“开始录制”；点击开始后服务会先启动 Trace，临时禁用 Chromium 缓存并刷新当前 SPA 页面，等待 DOM、CSS、字体和图片稳定后恢复缓存，随后才进入正式录制计时。页面导航和录制开始后的刷新最长等待 1 小时。刷新期间不要操作页面；页面稳定后按需操作，只有点击“截图”才会保存当前渲染画面，普通点击、输入和滚动不会生成自定义 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` 确定。
 
+## 使用示例
+
+用户可以显式调用 Skill：
+
+```text
+$trace-recorder 启动 Playwright trace，访问 https://cpd.dev.autobestdevops.com，version=v2.1.0，title=首页功能02，operator=张三
+```
+
+也可以直接表达录制意图，Skill 会自动匹配：
+
+```text
+请打开 https://cpd.dev.autobestdevops.com 录制首页功能，版本 v2.1.0，操作人张三
+```
+
+浏览器打开后，指导用户按以下顺序操作：
+
+1. 默认使用 PC `1400×740`；需要移动端时点击“切换移动端”。
+2. 点击左下角“开始录制”，等待页面刷新和资源稳定完成。
+3. 普通页面操作不会生成自定义步骤；需要记录页面状态时点击“画笔”标注，再点击“截图”。
+4. 完成后点击“停止录制”，或发送 `$trace-recorder 停止录制`。
+
+上传确认示例：
+
+```text
+$trace-recorder 停止录制
+$trace-recorder 上传录制内容
+```
+
+用户明确说“停止录制并上传”时，直接调用 `stop_trace_recording` 并传入 `confirm=upload`。用户说“不上传”时传入 `confirm=cancel`。返回结果以工具本次响应为准，成功时整理回放链接、版本、标题、操作人和浏览器版本。
+
 ## 停止录制
 
 页面左下角“停止录制”会立即停止并自动上传。用户随后要求获取回放链接时，调用 `stop_trace_recording` 读取这次按钮停止的结果，并整理回放链接和元数据。