@autobest-ui/agent 1.0.1 → 1.0.3

package/mcp/figma-mcp-bridge/src/tools/nodes.js

@@ -5,7 +5,8 @@
 
 export const nodesTool = {
   name: 'figma_get_nodes',
-  description: 'Get detailed information about specific Figma nodes by their IDs. Returns node properties including type, position, size, fills, strokes, auto-layout (including layoutWrap and counterAxisSpacing), clipsContent, node-level boundVariables, explicitVariableModes, and more.',
+  description:
+    'Get detailed information about specific Figma nodes by their IDs. Returns node properties including type, position, size, fills, strokes, auto-layout (including layoutWrap and counterAxisSpacing), clipsContent, node-level boundVariables, explicitVariableModes, and more.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -22,15 +23,21 @@ export const nodesTool = {
 export async function handleGetNodes(bridge, args) {
   if (!bridge.isConnected()) {
     return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          error: {
-            code: 'NOT_CONNECTED',
-            message: 'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
-          }
-        }, null, 2)
-      }],
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              error: {
+                code: 'NOT_CONNECTED',
+                message: 'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
+              }
+            },
+            null,
+            2
+          )
+        }
+      ],
       isError: true
     };
   }
@@ -39,15 +46,21 @@ export async function handleGetNodes(bridge, args) {
 
   if (!nodeIds || !Array.isArray(nodeIds) || nodeIds.length === 0) {
     return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          error: {
-            code: 'INVALID_PARAMS',
-            message: 'nodeIds must be a non-empty array of node IDs'
-          }
-        }, null, 2)
-      }],
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              error: {
+                code: 'INVALID_PARAMS',
+                message: 'nodeIds must be a non-empty array of node IDs'
+              }
+            },
+            null,
+            2
+          )
+        }
+      ],
       isError: true
     };
   }
@@ -56,22 +69,30 @@ export async function handleGetNodes(bridge, args) {
     const result = await bridge.sendCommand('get_nodes', { nodeIds, depth });
 
     return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify(result, null, 2)
-      }]
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
     };
   } catch (error) {
     return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          error: {
-            code: error.code || 'UNKNOWN_ERROR',
-            message: error.message
-          }
-        }, null, 2)
-      }],
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              error: {
+                code: error.code || 'UNKNOWN_ERROR',
+                message: error.message
+              }
+            },
+            null,
+            2
+          )
+        }
+      ],
       isError: true
     };
   }

package/mcp/figma-mcp-bridge/src/tools/pages.js

@@ -5,7 +5,8 @@
 
 export const pagesTool = {
   name: 'figma_list_pages',
-  description: 'List all pages in the current Figma document. Returns page IDs, names, and indicates which page is currently active.',
+  description:
+    'List all pages in the current Figma document. Returns page IDs, names, and indicates which page is currently active.',
   inputSchema: {
     type: 'object',
     properties: {},
@@ -16,15 +17,21 @@ export const pagesTool = {
 export async function handleListPages(bridge) {
   if (!bridge.isConnected()) {
     return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          error: {
-            code: 'NOT_CONNECTED',
-            message: 'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
-          }
-        }, null, 2)
-      }],
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              error: {
+                code: 'NOT_CONNECTED',
+                message: 'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
+              }
+            },
+            null,
+            2
+          )
+        }
+      ],
       isError: true
     };
   }
@@ -33,22 +40,30 @@ export async function handleListPages(bridge) {
     const result = await bridge.sendCommand('list_pages', {});
 
     return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify(result, null, 2)
-      }]
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
     };
   } catch (error) {
     return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          error: {
-            code: error.code || 'UNKNOWN_ERROR',
-            message: error.message
-          }
-        }, null, 2)
-      }],
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              error: {
+                code: error.code || 'UNKNOWN_ERROR',
+                message: error.message
+              }
+            },
+            null,
+            2
+          )
+        }
+      ],
       isError: true
     };
   }

package/mcp/rag-mcp-bridge/README.md

@@ -1,13 +1,13 @@
 # rag-mcp-bridge
 
-`rag-mcp-bridge` 是 PRD Knowledge RAG API 的本地 STDIO MCP 适配器。它负责展开 Markdown 路径并把 MCP 工具调用转发给 HTTP API；文档解析、Embedding、数据库读写和检索仍由 Express 服务完成。
+`rag-mcp-bridge` 是 PRD Knowledge RAG API 的本地 STDIO MCP 适配器。它在 MCP 客户端所在机器展开并读取 Markdown，把实际引用的本地图片打包到 `documents` 请求后转发给 HTTP API。因此 API 可以部署在另一台机器，不需要访问客户端的本地文件系统。Embedding、数据库读写和检索仍由 Express 服务完成。
 
 ## 启动
 
 先启动 PRD Knowledge HTTP API。直接在终端验证时，必须在同一条命令中提供 API 根地址：
 
 ```bash
-RAG_API_BASE_URL="http://127.0.0.1:3000/api/knowledge" \
+RAG_API_BASE_URL="http://192.168.1.12:3000/api/knowledge" \
 npx --yes \
   --package=@autobest-ui/agent@latest \
   autobest-rag-mcp
@@ -26,7 +26,7 @@ tool_timeout_sec = 120
 enabled = true
 
 [mcp_servers.rag-mcp-bridge.env]
-RAG_API_BASE_URL = "http://127.0.0.1:3000/api/knowledge"
+RAG_API_BASE_URL = "http://192.168.1.12:3000/api/knowledge"
 RAG_MCP_HTTP_TIMEOUT_MS = "120000"
 ```
 
@@ -47,6 +47,43 @@ RAG_MCP_HTTP_TIMEOUT_MS = "120000"
 - `update_spec_file`：录入已经合并并确认生效的迭代 Spec。
 - `retrieve_knowledge`：检索 PRD 基线和迭代 Spec。
 
+两个录入工具的 MCP 参数保持不变：`paths` 支持单个 Markdown 绝对路径、绝对路径数组或目录。bridge 递归展开目录，并向 API 发送以下协议：
+
+```json
+{
+  "documents": [
+    {
+      "docKey": "/absolute/client/path/file.md",
+      "fileName": "file.md",
+      "markdown": "完整 Markdown 内容",
+      "assets": [
+        {
+          "path": "../.attachments/example.png",
+          "mimeType": "image/png",
+          "base64": "..."
+        }
+      ]
+    }
+  ],
+  "platform": "app",
+  "module": "vehicle-selector",
+  "page": "home"
+}
+```
+
+`add_prd_file` 发送到 `/add-prd`；`update_spec_file` 发送到 `/add-spec`，并额外保留 `sprintVersion`、`iterationTag`。多文档请求不发送 `page`，由后端按文件名分别推断；单文档请求继续透传显式 `page`。`retrieve_knowledge` 的 GET 协议不变。
+
+## 图片安全边界
+
+- 使用 Markdown AST 识别行内图片和引用式图片，不修改 Markdown 原文。
+- URL 编码会在解析本地文件路径前解码，上传的 `assets[].path` 保留 Markdown 中的原引用。
+- HTTP、HTTPS、data URL、其他带 scheme 的 URL、协议相对 URL 和站点根路径引用保持原样，不读取或上传。
+- 本地图片仅支持 PNG、JPEG、GIF、WebP；扩展名必须与文件内容签名对应。
+- 普通相对图片必须位于 Markdown 所在目录内；允许使用 `../.attachments/...` 引用紧邻的上级附件目录。词法路径和符号链接真实路径都会进行边界检查。
+- 单张图片最大 `10 MiB`；包含 Markdown 和 base64 后的完整 JSON 请求最大 `40 MiB`。
+- Markdown 引用的受支持本地图片缺失、类型非法、内容签名不符或路径越界时，整次调用失败并返回包含 Markdown 文件名和图片引用的错误。
+- 同一 Markdown 内相同引用只上传一次；不同 Markdown 引用同一图片时，每个 document 都携带自己的 asset，保持文档协议自包含。
+
 运行协议测试：
 
 ```bash

package/mcp/rag-mcp-bridge/codex-system-prompt.md

@@ -17,4 +17,4 @@
 - `update_spec_file`：仅在PR已经合并且leader review确认变更生效后调用。必须传与基线一致的 `platform`；`paths` 同样支持单个spec文件、spec文件数组、spec文件夹；只传本次改动spec，不需要完整PRD。`sprintVersion` 必须按迭代递增。单文件spec可以显式传其 `page`。
 - `retrieve_knowledge`：分析需求、制定实现方案、编写代码或判断历史行为前调用。必须根据目标端传 `platform`，已知模块时传 `module`，明确页面时传 `page`，已知文档时传 `docKey`。仅明确需要六字段结构化PRD时传 `enableStruct=true`；仅需要在UI显示需求截图时传 `includeImages=true`。
 
-`rag-mcp-bridge` 仅执行文件夹扫描和HTTP转发。文档解析、截图提取、Embedding、RAG与PostgreSQL操作全部由Express后端完成。
+`rag-mcp-bridge` 在MCP客户端所在机器展开路径、读取Markdown，并使用Markdown AST收集实际引用且通过安全校验的本地图片，然后通过 `documents` 协议把内容发送给API。远端API不需要访问客户端路径；Embedding、RAG与PostgreSQL操作仍由Express后端完成。

package/mcp/rag-mcp-bridge/config.toml.example

@@ -7,6 +7,6 @@ enabled = true
 
 [mcp_servers.rag-mcp-bridge.env]
 # 必填：按实际部署地址修改，MCP 服务本身不提供默认地址。
-RAG_API_BASE_URL = "http://127.0.0.1:3000/api/knowledge"
+RAG_API_BASE_URL = "http://192.168.1.12:3000/api/knowledge"
 # 可选：单次 HTTP 请求超时，单位为毫秒。
 RAG_MCP_HTTP_TIMEOUT_MS = "120000"

package/mcp/rag-mcp-bridge/documents.js

@@ -0,0 +1,236 @@
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_REQUEST_BYTES = 40 * 1024 * 1024;
+
+const IMAGE_TYPES = new Map([
+  ['.gif', 'image/gif'],
+  ['.jpeg', 'image/jpeg'],
+  ['.jpg', 'image/jpeg'],
+  ['.png', 'image/png'],
+  ['.webp', 'image/webp']
+]);
+
+async function scanMarkdownDirectory(directoryPath) {
+  const markdownFiles = [];
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
+    const entryPath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      markdownFiles.push(...(await scanMarkdownDirectory(entryPath)));
+    } else if (entry.isFile() && path.extname(entry.name).toLowerCase() === '.md') {
+      markdownFiles.push(path.resolve(entryPath));
+    }
+  }
+  return markdownFiles;
+}
+
+export async function expandMarkdownPaths(pathsInput) {
+  const inputs = Array.isArray(pathsInput) ? pathsInput : [pathsInput];
+  const markdownFiles = [];
+
+  for (const input of inputs) {
+    if (typeof input !== 'string' || !input.trim()) {
+      throw new Error('paths中的每一项都必须是非空字符串');
+    }
+    if (!path.isAbsolute(input.trim())) {
+      throw new Error(`必须使用绝对路径: ${input}`);
+    }
+
+    const absolutePath = path.resolve(input.trim());
+    const pathStat = await stat(absolutePath);
+    if (pathStat.isDirectory()) {
+      markdownFiles.push(...(await scanMarkdownDirectory(absolutePath)));
+    } else if (pathStat.isFile() && path.extname(absolutePath).toLowerCase() === '.md') {
+      markdownFiles.push(absolutePath);
+    } else {
+      throw new Error(`路径不是Markdown文件或文件夹: ${absolutePath}`);
+    }
+  }
+
+  const uniquePaths = [...new Set(markdownFiles)].sort((left, right) => left.localeCompare(right));
+  if (uniquePaths.length === 0) {
+    throw new Error('指定路径中没有找到任何.md文件');
+  }
+  return uniquePaths;
+}
+
+function walk(node, visit) {
+  visit(node);
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) walk(child, visit);
+}
+
+function extractImageReferences(markdown) {
+  const tree = fromMarkdown(markdown);
+  const definitions = new Map();
+  walk(tree, node => {
+    if (node.type === 'definition') definitions.set(node.identifier, node.url);
+  });
+
+  const references = [];
+  walk(tree, node => {
+    if (node.type === 'image') references.push(node.url);
+    if (node.type === 'imageReference') {
+      const definitionUrl = definitions.get(node.identifier);
+      if (definitionUrl) references.push(definitionUrl);
+    }
+  });
+  return [...new Set(references)];
+}
+
+function isNonLocalReference(reference) {
+  return (
+    reference.startsWith('#') ||
+    reference.startsWith('/') ||
+    reference.startsWith('//') ||
+    /^[a-z][a-z\d+.-]*:/i.test(reference)
+  );
+}
+
+function decodeLocalReference(reference, markdownPath) {
+  const pathOnly = reference.split(/[?#]/, 1)[0];
+  try {
+    const decoded = decodeURIComponent(pathOnly);
+    if (!decoded || decoded.includes('\0') || decoded.includes('\\')) {
+      throw new Error('图片路径为空或包含不支持的字符');
+    }
+    return decoded;
+  } catch (error) {
+    const reason = error instanceof URIError ? 'URL编码无效' : error.message;
+    throw new Error(`Markdown ${path.basename(markdownPath)} 的图片路径无效: ${reference} (${reason})`);
+  }
+}
+
+function isPathInside(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function allowedAssetRoot(markdownPath, decodedReference) {
+  const markdownDirectory = path.dirname(markdownPath);
+  const segments = decodedReference.split('/');
+  if (segments[0] !== '..') return markdownDirectory;
+  if (segments[1] !== '.attachments') return undefined;
+  return path.resolve(markdownDirectory, '..', '.attachments');
+}
+
+function detectMimeType(buffer) {
+  if (buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+    return 'image/png';
+  }
+  if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  const prefix = buffer.subarray(0, 6).toString('ascii');
+  if (prefix === 'GIF87a' || prefix === 'GIF89a') return 'image/gif';
+  if (
+    buffer.length >= 12 &&
+    buffer.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    buffer.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return 'image/webp';
+  }
+  return undefined;
+}
+
+async function readLocalAsset(markdownPath, reference) {
+  const decodedReference = decodeLocalReference(reference, markdownPath);
+  const extension = path.extname(decodedReference).toLowerCase();
+  const expectedMimeType = IMAGE_TYPES.get(extension);
+  if (!expectedMimeType) {
+    throw new Error(
+      `Markdown ${path.basename(markdownPath)} 引用了不受支持的图片类型: ${reference}（仅支持 PNG、JPEG、GIF、WebP）`
+    );
+  }
+
+  const markdownDirectory = path.dirname(markdownPath);
+  const assetPath = path.resolve(markdownDirectory, decodedReference);
+  const allowedRoot = allowedAssetRoot(markdownPath, decodedReference);
+  if (!allowedRoot || !isPathInside(assetPath, allowedRoot)) {
+    throw new Error(`Markdown ${path.basename(markdownPath)} 的图片路径越界: ${reference}`);
+  }
+
+  let assetStat;
+  try {
+    assetStat = await stat(assetPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`Markdown ${path.basename(markdownPath)} 引用的图片不存在: ${reference}`);
+    }
+    throw error;
+  }
+  if (!assetStat.isFile()) {
+    throw new Error(`Markdown ${path.basename(markdownPath)} 引用的图片不是文件: ${reference}`);
+  }
+  if (assetStat.size > MAX_IMAGE_BYTES) {
+    throw new Error(
+      `Markdown ${path.basename(markdownPath)} 引用的图片超过单文件限制 ${MAX_IMAGE_BYTES} bytes: ${reference}`
+    );
+  }
+
+  const [realAssetPath, realAllowedRoot] = await Promise.all([realpath(assetPath), realpath(allowedRoot)]);
+  if (!isPathInside(realAssetPath, realAllowedRoot)) {
+    throw new Error(`Markdown ${path.basename(markdownPath)} 的图片路径通过符号链接越界: ${reference}`);
+  }
+
+  const buffer = await readFile(realAssetPath);
+  if (buffer.length > MAX_IMAGE_BYTES) {
+    throw new Error(
+      `Markdown ${path.basename(markdownPath)} 引用的图片超过单文件限制 ${MAX_IMAGE_BYTES} bytes: ${reference}`
+    );
+  }
+  const detectedMimeType = detectMimeType(buffer);
+  if (detectedMimeType !== expectedMimeType) {
+    throw new Error(`Markdown ${path.basename(markdownPath)} 引用的图片内容与扩展名不匹配: ${reference}`);
+  }
+  return {
+    path: reference,
+    mimeType: expectedMimeType,
+    base64: buffer.toString('base64')
+  };
+}
+
+export async function buildDocuments(markdownPaths) {
+  const documents = [];
+  let contentBytes = 0;
+  for (const markdownPath of markdownPaths) {
+    const markdown = await readFile(markdownPath, 'utf8');
+    contentBytes += Buffer.byteLength(markdown);
+    if (contentBytes > MAX_REQUEST_BYTES) {
+      throw new Error(`documents内容超过单次请求限制 ${MAX_REQUEST_BYTES} bytes`);
+    }
+    const imageReferences = extractImageReferences(markdown);
+    const assets = [];
+    for (const reference of imageReferences) {
+      if (!reference || isNonLocalReference(reference)) continue;
+      const asset = await readLocalAsset(markdownPath, reference);
+      contentBytes +=
+        Buffer.byteLength(asset.path) + Buffer.byteLength(asset.mimeType) + Buffer.byteLength(asset.base64);
+      if (contentBytes > MAX_REQUEST_BYTES) {
+        throw new Error(`documents内容超过单次请求限制 ${MAX_REQUEST_BYTES} bytes`);
+      }
+      assets.push(asset);
+    }
+    documents.push({
+      docKey: path.resolve(markdownPath),
+      fileName: path.basename(markdownPath),
+      markdown,
+      assets
+    });
+  }
+  return documents;
+}
+
+export function serializeRequestBody(body) {
+  const serialized = JSON.stringify(body);
+  const requestBytes = Buffer.byteLength(serialized);
+  if (requestBytes > MAX_REQUEST_BYTES) {
+    throw new Error(`documents请求超过单次限制 ${MAX_REQUEST_BYTES} bytes（实际 ${requestBytes} bytes）`);
+  }
+  return serialized;
+}