ygc-dsh-sync 1.2.2 → 1.3.0

package/lib/skill-learn.js

@@ -0,0 +1,1115 @@
+/**
+ * 技能学习：把「别的机器有同名的技能，但内容与本机不一样」这件事，
+ * 从「覆盖 / 不覆盖」的二选一，升级成一次**有人负责的评估**。
+ *
+ * 为什么要有这一层：
+ *   - 技能的价值不在正文长度，而在它有没有把某类工况、某个坑写进去。
+ *     两台机器各自踩过不同的坑，简单覆盖一定丢掉一边。
+ *   - 但也不能「差异一律等人工」：那样台账会积一堆待办，最后没人看。
+ *     所以分两段：机械判定能定的直接给出结论，只有真正需要判断的才叫模型。
+ *
+ * 判定顺序（便宜的先跑）：
+ *   1. 指纹相同                     → same，什么都不做
+ *   2. 一侧是另一侧的严格超集（章节 + 行数都在包含关系里）
+ *                                   → 直接取超集那一侧，不叫模型
+ *   3. 双方各有对方没有的章节        → 进模型评估（可能是合并 / 补全 / 删除）
+ *   4. 模型不可用                    → 只出确定性结论 + 差异清单，标 manual
+ *
+ * 优化类型（用户定的，不限于此）：
+ *   merge     合并精炼：两个版本各有一半，合成一份更准的（允许比任一侧短）
+ *   condense  精炼冗余：内容重复、篇幅虚胖，压短同时保住可执行层
+ *   enrich    补全工况：把对方踩过的工况 / 触发条件补进来
+ *   pitfalls  增加踩坑经验：把对方的 Pitfalls 并进本机
+ *   revise    修订错误技能：**改正**会误导模型的错误做法（错命令 / 过时 API /
+ *             引用不存在的资源），产出一份修正后的正文；整条作废时标
+ *             `deprecate`，正文换成停用声明，不误删别人的历史记录
+ *   adopt     采用对方版本：本机版本明显更差
+ *   keep      保留本机：对方版本更差，只记录理由
+ *
+ * 落点：所有评估结果写进 `插件库/<本机>/skills/SKILL-LEARNINGS.{json,md}`，
+ * 草稿落在 `插件库/<本机>/skills/learn-drafts/<技能名>/SKILL.md`。
+ * 别的机器读那份说明文件就能看到「谁、因为什么、怎么改的」，不必重跑一次评估。
+ *
+ * **写边界（硬）**：本模块只写本机那一格（`插件库/<本机标识>/skills/**`）
+ * 与本机技能根（`~/.agents/skills/**`）。别人的特征文件夹**全程只读**：
+ * 不写、不改、不删、不移动。任何「要不要覆盖对方」的念头都在这里被排除，
+ * 对方的版本永远是输入，不是输出。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import {
+  DRAFTS_DIR,
+  LEARNINGS_INDEX,
+  LEARNINGS_INDEX_MD,
+  SKILLS_DIR,
+  mySkillsRoot,
+  readSkillMeta,
+  recordOrigin,
+} from './skillshare.js';
+import { assertOwnFeaturePath, featuresDir } from './plugins.js';
+import { diffSummary, parseFrontMatter, walkFiles } from './skills.js';
+
+/** 一条学习单最多允许的模型调用次数（含一次格式纠正重试）。 */
+const MAX_MODEL_CALLS = 2;
+/** 送进模型的单侧正文上限：超了截断并明确标注，不假装看全了。 */
+const MAX_SIDE_CHARS = 24000;
+/** 合并结果的硬上限行数与相对上限。 */
+const MAX_MERGED_LINES = 900;
+/** 认定「冗余技能」的描述相似度门槛。 */
+const REDUNDANT_SIMILARITY = 0.42;
+
+export const LEARN_LABEL = {
+  merge: '合并精炼',
+  condense: '精炼冗余',
+  enrich: '补全工况',
+  pitfalls: '增加踩坑经验',
+  revise: '修订错误技能',
+  deprecate: '停用（作废）',
+  adopt: '采用对方版本',
+  keep: '保留本机版本',
+  manual: '等人工判断',
+};
+
+/* -------------------------------------------------------------- 小工具 */
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function writeJson(file, value) {
+  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);
+}
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
+}
+
+/** 取 H2/H3 标题集合，用于判断章节包含关系。 */
+export function headingsOf(text) {
+  const out = new Set();
+  for (const m of String(text || '').matchAll(/^#{2,3}\s+(.+)$/gm)) {
+    out.add(m[1].replace(/\s+/g, ' ').trim());
+  }
+  return out;
+}
+
+/** 机械特征：给判定与模型都用同一份事实。 */
+export function profileOf(text, dir) {
+  const t = String(text || '');
+  const lines = t ? t.split(/\r?\n/).length : 0;
+  const heads = headingsOf(t);
+  const fm = dir ? parseFrontMatter(path.join(dir, 'SKILL.md')) : {};
+  const fences = (t.match(/^```/gm) || []).length;
+  const codeLines = (t.match(/^\s*(\$\s|\w+\s+--|node |python |pnpm |npm |git )/gm) || []).length;
+  const numbers = (t.match(/\b\d+(\.\d+)?\s*(ms|s|秒|分钟|行|字|%|MB|GB|pt|px)\b/g) || []).length;
+  return {
+    lines,
+    chars: t.length,
+    bytes: Buffer.byteLength(t, 'utf8'),
+    headings: [...heads].sort(),
+    fences,
+    codeLines,
+    numbers,
+    description: fm.description || '',
+    version: fm.version || '',
+    hasPitfalls: /^##+\s*(Pitfalls|常见错误)/m.test(t),
+    hasVerification: /^##+\s*(Verification|验收)/m.test(t),
+    files: dir ? walkFiles(dir).length : 0,
+  };
+}
+
+/**
+ * 机械判「一侧是不是另一侧的超集」。
+ *
+ * 只看两件事：章节集合的包含关系，与行数不短于对方。两条都成立才算，
+ * 因为「章节全有但删掉了一大段」不是超集，那是精炼过。
+ *
+ * @returns {'master'|'peer'|'neither'}
+ */
+export function supersetOf(aText, bText) {
+  const a = headingsOf(aText);
+  const b = headingsOf(bText);
+  const aLines = aText ? aText.split(/\r?\n/).length : 0;
+  const bLines = bText ? bText.split(/\r?\n/).length : 0;
+  const aHasAllB = [...b].every((h) => a.has(h));
+  const bHasAllA = [...a].every((h) => b.has(h));
+  if (aHasAllB && !bHasAllA && aLines >= bLines) return 'master';
+  if (bHasAllA && !aHasAllB && bLines >= aLines) return 'peer';
+  return 'neither';
+}
+
+/* ------------------------------------------------------- 冗余技能发现 */
+
+const STOP_WORDS = new Set([
+  'the','and','for','with','that','this','from','when','use','used','user','users','skill','skills',
+  'dsh','本机','用户','技能','使用','以及','可以','需要','这个','那个','时候','问题','进行','一个',
+]);
+
+function tokensOf(text) {
+  const raw = String(text || '')
+    .toLowerCase()
+    .split(/[^a-z0-9\u4e00-\u9fa5-]+/)
+    .filter(Boolean);
+  const out = new Set();
+  for (const t of raw) {
+    if (t.length < 2 || STOP_WORDS.has(t)) continue;
+    out.add(t);
+  }
+  return out;
+}
+
+function jaccard(a, b) {
+  if (!a.size || !b.size) return 0;
+  let inter = 0;
+  for (const x of a) if (b.has(x)) inter += 1;
+  return inter / (a.size + b.size - inter);
+}
+
+/**
+ * 找出「像是同一件事」的多个技能（合并精炼的候选）。
+ *
+ * 判据：描述词的 Jaccard 相似度 >= 门槛，或去掉前缀后名字相同
+ * （`comfyui-a-b` 与 `comfyui-a-c` 这种不算，必须去掉 `-` 后前两段一致）。
+ *
+ * 只产出候选，不做任何合并：合并是不可逆的，必须有人点头。
+ */
+export function findRedundantPairs(localSkills, { threshold = REDUNDANT_SIMILARITY } = {}) {
+  const list = [...localSkills.values()].map((s) => ({
+    name: s.name,
+    dirName: s.dirName,
+    tokens: tokensOf(`${s.description} ${s.name.replace(/-/g, ' ')}`),
+    desc: s.description || '',
+    lines: s.text ? s.text.split(/\r?\n/).length : 0,
+  }));
+  const pairs = [];
+  for (let i = 0; i < list.length; i += 1) {
+    for (let j = i + 1; j < list.length; j += 1) {
+      const sim = jaccard(list[i].tokens, list[j].tokens);
+      if (sim < threshold) continue;
+      pairs.push({
+        a: list[i].name,
+        b: list[j].name,
+        similarity: Number(sim.toFixed(3)),
+        lines: [list[i].lines, list[j].lines],
+        action: 'merge',
+        reason: `描述词重合理度 ${sim.toFixed(2)}（门槛 ${threshold}），像同一件事的两个版本`,
+      });
+    }
+  }
+  return pairs.sort((x, y) => y.similarity - x.similarity).slice(0, 20);
+}
+
+/* ------------------------------------------------------------ 提示词 */
+
+/**
+ * 评估用的 system。
+ *
+ * 与 mnemon 起草段同一条教训：**不要把正文塞进 JSON 字符串**。正文里有代码块、
+ * 引号、反斜杠，转义必坏。所以拆成两块——短结论用 json 围栏，长正文用 markdown 围栏。
+ */
+export const LEARN_SYSTEM = [
+  '你是技能（SKILL.md）评审。你的任务不是夸，而是判断两份同名技能该不该合。',
+  '',
+  '输出必须分成两块，顺序固定：',
+  '第一块：一个 ```json 围栏，只含这些键：',
+  '{',
+  '  "action": "merge|condense|enrich|pitfalls|revise|deprecate|adopt|keep",',
+  '  "confidence": 0.0 到 1.0,',
+  '  "base": "mine|peer",',
+  '  "reason": "不超过 200 字，说清判据：哪一侧多了什么、为什么这样处理",',
+  '  "evidence": ["对方版本里本机没有的具体一条", "..."],',
+  '  "dropped": ["合并后会删掉的章节或做法", "..."]',
+  '}',
+  '第二块：当 action 是 merge / condense / enrich / pitfalls / revise / adopt 时，',
+  '再给一个 ```markdown 围栏，里面是可直接落盘的 SKILL.md 全文；',
+  'action 是 keep 或 deprecate 时不输出第二块。',
+  '',
+  '判定规则（按顺序套，不许跳）：',
+  '1. 一侧做的事会**误导**模型（错误命令、过时 API、把不存在的文件当资源）→ 错的必须被改正，不能原样保留：',
+  '   本机一侧有错 → action=revise，正文写成改正后的版本（其它正确内容保留，只替换掉错的那部分）；',
+  '   错只在对方一侧 → action=keep，并在 reason 与 evidence 写清哪条错、应该怎么改，供对方修订自己的副本。',
+  '2. 双方各有对方没有的**工况/前提条件**（什么情况下适用、什么情况下不要用）→ enrich 或 merge。',
+  '3. 双方各有对方没有的**踩坑经验**（Pitfalls）→ pitfalls 或 merge，把两边都保住。',
+  '4. 内容大量重复、正文虚胖、可执行层（命令/数值/模板）没增加 → condense。',
+  '5. 只有「改也没意义、整条技能本就不该存在」才 action=deprecate，reason 写清为什么，不要输出正文；',
+  '   能改就先改：能定位到错在哪就一律 revise，不要用 deprecate 回避修订。',
+  '6. 只多出无关紧要的措辞 → keep。',
+  '',
+  '合并正文的硬要求：',
+  '- 保留 frontmatter，`name:` 与给定技能名逐字相同；description 60 到 400 字，要写进两边新增的触发场景。',
+  '- 必须有 `## Pitfalls`（或 `## 常见错误`）与 `## Verification`（或 `## 验收`）两节，两边原有的条目一条都不许丢。',
+  '- 不许出现长破折号「—」「–」，用逗号或冒号。',
+  '- 代码围栏成对闭合。',
+  '- 行数不得超过两版之和；合并后不许比更长的那一版多出 20%。',
+  '- 只写这一个文件，不要引用不存在的 references/ 或 scripts/ 文件；两边原本就有的资源目录可以继续引用。',
+].join('\n');
+
+/**
+ * 组评估提示词。
+ *
+ * @param {{name:string, mineText:string, peerText:string, mineProfile:object,
+ *          peerProfile:object, peerFeature:string, peerMachine:string,
+ *          peerAssets:object, mineAssets:object, redundant?:Array}} input
+ */
+export function buildLearnPrompt(input) {
+  const tr = (s, cap = MAX_SIDE_CHARS) => {
+    const t = String(s || '');
+    if (t.length <= cap) return { text: t, truncated: false };
+    return { text: `${t.slice(0, cap)}\n\n[以上被截断：原文 ${t.length} 字，只给了前 ${cap} 字]`, truncated: true };
+  };
+  const mine = tr(input.mineText);
+  const peer = tr(input.peerText);
+  const line = (label, v) => `${label}：${v}`;
+  const L = [];
+  L.push(`技能名（合并正文的 frontmatter name 必须逐字写成这个）：${input.name}`);
+  L.push('');
+  L.push('## 机械比对（这两行是真实现算，不要推翻，只能解释）');
+  L.push(line('左（本机 mine）', ``));
+  L.push(`  行 ${input.mineProfile.lines} · 字 ${input.mineProfile.chars} · 命令行 ${input.mineProfile.codeLines} · 数值 ${input.mineProfile.numbers} · Pitfalls ${input.mineProfile.hasPitfalls ? '有' : '无'} · Verification ${input.mineProfile.hasVerification ? '有' : '无'}`);
+  L.push(`  章节：${input.mineProfile.headings.join(' / ') || '（无）'}`);
+  L.push(`  资产：${input.mineAssets.scripts ? 'scripts ' : ''}${input.mineAssets.references ? 'references ' : ''}${input.mineAssets.evals ? 'evals' : ''}${input.mineAssets.scripts || input.mineAssets.references || input.mineAssets.evals ? '' : '（无）'}`);
+  L.push(line('右（对方 peer）', `${input.peerFeature}${input.peerMachine ? ` · ${input.peerMachine}` : ''}`));
+  L.push(`  行 ${input.peerProfile.lines} · 字 ${input.peerProfile.chars} · 命令行 ${input.peerProfile.codeLines} · 数值 ${input.peerProfile.numbers} · Pitfalls ${input.peerProfile.hasPitfalls ? '有' : '无'} · Verification ${input.peerProfile.hasVerification ? '有' : '无'}`);
+  L.push(`  章节：${input.peerProfile.headings.join(' / ') || '（无）'}`);
+  L.push(`  资产：${input.peerAssets.scripts ? 'scripts ' : ''}${input.peerAssets.references ? 'references ' : ''}${input.peerAssets.evals ? 'evals' : ''}${input.peerAssets.scripts || input.peerAssets.references || input.peerAssets.evals ? '' : '（无）'}`);
+  const onlyMine = input.mineProfile.headings.filter((h) => !input.peerProfile.headings.includes(h));
+  const onlyPeer = input.peerProfile.headings.filter((h) => !input.mineProfile.headings.includes(h));
+  L.push(`  只有本机有的章节：${onlyMine.join(' / ') || '（无）'}`);
+  L.push(`  只有对方有的章节：${onlyPeer.join(' / ') || '（无）'}`);
+  L.push(`  文本差异摘要：${input.diff || '（无）'}`);
+  if (Array.isArray(input.redundant) && input.redundant.length) {
+    L.push('');
+    L.push('## 与本机其他技能的重合（合并精炼的候选，酌情在 reason 里提一句）');
+    for (const r of input.redundant.slice(0, 5)) {
+      L.push(`- \`${r.a}\` 与 \`${r.b}\` 描述重合理度 ${r.similarity}：${r.reason}`);
+    }
+  }
+  L.push('');
+  L.push('## 左：本机（mine）SKILL.md 原文');
+  L.push('```markdown');
+  L.push(mine.text || '（空）');
+  L.push('```');
+  L.push('');
+  L.push('## 右：对方（peer）SKILL.md 原文');
+  L.push('```markdown');
+  L.push(peer.text || '（空）');
+  L.push('```');
+  L.push('');
+  L.push('现在给出结论。先 json 围栏，需要给正文时再跟一个 markdown 围栏。');
+  return L.join('\n');
+}
+
+/* ------------------------------------------------------------ 解析 */
+
+/**
+ * 从模型回复里切出「可落盘的 SKILL.md 正文」。
+ *
+ * **不能用「第一个 ``` 到下一个 ```」那种非贪婪匹配**：SKILL.md 正文里本来就有
+ * 代码块（```bash / ```json），非贪婪一碰到内层围栏就截断，正文只剩半个文件，
+ * 后面的机械审核会以「缺 Pitfalls / 缺 Verification」拒掉——本机实测踩过这个坑。
+ *
+ * 正确做法：找到起始围栏，取到**最后一个**闭合围栏（或整段结尾），把中间的
+ * 内层围栏原样保留。
+ *
+ * 兼容三种形态：
+ *   1. ```markdown 围栏，内容以 `---` 起手
+ *   2. 任意语言标记的围栏，内容含 `name:`
+ *   3. 整段回复本身就是 SKILL.md（没有围栏）
+ *
+ * @param {string} raw 模型原始回复
+ * @returns {string} 正文；切不出来返回空串
+ */
+export function extractSkillMarkdown(raw) {
+  const text = String(raw || '');
+  if (!text.trim()) return '';
+
+  // 1. 所有可能的起始围栏位置（带语言标记或不带）
+  const openRe = /^[ \t]*```[A-Za-z0-9_-]*[ \t]*\r?\n/gm;
+  const starts = [];
+  for (const m of text.matchAll(openRe)) starts.push(m.index + m[0].length);
+
+  for (const from of starts) {
+    const rest = text.slice(from);
+    if (!/^\s*---\s*\r?\n/.test(rest)) continue;
+    // 取到最后一个闭合围栏（行首的 ```，其后到行尾没有别的内容）
+    const closeRe = /^[ \t]*```[ \t]*$/gm;
+    let last = -1;
+    for (const c of rest.matchAll(closeRe)) last = c.index;
+    const body = (last >= 0 ? rest.slice(0, last) : rest).replace(/\s+$/, '');
+    if (/^name\s*:/m.test(body)) return body;
+  }
+
+  // 2. 整段就是正文
+  if (/^\s*---\s*\r?\n/.test(text) && /^name\s*:/m.test(text)) return text.trim();
+  return '';
+}
+
+const ACTIONS = new Set(['merge', 'condense', 'enrich', 'pitfalls', 'revise', 'deprecate', 'adopt', 'keep']);
+
+/**
+ * 从模型回复里取出结论 + 正文。
+ *
+ * 兼容：
+ *   - 有 json 围栏 → 取结论；没 json 围栏但整段是 JSON → 也算
+ *   - markdown 围栏里以 `---` 开头的 → 正文
+ *   - 正文里带了 json（模型把结论塞进正文前后的 prose）→ 用 `name:` + `## Pitfalls` 兜底判
+ */
+export function parseLearnReply(text) {
+  const raw = String(text || '');
+  const out = { action: '', confidence: 0, base: '', reason: '', evidence: [], dropped: [], content: '', form: '' };
+
+  const jsonBlocks = [...raw.matchAll(/```(?:json|JSON)\s*\r?\n([\s\S]*?)```/g)].map((m) => m[1].trim());
+  const candidates = jsonBlocks.length ? jsonBlocks : [];
+  // 没有围栏但整段以 { 开头也试一次
+  const whole = raw.trim();
+  if (!candidates.length && whole.startsWith('{')) candidates.push(whole);
+
+  for (const c of candidates) {
+    try {
+      const v = JSON.parse(c);
+      if (!v || typeof v !== 'object') continue;
+      if (typeof v.action === 'string' && ACTIONS.has(v.action.trim())) out.action = v.action.trim();
+      const conf = Number(v.confidence);
+      if (Number.isFinite(conf)) out.confidence = Math.max(0, Math.min(1, conf));
+      if (v.base === 'mine' || v.base === 'peer') out.base = v.base;
+      if (typeof v.reason === 'string') out.reason = v.reason.trim().slice(0, 1200);
+      if (Array.isArray(v.evidence)) out.evidence = v.evidence.filter((x) => typeof x === 'string').slice(0, 20);
+      if (Array.isArray(v.dropped)) out.dropped = v.dropped.filter((x) => typeof x === 'string').slice(0, 20);
+      out.form = 'json';
+      break;
+    } catch {
+      /* 坏 JSON 继续找下一个 */
+    }
+  }
+
+  // 正文：走共用的切分器（内层代码块不会被当成结束围栏）
+  out.content = extractSkillMarkdown(raw);
+  if (out.content) out.form = out.form ? `${out.form}+markdown` : 'markdown';
+  return out;
+}
+
+/* ------------------------------------------------------- 合并结果审核 */
+
+/**
+ * 审核一份合并后的 SKILL.md。
+ *
+ * 与 mnemon 的 auditDraftFor 不同：这里**允许比原件短**（精炼是合法动作），
+ * 但不允许丢可执行层、不允许丢两侧都有的 Pitfalls 条目、不允许超出硬上限。
+ *
+ * @param {{text:string, name:string, mineText:string, peerText:string, action:string}} input
+ */
+export function auditLearning({ text, name, mineText, peerText, action, allowShorter = false }) {
+  const problems = [];
+  const info = {};
+  if (typeof text !== 'string' || !text.trim()) {
+    return { ok: false, problems: ['合并正文为空'], info };
+  }
+  info.lines = text.split(/\r?\n/).length;
+  info.chars = text.length;
+
+  let body = text;
+  if (body.charCodeAt(0) === 0xfeff) body = body.slice(1);
+  const fm = body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) problems.push('没有 frontmatter');
+  else {
+    const kv = {};
+    for (const l of fm[1].split(/\r?\n/)) {
+      const m = l.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+      if (!m) continue;
+      let v = m[2].trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+      kv[m[1]] = v;
+    }
+    if (kv.name !== name) problems.push(`frontmatter name=${kv.name || '(空)'} 与技能名 ${name} 不一致`);
+    const desc = kv.description || '';
+    info.description = desc.length;
+    if (!desc) problems.push('缺 description');
+    else if (desc.length < 60) problems.push(`description 只有 ${desc.length} 字，触发不了`);
+    else if (desc.length > 400) problems.push(`description ${desc.length} 字，超过 400`);
+  }
+
+  if (!/^##+\s*(Pitfalls|常见错误)/m.test(text)) problems.push('缺 Pitfalls / 常见错误 一节');
+  if (!/^##+\s*(Verification|验收)/m.test(text)) problems.push('缺 Verification / 验收 一节');
+
+  const fences = (text.match(/^```/gm) || []).length;
+  if (fences % 2 !== 0) problems.push(`代码围栏 ${fences} 个，不成对`);
+
+  const dashes = (text.match(/[—–]/g) || []).length;
+  const srcDashes = ((mineText || '').match(/[—–]/g) || []).length + ((peerText || '').match(/[—–]/g) || []).length;
+  if (dashes > srcDashes) problems.push(`新增长破折号 ${dashes} 处（两侧合计 ${srcDashes} 处）`);
+
+  const capLines = Math.max(
+    120,
+    Math.min(
+      MAX_MERGED_LINES,
+      Math.ceil(Math.max(info.lines, ((mineText || '').split(/\r?\n/).length + (peerText || '').split(/\r?\n/).length) * 1.2)),
+    ),
+  );
+  info.capLines = capLines;
+  if (info.lines > capLines) problems.push(`${info.lines} 行，超过上限 ${capLines}`);
+
+  // 可执行层：命令行 + 数值，不许比两侧任何一侧都少。
+  //
+  // revise 与 condense 是「改正 / 精简」，删掉的恰恰是错的那部分，所以这两种动作
+  // 只要求「要么保住可执行层，要么确实变短了」——两条都不满足才判失败。
+  const prof = profileOf(text, null);
+  info.codeLines = prof.codeLines;
+  info.numbers = prof.numbers;
+  const mineP = profileOf(mineText || '', null);
+  const peerP = profileOf(peerText || '', null);
+  const bestCode = Math.max(mineP.codeLines, peerP.codeLines);
+  const bestNum = Math.max(mineP.numbers, peerP.numbers);
+  const mineLines = (mineText || '').split(/\r?\n/).length;
+  const shrank = info.lines < mineLines;
+  const lenient = Boolean(allowShorter) && shrank;
+  if (!lenient && bestCode >= 3 && prof.codeLines < bestCode) {
+    problems.push(`命令行从 ${bestCode} 掉到 ${prof.codeLines}，可执行层被削`);
+  }
+  if (!lenient && bestNum >= 5 && prof.numbers < Math.floor(bestNum * 0.6)) {
+    problems.push(`具体数值从 ${bestNum} 掉到 ${prof.numbers}，判据被稀释`);
+  }
+
+  // 两侧都有的 Pitfalls 条目：合并后一条都不许少
+  const pitItems = (t) => {
+    const lines = String(t || '').split(/\r?\n/);
+    const out = [];
+    let inPit = false;
+    for (const l of lines) {
+      const h = l.match(/^##+\s+(.+)$/);
+      if (h) {
+        inPit = /^(Pitfalls|常见错误)/i.test(h[1].trim());
+        continue;
+      }
+      if (!inPit) continue;
+      const item = l.match(/^\s*(?:[-*+]|\d+\.)\s+(.{6,})$/);
+      if (item) out.push(item[1].trim().toLowerCase().replace(/\s+/g, ' ').slice(0, 60));
+    }
+    return out;
+  };
+  const mergedPit = pitItems(text);
+  const lost = [];
+  for (const src of [mineText, peerText]) {
+    for (const item of pitItems(src)) {
+      // 合并正文里应能找到该条目的前 20 个字符（允许改写措辞，但要留下痕迹）
+      const key = item.slice(0, 20);
+      if (key && !mergedPit.some((x) => x.includes(key) || key.includes(x.slice(0, 20)))) lost.push(item.slice(0, 40));
+    }
+  }
+  info.lostPitfalls = lost.slice(0, 8);
+  if (lost.length > Math.max(2, mergedPit.length)) {
+    problems.push(`丢了 ${lost.length} 条原有踩坑条目（合并后只剩 ${mergedPit.length} 条）`);
+  }
+
+  if (action && !ACTIONS.has(action)) problems.push(`未知动作 ${action}`);
+  return { ok: problems.length === 0, problems, info };
+}
+
+/**
+ * 生成「停用声明」正文。
+ *
+ * 为什么不是直接删目录：删掉不可逆，而且别的机器还想知道「这个技能曾经存在、
+ * 为什么作废」。停用声明留在原地（名字不变，正文换成声明），技能加载器读到
+ * `deprecated: true` 就不该再把它当能力用，人也能一眼看到原因与来源。
+ */
+export function deprecationStub({ name, reason, source = '', at = new Date().toISOString() }) {
+  const why = String(reason || '评估判定该技能会误导模型').replace(/\s+/g, ' ').trim();
+  return [
+    '---',
+    `name: ${name}`,
+    'description: "已停用：这条技能被判定会误导模型，不要按它执行。保留本文件只为记录原因与来源。"',
+    'deprecated: true',
+    `deprecatedAt: "${at}"`,
+    `deprecatedFrom: "${String(source || '')}"`,
+    'license: MIT',
+    '---',
+    '',
+    `# ${name}（已停用）`,
+    '',
+    '这条技能不再生效。下面是停用原因，供日后复查：',
+    '',
+    why,
+    '',
+    '## Pitfalls',
+    '',
+    `- 停用前的问题：${why}`,
+    '- 不要照着旧版本的文件继续执行：旧命令/旧 API 会得到错误结果。',
+    '',
+    '## Verification',
+    '',
+    '- 确认技能目录里 `SKILL.md` 的 frontmatter 含 `deprecated: true`；',
+    '- 需要恢复时，改回原正文并把 `deprecated` 删掉，不要新建同名目录。',
+    '',
+  ].join('\n');
+}
+
+/* ------------------------------------------------------------ 落草稿 */
+
+/**
+ * 把合并结果落成待批草稿（写在自己那一格里，不动本机技能根）。
+ *
+ * 为什么先落草稿：合并是不可逆动作，而模型评审会出错。草稿 + 原文差异 +
+ * 结论理由三者一起放在共享盘上，人（或者另一个模型）能在不重跑评估的前提下复核。
+ */
+export function landLearningDraft({ config, machineId, name, content, meta = {} }) {
+  const root = mySkillsRoot(config, machineId);
+  const dir = path.join(root, DRAFTS_DIR, name);
+  assertOwnFeaturePath(dir, { featuresRoot: featuresDir(config), machineId });
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'SKILL.md');
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, file);
+  writeJson(path.join(dir, 'DRAFT-META.json'), {
+    schemaVersion: 1,
+    skill: name,
+    draftHash: sha256(content),
+    lines: content.split(/\r?\n/).length,
+    createdAt: new Date().toISOString(),
+    ...meta,
+  });
+  return { dir, file, hash: sha256(content) };
+}
+
+/* ------------------------------------------------------------ 主流程 */
+
+/**
+ * 评估一条「同名不同内容」的差异。
+ *
+ * @param {object} input
+ * @param {string} input.name            技能名
+ * @param {string} input.mineText        本机 SKILL.md
+ * @param {string} input.peerText        对方 SKILL.md
+ * @param {object} input.peer            对方 peers[0]（含 feature / machine / dir）
+ * @param {object} input.mineAssets      本机资产（scripts/references/evals）
+ * @param {Function|null} input.generate 宿主模型（createHostDrafter 产物），可为 null
+ * @param {boolean} input.dryRun         只算不写
+ * @param {object} [input.redundant]     该技能在本机的冗余候选
+ * @param {number} [input.now]
+ */
+export async function learnOneDiff({
+  name,
+  mineText,
+  peerText,
+  peer,
+  mineAssets = {},
+  generate = null,
+  dryRun = false,
+  redundant = [],
+  now = Date.now(),
+  /** 落草稿的目标（本机标识与插件库配置）。缺了就只算不写。 */
+  config = null,
+  machineId = '',
+}) {
+  const record = {
+    skill: name,
+    at: new Date(now).toISOString(),
+    mineHash: sha256(mineText),
+    peerHash: sha256(peerText),
+    peerFeature: peer?.feature || '',
+    peerMachine: peer?.machine || '',
+    action: '',
+    label: '',
+    confidence: 0,
+    reason: '',
+    evidence: [],
+    dropped: [],
+    /** 判定依据：deterministic（机械）/ model（模型）/ manual（等人工） */
+    basis: '',
+    draft: null,
+    audit: null,
+    modelCalls: 0,
+    error: '',
+  };
+
+  const mineProfile = profileOf(mineText, null);
+  const peerProfile = profileOf(peerText, null);
+
+  // ── 1. 严格超集：不叫模型，直接有结论
+  const sup = supersetOf(mineText, peerText);
+  if (sup === 'master') {
+    record.action = 'keep';
+    record.basis = 'deterministic';
+    record.confidence = 0.86;
+    record.reason =
+      `本机版本的章节是对方版本的超集（本机 ${mineProfile.lines} 行 / 对方 ${peerProfile.lines} 行，` +
+      `对方多出的章节：无）。采用本机版本，把对方的差异只记录到台账。`;
+    record.evidence = [
+      `本机章节 ${mineProfile.headings.length} 个，覆盖对方全部 ${peerProfile.headings.length} 个`,
+      `命令行 本机 ${mineProfile.codeLines} / 对方 ${peerProfile.codeLines}`,
+    ];
+    record.label = LEARN_LABEL[record.action];
+    return record;
+  }
+  if (sup === 'peer') {
+    record.action = 'adopt';
+    record.basis = 'deterministic';
+    record.confidence = 0.82;
+    record.reason =
+      `对方版本的章节是本机版本的超集（对方 ${peerProfile.lines} 行 / 本机 ${mineProfile.lines} 行）。` +
+      '建议采用对方版本（来自 ' + (peer?.feature || '未知特征本') + '）。';
+    record.evidence = [
+      `对方章节 ${peerProfile.headings.length} 个，覆盖本机全部 ${mineProfile.headings.length} 个`,
+      `命令行 对方 ${peerProfile.codeLines} / 本机 ${mineProfile.codeLines}`,
+    ];
+    record.label = LEARN_LABEL[record.action];
+    // adopt 要落草稿，这样复核与落地走同一条路
+    if (!dryRun) {
+      try {
+        const d = landLearningDraft({
+          config,
+          machineId,
+          name,
+          content: peerText,
+          meta: { action: 'adopt', from: peer?.feature || '', basis: 'deterministic' },
+        });
+        record.draft = d.file;
+      } catch (err) {
+        record.error = String((err && err.message) || err);
+      }
+    }
+    return record;
+  }
+
+  // ── 2. 需要判断：叫模型
+  if (typeof generate !== 'function') {
+    record.action = 'manual';
+    record.label = LEARN_LABEL.manual;
+    record.basis = 'manual';
+    record.confidence = 0;
+    record.reason =
+      '双方各有对方没有的章节，且宿主没有可用默认模型，无法评估怎么合并。' +
+      `本机独有：${mineProfile.headings.filter((h) => !peerProfile.headings.includes(h)).join(' / ') || '（无章节差异，差异在正文）'}；` +
+      `对方独有：${peerProfile.headings.filter((h) => !mineProfile.headings.includes(h)).join(' / ') || '（无章节差异，差异在正文）'}`;
+    record.evidence = [diffSummary(mineText, peerText)].filter(Boolean);
+    return record;
+  }
+
+  const prompt = buildLearnPrompt({
+    name,
+    mineText,
+    peerText,
+    mineProfile,
+    peerProfile,
+    peerFeature: peer?.feature || '',
+    peerMachine: peer?.machine || '',
+    mineAssets,
+    peerAssets: { scripts: false, references: false, evals: false },
+    diff: diffSummary(mineText, peerText),
+    redundant,
+  });
+
+  let parsed = null;
+  let lastError = '';
+  for (let attempt = 0; attempt < MAX_MODEL_CALLS; attempt += 1) {
+    try {
+      record.modelCalls += 1;
+      const reply = await generate(prompt);
+      const p = parseLearnReply(reply);
+      if (!p.action) {
+        lastError = '模型回复里没有可解析的 action（json 围栏缺失或坏掉）';
+        continue;
+      }
+      parsed = p;
+      break;
+    } catch (err) {
+      lastError = String((err && err.message) || err);
+      break;
+    }
+  }
+
+  if (!parsed) {
+    record.action = 'manual';
+    record.label = LEARN_LABEL.manual;
+    record.basis = 'manual';
+    record.reason = `模型评估没跑通：${lastError}`;
+    return record;
+  }
+
+  record.action = parsed.action;
+  record.label = LEARN_LABEL[parsed.action] || parsed.action;
+  record.basis = 'model';
+  record.confidence = parsed.confidence;
+  record.reason = parsed.reason;
+  record.evidence = parsed.evidence;
+  record.dropped = parsed.dropped;
+
+  // ── 3. keep / deprecate：不需要正文
+  //
+  // 注意：这里没有「擅自删掉对方技能」这条路。deprecate 出的是**停用声明**，
+  // 落成本机草稿（人批了才替换本机副本），对方那一格从不被触碰。
+  // 能定位到错在哪就一律改（revise），deprecate 只留给「改也没意义」。
+  if (parsed.action === 'keep' || parsed.action === 'deprecate') {
+    if (parsed.action === 'deprecate' && parsed.confidence < 0.6) {
+      // 低置信度的停用建议不该出现在面板上等人批准，降级成人工
+      record.action = 'manual';
+      record.label = LEARN_LABEL.manual;
+      record.reason = `模型建议停用但置信度只有 ${parsed.confidence}：${parsed.reason}`;
+      return record;
+    }
+    if (parsed.action === 'deprecate') {
+      record.deprecation = deprecationStub({
+        name,
+        reason: parsed.reason,
+        source: peer?.feature || '',
+        at: record.at,
+      });
+      if (!dryRun) {
+        try {
+          const d = landLearningDraft({
+            config,
+            machineId,
+            name,
+            content: record.deprecation,
+            meta: { action: 'deprecate', from: peer?.feature || '', basis: 'model', reason: parsed.reason },
+          });
+          record.draft = d.file;
+        } catch (err) {
+          record.error = String((err && err.message) || err);
+        }
+      }
+    }
+    return record;
+  }
+
+  // ── 4. 需要正文：审核
+  if (!parsed.content) {
+    record.action = 'manual';
+    record.label = LEARN_LABEL.manual;
+    record.reason = `模型选了 ${parsed.action} 但没有给出可落盘的 SKILL.md`;
+    return record;
+  }
+  // revise 的重心是「改正」，允许比本机短（删掉错的那段就该变短）；
+  // 但两侧原有的 Pitfalls 条目仍然一条都不许丢，所以审核参数只放宽行动作。
+  const audit = auditLearning({
+    text: parsed.content,
+    name,
+    mineText,
+    peerText,
+    action: parsed.action,
+    allowShorter: parsed.action === 'revise' || parsed.action === 'condense',
+  });
+  record.audit = { ok: audit.ok, problems: audit.problems, info: audit.info };
+  if (!audit.ok) {
+    record.action = 'manual';
+    record.label = LEARN_LABEL.manual;
+    record.reason =
+      `模型给的合并稿没过机械审核（${audit.problems.slice(0, 3).join('；')}）。原始理由：${parsed.reason}`;
+    record.rejectedDraft = parsed.content.slice(0, 400);
+    return record;
+  }
+
+  if (!dryRun) {
+    try {
+      const d = landLearningDraft({
+        config,
+        machineId,
+        name,
+        content: parsed.content,
+        meta: {
+          action: parsed.action,
+          from: peer?.feature || '',
+          base: parsed.base || '',
+          confidence: parsed.confidence,
+          reason: parsed.reason,
+          evidence: parsed.evidence,
+          dropped: parsed.dropped,
+          audit: audit.info,
+        },
+      });
+      record.draft = d.file;
+    } catch (err) {
+      record.error = String((err && err.message) || err);
+    }
+  }
+  return record;
+}
+
+/* ------------------------------------------------------------ 台账读写 */
+
+/**
+ * 学一条记录进台账（同名同对方指纹的旧记录会被替换，不做无意义的堆叠）。
+ *
+ * @param {object} input
+ */
+export function recordLearning({ config, machineId, record, machineName = '' }) {
+  const root = mySkillsRoot(config, machineId);
+  const file = path.join(root, LEARNINGS_INDEX);
+  assertOwnFeaturePath(file, { featuresRoot: featuresDir(config), machineId });
+  const doc = readJson(file) || { schemaVersion: 1, items: [] };
+  const items = Array.isArray(doc.items) ? doc.items : [];
+  const key = (x) => `${x.skill}\u0000${x.peerFeature}\u0000${x.peerHash}`;
+  const next = items.filter((x) => key(x) !== key(record));
+  next.push({ ...record, machine: record.machine || machineName });
+  // 只留最近 400 条，避免共享盘上无限膨胀
+  const trimmed = next.slice(-400);
+  const counts = {};
+  for (const x of trimmed) counts[x.action] = (counts[x.action] || 0) + 1;
+  const out = {
+    schemaVersion: 1,
+    feature: String(machineId || ''),
+    machine: machineName,
+    generatedAt: new Date().toISOString(),
+    counts: { total: trimmed.length, pending: trimmed.filter((x) => x.draft && !x.appliedAt).length, byAction: counts },
+    items: trimmed,
+  };
+  writeJson(file, out);
+  return out;
+}
+
+/** 生成人读版（也是给别的机器参考的那一份）。 */
+export function writeLearningsMd({ config, machineId, log }) {
+  const root = mySkillsRoot(config, machineId);
+  const doc = readJson(path.join(root, LEARNINGS_INDEX)) || { items: [], counts: {} };
+  const items = [...(doc.items || [])].reverse();
+  const pending = items.filter((x) => x.draft && !x.appliedAt);
+
+  const lines = [
+    '# 技能学习台账（本机产出，共享给所有机器参考）',
+    '',
+    '> 由 ygc-dsh-sync 的「技能共享」在每次同步后自动生成。',
+    '> 它回答一个问题：**别的机器有同名技能、内容不一样时，本机评估后决定怎么处理**。',
+    '> 任何一台机器读到这份文件，都能直接参考结论，不必重跑一次评估；',
+    '> 想复核就按 `draft` 路径去读合并稿，按 `peerFeature` 去找原版。',
+    '> 判据一律是内容指纹（`mineHash` / `peerHash`），不是时间戳。',
+    `> 生成时间：${doc.generatedAt || new Date().toISOString()}`,
+    `> 记录 ${items.length} 条 · 待批草稿 ${pending.length} 条`,
+    '',
+    '## 待批合并稿',
+    '',
+    pending.length
+      ? '| 技能 | 动作 | 来源 | 置信度 | 草稿 | 理由 |'
+      : '（当前没有待批草稿）',
+  ];
+  if (pending.length) {
+    lines.push('|---|---|---|---|---|---|');
+    for (const x of pending.slice(0, 60)) {
+      lines.push(
+        `| \`${x.skill}\` | ${x.label || x.action} | ${x.peerFeature || '-'} | ${fmtConf(x.confidence)} | \`${relOf(root, x.draft)}\` | ${clip(x.reason, 110)} |`,
+      );
+    }
+  }
+  lines.push('');
+
+  lines.push('## 评估记录（最近 80 条）', '');
+  lines.push('| 技能 | 动作 | 依据 | 来源 | 置信度 | 理由 |');
+  lines.push('|---|---|---|---|---|---|');
+  for (const x of items.slice(0, 80)) {
+    lines.push(
+      `| \`${x.skill}\` | ${x.label || x.action} | ${x.basis || '-'} | ${x.peerFeature || '-'} | ${fmtConf(x.confidence)} | ${clip(x.reason, 120)} |`,
+    );
+  }
+  lines.push('');
+
+  // 优化类型说明：别的机器看这一节就知道本机都会评估什么
+  lines.push('## 本机会评估的优化类型', '');
+  lines.push('| 动作 | 含义 | 判据 |');
+  lines.push('|---|---|---|');
+  lines.push('| 合并精炼 merge | 两侧各有一半，合成一份更准的 | 双方各有对方没有的章节，且章节都能保住 |');
+  lines.push('| 精炼冗余 condense | 内容重复、篇幅虚胖 | 命令行与数值没有增加，正文显著冗余 |');
+  lines.push('| 补全工况 enrich | 补上「什么情况下用 / 不用」 | 一侧有适用条件，一侧没有 |');
+  lines.push('| 增加踩坑经验 pitfalls | 把对方的 Pitfalls 并进来 | 两侧踩坑条目不同，且都能保住 |');
+  lines.push('| 修订错误技能 revise | 改正会误导模型的错做法 | 含错误命令 / 过时 API / 引用不存在的资源，且能定位到错在哪 |');
+  lines.push('| 停用（作废）deprecate | 整条技能不该存在 | 改也没意义，正文换成停用声明；本机副本要人批了才替换 |');
+  lines.push('| 采用对方版本 adopt | 对方明显更完整 | 对方章节是本机超集 |');
+  lines.push('| 保留本机 keep | 本机更完整或对方有错 | 本机章节是对方超集，或对方是错误做法 |');
+  lines.push('| 等人工 manual | 判不出来 | 模型不可用 / 回复不可解析 / 合并稿没过审核 |');
+  lines.push('');
+
+  const mdChanged = (() => {
+    const file = path.join(root, LEARNINGS_INDEX_MD);
+    const strip = (s) => String(s).replace(/^> 生成时间：.*$/m, '');
+    try {
+      if (strip(fs.readFileSync(file, 'utf8')) === strip(lines.join('\n'))) return false;
+    } catch {
+      /* 不存在就写 */
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, lines.join('\n'), 'utf8');
+    fs.renameSync(tmp, file);
+    return true;
+  })();
+
+  log?.(`学习台账已更新：${items.length} 条（待批 ${pending.length}）`);
+  return { file: path.join(root, LEARNINGS_INDEX), mdFile: path.join(root, LEARNINGS_INDEX_MD), mdChanged, doc };
+}
+
+function fmtConf(c) {
+  const n = Number(c);
+  return Number.isFinite(n) && n > 0 ? n.toFixed(2) : '-';
+}
+
+function clip(s, n) {
+  return String(s || '').replace(/\s+/g, ' ').replace(/\|/g, '/').slice(0, n) || '-';
+}
+
+function relOf(root, file) {
+  try {
+    return path.relative(root, file).replace(/\\/g, '/');
+  } catch {
+    return String(file || '');
+  }
+}
+
+/* ------------------------------------------------------------ 批准 / 驳回 */
+
+/**
+ * 批准一条学习草稿：写进本机技能根。
+ *
+ * 落地前再核一次指纹：从出草稿到现在，本机技能可能已经被人改过，
+ * 这时候覆盖就等于把别人的改动冲掉——判据是「当前 SKILL.md 的 hash 是否等于
+ * 出草稿时的 mineHash」，不等就拒绝并要求重新评估。
+ *
+ * @param {{config:object, machineId:string, localRoot:string, name:string,
+ *          force?:boolean, stamp?:string, log?:Function}} input
+ */
+export function approveLearning({ config, machineId, localRoot, name, force = false, stamp, log }) {
+  const root = mySkillsRoot(config, machineId);
+  const draftFile = path.join(root, DRAFTS_DIR, name, 'SKILL.md');
+  let content = '';
+  try {
+    content = fs.readFileSync(draftFile, 'utf8');
+  } catch {
+    return { ok: false, message: `没有待批草稿：${draftFile}` };
+  }
+  const meta = readJson(path.join(root, DRAFTS_DIR, name, 'DRAFT-META.json')) || {};
+
+  const target = path.join(localRoot, name, 'SKILL.md');
+  let current = '';
+  try {
+    current = fs.readFileSync(target, 'utf8');
+  } catch {
+    current = '';
+  }
+  const doc = readJson(path.join(root, LEARNINGS_INDEX)) || { items: [] };
+  const rec = (doc.items || []).find((x) => x.skill === name && x.draft && !x.appliedAt);
+  if (!force && rec && rec.mineHash && current && sha256(current) !== rec.mineHash) {
+    return {
+      ok: false,
+      message:
+        `${name} 的本机 SKILL.md 在出草稿之后被改过（当前 ${sha256(current).slice(0, 8)}，` +
+        `出草稿时 ${String(rec.mineHash).slice(0, 8)}）。强制覆盖请带 force。`,
+    };
+  }
+
+  const st = stamp || new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = path.join(localRoot, `.pre-learn-${st}`, name);
+  try {
+    if (current) {
+      fs.mkdirSync(backupDir, { recursive: true });
+      fs.writeFileSync(path.join(backupDir, 'SKILL.md'), current, 'utf8');
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, content, 'utf8');
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    return { ok: false, message: String((err && err.message) || err) };
+  }
+
+  // 台账标记已落地，并记一条来源（学自哪台机器）
+  const items = doc.items || [];
+  const idx = items.findIndex((x) => x.skill === name && x.draft && !x.appliedAt);
+  if (idx >= 0) {
+    items[idx] = {
+      ...items[idx],
+      appliedAt: new Date().toISOString(),
+      appliedHash: sha256(content),
+      appliedBy: String(machineId || ''),
+    };
+  }
+  writeJson(path.join(root, LEARNINGS_INDEX), {
+    ...doc,
+    generatedAt: new Date().toISOString(),
+    items,
+    counts: {
+      total: items.length,
+      pending: items.filter((x) => x.draft && !x.appliedAt).length,
+    },
+  });
+  if (idx >= 0 && items[idx].peerFeature) {
+    try {
+      recordOrigin(config, machineId, name, { learnedFrom: [items[idx].peerFeature] });
+    } catch {
+      /* 来源写不进去不影响落地 */
+    }
+  }
+  log?.(`学习草稿已落地：${name}（旧版备份在 .pre-learn-${st}/）`);
+  return { ok: true, name, file: target, backup: current ? backupDir : '', hash: sha256(content) };
+}
+
+/** 驳回一条学习草稿：只标状态 + 记理由，草稿文件留着供复核。 */
+export function rejectLearning({ config, machineId, name, reason = '', machineIdOf = '' }) {
+  const root = mySkillsRoot(config, machineId);
+  const file = path.join(root, LEARNINGS_INDEX);
+  assertOwnFeaturePath(file, { featuresRoot: featuresDir(config), machineId });
+  const doc = readJson(file) || { items: [] };
+  const items = Array.isArray(doc.items) ? doc.items : [];
+  const idx = items.findIndex((x) => x.skill === name && x.draft && !x.appliedAt);
+  if (idx < 0) return { ok: false, message: `没有待批记录：${name}` };
+  items[idx] = {
+    ...items[idx],
+    rejectedAt: new Date().toISOString(),
+    rejectReason: String(reason || '人工驳回').slice(0, 400),
+    rejectedBy: String(machineIdOf || machineId || ''),
+  };
+  writeJson(file, {
+    ...doc,
+    generatedAt: new Date().toISOString(),
+    items,
+    counts: { total: items.length, pending: items.filter((x) => x.draft && !x.appliedAt).length },
+  });
+  return { ok: true, name };
+}
+
+/** 列出待批草稿（面板用）。 */
+export function listPendingLearnings({ config, machineId }) {
+  const root = mySkillsRoot(config, machineId);
+  const doc = readJson(path.join(root, LEARNINGS_INDEX)) || { items: [] };
+  return (doc.items || [])
+    .filter((x) => x.draft && !x.appliedAt && !x.rejectedAt)
+    .map((x) => ({
+      skill: x.skill,
+      action: x.action,
+      label: x.label,
+      basis: x.basis,
+      confidence: x.confidence,
+      peerFeature: x.peerFeature,
+      reason: x.reason,
+      evidence: (x.evidence || []).slice(0, 6),
+      dropped: (x.dropped || []).slice(0, 6),
+      audit: x.audit,
+      at: x.at,
+      draft: path.relative(root, x.draft).replace(/\\/g, '/'),
+    }));
+}
+
+/** 读一份草稿正文（面板预览用）。 */
+export function readDraft({ config, machineId, name }) {
+  const file = path.join(mySkillsRoot(config, machineId), DRAFTS_DIR, name, 'SKILL.md');
+  try {
+    return { ok: true, file, text: fs.readFileSync(file, 'utf8') };
+  } catch {
+    return { ok: false, file, text: '' };
+  }
+}
+
+/** 导出常量给上层用（面板要显示目录名）。 */
+export const PATHS = Object.freeze({ SKILLS_DIR, DRAFTS_DIR, LEARNINGS_INDEX, LEARNINGS_INDEX_MD });