@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-analyze/scripts/append-summary-chapter.js

@@ -0,0 +1,612 @@
+#!/usr/bin/env node
+/**
+ * append-summary-chapter.js —— 往总结文件里追加技法内容 + 登记章节
+ *
+ * ## 为什么需要这个脚本
+ *
+ * 「已总结章节」清单是插件判断"哪些章节已经总结过"的**唯一事实源**
+ * （summary-progress.js:374 —— 头部权威；头部非空时正文反推不参与）。
+ *
+ * 让模型手工编辑 YAML 头部来"追加一行"非常脆：模型习惯用 write 重写整个
+ * 文件，一旦把头部写坏了（只留最新登记的那一章），之前登记的章节**全丢** ——
+ * 下次 summary 会把它们全部重做一遍，文件越滚越胖，而且没有任何报错。
+ *
+ * 这个脚本把"追加"做成**幂等且原子**的操作：
+ *   · 章节已在清单里 → 跳过，不重复登记；
+ *   · 文件有正文但没有 front-matter → 补一个；
+ *   · front-matter 里没有「已总结章节」键 → 补上；
+ *   · 写盘用临时文件 + rename，中途失败不会留下半截文件。
+ *
+ * ## 用法
+ *
+ *   node append-summary-chapter.js --file=<绝对路径> --chapter=<章节名>
+ *
+ * 追加正文（从 stdin 读，heredoc 最方便）：
+ *
+ *   node append-summary-chapter.js --file=<绝对路径> --chapter=<章节名> <<'EOF'
+ *   ### 技法名称
+ *   - 来源章节：某书-某技法-第1章
+ *   - 核心要点：……
+ *   EOF
+ *
+ * 正文也可以用 --body-file=<路径> 给。
+ *
+ * 输出：一行 JSON（{ ok, file, added, alreadyRegistered, bodyAdded, total }）
+ */
+import { existsSync, statSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync, realpathSync } from 'fs';
+import { dirname, resolve, relative, isAbsolute } from 'path';
+
+const KEY = '已总结章节';
+
+function parseArgs(argv) {
+  const out = { file: '', chapter: '', bodyFile: '', projectRoot: '', verify: false, section: '核心技法' };
+  for (const arg of argv) {
+    if (arg === '--verify') { out.verify = true; continue; }
+    const m = /^--([a-zA-Z-]+)=(.*)$/.exec(arg);
+    if (!m) continue;
+    const key = m[1];
+    if (key === 'file') out.file = m[2];
+    else if (key === 'chapter') out.chapter = m[2];
+    else if (key === 'body-file') out.bodyFile = m[2];
+    else if (key === 'project-root') out.projectRoot = m[2];
+    else if (key === 'section') out.section = m[2].trim() || '核心技法';
+  }
+  return out;
+}
+
+/** front-matter 里可能出现的键（用于识别坏头部的残留块）。 */
+const FM_KEY = /^(已总结章节|标题|标签)\s*[:：]/;
+
+/**
+ * 头部有开头没结尾时，把开头的 YAML 残块从正文里剥掉。
+ *
+ * 只认已知的几个键和它们下面的列表项 —— 不能用"看起来像 key: value"
+ * 这种宽泛的判断，否则正文里的 URL（https://...）会被误当成头部。
+ *
+ * @param {string} text - 全文
+ * @returns {string} 剥掉头部残块后的正文
+ */
+function stripBrokenHeader(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  if (!/^---\s*$/.test(lines[0] || '')) return text;
+  let i = 1;
+  let inList = false;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+    if (FM_KEY.test(line)) { inList = true; continue; }
+    if (inList && /^\s*-\s+\S/.test(line)) continue;
+    break;
+  }
+  return lines.slice(i).join('\n');
+}
+
+/**
+ * 取开头两段 --- 之间的 front-matter 原文；没有则 null。
+ *
+ * 头��**有开头没结尾**（被 write 冲掉了结尾的 ---）时 fm 也是 null，
+ * 但要跟"根本没有头部"区分开：前者要抢救清单，不能当成新文件重建。
+ *
+ * @param {string} text
+ * @returns {{fm: string|null, body: string, broken: boolean, partialFm: string}}
+ */
+function splitFrontmatter(text) {
+  const normalized = text.replace(/^/, '');
+  if (!/^---\r?\n/.test(normalized)) {
+    return { fm: null, body: normalized, broken: false, partialFm: '' };
+  }
+  const rest = normalized.slice(normalized.indexOf('\n') + 1);
+  const end = rest.search(/^---[ \t]*(\r?\n|$)/m);
+  if (end === -1) {
+    // 有开头没结尾 → 头部坏了。残块留着，等下从里面抢救清单。
+    return {
+      fm: null,
+      body: stripBrokenHeader(normalized),
+      broken: true,
+      partialFm: rest,
+    };
+  }
+  // fm 不含 --- 标记，body 也不含 —— 写盘时再统一包回去
+  return {
+    fm: rest.slice(0, end),
+    body: rest.slice(end).replace(/^---[ \t]*\r?\n?/, ''),
+    broken: false,
+    partialFm: '',
+  };
+}
+
+/** 从 front-matter 里读已登记章节（块列表 + 行内数组都认）。 */
+function parseChapters(fm) {
+  if (!fm) return [];
+  const lines = fm.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const km = lines[i].match(/^\s*已总结章节\s*[:：]\s*(.*)$/);
+    if (!km) continue;
+    const inline = km[1].trim();
+    if (inline.startsWith('[') && inline.endsWith(']')) {
+      for (const part of inline.slice(1, -1).split(',')) {
+        const v = part.trim().replace(/^["']|["']$/g, '').trim();
+        if (v) out.push(v);
+      }
+      continue;
+    }
+    for (let j = i + 1; j < lines.length; j++) {
+      const item = lines[j].match(/^\s*-\s+(.*\S)\s*$/);
+      if (!item) {
+        if (lines[j].trim() === '') continue;
+        break;
+      }
+      out.push(item[1].trim().replace(/^["']|["']$/g, '').trim());
+    }
+  }
+  return out;
+}
+
+/**
+ * 从正文里**反推**已总结的章节名。
+ *
+ * ## 为什么需要
+ *
+ * 头部损坏时（front-matter 被 write 冲掉、或者结尾的 --- 没了），
+ * 直接重建头部会**把已登记的章节全冲掉** —— 实测：
+ * 头部里已有甲-第1/2/3章，坏掉后追加甲-第4章，
+ * 新头部里只剩甲-第4章，而脚本还报 ok:true。
+ * 下次 summary 会把甲-第1/2/3章全部重做一遍。
+ *
+ * 但每条技法条目本身就记着它来自哪些文件：
+ *
+ *     ### 轻叙、爆料与心理停顿交替
+ *     - 来源章节：全球高武-节奏韵律-第1章
+ *
+ * 所以坏掉时可以从正文反推，把清单补回来。
+ * 这跟 summary-progress.js 的 inferSummarizedChapters 同一套思路 ——
+ * **反推不如头部权威**（可能漏写），但比"全部推倒重来"好得多。
+ *
+ * @param {string} body - 正文（不含 front-matter）
+ * @returns {string[]} 反推出的章节名（去重、保序）
+ */
+function inferChapters(body) {
+  const out = [];
+  const seen = new Set();
+  for (const match of String(body || '').matchAll(/^\s*-\s*来源(?:章节|实体|页面)\s*[:：]\s*(.+)$/gm)) {
+    // "来源章节：甲-第1章、甲-第2章" → 拆开
+    for (const part of String(match[1]).split(/[、,，;；]/)) {
+      const v = part.trim();
+      if (!v || seen.has(v)) continue;
+      seen.add(v);
+      out.push(v);
+    }
+  }
+  return out;
+}
+
+/**
+ * 正文里是否已经有这一章的「来源章节」行。
+ *
+ * 为什么需要：头部说"已登记"不代表正文一定写过（比如上一次只登记了清单，
+ * 或者模型重试时又调用了一次）。如果正文已有这一章，就不能再把同一段
+ * 技法追加一遍 —— 否则重试会产出重复条目，文件越滚越胖。
+ *
+ * @param {string} body
+ * @param {string} chapter
+ * @returns {boolean}
+ */
+function bodyHasChapter(body, chapter) {
+  const target = String(chapter || '').trim().replace(/\.md$/i, '');
+  if (!target) return false;
+  for (const match of String(body || '').matchAll(/^\s*-\s*来源(?:章节|实体|页面)\s*[:：]\s*(.+)$/gm)) {
+    for (const part of String(match[1]).split(/[、,，;；]/)) {
+      if (part.trim().replace(/\.md$/i, '') === target) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * 把章节名写进 front-matter 的「已总结章节」清单。
+ *
+ * - 已有该键（块列表）→ 插到列表末尾
+ * - 已有该键（行内数组）→ 转成块列表再插
+ * - 没有该键 → 在 front-matter 末尾补一个块列表
+ * - front-matter 整个不存在 → 建一份只含「已总结章节」的
+ *
+ * ## 为什么头部只有这一个键
+ *
+ * 早先还会写「标题:」和「标签:」两行，但整个插件里**没有任何代码读它们**
+ * （summary-progress.js 只认「已总结章节」这一个键）—— 它们只是看着完整，
+ * 实际是死字段。模型看到这个模板还容易误以为"头部该由我手写"，
+ * 而手写头部正是 write 冲掉清单的诱因。
+ *
+ * @param {string|null} fm - front-matter 原文（不含 --- 标记）
+ * @param {string} chapter - 章节名
+ * @param {string[]} recovered - 头部损坏时从正文反推出来的章节名
+ * @returns {string} 新的 front-matter 原文
+ */
+function registerChapter(fm, chapter, recovered) {
+  if (fm === null) {
+    // 文件没有可用的 front-matter —— 建一份新的。
+    //
+    // 关键：把从正文反推出来的章节**一起**补回去。
+    // 头部损坏时如果只放当前这一章，之前登记的章节就被冲掉了
+    // （实测：已有甲-第1/2/3章，坏掉后追加甲-第4章 → 新头部只剩甲-第4章，
+    //  而脚本还报 ok:true），下次 summary 会把那 3 章全部重做一遍。
+    const list = [];
+    const seen = new Set();
+    for (const c of (recovered || [])) {
+      if (!c || seen.has(c)) continue;
+      seen.add(c);
+      list.push(c);
+    }
+    if (!seen.has(chapter)) list.push(chapter);
+    return [
+      `${KEY}:`,
+      ...list.map(c => `  - ${c}`),
+    ].join('\n');
+  }
+
+  const lines = fm.split(/\r?\n/);
+  // 去掉末尾的空行
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+
+  let keyIndex = -1;
+  let inline = '';
+  for (let i = 0; i < lines.length; i++) {
+    const km = lines[i].match(/^(\s*已总结章节\s*[:：]\s*)(.*)$/);
+    if (km) { keyIndex = i; inline = km[2].trim(); break; }
+  }
+
+  if (keyIndex === -1) {
+    // 补键
+    lines.push(`${KEY}:`);
+    lines.push(`  - ${chapter}`);
+    return lines.join('\n');
+  }
+
+  if (inline.startsWith('[') && inline.endsWith(']')) {
+    // 行内数组 → 转块列表
+    const items = [];
+    for (const part of inline.slice(1, -1).split(',')) {
+      const v = part.trim().replace(/^["']|["']$/g, '').trim();
+      if (v) items.push(v);
+    }
+    items.push(chapter);
+    lines.splice(keyIndex, 1, `${KEY}:`, ...items.map(x => `  - ${x}`));
+    return lines.join('\n');
+  }
+
+  // 块列表：插到该列表末尾
+  let insertAt = keyIndex + 1;
+  while (insertAt < lines.length) {
+    const item = lines[insertAt].match(/^\s*-\s+(.*\S)\s*$/);
+    if (!item) {
+      if (lines[insertAt].trim() === '') { insertAt++; continue; }
+      break;
+    }
+    insertAt++;
+  }
+  lines.splice(insertAt, 0, `  - ${chapter}`);
+  return lines.join('\n');
+}
+
+/** 把正文块追加到指定章节末尾（默认「## 核心技法」）；没有该章节就新建。 */
+function appendBody(body, addition, sectionName = '核心技法') {
+  const text = addition.trim();
+  if (!text) return body;
+  const escaped = sectionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const marker = new RegExp(`^##\\s+${escaped}\\s*$`, 'm');
+  const m = marker.exec(body);
+  if (!m) {
+    const sep = body.endsWith('\n') ? '' : '\n';
+    return `${body}${sep}\n## ${sectionName}\n\n${text}\n`;
+  }
+  const start = m.index + m[0].length;
+  const rest = body.slice(start);
+  const nextHeading = /^##\s+/m.exec(rest);
+  const end = nextHeading ? start + nextHeading.index : body.length;
+  const head = body.slice(0, end).replace(/\s*$/, '\n');
+  const tail = body.slice(end);
+  return `${head}\n${text}\n${tail}`;
+}
+
+/**
+ * 统计「## 核心技法」段落下的技法条目。
+ *
+ * 条目 = `###` 三级标题（与 summary-progress.js 的 entries 口径一致）。
+ * 顺带看每条有没有「来源章节」行 —— 那是头部缺失时反推已总结章节的
+ * 兜底依据（summary-progress.js:222），缺了就会连兜底一起失效。
+ *
+ * @param {string} body - 正文（不含 front-matter）
+ * @returns {{entries: number, withSource: number, missingSource: number}}
+ */
+function inspectEntries(body, sectionName = '核心技法') {
+  const escaped = sectionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const marker = new RegExp(`^##\\s+${escaped}\\s*$`, 'm').exec(body);
+  const scope = marker ? body.slice(marker.index) : '';
+  // 只数「核心技法」这一节里的 ###，别把后面别的 ## 段落算进来
+  const section = scope.replace(new RegExp(`^##\\s+${escaped}\\s*$`, 'm'), '');
+  const nextSection = /^##\s+/m.exec(section);
+  const text = nextSection ? section.slice(0, nextSection.index) : section;
+
+  const heads = [...text.matchAll(/^###\s+(.+?)\s*$/gm)];
+  let withSource = 0;
+  for (const h of heads) {
+    const start = h.index + h[0].length;
+    const nextHead = text.slice(start).search(/^###\s+/m);
+    const chunk = nextHead === -1 ? text.slice(start) : text.slice(start, start + nextHead);
+    if (/^\s*-\s*来源(?:章节|实体|页面)\s*[:：]/m.test(chunk)) withSource++;
+  }
+  return {
+    entries: heads.length,
+    withSource,
+    missingSource: heads.length - withSource,
+  };
+}
+
+/**
+ * 只读校验：报告登记状态，**不修改任何文件**。
+ *
+ * 为什么不用 `head -20`：章节一多，front-matter 里的清单就超过 20 行，
+ * head 根本看不到最新登记的那一条 —— 越到后期越验不出来。清单条数和
+ * 最后一条在这里直接算出来，跟章节数多少无关。
+ *
+ * @param {string} file - 总结文件绝对路径
+ * @returns {number} 退出码
+ */
+function verifyMain(file, sectionName = '核心技法') {
+  if (!existsSync(file)) {
+    process.stdout.write(JSON.stringify({
+      ok: false, verify: true, file, exists: false,
+    }) + '\n');
+    return 1;
+  }
+  let text = '';
+  try {
+    text = readFileSync(file, 'utf-8');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stdout.write(JSON.stringify({
+      ok: false, verify: true, file, error: msg,
+    }) + '\n');
+    return 1;
+  }
+
+  const { fm, body, broken, partialFm } = splitFrontmatter(text);
+  const chapters = parseChapters(fm);
+  const seen = new Set();
+  const duplicates = [];
+  for (const c of chapters) {
+    if (seen.has(c)) duplicates.push(c);
+    seen.add(c);
+  }
+
+  const entryInfo = inspectEntries(body, sectionName);
+  const frontmatterOk = fm !== null;
+  const hasCoreSection = new RegExp(`^##\\s+${sectionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(body);
+
+  // 头部坏了 → 清单读不出来，但残留块/正文里可能还捞得回一些。
+  // 报告出来，让模型知道"登记清单可能不完整"。
+  const recovered = fm === null
+    ? [...new Set([...parseChapters(partialFm), ...inferChapters(body)])]
+    : [];
+
+  // ---- 判定"内容是否正常" ----
+  //
+  // ok 只表示"文件读到了"是不够的：模型拿到 ok:true 会以为一切正常，
+  // 于是带着坏掉的登记状态继续往下写，把问题越滚越大。
+  // 所以这里把"什么算正常"直接算出来，模型看 ok 和 problems 就行，
+  // 不用自己推断字段之间的关系。
+  //
+  // entries 与 total 的关系（**两者不要求相等**）：
+  //   · 一章提炼出多条技法 → entries > total；
+  //   · 多章合并成同一条技法（提示词里的"去重合并"原则）→ entries < total；
+  //   · 一章一条 → entries == total。
+  // 所以 entries 与 total 谁大谁小都正常，**只有下面几条是不正常的**。
+  const problems = [];
+  if (broken) {
+    problems.push('文件头有开头没结尾（被覆盖过）：frontmatterOk=false。'
+      + `已登记章节清单读不出来，但从残留内容里反推出 ${recovered.length} 章`
+      + (recovered.length ? `（${recovered.join('、')}）` : '')
+      + '—— 下次写入会把这些补回头部，但清单可能仍不完整，建议检查该文件');
+  } else if (!frontmatterOk) {
+    problems.push('文件头缺失或损坏：frontmatterOk=false（已登记章节清单读不出来，'
+      + '下次执行会把这批章节全部重做）');
+  }
+  if (duplicates.length > 0) {
+    problems.push(`有重复登记的章节（${duplicates.length} 个）：${duplicates.join('、')}`);
+  }
+  if (!hasCoreSection) {
+    problems.push(`正文中未找到「## ${sectionName}」段（hasCoreSection=false，` +
+      '总结内容没落到正确的位置）');
+  }
+  if (entryInfo.entries === 0 && chapters.length > 0) {
+    problems.push(`已登记了章节，但「## ${sectionName}」下没有任何条目`);
+  }
+  if (entryInfo.missingSource > 0) {
+    problems.push(`有 ${entryInfo.missingSource} 个条目缺「来源章节/来源实体」行`
+      + '（头部一旦损坏，这些条目就没法反推出章节名）');
+  }
+
+  process.stdout.write(JSON.stringify({
+    // ok 现在是**内容判定结果**：false 说明有问题，看 problems 找原因
+    ok: problems.length === 0,
+    verify: true,
+    file,
+    exists: true,
+    problems,
+    frontmatterOk,
+    brokenHeader: broken,
+    recovered,
+    total: chapters.length,
+    last: chapters.length ? chapters[chapters.length - 1] : null,
+    duplicates,
+    hasCoreSection,
+    // 技法条目（内容）的校验结果
+    entries: entryInfo.entries,
+    entriesWithSource: entryInfo.withSource,
+    entriesMissingSource: entryInfo.missingSource,
+    bytes: Buffer.byteLength(text, 'utf-8'),
+  }) + '\n');
+  return 0;
+}
+
+/**
+ * 校验 --file 是否在项目内的 对标/wiki/<技法>/<技法>-总结.md。
+ *
+ * 只有调用方显式给了 --project-root 才校验；老测试/直接调用不带这个参数，
+ * 保持兼容。生产提示词会带上它，避免模型被参考文本里的注入指令带偏，
+ * 把内容写到项目外。
+ *
+ * @param {{projectRoot: string, file: string}} args
+ * @returns {string|null} 错误信息；合法时返回 null
+ */
+function validateTargetPath(args) {
+  if (!args.projectRoot) return null;
+  let root;
+  let rootReal;
+  try {
+    root = resolve(args.projectRoot);
+    if (!statSync(root).isDirectory()) return `项目根不是目录: ${root}`;
+    rootReal = realpathSync(root);
+  } catch (e) {
+    return `项目根不可用: ${e instanceof Error ? e.message : String(e)}`;
+  }
+
+  const target = resolve(args.file);
+  // 先用词法路径判断（项目根本身可能是符号链接，不能拿 realpath 去比原始路径）
+  const rel = relative(root, target);
+  const normalized = rel.replace(/\\/g, '/');
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) {
+    return `总结文件必须位于项目根内: ${target}`;
+  }
+  const parts = normalized.split('/');
+  if (parts.length !== 4 || parts[0] !== '对标' || parts[1] !== 'wiki'
+    || !parts[3].endsWith('-总结.md')) {
+    return `总结文件必须位于 对标/wiki/<技法>/<技法>-总结.md: ${target}`;
+  }
+
+  // 父目录若已存在，解析真实路径，防止通过项目内符号链接写到外面。
+  try {
+    const parentReal = realpathSync(dirname(target));
+    const parentRel = relative(rootReal, parentReal);
+    if (parentRel.startsWith('..') || isAbsolute(parentRel)) {
+      return `总结文件父目录不在项目根内: ${target}`;
+    }
+  } catch {
+    // 父目录不存在：后面写入时会创建，词法检查已覆盖
+  }
+  return null;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.file) {
+    process.stdout.write(JSON.stringify({
+      ok: false,
+      error: '必须给 --file=<绝对路径>',
+    }) + '\n');
+    process.exit(2);
+  }
+
+  const pathError = validateTargetPath(args);
+  if (pathError) {
+    process.stdout.write(JSON.stringify({
+      ok: false,
+      error: pathError,
+    }) + '\n');
+    process.exit(2);
+  }
+
+  if (args.verify) {
+    process.exit(verifyMain(args.file, args.section));
+  }
+
+  if (!args.chapter) {
+    process.stdout.write(JSON.stringify({
+      ok: false,
+      error: '必须给 --chapter=<章节名>（或用 --verify 只做校验）',
+    }) + '\n');
+    process.exit(2);
+  }
+
+  let bodyText = '';
+  if (args.bodyFile) {
+    if (!existsSync(args.bodyFile)) {
+      process.stdout.write(JSON.stringify({
+        ok: false,
+        error: `--body-file 不存在: ${args.bodyFile}`,
+      }) + '\n');
+      process.exit(2);
+    }
+    bodyText = readFileSync(args.bodyFile, 'utf-8');
+  } else if (!process.stdin.isTTY) {
+    try {
+      bodyText = readFileSync(0, 'utf-8');
+    } catch {
+      bodyText = '';
+    }
+  }
+
+  const existed = existsSync(args.file);
+  const raw = existed ? readFileSync(args.file, 'utf-8') : '';
+  const { fm, body, broken, partialFm } = splitFrontmatter(raw);
+
+  // 头部坏了就抢救清单 ——
+  //
+  // 头部是唯一事实源（summary-progress.js 只认它），它一坏，
+  // "这章总结过没有"就无从判断，下次 summary 会把整本重做一遍。
+  // 但清单还在两处可能的地方：残留的头部块里，或正文的「来源章节」行里。
+  // 两者都捞一遍，捞到多少算多少（反推不如头部权威，但远好过推倒重来）。
+  let recovered = [];
+  if (fm === null && existed) {
+    recovered = parseChapters(partialFm);
+    for (const c of inferChapters(body)) {
+      if (!recovered.includes(c)) recovered.push(c);
+    }
+  }
+
+  const already = parseChapters(fm).includes(args.chapter)
+    || recovered.includes(args.chapter);
+  // 头部没登记、但正文已经有这一章的「来源章节」行 → 只补头部，不重复追加正文。
+  const bodyAlready = bodyHasChapter(body, args.chapter);
+  // fm 为 null（头部坏/缺）时一定要重建头部 —— 即使这一章"已经登记过"，
+  // 也得把抢救回来的清单写回去，否则清单就永远丢了。
+  const newFm = (fm !== null && already)
+    ? fm
+    : registerChapter(fm, args.chapter, recovered);
+  const newBody = bodyAlready ? body : appendBody(body, bodyText, args.section);
+
+  // front-matter 必须用 --- 包起来 —— 少了它，summary-progress.js
+  // 的 extractFrontmatter 会认不出来，整份清单就废了。
+  const out = (newFm === null ? '' : '---\n' + newFm + '\n---\n') + newBody;
+
+  try {
+    const dir = dirname(args.file);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const tmp = `${args.file}.tmp-${Date.now()}-${process.pid}`;
+    writeFileSync(tmp, out, 'utf-8');
+    renameSync(tmp, args.file);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stdout.write(JSON.stringify({ ok: false, file: args.file, error: msg }) + '\n');
+    process.exit(1);
+  }
+
+  process.stdout.write(JSON.stringify({
+    // ok=true 表示**这次写入确实落盘了**（写盘异常时前面已 exit(1)）
+    ok: true,
+    file: args.file,
+    added: !already,
+    alreadyRegistered: already,
+    bodyAdded: Boolean(bodyText.trim()) && !bodyAlready,
+    bodyAlreadyPresent: bodyAlready,
+    // 写完后文件里的实际状态，方便模型直接确认，不用再 cat 一遍
+    total: parseChapters(newFm).length,
+    hasCoreSection: /^##\s+核心技法\s*$/m.test(newBody),
+    // 头部原来是坏的 → 已从残留头部/正文反推抢救回这些章节
+    repaired: fm === null && existed,
+    recovered: recovered.length,
+  }) + '\n');
+}
+
+main();