@autobest-ui/agent 1.0.0 → 1.0.2

package/README.md

@@ -20,30 +20,63 @@ npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync react
 
 ## MCP
 
-安装 Node.js 20 或更高版本后，无需在业务项目中安装依赖，可以直接通过 `npx` 启动 MCP：
+安装 Node.js 20 或更高版本后，无需在业务项目中安装依赖。直接在终端验证 MCP 时，必须同时提供对应的环境变量。
+
+先启动 PRD Knowledge HTTP API，再验证 RAG MCP：
+
+```bash
+RAG_API_BASE_URL="http://192.168.1.12:3000/api/knowledge" \
+npx --yes \
+  --package=@autobest-ui/agent@latest \
+  autobest-rag-mcp
+```
+
+验证 Azure PR MCP：
 
 ```bash
-npx --yes --package=@autobest-ui/agent@latest autobest-rag-mcp
-npx --yes --package=@autobest-ui/agent@latest autobest-azurepr-mcp
+AZURE_DEVOPS_PAT="your-personal-access-token" \
+npx --yes \
+  --package=@autobest-ui/agent@latest \
+  autobest-azurepr-mcp
 ```
 
-同一个 npm 包暴露两个独立命令：
+启动成功后，MCP 会通过 stdio 持续等待客户端请求，终端没有输出属于正常状态，可按 `Ctrl+C` 停止。供 Codex 长期使用时，不要只执行上述临时命令，应将完整配置加入 `~/.codex/config.toml` 后重启 Codex。
+
+同一个 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          | 无                 |
 
 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)
 
 生产环境可将 `@latest` 替换为明确版本，以固定 MCP 行为。
 
 如果 `@autobest-ui` 发布在私有 npm registry，使用前需要在 npm 的 `.npmrc` 中配置该 scope 对应的 registry 和认证信息。
 
-## Plugin
+## Figma Plugin
+
+Figma Plugin 与 `figma-mcp-bridge` 分目录维护，并通过同一个 npm 包提供两个独立命令。安装或更新到稳定目录：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-plugin
+```
+
+命令会输出 `manifest.json` 的稳定路径。首次安装后，在 Figma 中通过 **Plugins -> Development -> Import plugin from manifest** 导入该文件。详细说明见 [Figma Plugin 使用说明](plugins/figma-plugin/README.md)。
+
+卸载本地文件：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-plugin uninstall
+```
+
+## Codex Plugin
 
 Autobest Delivery 将交付闭环 Skills 和隔离的 Playwright MCP 运行器作为一个 Codex Plugin 安装。需要 Node.js 20 或更高版本，以及支持 `codex plugin` 命令的 Codex CLI。
 
@@ -126,7 +159,7 @@ Common Skills 会写入 `~/.agents/skills`，React Skills 会写入目标项目
 RAG MCP：
 
 ```bash
-RAG_API_BASE_URL=http://127.0.0.1:3000 \
+RAG_API_BASE_URL="http://192.168.1.12:3000/api/knowledge" \
 npx --yes \
   --package="$AGENT_TARBALL_PATH" \
   autobest-rag-mcp
@@ -141,6 +174,22 @@ npx --yes \
   autobest-azurepr-mcp
 ```
 
+Figma MCP：
+
+```bash
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  figma-mcp-bridge
+```
+
+Figma Plugin：
+
+```bash
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  figma-plugin
+```
+
 MCP 使用 stdio 协议，启动后持续等待客户端请求属于正常行为，可按 `Ctrl+C` 停止。
 
 ### 5. 在 Codex 中联调 MCP
@@ -157,7 +206,7 @@ args = [
 ]
 
 [mcp_servers.rag-mcp-bridge.env]
-RAG_API_BASE_URL = "http://127.0.0.1:3000"
+RAG_API_BASE_URL = "http://192.168.1.12:3000/api/knowledge"
 
 [mcp_servers.azurepr-mcp-bridge]
 command = "npx"
@@ -167,11 +216,21 @@ args = [
   "autobest-azurepr-mcp"
 ]
 
-[mcp_servers.azurepr-mcp-bridge.env]
-AZURE_DEVOPS_PAT = "your-token"
+env_vars = ["AZURE_DEVOPS_PAT"]
+
+[mcp_servers.figma-mcp-bridge]
+command = "npx"
+args = [
+  "--yes",
+  "--package=/absolute/path/to/autobest-ui-agent-x.y.z.tgz",
+  "figma-mcp-bridge"
+]
+startup_timeout_sec = 30
+tool_timeout_sec = 120
+enabled = true
 ```
 
-修改 `config.toml` 后重启 Codex，再从新会话调用对应 MCP 工具。重新打包后如果 tarball 文件名或路径发生变化，需要同步更新 `config.toml`。
+配置 Azure PR MCP 前，还需要在启动 Codex 的环境中设置 `AZURE_DEVOPS_PAT`。修改 `config.toml` 后重启 Codex，再从新会话调用对应 MCP 工具。重新打包后如果 tarball 文件名或路径发生变化，需要同步更新 `config.toml`。
 
 ## 本地验证
 

package/mcp/azurepr-mcp-bridge/azure-devops.js

@@ -1,4 +1,4 @@
-import { diffLines } from "diff";
+import { diffLines } from 'diff';
 
 export const MAX_CONTENT_LENGTH = 120_000;
 const MAX_FILE_CONTENT_LENGTH = 500_000;
@@ -10,28 +10,25 @@ const HTTP_TIMEOUT_MS = 30_000;
 const FILE_FETCH_CONCURRENCY = 6;
 
 const ignoredBinaryExtensions = new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".ico",
-  ".pdf",
-  ".zip",
-  ".woff",
-  ".woff2",
-  ".ttf",
-  ".eot",
-  ".mp3",
-  ".mp4",
-  ".mov",
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.ico',
+  '.pdf',
+  '.zip',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.eot',
+  '.mp3',
+  '.mp4',
+  '.mov'
 ]);
 
 export function isAttachmentPath(filePath) {
-  return (
-    typeof filePath === "string" &&
-    /(^|\/)\.attachments(?:\/|$)/i.test(filePath)
-  );
+  return typeof filePath === 'string' && /(^|\/)\.attachments(?:\/|$)/i.test(filePath);
 }
 
 export function isBinaryPath(filePath) {
@@ -40,12 +37,10 @@ export function isBinaryPath(filePath) {
 }
 
 export function isInsideRequestedPath(filePath, requestedPath) {
-  if (typeof filePath !== "string" || !filePath) return false;
-  if (!requestedPath || requestedPath === "/") return true;
+  if (typeof filePath !== 'string' || !filePath) return false;
+  if (!requestedPath || requestedPath === '/') return true;
 
-  const normalized = `/${requestedPath}`
-    .replace(/\/{2,}/g, "/")
-    .replace(/\/$/, "");
+  const normalized = `/${requestedPath}`.replace(/\/{2,}/g, '/').replace(/\/$/, '');
   return filePath === normalized || filePath.startsWith(`${normalized}/`);
 }
 
@@ -53,38 +48,36 @@ function decodePathSegment(value) {
   try {
     return decodeURIComponent(value);
   } catch {
-    throw new Error("Azure DevOps PR 地址包含无效编码");
+    throw new Error('Azure DevOps PR 地址包含无效编码');
   }
 }
 
 export function parsePullRequestLocation(urlValue) {
   const url = new URL(urlValue);
-  if (url.protocol !== "https:") {
-    throw new Error("Azure DevOps PR 地址必须使用 HTTPS");
+  if (url.protocol !== 'https:') {
+    throw new Error('Azure DevOps PR 地址必须使用 HTTPS');
   }
 
   const hostname = url.hostname.toLowerCase();
-  const isVisualStudio = hostname.endsWith(".visualstudio.com");
-  const isDevAzure = hostname === "dev.azure.com";
+  const isVisualStudio = hostname.endsWith('.visualstudio.com');
+  const isDevAzure = hostname === 'dev.azure.com';
   if (!isVisualStudio && !isDevAzure) {
-    throw new Error(
-      "仅支持 dev.azure.com 或 *.visualstudio.com 的 Azure DevOps PR 地址",
-    );
+    throw new Error('仅支持 dev.azure.com 或 *.visualstudio.com 的 Azure DevOps PR 地址');
   }
 
   const match = url.pathname.match(
     isVisualStudio
       ? /^\/([^/]+)\/_git\/([^/]+)\/pullrequest\/(\d+)\/?$/i
-      : /^\/([^/]+)\/([^/]+)\/_git\/([^/]+)\/pullrequest\/(\d+)\/?$/i,
+      : /^\/([^/]+)\/([^/]+)\/_git\/([^/]+)\/pullrequest\/(\d+)\/?$/i
   );
-  if (!match) throw new Error("无法识别 Azure DevOps PR 地址");
+  if (!match) throw new Error('无法识别 Azure DevOps PR 地址');
 
   if (isVisualStudio) {
     const project = decodePathSegment(match[1]);
     return {
       apiRoot: `${url.origin}/${encodeURIComponent(project)}`,
       repository: decodePathSegment(match[2]),
-      pullRequestId: match[3],
+      pullRequestId: match[3]
     };
   }
 
@@ -93,14 +86,14 @@ export function parsePullRequestLocation(urlValue) {
   return {
     apiRoot: `${url.origin}/${encodeURIComponent(organization)}/${encodeURIComponent(project)}`,
     repository: decodePathSegment(match[3]),
-    pullRequestId: match[4],
+    pullRequestId: match[4]
   };
 }
 
 async function azureGet(url, headers, optional = false) {
   const response = await fetch(url, {
     headers,
-    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
   });
   if (!response.ok) {
     if (optional) return undefined;
@@ -114,17 +107,13 @@ async function azureItemContent(repositoryRoot, filePath, commitId, headers) {
 
   const query = new URLSearchParams({
     path: filePath,
-    includeContent: "true",
-    "versionDescriptor.version": commitId,
-    "versionDescriptor.versionType": "commit",
-    "api-version": "7.1",
+    includeContent: 'true',
+    'versionDescriptor.version': commitId,
+    'versionDescriptor.versionType': 'commit',
+    'api-version': '7.1'
   });
-  const item = await azureGet(
-    `${repositoryRoot}/items?${query.toString()}`,
-    headers,
-    true,
-  );
-  if (!item || item.isBinary || typeof item.content !== "string") {
+  const item = await azureGet(`${repositoryRoot}/items?${query.toString()}`, headers, true);
+  if (!item || item.isBinary || typeof item.content !== 'string') {
     return undefined;
   }
   if (item.content.length > MAX_FILE_CONTENT_LENGTH) return undefined;
@@ -132,19 +121,19 @@ async function azureItemContent(repositoryRoot, filePath, commitId, headers) {
 }
 
 export function extractAddedContent(previousContent, currentContent) {
-  if (typeof currentContent !== "string") return undefined;
+  if (typeof currentContent !== 'string') return undefined;
 
   const additions =
-    typeof previousContent === "string"
+    typeof previousContent === 'string'
       ? diffLines(previousContent, currentContent)
-          .filter((part) => part.added)
-          .map((part) => part.value)
-          .join("")
+          .filter(part => part.added)
+          .map(part => part.value)
+          .join('')
       : currentContent;
 
   return {
     content: additions.slice(0, MAX_ADDED_CONTENT_LENGTH),
-    truncated: additions.length > MAX_ADDED_CONTENT_LENGTH,
+    truncated: additions.length > MAX_ADDED_CONTENT_LENGTH
   };
 }
 
@@ -159,17 +148,12 @@ async function mapWithConcurrency(items, concurrency, mapper) {
     }
   }
 
-  await Promise.all(
-    Array.from(
-      { length: Math.min(concurrency, items.length) },
-      () => worker(),
-    ),
-  );
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
   return results;
 }
 
 function truncateText(value, maximumLength) {
-  if (typeof value !== "string") return value;
+  if (typeof value !== 'string') return value;
   return value.length > maximumLength ? value.slice(0, maximumLength) : value;
 }
 
@@ -183,25 +167,19 @@ export function serializePullRequest(result) {
   const bounded = {
     ...result,
     changedFiles: sourceFiles.map(withoutAddedContent),
-    addedContentOmittedDueToResponseLimit: 0,
+    addedContentOmittedDueToResponseLimit: 0
   };
 
   let omittedComments = 0;
   let omittedFiles = 0;
   let serialized = JSON.stringify(bounded, null, 2);
 
-  while (
-    serialized.length > MAX_CONTENT_LENGTH &&
-    bounded.reviewComments.length > 0
-  ) {
+  while (serialized.length > MAX_CONTENT_LENGTH && bounded.reviewComments.length > 0) {
     bounded.reviewComments.pop();
     omittedComments += 1;
     serialized = JSON.stringify(bounded, null, 2);
   }
-  while (
-    serialized.length > MAX_CONTENT_LENGTH &&
-    bounded.changedFiles.length > 0
-  ) {
+  while (serialized.length > MAX_CONTENT_LENGTH && bounded.changedFiles.length > 0) {
     bounded.changedFiles.pop();
     omittedFiles += 1;
     serialized = JSON.stringify(bounded, null, 2);
@@ -233,38 +211,34 @@ export function serializePullRequest(result) {
     title: truncateText(result.title, 500),
     status: result.status,
     responseTruncated: true,
-    error: "PR 响应超过 MCP 内容上限",
+    error: 'PR 响应超过 MCP 内容上限'
   });
 }
 
 export async function getAzurePullRequest(urlValue, pat) {
   const inputUrl = new URL(urlValue);
-  const requestedPath = inputUrl.searchParams.get("path");
-  const { apiRoot, repository, pullRequestId } =
-    parsePullRequestLocation(urlValue);
+  const requestedPath = inputUrl.searchParams.get('path');
+  const { apiRoot, repository, pullRequestId } = parsePullRequestLocation(urlValue);
   const encodedRepository = encodeURIComponent(repository);
   const repositoryRoot = `${apiRoot}/_apis/git/repositories/${encodedRepository}`;
   const root = `${repositoryRoot}/pullRequests/${pullRequestId}`;
   const headers = {
-    Accept: "application/json",
-    Authorization: `Basic ${Buffer.from(`:${pat}`).toString("base64")}`,
+    Accept: 'application/json',
+    Authorization: `Basic ${Buffer.from(`:${pat}`).toString('base64')}`
   };
 
   const [pullRequest, threads, workItems, iterations] = await Promise.all([
     azureGet(`${root}?api-version=7.1`, headers),
     azureGet(`${root}/threads?api-version=7.1`, headers, true),
     azureGet(`${root}/workitems?api-version=7.1`, headers, true),
-    azureGet(`${root}/iterations?api-version=7.1`, headers, true),
+    azureGet(`${root}/iterations?api-version=7.1`, headers, true)
   ]);
-  const latestIterationId = Math.max(
-    0,
-    ...(iterations?.value || []).map(({ id }) => Number(id) || 0),
-  );
+  const latestIterationId = Math.max(0, ...(iterations?.value || []).map(({ id }) => Number(id) || 0));
   const changes = latestIterationId
     ? await azureGet(
         `${root}/iterations/${latestIterationId}/changes?$top=${MAX_CHANGED_FILES}&api-version=7.1`,
         headers,
-        true,
+        true
       )
     : undefined;
 
@@ -274,30 +248,26 @@ export async function getAzurePullRequest(urlValue, pat) {
     .filter(({ item }) => !isAttachmentPath(item?.path))
     .filter(({ item }) => isInsideRequestedPath(item?.path, requestedPath))
     .slice(0, MAX_CHANGED_FILES);
-  const changedFiles = await mapWithConcurrency(
-    changeEntries,
-    FILE_FETCH_CONCURRENCY,
-    async ({ changeType, item }) => {
-      const filePath = item?.path;
-      const deleted = String(changeType).toLowerCase().includes("delete");
-      const isFile = !item?.gitObjectType || item.gitObjectType === "blob";
-      if (!filePath || deleted || !isFile || isBinaryPath(filePath)) {
-        return { changeType, path: filePath };
-      }
-
-      const [previousContent, currentContent] = await Promise.all([
-        azureItemContent(repositoryRoot, filePath, targetCommitId, headers),
-        azureItemContent(repositoryRoot, filePath, sourceCommitId, headers),
-      ]);
-      const additions = extractAddedContent(previousContent, currentContent);
-      return {
-        changeType,
-        path: filePath,
-        addedContent: additions?.content || undefined,
-        addedContentTruncated: additions?.truncated || undefined,
-      };
-    },
-  );
+  const changedFiles = await mapWithConcurrency(changeEntries, FILE_FETCH_CONCURRENCY, async ({ changeType, item }) => {
+    const filePath = item?.path;
+    const deleted = String(changeType).toLowerCase().includes('delete');
+    const isFile = !item?.gitObjectType || item.gitObjectType === 'blob';
+    if (!filePath || deleted || !isFile || isBinaryPath(filePath)) {
+      return { changeType, path: filePath };
+    }
+
+    const [previousContent, currentContent] = await Promise.all([
+      azureItemContent(repositoryRoot, filePath, targetCommitId, headers),
+      azureItemContent(repositoryRoot, filePath, sourceCommitId, headers)
+    ]);
+    const additions = extractAddedContent(previousContent, currentContent);
+    return {
+      changeType,
+      path: filePath,
+      addedContent: additions?.content || undefined,
+      addedContentTruncated: additions?.truncated || undefined
+    };
+  });
 
   return {
     title: truncateText(pullRequest.title, 2_000),
@@ -307,21 +277,21 @@ export async function getAzurePullRequest(urlValue, pat) {
     targetBranch: pullRequest.targetRefName,
     reviewers: (pullRequest.reviewers || []).map(({ displayName, vote }) => ({
       displayName: truncateText(displayName, 1_000),
-      vote,
+      vote
     })),
     reviewComments: (threads?.value || [])
-      .flatMap((thread) =>
+      .flatMap(thread =>
         (thread.comments || [])
-          .filter((comment) => !comment.isDeleted && comment.content)
+          .filter(comment => !comment.isDeleted && comment.content)
           .map(({ content, author }) => ({
             content: truncateText(content, MAX_COMMENT_LENGTH),
-            author: truncateText(author?.displayName, 1_000),
-          })),
+            author: truncateText(author?.displayName, 1_000)
+          }))
       )
       .slice(0, MAX_REVIEW_COMMENTS),
     workItems: (workItems?.value || []).map(({ id, url }) => ({ id, url })),
     requestedPath: requestedPath || undefined,
     latestIterationId,
-    changedFiles,
+    changedFiles
   };
 }

package/mcp/azurepr-mcp-bridge/index.js

@@ -1,65 +1,61 @@
 #!/usr/bin/env node
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { getAzurePullRequest, serializePullRequest } from "./azure-devops.js";
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { getAzurePullRequest, serializePullRequest } from './azure-devops.js';
 
 const server = new McpServer(
-  { name: "azurepr-mcp-bridge", version: "1.0.0" },
+  { name: 'azurepr-mcp-bridge', version: '1.0.0' },
   {
     instructions:
-      "Use get_azure_pull_request to read Azure DevOps pull request metadata, review comments, linked work items, and changed text files. " +
-      "The tool is read-only and requires an HTTPS PR URL from dev.azure.com or *.visualstudio.com. " +
-      "AZURE_DEVOPS_PAT is used only for Azure DevOps API authentication and must never be exposed in output.",
-  },
+      'Use get_azure_pull_request to read Azure DevOps pull request metadata, review comments, linked work items, and changed text files. ' +
+      'The tool is read-only and requires an HTTPS PR URL from dev.azure.com or *.visualstudio.com. ' +
+      'AZURE_DEVOPS_PAT is used only for Azure DevOps API authentication and must never be exposed in output.'
+  }
 );
 
 server.registerTool(
-  "get_azure_pull_request",
+  'get_azure_pull_request',
   {
-    title: "读取 Azure DevOps PR",
+    title: '读取 Azure DevOps PR',
     description:
-      "读取 PR 基本信息、评审意见、关联工作项和变更文件。URL 可使用 path 查询参数限定仓库目录，例如 ?path=/src。",
+      '读取 PR 基本信息、评审意见、关联工作项和变更文件。URL 可使用 path 查询参数限定仓库目录，例如 ?path=/src。',
     inputSchema: {
-      url: z
-        .url()
-        .describe("dev.azure.com 或 *.visualstudio.com 的 Azure DevOps PR 地址"),
+      url: z.url().describe('dev.azure.com 或 *.visualstudio.com 的 Azure DevOps PR 地址')
     },
     annotations: {
       readOnlyHint: true,
       destructiveHint: false,
       idempotentHint: true,
-      openWorldHint: true,
-    },
+      openWorldHint: true
+    }
   },
   async ({ url }) => {
     try {
       const pat = process.env.AZURE_DEVOPS_PAT?.trim();
       if (!pat) {
-        throw new Error(
-          "AZURE_DEVOPS_PAT 未配置，Stdio MCP 无法读取 Azure DevOps PR",
-        );
+        throw new Error('AZURE_DEVOPS_PAT 未配置，Stdio MCP 无法读取 Azure DevOps PR');
       }
       const result = await getAzurePullRequest(url, pat);
       return {
-        content: [{ type: "text", text: serializePullRequest(result) }],
+        content: [{ type: 'text', text: serializePullRequest(result) }]
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       return {
         isError: true,
-        content: [{ type: "text", text: message }],
+        content: [{ type: 'text', text: message }]
       };
     }
-  },
+  }
 );
 
 async function main() {
   await server.connect(new StdioServerTransport());
 }
 
-main().catch((error) => {
-  console.error("Failed to start azurepr-mcp-bridge:", error);
+main().catch(error => {
+  console.error('Failed to start azurepr-mcp-bridge:', error);
   process.exitCode = 1;
 });