@reglow/reui-mcp 0.1.0

package/knowledge.mjs

@@ -0,0 +1,923 @@
+/**
+ * 知识源（Knowledge）：为 MCP 工具提供组件文档、示例、源码、函数实现与检索能力
+ *
+ * 支持三种数据来源，按优先级自动选择：
+ * 1. `local`     —— `--root` 指定的工作区，或从当前项目解析到的已安装 `@reglow/reui`（与项目版本一致）
+ * 2. `version`   —— `version` 参数指定的 npm 版本（下载 tarball 到缓存目录后离线读取）
+ * 3. `site`      —— 官方文档站点兜底（包内缺文档时，抓取 https://reglow.huoli.tech/components-library/reui）
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { extractTarball } from "./tar.mjs";
+import { fetchSiteDocument, fetchSiteOverview } from "./site.mjs";
+import { CATEGORIES, catalogItem, docsUrlFor } from "./catalog.mjs";
+
+const require = createRequire(import.meta.url);
+const PACKAGE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const OWN_PACKAGE = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf8"),
+);
+
+const REUI_PACKAGE = "@reglow/reui";
+const REGISTRY = "https://registry.npmjs.org";
+/** 可参与检索 / 读取的文本文件扩展名 */
+const TEXT_EXTENSIONS = [
+  ".md",
+  ".ts",
+  ".vue",
+  ".js",
+  ".mjs",
+  ".json",
+  ".css",
+  ".txt",
+];
+/** 检索时单文件最大读取体积 */
+const MAX_SEARCH_FILE_BYTES = 512 * 1024;
+/** 单次读取文件的最大字节数 */
+const MAX_READ_BYTES = 1024 * 1024;
+
+const LAYER_DIRS = [
+  { layer: "reui", dir: "components/reui" },
+  { layer: "ui", dir: "components/ui" },
+  // 历史发布版本可能未把 components 打进产物，此时退化为 dist 目录（仅编译产物与 .d.ts）
+  { layer: "reui", dir: "dist/components/reui" },
+  { layer: "ui", dir: "dist/components/ui" },
+];
+
+// ============================ 通用工具函数 ============================
+
+function toPosix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function isTextFile(file) {
+  return TEXT_EXTENSIONS.some((ext) => file.endsWith(ext));
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** 递归读取目录下所有文件（相对路径，posix 分隔符），跳过测试与隐藏目录 */
+function walkFiles(dir, { skipTests = true, base = dir } = {}) {
+  const result = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (
+      skipTests &&
+      (entry.name === "__tests__" || entry.name.endsWith(".test.ts"))
+    )
+      continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory())
+      result.push(...walkFiles(full, { skipTests, base }));
+    else if (entry.isFile()) result.push(toPosix(path.relative(base, full)));
+  }
+  return result.sort();
+}
+
+function lineCount(text) {
+  return text === "" ? 1 : text.split("\n").length;
+}
+
+/** 是否为 ReUI 知识点根目录 */
+export function isReuiRoot(dir) {
+  if (!dir) return false;
+  const stat = fs.existsSync(dir) && fs.statSync(dir);
+  if (!stat || !stat.isDirectory()) return false;
+  const pkg = readJsonSafe(path.join(dir, "package.json"));
+  if (pkg?.name === REUI_PACKAGE) return true;
+  // 仓库源码形态（reui 本体）
+  return (
+    fs.existsSync(path.join(dir, "components/reui/index.ts")) &&
+    fs.existsSync(path.join(dir, "index.ts"))
+  );
+}
+
+/** 解析本地知识点根目录 */
+export function resolveLocalRoot(explicitRoot) {
+  const candidates = [];
+  if (explicitRoot) candidates.push(path.resolve(explicitRoot));
+  if (process.env.REUI_ROOT)
+    candidates.push(path.resolve(process.env.REUI_ROOT));
+  // 仓库内运行：reui/mcp → reui
+  candidates.push(path.resolve(PACKAGE_DIR, ".."));
+  // 当前项目已安装的 @reglow/reui
+  try {
+    candidates.push(
+      path.dirname(
+        require.resolve(`${REUI_PACKAGE}/package.json`, {
+          paths: [process.cwd()],
+        }),
+      ),
+    );
+  } catch {
+    /* 未安装则跳过 */
+  }
+  candidates.push(path.join(process.cwd(), "node_modules", REUI_PACKAGE));
+  return candidates.find(isReuiRoot) ?? null;
+}
+
+// ============================ 符号（函数）提取 ============================
+
+/**
+ * 从起始大括号处匹配到配对的结束大括号
+ *
+ * 会跳过字符串（'、"、`）、行注释与块注释，避免括号出现在字面量里导致错配。
+ */
+export function matchBlock(text, openIndex) {
+  if (text[openIndex] !== "{") return openIndex;
+  let depth = 0;
+  for (let i = openIndex; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === "/" && text[i + 1] === "/") {
+      const end = text.indexOf("\n", i);
+      i = end === -1 ? text.length : end;
+      continue;
+    }
+    if (char === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end === -1 ? text.length : end + 1;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      for (let j = i + 1; j < text.length; j += 1) {
+        if (text[j] === "\\") {
+          j += 1;
+          continue;
+        }
+        if (text[j] === char) {
+          i = j;
+          break;
+        }
+        if (text[j] === "\n" && char !== "`") {
+          i = j - 1;
+          break;
+        }
+      }
+      continue;
+    }
+    if (char === "{") depth += 1;
+    else if (char === "}") {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return text.length - 1;
+}
+
+/** 匹配 `(...)` 的结束位置 */
+function matchParen(text, openIndex) {
+  let depth = 0;
+  for (let i = openIndex; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '"' || char === "'" || char === "`") {
+      for (let j = i + 1; j < text.length; j += 1) {
+        if (text[j] === "\\") {
+          j += 1;
+          continue;
+        }
+        if (text[j] === char) {
+          i = j;
+          break;
+        }
+      }
+      continue;
+    }
+    if (char === "(") depth += 1;
+    else if (char === ")") {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+  return text.length - 1;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function lineOf(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+
+/**
+ * 提取指定符号的完整定义（函数 / 常量 / 类 / 接口 / 类型）
+ *
+ * @param {string} text 源码
+ * @param {string} name 符号名
+ * @returns {{ name: string, kind: string, text: string, startLine: number, endLine: number } | null}
+ */
+export function extractSymbol(text, name) {
+  const safe = escapeRegExp(name);
+  const patterns = [
+    {
+      kind: "function",
+      re: new RegExp(
+        `^[\\t ]*(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?function\\s+(${safe})\\s*\\(`,
+        "m",
+      ),
+    },
+    {
+      kind: "const",
+      re: new RegExp(
+        `^[\\t ]*(?:export\\s+)?(?:const|let|var)\\s+(${safe})\\s*=`,
+        "m",
+      ),
+    },
+    {
+      kind: "class",
+      re: new RegExp(
+        `^[\\t ]*(?:export\\s+)?(?:default\\s+)?class\\s+(${safe})\\b`,
+        "m",
+      ),
+    },
+    {
+      kind: "interface",
+      re: new RegExp(
+        `^[\\t ]*(?:export\\s+)?(?:interface|type|enum)\\s+(${safe})\\b`,
+        "m",
+      ),
+    },
+    {
+      kind: "property",
+      re: new RegExp(`^[\\t ]*(${safe})\\s*[:=]\\s*(?:function|\\()`, "m"),
+    },
+  ];
+
+  for (const { kind, re } of patterns) {
+    const match = re.exec(text);
+    if (!match) continue;
+    const start = match.index;
+    let end;
+    if (kind === "function") {
+      const paren = text.indexOf("(", start);
+      const parenEnd = matchParen(text, paren);
+      const brace = text.indexOf("{", parenEnd);
+      // 无函数体（类型声明 / 重载签名）时截到行尾
+      end =
+        brace === -1 ? text.indexOf("\n", parenEnd) : matchBlock(text, brace);
+      if (end === -1) end = text.length - 1;
+    } else if (kind === "interface") {
+      const brace = text.indexOf("{", start);
+      const semi = text.indexOf(";", start);
+      if (brace !== -1 && (semi === -1 || brace < semi))
+        end = matchBlock(text, brace);
+      else end = semi === -1 ? text.indexOf("\n", start) : semi;
+      if (end === -1) end = text.length - 1;
+    } else if (kind === "class") {
+      const brace = text.indexOf("{", start);
+      end = brace === -1 ? text.length - 1 : matchBlock(text, brace);
+    } else {
+      // const / var / property：优先函数体，其次箭头函数体，最后到分号或行尾
+      const eq = text.indexOf("=", start);
+      const brace = text.indexOf("{", eq === -1 ? start : eq);
+      const semi = text.indexOf(";", eq === -1 ? start : eq);
+      const newline = text.indexOf("\n", eq === -1 ? start : eq);
+      if (brace !== -1 && brace !== -1 && (semi === -1 || brace < semi)) {
+        end = matchBlock(text, brace);
+      } else if (
+        eq !== -1 &&
+        text.slice(eq, eq + 12).includes("=>") &&
+        brace !== -1
+      ) {
+        end = matchBlock(text, brace);
+      } else if (
+        semi !== -1 &&
+        semi < (newline === -1 ? text.length : newline)
+      ) {
+        end = semi;
+      } else {
+        end = newline === -1 ? text.length - 1 : newline - 1;
+      }
+    }
+    const slice = text.slice(start, end + 1);
+    return {
+      name,
+      kind,
+      text: slice.replace(/\s+$/, ""),
+      startLine: lineOf(text, start),
+      endLine: lineOf(text, start + slice.length),
+    };
+  }
+  return null;
+}
+
+/** 列出源码中可提取的符号名（用于未命中时给出候选） */
+export function listSymbols(text) {
+  const names = new Set();
+  const patterns = [
+    /^[\t ]*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm,
+    /^[\t ]*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/gm,
+    /^[\t ]*(?:export\s+)?(?:default\s+)?class\s+([A-Za-z_$][\w$]*)/gm,
+    /^[\t ]*(?:export\s+)?(?:interface|type|enum)\s+([A-Za-z_$][\w$]*)/gm,
+  ];
+  for (const re of patterns) {
+    for (const match of text.matchAll(re)) names.add(match[1]);
+  }
+  return [...names];
+}
+
+// ============================ 版本化知识（npm tarball） ============================
+
+function cacheRoot() {
+  return process.env.REUI_MCP_CACHE || path.join(os.tmpdir(), "reui-mcp-cache");
+}
+
+async function fetchJson(url, timeout = 20000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchBuffer(url, timeout = 60000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) return null;
+    return Buffer.from(await response.arrayBuffer());
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 解析版本号：支持 `latest`、dist-tag、精确版本、`^x.y.z`（取同主版本最高） */
+async function resolveVersion(version) {
+  const wanted = String(version).trim();
+  if (/^\d+\.\d+\.\d+/.test(wanted)) return wanted;
+  const meta = await fetchJson(
+    `${REGISTRY}/${encodeURIComponent(REUI_PACKAGE)}`,
+  );
+  if (!meta) return null;
+  if (wanted === "latest" || wanted === "")
+    return meta["dist-tags"]?.latest ?? null;
+  if (meta["dist-tags"]?.[wanted]) return meta["dist-tags"][wanted];
+  const caret = wanted.match(/^[\^~](\d+)\.(\d+)\.(\d+)/);
+  if (caret) {
+    const major = Number(caret[1]);
+    const versions = Object.keys(meta.versions ?? {})
+      .filter((item) => item.startsWith(`${major}.`))
+      .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+    return versions.at(-1) ?? null;
+  }
+  return null;
+}
+
+/** 下载并解包指定版本到缓存目录，返回解包后的 package 根目录 */
+async function ensureVersionCache(version) {
+  const resolved = await resolveVersion(version);
+  if (!resolved) {
+    const error = new Error(
+      `无法解析 @reglow/reui 版本「${version}」（可能无网络或版本不存在）`,
+    );
+    error.code = "VERSION_UNRESOLVED";
+    throw error;
+  }
+  const dir = path.join(cacheRoot(), resolved);
+  const marker = path.join(dir, ".ready");
+  if (fs.existsSync(marker)) return { dir, version: resolved };
+
+  const meta = await fetchJson(
+    `${REGISTRY}/${encodeURIComponent(REUI_PACKAGE)}/${resolved}`,
+  );
+  const tarball = meta?.dist?.tarball;
+  if (!tarball) {
+    const error = new Error(`未找到 @reglow/reui@${resolved} 的 tarball 地址`);
+    error.code = "VERSION_UNRESOLVED";
+    throw error;
+  }
+  const buffer = await fetchBuffer(tarball);
+  if (!buffer) {
+    const error = new Error(`下载 @reglow/reui@${resolved} 失败（网络不可用）`);
+    error.code = "VERSION_UNRESOLVED";
+    throw error;
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+  extractTarball(buffer, (entry) => {
+    const relative = entry.path.replace(/^package\//, "");
+    if (!relative || relative.startsWith("..")) return;
+    const target = path.join(dir, relative);
+    if (!target.startsWith(dir)) return;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, entry.data);
+  });
+  fs.writeFileSync(
+    marker,
+    JSON.stringify({ version: resolved, tarball }, null, 2),
+  );
+  return { dir, version: resolved };
+}
+
+// ============================ 知识对象 ============================
+
+/**
+ * 创建知识对象
+ *
+ * @param {{ root?: string, version?: string, allowSite?: boolean, logger?: (msg: string) => void }} options
+ */
+export async function createKnowledge(options = {}) {
+  const logger = options.logger ?? (() => { });
+  const allowSite = options.allowSite !== false;
+  let root = null;
+  let version = OWN_PACKAGE.version;
+  let source = "local";
+  let warning = null;
+
+  if (options.version) {
+    const cached = await ensureVersionCache(options.version);
+    root = cached.dir;
+    version = cached.version;
+    source = "version";
+  } else {
+    root = resolveLocalRoot(options.root);
+    if (root) {
+      const pkg = readJsonSafe(path.join(root, "package.json"));
+      version = pkg?.version ?? version;
+      source = root === path.resolve(PACKAGE_DIR, "..") ? "workspace" : "local";
+    } else if (allowSite) {
+      warning =
+        "未找到本地 @reglow/reui（既未安装也未指定 --root），文档将回退到官方文档站点（最新版）";
+      source = "site";
+    } else {
+      warning = "未找到本地 @reglow/reui，且已禁用官网回退";
+      source = "none";
+    }
+  }
+
+  /** 构建组件索引（懒执行一次） */
+  let indexCache = null;
+  function buildIndex() {
+    if (indexCache) return indexCache;
+    const entries = new Map();
+    if (!root) return (indexCache = entries);
+
+    for (const { layer, dir } of LAYER_DIRS) {
+      const abs = path.join(root, dir);
+      if (!fs.existsSync(abs)) continue;
+      for (const name of fs.readdirSync(abs)) {
+        // 同名组件 reui 优先（与组件库导出策略一致：ui 层的同名包仅做转发）
+        if (entries.has(name)) continue;
+        const componentDir = path.join(abs, name);
+        if (!fs.statSync(componentDir).isDirectory()) continue;
+        const files = walkFiles(componentDir);
+        const hasApi = files.some((file) => /index\.(ts|js|d\.ts)$/.test(file));
+        if (!hasApi && files.length === 0) continue;
+        const docFile = files.find((file) => file === "README.md") ?? null;
+        const catalog = catalogItem(name);
+        entries.set(name, {
+          name,
+          layer,
+          dir: toPosix(path.relative(root, componentDir)),
+          files,
+          docPath: docFile
+            ? `${toPosix(path.relative(root, componentDir))}/${docFile}`
+            : null,
+          description: catalog?.desc ?? "",
+          cn: catalog?.cn ?? "",
+          category: catalog?.category ?? layer,
+          categoryLabel:
+            catalog?.categoryLabel ??
+            (layer === "ui" ? "基础组件(ui)" : "高级组件(reui)"),
+          docsUrl: docsUrlFor(name),
+        });
+      }
+    }
+    indexCache = entries;
+    return entries;
+  }
+
+  function componentEntry(name) {
+    const key = String(name ?? "")
+      .trim()
+      .toLowerCase();
+    const index = buildIndex();
+    if (index.has(key)) return index.get(key);
+    // 兼容驼峰/符号名（如 PageTable → table、QRCode → qr-code）
+    const normalized = key
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .replace(/\s+/g, "-")
+      .toLowerCase();
+    return index.get(normalized) ?? null;
+  }
+
+  function readFileByRel(relPath) {
+    if (!root) return null;
+    const target = path.resolve(root, relPath);
+    if (!target.startsWith(path.resolve(root))) return null;
+    try {
+      const stat = fs.statSync(target);
+      if (!stat.isFile() || stat.size > MAX_READ_BYTES) return null;
+      return fs.readFileSync(target, "utf8");
+    } catch {
+      return null;
+    }
+  }
+
+  /** 汇总组件的类型声明（版本包内只有 dist 时作为 API 文档） */
+  function typeDocs(entry) {
+    const declFiles = entry.files.filter((file) => file.endsWith(".d.ts"));
+    const chunks = declFiles
+      .map((file) => {
+        const text = readFileByRel(`${entry.dir}/${file}`);
+        if (!text) return null;
+        return `### ${file}\n\n\`\`\`ts\n${text.trim()}\n\`\`\``;
+      })
+      .filter(Boolean);
+    return chunks.join("\n\n");
+  }
+
+  /** 从 Markdown 中提取带标题上下文的代码块 */
+  function parseCodeExamples(markdown) {
+    const examples = [];
+    const lines = String(markdown ?? "").split("\n");
+    let heading = "";
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
+      if (headingMatch) heading = headingMatch[2].trim();
+      const fenceMatch = line.match(/^```(\w+)?\s*$/);
+      if (!fenceMatch) continue;
+      const lang = (fenceMatch[1] ?? "text").toLowerCase();
+      const body = [];
+      i += 1;
+      while (i < lines.length && !/^```\s*$/.test(lines[i])) {
+        body.push(lines[i]);
+        i += 1;
+      }
+      const code = body.join("\n").replace(/\s+$/, "");
+      if (code.trim() === "") continue;
+      examples.push({ title: heading || "未命名示例", lang, code, line: i });
+    }
+    return examples;
+  }
+
+  const knowledge = {
+    meta() {
+      return {
+        version,
+        source,
+        root: root ? toPosix(root) : null,
+        warning,
+        docsBase: "https://reglow.huoli.tech/components-library/reui",
+      };
+    },
+
+    /** 组件清单 */
+    listComponents({ category } = {}) {
+      const all = [...buildIndex().values()];
+      const filtered = category
+        ? all.filter(
+          (entry) =>
+            entry.category === category || entry.categoryLabel === category,
+        )
+        : all;
+      return filtered.sort((a, b) => a.name.localeCompare(b.name));
+    },
+
+    /** 组件条目 */
+    getComponent(name) {
+      return componentEntry(name);
+    },
+
+    /**
+     * 组件文档
+     * @returns {Promise<{ markdown: string, kind: "readme"|"types"|"site"|"none", path: string|null, url: string|null }>}
+     */
+    async getDocument(name) {
+      const entry = componentEntry(name);
+      const url = entry?.docsUrl ?? docsUrlFor(name) ?? null;
+      const readme = entry?.docPath ? readFileByRel(entry.docPath) : null;
+      if (readme) {
+        return { markdown: readme, kind: "readme", path: entry.docPath, url };
+      }
+
+      // 包内无 README：先用官网文档兜底，再补充 dist 类型声明
+      const types = entry ? typeDocs(entry) : "";
+      const siteDoc = allowSite
+        ? await fetchSiteDocument(entry?.name ?? String(name))
+        : null;
+      if (siteDoc) {
+        const appendix = types
+          ? `\n\n---\n\n## 附：该版本包内类型声明（\`dist/**/*.d.ts\`）\n\n${types}`
+          : "";
+        return {
+          markdown: siteDoc.markdown + appendix,
+          kind: "site",
+          path: null,
+          url: siteDoc.url,
+        };
+      }
+      if (types) {
+        return {
+          markdown: types,
+          kind: "types",
+          path: `${entry.dir}/index.d.ts`,
+          url,
+        };
+      }
+      return { markdown: "", kind: "none", path: null, url };
+    },
+
+    /** 代码示例（优先本地 README，缺失时走官网兜底） */
+    async getCodeExamples(name, { index, lang } = {}) {
+      const entry = componentEntry(name);
+      const readme = entry?.docPath ? readFileByRel(entry.docPath) : null;
+      if (readme) {
+        let examples = parseCodeExamples(readme);
+        if (lang && lang !== "all")
+          examples = examples.filter((item) => item.lang === lang);
+        return {
+          examples:
+            index === undefined ? examples : examples.slice(index, index + 1),
+          source: "readme",
+          path: entry.docPath,
+          url: entry.docsUrl ?? null,
+        };
+      }
+      if (allowSite) {
+        const siteDoc = await fetchSiteDocument(entry?.name ?? String(name));
+        if (siteDoc) {
+          let examples = parseCodeExamples(siteDoc.markdown);
+          if (lang && lang !== "all")
+            examples = examples.filter((item) => item.lang === lang);
+          return {
+            examples:
+              index === undefined ? examples : examples.slice(index, index + 1),
+            source: "site",
+            path: null,
+            url: siteDoc.url,
+          };
+        }
+      }
+      return {
+        examples: [],
+        source: "none",
+        path: null,
+        url: entry?.docsUrl ?? null,
+      };
+    },
+
+    /** 组件文件清单 */
+    listFiles(name) {
+      const entry = componentEntry(name);
+      if (!entry) return null;
+      return entry.files.map((file) => {
+        const rel = `${entry.dir}/${file}`;
+        const abs = root ? path.join(root, rel) : null;
+        let size = 0;
+        let lines = 0;
+        if (abs) {
+          try {
+            const stat = fs.statSync(abs);
+            size = stat.size;
+            if (isTextFile(file) && size <= MAX_READ_BYTES)
+              lines = lineCount(fs.readFileSync(abs, "utf8"));
+          } catch {
+            /* 忽略 */
+          }
+        }
+        return { path: file, size, lines };
+      });
+    },
+
+    /** 读取组件内文件（带路径穿越防护） */
+    readComponentFile(name, file, { startLine, endLine } = {}) {
+      const entry = componentEntry(name);
+      if (!entry) return { error: `未找到组件「${name}」` };
+      const normalized = toPosix(String(file ?? "")).replace(/^\.\//, "");
+      const target = path.resolve(root ?? "", `${entry.dir}/${normalized}`);
+      if (!root || !target.startsWith(path.resolve(root))) {
+        return { error: "非法文件路径" };
+      }
+      const rel = toPosix(path.relative(root, target));
+      let text;
+      try {
+        const stat = fs.statSync(target);
+        if (!stat.isFile()) return { error: `不是文件：${normalized}` };
+        if (stat.size > MAX_READ_BYTES)
+          return { error: `文件过大（>${MAX_READ_BYTES} 字节）` };
+        text = fs.readFileSync(target, "utf8");
+      } catch {
+        const available = entry.files.slice(0, 40).join("\n- ");
+        return {
+          error: `文件不存在：${normalized}\n\n该组件可用文件：\n- ${available}`,
+        };
+      }
+      const total = lineCount(text);
+      let output = text;
+      let from = 1;
+      let to = total;
+      if (startLine || endLine) {
+        from = Math.max(1, Number(startLine ?? 1));
+        to = Math.min(total, Number(endLine ?? total));
+        output = text
+          .split("\n")
+          .slice(from - 1, to)
+          .map((line, i) => `${from + i}: ${line}`)
+          .join("\n");
+      }
+      return {
+        path: rel,
+        text: output,
+        totalLines: total,
+        startLine: from,
+        endLine: to,
+      };
+    },
+
+    /** 提取函数 / 常量 / 类定义 */
+    findFunction(name, symbol, { file } = {}) {
+      const entry = componentEntry(name);
+      if (!entry) return { error: `未找到组件「${name}」` };
+      const candidates = file
+        ? [toPosix(file)]
+        : entry.files.filter(
+          (item) =>
+            /\.(vue|ts|mjs|js)$/.test(item) && !item.endsWith(".d.ts"),
+        );
+      const searched = [];
+      for (const candidate of candidates) {
+        const text = readFileByRel(`${entry.dir}/${candidate}`);
+        if (!text) continue;
+        searched.push(candidate);
+        const found = extractSymbol(text, symbol);
+        if (found) {
+          return {
+            ...found,
+            path: `${entry.dir}/${candidate}`,
+            component: entry.name,
+          };
+        }
+      }
+      const symbols = new Set();
+      for (const candidate of searched) {
+        const text = readFileByRel(`${entry.dir}/${candidate}`);
+        if (!text) continue;
+        listSymbols(text).forEach((item) => symbols.add(item));
+      }
+      const all = [...symbols].sort((a, b) =>
+        a.localeCompare(b, "en", { sensitivity: "base" }),
+      );
+      const similar = all.filter((item) =>
+        item.toLowerCase().includes(String(symbol).toLowerCase()),
+      );
+      return {
+        error: `未在组件「${entry.name}」中找到符号「${symbol}」`,
+        searched: searched.map((item) => `${entry.dir}/${item}`),
+        availableSymbols: all.slice(0, 300),
+        similarSymbols: similar,
+        allSymbolsCount: all.length,
+      };
+    },
+
+    /** 跨组件文档 / 源码检索 */
+    search(query, { category, limit = 20, component } = {}) {
+      const terms = String(query ?? "")
+        .split(/\s+/)
+        .map((term) => term.trim().toLowerCase())
+        .filter(Boolean);
+      if (terms.length === 0) return { hits: [], scanned: 0, terms };
+
+      const entries = component
+        ? [componentEntry(component)].filter(Boolean)
+        : knowledge.listComponents({ category });
+      const targets = [];
+      for (const entry of entries) {
+        if (entry.docPath) targets.push({ entry, file: entry.docPath });
+        for (const item of entry.files) {
+          if (item === "README.md") continue;
+          if (!isTextFile(item)) continue;
+          targets.push({ entry, file: `${entry.dir}/${item}` });
+        }
+      }
+      // 库级文档
+      for (const extra of [
+        "README.md",
+        "guide.md",
+        "COMPONENT_FUNCTIONALITY.md",
+      ]) {
+        if (root && fs.existsSync(path.join(root, extra))) {
+          targets.push({
+            entry: { name: "reui", category: "library", docsUrl: null },
+            file: extra,
+          });
+        }
+      }
+
+      const hits = [];
+      let scanned = 0;
+      for (const target of targets) {
+        if (hits.length >= limit) break;
+        const abs = path.join(root ?? "", target.file);
+        let text;
+        try {
+          const stat = fs.statSync(abs);
+          if (!stat.isFile() || stat.size > MAX_SEARCH_FILE_BYTES) continue;
+          text = fs.readFileSync(abs, "utf8");
+        } catch {
+          continue;
+        }
+        scanned += 1;
+        const lower = text.toLowerCase();
+        if (!terms.every((term) => lower.includes(term))) continue;
+        const lines = text.split("\n");
+        let found = 0;
+        for (
+          let i = 0;
+          i < lines.length && found < 3 && hits.length < limit;
+          i += 1
+        ) {
+          const lineLower = lines[i].toLowerCase();
+          if (!terms.some((term) => lineLower.includes(term))) continue;
+          const from = Math.max(0, i - 1);
+          const to = Math.min(lines.length, i + 2);
+          hits.push({
+            component: target.entry.name,
+            path: toPosix(target.file),
+            line: i + 1,
+            text: lines.slice(from, to).join("\n"),
+            docsUrl: target.entry.docsUrl ?? null,
+          });
+          found += 1;
+        }
+      }
+      return { hits, scanned, terms };
+    },
+
+    /** 库级指南（安装 / 主题 / i18n / Nuxt / 构建 / 约定 等章节） */
+    getGuide(topic) {
+      if (!root) return null;
+      const sources = ["README.md", "guide.md", "COMPONENT_FUNCTIONALITY.md"]
+        .map((file) => ({ file, text: readFileByRel(file) }))
+        .filter((item) => !!item.text);
+      if (sources.length === 0) return null;
+      if (!topic || topic === "overview") {
+        return { sections: sources, docsBase: knowledge.meta().docsBase };
+      }
+      const keywords = {
+        install: ["安装", "开始", "引入", "install", "usage", "快速"],
+        theme: ["主题", "theme", "dark", "color", "radius"],
+        i18n: ["i18n", "国际化", "locale", "语言"],
+        nuxt: ["nuxt", "模块", "module", "ssr"],
+        build: ["构建", "build", "打包", "发布", "dist"],
+        conventions: ["约定", "规范", "新增组件", "目录结构", "工程"],
+      }[topic] ?? [topic];
+      const sections = [];
+      for (const { file, text } of sources) {
+        const chunks = text.split(/\n(?=#{1,3}\s)/);
+        for (const chunk of chunks) {
+          const title = chunk.match(/^#{1,3}\s+(.*)$/m)?.[1] ?? "";
+          const haystack = `${title}\n${chunk.slice(0, 400)}`.toLowerCase();
+          if (
+            keywords.some((keyword) =>
+              haystack.includes(String(keyword).toLowerCase()),
+            )
+          ) {
+            sections.push({ file, text: chunk.trim() });
+          }
+        }
+      }
+      return { sections, docsBase: knowledge.meta().docsBase };
+    },
+
+    /** 官网组件总览（回退用） */
+    async siteOverview() {
+      if (!allowSite) return null;
+      return fetchSiteOverview();
+    },
+  };
+
+  logger(
+    `[reui-mcp] 知识源：source=${source} version=${version} root=${root ?? "(none)"}` +
+    (warning ? ` warning=${warning}` : ""),
+  );
+  return knowledge;
+}
+
+export { CATEGORIES, PACKAGE_DIR, REUI_PACKAGE };