@reglow/reui-mcp 0.1.0

package/server.mjs

@@ -0,0 +1,710 @@
+/**
+ * ReUI MCP 服务器：注册工具并桥接 stdio 传输
+ *
+ * 工具能力对齐 Semi MCP，并针对 ReUI（Vue 3 + Tailwind v4 组件库）补充检索与指南：
+ * - get_reui_document       组件文档 / 组件总览
+ * - get_reui_code_examples  文档中的可复制示例
+ * - list_component_files    组件源码文件清单
+ * - get_file_code           读取组件内文件内容
+ * - get_function_code       提取函数 / 常量 / 类定义
+ * - search_reui_docs        跨文档与源码检索
+ * - get_reui_guide          库级指南（安装 / 主题 / i18n / Nuxt / 构建 / 约定）
+ *
+ * 注意：stdio 模式下 stdout 仅用于协议通信，所有日志必须走 stderr。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import {
+  CATEGORIES,
+  DOCS_BASE,
+  componentLabel,
+  docsUrlFor,
+} from "./catalog.mjs";
+import { createKnowledge } from "./knowledge.mjs";
+
+const PACKAGE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const OWN_PACKAGE = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8"),
+);
+
+const GUIDE_TOPICS = [
+  "overview",
+  "install",
+  "theme",
+  "i18n",
+  "nuxt",
+  "build",
+  "conventions",
+];
+
+/** 文本结果 */
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+/** 错误结果（让 AI 明确失败原因并自行纠正参数） */
+function errorResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+function sourceLabel(source) {
+  return (
+    {
+      workspace: "仓库工作区（--root / 仓库内运行）",
+      local: "项目本地已安装包",
+      version: "指定 npm 版本（缓存）",
+      site: "官方文档站点兜底（最新版）",
+      none: "无可用知识源",
+    }[source] ?? source
+  );
+}
+
+/** 响应头：知识来源与版本，避免 AI 误判文档对应的版本 */
+function metaHeader(knowledge, extraLines = []) {
+  const meta = knowledge.meta();
+  const lines = [
+    `> 知识源：${sourceLabel(meta.source)}｜组件库版本：\`${meta.version}\`${meta.root ? `｜路径：\`${meta.root}\`` : ""
+    }`,
+  ];
+  if (meta.warning) lines.push(`> ⚠️ ${meta.warning}`);
+  lines.push(...extraLines);
+  return lines.join("\n");
+}
+
+/** 从组件 index 文件推导导入方式 */
+function importInfo(knowledge, entry) {
+  const candidates = ["index.ts", "index.d.ts", "index.js"];
+  let text = null;
+  let used = null;
+  for (const file of candidates) {
+    const result = knowledge.readComponentFile(entry.name, file);
+    if (result?.text) {
+      text = result.text;
+      used = file;
+      break;
+    }
+  }
+  if (!text) return null;
+  const names = new Set();
+  for (const match of text.matchAll(/export\s*\{([^}]*)\}/g)) {
+    for (const part of match[1].split(",")) {
+      const alias = part.trim().match(/as\s+([A-Za-z_$][\w$]*)$/);
+      const raw = alias
+        ? alias[1]
+        : part.trim().match(/^([A-Za-z_$][\w$]*)/)?.[1];
+      if (raw) names.add(raw);
+    }
+  }
+  const symbolList = [...names];
+  if (symbolList.length === 0) return null;
+  const subpath =
+    entry.layer === "ui"
+      ? `@reglow/reui/ui/${entry.name}`
+      : `@reglow/reui/reui/${entry.name}`;
+  return {
+    file: used,
+    symbols: symbolList,
+    main: `import { ${symbolList.join(", ")} } from "@reglow/reui";`,
+    subpath: `import { ${symbolList.join(", ")} } from "${subpath}";`,
+  };
+}
+
+/** 组件概览（按官网分类组织） */
+function renderOverview(knowledge, category) {
+  const entries = knowledge.listComponents({ category });
+  const byName = new Map(entries.map((entry) => [entry.name, entry]));
+  const blocks = [];
+  const knownCategories = CATEGORIES.map((item) => item.key);
+  for (const item of CATEGORIES) {
+    if (category && item.key !== category) continue;
+    const rows = item.components
+      .map((component) => {
+        const entry = byName.get(component.name);
+        if (!entry) return null;
+        const importName = entry.files.includes("index.ts") ? "✅" : "（dist）";
+        return `| \`${component.name}\` ${component.cn} | ${component.desc} | ${importName} | [文档](${docsUrlFor(component.name)}) |`;
+      })
+      .filter(Boolean);
+    if (rows.length === 0) continue;
+    blocks.push(
+      `## ${item.label}\n\n| 组件 | 说明 | 源码 | 官网 |\n| --- | --- | --- | --- |\n${rows.join("\n")}`,
+    );
+  }
+  // 官网未收录但仓库内存在的组件
+  const extra = entries.filter(
+    (entry) => !knownCategories.includes(entry.category),
+  );
+  if (extra.length > 0 && !category) {
+    blocks.push(
+      `## 其他（官网未收录 / 基础组件）\n\n| 组件 | 说明 | 来源 |\n| --- | --- | --- |\n${extra
+        .map(
+          (entry) =>
+            `| \`${entry.name}\` | ${entry.description || "—"} | ${entry.layer} |`,
+        )
+        .join("\n")}`,
+    );
+  }
+  return blocks.join("\n\n");
+}
+
+/**
+ * 创建 MCP 服务器
+ *
+ * @param {{ resolveKnowledge: (version?: string) => Promise<object>, defaultKnowledge: object, version?: string }} options
+ */
+export function createServer({ resolveKnowledge, defaultKnowledge }) {
+  const server = new McpServer({
+    name: "reui-mcp",
+    version: OWN_PACKAGE.version,
+  });
+
+  const withKnowledge = async (version) => resolveKnowledge(version);
+
+  // ============================ 1. 组件文档 ============================
+  server.registerTool(
+    "get_reui_document",
+    {
+      title: "获取 ReUI 组件文档",
+      description:
+        "获取 ReUI 组件库的组件文档。不传 component 时返回按分类组织的组件总览（组件名/说明/源码可用性/官网链接）；" +
+        "传 component 时返回该组件的完整文档（README：安装用法、代码示例、Props/Events/Slots 表格、Semantic DOM）。" +
+        "包内缺少 README 时会自动回退官方文档站点并在回复中标注来源。",
+      inputSchema: {
+        component: z
+          .string()
+          .optional()
+          .describe(
+            "组件名，kebab-case，如 splitter、date-picker、table；不传则返回组件总览",
+          ),
+        category: z
+          .enum([
+            "general",
+            "layout",
+            "navigation",
+            "data-entry",
+            "data-display",
+            "feedback",
+            "others",
+          ])
+          .optional()
+          .describe("分类过滤（仅总览生效）"),
+        version: z
+          .string()
+          .optional()
+          .describe(
+            "指定 @reglow/reui 版本（如 0.1.10、latest）；不传则使用项目本地已安装版本",
+          ),
+        source: z
+          .enum(["auto", "local", "site"])
+          .optional()
+          .describe(
+            "auto（默认）：本地优先、缺失时回退官网；local：仅本地；site：强制取官网最新文档",
+          ),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ component, category, version, source }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const meta = knowledge.meta();
+        if (!component) {
+          const overview = renderOverview(knowledge, category);
+          if (!overview) {
+            const siteOverview = await knowledge.siteOverview();
+            if (siteOverview) {
+              return textResult(
+                `${metaHeader(knowledge, ["", `> 官网总览：${siteOverview.url}`])}\n\n${siteOverview.markdown}`,
+              );
+            }
+            return errorResult(
+              `未找到任何组件信息。\n\n${metaHeader(knowledge)}\n\n` +
+              `请使用 \`--root <reui 仓库路径>\` 启动，或在已安装 @reglow/reui 的项目中运行；也可用 \`version\` 指定 npm 版本。`,
+            );
+          }
+          return textResult(
+            `${metaHeader(knowledge, ["", `> 官网总览：${DOCS_BASE}`])}\n\n# ReUI 组件总览\n\n${overview}`,
+          );
+        }
+
+        const entry = knowledge.getComponent(component);
+        if (source === "site" || (meta.source === "site" && !entry)) {
+          const { fetchSiteDocument } = await import("./site.mjs");
+          const siteDoc = await fetchSiteDocument(component);
+          if (siteDoc) {
+            return textResult(
+              `> 知识源：官方文档站点（最新版）｜链接：${siteDoc.url}\n\n# ${componentLabel(component)}\n\n${siteDoc.markdown}`,
+            );
+          }
+          return errorResult(
+            `官方文档站点暂无「${component}」页面（可能是新组件或名称不符）。\n可用组件见 \`get_reui_document\`（不传 component）。`,
+          );
+        }
+
+        const doc = await knowledge.getDocument(component);
+        if (!entry && doc.kind === "none") {
+          const names = knowledge
+            .listComponents()
+            .map((item) => item.name)
+            .slice(0, 60);
+          return errorResult(
+            `未找到组件「${component}」。\n\n可用组件（部分）：${names.join(", ")}\n\n` +
+            `提示：组件名为 kebab-case；\`PageTable\` → \`table\`，\`QRCode\` → \`qr-code\`。`,
+          );
+        }
+
+        const lines = [`# ${componentLabel(entry?.name ?? component)}`];
+        const facts = [];
+        if (entry) {
+          facts.push(
+            `> 分类：${entry.categoryLabel}｜源码目录：\`${entry.dir}\``,
+          );
+          const imports = importInfo(knowledge, entry);
+          if (imports) {
+            facts.push(
+              "> 导入方式：",
+              "",
+              "```ts",
+              imports.main,
+              imports.subpath,
+              "```",
+            );
+          }
+          const mainFiles = entry.files.filter(
+            (file) => file.endsWith(".vue") || file.endsWith("context.ts"),
+          );
+          if (mainFiles.length > 0) {
+            facts.push(
+              `> 源码文件：${mainFiles.map((file) => `\`${file}\``).join("、")}`,
+            );
+          }
+        }
+        if (doc.url) facts.push(`> 官方文档：${doc.url}`);
+        if (doc.kind === "site") {
+          facts.push(
+            "> ⚠️ 该版本包内未包含组件 README，以下正文来自官方文档站点（最新版），示例可能与指定版本存在差异。",
+          );
+        }
+        if (doc.kind === "types") {
+          facts.push(
+            "> ⚠️ 该版本包内未包含组件 README，以下内容由 `dist/**/*.d.ts` 汇总而成（仅类型与注释，无示例）。",
+          );
+        }
+        lines.push(
+          "",
+          metaHeader(knowledge, facts),
+          "",
+          "---",
+          "",
+          doc.markdown || "（无文档内容）",
+        );
+        return textResult(lines.join("\n"));
+      } catch (error) {
+        return errorResult(`获取文档失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 2. 代码示例 ============================
+  server.registerTool(
+    "get_reui_code_examples",
+    {
+      title: "获取 ReUI 组件代码示例",
+      description:
+        "从组件文档中提取可直接复制的代码示例（Vue SFC / TS），保留示例所属小节标题。" +
+        "用于快速拿到「官方推荐写法」，避免臆造 API。可用 index 取第 N 个示例，lang 过滤语言。",
+      inputSchema: {
+        component: z.string().describe("组件名，kebab-case"),
+        index: z
+          .number()
+          .int()
+          .min(0)
+          .optional()
+          .describe("示例下标（从 0 开始）；不传则返回全部"),
+        lang: z
+          .enum(["all", "vue", "ts", "js", "bash", "json", "text"])
+          .optional()
+          .describe("按语言过滤，默认 all"),
+        version: z.string().optional().describe("指定 @reglow/reui 版本"),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ component, index, lang, version }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const result = await knowledge.getCodeExamples(component, {
+          index,
+          lang: lang ?? "all",
+        });
+        if (result.examples.length === 0) {
+          return errorResult(
+            `未找到「${component}」的代码示例（来源：${result.source}）。\n` +
+            `可先用 \`get_reui_document\` 确认组件是否存在，或改用 \`get_reui_code_examples\` 的 lang=all。\n` +
+            `官网文档：${result.url ?? "无"}`,
+          );
+        }
+        const blocks = result.examples.map(
+          (example, i) =>
+            `### ${index !== undefined ? index : i}. ${example.title}\n\n\`\`\`${example.lang}\n${example.code}\n\`\`\``,
+        );
+        const origin =
+          result.source === "readme"
+            ? `组件 README（\`${result.path}\`，与项目版本一致）`
+            : result.source === "site"
+              ? "官方文档站点（最新版，示例可能高于当前版本）"
+              : "未知来源";
+        return textResult(
+          `# ${componentLabel(component)} 代码示例（共 ${result.examples.length} 个）\n\n` +
+          `> 来源：${origin}${result.url ? `｜官方文档：${result.url}` : ""}\n\n` +
+          metaHeader(knowledge) +
+          "\n\n---\n\n" +
+          blocks.join("\n\n"),
+        );
+      } catch (error) {
+        return errorResult(`获取代码示例失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 3. 文件清单 ============================
+  server.registerTool(
+    "list_component_files",
+    {
+      title: "列出 ReUI 组件源码文件",
+      description:
+        "列出组件目录下的源码文件清单（相对路径 / 行数 / 字节数），用于了解组件结构，再配合 get_file_code 查看具体实现。" +
+        "组件通常包含：Xxx.vue（组件实现）、context.ts / types.ts（类型与上下文）、index.ts（导出）、README.md（文档）、__tests__（单测，默认不列出）。",
+      inputSchema: {
+        component: z.string().describe("组件名，kebab-case"),
+        version: z.string().optional().describe("指定 @reglow/reui 版本"),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ component, version }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const entry = knowledge.getComponent(component);
+        if (!entry)
+          return errorResult(
+            `未找到组件「${component}」。可用组件见 get_reui_document（不传 component）。`,
+          );
+        const files = knowledge.listFiles(component) ?? [];
+        const rows = files
+          .map(
+            (file) =>
+              `| \`${file.path}\` | ${file.lines || "—"} | ${file.size} |`,
+          )
+          .join("\n");
+        const imports = importInfo(knowledge, entry);
+        return textResult(
+          `# ${componentLabel(entry.name)} 源码文件\n\n` +
+          metaHeader(knowledge, [
+            `> 分类：${entry.categoryLabel}｜目录：\`${entry.dir}\`｜文件数：${files.length}`,
+            ...(imports ? [`> 导入：\`${imports.main}\``] : []),
+          ]) +
+          `\n\n| 文件 | 行数 | 字节 |\n| --- | --- | --- |\n${rows}\n\n` +
+          `> 下一步：\`get_file_code\` 读取具体文件，\`get_function_code\` 直接取某个函数实现。`,
+        );
+      } catch (error) {
+        return errorResult(`列出文件失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 4. 文件内容 ============================
+  server.registerTool(
+    "get_file_code",
+    {
+      title: "读取 ReUI 组件文件内容",
+      description:
+        "读取组件目录内某个文件的代码（支持 startLine/endLine 只取片段）。用于查看组件实现细节、类型定义、样式与默认值。" +
+        "文件路径来自 list_component_files 的结果，禁止越出组件目录。",
+      inputSchema: {
+        component: z.string().describe("组件名，kebab-case"),
+        file: z
+          .string()
+          .describe(
+            "组件目录内的相对路径，如 Splitter.vue、context.ts、index.ts",
+          ),
+        version: z.string().optional().describe("指定 @reglow/reui 版本"),
+        startLine: z
+          .number()
+          .int()
+          .min(1)
+          .optional()
+          .describe("起始行（从 1 开始，含）"),
+        endLine: z.number().int().min(1).optional().describe("结束行（含）"),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ component, file, version, startLine, endLine }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const result = knowledge.readComponentFile(component, file, {
+          startLine,
+          endLine,
+        });
+        if (result.error)
+          return errorResult(`${result.error}\n\n${metaHeader(knowledge)}`);
+        const ext = path.extname(result.path).replace(".", "") || "ts";
+        const lang = ext === "vue" ? "vue" : ext === "d.ts" ? "ts" : ext;
+        return textResult(
+          `# \`${result.path}\`\n\n` +
+          metaHeader(knowledge, [
+            `> 组件：${componentLabel(component)}｜总行数：${result.totalLines}${startLine || endLine
+              ? `｜当前片段：${result.startLine}-${result.endLine}`
+              : ""
+            }`,
+          ]) +
+          `\n\n\`\`\`${lang}\n${result.text}\n\`\`\``,
+        );
+      } catch (error) {
+        return errorResult(`读取文件失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 5. 函数实现 ============================
+  server.registerTool(
+    "get_function_code",
+    {
+      title: "获取 ReUI 组件函数实现",
+      description:
+        "提取组件源码中某个函数 / 常量 / 类 / 接口的完整实现（含起止行号），用于深入理解组件逻辑与可复用工具。" +
+        "未命中时会返回该组件可用符号清单，便于纠正名称后重试。",
+      inputSchema: {
+        component: z.string().describe("组件名，kebab-case"),
+        name: z
+          .string()
+          .describe("符号名，如 startDrag、equalizeFrPanels、useResizable"),
+        file: z
+          .string()
+          .optional()
+          .describe(
+            "限定文件（如 Splitter.vue）；不传则在组件内所有 .vue/.ts 中查找",
+          ),
+        version: z.string().optional().describe("指定 @reglow/reui 版本"),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ component, name, file, version }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const result = knowledge.findFunction(component, name, { file });
+        if (result.error) {
+          const similar = (result.similarSymbols ?? []).join(", ");
+          const symbols = (result.availableSymbols ?? [])
+            .slice(0, 200)
+            .join(", ");
+          return errorResult(
+            `${result.error}\n\n` +
+            (similar ? `最相近的符号：${similar}\n\n` : "") +
+            (result.searched?.length
+              ? `已检索：${result.searched.map((item) => `\`${item}\``).join("、")}\n\n`
+              : "") +
+            (symbols
+              ? `该组件可用符号（共 ${result.allSymbolsCount ?? "?"} 个，展示前 80 个）：${symbols}`
+              : "") +
+            `\n\n提示：也可用 \`search_reui_docs\` 以关键词定位，再用 \`get_file_code\` 读取上下文。`,
+          );
+        }
+        return textResult(
+          `# \`${result.name}\`（${result.kind}）\n\n` +
+          metaHeader(knowledge, [
+            `> 组件：${componentLabel(component)}｜文件：\`${result.path}\`｜行号：${result.startLine}-${result.endLine}`,
+          ]) +
+          `\n\n\`\`\`ts\n${result.text}\n\`\`\``,
+        );
+      } catch (error) {
+        return errorResult(`提取函数失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 6. 文档检索 ============================
+  server.registerTool(
+    "search_reui_docs",
+    {
+      title: "检索 ReUI 文档与源码",
+      description:
+        "在组件文档、源码与库级文档中做关键词检索（多关键词空格分隔，按“全部命中”过滤），返回「组件 / 文件:行号 + 上下文片段 + 文档链接」。" +
+        "适合在不确定用哪个组件、或想找某个 prop / 事件 / CSS 变量在何处实现时使用。",
+      inputSchema: {
+        query: z
+          .string()
+          .describe("关键词，支持多词（空格分隔，如「折叠 collapsible」）"),
+        component: z.string().optional().describe("限定单个组件"),
+        category: z
+          .enum([
+            "general",
+            "layout",
+            "navigation",
+            "data-entry",
+            "data-display",
+            "feedback",
+            "others",
+          ])
+          .optional()
+          .describe("限定分类"),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(60)
+          .optional()
+          .describe("最多返回条数，默认 20"),
+        version: z.string().optional().describe("指定 @reglow/reui 版本"),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ query, component, category, limit, version }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const { hits, scanned, terms } = knowledge.search(query, {
+          component,
+          category,
+          limit,
+        });
+        if (hits.length === 0) {
+          return textResult(
+            `未检索到与「${query}」匹配的内容（已扫描 ${scanned} 个文件）。\n\n` +
+            `${metaHeader(knowledge)}\n\n` +
+            `建议：减少关键词数量、换用英文标识（如 \`allowClear\`）、或先用 \`get_reui_document\` 浏览组件总览。`,
+          );
+        }
+        const grouped = new Map();
+        for (const hit of hits) {
+          if (!grouped.has(hit.component)) grouped.set(hit.component, []);
+          grouped.get(hit.component).push(hit);
+        }
+        const blocks = [...grouped.entries()].map(([name, items]) => {
+          const link = items[0].docsUrl
+            ? `｜[官方文档](${items[0].docsUrl})`
+            : "";
+          const body = items
+            .map(
+              (hit) =>
+                `- \`${hit.path}:${hit.line}\`\n\n\`\`\`\n${hit.text}\n\`\`\``,
+            )
+            .join("\n");
+          return `## ${componentLabel(name)}${link}\n\n${body}`;
+        });
+        return textResult(
+          `# 检索「${query}」\n\n` +
+          `${metaHeader(knowledge, [
+            `> 命中 ${hits.length} 处（扫描 ${scanned} 个文件，关键词：${terms.join(" + ")}）`,
+          ])}\n\n---\n\n${blocks.join("\n\n")}`,
+        );
+      } catch (error) {
+        return errorResult(`检索失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 7. 库级指南 ============================
+  server.registerTool(
+    "get_reui_guide",
+    {
+      title: "获取 ReUI 使用指南",
+      description:
+        "获取库级指南：安装与引入（含按需子路径、样式）、主题定制、国际化、Nuxt 接入、构建发布与项目工程约定。" +
+        "在动手前用它对齐「正确引入方式 / 主题变量 / i18n 铁律 / Nuxt 配置」，避免踩坑。",
+      inputSchema: {
+        topic: z
+          .enum(GUIDE_TOPICS)
+          .optional()
+          .describe(
+            "主题：overview（总览）| install（安装引入）| theme（主题）| i18n（国际化）| nuxt（Nuxt 接入）| build（构建发布）| conventions（工程约定）",
+          ),
+        version: z.string().optional().describe("指定 @reglow/reui 版本"),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ topic, version }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const guide = knowledge.getGuide(topic ?? "overview");
+        if (!guide || guide.sections.length === 0) {
+          const doc = await knowledge.getDocument("README");
+          return textResult(
+            `${metaHeader(knowledge)}\n\n` +
+            `未取到本地指南章节（topic=${topic ?? "overview"}）。\n` +
+            `可用方式：指定 \`--root <reui 仓库路径>\` 启动以读取 \`guide.md\`；或先调用 \`get_reui_document\`。\n` +
+            (doc?.markdown ? `\n---\n\n${doc.markdown}` : ""),
+          );
+        }
+        const blocks = guide.sections.map(
+          (section) => `<!-- 来源：${section.file} -->\n\n${section.text}`,
+        );
+        return textResult(
+          `# ReUI 指南（${topic ?? "overview"}）\n\n` +
+          metaHeader(knowledge, [
+            `> 章节数：${guide.sections.length}｜官方文档：${guide.docsBase}`,
+          ]) +
+          "\n\n---\n\n" +
+          blocks.join("\n\n---\n\n"),
+        );
+      } catch (error) {
+        return errorResult(`获取指南失败：${error.message}`);
+      }
+    },
+  );
+
+  return server;
+}
+
+/**
+ * 默认知识解析器：按 version 缓存（同一进程内复用）
+ *
+ * @param {{ root?: string, logger?: (message: string) => void }} options
+ */
+export function createKnowledgeResolver(options = {}) {
+  const cache = new Map();
+  return async function resolveKnowledge(version) {
+    const key = version ? `version:${version}` : `local:${options.root ?? ""}`;
+    if (!cache.has(key)) {
+      cache.set(
+        key,
+        createKnowledge({
+          root: options.root,
+          version,
+          logger: options.logger ?? (() => { }),
+        }),
+      );
+    }
+    return cache.get(key);
+  };
+}
+
+export { createKnowledge };