ygc-dsh-sync 1.2.2 → 1.3.0

package/lib/skill-optimize.js

@@ -0,0 +1,888 @@
+/**
+ * 本机技能优化：点一下，后台自己把本机技能精炼、合并、优化。
+ *
+ * 与 skill-learn.js 的分工：
+ *   skill-learn  管「我和别的机器同名技能不一样」→ 跨机学习
+ *   skill-optimize 管「我自己这一堆技能」→ 本机体检 + 精炼 + 合并
+ * 两者的产出同构（都是待批草稿 + 台账记录），所以落地、批准、驳回共用一套。
+ *
+ * 只处理**归本插件管**的技能：第三方（技能市场装的）由 skill-scope.js 先剔掉，
+ * 这里拿到的 ownSet 已经不含它们；就算调用方传错，下面每个入口还会再查一次。
+ *
+ * 一轮的固定顺序（便宜的先跑，模型调用最后）：
+ *   1. 机械体检（不花钱）：缺章节、死指针、围栏、破折号、篇幅异常
+ *   2. 冗余配对（不花钱）：描述词重合度 → 合并精炼候选
+ *   3. 建模评估（花钱）：按严重度排序，取前 N 条出草稿
+ *   4. 落草稿 + 记台账（写自己那一格）
+ *
+ * 为什么要「后台 + 待批」而不是「点完就改」：
+ *   优化是不可逆动作，而且模型会犯错。草稿 + 机械审核 + 原文差异一起摆在
+ *   共享盘上，人（或另一个模型）能复核；批准时才替换本机副本，且替换前留备份。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import {
+  DRAFTS_DIR,
+  LEARNINGS_INDEX,
+  LEARNINGS_INDEX_MD,
+  mySkillsRoot,
+  readSkillMeta,
+} from './skillshare.js';
+import { assertOwnFeaturePath, featuresDir } from './plugins.js';
+import { parseFrontMatter, walkFiles } from './skills.js';
+import {
+  extractSkillMarkdown,
+  findRedundantPairs,
+  landLearningDraft,
+  recordLearning,
+  writeLearningsMd,
+} from './skill-learn.js';
+
+/** 一次优化一轮最多出几份草稿（模型调用要时间，默认 3 条）。 */
+export const DEFAULT_MAX_PER_ROUND = 3;
+/** 一轮里模型调用总上限（含重试）。 */
+const MAX_MODEL_CALLS = 8;
+/** 单份技能送进模型的正文上限。 */
+const MAX_SIDE_CHARS = 26000;
+/** 优化后正文的硬上限行数。 */
+const MAX_OPTIMIZED_LINES = 900;
+
+export const OPT = Object.freeze({
+  REFINE: 'refine',
+  CONDENSE: 'condense',
+  MERGE: 'merge',
+  ENRICH: 'enrich',
+  PITFALLS: 'pitfalls',
+  FIXPATH: 'fixpath',
+  DEPRECATE: 'deprecate',
+});
+
+export const OPT_LABEL = {
+  refine: '精炼（结构与可执行层）',
+  condense: '精简冗余（压长度不削判据）',
+  merge: '合并重复技能',
+  enrich: '补全工况与触发条件',
+  pitfalls: '补踩坑经验',
+  fixpath: '修掉不存在的引用',
+  deprecate: '停用（作废）',
+};
+
+/* -------------------------------------------------------------- 小工具 */
+
+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 sha256(text) {
+  return crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
+}
+
+/** SKILL.md 里被引用的本地相对路径（用于抓「引用了不存在的文件」）。 */
+export function citedPaths(text) {
+  const out = new Set();
+  const t = String(text || '');
+  // 形如 `scripts/foo.mjs`、`references/bar.md`、`./assets/x.png`
+  for (const m of t.matchAll(/(?:^|[\s(`'"])((?:\.\/)?(?:scripts|references|assets|evals|templates)\/[A-Za-z0-9._\-/]+)/g)) {
+    out.add(m[1].replace(/^\.\//, ''));
+  }
+  return [...out];
+}
+
+/** 引用里哪些在本技能目录中真的不存在。 */
+export function missingCitations(dir, text) {
+  const missing = [];
+  for (const rel of citedPaths(text)) {
+    if (!fs.existsSync(path.join(dir, rel))) missing.push(rel);
+  }
+  return missing;
+}
+
+/**
+ * 单技能机械体检。
+ *
+ * 每条都写成「问题 + 为什么错 + 该怎么做」，因为模型拿着这份清单去改，
+ * 比给它一句「优化一下」有用得多。
+ */
+export function inspectSkill({ name, dir, maxLines = 600, minLines = 40 }) {
+  const file = path.join(dir, 'SKILL.md');
+  const text = readText(file);
+  const fm = parseFrontMatter(file);
+  const issues = [];
+  const lines = text ? text.split(/\r?\n/).length : 0;
+  const fences = (text.match(/^```/gm) || []).length;
+
+  if (!text.trim()) {
+    issues.push({ code: 'empty', severity: 3, why: 'SKILL.md 是空的或读不到', fix: '补正文，或停用这个技能' });
+  }
+  if (!fm.name) issues.push({ code: 'no-name', severity: 2, why: 'frontmatter 缺 name', fix: '补 name，值与目录名一致' });
+  else if (fm.name !== name) {
+    issues.push({
+      code: 'name-mismatch',
+      severity: 2,
+      why: `frontmatter name=${fm.name} 与目录名 ${name} 不一致`,
+      fix: `把 name 改成 ${name}`,
+    });
+  }
+  const desc = fm.description || '';
+  if (!desc) issues.push({ code: 'no-desc', severity: 3, why: '缺 description（技能永远不会被触发）', fix: '写 60 到 400 字，含用户会说的原话' });
+  else if (desc.length < 60) {
+    issues.push({
+      code: 'short-desc',
+      severity: 2,
+      why: `description 只有 ${desc.length} 字，触发不准`,
+      fix: '扩到 60 到 400 字，补 4 到 6 个用户真实会说的场景',
+    });
+  } else if (desc.length > 400) {
+    issues.push({
+      code: 'long-desc',
+      severity: 1,
+      why: `description ${desc.length} 字，超过 400（常驻上下文挤占）`,
+      fix: '压到 400 字以内，保留场景关键词',
+    });
+  }
+
+  const hasPit = /^##+\s*(Pitfalls|常见错误|踩坑)/m.test(text);
+  const hasVer = /^##+\s*(Verification|验收|自查|交付前)/m.test(text);
+  if (!hasPit) issues.push({ code: 'no-pitfalls', severity: 2, why: '缺踩坑小节（同一坑会反复踩）', fix: '加 `## Pitfalls`，每条写成 症状 / 为什么错 / 正确做法' });
+  if (!hasVer) issues.push({ code: 'no-verification', severity: 2, why: '缺验收小节（交出来什么算什么）', fix: '加 `## Verification`，写成可勾选的自查项' });
+
+  if (fences % 2 !== 0) {
+    issues.push({ code: 'fence', severity: 3, why: `代码围栏 ${fences} 个，不成对（正文已损坏）`, fix: '补齐闭合围栏，别把正文吃掉' });
+  }
+
+  const missing = missingCitations(dir, text);
+  if (missing.length) {
+    issues.push({
+      code: 'dead-citation',
+      severity: 3,
+      why: `引用了不存在的文件：${missing.slice(0, 4).join('、')}（模型会照着去读，读不到就开始编）`,
+      fix: '能删就删这条引用；确实需要就补上文件，或改成「自行命名一个脚本」的说法',
+    });
+  }
+
+  if (lines && lines < minLines) {
+    issues.push({
+      code: 'too-short',
+      severity: 2,
+      why: `只有 ${lines} 行，缺可执行层（命令 / 数值 / 输出模板）`,
+      fix: '补具体命令、阈值与输出模板；确实不需要就考虑与其他技能合并',
+    });
+  }
+  if (lines > maxLines) {
+    issues.push({
+      code: 'too-long',
+      severity: 2,
+      why: `${lines} 行，超过 ${maxLines} 行（该拆 references 或精简）`,
+      fix: '把细节挪进 references/，SKILL.md 只留判断与入口',
+    });
+  }
+
+  const dashes = (text.match(/[—–]/g) || []).length;
+  if (dashes > 6) {
+    issues.push({ code: 'dashes', severity: 1, why: `长破折号 ${dashes} 处（模型文体习惯，读起来累）`, fix: '换成逗号或冒号' });
+  }
+  const assets = {
+    scripts: fs.existsSync(path.join(dir, 'scripts')),
+    references: fs.existsSync(path.join(dir, 'references')),
+    evals: fs.existsSync(path.join(dir, 'evals')) || fs.existsSync(path.join(dir, 'evals.json')),
+  };
+  // 有资源目录但正文零指针 = 死文件（D4 的一类硬伤）
+  if ((assets.scripts || assets.references) && citedPaths(text).length === 0) {
+    issues.push({
+      code: 'unreferenced-assets',
+      severity: 2,
+      why: '目录里有 scripts/references，但正文一条加载指针都没有（等于死文件）',
+      fix: '在正文里写清什么时候读哪个文件（相对路径）',
+    });
+  }
+
+  const severity = issues.reduce((n, x) => Math.max(n, x.severity), 0);
+  return {
+    name,
+    dir,
+    lines,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    files: walkFiles(dir).length,
+    descLength: desc.length,
+    assets,
+    hasPitfalls: hasPit,
+    hasVerification: hasVer,
+    missingCitations: missing,
+    issues,
+    severity,
+    score: issues.reduce((n, x) => n + x.severity, 0),
+    text,
+    mdHash: sha256(text),
+  };
+}
+
+/* ------------------------------------------------------------ 提示词 */
+
+export const OPT_SYSTEM = [
+  '你是技能（SKILL.md）的维护者。任务是把一份本机自研技能改得更好，不是重写它。',
+  '',
+  '输出必须分成两块，顺序固定：',
+  '第一块：一个 ```json 围栏，只含：',
+  '{',
+  '  "action": "refine|condense|merge|enrich|pitfalls|fixpath|deprecate",',
+  '  "confidence": 0.0 到 1.0,',
+  '  "reason": "不超过 200 字：改了哪几处、为什么这样改",',
+  '  "changes": ["具体改动一", "..."],',
+  '  "dropped": ["删掉的内容及理由", "..."]',
+  '}',
+  '第二块：action 不是 deprecate 时，再给一个 ```markdown 围栏，里面是改完的 SKILL.md 全文；',
+  'action 是 deprecate 时不输出第二块。',
+  '',
+  '硬规则（不满足会被机械审核拒掉）：',
+  '1. 保留 frontmatter，`name:` 与给定技能名逐字相同；description 60 到 400 字。',
+  '2. 必须有 `## Pitfalls`（或 `## 常见错误`）与 `## Verification`（或 `## 验收`）两节。',
+  '3. **不许删掉原有的可执行层**：命令、参数、阈值、输出模板、判定表。要精简就精简解释性文字。',
+  '4. 不许新增对不存在的文件的引用；原本指向不存在文件的引用要删掉或改成「自行命名」。',
+  '5. 不许出现长破折号「—」「–」。代码围栏成对闭合。',
+  '6. 不许比原文长出 40% 以上；允许比原文短，但删的必须是冗余而不是判据。',
+  '7. 每一条原有 Pitfalls 都要留下（可以合并措辞，但坑本身不许消失）。',
+  '',
+  '动作怎么选：',
+  '- 结构乱、缺章节、缺验收 → refine',
+  '- 解释性文字太多、判据被埋住 → condense',
+  '- 缺「什么情况下用 / 不用」→ enrich',
+  '- 只有正面规则没有踩坑 → pitfalls',
+  '- 引用了不存在的文件 → fixpath',
+  '- 两个技能该合成一个 → merge（会额外给另一份正文）',
+  '- 整条技能是错的、改也没意义 → deprecate',
+].join('\n');
+
+/** 组一条单技能优化提示词。 */
+export function buildOptimizePrompt({ name, text, profile, issues, action, peer = null, redundant = [] }) {
+  const tr = (s, cap = MAX_SIDE_CHARS) => {
+    const t = String(s || '');
+    return t.length <= cap ? t : `${t.slice(0, cap)}\n\n[以上被截断：原文 ${t.length} 字，只给了前 ${cap} 字]`;
+  };
+  const L = [];
+  L.push(`技能名（frontmatter 的 name 必须逐字写成这个）：${name}`);
+  L.push(`建议动作：${OPT_LABEL[action] || action}（可以改成更合适的动作，但要在 reason 里说清）`);
+  L.push('');
+  L.push('## 机械体检结果（真实现算，不要推翻，逐条处理）');
+  L.push(`行 ${profile.lines} · 字 ${profile.bytes} 字节 · 资产 scripts=${profile.assets.scripts} references=${profile.assets.references} evals=${profile.assets.evals}`);
+  if (!issues.length) L.push('- （没有机械问题，按动作自由优化）');
+  for (const it of issues) {
+    L.push(`- [${it.severity}] ${it.code}：${it.why}`);
+    L.push(`  处理方式：${it.fix}`);
+  }
+  if (peer) {
+    L.push('');
+    L.push(`## 待合并的另一份技能：${peer.name}`);
+    L.push(`行 ${peer.lines} · 说明：${String(peer.desc || '').slice(0, 200)}`);
+    L.push('合并要求：两份的可执行层都要保住；合成后 name 用上面给定的技能名；');
+    L.push('另一份里独有的坑与工况必须留在合并稿里，合并后在 JSON 的 dropped 里列出被移走的内容。');
+    L.push('```markdown');
+    L.push(tr(peer.text));
+    L.push('```');
+  }
+  if (Array.isArray(redundant) && redundant.length) {
+    L.push('');
+    L.push('## 与本机其他技能的重合（供判断是否该 merge）');
+    for (const r of redundant.slice(0, 4)) L.push(`- \`${r.a}\` 与 \`${r.b}\` 重合理度 ${r.similarity}：${r.reason}`);
+  }
+  L.push('');
+  L.push('## 当前 SKILL.md 全文');
+  L.push('```markdown');
+  L.push(tr(text));
+  L.push('```');
+  L.push('');
+  L.push('现在给出改完的版本。先 json 围栏，需要正文时再跟一个 markdown 围栏。');
+  return L.join('\n');
+}
+
+/* ------------------------------------------------------------ 解析与审核 */
+
+/** 从模型回复里取结论与正文（与 skill-learn 的解析同构，但动作集不同）。 */
+export function parseOptimizeReply(text) {
+  const raw = String(text || '');
+  const out = { action: '', confidence: 0, reason: '', changes: [], dropped: [], content: '' };
+  const ACTIONS = new Set(Object.values(OPT));
+  const blocks = [...raw.matchAll(/```(?:json|JSON)\s*\r?\n([\s\S]*?)```/g)].map((m) => m[1].trim());
+  const whole = raw.trim();
+  if (!blocks.length && whole.startsWith('{')) blocks.push(whole);
+  for (const b of blocks) {
+    try {
+      const v = JSON.parse(b);
+      if (!v || typeof v !== 'object') continue;
+      const a = typeof v.action === 'string' ? v.action.trim() : '';
+      if (ACTIONS.has(a)) out.action = a;
+      const c = Number(v.confidence);
+      if (Number.isFinite(c)) out.confidence = Math.max(0, Math.min(1, c));
+      if (typeof v.reason === 'string') out.reason = v.reason.trim().slice(0, 1200);
+      if (Array.isArray(v.changes)) out.changes = v.changes.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);
+      break;
+    } catch {
+      /* 坏 JSON 继续 */
+    }
+  }
+  // 正文切分走共用实现：SKILL.md 内部自带代码块，非贪婪正则会把它截断
+  out.content = extractSkillMarkdown(raw);
+  return out;
+}
+
+/**
+ * 审核优化稿。
+ *
+ * 与本机原有的 mnemon 审核口径一致的地方：frontmatter / 两节必备 / 围栏 / 破折号 / 章节不许丢。
+ * 刻意放宽的地方：**允许变短**（精炼是合法动作），但可执行层的命令行数量不许
+ * 掉到原文的 70% 以下——这是「精简」和「削判据」的分界线。
+ */
+export function auditOptimized({ text, name, originalText, action }) {
+  const problems = [];
+  const info = {};
+  if (!text || !text.trim()) return { ok: false, problems: ['优化稿为空'], info };
+  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.descLength = 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`);
+  }
+
+  info.lines = text.split(/\r?\n/).length;
+  if (info.lines > MAX_OPTIMIZED_LINES) problems.push(`${info.lines} 行，超过上限 ${MAX_OPTIMIZED_LINES}`);
+
+  const srcLines = (originalText || '').split(/\r?\n/).length;
+  if (srcLines && info.lines > Math.ceil(srcLines * 1.4) + 40) {
+    problems.push(`比原文长出太多（${srcLines} → ${info.lines} 行），优化不该膨胀`);
+  }
+  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 = ((originalText || '').match(/[—–]/g) || []).length;
+  if (dashes > Math.max(srcDashes, 6)) problems.push(`新增长破折号（${srcDashes} → ${dashes} 处）`);
+
+  // 可执行层不许被削
+  const countCmd = (t) => (String(t || '').match(/^\s*(\$\s|\w+\s+--|node |python |pnpm |npm |git |powershell |curl )/gm) || []).length;
+  const countNum = (t) => (String(t || '').match(/\b\d+(\.\d+)?\s*(ms|s|秒|分钟|行|字|%|MB|GB|pt|px)\b/g) || []).length;
+  info.cmdBefore = countCmd(originalText);
+  info.cmdAfter = countCmd(text);
+  info.numBefore = countNum(originalText);
+  info.numAfter = countNum(text);
+  if (info.cmdBefore >= 4 && info.cmdAfter < Math.floor(info.cmdBefore * 0.7)) {
+    problems.push(`命令行从 ${info.cmdBefore} 掉到 ${info.cmdAfter}（低于 70%），判据被削`);
+  }
+  if (info.numBefore >= 6 && info.numAfter < Math.floor(info.numBefore * 0.7)) {
+    problems.push(`具体数值从 ${info.numBefore} 掉到 ${info.numAfter}（低于 70%）；收紧口子不行，现在是放宽`);
+  }
+
+  // 原有章节标题不许丢（允许改写同义，但标题集合不能少太多）
+  const heads = (t) => new Set((String(t || '').match(/^#{2,3}\s+(.+)$/gm) || []).map((x) => x.replace(/^#+\s*/, '').trim()));
+  const before = heads(originalText);
+  const after = heads(text);
+  const lost = [...before].filter((h) => !after.has(h));
+  info.lostHeadings = lost.slice(0, 6);
+  if (lost.length > Math.max(2, Math.floor(before.size * 0.4))) {
+    problems.push(`丢了 ${lost.length} 个原有章节（原有 ${before.size} 个）：${lost.slice(0, 4).join(' / ')}`);
+  }
+
+  // 原有 Pitfalls 条目：合并措辞可以，坑本身不许消失
+  const pitItems = (t) => {
+    const out = [];
+    let inPit = false;
+    for (const l of String(t || '').split(/\r?\n/)) {
+      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, 50));
+    }
+    return out;
+  };
+  const srcPit = pitItems(originalText);
+  const nowPit = pitItems(text);
+  const lostPit = srcPit.filter((k) => !nowPit.some((x) => x.includes(k.slice(0, 16))));
+  info.lostPitfalls = lostPit.slice(0, 6);
+  if (srcPit.length >= 3 && lostPit.length > Math.max(1, Math.floor(srcPit.length * 0.3))) {
+    problems.push(`丢了 ${lostPit.length} / ${srcPit.length} 条原有踩坑条目`);
+  }
+
+  if (action && !Object.values(OPT).includes(action)) problems.push(`未知动作 ${action}`);
+  return { ok: problems.length === 0, problems, info };
+}
+
+/* ------------------------------------------------------------ 主流程 */
+
+/**
+ * 跑一轮本机优化。
+ *
+ * @param {object} input
+ * @param {object} input.config              { libraryRoot }
+ * @param {string} input.machineId
+ * @param {string} input.machineName
+ * @param {string} input.localRoot           本机技能根
+ * @param {Set<string>} input.ownSet         归本插件管的技能名（skill-scope 给的）
+ * @param {Function|null} input.generate     宿主模型
+ * @param {number} [input.maxPerRound=3]
+ * @param {boolean} [input.dryRun=false]
+ * @param {boolean} [input.includeMerge=true] 是否把冗余合并算进来
+ * @param {Function} [input.log]
+ */
+export async function runOptimizeRound({
+  config,
+  machineId,
+  machineName = '',
+  localRoot,
+  ownSet,
+  generate = null,
+  maxPerRound = DEFAULT_MAX_PER_ROUND,
+  dryRun = false,
+  includeMerge = true,
+  log,
+}) {
+  const started = Date.now();
+  const feature = String(machineId || '').trim();
+  if (!feature) return { ok: false, error: '本机标识还没生成' };
+
+  const report = {
+    ok: true,
+    feature,
+    ms: 0,
+    scanned: 0,
+    skippedThirdParty: 0,
+    healthy: 0,
+    queued: [],
+    queueTotal: 0,
+    drafted: [],
+    rejected: [],
+    onlyRecorded: [],
+    merged: [],
+    errors: [],
+    dryRun,
+    modelCalls: 0,
+  };
+
+  // ── 1. 体检（只查 ownSet 里的）
+  const dirs = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(localRoot, { withFileTypes: true });
+  } catch {
+    return { ok: false, error: `读不到技能根：${localRoot}` };
+  }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.') || e.name.startsWith('_')) continue;
+    const dir = path.join(localRoot, e.name);
+    if (!fs.existsSync(path.join(dir, 'SKILL.md'))) continue;
+    if (ownSet && !ownSet.has(e.name)) {
+      report.skippedThirdParty += 1;
+      continue;
+    }
+    dirs.push({ name: e.name, dir });
+  }
+
+  const profiles = [];
+  for (const { name, dir } of dirs) {
+    try {
+      const p = inspectSkill({ name, dir });
+      profiles.push(p);
+      report.scanned += 1;
+    } catch (err) {
+      report.errors.push(`${name}：体检失败 ${String((err && err.message) || err)}`);
+    }
+  }
+
+  const byName = new Map(profiles.map((p) => [p.name, p]));
+  for (const p of profiles) if (!p.issues.length) report.healthy += 1;
+
+  // ── 2. 冗余配对（只保留两份都归自己管的）
+  let pairs = [];
+  if (includeMerge) {
+    try {
+      const asMap = new Map();
+      for (const p of profiles) {
+        asMap.set(p.name, {
+          name: p.name,
+          dirName: p.name,
+          description: (parseFrontMatter(path.join(p.dir, 'SKILL.md')).description || ''),
+          text: p.text,
+        });
+      }
+      pairs = findRedundantPairs(asMap).filter((x) => ownSet.has(x.a) && ownSet.has(x.b));
+    } catch (err) {
+      report.errors.push(`冗余配对失败：${String((err && err.message) || err)}`);
+    }
+  }
+
+  // ── 3. 排优先级：严重度高的先处理
+  const cand = [];
+  for (const p of profiles) {
+    if (!p.issues.length) continue;
+    const action = decideAction(p);
+    cand.push({ name: p.name, profile: p, action, weight: p.score });
+  }
+  // 合并候选排在前面（一次处理两条技能，性价比最高）
+  for (const pair of pairs.slice(0, 4)) {
+    const a = byName.get(pair.a);
+    if (!a) continue;
+    cand.push({
+      name: pair.a,
+      profile: a,
+      action: OPT.MERGE,
+      weight: a.score + 6 + Math.round(pair.similarity * 10),
+      peerName: pair.b,
+      peerProfile: byName.get(pair.b) || null,
+      pair,
+    });
+  }
+  cand.sort((x, y) => y.weight - x.weight);
+
+  // 同名去重：同一个技能只排一次，保留权重最高的那条
+  const seen = new Set();
+  const queue = [];
+  for (const c of cand) {
+    if (seen.has(c.name)) continue;
+    seen.add(c.name);
+    queue.push(c);
+  }
+
+  const limit = Math.max(0, Math.min(Number(maxPerRound) || 0, 12));
+  const picked = queue.slice(0, limit);
+  // queued 只记「本轮真的会处理」的那些：把整条队列塞进去会让面板显示
+  // 「排队 N 个」而实际只做 1 个，看起来像报错了。
+  report.queued = picked.map((c) => ({ name: c.name, action: c.action, label: OPT_LABEL[c.action], weight: c.weight }));
+  report.queueTotal = queue.length;
+
+  // ── 4. 出草稿
+  if (typeof generate !== 'function') {
+    report.skipped = '宿主没有可用默认模型：只做体检与排队，不出草稿';
+  } else {
+    for (const item of picked) {
+      if (report.modelCalls >= MAX_MODEL_CALLS) {
+        report.errors.push(`模型调用已达上限 ${MAX_MODEL_CALLS}，剩下的下一轮再处理`);
+        break;
+      }
+      const rec = await optimizeOne({
+        item,
+        config,
+        machineId: feature,
+        machineName,
+        localRoot,
+        generate,
+        dryRun,
+        redundant: pairs.filter((p) => p.a === item.name || p.b === item.name),
+        onModelCall: () => {
+          report.modelCalls += 1;
+        },
+        log,
+      });
+      // 字段名是 draft（草稿路径），不是 drafted。写错了会把「成功出稿」记成「审核未过」。
+      if (rec.draft) report.drafted.push({ name: rec.skill, action: rec.action, label: OPT_LABEL[rec.action] });
+      else if (rec.action === 'manual' || rec.action === OPT.DEPRECATE) report.onlyRecorded.push({ name: rec.skill, action: rec.action, note: '仅记录' });
+      else report.rejected.push({ name: rec.skill, reason: rec.reason });
+      if (rec.action === OPT.MERGE && rec.peerName) report.merged.push({ into: rec.skill, from: rec.peerName });
+      if (rec.error) report.errors.push(`${rec.skill}：${rec.error}`);
+    }
+  }
+
+  // ── 5. 健康态也记一条（不调模型），让面板知道「体检跑过了」
+  if (!dryRun) {
+    try {
+      const doc = readJson(path.join(mySkillsRoot(config, feature), LEARNINGS_INDEX)) || { items: [] };
+      const items = Array.isArray(doc.items) ? doc.items : [];
+      const inspectAt = new Date().toISOString();
+      const summary = {
+        schemaVersion: 1,
+        feature,
+        machine: machineName,
+        generatedAt: inspectAt,
+        kind: 'inspect',
+        counts: {
+          scanned: report.scanned,
+          healthy: report.healthy,
+          queued: report.queued.length,
+          drafted: report.drafted.length,
+          thirdPartySkipped: report.skippedThirdParty,
+        },
+        // 只留最严重的 30 条，避免台账变成另一份全量体检报告
+        worst: profiles
+          .filter((p) => p.issues.length)
+          .sort((a, b) => b.score - a.score)
+          .slice(0, 30)
+          .map((p) => ({
+            skill: p.name,
+            score: p.score,
+            lines: p.lines,
+            codes: [...new Set(p.issues.map((x) => x.code))],
+          })),
+        at: inspectAt,
+      };
+      const rest = items.filter((x) => x.kind !== 'inspect');
+      writeLedger(config, feature, { ...doc, items: [...rest, summary] });
+      writeLearningsMd({ config, machineId: feature, log });
+    } catch (err) {
+      report.errors.push(`写体检摘要失败：${String((err && err.message) || err)}`);
+    }
+  }
+
+  report.ms = Date.now() - started;
+  log?.(
+    `本机技能优化：体检 ${report.scanned} 个（健康 ${report.healthy}，第三方跳过 ${report.skippedThirdParty}）、` +
+      `排队 ${report.queued.length}、出草稿 ${report.drafted.length}` +
+      (report.rejected.length ? `、审核未过 ${report.rejected.length}` : '') +
+      (report.errors.length ? `、错误 ${report.errors.length}` : ''),
+  );
+  return report;
+}
+
+/** 按体检问题选一个默认动作。 */
+export function decideAction(profile) {
+  const codes = new Set(profile.issues.map((x) => x.code));
+  if (codes.has('empty')) return OPT.DEPRECATE;
+  if (codes.has('dead-citation')) return OPT.FIXPATH;
+  if (codes.has('fence')) return OPT.REFINE;
+  if (codes.has('too-long')) return OPT.CONDENSE;
+  if (codes.has('no-pitfalls')) return OPT.PITFALLS;
+  if (codes.has('no-verification')) return OPT.REFINE;
+  if (codes.has('too-short')) return OPT.ENRICH;
+  if (codes.has('unreferenced-assets')) return OPT.REFINE;
+  if (/desc/.test([...codes].join(' '))) return OPT.REFINE;
+  return OPT.REFINE;
+}
+
+/** 处理一条：调模型 → 解析 → 审核 → 落草稿 → 记台账。 */
+async function optimizeOne({
+  item,
+  config,
+  machineId,
+  machineName,
+  localRoot,
+  generate,
+  dryRun,
+  redundant,
+  onModelCall,
+  log,
+}) {
+  const { name, profile, action, peerName, peerProfile } = item;
+  const rec = {
+    skill: name,
+    at: new Date().toISOString(),
+    mineHash: profile.mdHash,
+    peerHash: '',
+    peerFeature: '',
+    peerMachine: '',
+    action,
+    label: OPT_LABEL[action],
+    basis: 'model',
+    confidence: 0,
+    reason: '',
+    evidence: profile.issues.map((x) => `[${x.code}] ${x.why}`).slice(0, 8),
+    dropped: [],
+    draft: null,
+    audit: null,
+    modelCalls: 0,
+    error: '',
+    kind: 'optimize',
+    inspect: { score: profile.score, lines: profile.lines, codes: [...new Set(profile.issues.map((x) => x.code))] },
+  };
+
+  const prompt = buildOptimizePrompt({
+    name,
+    text: profile.text,
+    profile,
+    issues: profile.issues,
+    action,
+    peer: peerProfile
+      ? { name: peerName, text: peerProfile.text, lines: peerProfile.lines, desc: parseFrontMatter(path.join(peerProfile.dir, 'SKILL.md')).description || '' }
+      : null,
+    redundant,
+  });
+
+  let parsed = null;
+  let lastErr = '';
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      onModelCall();
+      rec.modelCalls += 1;
+      const reply = await generate(prompt);
+      const p = parseOptimizeReply(reply);
+      if (!p.action) {
+        lastErr = '回复里没有可解析的 action';
+        continue;
+      }
+      parsed = p;
+      break;
+    } catch (err) {
+      lastErr = String((err && err.message) || err);
+      break;
+    }
+  }
+  if (!parsed) {
+    rec.action = 'manual';
+    rec.label = '等人工处理';
+    rec.basis = 'manual';
+    rec.reason = `模型优化没跑通：${lastErr}`;
+    if (!dryRun) safeRecord(config, machineId, rec, machineName);
+    return rec;
+  }
+
+  rec.action = parsed.action;
+  rec.label = OPT_LABEL[parsed.action] || parsed.action;
+  rec.confidence = parsed.confidence;
+  rec.reason = parsed.reason;
+  rec.dropped = parsed.dropped;
+  rec.changes = parsed.changes;
+  if (peerName) rec.mergedFrom = peerName;
+
+  if (parsed.action === OPT.DEPRECATE) {
+    if (parsed.confidence < 0.6) {
+      rec.action = 'manual';
+      rec.label = '等人工处理';
+      rec.reason = `模型建议停用但置信度只有 ${parsed.confidence}：${parsed.reason}`;
+    }
+    if (!dryRun) safeRecord(config, machineId, rec, machineName);
+    return rec;
+  }
+
+  if (!parsed.content) {
+    rec.action = 'manual';
+    rec.label = '等人工处理';
+    rec.reason = `模型选了 ${parsed.action} 但没给正文`;
+    if (!dryRun) safeRecord(config, machineId, rec, machineName);
+    return rec;
+  }
+
+  const audit = auditOptimized({
+    text: parsed.content,
+    name,
+    originalText: profile.text,
+    action: parsed.action,
+  });
+  rec.audit = { ok: audit.ok, problems: audit.problems, info: audit.info };
+  if (!audit.ok) {
+    rec.action = 'manual';
+    rec.label = '等人工处理';
+    rec.reason = `优化稿没过机械审核（${audit.problems.slice(0, 3).join('；')}）`;
+    if (!dryRun) safeRecord(config, machineId, rec, machineName);
+    return rec;
+  }
+
+  if (!dryRun) {
+    try {
+      const d = landLearningDraft({
+        config,
+        machineId,
+        name,
+        content: parsed.content,
+        meta: {
+          action: parsed.action,
+          kind: 'optimize',
+          base: 'mine',
+          confidence: parsed.confidence,
+          reason: parsed.reason,
+          changes: parsed.changes,
+          dropped: parsed.dropped,
+          audit: audit.info,
+          mergedFrom: peerName || '',
+        },
+      });
+      rec.draft = d.file;
+      log?.(`优化草稿已出：${name}（${OPT_LABEL[parsed.action] || parsed.action}）`);
+    } catch (err) {
+      rec.error = String((err && err.message) || err);
+    }
+    safeRecord(config, machineId, rec, machineName);
+  }
+  return rec;
+}
+
+function safeRecord(config, machineId, rec, machineName) {
+  try {
+    recordLearning({ config, machineId, record: rec, machineName });
+  } catch {
+    /* 台账写失败不影响草稿本身 */
+  }
+}
+
+function writeLedger(config, machineId, doc) {
+  const file = path.join(mySkillsRoot(config, machineId), LEARNINGS_INDEX);
+  assertOwnFeaturePath(file, { featuresRoot: featuresDir(config), machineId });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+  fs.renameSync(tmp, file);
+}
+
+/** 整库体检摘要（不调模型，面板「体检」按钮用）。 */
+export function inspectAll({ localRoot, ownSet }) {
+  const out = { scanned: 0, healthy: 0, thirdParty: 0, items: [], codes: {} };
+  let entries = [];
+  try {
+    entries = fs.readdirSync(localRoot, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.') || e.name.startsWith('_')) continue;
+    const dir = path.join(localRoot, e.name);
+    if (!fs.existsSync(path.join(dir, 'SKILL.md'))) continue;
+    if (ownSet && !ownSet.has(e.name)) {
+      out.thirdParty += 1;
+      continue;
+    }
+    try {
+      const p = inspectSkill({ name: e.name, dir });
+      out.scanned += 1;
+      if (!p.issues.length) out.healthy += 1;
+      for (const it of p.issues) out.codes[it.code] = (out.codes[it.code] || 0) + 1;
+      if (p.issues.length) {
+        out.items.push({
+          name: p.name,
+          score: p.score,
+          lines: p.lines,
+          action: decideAction(p),
+          actionLabel: OPT_LABEL[decideAction(p)],
+          issues: p.issues.map((x) => ({ code: x.code, severity: x.severity, why: x.why })),
+        });
+      }
+    } catch {
+      /* 单个技能体检失败不影响整库 */
+    }
+  }
+  out.items.sort((a, b) => b.score - a.score);
+  return out;
+}
+
+/** 草稿目录（面板用）。 */
+export function draftsDir(config, machineId) {
+  return path.join(mySkillsRoot(config, machineId), DRAFTS_DIR);
+}