dsh-plugin-t-expert 0.1.0

package/lib/catalog.js

@@ -0,0 +1,376 @@
+/**
+ * T团队 花名册：扫描固定专家目录，解析 frontmatter，按 slug 建立索引。
+ *
+ * 目录形态固定为 `<root>/<division>/<slug>.md`，
+ * 其中 game-development 之类的分区可以再嵌套一层子目录（递归扫描）。
+ * persona 正文在召唤时按需读取，不在目录列表阶段预加载。
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+/** 内置的分区目录名（= divisions.json 的键）。 */
+export const DEFAULT_DIVISIONS = [
+  "academic",
+  "design",
+  "engineering",
+  "finance",
+  "game-development",
+  "gis",
+  "healthcare",
+  "marketing",
+  "paid-media",
+  "product",
+  "project-management",
+  "research",
+  "sales",
+  "security",
+  "spatial-computing",
+  "specialized",
+  "support",
+  "testing",
+];
+
+/** 分区显示名（面板里用；缺省回退分区 key）。 */
+export const DIVISION_LABEL = {
+  academic: { zh: "学术", en: "Academic" },
+  design: { zh: "设计", en: "Design" },
+  engineering: { zh: "工程", en: "Engineering" },
+  finance: { zh: "金融", en: "Finance" },
+  "game-development": { zh: "游戏开发", en: "Game Development" },
+  gis: { zh: "地理信息", en: "GIS" },
+  healthcare: { zh: "医疗健康", en: "Healthcare" },
+  marketing: { zh: "市场营销", en: "Marketing" },
+  "paid-media": { zh: "付费媒体", en: "Paid Media" },
+  product: { zh: "产品", en: "Product" },
+  "project-management": { zh: "项目管理", en: "Project Management" },
+  research: { zh: "研究", en: "Research" },
+  sales: { zh: "销售", en: "Sales" },
+  security: { zh: "安全", en: "Security" },
+  "spatial-computing": { zh: "空间计算", en: "Spatial Computing" },
+  specialized: { zh: "专业", en: "Specialized" },
+  support: { zh: "支持", en: "Support" },
+  testing: { zh: "测试", en: "Testing" },
+};
+
+/**
+ * 取分区显示名：优先侧车目录 zh/divisions.json（数据驱动，上游新增分区只需补数据），
+ * 其次内置对照表，最后回退分区 key。
+ */
+export function divisionOf(division, labels) {
+  const custom = labels?.[division];
+  if (typeof custom === "string" && custom !== "") return { zh: custom, en: custom };
+  if (custom !== undefined && typeof custom === "object") {
+    return { zh: custom.zh ?? division, en: custom.en ?? division };
+  }
+  return DIVISION_LABEL[division] ?? { zh: division, en: division };
+}
+
+/** 读侧车分区标签：{ "<division>": "中文名" | { zh, en } }。 */
+export async function loadDivisionLabels(zhRoot) {
+  if (typeof zhRoot !== "string" || zhRoot === "") return {};
+  return await readJson(join(zhRoot, "divisions.json"));
+}
+
+/**
+ * 自动发现分区：root 下所有直接含 .md 的顶层目录。
+ * 这样上游新增的分区不必改代码就能被扫描到。
+ */
+export async function discoverDivisions(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const files = await readdir(join(root, entry.name)).catch(() => []);
+    if (files.some((name) => name.endsWith(".md"))) found.push(entry.name);
+  }
+  return found.sort();
+}
+
+const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,127}$/;
+const SEGMENT_PATTERN = /^[a-z0-9][a-z0-9.-]{0,127}$/;
+
+/** 去掉 BOM，统一换行，避免解析抖动。 */
+export function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/** 去掉 YAML 标量两端的引号。 */
+export function unquote(value) {
+  const text = String(value ?? "").trim();
+  if (text.length >= 2 && ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+/** 从 frontmatter 文本里取一个标量字段。 */
+function field(frontmatter, key) {
+  const match = frontmatter.match(new RegExp(`^${key}\\s*:\\s*(.*)$`, "m"));
+  return match === null ? undefined : unquote(match[1]);
+}
+
+/** 解析 frontmatter 元数据（name/description/descriptionEn/emoji/color/vibe）。 */
+export function parseMetadata(frontmatter) {
+  return {
+    name: field(frontmatter, "name"),
+    description: field(frontmatter, "description"),
+    descriptionEn: field(frontmatter, "descriptionEn"),
+    emoji: field(frontmatter, "emoji"),
+    color: field(frontmatter, "color"),
+    vibe: field(frontmatter, "vibe"),
+  };
+}
+
+/** 解析完整文件：frontmatter + 正文。 */
+export function parseFrontmatter(raw) {
+  const match = stripBom(raw).match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (match === null) return undefined;
+  return { ...parseMetadata(match[1]), body: match[2].trim() };
+}
+
+/** 中和 `{{` 双花括号，避免 persona 正文被当成模板插值。 */
+export function sanitize(text) {
+  return text.replace(/\{(?=\{)/g, "{\u200b");
+}
+
+/** 单次截断，用于列表里的简介。 */
+export function truncate(text, limit) {
+  const value = String(text ?? "");
+  return value.length > limit ? `${value.slice(0, Math.max(0, limit - 1))}…` : value;
+}
+
+/** 递归收集目录下的 .md 文件（跳过符号链接，与 DSH 的扫描口径一致）。 */
+async function walkMarkdown(dir, onFile) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) await walkMarkdown(full, onFile);
+    else if (entry.isFile() && entry.name.endsWith(".md")) await onFile(full, entry.name);
+  }
+}
+
+/** 只读前置检查：根目录必须存在且是目录。 */
+export async function assertDirectory(root) {
+  const info = await stat(root).catch(() => undefined);
+  if (info === undefined) throw new Error(`专家目录不存在：${root}`);
+  if (!info.isDirectory()) throw new Error(`专家目录不是目录：${root}`);
+}
+
+/**
+ * 载入花名册。
+ * @param root 专家根目录
+ * @param divisions 要扫描的分区目录名
+ * @returns Map<slug, Expert>，Expert 额外带 personaPath（正文按需读取）
+ */
+export async function loadCatalog(root, divisions, options = {}) {
+  await assertDirectory(root);
+  const zhRoot = typeof options.zhRoot === "string" && options.zhRoot !== "" ? options.zhRoot : undefined;
+  // 中文侧车目录：names.json / descriptions.json / <与 experts 同相对路径的 .md>。
+  // 译文永不写进 experts（那是上游镜像），所以上游更新不受影响。
+  const zhNames = zhRoot === undefined ? {} : await readJson(join(zhRoot, "names.json"));
+  const zhDescriptions = zhRoot === undefined ? {} : await readJson(join(zhRoot, "descriptions.json"));
+  const divisionLabels = await loadDivisionLabels(zhRoot);
+  // 未显式配置分区时自动发现：上游新增分区无需改代码。
+  const scanned = divisions !== undefined && divisions.length > 0 ? divisions : await discoverDivisions(root);
+  const catalog = new Map();
+  for (const division of scanned) {
+    if (!SEGMENT_PATTERN.test(division) || division.includes("..")) continue;
+    const dir = join(root, division);
+    await walkMarkdown(dir, async (filePath, fileName) => {
+      const slug = fileName.slice(0, -3);
+      if (!SLUG_PATTERN.test(slug)) return;
+      let raw;
+      try {
+        raw = stripBom(await readFile(filePath, "utf8"));
+      } catch {
+        return;
+      }
+      const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (match === null) return;
+      const meta = parseMetadata(match[1]);
+      if (!meta.name || !meta.description) return;
+      if (catalog.has(slug)) {
+        console.warn(`[t-team] slug 冲突，后者覆盖前者：${slug}`);
+      }
+      catalog.set(slug, {
+        slug,
+        name: meta.name,
+        nameEn: meta.name,
+        description: meta.description,
+        descriptionEn: meta.descriptionEn ?? "",
+        emoji: meta.emoji ?? "",
+        color: meta.color ?? "",
+        vibe: meta.vibe ?? "",
+        division,
+        personaPath: filePath,
+        relativePath: relative(root, filePath),
+      });
+    });
+  }
+  if (catalog.size === 0) throw new Error(`专家目录为空或没有可解析的专家：${root}`);
+  markConflicts(catalog);
+  catalog.divisions = scanned;
+  catalog.labels = divisionLabels;
+  if (zhRoot !== undefined) {
+    for (const expert of catalog.values()) {
+      const nameZh = zhNames[expert.slug];
+      if (typeof nameZh === "string" && nameZh !== "") expert.nameZh = nameZh;
+      const descriptionZh = zhDescriptions[expert.slug];
+      if (typeof descriptionZh === "string" && descriptionZh !== "") expert.descriptionZh = descriptionZh;
+      const zhPath = join(zhRoot, expert.relativePath);
+      if (await isFile(zhPath)) expert.personaPathZh = zhPath;
+    }
+  }
+  return catalog;
+}
+
+/** 读 JSON，失败就当空对象（侧车目录可缺省）。 */
+async function readJson(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return parsed !== null && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** 是否为普通文件。 */
+async function isFile(path) {
+  const info = await stat(path).catch(() => undefined);
+  return info !== undefined && info.isFile();
+}
+
+/**
+ * 标记重名专家：同名（含英文名）的两位都无法召唤，避免召唤到错误角色。
+ * 冲突项仍留在列表里（面板可见），但解析与召唤会跳过它们。
+ */
+export function markConflicts(catalog) {
+  const owners = new Map();
+  for (const expert of catalog.values()) {
+    for (const name of new Set([expert.name, expert.nameEn])) {
+      const key = normalizeName(name);
+      if (key === "") continue;
+      const slugs = owners.get(key) ?? new Set();
+      slugs.add(expert.slug);
+      owners.set(key, slugs);
+    }
+  }
+  for (const slugs of owners.values()) {
+    if (slugs.size < 2) continue;
+    for (const slug of slugs) {
+      const expert = catalog.get(slug);
+      if (expert !== undefined) expert.conflict = true;
+    }
+  }
+  return catalog;
+}
+
+/**
+ * 读取一位专家的 persona 正文（召唤时用）。
+ * 中文 locale 下优先用侧车目录里的中文正文，缺失则回退英文。
+ */
+export async function readPersona(expert, locale = "zh") {
+  const zhPath = locale === "zh" ? expert.personaPathZh : undefined;
+  const raw = zhPath === undefined
+    ? stripBom(await readFile(expert.personaPath, "utf8"))
+    : stripBom(await readFile(zhPath, "utf8").catch(() => readFile(expert.personaPath, "utf8")));
+  const parsed = parseFrontmatter(raw);
+  if (parsed === undefined) return raw.trim();      // 容忍没有 frontmatter 的译文文件
+  if (parsed.body === "") throw new Error(`专家提示词格式无效：${expert.relativePath}`);
+  return parsed.body;
+}
+
+/** 名称归一化，用于解析召唤目标。 */
+function normalizeName(value) {
+  return String(value ?? "").trim().toLowerCase();
+}
+
+/**
+ * 去掉 emoji / 标点后的比较形式：面板与 @ 芯片里会带 emoji 与全角空格，
+ * 模型也可能把「🗺️ 地理学家」原样传回来，所以比较前摘掉非文字字符。
+ */
+function cleanName(value) {
+  return normalizeName(value).replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s+/g, " ").trim();
+}
+
+/** 一位专家所有可用来指名它的键：中文名、英文名、slug。 */
+function matchKeys(expert) {
+  return [expert.nameZh, expert.name, expert.nameEn, expert.slug].filter((v) => typeof v === "string" && v !== "");
+}
+
+/**
+ * 解析召唤目标：中文名 / 英文名 / slug 都能用（面板与 @ 芯片传的是中文名，模型也可能带 emoji 回传）。
+ * 顺序：全名精确 → 唯一子串；歧义或缺省都给出可操作的报错。
+ */
+export function resolveExpert(experts, query, locale = "zh") {
+  const target = normalizeName(query);
+  const targetClean = cleanName(query);
+  if (target === "") throw new Error("expert 参数不能为空");
+  const display = (expert) => (locale === "en" ? (expert.nameEn || expert.name) : (expert.nameZh || expert.name));
+  const isExact = (expert) => matchKeys(expert).some((key) => normalizeName(key) === target || (targetClean !== "" && cleanName(key) === targetClean));
+  const exact = experts.filter(isExact);
+  if (exact.length === 1) return exact[0];
+  const isSubstring = (expert) => matchKeys(expert).some((key) => {
+    const normalized = normalizeName(key);
+    const cleaned = cleanName(key);
+    return normalized.includes(target) || (targetClean.length >= 2 && cleaned.includes(targetClean));
+  });
+  const matches = exact.length > 1 ? exact : experts.filter(isSubstring);
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    const preview = matches.slice(0, 12).map((e) => `${display(e)}(${e.slug})`).join(", ");
+    throw new Error(`专家名「${query}」有歧义，候选：${preview}`);
+  }
+  const samples = experts.slice(0, 8).map((e) => `${display(e)}(${e.slug})`).join(", ");
+  throw new Error(`找不到专家「${query}」；可以用中文名、英文名或 slug。可用示例：${samples}`);
+}
+
+/** 按分区分组（面板与 list_t_experts 共用）。 */
+/** 取该名册的分区清单（loadCatalog 把发现结果挂在返回的 Map 上）。 */
+export function catalogDivisions(catalog) {
+  return Array.isArray(catalog?.divisions) ? catalog.divisions : [];
+}
+
+export function groupByDivision(experts, enabled) {
+  const groups = new Map();
+  for (const expert of experts) {
+    if (enabled !== undefined && !enabled.has(expert.slug)) continue;
+    const list = groups.get(expert.division) ?? [];
+    list.push(expert);
+    groups.set(expert.division, list);
+  }
+  return [...groups.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([division, list]) => ({
+      division,
+      label: DIVISION_LABEL[division]?.zh ?? division,
+      labelEn: DIVISION_LABEL[division]?.en ?? division,
+      count: list.length,
+      experts: list.slice().sort((a, b) => a.slug.localeCompare(b.slug)),
+    }));
+}
+
+/** 受限并发映射，结果顺序与输入一致。 */
+export async function mapPool(items, concurrency, mapper) {
+  const results = new Array(items.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      results[index] = await mapper(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}