@reglow/review-mcp 0.1.0

package/server.mjs

@@ -0,0 +1,742 @@
+/**
+ * ReView MCP 服务器：注册工具并桥接 stdio 传输
+ *
+ * 针对 ReView（uni-app x 移动端组件库，uts/uvue + `re-*` easycom 标签 + uni_modules 安装）适配：
+ * - get_review_document       组件文档 / 组件总览
+ * - get_review_code_examples  演示页与文档中的可复制示例
+ * - list_component_files      组件源码文件清单
+ * - get_file_code             读取组件内文件内容（带路径穿越防护）
+ * - get_function_code         提取函数 / 常量 / 类型定义
+ * - search_review_docs        跨文档与源码检索
+ * - get_review_guide          库级指南（安装 / easycom / 主题 / i18n / 平台 / 版本记录 / 约定）
+ *
+ * 工具名、参数名与返回结构与同构的 reui-mcp 一一对应，方便用户在两个库之间迁移。
+ * 注意：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 { CATEGORY_KEYS, DOCS_BASE, componentLabel } from "./catalog.mjs";
+import {
+  GUIDE_TOPICS,
+  GUIDE_TOPIC_KEYS,
+  NPM_NOT_PUBLISHED_HINT,
+  createKnowledge,
+} from "./knowledge.mjs";
+import { fetchSiteDocument } from "./site.mjs";
+
+const PACKAGE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const OWN_PACKAGE = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8"),
+);
+
+/** 文本结果 */
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+/** 错误结果（让 AI 明确失败原因并自行纠正参数） */
+function errorResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+function sourceLabel(source) {
+  return (
+    {
+      workspace: "本地 ReView 仓库（--root / 仓库内运行）",
+      local: "项目内已安装 uni_modules/reglow-review（仅源码）",
+      version: "指定 npm 版本（本库未发布，不可用）",
+      site: "官方文档站点兜底（最新版）",
+      none: "无可用知识源",
+    }[source] ?? source
+  );
+}
+
+/** 响应头：知识来源与版本，避免 AI 误判文档对应的版本 */
+function metaHeader(knowledge, extraLines = []) {
+  const meta = knowledge.meta();
+  const lines = [
+    `> 知识源：${sourceLabel(meta.source)}｜组件库版本：\`${meta.version}\`` +
+    `${meta.versionDate ? `（${meta.versionDate}）` : ""}｜版本来源：\`${meta.versionSource ?? "未知"}\`` +
+    `${meta.root ? `｜路径：\`${meta.root}\`` : ""}`,
+  ];
+  if (meta.requestedVersion) {
+    lines.push(
+      `> ⚠️ 收到 version=\`${meta.requestedVersion}\`，但${NPM_NOT_PUBLISHED_HINT}`,
+    );
+  }
+  if (meta.warning) lines.push(`> ⚠️ ${meta.warning}`);
+  lines.push(...extraLines);
+  return lines.join("\n");
+}
+
+/** 从组件条目推导引入方式（easycom 标签 + 手动 import） */
+function importInfo(entry) {
+  if (!entry) return null;
+  const tags = entry.tags?.length ? entry.tags : entry.tag ? [entry.tag] : [];
+  const lines = [];
+  if (tags.length > 0) {
+    lines.push(
+      `easycom 自动引入（推荐）：模板里直接用 ${tags.map((tag) => `\`<${tag} />\``).join(" / ")}`,
+    );
+  }
+  if (entry.dir) {
+    const name = entry.dir.split("/").pop();
+    lines.push(
+      `手动引入：\`import ${name
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("")} from '@/${entry.dir}/${name}'\``,
+    );
+  }
+  return lines.length > 0 ? lines : null;
+}
+
+/** 组件概览（按 VitePress 侧边栏分类组织） */
+function renderOverview(knowledge, category) {
+  const catalog = knowledge.catalog;
+  const groups = catalog.categories.filter(
+    (group) => !category || group.key === category,
+  );
+  const blocks = [];
+  for (const group of groups) {
+    const rows = group.components
+      .map((entry) => {
+        const tag = entry.tag ? `\`<${entry.tag}>\`` : "—";
+        const demo = entry.demoPath ? "✅" : "—";
+        return `| \`${entry.name}\` ${entry.cn} | ${entry.description || "—"} | ${tag} | ${demo} | [文档](${entry.docsUrl}) |`;
+      })
+      .filter(Boolean);
+    if (rows.length === 0) continue;
+    blocks.push(
+      `## ${group.label}（${group.key}）\n\n| 组件 | 说明 | easycom 标签 | 演示页 | 官网 |\n| --- | --- | --- | --- | --- |\n${rows.join("\n")}`,
+    );
+  }
+
+  // 侧边栏未收录但仓库内存在的组件（内部子组件 / 新增未登记）
+  const listed = new Set(
+    catalog.categories.flatMap((group) =>
+      group.components.map((item) => item.name),
+    ),
+  );
+  const extra = catalog.components.filter((entry) => !listed.has(entry.name));
+  if (extra.length > 0 && !category) {
+    blocks.push(
+      `## 其他（侧边栏未收录，多为内部子组件）\n\n| 组件 | 说明 | easycom 标签 | 源码目录 |\n| --- | --- | --- | --- |\n${extra
+        .map(
+          (entry) =>
+            `| \`${entry.name}\` | ${entry.description || "—"} | ${entry.tag ? `\`<${entry.tag}>\`` : "—"} | \`${entry.dir ?? "（无独立目录）"}\` |`,
+        )
+        .join("\n")}`,
+    );
+  }
+  return blocks.join("\n\n");
+}
+
+/**
+ * 创建 MCP 服务器
+ *
+ * @param {{ resolveKnowledge: (version?: string) => Promise<object>, defaultKnowledge: object }} options
+ */
+export function createServer({ resolveKnowledge, defaultKnowledge }) {
+  const server = new McpServer({
+    name: "review-mcp",
+    version: OWN_PACKAGE.version,
+  });
+
+  const withKnowledge = async (version) => resolveKnowledge(version);
+
+  // ============================ 1. 组件文档 ============================
+  server.registerTool(
+    "get_review_document",
+    {
+      title: "获取 ReView 组件文档",
+      description:
+        "获取 ReView（uni-app x / uts / uvue 移动端组件库）的组件文档。不传 component 时返回按分类组织的组件总览" +
+        "（组件名/说明/easycom 标签/演示页可用性/官网链接）；传 component 时返回该组件的完整文档" +
+        "（引入方式、Props/Events/Slots 表格）。组件通过 uni_modules 安装，模板里用 `re-*` 标签（如 `<re-button />`）。" +
+        "仓库内缺少该组件文档时会自动回退官方文档站点并在回复中标注来源。",
+      inputSchema: {
+        component: z
+          .string()
+          .optional()
+          .describe(
+            "组件名，kebab-case 且不带 re- 前缀，如 button、search-history、date-time-picker（也可写易用标签 re-button）；不传则返回组件总览",
+          ),
+        category: z
+          .enum(CATEGORY_KEYS)
+          .optional()
+          .describe(
+            "分类过滤（仅总览生效）：base / navigation / input / display / feedback / list-layout / marketing / business / module",
+          ),
+        version: z
+          .string()
+          .optional()
+          .describe(
+            "指定 @reglow/review 版本；本库未发布到 npm，传值只会得到提示（知识源仍是本地仓库）",
+          ),
+        source: z
+          .enum(["auto", "workspace", "site"])
+          .optional()
+          .describe(
+            "auto（默认）：本地仓库优先、缺失时回退官网；workspace：仅本地；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 <review 仓库路径>\` 启动（在 review 仓库内运行可自动识别），或用 \`--no-site\` 之外的默认配置联网兜底。`,
+            );
+          }
+          return textResult(
+            `${metaHeader(knowledge, ["", `> 官网总览：${DOCS_BASE}`])}\n\n# ReView 组件总览\n\n${overview}`,
+          );
+        }
+
+        const entry = knowledge.getComponent(component);
+        if (source === "site" || (meta.source === "site" && !entry)) {
+          const siteDoc = await fetchSiteDocument(
+            entry?.name ?? String(component),
+            { category: entry?.category ?? null },
+          );
+          if (siteDoc) {
+            return textResult(
+              `> 知识源：官方文档站点（最新版）｜链接：${siteDoc.url}\n\n# ${componentLabel(entry) || component}\n\n${siteDoc.markdown}`,
+            );
+          }
+          return errorResult(
+            `官方文档站点暂无「${component}」页面（可能是新组件或名称不符）。\n可用组件见 \`get_review_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 且不带 re- 前缀（\`re-button\` → \`button\`）；` +
+            `\`IndexesAnchor\` → \`indexes-anchor\`，\`QRCode\` → \`qrcode\`。`,
+          );
+        }
+
+        const lines = [`# ${componentLabel(entry) || component}`];
+        const facts = [];
+        if (entry) {
+          facts.push(
+            `> 分类：${entry.categoryLabel}（${entry.category}）｜源码目录：\`${entry.dir ?? "（该文档页对应多个组件，无独立目录）"}\``,
+          );
+          const imports = importInfo(entry);
+          if (imports)
+            facts.push("> 使用方式：", ...imports.map((line) => `> - ${line}`));
+          const mainFiles = entry.files.filter((file) =>
+            file.endsWith(".uvue"),
+          );
+          if (mainFiles.length > 0) {
+            facts.push(
+              `> 源码文件：${mainFiles.map((file) => `\`${file}\``).join("、")}`,
+            );
+          }
+          if (entry.demoPath) {
+            facts.push(
+              `> 演示页：\`${entry.demoPath}\`（示例代码用 \`get_review_code_examples\` 取）`,
+            );
+          }
+        }
+        if (doc.url) facts.push(`> 官方文档：${doc.url}`);
+        if (doc.kind === "site") {
+          facts.push(
+            "> ⚠️ 本地仓库未包含该组件文档，以下正文来自官方文档站点（最新版），可能与当前版本存在差异。",
+          );
+        }
+        if (doc.kind === "readme") {
+          facts.push(
+            "> ℹ️ 正文来自组件目录内的 `readme.md`（脚本生成物，内容可能落后于源码）。",
+          );
+        }
+        if (doc.kind === "source") {
+          facts.push(
+            "> ⚠️ 本地既无组件文档也无官网可访问，以下内容由组件 `.uvue` 源码摘要而成（仅前若干行，无 API 表格）。",
+          );
+        }
+        lines.push(
+          "",
+          metaHeader(knowledge, facts),
+          "",
+          "---",
+          "",
+          doc.markdown || "（无文档内容）",
+        );
+        return textResult(lines.join("\n"));
+      } catch (error) {
+        return errorResult(`获取文档失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 2. 代码示例 ============================
+  server.registerTool(
+    "get_review_code_examples",
+    {
+      title: "获取 ReView 组件代码示例",
+      description:
+        "从官方演示页（`pages/<category>/<name>/<name>.uvue`）中提取可直接复制的 uvue 示例，按 `<!-- 小节标题 -->` 切分并保留小节标题；" +
+        "本地缺失时回退官网文档站。用于快速拿到「官方推荐写法」，避免臆造 props / 事件。可用 index 取第 N 个示例，lang 过滤语言。",
+      inputSchema: {
+        component: z
+          .string()
+          .describe("组件名，kebab-case（如 button、infinite-loading）"),
+        index: z
+          .number()
+          .int()
+          .min(0)
+          .optional()
+          .describe("示例下标（从 0 开始）；不传则返回全部"),
+        lang: z
+          .enum([
+            "all",
+            "uvue",
+            "uts",
+            "vue",
+            "ts",
+            "js",
+            "json",
+            "bash",
+            "text",
+          ])
+          .optional()
+          .describe("按语言过滤，默认 all"),
+        version: z
+          .string()
+          .optional()
+          .describe("指定 @reglow/review 版本（未发布 npm，仅提示）"),
+      },
+      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_review_document\` 确认组件是否存在，或改用 \`get_review_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 === "demo"
+            ? `官方演示页（\`${result.path}\`，与仓库版本一致）`
+            : result.source === "doc"
+              ? `组件文档（\`${result.path}\`）`
+              : result.source === "site"
+                ? "官方文档站点（最新版，示例可能高于当前版本）"
+                : "未知来源";
+        return textResult(
+          `# ${componentLabel(knowledge.getComponent(component)) || 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: "列出 ReView 组件源码文件",
+      description:
+        "列出组件目录（`uni_modules/reglow-review/components/re-*/`）下的源码文件清单（相对路径 / 行数 / 字节数），用于了解组件结构，" +
+        "再配合 get_file_code 查看具体实现。典型文件：`re-xxx.uvue`（组件实现）、`readme.md`（脚本生成的文档，中文可能有编码问题）、" +
+        "`*.uts`（类型 / 工具）、`static/*`（静态资源）。子组件目录（如 re-chat-sender）也可直接用组件名查询。",
+      inputSchema: {
+        component: z.string().describe("组件名，kebab-case"),
+        version: z
+          .string()
+          .optional()
+          .describe("指定 @reglow/review 版本（未发布 npm，仅提示）"),
+      },
+      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_review_document（不传 component）。`,
+          );
+        const files = knowledge.listFiles(component) ?? [];
+        const rows = files
+          .map(
+            (file) =>
+              `| \`${file.path}\` | ${file.lines || "—"} | ${file.size} |`,
+          )
+          .join("\n");
+        const imports = importInfo(entry);
+        return textResult(
+          `# ${componentLabel(entry)} 源码文件\n\n` +
+          metaHeader(knowledge, [
+            `> 分类：${entry.categoryLabel}｜目录：\`${entry.dir ?? "（无独立源码目录）"}\`｜文件数：${files.length}`,
+            ...(imports ? imports.map((line) => `> - ${line}`) : []),
+          ]) +
+          (rows
+            ? `\n\n| 文件 | 行数 | 字节 |\n| --- | --- | --- |\n${rows}`
+            : "\n\n（该组件在仓库内没有独立源码目录）") +
+          `\n\n> 下一步：\`get_file_code\` 读取具体文件，\`get_function_code\` 直接取某个函数实现。`,
+        );
+      } catch (error) {
+        return errorResult(`列出文件失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 4. 文件内容 ============================
+  server.registerTool(
+    "get_file_code",
+    {
+      title: "读取 ReView 组件文件内容",
+      description:
+        "读取组件目录内某个文件的代码（支持 startLine/endLine 只取片段）。用于查看组件实现细节、`type Props` / `withDefaults(defineProps<Props>())`、" +
+        "`defineEmits` 与默认值 —— ReView 的部分文档页 Props 表格为空，此时必须以源码为准。文件路径来自 list_component_files，禁止越出组件目录。",
+      inputSchema: {
+        component: z.string().describe("组件名，kebab-case"),
+        file: z
+          .string()
+          .describe(
+            "组件目录内的相对路径，如 re-button.uvue、type.uts、readme.md",
+          ),
+        version: z
+          .string()
+          .optional()
+          .describe("指定 @reglow/review 版本（未发布 npm，仅提示）"),
+        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 === "uvue"
+            ? "vue"
+            : ext === "uts"
+              ? "ts"
+              : ext === "d.ts"
+                ? "ts"
+                : ext;
+        return textResult(
+          `# \`${result.path}\`\n\n` +
+          metaHeader(knowledge, [
+            `> 组件：${componentLabel(knowledge.getComponent(component)) || component}｜总行数：${result.totalLines}${startLine || endLine
+              ? `｜当前片段：${result.startLine}-${result.endLine}`
+              : ""
+            }`,
+            ...(result.garbled
+              ? [
+                "> ⚠️ 该文件是脚本生成的二次编码文本（中文为乱码），请只参考其中的代码片段。",
+              ]
+              : []),
+          ]) +
+          `\n\n\`\`\`${lang}\n${result.text}\n\`\`\``,
+        );
+      } catch (error) {
+        return errorResult(`读取文件失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 5. 函数实现 ============================
+  server.registerTool(
+    "get_function_code",
+    {
+      title: "获取 ReView 组件函数实现",
+      description:
+        "提取组件源码中某个函数 / 常量 / 类 / 接口 / 类型（`type Props` 等）的完整实现（含起止行号），用于深入理解组件逻辑。" +
+        "未命中时会返回该组件可用符号清单，便于纠正名称后重试。",
+      inputSchema: {
+        component: z.string().describe("组件名，kebab-case"),
+        name: z
+          .string()
+          .describe("符号名，如 onTouchStart、buildStateByValues、Props"),
+        file: z
+          .string()
+          .optional()
+          .describe(
+            "限定文件（如 re-cascader.uvue）；不传则在组件内所有 .uvue/.uts 中查找",
+          ),
+        version: z
+          .string()
+          .optional()
+          .describe("指定 @reglow/review 版本（未发布 npm，仅提示）"),
+      },
+      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 ?? "?"} 个，展示前 200 个）：${symbols}`
+              : "") +
+            `\n\n提示：也可用 \`search_review_docs\` 以关键词定位，再用 \`get_file_code\` 读取上下文。`,
+          );
+        }
+        return textResult(
+          `# \`${result.name}\`（${result.kind}）\n\n` +
+          metaHeader(knowledge, [
+            `> 组件：${componentLabel(knowledge.getComponent(component)) || component}｜文件：\`${result.path}\`｜行号：${result.startLine}-${result.endLine}`,
+          ]) +
+          `\n\n\`\`\`ts\n${result.text}\n\`\`\``,
+        );
+      } catch (error) {
+        return errorResult(`提取函数失败：${error.message}`);
+      }
+    },
+  );
+
+  // ============================ 6. 文档检索 ============================
+  server.registerTool(
+    "search_review_docs",
+    {
+      title: "检索 ReView 文档与源码",
+      description:
+        "在组件文档、演示页、组件源码与库级文档（README / CHANGELOG / docs/guide）中做关键词检索（多关键词空格分隔，按「全部命中」过滤），" +
+        "返回「组件 / 文件:行号 + 上下文片段 + 文档链接」。适合不确定用哪个组件、或想找某个 prop / 事件 / CSS 变量在何处实现时使用。",
+      inputSchema: {
+        query: z
+          .string()
+          .optional()
+          .describe("关键词，支持多词（空格分隔，如「级联 lazy」）"),
+        keywords: z
+          .array(z.string())
+          .optional()
+          .describe("关键词数组写法（等价于 query，多个关键词为「全部命中」）"),
+        component: z.string().optional().describe("限定单个组件"),
+        category: z.enum(CATEGORY_KEYS).optional().describe("限定分类"),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(60)
+          .optional()
+          .describe("最多返回条数，默认 20"),
+        version: z
+          .string()
+          .optional()
+          .describe("指定 @reglow/review 版本（未发布 npm，仅提示）"),
+      },
+      annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ query, keywords, component, category, limit, version }) => {
+      try {
+        const knowledge = await withKnowledge(version);
+        const text = keywords?.length ? keywords.join(" ") : (query ?? "");
+        const { hits, scanned, terms } = knowledge.search(text, {
+          component,
+          category,
+          limit,
+        });
+        if (hits.length === 0) {
+          return textResult(
+            `未检索到与「${text}」匹配的内容（已扫描 ${scanned} 个文件）。\n\n` +
+            `${metaHeader(knowledge)}\n\n` +
+            `建议：减少关键词数量、换用英文标识（如 \`customStyle\`、\`themeVars\`）、或先用 \`get_review_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(knowledge.getComponent(name)) || name}${link}\n\n${body}`;
+        });
+        return textResult(
+          `# 检索「${text}」\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_review_guide",
+    {
+      title: "获取 ReView 使用指南",
+      description:
+        "获取库级指南：安装与引入（uni_modules / 插件市场 / easycom）、easycom 细节、主题与样式定制（`--re-*` CSS 变量）、" +
+        "国际化（zh-CN / zh-TW / en-US）、平台差异与运行方式（HBuilderX、App/H5/小程序）、版本记录与工程约定。" +
+        "在动手前用它对齐「正确引入方式 / 主题变量 / 语言包 / 平台限制」，避免踩坑。",
+      inputSchema: {
+        topic: z
+          .enum(GUIDE_TOPIC_KEYS)
+          .optional()
+          .describe(
+            GUIDE_TOPICS.map((item) => `${item.key}（${item.label}）`).join(
+              " | ",
+            ),
+          ),
+        version: z
+          .string()
+          .optional()
+          .describe("指定 @reglow/review 版本（未发布 npm，仅提示）"),
+      },
+      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) {
+          return textResult(
+            `${metaHeader(knowledge)}\n\n` +
+            `未取到本地指南章节（topic=${topic ?? "overview"}）。\n` +
+            `可用方式：用 \`--root <review 仓库路径>\` 启动以读取 \`README.md\` / \`docs/guide/*.md\`；或直接改用 \`get_review_document\`。`,
+          );
+        }
+        const blocks = guide.sections.map(
+          (section) =>
+            `<!-- 来源：${section.file}${section.title ? ` · ${section.title}` : ""} -->\n\n${section.text}`,
+        );
+        return textResult(
+          `# ReView 指南（${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 缓存（同一进程内复用）
+ *
+ * version 在本库不生效（未发布 npm），但保留参数以与 reui-mcp 的工具签名一致。
+ *
+ * @param {{ root?: string, allowSite?: boolean, logger?: (message: string) => void }} options
+ */
+export function createKnowledgeResolver(options = {}) {
+  const cache = new Map();
+  return async function resolveKnowledge(version) {
+    const key = version ? `version:${version}` : "default";
+    if (!cache.has(key)) {
+      cache.set(
+        key,
+        await createKnowledge({
+          root: options.root,
+          version,
+          allowSite: options.allowSite,
+          logger: options.logger ?? (() => { }),
+        }),
+      );
+    }
+    return cache.get(key);
+  };
+}
+
+export { createKnowledge };