@autobest-ui/agent 1.0.2 → 1.0.3

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

@@ -1,6 +1,6 @@
 # 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 服务完成。
 
 ## 启动
 
@@ -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/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;
+}

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

@@ -4,17 +4,16 @@
  * RAG MCP bridge for the local PRD knowledge Express API.
  *
  * Responsibilities are deliberately limited to:
- * 1. Expanding file, file-array, and directory inputs into Markdown paths.
- * 2. Forwarding MCP tool calls to the local HTTP API.
+ * 1. Packaging local Markdown files and referenced images for remote ingestion.
+ * 2. Forwarding MCP tool calls to the configured HTTP API.
  *
- * Database access, Markdown parsing, embeddings, and RAG stay in Express.
+ * Requirement parsing, database access, embeddings, and RAG stay in Express.
  */
 
-import { readdir, stat } from 'node:fs/promises';
-import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { buildDocuments, expandMarkdownPaths, serializeRequestBody } from './documents.js';
 
 const DEFAULT_HTTP_TIMEOUT_MS = 120_000;
 
@@ -62,60 +61,13 @@ const pageSchema = z
   .describe('业务页面键，例如home、pl、pn、pd、name-search；录入多个文件时不要传，由后端按文件名分别推断');
 const docKeySchema = z.string().min(1).optional().describe('需要限定到单一文档时传knowledge_doc.doc_key绝对路径');
 
-/** Recursively collects Markdown files from a directory in stable order. */
-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;
-}
-
-/** Normalizes all supported path inputs to a unique array of absolute .md files. */
-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;
-}
-
 /** Posts JSON to Express and returns its parsed response body. */
 async function postJson(endpoint, body) {
+  const serializedBody = serializeRequestBody(body);
   const response = await fetch(`${API_BASE_URL}${endpoint}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
-    body: JSON.stringify(body),
+    body: serializedBody,
     signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
   });
   const responseText = await response.text();
@@ -210,12 +162,13 @@ server.registerTool(
   async ({ paths, platform, module, page }) => {
     try {
       const expandedPaths = await expandMarkdownPaths(paths);
+      const documents = await buildDocuments(expandedPaths);
       return toolSuccess(
         await postJson('/add-prd', {
-          paths: expandedPaths,
+          documents,
           platform,
           module,
-          page
+          page: documents.length === 1 ? page : undefined
         })
       );
     } catch (error) {
@@ -248,14 +201,15 @@ server.registerTool(
   async ({ paths, sprintVersion, iterationTag, platform, module, page }) => {
     try {
       const expandedPaths = await expandMarkdownPaths(paths);
+      const documents = await buildDocuments(expandedPaths);
       return toolSuccess(
         await postJson('/add-spec', {
-          paths: expandedPaths,
+          documents,
           sprintVersion,
           iterationTag,
           platform,
           module,
-          page
+          page: documents.length === 1 ? page : undefined
         })
       );
     } catch (error) {

package/mcp/rag-mcp-bridge/index.test.js

@@ -1,52 +1,279 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import os from 'node:os';
 import path from 'node:path';
-import test from 'node:test';
+import { after, before, 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 {
+  MAX_IMAGE_BYTES,
+  MAX_REQUEST_BYTES,
+  buildDocuments,
+  expandMarkdownPaths,
+  serializeRequestBody
+} from './documents.js';
 
 const directory = path.dirname(fileURLToPath(import.meta.url));
+const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00]);
 
-test('initializes and exposes the RAG tools over stdio', async () => {
-  const client = new Client({ name: 'rag-mcp-bridge-test', version: '1.0.0' });
+let apiServer;
+let client;
+let temporaryDirectory;
+const requests = [];
+
+async function readRequestBody(request) {
+  const chunks = [];
+  for await (const chunk of request) chunks.push(chunk);
+  return chunks.length > 0 ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : undefined;
+}
+
+async function callTool(name, args) {
+  return client.callTool({ name, arguments: args });
+}
+
+function toolText(result) {
+  return result.content.map(item => item.text ?? '').join('\n');
+}
+
+before(async () => {
+  temporaryDirectory = await mkdtemp(path.join(os.tmpdir(), 'rag-mcp-bridge-'));
+  apiServer = createServer(async (request, response) => {
+    const url = new URL(request.url, 'http://localhost');
+    requests.push({
+      method: request.method,
+      path: url.pathname,
+      query: Object.fromEntries(url.searchParams),
+      body: await readRequestBody(request)
+    });
+    response.writeHead(200, { 'content-type': 'application/json' });
+    response.end(JSON.stringify({ ok: true, endpoint: url.pathname }));
+  });
+  await new Promise(resolve => apiServer.listen(0, '127.0.0.1', resolve));
+  const address = apiServer.address();
+  const apiBaseUrl = `http://127.0.0.1:${address.port}/api/knowledge`;
+
+  client = new Client({ name: 'rag-mcp-bridge-test', version: '1.0.0' });
   const transport = new StdioClientTransport({
     command: process.execPath,
     args: [path.join(directory, 'index.js')],
     cwd: path.resolve(directory, '../..'),
-    env: {
-      RAG_API_BASE_URL: 'http://192.168.1.12:3000/api/knowledge'
-    },
+    env: { RAG_API_BASE_URL: apiBaseUrl },
     stderr: 'pipe'
   });
+  await client.connect(transport);
+});
+
+after(async () => {
+  await client?.close();
+  await new Promise(resolve => apiServer?.close(resolve));
+  await rm(temporaryDirectory, { recursive: true, force: true });
+});
+
+test('initializes and preserves the existing MCP tool contract', async () => {
+  assert.equal(client.getServerVersion()?.name, 'rag-mcp-bridge');
+  assert.match(client.getInstructions() ?? '', /retrieve_knowledge/);
+  const { tools } = await client.listTools();
+  assert.deepEqual(
+    tools.map(({ name }) => name),
+    ['add_prd_file', 'update_spec_file', 'retrieve_knowledge']
+  );
+  assert.equal(tools.find(({ name }) => name === 'retrieve_knowledge')?.annotations?.readOnlyHint, true);
+});
+
+test('add_prd_file uploads one Unicode Markdown file and its encoded local image', async () => {
+  const root = path.join(temporaryDirectory, '单文件 根目录');
+  const docs = path.join(root, '页面 文档');
+  const attachments = path.join(root, '.attachments');
+  await Promise.all([mkdir(docs, { recursive: true }), mkdir(attachments, { recursive: true })]);
+  const markdownPath = path.join(docs, '首页 需求.md');
+  const imageReference = '../.attachments/%E7%A4%BA%E4%BE%8B%20%E5%9B%BE%E7%89%87.png';
+  const markdown = `# 首页\n\n![本地图片][local-shot]\n![远端](https://example.com/a.png)\n![内嵌](data:image/png;base64,AAAA)\n\n[local-shot]: ${imageReference}\n`;
+  await Promise.all([writeFile(markdownPath, markdown), writeFile(path.join(attachments, '示例 图片.png'), png)]);
+
+  const result = await callTool('add_prd_file', {
+    paths: markdownPath,
+    platform: 'app',
+    module: 'vehicle-selector',
+    page: 'home'
+  });
+  assert.notEqual(result.isError, true);
+  const request = requests.at(-1);
+  assert.equal(request.path, '/api/knowledge/add-prd');
+  assert.equal('paths' in request.body, false);
+  assert.equal(request.body.page, 'home');
+  assert.equal(request.body.documents.length, 1);
+  assert.deepEqual(request.body.documents[0], {
+    docKey: path.resolve(markdownPath),
+    fileName: '首页 需求.md',
+    markdown,
+    assets: [{ path: imageReference, mimeType: 'image/png', base64: png.toString('base64') }]
+  });
+});
+
+test('file arrays and recursive directories upload all documents, omit page, and preserve shared assets', async () => {
+  const root = path.join(temporaryDirectory, '批量');
+  const docs = path.join(root, 'docs');
+  const nested = path.join(docs, 'nested');
+  const attachments = path.join(root, '.attachments');
+  await Promise.all([mkdir(nested, { recursive: true }), mkdir(attachments, { recursive: true })]);
+  await writeFile(path.join(attachments, 'shared.png'), png);
+  const first = path.join(docs, 'PL.md');
+  const second = path.join(docs, 'PN.md');
+  const third = path.join(nested, 'PD.md');
+  await Promise.all([
+    writeFile(first, '![shared](../.attachments/shared.png)'),
+    writeFile(second, '![shared](../.attachments/shared.png)'),
+    writeFile(third, '# no local image')
+  ]);
+
+  await callTool('add_prd_file', { paths: [first, second], platform: 'app', page: 'pl' });
+  const arrayRequest = requests.at(-1);
+  assert.equal(arrayRequest.body.page, undefined);
+  assert.equal(arrayRequest.body.documents.length, 2);
+  assert.equal(arrayRequest.body.documents[0].assets[0].base64, png.toString('base64'));
+  assert.equal(arrayRequest.body.documents[1].assets[0].base64, png.toString('base64'));
+
+  await callTool('add_prd_file', { paths: docs, platform: 'app', module: 'vehicle-selector' });
+  const directoryRequest = requests.at(-1);
+  assert.deepEqual(
+    directoryRequest.body.documents.map(document => document.fileName),
+    ['PD.md', 'PL.md', 'PN.md']
+  );
+  assert.equal(directoryRequest.body.page, undefined);
+});
+
+test('update_spec_file uses documents mode and preserves iteration metadata', async () => {
+  const specPath = path.join(temporaryDirectory, '迭代 spec.md');
+  await writeFile(specPath, '# iteration');
+  await callTool('update_spec_file', {
+    paths: specPath,
+    sprintVersion: 12,
+    iterationTag: '2026-S12',
+    platform: 'california-web',
+    module: 'vehicle-selector',
+    page: 'pd'
+  });
+  const request = requests.at(-1);
+  assert.equal(request.path, '/api/knowledge/add-spec');
+  assert.equal('paths' in request.body, false);
+  assert.equal(request.body.sprintVersion, 12);
+  assert.equal(request.body.iterationTag, '2026-S12');
+  assert.equal(request.body.page, 'pd');
+  assert.equal(request.body.documents[0].markdown, '# iteration');
+});
+
+test('retrieve_knowledge remains a GET request with the existing query mapping', async () => {
+  await callTool('retrieve_knowledge', {
+    query: 'selector requirements',
+    platform: 'app',
+    module: 'vehicle-selector',
+    page: 'home',
+    enableStruct: false,
+    includeImages: false
+  });
+  const request = requests.at(-1);
+  assert.equal(request.method, 'GET');
+  assert.equal(request.path, '/api/knowledge/search');
+  assert.deepEqual(request.query, {
+    query: 'selector requirements',
+    platform: 'app',
+    module: 'vehicle-selector',
+    page: 'home',
+    enableStruct: 'false',
+    includeImages: 'false'
+  });
+});
+
+test('reports missing images with the Markdown file and referenced path', async () => {
+  const markdownPath = path.join(temporaryDirectory, '缺图.md');
+  await writeFile(markdownPath, '![missing](images/not-found.png)');
+  const result = await callTool('add_prd_file', { paths: markdownPath, platform: 'app' });
+  assert.equal(result.isError, true);
+  assert.match(toolText(result), /缺图\.md/);
+  assert.match(toolText(result), /images\/not-found\.png/);
+  assert.match(toolText(result), /不存在/);
+});
+
+test('rejects unsafe image inputs', async t => {
+  await t.test('unsupported extension', async () => {
+    const markdownPath = path.join(temporaryDirectory, '非法类型.md');
+    await writeFile(markdownPath, '![svg](image.svg)');
+    const result = await callTool('add_prd_file', { paths: markdownPath, platform: 'app' });
+    assert.equal(result.isError, true);
+    assert.match(toolText(result), /不受支持的图片类型/);
+  });
+
+  await t.test('MIME signature mismatch', async () => {
+    const markdownPath = path.join(temporaryDirectory, '伪装图片.md');
+    await Promise.all([
+      writeFile(markdownPath, '![fake](fake.png)'),
+      writeFile(path.join(temporaryDirectory, 'fake.png'), 'secret')
+    ]);
+    const result = await callTool('add_prd_file', { paths: markdownPath, platform: 'app' });
+    assert.equal(result.isError, true);
+    assert.match(toolText(result), /内容与扩展名不匹配/);
+  });
+
+  await t.test('single image size limit', async () => {
+    const markdownPath = path.join(temporaryDirectory, '超大图片.md');
+    const oversized = Buffer.alloc(MAX_IMAGE_BYTES + 1);
+    png.copy(oversized);
+    await Promise.all([
+      writeFile(markdownPath, '![large](large.png)'),
+      writeFile(path.join(temporaryDirectory, 'large.png'), oversized)
+    ]);
+    const result = await callTool('add_prd_file', { paths: markdownPath, platform: 'app' });
+    assert.equal(result.isError, true);
+    assert.match(toolText(result), /超过单文件限制/);
+  });
 
-  try {
-    await client.connect(transport);
+  await t.test('path traversal outside approved attachment roots', async () => {
+    const docs = path.join(temporaryDirectory, 'traversal', 'docs');
+    await mkdir(docs, { recursive: true });
+    const markdownPath = path.join(docs, '越界.md');
+    await writeFile(markdownPath, '![outside](../secret.png)');
+    const result = await callTool('add_prd_file', { paths: markdownPath, platform: 'app' });
+    assert.equal(result.isError, true);
+    assert.match(toolText(result), /越界\.md/);
+    assert.match(toolText(result), /\.\.\/secret\.png/);
+    assert.match(toolText(result), /路径越界/);
+  });
+});
 
-    assert.equal(client.getServerVersion()?.name, 'rag-mcp-bridge');
-    assert.match(client.getInstructions() ?? '', /retrieve_knowledge/);
+test('enforces the total request size while packaging and serializing', async () => {
+  const markdownPath = path.join(temporaryDirectory, '超大文档.md');
+  await writeFile(markdownPath, 'x'.repeat(MAX_REQUEST_BYTES + 1));
+  await assert.rejects(() => buildDocuments([markdownPath]), /内容超过单次请求限制/);
+  assert.throws(
+    () => serializeRequestBody({ documents: [{ markdown: 'x'.repeat(MAX_REQUEST_BYTES) }] }),
+    /超过单次限制/
+  );
+});
 
-    const { tools } = await client.listTools();
-    assert.deepEqual(
-      tools.map(({ name }) => name),
-      ['add_prd_file', 'update_spec_file', 'retrieve_knowledge']
-    );
-    assert.equal(tools.find(({ name }) => name === 'retrieve_knowledge')?.annotations?.readOnlyHint, true);
-  } finally {
-    await client.close();
-  }
+test('expands files, arrays, and recursive directories in stable order', async () => {
+  const root = path.join(temporaryDirectory, 'expand');
+  const nested = path.join(root, 'nested');
+  await mkdir(nested, { recursive: true });
+  const a = path.join(root, 'a.md');
+  const b = path.join(nested, 'b.md');
+  await Promise.all([writeFile(a, '# a'), writeFile(b, '# b'), writeFile(path.join(root, 'ignored.txt'), 'x')]);
+  assert.deepEqual(await expandMarkdownPaths(a), [a]);
+  assert.deepEqual(await expandMarkdownPaths([b, a]), [a, b]);
+  assert.deepEqual(await expandMarkdownPaths(root), [a, b]);
+  assert.equal((await buildDocuments([a]))[0].markdown, '# a');
 });
 
 test('fails to start when RAG_API_BASE_URL is not configured', () => {
   const environment = { ...process.env };
   delete environment.RAG_API_BASE_URL;
-
   const result = spawnSync(process.execPath, [path.join(directory, 'index.js')], {
     cwd: path.resolve(directory, '../..'),
     env: environment,
     encoding: 'utf8'
   });
-
   assert.notEqual(result.status, 0);
   assert.match(result.stderr, /RAG_API_BASE_URL is required/);
 });

package/mcp/rag-mcp-bridge/package.json

@@ -10,12 +10,13 @@
   },
   "scripts": {
     "start": "node index.js",
-    "lint": "node --check index.js && node --check index.test.js",
+    "lint": "node --check index.js && node --check documents.js && node --check index.test.js",
     "test": "node --test index.test.js",
     "verify": "npm run lint && npm test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
+    "mdast-util-from-markdown": "2.0.2",
     "zod": "4.4.3"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "private": false,
   "description": "Autobest Agent skills/plugins/mcp assets + sync cli",
   "files": [
@@ -39,6 +39,7 @@
     "@modelcontextprotocol/sdk": "1.30.0",
     "diff": "9.0.0",
     "fs-extra": "11.3.0",
+    "mdast-util-from-markdown": "2.0.2",
     "ws": "8.18.3",
     "zod": "4.4.3"
   },