@reglow/review-mcp 0.1.0

package/knowledge.mjs

@@ -0,0 +1,1130 @@
+/**
+ * 知识源（Knowledge）：为 MCP 工具提供组件文档、示例、源码、函数实现与检索能力
+ *
+ * `@reglow/review` **未发布到 npm**，因此只有两级数据来源：
+ * 1. `workspace` —— `--root` 指定的 ReView 仓库（或从当前项目解析到的 `uni_modules/reglow-review`），
+ *    读取 `docs/components/*.md`、`docs/guide/*.md`、`README.md`、`CHANGELOG.md` 与
+ *    `uni_modules/reglow-review/components/**` 源码；
+ * 2. `site` —— 官方文档站点兜底（https://reglow.huoli.tech/components-library/review）。
+ *
+ * `version` 参数保留（与 reui 版工具签名一致），但因为包未发布，传版本号时只会给出提示、
+ * 不切换知识源；版本号一律从 `CHANGELOG.md` 顶部解析。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  CATEGORIES,
+  CHANGELOG_FILE,
+  COMPONENT_DIR,
+  DOCS_BASE,
+  DOCS_DIR,
+  GUIDE_DIR,
+  README_FILE,
+  SIDEBAR_FILE,
+  changelogUrlFor,
+  createCatalog,
+  guideUrlFor,
+  readTextSafe,
+  toPosix,
+} from "./catalog.mjs";
+import {
+  fetchSiteChangelog,
+  fetchSiteDocument,
+  fetchSiteGuide,
+  fetchSiteOverview,
+} from "./site.mjs";
+
+const PACKAGE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/** 组件库包名（未发布到 npm，仅用于识别仓库 / 安装目录） */
+export const REVIEW_PACKAGE = "@reglow/review";
+/** 未发布 npm 的统一提示文案 */
+export const NPM_NOT_PUBLISHED_HINT =
+  "`@reglow/review` 尚未发布到 npm，因此无法按版本号拉取知识；" +
+  "请用 `--root <review 仓库路径>` 指向本地仓库（或在含 `uni_modules/reglow-review` 的项目内运行），" +
+  "官网文档站点仅作为兜底。";
+
+/** 可参与检索 / 读取的文本文件扩展名 */
+const TEXT_EXTENSIONS = [
+  ".md",
+  ".uvue",
+  ".uts",
+  ".vue",
+  ".ts",
+  ".js",
+  ".mjs",
+  ".json",
+  ".css",
+  ".scss",
+  ".txt",
+];
+/** 检索时单文件最大读取体积 */
+const MAX_SEARCH_FILE_BYTES = 512 * 1024;
+/** 单次读取文件的最大字节数 */
+const MAX_READ_BYTES = 1024 * 1024;
+
+/** 子包自带 readme 的乱码特征字符（脚本生成的 readme 存在 UTF-8/GBK 二次编码问题） */
+const GARBLED_MARKERS = /[\u953b\u9286\u93b8\u9470\u9428]/;
+
+/**
+ * 指南 topic → 知识文件映射
+ *
+ * `topic` 与 reui 版工具的参数名保持一致，取值按 ReView（uni-app x）的实际情况适配。
+ */
+export const GUIDE_TOPICS = [
+  {
+    key: "overview",
+    label: "总览",
+    files: [README_FILE, "docs/index.md", `${GUIDE_DIR}/introduction.md`],
+  },
+  {
+    key: "install",
+    label: "安装与引入",
+    files: [`${GUIDE_DIR}/introduction.md`, README_FILE],
+    headings: ["安装", "引入", "全局配置", "快速使用", "运行", "npm"],
+  },
+  {
+    key: "easycom",
+    label: "easycom 自动引入",
+    files: [README_FILE, `${GUIDE_DIR}/introduction.md`],
+    headings: ["引入", "快速使用", "easycom"],
+  },
+  {
+    key: "theme",
+    label: "主题与样式定制",
+    files: [`${GUIDE_DIR}/theme.md`, `${GUIDE_DIR}/introduction.md`],
+    headings: ["主题", "变量", "暗色", "样式", "re-theme", "re-common"],
+  },
+  {
+    key: "i18n",
+    label: "国际化",
+    files: [`${GUIDE_DIR}/locale.md`, README_FILE],
+    headings: ["国际化", "语言", "locale", "特性"],
+  },
+  {
+    key: "platform",
+    label: "平台与运行",
+    files: [README_FILE, "docs/index.md"],
+    headings: ["平台", "运行", "特性", "脚本", "结构"],
+  },
+  {
+    key: "changelog",
+    label: "版本记录",
+    files: [CHANGELOG_FILE, `${GUIDE_DIR}/changelog.md`],
+  },
+  {
+    key: "conventions",
+    label: "工程与组件约定",
+    files: [`${GUIDE_DIR}/introduction.md`, README_FILE],
+    headings: ["基础模块", "项目结构", "脚本命令", "约定", "结构"],
+  },
+];
+
+export const GUIDE_TOPIC_KEYS = GUIDE_TOPICS.map((item) => item.key);
+
+// ============================ 通用工具函数 ============================
+
+function isTextFile(file) {
+  return TEXT_EXTENSIONS.some((ext) => file.endsWith(ext));
+}
+
+function lineCount(text) {
+  return text === "" ? 1 : text.split("\n").length;
+}
+
+/** readme 是否为二次编码的乱码（这种内容不能当文档喂给 AI） */
+export function isGarbledText(text) {
+  return GARBLED_MARKERS.test(String(text ?? ""));
+}
+
+/** 是否可作为知识点根目录（完整仓库 / 只装了 uni_modules 的项目 / 组件包目录） */
+export function isReviewRoot(dir) {
+  if (!dir) return false;
+  let stat;
+  try {
+    stat = fs.statSync(dir);
+  } catch {
+    return false;
+  }
+  if (!stat.isDirectory()) return false;
+  // 1. 完整仓库：docs/components + uni_modules
+  if (fs.existsSync(path.join(dir, DOCS_DIR))) return true;
+  // 2. 项目 / 仓库根：含 uni_modules/reglow-review 组件目录
+  if (
+    fs.existsSync(path.join(dir, COMPONENT_DIR)) &&
+    fs.existsSync(path.join(dir, SIDEBAR_FILE))
+  )
+    return true;
+  if (fs.existsSync(path.join(dir, COMPONENT_DIR))) return true;
+  // 3. 组件包自身（uni_modules/reglow-review）：components/re-* 直接位于其下
+  if (
+    fs.existsSync(path.join(dir, "components")) &&
+    fs.existsSync(path.join(dir, CHANGELOG_FILE))
+  )
+    return true;
+  return false;
+}
+
+/**
+ * 一个「知识点根目录」内部可能有三种形态，需要归一化成「仓库根」语义：
+ * - 仓库根：含 `docs/` 与 `uni_modules/`
+ * - 项目根：含 `uni_modules/reglow-review/`
+ * - 组件包目录：`uni_modules/reglow-review` 自身（`components/re-*` 直接在其下）
+ *
+ * 返回归一化的仓库根（把组件包目录折算到 `uni_modules/` 的上一级）。
+ */
+export function normalizeReviewRoot(dir) {
+  if (!dir) return null;
+  if (fs.existsSync(path.join(dir, DOCS_DIR))) return dir;
+  if (fs.existsSync(path.join(dir, COMPONENT_DIR))) return dir;
+  const componentsDir = path.join(dir, "components");
+  if (
+    fs.existsSync(componentsDir) &&
+    fs.existsSync(path.join(dir, CHANGELOG_FILE))
+  ) {
+    const parent = path.dirname(dir);
+    const grand = path.dirname(parent);
+    // <project>/uni_modules/reglow-review → <project>（catalog 会按 uni_modules/reglow-review 找）
+    if (path.basename(parent) === "uni_modules") return grand;
+    // 兜底：把该目录当作仓库根（无 docs / pages，只能读源码）
+    return dir;
+  }
+  return null;
+}
+
+/** 解析本地知识点根目录 */
+export function resolveLocalRoot(explicitRoot) {
+  const candidates = [];
+  if (explicitRoot) candidates.push(path.resolve(explicitRoot));
+  if (process.env.REVIEW_ROOT)
+    candidates.push(path.resolve(process.env.REVIEW_ROOT));
+  // 仓库内运行：review/mcp → review
+  candidates.push(path.resolve(PACKAGE_DIR, ".."));
+  // 当前项目已安装的组件（uni_modules 安装方式）
+  candidates.push(path.join(process.cwd(), COMPONENT_DIR));
+  candidates.push(process.cwd());
+  for (const candidate of candidates) {
+    if (!isReviewRoot(candidate)) continue;
+    const root = normalizeReviewRoot(candidate);
+    if (root) return root;
+  }
+  return 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;
+}
+
+/**
+ * 提取指定符号的完整定义（函数 / 常量 / 类 / 接口 / 类型）
+ *
+ * 同时适用于 `.uvue` / `.uts`：uts 的 `function name(...) : Type {}` 与
+ * `const name = computed(...)` 两类写法都能命中。
+ *
+ * @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 && (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];
+}
+
+// ============================ 代码示例提取 ============================
+
+/** 从 Markdown 中提取带标题上下文的代码块（官网兜底内容用） */
+export 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;
+}
+
+/** 匹配一段配对的 `<view ...>...</view>`（返回**不含**开始标签的内部内容与结束位置） */
+function extractViewBlock(text, startIndex) {
+  const openEnd = text.indexOf(">", startIndex);
+  if (openEnd === -1) return null;
+  const re = /<view(?=[\s/])|<\/view>/g;
+  re.lastIndex = openEnd + 1;
+  let depth = 1;
+  let match;
+  while ((match = re.exec(text))) {
+    if (match[0] === "</view>") {
+      depth -= 1;
+      if (depth === 0)
+        return {
+          inner: text.slice(openEnd + 1, match.index),
+          end: re.lastIndex,
+        };
+    } else {
+      depth += 1;
+    }
+  }
+  return null;
+}
+
+/** 去掉每行公共缩进 */
+function dedent(text) {
+  const lines = String(text ?? "").split("\n");
+  while (lines.length && lines[0].trim() === "") lines.shift();
+  while (lines.length && lines[lines.length - 1].trim() === "") lines.pop();
+  const indents = lines
+    .filter((line) => line.trim() !== "")
+    .map((line) => line.match(/^[ \t]*/)[0].replace(/\t/g, "  ").length);
+  const min = indents.length ? Math.min(...indents) : 0;
+  return lines
+    .map((line) =>
+      line
+        .replace(/\t/g, "  ")
+        .slice(min)
+        .replace(/[ \t]+$/, ""),
+    )
+    .join("\n");
+}
+
+/** 剥掉演示页的 demo-block 外壳，只留可直接复制的用法片段 */
+export function stripDemoWrapper(chunk) {
+  const raw = String(chunk ?? "").trim();
+  let body = raw;
+  const outerStart = raw.indexOf('<view class="demo-block"');
+  if (outerStart !== -1) {
+    const outer = extractViewBlock(raw, outerStart);
+    if (outer) body = outer.inner;
+  }
+  body = body.replace(/<text class="demo-block__title">[\s\S]*?<\/text>/g, "");
+  const innerStart = body.indexOf('<view class="demo-block__content');
+  if (innerStart !== -1) {
+    const inner = extractViewBlock(body, innerStart);
+    if (inner) body = inner.inner;
+  }
+  return dedent(body);
+}
+
+/**
+ * 从演示页（`pages/<category>/<name>/<name>.uvue`）提取可复制示例
+ *
+ * ReView 的组件文档页（`docs/components/*.md`）**不含代码块**，官网「代码示例」区块
+ * 就是把演示页的模板按 `<!-- 小节标题 -->` 切分后展示的，因此这里做同样的切分。
+ *
+ * @param {string} code 演示页源码
+ * @param {{ name?: string }} [options]
+ * @returns {{ title: string, lang: string, code: string }[]}
+ */
+export function parseDemoExamples(code, { name = "" } = {}) {
+  const source = String(code ?? "").replace(/\r\n/g, "\n");
+  const template = source.match(/<template>([\s\S]*?)<\/template>/)?.[1] ?? "";
+  const examples = [];
+
+  if (template) {
+    const markers = [...template.matchAll(/<!--\s*([\s\S]*?)\s*-->/g)];
+    for (let i = 0; i < markers.length; i += 1) {
+      const title = markers[i][1].replace(/\s+/g, " ").trim() || "示例";
+      const start = markers[i].index + markers[i][0].length;
+      const end =
+        i + 1 < markers.length ? markers[i + 1].index : template.length;
+      const snippet = stripDemoWrapper(template.slice(start, end));
+      if (snippet.trim() === "") continue;
+      examples.push({ title, lang: "uvue", code: snippet });
+    }
+    if (examples.length === 0) {
+      const snippet = stripDemoWrapper(template);
+      if (snippet.trim() !== "")
+        examples.push({
+          title: name ? `${name} 演示页模板` : "演示页模板",
+          lang: "uvue",
+          code: snippet,
+        });
+    }
+  }
+
+  const script = source.match(/<script[^>]*>([\s\S]*?)<\/script>/)?.[1]?.trim();
+  if (script)
+    examples.push({
+      title: name ? `${name} 演示页 script` : "演示页 script",
+      lang: "uts",
+      code: script,
+    });
+
+  return examples;
+}
+
+// ============================ 版本解析 ============================
+
+/**
+ * 从 `CHANGELOG.md` 顶部解析版本号（`## 1.0.5（2026-09-14）`）
+ *
+ * @returns {{ version: string | null, date: string | null, source: string | null }}
+ */
+export function parseChangelogVersion(markdown) {
+  const text = String(markdown ?? "");
+  const match = text.match(
+    /^##\s*v?(\d+\.\d+\.\d+[^\s（(]*)\s*(?:[（(]([^）)]*)[）)])?/m,
+  );
+  if (!match) return { version: null, date: null, source: null };
+  return { version: match[1], date: match[2] ?? null, source: null };
+}
+
+// ============================ 知识对象 ============================
+
+/**
+ * 创建知识对象
+ *
+ * @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;
+  const requestedVersion = options.version
+    ? String(options.version).trim()
+    : null;
+  const root = resolveLocalRoot(options.root);
+  const catalog = createCatalog(root ?? path.resolve(PACKAGE_DIR, ".."));
+
+  let source = "workspace";
+  let warning = null;
+  if (!root) {
+    if (allowSite) {
+      warning =
+        "未找到本地 ReView 知识源（既未指定 --root，也未在项目内发现 uni_modules/reglow-review），" +
+        "文档将回退到官方文档站点（最新版）";
+      source = "site";
+    } else {
+      warning = "未找到本地 ReView 知识源，且已禁用官网回退";
+      source = "none";
+    }
+    // 没有本地根目录时，目录只能来自官网总览页（惰性拉取，失败则为空）
+  } else if (!fs.existsSync(path.join(root, DOCS_DIR))) {
+    // 只装了 uni_modules/reglow-review：只有源码，没有仓库级文档与演示页
+    source = "local";
+    warning =
+      "当前知识源只包含 `uni_modules/reglow-review` 安装包（无 `docs/` 与 `pages/`）：" +
+      "源码可用，组件文档与官方链接将回退到官网文档站点";
+  } else {
+    // 完整仓库（含 docs/ 与 pages/）
+    source = "workspace";
+  }
+  if (requestedVersion) {
+    const hint = `${NPM_NOT_PUBLISHED_HINT}（收到 version=${requestedVersion}，已忽略）`;
+    warning = warning ? `${warning}；${hint}` : hint;
+  }
+
+  // ---- 版本号：CHANGELOG.md 顶部为准 ----
+  const changelogPath = root ? path.join(root, CHANGELOG_FILE) : null;
+  const changelogText = changelogPath ? readTextSafe(changelogPath) : null;
+  const parsedVersion = parseChangelogVersion(changelogText ?? "");
+  let version = parsedVersion.version;
+  let versionDate = parsedVersion.date;
+  let versionSource = version ? CHANGELOG_FILE : null;
+  if (!version && root) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(root, "package.json"), "utf8"),
+      );
+      if (pkg?.version) {
+        version = String(pkg.version);
+        versionSource = "package.json";
+      }
+    } catch {
+      /* 忽略 */
+    }
+  }
+  if (!version) {
+    version = "unknown";
+    versionSource = null;
+  }
+
+  function readFileByRel(relPath) {
+    if (!root) return null;
+    const target = path.resolve(root, relPath);
+    if (!target.startsWith(path.resolve(root))) return null;
+    return readTextSafe(target, MAX_READ_BYTES);
+  }
+
+  function entryOf(name) {
+    return catalog.catalogItem(name);
+  }
+
+  /** 组件 readme（脚本生成的 readme 存在乱码时不可用） */
+  function readmeOf(entry) {
+    if (!entry?.dir) return null;
+    const rel = `${entry.dir}/readme.md`;
+    const text = readFileByRel(rel);
+    if (!text || isGarbledText(text)) return null;
+    return { path: rel, text };
+  }
+
+  /** 汇总组件源码（文档缺失时的最后兜底：Props / Events 一目了然） */
+  function sourceDigest(entry) {
+    const mainFiles = entry.files.filter((file) => file.endsWith(".uvue"));
+    const chunks = mainFiles.map((file) => {
+      const text = readFileByRel(`${entry.dir}/${file}`);
+      if (!text) return null;
+      const lines = Math.min(lineCount(text), 400);
+      const head = text.split("\n").slice(0, lines).join("\n");
+      return `### ${file}（前 ${lines} 行）\n\n\`\`\`uvue\n${head}\n\`\`\``;
+    });
+    return chunks.filter(Boolean).join("\n\n");
+  }
+
+  const knowledge = {
+    catalog,
+
+    meta() {
+      return {
+        version,
+        versionDate,
+        versionSource,
+        source,
+        root: root ? toPosix(root) : null,
+        requestedVersion,
+        warning,
+        docsBase: DOCS_BASE,
+        changelogUrl: changelogUrlFor(),
+      };
+    },
+
+    /** 组件清单 */
+    listComponents({ category } = {}) {
+      const all = catalog.components;
+      if (!category) return all;
+      const key = String(category).trim();
+      const def = catalog.categoryOf(key);
+      return all.filter(
+        (entry) =>
+          entry.category === key ||
+          entry.categoryLabel === key ||
+          (def && entry.categoryLabel === def.label),
+      );
+    },
+
+    /** 组件条目 */
+    getComponent(name) {
+      return entryOf(name);
+    },
+
+    /**
+     * 组件文档
+     * @returns {Promise<{ markdown: string, kind: "doc"|"readme"|"source"|"site"|"none", path: string|null, url: string|null }>}
+     */
+    async getDocument(name) {
+      const entry = entryOf(name);
+      const url = entry?.docsUrl ?? null;
+      const doc = entry?.docPath ? readFileByRel(entry.docPath) : null;
+      if (doc) {
+        return {
+          markdown: doc,
+          kind: "doc",
+          path: entry.docPath,
+          url: entry.docsUrl,
+        };
+      }
+
+      const readme = readmeOf(entry);
+      if (readme) {
+        return {
+          markdown: readme.text,
+          kind: "readme",
+          path: readme.path,
+          url,
+        };
+      }
+
+      const siteDoc = allowSite
+        ? await fetchSiteDocument(entry?.name ?? String(name), {
+          category: entry?.category ?? null,
+        })
+        : null;
+      if (siteDoc) {
+        return {
+          markdown: siteDoc.markdown,
+          kind: "site",
+          path: null,
+          url: siteDoc.url,
+        };
+      }
+
+      const digest = entry ? sourceDigest(entry) : "";
+      if (digest) {
+        return {
+          markdown: digest,
+          kind: "source",
+          path: entry.dir,
+          url: entry.docsUrl,
+        };
+      }
+      return { markdown: "", kind: "none", path: null, url };
+    },
+
+    /**
+     * 代码示例（优先演示页，缺失时走官网兜底）
+     *
+     * @param {string} name 组件名
+     * @param {{ index?: number, lang?: string }} [options]
+     */
+    async getCodeExamples(name, { index, lang } = {}) {
+      const entry = entryOf(name);
+      const filter = (items) =>
+        !lang || lang === "all"
+          ? items
+          : items.filter((item) => item.lang === lang);
+      const pick = (items) =>
+        index === undefined ? items : items.slice(index, index + 1);
+
+      const demo = entry?.demoPath ? readFileByRel(entry.demoPath) : null;
+      if (demo) {
+        const examples = filter(parseDemoExamples(demo, { name: entry.name }));
+        if (examples.length > 0) {
+          return {
+            examples: pick(examples),
+            source: "demo",
+            path: entry.demoPath,
+            url: entry.docsUrl,
+          };
+        }
+      }
+
+      const doc = entry?.docPath ? readFileByRel(entry.docPath) : null;
+      if (doc) {
+        const examples = filter(parseCodeExamples(doc));
+        if (examples.length > 0) {
+          return {
+            examples: pick(examples),
+            source: "doc",
+            path: entry.docPath,
+            url: entry.docsUrl,
+          };
+        }
+      }
+
+      if (allowSite) {
+        const siteDoc = await fetchSiteDocument(entry?.name ?? String(name), {
+          category: entry?.category ?? null,
+        });
+        if (siteDoc) {
+          const examples = filter(parseCodeExamples(siteDoc.markdown));
+          if (examples.length > 0) {
+            return {
+              examples: pick(examples),
+              source: "site",
+              path: null,
+              url: siteDoc.url,
+            };
+          }
+        }
+      }
+
+      return {
+        examples: [],
+        source: "none",
+        path: null,
+        url: entry?.docsUrl ?? null,
+      };
+    },
+
+    /** 组件文件清单 */
+    listFiles(name) {
+      const entry = entryOf(name);
+      if (!entry) return null;
+      if (!entry.dir) return [];
+      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) {
+              const text = fs.readFileSync(abs, "utf8");
+              if (!isGarbledText(text)) lines = lineCount(text);
+            }
+          } catch {
+            /* 忽略 */
+          }
+        }
+        return { path: file, size, lines };
+      });
+    },
+
+    /** 读取组件内文件（带路径穿越防护） */
+    readComponentFile(name, file, { startLine, endLine } = {}) {
+      const entry = entryOf(name);
+      if (!entry) return { error: `未找到组件「${name}」` };
+      if (!entry.dir)
+        return {
+          error:
+            `组件「${entry.name}」在仓库里没有独立源码目录（该文档页对应 ` +
+            `${(entry.tags ?? []).map((tag) => `\`${tag}\``).join(" / ") || "多个组件"}），` +
+            `可用组件见 list_component_files 的同类组件。`,
+        };
+      const normalized = toPosix(String(file ?? "")).replace(/^\.\//, "");
+      const componentRoot = path.resolve(root ?? "", entry.dir);
+      const target = path.resolve(componentRoot, normalized);
+      // 必须留在组件目录内（`..` / 绝对路径都会被拦下）
+      if (!root || !target.startsWith(componentRoot + path.sep)) {
+        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,
+        garbled: isGarbledText(text),
+      };
+    },
+
+    /** 提取函数 / 常量 / 类定义 */
+    findFunction(name, symbol, { file } = {}) {
+      const entry = entryOf(name);
+      if (!entry) return { error: `未找到组件「${name}」` };
+      if (!entry.dir)
+        return { error: `组件「${entry.name}」没有独立源码目录，无法提取符号` };
+      const candidates = file
+        ? [toPosix(file)]
+        : entry.files.filter(
+          (item) =>
+            /\.(uvue|uts|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 };
+      if (!root) return { hits: [], scanned: 0, terms };
+
+      const entries = component
+        ? [entryOf(component)].filter(Boolean)
+        : knowledge.listComponents({ category });
+      const targets = [];
+      for (const entry of entries) {
+        if (entry.docPath) targets.push({ entry, file: entry.docPath });
+        if (entry.demoPath) targets.push({ entry, file: entry.demoPath });
+        for (const item of entry.files) {
+          // `readme.md` 多为脚本生成的二次编码文本（乱码），不参与检索
+          if (item === "readme.md") continue;
+          if (!isTextFile(item)) continue;
+          targets.push({ entry, file: `${entry.dir}/${item}` });
+        }
+      }
+      // 库级文档（仅在未限定组件时参与检索，避免污染组件范围的检索结果）
+      const libraryFiles = component
+        ? []
+        : [
+          README_FILE,
+          CHANGELOG_FILE,
+          "docs/index.md",
+          ...(fs.existsSync(path.join(root, GUIDE_DIR))
+            ? fs
+              .readdirSync(path.join(root, GUIDE_DIR))
+              .filter((file) => file.endsWith(".md"))
+              .map((file) => `${GUIDE_DIR}/${file}`)
+            : []),
+        ];
+      for (const extra of libraryFiles) {
+        if (fs.existsSync(path.join(root, extra))) {
+          targets.push({
+            entry: { name: "review", category: "library", docsUrl: DOCS_BASE },
+            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 };
+    },
+
+    /**
+     * 库级指南（安装 / easycom / 主题 / 国际化 / 平台 / 版本记录 / 约定 等章节）
+     *
+     * @param {string} topic GUIDE_TOPICS 的 key
+     */
+    getGuide(topic) {
+      if (!root) return null;
+      const key = String(topic ?? "overview").trim() || "overview";
+      const def = GUIDE_TOPICS.find((item) => item.key === key);
+      const files = def?.files ?? [README_FILE];
+      const sources = files
+        .map((file) => ({ file, text: readFileByRel(file) }))
+        .filter((item) => Boolean(item.text));
+      if (sources.length === 0) return null;
+
+      const sectionsOf = (file, text) =>
+        text
+          .split(/\n(?=#{1,3}\s)/)
+          .map((chunk) => ({
+            file,
+            title: chunk.match(/^#{1,3}\s+(.*)$/m)?.[1]?.trim() ?? "",
+            text: chunk.trim(),
+          }))
+          .filter((section) => section.text !== "");
+
+      let sections = sources.flatMap((item) =>
+        sectionsOf(item.file, item.text),
+      );
+      const keywords = def?.headings;
+      if (keywords?.length) {
+        const matched = sections.filter((section) => {
+          const haystack =
+            `${section.title}\n${section.text.slice(0, 400)}`.toLowerCase();
+          return keywords.some((keyword) =>
+            haystack.includes(String(keyword).toLowerCase()),
+          );
+        });
+        // 关键词没命中任何章节时退回该 topic 的全部章节（避免返回空）
+        if (matched.length > 0) sections = matched;
+      }
+      if (sections.length === 0) return null;
+      return {
+        sections,
+        docsBase: DOCS_BASE,
+        url: guideUrlFor(
+          {
+            install: "introduction",
+            easycom: "introduction",
+            theme: "theme",
+            i18n: "locale",
+          }[key] ?? "",
+        ),
+      };
+    },
+
+    /** 官网组件总览（回退用） */
+    async siteOverview() {
+      if (!allowSite) return null;
+      return fetchSiteOverview();
+    },
+
+    /** 官网指南页（回退用） */
+    async siteGuide(slug) {
+      if (!allowSite) return null;
+      return fetchSiteGuide(slug);
+    },
+
+    /** 官网版本记录页（回退用） */
+    async siteChangelog() {
+      if (!allowSite) return null;
+      return fetchSiteChangelog();
+    },
+  };
+
+  logger(
+    `[review-mcp] 知识源：source=${source} version=${version} root=${root ?? "(none)"}` +
+    (warning ? ` warning=${warning}` : ""),
+  );
+  return knowledge;
+}
+
+export {
+  CATEGORIES,
+  CHANGELOG_FILE,
+  COMPONENT_DIR,
+  DOCS_BASE,
+  DOCS_DIR,
+  GUIDE_DIR,
+  PACKAGE_DIR,
+  createCatalog,
+};