ygc-dsh-sync 1.2.2 → 1.3.0

package/lib/skillshare.js

@@ -0,0 +1,781 @@
+/**
+ * 技能共享（特征文件夹）——把「技能同步」做成和「插件清单同步」同一套模型。
+ *
+ * 插件那一侧只存清单（清单里只有名字、版本、来源坐标，安装一律联网拉）。
+ * 技能这一侧没有 registry，技能本身就是文件，所以规则相应地改成：
+ *
+ *   插件库\
+ *   └─ <我的特征名>\
+ *      ├─ FEATURE.json          本机特征说明（插件侧写的，本来就有的）
+ *      ├─ PLUGINS.json          本机插件清单（插件侧）
+ *      ├─ skills\               ← 本文件管这一层
+ *      │  ├─ SKILLS.json        本机技能索引（我自己算的）
+ *      │  ├─ SKILLS.md          同一份的人读版本
+ *      │  ├─ SKILL-LEARNINGS.json  我的学习台账（别人差异 → 我怎么处理）
+ *      │  ├─ SKILL-LEARNINGS.md    同一份的人读版本（**给别的机器看的**）
+ *      │  └─ <技能名>\
+ *      │     ├─ SKILL.md        技能正文（整棵目录一起备份）
+ *      │     ├─ scripts\ ...    技能自带的脚本与资料
+ *      │     └─ SKILL-CARD.json 这一个技能的名片：说明 / 来源 / 更新时间 / 内容指纹
+ *
+ * 三条硬规则：
+ *   1. **只写自己那一格**，别人的格只读。所有写入前过 assertOwnFeaturePath。
+ *   2. **备份是整棵目录**，不是只拷 SKILL.md：技能的价值常常在 scripts/ 与
+ *      references/ 里，只拷正文等于把可执行层扔掉。
+ *   3. **同名不同内容不等于覆盖**。谁新谁旧判不出来时不做破坏性动作，
+ *      交给学习台账（skill-learn.js）评估要不要合并，人再决定。
+ *
+ * 为什么不用 mtime 判新旧：NAS 同步会改写时间戳，这一点在会话同步一侧已经踩过。
+ * 这里把 mtime 只当「技能更新时间」展示，判同一律看内容指纹。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+import { assertOwnFeaturePath, featuresDir } from './plugins.js';
+import { parseFrontMatter, scanSkills, walkFiles } from './skills.js';
+
+/** 特征文件夹里放技能的那一层目录名。 */
+export const SKILLS_DIR = 'skills';
+/** 本机技能索引（机器读）。 */
+export const SKILLS_INDEX = 'SKILLS.json';
+/** 本机技能索引（人读）。 */
+export const SKILLS_INDEX_MD = 'SKILLS.md';
+/** 单个技能的名片。 */
+export const SKILL_CARD = 'SKILL-CARD.json';
+/** 学习台账（机器读）。 */
+export const LEARNINGS_INDEX = 'SKILL-LEARNINGS.json';
+/** 学习台账（人读，也是给别的机器参考的那一份）。 */
+export const LEARNINGS_INDEX_MD = 'SKILL-LEARNINGS.md';
+/** 来源台账：这个技能最初是从哪台机器 / 哪次学习来的。 */
+export const ORIGIN_INDEX = 'SKILL-ORIGIN.json';
+/** 等人工批准的学习草稿（落在本机自己的格子里，不直接覆盖本机技能）。 */
+export const DRAFTS_DIR = 'learn-drafts';
+
+/** 一键开关的默认值：默认开（与插件清单同步一致）。 */
+export const SHARE_DEFAULTS = Object.freeze({
+  enabled: true,
+  /** 同机不同内容时是否调用模型评估「怎么优化」。默认开。 */
+  learn: true,
+  /** 一轮最多评估几个冲突，避免一次同步跑太久。 */
+  learnPerRound: 4,
+  /** 评估通过后是否直接落到本机技能根。默认关：先出草稿，人批了再落。 */
+  autoApply: false,
+});
+
+/* ---------------------------------------------------------------- 路径 */
+
+/** 插件库根（与插件清单同步共用同一个根，一人一格）。 */
+export function libraryRootOf(config) {
+  return featuresDir(config);
+}
+
+/** 我的技能共享根：`插件库/<本机标识>/skills`。 */
+export function mySkillsRoot(config, machineId) {
+  const feature = String(machineId || '').trim();
+  if (!feature) throw new Error('缺少本机标识，拒绝定位技能共享目录');
+  return path.join(libraryRootOf(config), feature, SKILLS_DIR);
+}
+
+/** 别人的技能共享根（只读；名字先安全化，防 `../..`）。 */
+export function peerSkillsRoot(config, featureName) {
+  return path.join(libraryRootOf(config), featureName, SKILLS_DIR);
+}
+
+/* -------------------------------------------------------------- 小工具 */
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** 内容没变就不写（忽略易变字段），返回是否真的写了。 */
+function writeJsonIfChanged(file, value, volatile = ['generatedAt', 'lastSharedAt', 'ms']) {
+  const strip = (v) => {
+    if (Array.isArray(v)) return v.map(strip);
+    if (!v || typeof v !== 'object') return v;
+    const out = {};
+    for (const k of Object.keys(v).sort()) {
+      if (volatile.includes(k)) continue;
+      out[k] = strip(v[k]);
+    }
+    return out;
+  };
+  const old = readJson(file);
+  if (old !== undefined) {
+    try {
+      if (JSON.stringify(strip(old)) === JSON.stringify(strip(value))) return false;
+    } catch {
+      /* 比不了就写 */
+    }
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, file);
+  return true;
+}
+
+/** 文本版幂等写：比较时剔掉「生成时间」。 */
+function writeTextIfChanged(file, text) {
+  const strip = (s) => String(s).replace(/^> 生成时间：.*$/m, '');
+  try {
+    if (strip(fs.readFileSync(file, 'utf8')) === strip(text)) return false;
+  } catch {
+    /* 不存在就写 */
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, text, 'utf8');
+  fs.renameSync(tmp, file);
+  return true;
+}
+
+/** SKILL.md 的 sha256。与 dsh-mnemon 账本同一算法（逐字节）。 */
+export function mdHash(dir) {
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(path.join(dir, 'SKILL.md'))).digest('hex');
+  } catch {
+    return '';
+  }
+}
+
+/** 整棵技能目录的指纹（文件名 + 大小 + 内容），与时间戳无关。 */
+export function dirHash(dir) {
+  let files = [];
+  try {
+    files = walkFiles(dir).sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+  } catch {
+    return '';
+  }
+  const sha = crypto.createHash('sha256');
+  for (const f of files) {
+    sha.update(f.rel);
+    sha.update('|');
+    sha.update(String(f.size));
+    sha.update('|');
+    try {
+      sha.update(fs.readFileSync(f.abs));
+    } catch {
+      sha.update('<unreadable>');
+    }
+    sha.update('\n');
+  }
+  return sha.digest('hex');
+}
+
+/** 复制整棵目录，跳过备份残留与缓存。 */
+const COPY_IGNORED = /^(__pycache__|node_modules|\.git|\.trash-.*|_trash-.*)$|\.(bak|orig|rej)$|~$/i;
+
+function copyDir(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  let entries = [];
+  try {
+    entries = fs.readdirSync(from, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (COPY_IGNORED.test(e.name)) continue;
+    const src = path.join(from, e.name);
+    const dst = path.join(to, e.name);
+    if (e.isDirectory()) copyDir(src, dst);
+    else if (e.isFile()) {
+      try {
+        fs.copyFileSync(src, dst);
+      } catch {
+        /* 单个文件拷不动不影响整棵树 */
+      }
+    }
+  }
+}
+
+function rmDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    /* 尽力而为 */
+  }
+}
+
+function bytesOfDir(dir) {
+  let n = 0;
+  for (const f of walkFiles(dir)) n += f.size;
+  return n;
+}
+
+/** 人类可读字节数。 */
+export function humanBytes(n) {
+  const v = Number(n) || 0;
+  if (v < 1024) return `${v} B`;
+  if (v < 1024 * 1024) return `${(v / 1024).toFixed(1)} KB`;
+  return `${(v / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/** ISO 时间，取不到返回空串。 */
+function isoOf(ts) {
+  const n = Number(ts);
+  if (!Number.isFinite(n) || n <= 0) return '';
+  try {
+    return new Date(n).toISOString();
+  } catch {
+    return '';
+  }
+}
+
+/* ------------------------------------------------------------ 技能元信息 */
+
+/**
+ * 读一个技能目录的元信息（比 skills.js 的 readSkill 多出「更新时间」与「来源」）。
+ *
+ * @param {string} dir  技能绝对目录
+ * @param {string} name 目录名
+ * @param {{masterRoot?:string, origin?:object}} extra
+ */
+export function readSkillMeta(dir, name, extra = {}) {
+  const skillMd = path.join(dir, 'SKILL.md');
+  const fm = parseFrontMatter(skillMd);
+  let mtime = 0;
+  try {
+    mtime = fs.statSync(skillMd).mtimeMs;
+  } catch {
+    mtime = 0;
+  }
+  const files = walkFiles(dir);
+  const origin = extra.origin && typeof extra.origin === 'object' ? extra.origin : {};
+  const masterRoot = typeof extra.masterRoot === 'string' ? extra.masterRoot : '';
+  const inMaster = masterRoot ? fs.existsSync(path.join(masterRoot, name, 'SKILL.md')) : false;
+
+  return {
+    name: fm.name || name,
+    skill: name,
+    dir,
+    version: fm.version || '',
+    description: fm.description || '',
+    whenToUse: fm.whenToUse || '',
+    hasSkillMd: fs.existsSync(skillMd),
+    mdHash: mdHash(dir),
+    treeHash: dirHash(dir),
+    files: files.length,
+    bytes: files.reduce((n, f) => n + f.size, 0),
+    hasScripts: fs.existsSync(path.join(dir, 'scripts')),
+    hasReferences: fs.existsSync(path.join(dir, 'references')),
+    hasEvals: fs.existsSync(path.join(dir, 'evals')) || fs.existsSync(path.join(dir, 'evals.json')),
+    updatedAt: isoOf(mtime),
+    updatedAtMs: mtime,
+    /** 来源：母版有没有、是不是从别的机器学来的。 */
+    source: {
+      inMaster: inMaster,
+      masterRoot: inMaster ? masterRoot : '',
+      /** 最初从哪台机器的特征本拿到的；本机自产为空。 */
+      firstSeenFrom: typeof origin.firstSeenFrom === 'string' ? origin.firstSeenFrom : '',
+      /** 学习记录：从哪些机器学到过东西。 */
+      learnedFrom: Array.isArray(origin.learnedFrom) ? origin.learnedFrom.slice(0, 12) : [],
+      /** 母版是「本机独属」属性的，就等于只在本机存在。 */
+      mode: typeof origin.mode === 'string' ? origin.mode : '',
+    },
+  };
+}
+
+/** 来源台账的路径（写在自己那一格里，别人也能读到是谁学的）。 */
+export function originFile(config, machineId) {
+  return path.join(mySkillsRoot(config, machineId), ORIGIN_INDEX);
+}
+
+/** 读来源台账：技能名 → { firstSeenFrom, learnedFrom, mode }。 */
+export function readOrigins(config, machineId) {
+  const doc = readJson(originFile(config, machineId));
+  return doc && typeof doc.skills === 'object' && doc.skills ? doc.skills : {};
+}
+
+/** 记一条来源（幂等：重复写同样的值不产生改动）。 */
+export function recordOrigin(config, machineId, name, patch = {}) {
+  const file = originFile(config, machineId);
+  const doc = readJson(file) || { schemaVersion: 1, skills: {} };
+  if (!doc.skills || typeof doc.skills !== 'object') doc.skills = {};
+  const cur = doc.skills[name] && typeof doc.skills[name] === 'object' ? doc.skills[name] : {};
+  const next = { ...cur, ...patch };
+  if (Array.isArray(patch.learnedFrom)) {
+    const set = new Set([...(cur.learnedFrom || []), ...patch.learnedFrom]);
+    next.learnedFrom = [...set].slice(0, 12);
+  }
+  doc.schemaVersion = 1;
+  doc.skills[name] = next;
+  doc.updatedAt = new Date().toISOString();
+  return writeJsonIfChanged(file, doc, ['updatedAt']);
+}
+
+/* ------------------------------------------------------ 把我的技能备份出去 */
+
+/**
+ * 扫本机技能根，写成 `插件库/<本机>/skills/` 一整套。
+ *
+ * 幂等：内容没变的技能不重拷（比对目录指纹），索引没变不重写。
+ * 清理：特征目录里有、本机技能根里已经没有的技能目录会被移进 `_trash-<stamp>`
+ * （不直接删，留着给别的机器最后一次机会读）。
+ *
+ * @param {{config:object, machineId:string, machineHash?:string, machineName?:string,
+ *          localRoot:string, masterRoot?:string, modes?:object, log?:Function,
+ *          stamp?:string}} input
+ */
+export function syncMySkills({
+  config,
+  machineId,
+  machineHash = '',
+  machineName = '',
+  localRoot,
+  masterRoot = '',
+  modes = {},
+  only = null,
+  log,
+  stamp,
+}) {
+  const started = Date.now();
+  const feature = String(machineId || '').trim();
+  const root = mySkillsRoot(config, feature);
+  // 写入前过守门：只允许写自己那一格
+  assertOwnFeaturePath(root, { featuresRoot: libraryRootOf(config), machineId: feature });
+
+  const origins = readOrigins(config, feature);
+  const scanned = scanSkills(localRoot);
+  // `only` 是 skill-scope 判定的「归本插件管」集合：
+  // 只备份归本插件管的技能，市场装的第三方技能不进特征文件夹（既不共享也不优化）。
+  // only 为 null 时退化成「全都备份」（测试与首次迁移用）。
+  const local = new Map();
+  for (const [name, skill] of scanned) {
+    if (only && !only.has(name)) continue;
+    local.set(name, skill);
+  }
+  const excluded = only ? scanned.size - local.size : 0;
+  const items = [];
+  const copied = [];
+  const skipped = [];
+  const errors = [];
+
+  fs.mkdirSync(root, { recursive: true });
+
+  for (const [name, skill] of local) {
+    const srcDir = skill.dir;
+    const dstDir = path.join(root, name);
+    const meta = readSkillMeta(srcDir, name, {
+      masterRoot,
+      origin: { ...(origins[name] || {}), mode: modes[name] || '' },
+    });
+
+    // 已经备份过、且整棵目录指纹一致 → 不重拷，只更新名片里的易变字段
+    const oldCard = readJson(path.join(dstDir, SKILL_CARD));
+    const upToDate = oldCard && oldCard.treeHash === meta.treeHash && fs.existsSync(path.join(dstDir, 'SKILL.md'));
+    if (upToDate) {
+      skipped.push(name);
+    } else {
+      try {
+        rmDir(dstDir);
+        copyDir(srcDir, dstDir);
+        copied.push(name);
+      } catch (err) {
+        errors.push({ name, message: String((err && err.message) || err) });
+        continue;
+      }
+    }
+
+    const card = {
+      schemaVersion: 1,
+      skill: name,
+      name: meta.name,
+      feature,
+      machine: machineName || '',
+      machineId: feature,
+      machineHash: machineHash || '',
+      description: meta.description,
+      whenToUse: meta.whenToUse,
+      version: meta.version,
+      /** 技能更新时间：取 SKILL.md 的落盘时间，只作展示，判同一律看指纹。 */
+      updatedAt: meta.updatedAt,
+      contentHash: meta.mdHash,
+      treeHash: meta.treeHash,
+      files: meta.files,
+      bytes: meta.bytes,
+      assets: {
+        scripts: meta.hasScripts,
+        references: meta.hasReferences,
+        evals: meta.hasEvals,
+      },
+      source: {
+        type: meta.source.inMaster ? 'master' : 'local',
+        inMaster: meta.source.inMaster,
+        masterRoot: meta.source.masterRoot,
+        mode: meta.source.mode,
+        firstSeenFrom: meta.source.firstSeenFrom,
+        learnedFrom: meta.source.learnedFrom,
+      },
+      note:
+        '本目录由 ygc-dsh-sync 的「技能共享」自动生成：整棵技能目录的备份 + 这张名片。' +
+        '目录名即技能名；contentHash 是 SKILL.md 的 sha256，treeHash 是整棵目录的指纹；' +
+        'updatedAt 只是落盘时间，判同一律看指纹。',
+    };
+    writeJsonIfChanged(path.join(dstDir, SKILL_CARD), card);
+    items.push(card);
+  }
+
+  // 本机已经没有的技能（含被 skill-scope 划出去的第三方）：移进回收目录，不直删。
+  // 移出的是**自己格子里的旧副本**，不碰任何别人的特征本。
+  const trashStamp = stamp || makeStamp();
+  const trashed = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory());
+  } catch {
+    entries = [];
+  }
+  for (const e of entries) {
+    if (!local.has(e.name)) {
+      const from = path.join(root, e.name);
+      const to = path.join(root, `.trash-${trashStamp}`, e.name);
+      try {
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        fs.renameSync(from, to);
+        trashed.push(e.name);
+      } catch {
+        /* 挪不动就留着，不影响索引 */
+      }
+    }
+  }
+
+  items.sort((a, b) => a.skill.localeCompare(b.skill));
+  const index = {
+    schemaVersion: 1,
+    feature,
+    machine: machineName || '',
+    machineId: feature,
+    machineHash: machineHash || '',
+    platform: `${process.platform}-${process.arch}`,
+    localRoot,
+    generatedAt: new Date().toISOString(),
+    counts: {
+      total: items.length,
+      withScripts: items.filter((x) => x.assets.scripts).length,
+      withReferences: items.filter((x) => x.assets.references).length,
+      withEvals: items.filter((x) => x.assets.evals).length,
+      bytes: items.reduce((n, x) => n + x.bytes, 0),
+    },
+    policy: {
+      /** 技能整棵备份（含 scripts/references），与插件侧的「只存清单」不同：技能没有 registry。 */
+      storesSkillTree: true,
+      storesSourceCode: true,
+      /** 同名不同内容不自动覆盖，交给学习台账。 */
+      sameNameConflict: 'learn',
+      /** 索引里带的字段：说明、来源、更新时间、内容指纹。 */
+      fields: ['description', 'source', 'updatedAt', 'contentHash', 'treeHash'],
+      note: '技能共享是整棵目录备份；判同一律看 contentHash/treeHash，不看时间戳。',
+    },
+    skills: items,
+  };
+  const indexChanged = writeJsonIfChanged(path.join(root, SKILLS_INDEX), index);
+
+  const lines = [
+    '# 本机技能索引（自动生成）',
+    '',
+    '> 由 ygc-dsh-sync 的「技能共享」生成。目录名即本机标识，与插件清单、会话同步共用。',
+    '> 每个技能目录里除了技能本体，还有一张 `SKILL-CARD.json`：说明、来源、更新时间、内容指纹。',
+    '> 判同一律看 `contentHash`（SKILL.md 的 sha256）与 `treeHash`（整棵目录），**不看时间戳**。',
+    '> 同名不同内容**不会被覆盖**：差异会进 `SKILL-LEARNINGS.md`，由本机评估后写学习建议，',
+    '> 别的机器读那份文件也能参考（学到什么、为什么、草稿落在哪）。',
+    `> 生成时间：${index.generatedAt}`,
+    `> 技能 ${index.counts.total} 个 · ${humanBytes(index.counts.bytes)} · 带脚本 ${index.counts.withScripts} 个 · 带评测 ${index.counts.withEvals} 个`,
+    '',
+    '| 技能 | 版本 | 更新时间 | 来源 | 资产 | 说明 |',
+    '|---|---|---|---|---|---|',
+    ...items.map((x) => {
+      const assets = [x.assets.scripts ? 'scripts' : '', x.assets.references ? 'references' : '', x.assets.evals ? 'evals' : '']
+        .filter(Boolean)
+        .join(' / ');
+      const src = x.source.type === 'master' ? '母版' : '本机独属';
+      const from = x.source.firstSeenFrom ? ` · 学自 ${x.source.firstSeenFrom}` : '';
+      const desc = String(x.description || '').replace(/\|/g, '/').slice(0, 90);
+      return `| \`${x.skill}\` | ${x.version || '-'} | ${x.updatedAt || '-'} | ${src}${from} | ${assets || '-'} | ${desc || '-'} |`;
+    }),
+    '',
+  ];
+  if (trashed.length) {
+    lines.push('## 本轮移出的技能', '', ...trashed.map((n) => `- \`${n}\`（本机已没有，移进 \`.trash-${trashStamp}/\`）`), '');
+  }
+  if (errors.length) {
+    lines.push('## 备份失败', '', ...errors.map((e) => `- \`${e.name}\`：${e.message}`), '');
+  }
+  const mdChanged = writeTextIfChanged(path.join(root, SKILLS_INDEX_MD), lines.join('\n'));
+
+  log?.(
+    `技能共享：${feature} → ${items.length} 个技能（新备份 ${copied.length}、未变 ${skipped.length}` +
+      `${trashed.length ? `、移出 ${trashed.length}` : ''}${errors.length ? `、失败 ${errors.length}` : ''}）`,
+  );
+
+  return {
+    ok: true,
+    feature,
+    root,
+    ms: Date.now() - started,
+    indexChanged,
+    mdChanged,
+    copied,
+    skipped,
+    trashed,
+    excluded,
+    errors,
+    counts: index.counts,
+    index,
+  };
+}
+
+/** 生成时间戳串（与 skills.js 的 makeStamp 同格式）。 */
+export function makeStamp(date = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}-${p(date.getHours())}${p(
+    date.getMinutes(),
+  )}${p(date.getSeconds())}`;
+}
+
+/* ------------------------------------------------------ 扫别人的技能格 */
+
+/**
+ * 扫全部特征文件夹的技能层，合并成「别人有什么」。
+ *
+ * 返回里每个技能带 `peer` 数组（哪几台机器有、指纹分别是什么），
+ * 本机技能根里的同名技能用 `mine` 标出状态：
+ *   missing  本机没有 → 可直接拉取
+ *   same     内容一致 → 什么都不用做
+ *   differ   内容不同 → 交给学习评估
+ *
+ * @param {{config:object, machineId:string, localRoot:string, masterRoot?:string}} input
+ */
+export function collectSharedSkills({ config, machineId, localRoot, masterRoot = '', only = null, thirdParty = null }) {
+  const mine = String(machineId || '').trim();
+  const base = libraryRootOf(config);
+  const scannedLocal = scanSkills(localRoot);
+  // 只把「归本插件管」的技能算进本机现状：第三方（市场装的）不参与比对，
+  // 否则会出现「别人也装了同一个市场技能、内容不同 → 触发学习」这种无意义动作。
+  const local = new Map();
+  for (const [name, skill] of scannedLocal) {
+    if (only && !only.has(name)) continue;
+    local.set(name, skill);
+  }
+  const sources = [];
+  const warnings = [];
+  const merged = new Map();
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory());
+  } catch {
+    entries = [];
+  }
+
+  for (const entry of entries) {
+    const feature = entry.name;
+    const dir = path.join(base, feature, SKILLS_DIR);
+    const index = readJson(path.join(dir, SKILLS_INDEX));
+    let skillDirs = [];
+    try {
+      skillDirs = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => e.name);
+    } catch {
+      skillDirs = [];
+    }
+    if (!index && !skillDirs.length) {
+      // 这个特征本没有技能层（对方还是旧版插件）：不算错，只提示一句
+      if (feature !== mine) warnings.push(`${feature}：还没有技能共享目录，跳过`);
+      continue;
+    }
+
+    const isMine = feature === mine;
+    sources.push({
+      feature,
+      mine: isMine,
+      machine: (index && index.machine) || '',
+      generatedAt: (index && index.generatedAt) || '',
+      total: Array.isArray(index && index.skills) ? index.skills.length : skillDirs.length,
+      bytes: (index && index.counts && index.counts.bytes) || 0,
+    });
+
+    for (const skillName of skillDirs) {
+      // **不要用 only 过滤别人的格子**。only 只回答「本机该不该管这个技能」，
+      // 拿它过滤对方的目录会让本机永远看不见新技能（对方独有的一律被滤掉，拉取永远为 0）。
+      // 第三方过滤放在拉取那一步：市场台账里有的技能，不往本机拉（见 applySkillPull）。
+      const skillDir = path.join(dir, skillName);
+      if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) continue;
+      const card = readJson(path.join(skillDir, SKILL_CARD)) || {};
+      // 名片可能过期（对方手改过文件）。指纹一律现算，名片只用来取说明与来源。
+      const md = mdHash(skillDir);
+      const tree = dirHash(skillDir);
+      const rec =
+        merged.get(skillName) ||
+        {
+          name: skillName,
+          description: typeof card.description === 'string' ? card.description : '',
+          version: typeof card.version === 'string' ? card.version : '',
+          updatedAt: typeof card.updatedAt === 'string' ? card.updatedAt : '',
+          source: card.source && typeof card.source === 'object' ? card.source : {},
+          peers: [],
+          counts: { peers: 0, distinctHashes: 0 },
+        };
+      rec.peers.push({
+        feature,
+        machine: typeof card.machine === 'string' ? card.machine : '',
+        dir: skillDir,
+        mdHash: md,
+        treeHash: tree,
+        descLength: String(card.description || '').length,
+      });
+      merged.set(skillName, rec);
+    }
+  }
+
+  for (const rec of merged.values()) {
+    // 本机没有的话，还要判断「是不是市场第三方」：第三方的技能不拉、不优化。
+    // 判据在这里注入（thirdParty 集合由编排层传进来），不在这里重读台账。
+    const mineRec = local.get(rec.name);
+    rec.mineHash = mineRec ? mineRec.contentHash : '';
+    rec.mineTree = mineRec ? mineRec.treeHash : '';
+    rec.mineDir = mineRec ? mineRec.dir : '';
+    // 市场第三方：本机没有也不要，别把市场的技能顺着共享盘扩散过来
+    rec.thirdParty = Boolean(thirdParty && thirdParty.has(rec.name));
+    rec.status = rec.thirdParty ? 'third-party' : !mineRec ? 'missing' : mineRec.treeHash === rec.peers[0].treeHash ? 'same' : 'differ';
+    // 只要有一台机器的指纹与本机不同，就算 differ（别的机器可能是同一版）
+    if (mineRec && rec.peers.some((p) => p.treeHash !== mineRec.treeHash)) rec.status = 'differ';
+    const hashes = new Set(rec.peers.map((p) => p.treeHash));
+    rec.counts.peers = rec.peers.length;
+    rec.counts.distinctHashes = hashes.size;
+  }
+
+  const all = [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return {
+    mine,
+    sources: sources.sort((a, b) => a.feature.localeCompare(b.feature)),
+    warnings,
+    skills: all,
+    missing: all.filter((x) => x.status === 'missing'),
+    same: all.filter((x) => x.status === 'same'),
+    differ: all.filter((x) => x.status === 'differ'),
+    thirdParty: all.filter((x) => x.thirdParty),
+    localCount: local.size,
+  };
+}
+
+/* --------------------------------------------------------- 拉取缺失技能 */
+
+/**
+ * 把本机没有的技能从别人的格子里拉到本机技能根。
+ *
+ * 只拉 missing。differ 一律不碰——那是学习评估的事，覆盖就等于用别人的版本
+ * 冲掉本机可能更好的版本，而这里没有可信的新旧判据。
+ *
+ * 拉取前记来源（firstSeenFrom），这样名片和台账里都能看出「这个技能是从哪学的」。
+ *
+ * @param {{items:Array, localRoot:string, config:object, machineId:string, stamp?:string}} input
+ */
+export function applySkillPull({ items = [], localRoot, config, machineId, stamp = makeStamp() }) {
+  const pulled = [];
+  const errors = [];
+  for (const item of items) {
+    const peer = (item.peers || [])[0];
+    if (!peer) {
+      errors.push({ name: item.name, message: '没有可用的来源特征本' });
+      continue;
+    }
+    const dst = path.join(localRoot, item.name);
+    try {
+      if (fs.existsSync(dst)) {
+        // 说好只拉 missing 的，走到了这里说明磁盘变了，保守跳过
+        errors.push({ name: item.name, message: '本机已有同名技能，跳过（不覆盖）' });
+        continue;
+      }
+      copyDir(peer.dir, dst);
+      // 名片是共享层的东西，不该污染本机技能目录
+      try {
+        fs.rmSync(path.join(dst, SKILL_CARD), { force: true });
+      } catch {
+        /* 删不掉也不影响用 */
+      }
+      if (config && machineId) {
+        recordOrigin(config, machineId, item.name, { firstSeenFrom: peer.feature });
+      }
+      pulled.push({ name: item.name, from: peer.feature, machine: peer.machine || '', mdHash: peer.mdHash });
+    } catch (err) {
+      rmDir(dst);
+      errors.push({ name: item.name, message: String((err && err.message) || err) });
+    }
+  }
+  return { pulled, errors, stamp };
+}
+
+/* ------------------------------------------------------------ 面板快照 */
+
+/** 面板用：我的技能层现状 + 来源列表 + 缺失/差异摘要（只读，扫盘）。 */
+export function skillShareSnapshot({ config, machineId, localRoot, masterRoot = '', only = null }) {
+  let myRoot = '';
+  let myIndex = null;
+  let myError = '';
+  try {
+    myRoot = mySkillsRoot(config, machineId);
+    myIndex = readJson(path.join(myRoot, SKILLS_INDEX)) || null;
+  } catch (err) {
+    myError = String((err && err.message) || err);
+  }
+  const collected = collectSharedSkills({ config, machineId, localRoot, masterRoot, only });
+  const learnings = readJson(path.join(myRoot, LEARNINGS_INDEX)) || null;
+  return {
+    root: myRoot,
+    libraryRoot: libraryRootOf(config),
+    myFeature: String(machineId || ''),
+    index: myIndex
+      ? {
+          generatedAt: myIndex.generatedAt,
+          counts: myIndex.counts,
+          // 面板只列名字，不塞整份索引
+          skills: (myIndex.skills || []).map((x) => ({
+            skill: x.skill,
+            version: x.version,
+            updatedAt: x.updatedAt,
+            sourceType: x.source && x.source.type,
+            firstSeenFrom: x.source && x.source.firstSeenFrom,
+          })),
+        }
+      : null,
+    error: myError,
+    sources: collected.sources,
+    warnings: collected.warnings,
+    counts: {
+      local: collected.localCount,
+      peers: collected.sources.length,
+      missing: collected.missing.length,
+      same: collected.same.length,
+      differ: collected.differ.length,
+    },
+    missing: collected.missing.map((x) => ({ name: x.name, from: x.peers[0] && x.peers[0].feature, version: x.version })),
+    differ: collected.differ.map((x) => ({
+      name: x.name,
+      peers: x.peers.map((p) => p.feature),
+      distinctHashes: x.counts.distinctHashes,
+    })),
+    learnings: learnings
+      ? {
+          generatedAt: learnings.generatedAt,
+          counts: learnings.counts,
+          items: (learnings.items || []).slice(0, 30),
+        }
+      : null,
+  };
+}