@autobest-ui/agent 1.0.11 → 1.0.12

package/README.md

@@ -40,21 +40,35 @@ npx --yes \
   autobest-azurepr-mcp
 ```
 
+启动 Playwright Trace 人工录制 MCP：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest playwright install chromium
+
+BACKEND_BASE_URL="http://127.0.0.1:3001" \
+MAX_RECORD_DURATION="1800000" \
+npx --yes \
+  --package=@autobest-ui/agent@latest \
+  autobest-trace-mcp-recorder
+```
+
 启动成功后，MCP 会通过 stdio 持续等待客户端请求，终端没有输出属于正常状态，可按 `Ctrl+C` 停止。供 Codex 长期使用时，不要只执行上述临时命令，应将完整配置加入 `~/.codex/config.toml` 后重启 Codex。
 
-同一个 npm 包暴露三个独立命令：
+同一个 npm 包暴露多个独立命令：
 
-| 命令                   | 用途                           | 必需配置           |
-| ---------------------- | ------------------------------ | ------------------ |
-| `autobest-rag-mcp`     | 连接 PRD Knowledge RAG API     | `RAG_API_BASE_URL` |
-| `autobest-azurepr-mcp` | 读取 Azure DevOps Pull Request | `AZURE_DEVOPS_PAT` |
-| `figma-mcp-bridge`     | 连接本机 Figma Plugin          | 无                 |
+| 命令                            | 用途                           | 必需配置           |
+| ------------------------------- | ------------------------------ | ------------------ |
+| `autobest-rag-mcp`              | 连接 PRD Knowledge RAG API     | `RAG_API_BASE_URL` |
+| `autobest-azurepr-mcp`          | 读取 Azure DevOps Pull Request | `AZURE_DEVOPS_PAT` |
+| `autobest-trace-mcp-recorder`   | 录制并上传 Playwright Trace    | `BACKEND_BASE_URL` |
+| `figma-mcp-bridge`              | 连接本机 Figma Plugin          | 无                 |
 
 Codex 配置示例分别位于：
 
 - [RAG MCP 配置](mcp/rag-mcp-bridge/config.toml.example)
 - [Azure PR MCP 配置](mcp/azurepr-mcp-bridge/config.toml.example)
 - [Figma MCP 配置](mcp/figma-mcp-bridge/config.toml.example)
+- [Trace Recorder MCP 配置](mcp/trace-mcp-recorder/config.toml.example)
 
 生产环境可将 `@latest` 替换为明确版本，以固定 MCP 行为。
 

package/bin/sync-assets.test.mjs

@@ -25,6 +25,7 @@ test("installs common skills into the user-level skills directory", async () =>
       "make-spec",
       "repo-setup",
       "review-from-docs",
+      "trace-recorder",
       "ui-prd-scope",
     ]);
     await access(
@@ -35,6 +36,7 @@ test("installs common skills into the user-level skills directory", async () =>
       path.join(result.targetRoot, "make-spec", "scripts", "validate-spec-traceability.mjs")
     );
     await access(path.join(result.targetRoot, "repo-setup", "SKILL.md"));
+    await access(path.join(result.targetRoot, "trace-recorder", "SKILL.md"));
     await access(
       path.join(result.targetRoot, "review-from-docs", "references", "review-result-schema.md")
     );

package/mcp/trace-mcp-recorder/.env.example

@@ -0,0 +1,6 @@
+# 必填：私有后端服务基础地址，不要以 / 结尾。
+BACKEND_BASE_URL=http://127.0.0.1:3001
+
+# 可选：最大录制时长（毫秒），默认 1800000（30 分钟）。
+MAX_RECORD_DURATION=1800000
+

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

@@ -0,0 +1,58 @@
+# trace-mcp-recorder
+
+`trace-mcp-recorder` 是基于 `@modelcontextprotocol/sdk` 和 `StdioServerTransport` 的 Node.js MCP Server。它打开非无头 Chromium 供测试人员手动操作，停止后上传 `trace.zip` 和浏览器元数据，并返回私有后端的 Trace Viewer 链接。同一进程同一时间只允许一个录制任务。
+
+## 安装与启动
+
+要求 Node.js 20 或更高版本。在本目录安装依赖及 Chromium：
+
+```bash
+npm install
+npx playwright install chromium
+```
+
+复制 `.env.example` 中的变量到 MCP 客户端环境。服务不会自动读取 `.env` 文件，也不会在代码中提供后端默认地址。直接启动：
+
+```bash
+BACKEND_BASE_URL="http://127.0.0.1:3001" \
+MAX_RECORD_DURATION="1800000" \
+npm start
+```
+
+服务使用 stdio 通信，启动后持续等待请求且不会向标准输出写日志。
+
+## Codex 接入
+
+将 [config.toml.example](config.toml.example) 的内容加入 `~/.codex/config.toml` 并按实际部署修改 `BACKEND_BASE_URL`，然后重启 Codex。发布包暴露的命令是 `autobest-trace-mcp-recorder`。
+
+配套 Skill 位于 `../../skills/common/trace-recorder/`，由 `autobest-agent-sync common` 安装，并作为 `skill://trace-recorder/SKILL.md` MCP 资源提供。Skill 的 `agents/openai.yaml` 声明了对 `trace-mcp-recorder` 的工具依赖。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `BACKEND_BASE_URL` | 无，必填 | 私有后端基础地址，必须为 HTTP(S) URL |
+| `MAX_RECORD_DURATION` | `1800000` | 最大录制时长，单位毫秒；超时后自动停止并上传 |
+
+回放链接按 `${BACKEND_BASE_URL}/trace-viewer/?trace=${fileUrl}` 生成。服务地址、域名和端口均来自 `BACKEND_BASE_URL`。
+
+## MCP 工具
+
+- `start_trace_recording`：参数为必填 `url` 和可选 `version`、`title`、`operator`。`url` 独立确定被测页面；`title` 是录制标题或功能描述，也可以直接填写 `bug3452` 这类 Bug 编号。系统不额外传递独立的 Bug 字段。MCP 认证上下文中的 `operator`、`name` 或 `preferred_username` 优先于参数。
+- `stop_trace_recording`：首次调用不传参数，只停止 trace 并询问是否上传；用户确认后传 `confirm=upload`，取消时传 `confirm=cancel`。上传成功后返回回放链接及版本、标题、操作人、浏览器版本。
+
+录制超时后服务自动停止并自动上传（无需人工确认），随后第一次人工调用 `stop_trace_recording` 会取回自动停止的结果；再调用则返回没有活动会话。
+
+## 后端接口契约
+
+服务期望后端提供以下接口：
+
+- `POST /api/trace-sessions`：接收 `multipart/form-data`，必填字段为 `trace`、`target_url`，可选字段为 `version`、`title`、`operator`、`browser_name`、`browser_version`、`user_agent`、`os_name`、`viewport`；后端生成 UUID，创建并上传成功后返回 `{ "uuid": "...", "fileUrl": "...", "item": { "status": "completed" } }`。
+
+`metadata` 包含浏览器版本、User-Agent、viewport、MCP 所在操作系统信息、目标 URL 和录制业务字段。上传或状态更新失败时，本地 trace 仍会被清理，会话会尽力回写为 `failed`。
+
+## 验证
+
+```bash
+npm run verify
+```

package/mcp/trace-mcp-recorder/config.toml.example

@@ -0,0 +1,11 @@
+[mcp_servers.trace-mcp-recorder]
+command = "npx"
+args = ["--yes", "--package=@autobest-ui/agent@latest", "autobest-trace-mcp-recorder"]
+startup_timeout_sec = 30
+tool_timeout_sec = 180
+enabled = true
+
+[mcp_servers.trace-mcp-recorder.env]
+BACKEND_BASE_URL = "http://127.0.0.1:3001"
+MAX_RECORD_DURATION = "1800000"
+

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

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+
+import { createReadStream, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import axios from 'axios';
+import FormData from 'form-data';
+import { chromium } from 'playwright';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const DEFAULT_MAX_RECORD_DURATION = 1_800_000;
+const directory = path.dirname(fileURLToPath(import.meta.url));
+
+function readConfiguration(environment = process.env) {
+  const configuredBaseUrl = environment.BACKEND_BASE_URL?.trim();
+  if (!configuredBaseUrl) {
+    throw new Error('BACKEND_BASE_URL 未配置，无法创建录制会话');
+  }
+
+  let baseUrl;
+  try {
+    baseUrl = new URL(configuredBaseUrl);
+  } catch {
+    throw new Error('BACKEND_BASE_URL 必须是有效的 URL');
+  }
+  if (!['http:', 'https:'].includes(baseUrl.protocol)) {
+    throw new Error('BACKEND_BASE_URL 必须使用 http 或 https 协议');
+  }
+
+  const durationText = environment.MAX_RECORD_DURATION ?? String(DEFAULT_MAX_RECORD_DURATION);
+  const maxRecordDuration = Number(durationText);
+  if (!Number.isSafeInteger(maxRecordDuration) || maxRecordDuration <= 0) {
+    throw new Error('MAX_RECORD_DURATION 必须是正整数毫秒值');
+  }
+
+  return {
+    baseUrl: baseUrl.toString().replace(/\/$/, ''),
+    maxRecordDuration
+  };
+}
+
+function validateTargetUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('url 必须是有效的网页地址');
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('url 必须使用 http 或 https 协议');
+  }
+  return url.toString();
+}
+
+function optionalTrimmed(value) {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+/** Prefer authenticated/request MCP identity data, then the explicit tool argument. */
+function resolveOperator(extra, suppliedOperator) {
+  const authExtra = extra?.authInfo?.extra;
+  const requestMeta = extra?._meta;
+  const candidates = [
+    authExtra?.operator,
+    authExtra?.name,
+    authExtra?.preferred_username,
+    requestMeta?.operator,
+    requestMeta?.user?.name,
+    suppliedOperator
+  ];
+  return candidates.find(value => typeof value === 'string' && value.trim())?.trim();
+}
+
+function errorMessage(error) {
+  if (axios.isAxiosError(error)) {
+    const responseData = error.response?.data;
+    const details =
+      typeof responseData === 'string' ? responseData : responseData ? JSON.stringify(responseData) : error.message;
+    return `后端请求失败${error.response?.status ? ` (HTTP ${error.response.status})` : ''}: ${details}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+function toolText(payload) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }]
+  };
+}
+
+function toolError(error) {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: errorMessage(error) }]
+  };
+}
+
+export class TraceRecorder {
+  constructor(options = {}) {
+    this.environment = options.environment ?? process.env;
+    this.launchChromium = options.launchChromium ?? (launchOptions => chromium.launch(launchOptions));
+    this.createHttpClient =
+      options.createHttpClient ??
+      (baseURL =>
+        axios.create({
+          baseURL,
+          timeout: 120_000,
+          maxBodyLength: Infinity,
+          maxContentLength: Infinity
+        }));
+    this.createFormData = options.createFormData ?? (() => new FormData());
+    this.createReadStream = options.createReadStream ?? createReadStream;
+    this.makeTemporaryDirectory =
+      options.makeTemporaryDirectory ?? (() => mkdtemp(path.join(os.tmpdir(), 'trace-mcp-recorder-')));
+    this.removeTemporaryDirectory =
+      options.removeTemporaryDirectory ?? (temporaryDirectory => rm(temporaryDirectory, { recursive: true, force: true }));
+    this.setTimer = options.setTimer ?? setTimeout;
+    this.clearTimer = options.clearTimer ?? clearTimeout;
+    this.platformInfo = options.platformInfo ?? (() => ({
+      platform: os.platform(),
+      type: os.type(),
+      release: os.release(),
+      architecture: os.arch()
+    }));
+    this.activeSession = undefined;
+    this.lastAutomaticResult = undefined;
+    this.lastAutomaticError = undefined;
+  }
+
+  async start(input, extra = {}) {
+    if (this.activeSession) {
+      throw new Error(`已有录制任务正在运行 (uuid: ${this.activeSession.uuid})，请先停止当前录制`);
+    }
+
+    const configuration = readConfiguration(this.environment);
+    const targetUrl = validateTargetUrl(input.url.trim());
+    const sessionInput = {
+      url: targetUrl,
+      version: optionalTrimmed(input.version),
+      title: optionalTrimmed(input.title),
+      operator: resolveOperator(extra, input.operator)
+    };
+    const reservation = { uuid: 'pending', state: 'starting' };
+    this.activeSession = reservation;
+    this.lastAutomaticResult = undefined;
+    this.lastAutomaticError = undefined;
+    let temporaryDirectory;
+    let browser;
+    let context;
+    let page;
+
+    try {
+      temporaryDirectory = await this.makeTemporaryDirectory();
+      browser = await this.launchChromium({ headless: false });
+      context = await browser.newContext();
+      await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
+      page = await context.newPage();
+      await page.goto(targetUrl);
+
+      const metadata = {
+        version: sessionInput.version,
+        title: sessionInput.title,
+        operator: sessionInput.operator,
+        targetUrl,
+        browserName: 'Chromium',
+        browserVersion: browser.version(),
+        userAgent: await page.evaluate(() => navigator.userAgent),
+        viewport: page.viewportSize(),
+        operatingSystem: this.platformInfo(),
+        startedAt: new Date().toISOString()
+      };
+      const session = {
+        browser,
+        context,
+        page,
+        metadata,
+        baseUrl: configuration.baseUrl,
+        tracePath: path.join(temporaryDirectory, 'trace.zip'),
+        temporaryDirectory,
+        state: 'recording',
+        stopPromise: undefined,
+        uploadPromise: undefined,
+        timer: undefined
+      };
+      this.activeSession = session;
+
+      const failOnBrowserExit = () => {
+        if (session.state === 'recording') {
+          session.stopPromise = this.failSession(session, new Error('Chromium 浏览器意外退出'));
+          void session.stopPromise.catch(failure => {
+            console.error('[trace-mcp-recorder] 浏览器异常退出:', errorMessage(failure));
+          });
+        }
+      };
+      browser.once('disconnected', failOnBrowserExit);
+      session.timer = this.setTimer(() => {
+        void this.stop({ trigger: 'timeout', confirm: 'upload' }).catch(error => {
+          this.lastAutomaticError = error;
+          console.error('[trace-mcp-recorder] 自动停止录制失败:', errorMessage(error));
+        });
+      }, configuration.maxRecordDuration);
+      session.timer?.unref?.();
+
+      return {
+        message: '浏览器已打开，请手动操作页面，完成后调用 stop_trace_recording',
+        maxRecordDuration: configuration.maxRecordDuration,
+        metadata
+      };
+    } catch (error) {
+      await this.closeResources({ browser, context, page, temporaryDirectory });
+      if (this.activeSession === reservation) {
+        this.activeSession = undefined;
+      }
+      throw error;
+    }
+  }
+
+  async stop({ trigger = 'manual', confirm } = {}) {
+    const session = this.activeSession;
+    if (!session) {
+      if (trigger === 'manual' && this.lastAutomaticError) {
+        const error = this.lastAutomaticError;
+        this.lastAutomaticError = undefined;
+        throw error;
+      }
+      if (trigger === 'manual' && this.lastAutomaticResult) {
+        const result = this.lastAutomaticResult;
+        this.lastAutomaticResult = undefined;
+        return result;
+      }
+      throw new Error('当前没有正在录制的 trace 会话');
+    }
+    if (session.state === 'starting') {
+      throw new Error('录制会话正在启动，请等待 start_trace_recording 返回后再停止');
+    }
+    if (session.state === 'recording') {
+      if (session.stopPromise) return session.stopPromise;
+      session.state = 'stopping';
+      this.clearTimer(session.timer);
+      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;
+    }
+    if (session.state === 'stopping' && session.stopPromise) return session.stopPromise;
+    if (session.state === 'awaiting_upload') {
+      if (confirm === 'upload') return this.uploadSession(session, trigger);
+      if (confirm === 'cancel') return this.cancelSession(session);
+      return {
+        uuid: undefined,
+        message: 'trace.zip 已生成，是否上传录制内容并创建回放记录？请确认“上传”或“不上传”。',
+        metadata: session.metadata
+      };
+    }
+    if (session.state === 'uploading' && session.uploadPromise) return session.uploadPromise;
+    throw new Error('当前录制会话不可停止');
+  }
+
+  async prepareSession(session) {
+    try {
+      await session.context.tracing.stop({ path: session.tracePath });
+      await this.closeResources({ page: session.page, context: session.context, browser: session.browser });
+      session.state = 'awaiting_upload';
+      return {
+        message: 'trace.zip 已生成，是否上传录制内容并创建回放记录？请确认“上传”或“不上传”。',
+        metadata: session.metadata
+      };
+    } catch (error) {
+      session.state = 'failed';
+      await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+      if (this.activeSession === session) this.activeSession = undefined;
+      throw error;
+    }
+  }
+
+  async uploadSession(session, trigger) {
+    if (session.uploadPromise) return session.uploadPromise;
+    session.state = 'uploading';
+    session.uploadPromise = (async () => {
+      const configuration = readConfiguration(this.environment);
+      const http = this.createHttpClient(configuration.baseUrl);
+      const form = this.createFormData();
+      form.append('target_url', session.metadata.targetUrl);
+      for (const [field, value] of [
+        ['version', session.metadata.version],
+        ['title', session.metadata.title],
+        ['operator', session.metadata.operator],
+        ['browser_name', session.metadata.browserName],
+        ['browser_version', session.metadata.browserVersion],
+        ['user_agent', session.metadata.userAgent],
+        ['os_name', session.metadata.operatingSystem.platform],
+        ['viewport', JSON.stringify(session.metadata.viewport)]
+      ]) {
+        if (value !== undefined && value !== null) form.append(field, String(value));
+      }
+      form.append('trace', this.createReadStream(session.tracePath), {
+        filename: 'trace.zip',
+        contentType: 'application/zip'
+      });
+      const uploadResponse = await http.post('/api/trace-sessions', form, {
+        headers: form.getHeaders()
+      });
+      const fileUrl = uploadResponse.data?.fileUrl;
+      if (typeof fileUrl !== 'string' || !fileUrl.trim()) throw new Error('上传响应缺少 fileUrl');
+      const replayLink = `${session.baseUrl}/trace-viewer/?trace=${fileUrl}`;
+      const result = {
+        uuid: uploadResponse.data?.uuid,
+        message: `✅录制完成，回放链接：${replayLink}`,
+        replayLink,
+        fileUrl,
+        stoppedBy: trigger,
+        metadata: {
+          version: session.metadata.version,
+          title: session.metadata.title,
+          operator: session.metadata.operator,
+          browserVersion: session.metadata.browserVersion
+        }
+      };
+      session.state = 'completed';
+      if (trigger === 'timeout') this.lastAutomaticResult = result;
+      return result;
+    })().catch(async error => {
+      session.state = 'failed';
+      if (trigger === 'timeout') this.lastAutomaticError = error;
+      await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+      if (this.activeSession === session) this.activeSession = undefined;
+      throw error;
+    }).finally(async () => {
+      await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+      if (this.activeSession === session && session.state === 'completed') this.activeSession = undefined;
+    });
+    return session.uploadPromise;
+  }
+
+  async cancelSession(session) {
+    session.state = 'cancelled';
+    await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+    if (this.activeSession === session) this.activeSession = undefined;
+    return { message: '已取消上传，本地 trace.zip 已删除。' };
+  }
+
+  async failSession(session, error) {
+    if (session.state !== 'recording') return;
+    session.state = 'failed';
+    this.clearTimer(session.timer);
+    await this.closeResources(session);
+    await this.removeTemporaryDirectory(session.temporaryDirectory).catch(() => {});
+    if (this.activeSession === session) this.activeSession = undefined;
+    throw error;
+  }
+
+  async closeResources({ browser, context, page, temporaryDirectory }) {
+    // Each cleanup step is independent so one closed/crashed Playwright object cannot block the rest.
+    await page?.close().catch(() => {});
+    await context?.close().catch(() => {});
+    await browser?.close().catch(() => {});
+    if (temporaryDirectory) await this.removeTemporaryDirectory(temporaryDirectory).catch(() => {});
+  }
+}
+
+function registerSkillResources(server) {
+  const skillPath = path.join(directory, '../../skills/common/trace-recorder/SKILL.md');
+  if (!existsSync(skillPath)) return;
+  const uri = 'skill://trace-recorder/SKILL.md';
+  server.registerResource(
+    'trace-recorder',
+    uri,
+    {
+      title: 'Skill: trace-recorder',
+      description: 'trace-mcp-recorder 的自然语言调用说明',
+      mimeType: 'text/markdown'
+    },
+    async () => ({
+      contents: [{ uri, mimeType: 'text/markdown', text: readFileSync(skillPath, 'utf8') }]
+    })
+  );
+}
+
+export function createServer(options = {}) {
+  const recorder = options.recorder ?? new TraceRecorder(options);
+  const server = new McpServer(
+    { 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.'
+    }
+  );
+
+  server.registerTool(
+    'start_trace_recording',
+    {
+      title: '启动 Playwright Trace 人工录制',
+      description: '启动非无头 Chromium、开启 trace 并访问指定 URL，供测试人员在浏览器窗口中手动操作。',
+      inputSchema: {
+        url: z.string().min(1).describe('必填，被测页面的 HTTP(S) 地址'),
+        version: z.string().min(1).optional().describe('可选，被测版本号，例如 v2.1.0'),
+        title: z.string().min(1).optional().describe('可选，录制标题，例如登录页面'),
+        operator: z.string().min(1).optional().describe('可选，操作人；MCP 上下文中的身份优先')
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async (input, extra) => {
+      try {
+        return toolText(await recorder.start(input, extra));
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    'stop_trace_recording',
+    {
+      title: '停止 Playwright Trace 录制',
+      description: '停止当前 trace 并询问上传；确认后上传 trace.zip 和浏览器元数据，返回回放链接。',
+      inputSchema: {
+        confirm: z.enum(['upload', 'cancel']).optional().describe('首次停止不传；用户确认上传传 upload，拒绝上传传 cancel')
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async ({ confirm } = {}) => {
+      try {
+        return toolText(await recorder.stop({ confirm }));
+      } catch (error) {
+        return toolError(error);
+      }
+    }
+  );
+
+  registerSkillResources(server);
+  return server;
+}
+
+async function main() {
+  await createServer().connect(new StdioServerTransport());
+}
+
+let isCommandEntry = false;
+if (process.argv[1]) {
+  try {
+    isCommandEntry = realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    isCommandEntry = false;
+  }
+}
+
+if (isCommandEntry) {
+  main().catch(error => {
+    console.error('[trace-mcp-recorder] 服务启动失败:', errorMessage(error));
+    process.exitCode = 1;
+  });
+}

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

@@ -0,0 +1,179 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { TraceRecorder } from './index.js';
+
+const directory = path.dirname(fileURLToPath(import.meta.url));
+const sessionUuid = '123e4567-e89b-42d3-a456-426614174000';
+
+function createFixture(options = {}) {
+  const calls = [];
+  const browser = new EventEmitter();
+  const tracing = {
+    start: async options => calls.push(['trace-start', options]),
+    stop: async options => calls.push(['trace-stop', options])
+  };
+  const page = {
+    goto: async url => calls.push(['goto', url]),
+    evaluate: async () => 'Fixture User Agent',
+    viewportSize: () => ({ width: 1280, height: 720 }),
+    close: async () => calls.push(['page-close'])
+  };
+  const context = {
+    tracing,
+    newPage: async () => page,
+    close: async () => calls.push(['context-close'])
+  };
+  browser.newContext = async () => context;
+  browser.version = () => 'Fixture Chromium 1';
+  browser.close = async () => calls.push(['browser-close']);
+
+  const http = {
+    post: async (endpoint, body) => {
+      calls.push(['post', endpoint, body]);
+      if (endpoint === '/api/trace-sessions' && body !== form) return { data: { uuid: sessionUuid } };
+      if (options.uploadError) throw options.uploadError;
+      return { data: { fileUrl: '/private/traces/trace.zip' } };
+    },
+    patch: async (endpoint, body) => {
+      calls.push(['patch', endpoint, body]);
+      return { data: {} };
+    }
+  };
+  const form = {
+    append: (...args) => calls.push(['form-append', ...args]),
+    getHeaders: () => ({ 'content-type': 'multipart/form-data; boundary=fixture' })
+  };
+  const timer = { unref() {} };
+  const recorder = new TraceRecorder({
+    environment: {
+      BACKEND_BASE_URL: 'https://trace.example.test/root/',
+      MAX_RECORD_DURATION: '1000'
+    },
+    launchChromium: async options => {
+      calls.push(['launch', options]);
+      return browser;
+    },
+    createHttpClient: baseUrl => {
+      calls.push(['http-client', baseUrl]);
+      return http;
+    },
+    createFormData: () => form,
+    createReadStream: tracePath => ({ tracePath }),
+    makeTemporaryDirectory: async () => '/tmp/trace-fixture',
+    removeTemporaryDirectory: async temporaryDirectory => calls.push(['remove', temporaryDirectory]),
+    setTimer: (callback, duration) => {
+      calls.push(['timer', duration]);
+      timer.callback = callback;
+      return timer;
+    },
+    clearTimer: value => calls.push(['clear-timer', value]),
+    platformInfo: () => ({ platform: 'fixture-os' })
+  });
+  return { browser, calls, recorder, timer };
+}
+
+test('starts, records metadata, uploads, completes and cleans up one session', async () => {
+  const { calls, recorder } = createFixture();
+  const started = await recorder.start(
+    {
+      url: 'https://app.example.test/login',
+      version: 'v2.1.0',
+      title: 'bug3452',
+      operator: '传入操作人'
+    },
+    { authInfo: { extra: { operator: '上下文操作人' } } }
+  );
+
+  assert.equal(started.uuid, undefined);
+  assert.equal(started.metadata.operator, '上下文操作人');
+  assert.equal(started.metadata.browserVersion, 'Fixture Chromium 1');
+  await assert.rejects(
+    recorder.start({ url: 'https://app.example.test/another' }),
+    /已有录制任务/
+  );
+
+  const confirmation = await recorder.stop();
+  assert.match(confirmation.message, /是否上传/);
+  const stopped = await recorder.stop({ confirm: 'upload' });
+  assert.equal(
+    stopped.replayLink,
+    'https://trace.example.test/root/trace-viewer/?trace=/private/traces/trace.zip'
+  );
+  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] === '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'));
+});
+
+test('rejects missing configuration before contacting the backend', async () => {
+  const recorder = new TraceRecorder({ environment: {} });
+  await assert.rejects(recorder.start({ url: 'https://app.example.test' }), /BACKEND_BASE_URL/);
+});
+
+test('cleans up when Chromium launch fails without a backend session', async () => {
+  const { calls, recorder } = createFixture();
+  recorder.launchChromium = async () => {
+    throw new Error('launch failed');
+  };
+
+  await assert.rejects(recorder.start({ url: 'https://app.example.test' }), /launch failed/);
+  assert.equal(calls.some(call => call[0] === 'post'), false);
+});
+
+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.stop();
+  await assert.rejects(recorder.stop({ confirm: 'upload' }), /upload failed/);
+  assert.ok(calls.some(call => call[0] === 'remove' && call[1] === '/tmp/trace-fixture'));
+});
+
+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' });
+  timer.callback();
+
+  while (recorder.activeSession) await new Promise(resolve => setImmediate(resolve));
+  const result = await recorder.stop();
+  assert.equal(result.stoppedBy, 'timeout');
+  await assert.rejects(recorder.stop(), /当前没有正在录制/);
+});
+
+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({
+    command: process.execPath,
+    args: [path.join(directory, 'index.js')],
+    cwd: directory,
+    env: { ...process.env },
+    stderr: 'pipe'
+  });
+
+  try {
+    await client.connect(transport);
+    assert.equal(client.getServerVersion()?.name, 'trace-mcp-recorder');
+    const { tools } = await client.listTools();
+    assert.deepEqual(
+      tools.map(tool => tool.name),
+      ['start_trace_recording', 'stop_trace_recording']
+    );
+    const { resources } = await client.listResources();
+    assert.ok(resources.some(resource => resource.uri === 'skill://trace-recorder/SKILL.md'));
+
+    const result = await client.callTool({
+      name: 'start_trace_recording',
+      arguments: { url: 'https://app.example.test' }
+    });
+    assert.equal(result.isError, true);
+    assert.match(result.content[0].text, /BACKEND_BASE_URL/);
+  } finally {
+    await client.close();
+  }
+});

package/mcp/trace-mcp-recorder/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@autobest/trace-mcp-recorder",
+  "version": "1.0.0",
+  "private": true,
+  "description": "MCP server for recording and uploading manual Playwright traces",
+  "type": "module",
+  "main": "index.js",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "lint": "node --check index.js && node --check index.test.js",
+    "test": "node --test index.test.js",
+    "verify": "npm run lint && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "axios": "1.20.0",
+    "form-data": "4.0.6",
+    "playwright": "1.63.0",
+    "uuid": "14.0.2",
+    "zod": "4.4.3"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "private": false,
   "description": "Autobest Agent skills/plugins/mcp assets + sync cli",
   "files": [
@@ -19,6 +19,7 @@
     "autobest-agent-sync": "./bin/sync-assets.mjs",
     "autobest-code-mcp-pr": "./mcp/code-mcp-pr/index.js",
     "autobest-azurepr-mcp": "./mcp/azurepr-mcp-bridge/index.js",
+    "autobest-trace-mcp-recorder": "./mcp/trace-mcp-recorder/index.js",
     "autobest-delivery-setup": "./plugins/autobest-delivery/scripts/setup.mjs",
     "autobest-rag-mcp": "./mcp/rag-mcp-bridge/index.js",
     "figma-mcp-bridge": "./mcp/figma-mcp-bridge/src/index.js",
@@ -29,20 +30,26 @@
     "mcp:code-mcp-pr": "node ./mcp/code-mcp-pr/index.js",
     "mcp:figma": "node ./mcp/figma-mcp-bridge/src/index.js",
     "mcp:rag": "node ./mcp/rag-mcp-bridge/index.js",
+    "mcp:trace-recorder": "node ./mcp/trace-mcp-recorder/index.js",
     "test": "npm run test:skills && npm run test:mcp && npm run test:plugin",
     "test:skills": "node --test ./bin/sync-assets.test.mjs ./bin/traceability-validators.test.mjs",
     "test:mcp:azurepr": "node --test ./mcp/azurepr-mcp-bridge/index.test.js",
     "test:mcp:code-mcp-pr": "node --test ./mcp/code-mcp-pr/index.test.js",
     "test:mcp:figma": "node --test ./mcp/figma-mcp-bridge/index.test.js",
     "test:mcp:rag": "node --test ./mcp/rag-mcp-bridge/index.test.js",
-    "test:mcp": "npm run test:mcp:azurepr && npm run test:mcp:code-mcp-pr && npm run test:mcp:figma && npm run test:mcp:rag",
+    "test:mcp:trace-recorder": "node --test ./mcp/trace-mcp-recorder/index.test.js",
+    "test:mcp": "npm run test:mcp:azurepr && npm run test:mcp:code-mcp-pr && npm run test:mcp:figma && npm run test:mcp:rag && npm run test:mcp:trace-recorder",
     "test:plugin": "node --test ./plugins/autobest-delivery/scripts/setup.test.mjs ./plugins/figma-plugin/scripts/setup.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
+    "axios": "1.20.0",
     "diff": "9.0.0",
+    "form-data": "4.0.6",
     "fs-extra": "11.3.0",
     "mdast-util-from-markdown": "2.0.2",
+    "playwright": "1.63.0",
+    "uuid": "14.0.2",
     "ws": "8.18.3",
     "zod": "4.4.3"
   },

package/skills/README.md

@@ -17,6 +17,7 @@ npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync common
 - `make-spec`
 - `repo-setup`
 - `review-from-docs`
+- `trace-recorder`
 - `ui-prd-scope`
 
 其中 `ui-prd-scope` 使用 `REQ-<页面或Scope简称>-<三位序号>` 分配稳定需求 ID；`review-from-docs` 为每个 REQ 建立决策树，逐轮询问当前完整 frontier 并记录用户确认的结论；`make-spec` 只从已完成的 review 生成逐项可验收的 `spec.md` 和机器可校验的映射。后续交付角色只引用编号，不重新编号。

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

@@ -0,0 +1,25 @@
+---
+name: trace-recorder
+description: 通过 trace-mcp-recorder 启动或停止 Playwright Trace 人工录制；当用户要求打开页面录制、停止录制或获取 trace 回放链接时使用。
+---
+
+# Trace MCP Recorder
+
+将用户的自然语言请求映射到 `trace-mcp-recorder` 的 MCP 工具。`url` 独立确定被测页面；`title` 是本次录制的标题或功能描述，也可以直接填写 Bug 编号（例如 `bug3452`）。系统不额外传递独立的 Bug 字段。
+
+## 启动录制
+
+当用户要求启动、开始或打开页面进行 trace 录制时：
+
+1. 从原话提取 `url`、`version`、`title`、`operator`。支持 `key=value` 和自然语言表达，不改写用户给出的值。
+2. `url` 必填；缺少时只询问目标页面地址。其他字段缺失时不要阻断录制。
+3. 调用 `start_trace_recording`，只传入用户明确提供的可选字段。服务端会优先使用 MCP 上下文中的操作人身份。
+4. 告知用户浏览器已打开，并保留工具返回的 `uuid` 和最大录制时长；不要代替用户操作页面。
+
+示例：`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` 整理给用户。
+
+若工具返回错误，如没有活动会话、后端不可达或上传失败，原样说明关键原因，不编造回放链接。

package/skills/common/trace-recorder/agents/openai.yaml

@@ -0,0 +1,11 @@
+interface:
+  display_name: "trace-recorder"
+  short_description: "启动或停止 Playwright Trace 人工录制并返回回放链接"
+  default_prompt: "使用 $trace-recorder 启动指定页面的 Playwright Trace 人工录制。"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "trace-mcp-recorder"
+      description: "启动、停止、上传 Playwright Trace 的本地 STDIO MCP 服务"
+