@autobest-ui/agent 1.0.11 → 1.0.13

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,60 @@
+# trace-mcp-recorder
+
+`trace-mcp-recorder` 是基于 `@modelcontextprotocol/sdk` 和 `StdioServerTransport` 的 Node.js MCP Server。它打开非无头 Chromium 供测试人员手动操作，使用 Chromium CDP 在内存中探测画面差异，仅在画面发生明显变化时调用 Playwright 截图写入原生 `trace.zip`，然后上传 trace 和浏览器元数据，并返回私有后端的 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` 会取回自动停止的结果；再调用则返回没有活动会话。
+
+画面探测默认每 500ms 执行一次，像素差异比例达到 0.5% 后进入防抖冷却；画面连续稳定 800ms 才写入一张截图 Action，持续变化超过 3 秒时强制写入一张。停止录制时会补一张最终截图。探测截图不会写入 Trace，因此静止页面和连续滚动不会产生大量重复图片。
+
+## 后端接口契约
+
+服务期望后端提供以下接口：
+
+- `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"
+