@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-scan/scripts/append-block.js

@@ -0,0 +1,725 @@
+#!/usr/bin/env node
+/**
+ * append-block.js —— 扫榜报告块的**校验 + 追加**（写目标文件的唯一入口）
+ *
+ * ## 为什么把校验搬到这里（2026-10-29）
+ *
+ * 原来校验写在提示词里（5.1 的一堆 grep + 5.3 的一段 python），靠模型自觉执行。三个问题：
+ *
+ *   1. **可以跳过** —— 模型不跑那段命令，报告照样交差，用户看到的是"写成功了"；
+ *   2. **口径会漂** —— 提示词里的正则和插件里的判定各写一遍，改一处就对不上；
+ *   3. **失败会污染文件** —— 先 `cat >>` 再校验，校验不过时坏内容已经落盘，
+ *      而"追加"是只增不减的，脏块永远留在报告里。
+ *
+ * 现在：**写目标文件只有这一条路**。
+ *
+ *   1. **预检** —— 目标可读可写、块标记不存在（不能写重）；
+ *   2. **先校验正文** —— 不合格**根本不碰目标文件**；
+ *   3. **追加** —— 脚本自己写 start/end 标记（模型不用写，也不会写重）；
+ *   4. **后校验** —— 旧内容前缀哈希没变、块结构对得上；变了就**回滚**（截回原长度）。
+ *
+ * ## 退出码
+ *
+ *   | 码 | 含义 | 目标文件 |
+ *   | --- | --- | --- |
+ *   | 0 | 成功 | 已追加 |
+ *   | 2 | 预检失败（不可读/不可写/块已存在） | **未改动** |
+ *   | 3 | 正文不合格 | **未改动** |
+ *   | 4 | 追加后校验失败 | **已自动回滚** |
+ *
+ * ## 用法
+ *
+ *   node append-block.js --target <文件> --block-id <块ID> --body <正文文件> \
+ *        --metric-label <月票> --grouped <0|1>
+ *
+ * 正文也可以从 stdin 读（不给 --body 时）。
+ */
+import {
+  existsSync, readFileSync, writeFileSync, statSync, lstatSync, accessSync,
+  openSync, readSync, closeSync, ftruncateSync, unlinkSync, constants, realpathSync,
+} from 'fs';
+import { createHash } from 'crypto';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'path';
+import { isSensitiveProjectPath, isValidProjectPath } from '#path-guard';
+import { validateReportBody } from './report-validate.js';
+
+const EXIT_OK = 0;
+const EXIT_PRECHECK = 2;
+const EXIT_BODY = 3;
+const EXIT_POSTCHECK = 4;
+
+// 预检模式的参数错误也必须输出 JSON —— 模型只按退出码 + stdout 决策，
+// 如果参数错时只写 stderr，它拿到的就是"退出码 2 + 空 stdout"。
+const IS_PREFLIGHT = process.argv.includes('--preflight');
+
+/** 解析 argv */
+function parseArgs(argv) {
+  // 三态：undefined = 没传（用 manifest 的值），true/false = 命令行覆盖
+  const out = { grouped: undefined, multiList: undefined };
+  // `--block-id` → `blockId`（命令行习惯用连字符，内部用驼峰）
+  const camel = s => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--grouped') out.grouped = true;
+    else if (a === '--ungrouped') out.grouped = false;
+    else if (a === '--multi-list') out.multiList = true;
+    else if (a === '--single-list') out.multiList = false;
+    else if (a === '--preflight') out.preflight = true;
+    else if (a === '--data-file') {
+      // 可重复：LLM 只需要照抄 3.1 的命令，不用自己拼数组。
+      const val = argv[i + 1];
+      if (val === undefined || val.startsWith('--')) {
+        fail(EXIT_PRECHECK, '--data-file 缺值');
+      }
+      if (!Array.isArray(out.dataFile)) out.dataFile = [];
+      out.dataFile.push(val);
+      i++;
+    } else if (a.startsWith('--')) {
+      const key = camel(a.slice(2));
+      const val = argv[i + 1];
+      if (val === undefined || val.startsWith('--')) {
+        fail(EXIT_PRECHECK, `参数 ${a} 缺值`);
+      }
+      out[key] = val;
+      i++;
+    } else {
+      fail(EXIT_PRECHECK, `无法识别的参数 ${a}`);
+    }
+  }
+  return out;
+}
+
+/** 失败：往 stderr 写人话，退出；预检模式下改写 JSON 到 stdout */
+function fail(code, message) {
+  if (IS_PREFLIGHT) {
+    const payload = {
+      ok: false,
+      mode: 'preflight',
+      status: 'blocked',
+      data_files: [],
+      missing_data_files: [],
+      empty_data_files: [],
+      unreadable_data_files: [],
+      non_utf8_data_files: [],
+      warnings: [],
+      problems: [String(message).replace(/\n?$/, '')],
+    };
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    process.exit(EXIT_PRECHECK);
+  }
+  process.stderr.write(message.endsWith('\n') ? message : message + '\n');
+  process.exit(code);
+}
+
+/** 读 stdin */
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/** child 是否在 parent 目录内 */
+function isInside(parent, child) {
+  const p = resolve(parent);
+  const c = resolve(child);
+  const rel = relative(p, c);
+  // 目录相等也算“在目录内”（目标文件所在目录就是 扫榜结果/ 本身）。
+  return (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)));
+}
+
+/**
+ * 只删本插件自己创建的临时正文文件。
+ *
+ * 绝不能无条件 unlink(args.body)：调用方传错时（比如把目标文件或用户
+ * 手稿当 body）会把真实文件删掉。路径必须是 <工作区目录>/.tmp 下的
+ * `fancy_scan_body_*.md`。
+ */
+function cleanupTempBody(bodyFile, projectRoot) {
+  if (!bodyFile || !projectRoot) return;
+  try {
+    const dir = resolve(projectRoot, '.tmp');
+    const file = resolve(bodyFile);
+    if (!isInside(dir, file)) return;
+    if (!/^fancy_scan_body_.*\.md$/i.test(basename(file))) return;
+    unlinkSync(file);
+  } catch { /* 临时文件删不掉不算失败 */ }
+}
+
+/**
+ * 文件**前 n 字节**的 sha256。
+ *
+ * 用来验证"旧内容一个字节都没被动过"——
+ * 追加后重新算一遍同样长度的前缀，哈希必须一模一样。
+ */
+function prefixHash(path, nBytes) {
+  if (!existsSync(path) || !nBytes) return '';
+  const fd = openSync(path, 'r');
+  try {
+    const h = createHash('sha256');
+    const chunk = Buffer.alloc(64 * 1024);
+    let read = 0;
+    while (read < nBytes) {
+      const want = Math.min(chunk.length, nBytes - read);
+      const got = readSync(fd, chunk, 0, want, read);
+      if (got <= 0) break;
+      h.update(chunk.subarray(0, got));
+      read += got;
+    }
+    return h.digest('hex');
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * 目标文件只读体检 —— 预检与真实写入**共用同一套判断**。
+ *
+ * 预检（`--preflight`）只把这个结果转成 JSON；真实写入在同一个结果上
+ * 再加"正文校验 + 追加 + 回滚"。这样不会出现"预检说能写、真写时才发现
+ * 是符号链接"的口径漂移。
+ *
+ * @param {{target: string, blockId: string, projectRoot?: string}} args
+ * @returns {{
+ *   problems: string[],
+ *   targetExisted: boolean,
+ *   blockExists: boolean,
+ *   size: number,
+ *   hash: string,
+ *   tail: string,
+ *   dir: string,
+ * }}
+ */
+function inspectTarget({ target, blockId, projectRoot }) {
+  const problems = [];
+  const out = {
+    problems,
+    targetExisted: false,
+    blockExists: false,
+    size: 0,
+    hash: '',
+    tail: '',
+    dir: target ? dirname(target) : '',
+  };
+
+  if (!target) {
+    problems.push('缺少 --target（目标文件路径）');
+    return out;
+  }
+  if (!blockId) {
+    problems.push('缺少 --block-id（块 ID）');
+    return out;
+  }
+  // 块 ID 会被原样插进 `# ...-start` 标记行；换行/井号会伪造出额外标题。
+  if (!/^[^\r\n#]{1,120}$/.test(blockId)) {
+    problems.push('块 ID 不合法：不能含换行或 #，长度 1-120');
+    return out;
+  }
+  if (!isAbsolute(target)) {
+    problems.push(`--target 必须是绝对路径：${target}`);
+    return out;
+  }
+
+  const dir = dirname(target);
+  out.dir = dir;
+  if (!existsSync(dir)) {
+    problems.push(`目标文件所在目录不存在：${dir}`);
+    return out;
+  }
+
+  // ── 可选：把目标限制在 <projectRoot>/扫榜结果/topic_decision_YYYYMMDD.md ──
+  if (projectRoot) {
+    const root = resolve(projectRoot);
+    if (isSensitiveProjectPath(root) || !isValidProjectPath(root)) {
+      problems.push(`工作区目录路径不合法或属于受保护目录，拒绝写入：${root}`);
+      return out;
+    }
+    let rootReal = '';
+    try {
+      rootReal = realpathSync(root);
+    } catch {
+      problems.push(`工作区目录不存在或无法读取：${root}`);
+      return out;
+    }
+    if (isSensitiveProjectPath(rootReal) || !isValidProjectPath(rootReal)) {
+      problems.push(`工作区目录的真实路径属于受保护目录：${rootReal}`);
+      return out;
+    }
+    const scanDir = join(root, '扫榜结果');
+    let scanReal = scanDir;
+    try {
+      if (existsSync(scanDir)) {
+        const st = lstatSync(scanDir);
+        if (st.isSymbolicLink() || !st.isDirectory()) {
+          problems.push(`扫榜结果/ 不是真实目录，拒绝写入：${scanDir}`);
+          return out;
+        }
+        scanReal = realpathSync(scanDir);
+      }
+    } catch (e) {
+      problems.push(`检查扫榜结果目录失败：${e.message}`);
+      return out;
+    }
+    // 目录本身也必须在工作区目录内 —— 防止通过 symlink 父目录绕过字符串检查。
+    let targetDirReal = '';
+    try {
+      targetDirReal = realpathSync(dir);
+    } catch {
+      problems.push(`目标文件所在目录不存在或无法读取：${dir}`);
+      return out;
+    }
+    if (!isInside(rootReal, targetDirReal)) {
+      problems.push(`目标文件目录不在工作区目录内：${target}`);
+      return out;
+    }
+    if (!isInside(scanReal, targetDirReal)) {
+      problems.push(`目标文件不在 扫榜结果/ 下：${target}`);
+      return out;
+    }
+    if (!/^topic_decision_\d{8}\.md$/.test(basename(target))) {
+      problems.push(`目标文件名必须是 topic_decision_YYYYMMDD.md：${basename(target)}`);
+      return out;
+    }
+  }
+
+  // ── 目录可写 ──────────────────────────────────────────────────
+  try {
+    accessSync(dir, constants.W_OK);
+  } catch {
+    problems.push(`目标文件所在目录不可写：${dir}`);
+  }
+
+  // 先看目录项本身：existsSync 对“悬空符号链接”返回 false，
+  // 而后面的 open('a') 会跟着悬空链接把目标文件创建到链接指向的位置。
+  let lst = null;
+  try { lst = lstatSync(target); } catch { /* 不存在 */ }
+  if (lst && lst.isSymbolicLink()) {
+    problems.push(`目标文件是符号链接，拒绝追加：${target}`);
+    return out;
+  }
+  if (lst && !lst.isFile()) {
+    problems.push(`目标路径不是普通文件：${target}`);
+    return out;
+  }
+
+  if (lst) {
+    out.targetExisted = true;
+    try {
+      accessSync(target, constants.R_OK | constants.W_OK);
+      const st = statSync(target);
+      out.size = st.size;
+      out.hash = prefixHash(target, st.size);
+      const fd = openSync(target, 'r');
+      try {
+        const buf = Buffer.alloc(Math.min(4, st.size));
+        if (buf.length) {
+          readSync(fd, buf, 0, buf.length, Math.max(0, st.size - buf.length));
+          out.tail = buf.toString('utf-8');
+        }
+      } finally {
+        closeSync(fd);
+      }
+    } catch (e) {
+      problems.push(`目标文件无法读取或不可写：${e.message}`);
+      return out;
+    }
+
+    // ── 本次块不能已经存在（不能写重） ──────────────────────────
+    try {
+      const cur = readFileSync(target, 'utf-8');
+      const startMarker = `# ${blockId}-start`;
+      const endMarker = `# ${blockId}-end`;
+      const nStart = cur.split('\n').filter(l => l.trim() === startMarker).length;
+      const nEnd = cur.split('\n').filter(l => l.trim() === endMarker).length;
+      if (nStart > 0 || nEnd > 0) {
+        out.blockExists = true;
+        problems.push(
+          `目标文件里已经有本次（${blockId}）的标记（start ${nStart} 个 / end ${nEnd} 个）—— 不能重复写入。`
+        );
+      }
+    } catch (e) {
+      problems.push(`目标文件无法读取：${e.message}`);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * 数据文件只读体检。
+ *
+ * 结果分四类，方便模型按字段做决定：
+ *   - ok：可读、非空、UTF-8；
+ *   - missing：不存在；
+ *   - empty：存在但 0 字节；
+ *   - unreadable：不是普通文件 / 读不了 / 不在工作区目录的 扫榜结果/ 下；
+ *   - nonUtf8：读到了，但不是合法 UTF-8。
+ *
+ * **部分文件有问题不阻断**（用能读的继续分析）；全部都有问题才阻断。
+ *
+ * @param {string[]} paths
+ * @param {string} projectRoot
+ */
+function inspectDataFiles(paths, projectRoot) {
+  const ok = [];
+  const missing = [];
+  const empty = [];
+  const unreadable = [];
+  const nonUtf8 = [];
+
+  let scanReal = '';
+  if (projectRoot) {
+    try {
+      const scanDir = join(resolve(projectRoot), '扫榜结果');
+      if (existsSync(scanDir)) scanReal = realpathSync(scanDir);
+    } catch { /* 目录问题由 inspectTarget 报 */ }
+  }
+
+  for (const raw of paths) {
+    const p = String(raw || '');
+    if (!p || !isAbsolute(p)) {
+      unreadable.push({ path: p, reason: '必须是绝对路径' });
+      continue;
+    }
+    let fileReal = '';
+    try {
+      fileReal = realpathSync(p);
+    } catch {
+      missing.push(p);
+      continue;
+    }
+    if (scanReal && !isInside(scanReal, fileReal)) {
+      unreadable.push({ path: p, reason: '不在工作区目录的 扫榜结果/ 下' });
+      continue;
+    }
+    let st = null;
+    try { st = statSync(fileReal); } catch {
+      missing.push(p);
+      continue;
+    }
+    if (!st.isFile()) {
+      unreadable.push({ path: p, reason: '不是普通文件' });
+      continue;
+    }
+    let buf = null;
+    try {
+      buf = readFileSync(fileReal);
+    } catch (e) {
+      unreadable.push({ path: p, reason: e.message });
+      continue;
+    }
+    if (!buf.length) {
+      empty.push(p);
+      continue;
+    }
+    try {
+      new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    } catch {
+      nonUtf8.push(p);
+      continue;
+    }
+    ok.push({ path: p, bytes: buf.length });
+  }
+
+  return { ok, missing, empty, unreadable, nonUtf8 };
+}
+
+/**
+ * 读取插件生成的运行清单。
+ *
+ * 清单由 `fancy-scan/index.js` 在投递提示词前写入
+ * `<工作区目录>/.fancy-tools/fancy-scan/run-<hash>.json`，里面有目标、工作区目录、
+ * 块 ID、数据文件、正文路径、指标与开关。模型只需要照抄两条短命令，
+ * **不需要自己拼参数** —— 少一个参数就少一个跑偏的机会。
+ *
+ * 命令行参数仍然可以覆盖清单（测试与手工调试用）。
+ *
+ * @param {string|undefined} manifestPath
+ * @returns {object}
+ */
+function loadManifest(manifestPath) {
+  if (!manifestPath) return {};
+  if (!isAbsolute(manifestPath)) {
+    fail(EXIT_PRECHECK, '--manifest 必须是绝对路径');
+  }
+  let raw = '';
+  try {
+    raw = readFileSync(manifestPath, 'utf-8');
+  } catch (e) {
+    fail(EXIT_PRECHECK, `无法读取运行清单：${e.message}`);
+  }
+  let data = null;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    fail(EXIT_PRECHECK, `运行清单不是合法 JSON：${e.message}`);
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    fail(EXIT_PRECHECK, '运行清单顶层必须是 JSON 对象');
+  }
+  return data;
+}
+
+/**
+ * `--preflight` 入口：只读，不碰目标文件。
+ *
+ * stdout **只输出一个 JSON 对象**（模型据此决定是否继续），
+ * stderr 留空。退出码：
+ *   0 = 可以继续；2 = 有阻断项，禁止继续。
+ *
+ * 数据文件缺失/部分不可读**不阻断**（放进 missing/empty/unreadable，
+ * 由模型在报告里说明）；只有"一个能用的都没有"才阻断。
+ */
+function runPreflight(args) {
+  const manifest = loadManifest(args.manifest);
+  const target = args.target || manifest.target || '';
+  const blockId = args.blockId || manifest.block_id || '';
+  const projectRoot = args.projectRoot || manifest.project_root || '';
+  const dataArgs = Array.isArray(args.dataFile)
+    ? args.dataFile
+    : (Array.isArray(manifest.data_files) ? manifest.data_files : []);
+  const warnings = [];
+
+  const ins = inspectTarget({ target, blockId, projectRoot });
+  const problems = [...ins.problems];
+  const data = inspectDataFiles(dataArgs, projectRoot);
+
+  if (!dataArgs.length) {
+    warnings.push('未提供 --data-file，数据文件预检被跳过');
+  }
+  if (data.missing.length) {
+    warnings.push(`缺失的数据文件 ${data.missing.length} 个（不阻断，但本次分析不能用它们）：${data.missing.join('、')}`);
+  }
+  if (data.empty.length) {
+    warnings.push(`空的数据文件 ${data.empty.length} 个（不阻断，但本次分析不能用它们）：${data.empty.join('、')}`);
+  }
+  if (data.unreadable.length) {
+    warnings.push('不可读的数据文件：' + data.unreadable.map(x => `${x.path}（${x.reason}）`).join('；'));
+  }
+  if (data.nonUtf8.length) {
+    warnings.push(`不是 UTF-8 的数据文件 ${data.nonUtf8.length} 个（不阻断，但不能拿乱码做统计）：${data.nonUtf8.join('、')}`);
+  }
+  if (dataArgs.length && data.ok.length === 0) {
+    problems.push(`所有数据文件都缺失、为空、不可读或不是 UTF-8（${dataArgs.length} 个）—— 没有可分析的数据`);
+  }
+
+  const payload = {
+    ok: problems.length === 0,
+    mode: 'preflight',
+    status: problems.length === 0 ? 'pass' : 'blocked',
+    target,
+    block_id: blockId,
+    project_root: projectRoot || null,
+    target_exists: ins.targetExisted,
+    target_size: ins.size,
+    block_exists: ins.blockExists,
+    data_files: data.ok,
+    missing_data_files: data.missing,
+    empty_data_files: data.empty,
+    unreadable_data_files: data.unreadable,
+    non_utf8_data_files: data.nonUtf8,
+    warnings,
+    problems,
+  };
+
+  process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+  process.exit(problems.length ? EXIT_PRECHECK : EXIT_OK);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.preflight) return runPreflight(args);
+
+  const manifest = loadManifest(args.manifest);
+  const target = args.target || manifest.target;
+  const blockId = args.blockId || manifest.block_id;
+  const metricLabel = args.metricLabel || manifest.metric_label || '月票';
+  const projectRoot = args.projectRoot || manifest.project_root || '';
+  const grouped = args.grouped === undefined ? manifest.grouped === true : args.grouped;
+  const multiList = args.multiList === undefined ? manifest.multi_list === true : args.multiList;
+  const dataFiles = Array.isArray(manifest.data_files) ? manifest.data_files : [];
+  const knownLists = Array.isArray(manifest.rank_labels) ? manifest.rank_labels : [];
+
+  const ins = inspectTarget({ target, blockId, projectRoot });
+  if (ins.problems.length) {
+    fail(EXIT_PRECHECK, ins.problems.join('\n') + '\n目标文件没有被动过。');
+  }
+  const targetExisted = ins.targetExisted;
+  const preSize = ins.size;
+  const preHash = ins.hash;
+  const preTail = ins.tail;
+  const startMarker = `# ${blockId}-start`;
+  const endMarker = `# ${blockId}-end`;
+
+  // ── 读正文 ────────────────────────────────────────────────────
+  let body = '';
+  let bodyFile = '';
+  const bodyArg = args.body || manifest.body_file || '';
+  if (bodyArg) {
+    if (!isAbsolute(bodyArg)) {
+      fail(EXIT_BODY, `--body 必须是绝对路径：${bodyArg}\n目标文件没有被动过。`);
+    }
+    bodyFile = bodyArg;
+    if (!existsSync(bodyFile)) {
+      fail(EXIT_BODY, `正文文件不存在：${bodyFile}\n目标文件没有被动过。`);
+    }
+    // body 与 target 相同（或符号链接指向同一文件）时，
+    // 追加后再 cleanupTempBody/无条件 unlink 会把目标文件删掉。
+    try {
+      const bodyReal = realpathSync(bodyFile);
+      const targetReal = existsSync(target) ? realpathSync(target) : resolve(target);
+      if (bodyReal === targetReal || resolve(bodyFile) === resolve(target)) {
+        fail(EXIT_BODY, `--body 不能与 --target 是同一个文件：${bodyFile}\n目标文件没有被动过。`);
+      }
+    } catch (e) {
+      if (e && e.exitCode) throw e;
+      // realpath 失败（例如 body 刚被删）交给下面的读取报错
+    }
+    try {
+      body = readFileSync(bodyFile, 'utf-8');
+    } catch (e) {
+      fail(EXIT_BODY, `无法读取正文文件：${e.message}\n目标文件未被修改。`);
+    }
+  } else {
+    body = readStdin();
+  }
+  body = body.replace(/\r\n/g, '\n').replace(/^\n+/, '').replace(/\n+$/, '');
+  if (!body.trim()) {
+    fail(EXIT_BODY, '正文是空的。\n目标文件没有被动过。');
+  }
+
+  // ── 校验正文（不合格根本不碰目标文件） ────────────────────────
+  const v = validateReportBody(body, {
+    metricLabel,
+    grouped,
+    multiList,
+    dataFiles,
+    knownLists,
+  });
+  if (!v.ok) {
+    const lines = [
+      `正文不合格（${v.errors.length} 项），**目标文件没有被改动**。`,
+      '请改正下面这些问题后重跑本脚本（正文写到同一个文件即可）：',
+      '',
+      ...v.errors.map((e, i) => `  ${i + 1}. ${e}`),
+    ];
+    if (v.warnings.length) {
+      lines.push('', '（另外有几条提醒，不拦你，但最好改）:', ...v.warnings.map(w => `  - ${w}`));
+    }
+    fail(EXIT_BODY, lines.join('\n'));
+  }
+
+  // ── 追加 ──────────────────────────────────────────────────────
+  // 旧文件末尾没有换行时先补一个，免得和上一段黏成一行
+  let prefix = '';
+  if (preSize > 0 && preTail && !preTail.endsWith('\n')) {
+    prefix = '\n';
+  }
+  const block = `${prefix}${startMarker}\n${body}\n${endMarker}\n`;
+  let writeErr = null;
+  try {
+    // O_APPEND + O_NOFOLLOW：不跟随符号链接，且始终追加到末尾。
+    // 预检已经 lstat 过一次，这里再让内核拒绝一次，缩小竞态窗口。
+    const flags = constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT
+      | (constants.O_NOFOLLOW || 0);
+    const fd = openSync(target, flags, 0o644);
+    try {
+      writeFileSync(fd, block, 'utf-8');
+    } finally {
+      closeSync(fd);
+    }
+  } catch (e) {
+    writeErr = e;
+  }
+  if (writeErr) {
+    // 写失败可能已经落了半截：尽量恢复到写入前，再报告。
+    try {
+      if (!targetExisted) unlinkSync(target);
+      else {
+        const fd = openSync(target, 'r+');
+        try { ftruncateSync(fd, preSize); } finally { closeSync(fd); }
+      }
+    } catch { /* 恢复失败在下面的文案里说明 */ }
+    fail(EXIT_PRECHECK,
+      `追加失败：${writeErr.message}\n本次写入可能只落了一部分，已尝试恢复到写入前；请人工确认目标文件。`);
+  }
+
+  // ── 后校验：旧内容没被覆盖 + 块结构对得上 ─────────────────────
+  const problems = [];
+  try {
+    const after = readFileSync(target, 'utf-8');
+    // 旧内容必须一个字节都没动 —— 重新算一遍同样长度的前缀，哈希要一模一样
+    if (preSize > 0) {
+      const afterHash = prefixHash(target, preSize);
+      if (afterHash !== preHash) {
+        problems.push('旧内容的前缀哈希变了 —— 说明旧内容被覆盖了');
+      }
+    }
+    const afterLines = after.split('\n');
+    const nStart = afterLines.filter(l => l.trim() === startMarker).length;
+    const nEnd = afterLines.filter(l => l.trim() === endMarker).length;
+    if (nStart !== 1) problems.push(`写入后 start 标记数是 ${nStart}，应为 1`);
+    if (nEnd !== 1) problems.push(`写入后 end 标记数是 ${nEnd}，应为 1`);
+    const idxS = afterLines.findIndex(l => l.trim() === startMarker);
+    const idxE = afterLines.findIndex(l => l.trim() === endMarker);
+    if (idxS >= 0 && idxE >= 0) {
+      const blockBody = afterLines.slice(idxS + 1, idxE).join('\n');
+      const v2 = validateReportBody(blockBody, {
+        metricLabel,
+        grouped,
+        multiList,
+        dataFiles,
+        knownLists,
+      });
+      if (!v2.ok) {
+        problems.push(...v2.errors.slice(0, 5).map(e => '写入后复检：' + e));
+      }
+    }
+  } catch (e) {
+    problems.push('写入后读不回来：' + e.message);
+  }
+
+  if (problems.length) {
+    // 回滚：目标原本不存在就删掉；原本存在就截回原长度。
+    try {
+      if (!targetExisted) {
+        unlinkSync(target);
+      } else {
+        const fd = openSync(target, 'r+');
+        try {
+          ftruncateSync(fd, preSize);
+        } finally {
+          closeSync(fd);
+        }
+      }
+    } catch (e) {
+      fail(EXIT_POSTCHECK,
+        `写入后校验失败（${problems.length} 项），**并且回滚失败**：${e.message}\n`
+        + problems.map(p => '  - ' + p).join('\n')
+        + '\n目标文件长度已尝试恢复，请人工检查。');
+    }
+    fail(EXIT_POSTCHECK,
+      `写入后校验失败（${problems.length} 项），**已自动回滚**，目标文件恢复到写入前的样子：\n`
+      + problems.map(p => '  - ' + p).join('\n'));
+  }
+
+  // ── 成功 ──────────────────────────────────────────────────────
+  // 只清理本插件自己的临时文件；用户传入的真实文件绝不能删。
+  cleanupTempBody(bodyFile, projectRoot);
+  const s = v.stats;
+  const out = [
+    `写入成功：${target}`,
+    `  块 ID：${blockId}`,
+    `  方向 ${s.directions} 个 · 表格 ${s.tables} 张 · 汉字 ${s.totalCjk}`
+    + `（纯正文 ${s.pureCjk}）· 引用 ${s.citations} 处 · 推断标记 ${s.inferMarks} 处`,
+    ...s.tags.map(t => `  方向 ${t.direction}：标签 ${t.okTags}/${t.total}`),
+  ];
+  if (v.warnings.length) {
+    out.push('  提醒（不拦你）：', ...v.warnings.map(w => `  - ${w}`));
+  }
+  process.stdout.write(out.join('\n') + '\n');
+  process.exit(EXIT_OK);
+}
+
+main();