annotatable-html 0.0.0-stage → 1.38.3

package/lib/core.js

@@ -0,0 +1,2198 @@
+'use strict';
+
+/* 可批注 HTML · 核心逻辑
+ * 供 bin/cli.js 与 agent/ 薄封装共用；与 AGENTS.md 描述的工作流保持一致。 */
+
+var fs = require('fs');
+var path = require('path');
+var LANG = require('./lang-en.js');
+
+/* ---------- 英文烤制（v1.25.0）----------
+ * 词典最长优先替换全文（HTML 文本/属性/JS 字面量）+ 两个 agent 协议块整体英译。
+ * 词典本体（zh 键）先掩码再替换——en 文档运行时还要用它把动态生成的中文翻成英文
+ * （boot 后 MutationObserver 消费 LANG_PAIRS，模板里 langTr 只认 DOC_LANG==='en'）。 */
+var LANG_BLOCK_ANNOT_EN = [
+  '<!-- ═══ ANNOTATION DATA BEGIN — response protocol for AI agents (this block is the only part you need to read):',
+  '① Handle only annotations with status:"new"; the thread array is the full conversation (role: user/ai). Read the whole thread before answering; answer only what is asked, quote minimal context, do not pad;',
+  '② Reply format: short answers (≤5 lines) go inline as the reply; long answers are written to answers/{project}_ANSWER__{topic}__{agent}.md next to this file (staging + per-round sections; reuse the same file for the same topic), with a 1-3 line summary plus the relative md path as the reply;',
+  '③ Write back with the standard tools annot_reply.js / annotatable reply (appends the ai turn, maintains history snapshots, rev+1); the reply field mirrors the latest AI turn;',
+  '④ If a comment contains "stash" or "keep" → file the quoted text into that ANSWER.md staging area; "distill" or "distill to: file" → distill reusable knowledge into docs/Learn/ (or the named file);',
+  '⑤ history is the version ledger: since v1.10.0 the file keeps a skeleton (rev/time/op/n, last 60; adjustable in the history panel ⚙, persisted via store histCaps — the CLI tools trim by the same counts; edit entries carry bodyOps strips); the full snapshot ledger lives in .annotatable/<file>.hist.json (tool-maintained, with DOC_ID ownership checks). Users can roll back any version (including body) in the page Version history. Agents append via annot_reply.js / annot_edit.js as usual — never hand-edit the history structure;',
+  '⑥ Duty & streaming (v1.21.0): while on duty, append with `annotatable reply doc.html --stream \'chunk\' --id annId` (the page renders typing live); finish with `--stream-end \'full text\'`; exit code 4 = the human pressed ⏹ (stop immediately), 5 = the annotation was deleted (stop too), 7 = no open streaming round (start one with --id). Without --id, a chunk auto-attaches to the most recently STARTED still-open streaming round and never to a finished one. An ai turn with streaming:true means a reply is in progress; top-level control.stop is an interrupt request written by the page button — tools consume it automatically, never hand-edit. After each round, re-mount `annotatable poll` to keep watching ═══ -->'
+].join('\n');
+var LANG_BLOCK_LESSON_EN = [
+  '<!-- ═══ LESSON DATA BEGIN — long answers / lesson cards: the agent writes via `annotatable answer` (the page renders read-only; browser saves preserve this block):',
+  'Shape { rev, answers: [{ id, annId (source annotation id), title, rungs: [{ title rung heading, body rung body, checkpoint checkpoint (optional), answer answer key (optional) }] }] }',
+  'Multi-rung or checkpointed entries render on the answer page as staged lesson cards (rung-by-rung unlock); single-rung entries render as one long-answer card.',
+  'The annotation store stays slim: to read pending annotations, read the annotations-store above — no need to swallow lesson full texts ═══ -->'
+].join('\n');
+function applyLangEn(tpl) {
+  var pairs = LANG.pairs.slice().sort(function (a, b) { return b[0].length - a[0].length; });
+  var masked = tpl.replace(/var LANG_PAIRS = null;[^\n]*/, '/*__LANG_PAIRS__*/');
+  /* v1.36.0：层三件的四个哨兵标记是结构坐标（inject/upgrade 按它们定位换装），先掩码——
+     否则词典短键「批注」把「批注层样式 BEGIN」烤成「annotation层…」，en 注入页从此造不出来（v1.17.0 潜伏 bug） */
+  masked = masked.split('/* ═══ 批注层样式 BEGIN').join('/*__SENT_CSS_B__')
+    .split('批注层样式 END ═══ */').join('__SENT_CSS_E__*/')
+    .split('<!-- ═══ 批注层骨架 BEGIN').join('<!--__SENT_SK_B__')
+    .split('批注层骨架 END ═══ -->').join('__SENT_SK_E__-->');
+  /* OP_LABELS 以中文为对象键（键是账本里的 op 代码，必须保持 zh；值另有词典条目负责显示），
+     键被替换会产出 "follow-up:'follow-up'" 这类未加引号含连字符的键=语法错，同样掩码 */
+  masked = masked.replace(/var OP_LABELS = \{[^}]*\};/, '/*__OP_LABELS__*/');
+  masked = masked.replace('<html lang="zh-CN">', '<html lang="en">');
+  masked = masked.replace(/<!-- ═══ AI批注数据 BEGIN[\s\S]*?═══ -->/, LANG_BLOCK_ANNOT_EN);
+  masked = masked.replace(/<!-- ═══ AI教学数据 BEGIN[\s\S]*?═══ -->/, LANG_BLOCK_LESSON_EN);
+  var missed = [];
+  pairs.forEach(function (p) {
+    if (masked.indexOf(p[0]) === -1) { missed.push(p[0]); return; }
+    masked = masked.split(p[0]).join(p[1]);
+  });
+  masked = masked.replace('var DOC_LANG = \'zh\';', 'var DOC_LANG = \'en\';');
+  masked = masked.replace('/*__LANG_PAIRS__*/',
+    'var LANG_PAIRS=' + JSON.stringify(pairs).replace(/<\//g, '<\\/') + ';');
+  masked = masked.split('/*__SENT_CSS_B__').join('/* ═══ 批注层样式 BEGIN')
+    .split('__SENT_CSS_E__*/').join('批注层样式 END ═══ */')
+    .split('<!--__SENT_SK_B__').join('<!-- ═══ 批注层骨架 BEGIN')
+    .split('__SENT_SK_E__-->').join('批注层骨架 END ═══ -->');
+  masked = masked.replace('/*__OP_LABELS__*/', function () {
+    var m = tpl.match(/var OP_LABELS = \{[^}]*\};/);
+    return m ? m[0] : '';
+  });
+  return { html: masked, missed: missed };
+}
+
+/* ---------- 版本历史外置存储（v1.10.0）----------
+ * 主文件 store 只留骨架 history（无 snap，体积有界）；
+ * 全量账本（含批注层快照）放同目录 .annotatable/<文件名>.hist.json。
+ * 伴生档案打开时做 DOC_ID 归属校验：不匹配视为不存在（防复制文件互染）。
+ * 写伴生失败（如目录只读）时自动降级：snap 留在主文件（v1.9 兼容模式）。 */
+var HIST_DIR = '.annotatable';
+var HIST_MAIN_MAX = 60;      // 主文件内骨架条数上限（默认值，可被 store.histCaps 覆盖）
+var HIST_SIDECAR_MAX = 1000; // 外置档案条数上限（默认值，可被 store.histCaps 覆盖）
+var HIST_FALLBACK_MAX = 120; // 无外置档案时主文件内全量历史上限（v1.9 行为，不随设置走）
+
+/* 用户可调的快照保留数量（v1.13.0）：浏览器在历史面板设置、随 store.histCaps 落盘；
+ * CLI 必须按同一数量裁剪——否则 agent 一次提交就把用户调大的档案砍回默认（数据丢失）。
+ * 与模板 clampCaps 同规则双实现，改动必须两侧同步。范围：main 10~500 / side 50~5000。 */
+function histCapsOf(o) {
+  var c = o && o.histCaps ? o.histCaps : {};
+  var main = Math.round(+c.main), side = Math.round(+c.side);
+  if (!isFinite(main) || main <= 0) main = HIST_MAIN_MAX;
+  if (!isFinite(side) || side <= 0) side = HIST_SIDECAR_MAX;
+  return { main: Math.max(10, Math.min(500, main)), side: Math.max(50, Math.min(5000, side)) };
+}
+
+function docIdOf(htmlText) {
+  var m = htmlText.match(/var DOC_ID\s*=\s*'([^']*)'/);
+  return m ? m[1] : '';
+}
+function histSidePath(htmlPath) {
+  return path.join(path.dirname(htmlPath), HIST_DIR, path.basename(htmlPath) + '.hist.json');
+}
+function readSideHist(htmlPath, expectDoc) {
+  try {
+    var j = JSON.parse(fs.readFileSync(histSidePath(htmlPath), 'utf8'));
+    if (j && Array.isArray(j.entries) && j.DOC_ID === expectDoc) return j;   // 归属校验
+  } catch (e) { /* 不存在/损坏 → 视为无档案 */ }
+  return null;
+}
+function writeSideHist(htmlPath, docId, entries, sideMax) {
+  try {
+    var p = histSidePath(htmlPath);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    var capped = entries.slice(-sideMax);
+    fs.writeFileSync(p, JSON.stringify({
+      annotatableHist: 1, DOC_ID: docId, FILE_NAME: path.basename(htmlPath),
+      rev: capped.length ? capped[capped.length - 1].rev : 0, entries: capped
+    }).replace(/</g, '\\u003c'));
+    return true;
+  } catch (e) { return false; }
+}
+/* v1.31.0：serve 页面写侧车（POST /__annot/hist 的服务端半边）。与读端点对称：
+ * 锁内做 DOC_ID/文件名归属校验（不符=复制文件互染，拒收），条数按盘上 store.histCaps
+ * 收敛（与 commitHistory 同纪律——服务端不认客户端多带的多留要求），复用 writeSideHist 落盘。 */
+function writeHistForFile(target, hist) {
+  if (!hist || !Array.isArray(hist.entries)) return { ok: false, error: 'bad-hist' };
+  var html = '';
+  try { html = fs.readFileSync(target, 'utf8'); } catch (e) { return { ok: false, error: 'no-file' }; }
+  var docId = docIdOf(html);
+  if (!docId) return { ok: false, error: 'no-doc-id' };
+  if (hist.DOC_ID !== docId || hist.FILE_NAME !== path.basename(target)) return { ok: false, error: 'doc-mismatch' };
+  var sideMax = histCapsOf(readStore(html)).side;
+  return withDocLock(target, function () {
+    return writeSideHist(target, docId, hist.entries, sideMax) ? { ok: true } : { ok: false, error: 'write-failed' };
+  });
+}
+
+/* 合并文件内 history 与外置档案（按 rev 去重，文件内优先、档案补 snap/bodyOps），返回全量账本 */
+function mergeHistory(inFileHist, sideEntries) {
+  var byRev = {}, out = [];
+  (inFileHist || []).forEach(function (en) { if (en && !byRev[en.rev]) { byRev[en.rev] = en; out.push(en); } });
+  (sideEntries || []).forEach(function (en) {
+    if (!en) return;
+    if (!byRev[en.rev]) { byRev[en.rev] = en; out.push(en); }
+    else {
+      if (!byRev[en.rev].snap && en.snap) byRev[en.rev].snap = en.snap;
+      /* 大纸条只在外置档案（浏览器端 skelEntry 同规则），并入内存时回填 */
+      if (!byRev[en.rev].bodyOps && en.bodyOps) byRev[en.rev].bodyOps = en.bodyOps;
+    }
+  });
+  out.sort(function (a, b) { return a.rev - b.rev; });
+  return out;
+}
+/* 提交一版：push 新条目 → 写外置档案 → 决定主文件内 history 形态。返回 {full, sideOk} */
+function commitHistory(htmlPath, htmlText, o, newEntry) {
+  o.history.push(newEntry);
+  var caps = histCapsOf(o);
+  var docId = docIdOf(htmlText) || ('doc-unknown-' + path.basename(htmlPath));
+  var side = readSideHist(htmlPath, docId);
+  var full = mergeHistory(o.history, side ? side.entries : null);
+  var sideOk = writeSideHist(htmlPath, docId, full, caps.side);
+  var mainHist;
+  if (sideOk) {
+    mainHist = full.slice(-caps.main).map(function (en) {
+      var c = { rev: en.rev, time: en.time, op: en.op, n: en.n };
+      /* 纸条小随骨架走（正文回滚要用）；>20KB 大纸条（浏览器 Word 模式整节改写）只留外置档案 */
+      if (en.bodyOps && JSON.stringify(en.bodyOps).length <= 20000) c.bodyOps = en.bodyOps;
+      return c;
+    });
+  } else {
+    mainHist = full.slice(-HIST_FALLBACK_MAX);      // 降级：snap 留在主文件（v1.9 行为）
+  }
+  o.history = mainHist;
+  return { full: full, sideOk: sideOk };
+}
+
+function fmtTime(ts) {
+  if (!ts) return '';
+  var d = new Date(ts);
+  function p(x) { return (x < 10 ? '0' : '') + x; }
+  return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate()) + ' ' + p(d.getHours()) + ':' + p(d.getMinutes());
+}
+
+/* ---------- 并发写回防线（v1.26.0，待改进⑮）----------
+ * 浏览器保存与 CLI 写回曾都是无锁「读→改→整文件覆盖」，毫秒级同时落盘后写者胜，
+ * 人类批注被静默冲掉。防线三层：
+ * ① 文档锁 withDocLock：.annotatable/<文件名>.lock 独占创建（wx 标志，已存在即失败），
+ *    持有者写完即删；锁内容 {pid,ts}，持锁>15s 或 pid 已死视为陈锁（持有者暴毙）破门重取；
+ *    serve 模式下 CLI 与服务器两个写入方都走锁 → 完全串行。
+ * ② 原子写 writeDocAtomic：临时文件+rename 覆盖，读方永远读到完整旧版或完整新版；
+ *    Windows rename 撞上正在读的进程（EPERM/EBUSY）小睡重试。
+ * ③ 写票日志 writes.jsonl：锁内每次落盘追加 {writer,rev,ts}，供无锁一方（浏览器 FS 直连
+ *    通道，无法参与独占锁）写后自查「我盖没盖掉别人」，盖了就自动合并重写。
+ * 配套规则：CLI 写回统一「锁内：重读最新→应用变更→写前再验磁盘未变→不符重来→原子写→记票」。
+ * 模板 autosaveNow/serverSaveNow 是本协议的另一端（锁礼让/rev 复验/回读/查票），双实现改动必须两侧同步。 */
+var LOCK_STALE_MS = 15000;
+var LOCK_WAIT_MS = 5000;
+var ANCHOR_SUSPECT_LEN = 2000;   // 锚定怀疑阈值：pos/文档长差异超过它即不可自动裁决（规范化字符）
+function docLockPath(htmlPath) {
+  return path.join(path.dirname(htmlPath), HIST_DIR, path.basename(htmlPath) + '.lock');
+}
+function docWritesLogPath(htmlPath) {
+  return path.join(path.dirname(htmlPath), HIST_DIR, path.basename(htmlPath) + '.writes.jsonl');
+}
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+/* 独占拿锁；成功返回 release 函数，超时抛错。EEXIST 时做陈锁判定（超龄/pid 已死/内容损坏）破门。 */
+function acquireDocLock(htmlPath, opts) {
+  var lockP = docLockPath(htmlPath);
+  var waitMs = (opts && opts.waitMs) || LOCK_WAIT_MS;
+  try { fs.mkdirSync(path.dirname(lockP), { recursive: true }); } catch (e0) { /* 目录已存在 */ }
+  var deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      var fd = fs.openSync(lockP, 'wx');
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      fs.closeSync(fd);
+      var mine = '';
+      try { mine = fs.readFileSync(lockP, 'utf8'); } catch (e1) {}
+      return function release() {
+        try {
+          var cur = fs.readFileSync(lockP, 'utf8');
+          if (!mine || cur === mine) fs.unlinkSync(lockP);   // 只删自己创建的那把（防误删破门后他人的新锁）
+        } catch (e) { /* 锁已被他人接管/删除 → 不管 */ }
+      };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      var stale = false;
+      try {
+        var j = JSON.parse(fs.readFileSync(lockP, 'utf8'));
+        if (!j || Date.now() - (j.ts || 0) > LOCK_STALE_MS) stale = true;
+        else if (typeof j.pid === 'number' && j.pid !== process.pid && !pidAlive(j.pid)) stale = true;
+      } catch (e2) { stale = true; }   // 锁内容损坏 → 视为陈锁
+      if (stale) { try { fs.unlinkSync(lockP); } catch (e3) {} continue; }
+      if (Date.now() >= deadline) throw new Error('文档正被另一写入方持有（等待锁超时 ' + (waitMs / 1000) + 's）：' + lockP);
+      var spin = Date.now() + 120;
+      while (Date.now() < spin) { /* CLI 是同步代码，忙等片刻再试 */ }
+    }
+  }
+}
+function withDocLock(htmlPath, fn, opts) {
+  var release = acquireDocLock(htmlPath, opts);
+  try { return fn(release); } finally { release(); }
+}
+/* 原子写：临时文件 + rename 覆盖。Windows 下目标正被别的进程读取时 rename 报
+ * EPERM/EBUSY——读者寿命都很短（readFileSync 即读即关），小睡重试即可。 */
+function writeDocAtomic(htmlPath, text) {
+  var tmp = htmlPath + '.tmp-' + process.pid + '-' + Math.random().toString(36).slice(2, 6);
+  fs.writeFileSync(tmp, text);
+  for (var i = 0; i < 4; i++) {
+    try { fs.renameSync(tmp, htmlPath); return; }
+    catch (e) {
+      if (i >= 3 || (e.code !== 'EPERM' && e.code !== 'EACCES' && e.code !== 'EBUSY')) {
+        try { fs.unlinkSync(tmp); } catch (e2) { /* temp 残留可容忍 */ }
+        throw e;
+      }
+      var spin = Date.now() + 60;
+      while (Date.now() < spin) { /* 等读者退出 */ }
+    }
+  }
+}
+/* 记写票：锁内每次成功落盘追加一行 {writer,rev,ts}；超长只留尾部，失败不影响写回 */
+function appendWriteTicket(htmlPath, writer, rev) {
+  try {
+    var p = docWritesLogPath(htmlPath);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify({ writer: writer || 'cli', rev: rev, ts: Date.now() }) + '\n');
+    try {
+      var lines = fs.readFileSync(p, 'utf8').split('\n');
+      if (lines.length > 220) fs.writeFileSync(p, lines.slice(-200).join('\n'));
+    } catch (e2) { /* 裁剪失败可容忍 */ }
+  } catch (e) { /* 日志失败不影响写回 */ }
+}
+/* serve 写回的锁内复验 + 原子落盘（serve.js 与测试共用）。
+ * baseRev = 浏览器提交所基于的 rev；null/undefined = 老页面，跳过校验按现状放行。
+ * 返回 { ok:true, rev } 或 { ok:false, conflict:true, diskRev }。 */
+/* v1.37.3 Bug C：serve 整页回传里的 answers-store 可能来自旧加载的内存快照（页面加载后
+ * DOM 里的区块不随 liveAdopt 更新，旧版 buildAnnotatedHTML 又序列化 DOM 旧块），直接落盘
+ * 会把 CLI 新写的教学卡冲掉（实测 P001 卡被清空）。教学卡唯一写方是 CLI（annotatable
+ * answer，区块 rev 单调递增）：锁内比对盘上与回传的区块，回传 rev 落后 → 以盘上为准保留。 */
+function answersBlockOf(htmlText) {
+  var m = htmlText.match(/<script id="answers-store" type="application\/json">\s*([\s\S]*?)\s*<\/script>/);
+  if (!m) return null;
+  var v = null;
+  try { v = JSON.parse(m[1]); } catch (e) { v = null; }
+  if (!v || typeof v !== 'object' || !Array.isArray(v.answers)) v = null;
+  return { m: m, v: v };
+}
+function saveDocHtml(target, html, baseRev, writer) {
+  return withDocLock(target, function () {
+    var disk = '';
+    try { disk = fs.readFileSync(target, 'utf8'); } catch (e) { /* 调用方已保证存在，兜底按空处理 */ }
+    var st = disk ? readStore(disk) : null;
+    var diskRev = st ? (st.rev || 0) : 0;
+    if (baseRev !== null && baseRev !== undefined && diskRev !== baseRev) {
+      return { ok: false, conflict: true, diskRev: diskRev };
+    }
+    /* v1.37.3 Bug C：教学卡字段级保留——盘上有卡（区块可解析）而回传块更旧/损坏 → 回填盘上区块 */
+    var diskAns = disk ? answersBlockOf(disk) : null;
+    if (diskAns && diskAns.v) {
+      var inAns = answersBlockOf(html);
+      if (inAns && inAns.m && (!inAns.v || (inAns.v.rev || 0) < (diskAns.v.rev || 0))) {
+        var keptScript = '<script id="answers-store" type="application/json">\n' + JSON.stringify(diskAns.v).replace(/</g, '\\u003c') + '\n</' + 'script>';
+        html = html.slice(0, inAns.m.index) + keptScript + html.slice(inAns.m.index + inAns.m[0].length);
+      }
+    }
+    writeDocAtomic(target, html);
+    var st2 = readStore(html);
+    var newRev = st2 ? (st2.rev || 0) : 0;
+    appendWriteTicket(target, writer || 'serve', newRev);
+    return { ok: true, rev: newRev };
+  });
+}
+/* 片段规范化：剥标签+解常见实体+压空白（供 bodyOps 纸条与批注 quote 的软比对） */
+function normSnippet(s) {
+  return String(s || '')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&nbsp;/gi, ' ').replace(/&amp;/gi, '&').replace(/&lt;/gi, '<').replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"').replace(/&#39;/gi, "'")
+    .replace(/\s+/g, ' ').trim();
+}
+/* 锚定失效追溯：在侧车账本里找「哪个 rev 的 bodyOps 纸条替换掉了含引用原文的片段」，
+ * 返回 { goneAt, lastWith }（lastWith=回退目标 rev）；账本缺失/无纸条记录返回 null。 */
+function findLastRevWithQuote(htmlPath, docId, quote) {
+  var side = readSideHist(htmlPath, docId);
+  if (!side || !Array.isArray(side.entries)) return null;
+  var q = normSnippet(quote);
+  if (!q) return null;
+  var entries = side.entries.slice().sort(function (a, b) { return (b.rev || 0) - (a.rev || 0); });
+  for (var i = 0; i < entries.length; i++) {
+    var ops = entries[i].bodyOps;
+    if (!Array.isArray(ops)) continue;
+    for (var j = 0; j < ops.length; j++) {
+      if (ops[j] && ops[j].o && normSnippet(ops[j].o).indexOf(q) !== -1) {
+        return { goneAt: entries[i].rev, lastWith: (entries[i].rev || 1) - 1 };
+      }
+    }
+  }
+  return null;
+}
+
+function readStore(t) {
+  var m = t.match(/<script id="annotations-store" type="application\/json">\s*([\s\S]*?)\s*<\/script>/);
+  if (!m) return null;
+  var v;
+  try { v = JSON.parse(m[1]); } catch (e) { return null; }
+  if (Array.isArray(v)) return { rev: 0, annotations: v, history: [] };
+  if (v && Array.isArray(v.annotations)) {
+    return { rev: v.rev || 0, annotations: v.annotations, history: Array.isArray(v.history) ? v.history : [], histCaps: v.histCaps, control: (v.control && typeof v.control === 'object') ? v.control : {} };
+  }
+  return { rev: 0, annotations: [], history: [], control: {} };
+}
+/* v1.29.0 纯高亮静默：没打字的批注（仅划线）不算「待回应」——人类划重点/标记看过，
+ * AI 保持静默；想让 AI 回话就打字（哪怕一个「?」）。有字才算数。 */
+function hasUserText(a) {
+  return (a.thread || []).some(function (t) { return t.role === 'user' && String(t.text || '').trim(); });
+}
+/* store 序列化唯一出口：control 区（stop 打断 / wordLock 编辑旗 / pendingBodyOps 排队 /
+ * replay 重做请求）必须随每次写回透传，丢了旗子排队制就断（v1.29.0） */
+function storePayload(o) {
+  var out = { rev: o.rev, annotations: o.annotations, history: o.history, histCaps: o.histCaps };
+  if (o.control && Object.keys(o.control).length) out.control = o.control;
+  return out;
+}
+
+/* ---------- 页面结构体检（v1.26.3）----------
+ * 背景：v1.26.0 发版时的壳升级脚本曾把调研页烤成「双尾巴 + 丢 </article> + 主脚本裸 </script>
+ * 截断」，腐坏页静默存活两天，直到人类刷新才暴露为全页控件失灵。这类「整段复制/标签被吃」
+ * 腐蚀可能来自任何写手（升级脚本、浏览器写回 bug、手工编辑）。read/reply 是 agent 动笔前后
+ * 必经之门——在这里亮警告，让 AI 在腐坏页上落笔前先看见。只警告不拦截（抢救数据优先于洁癖）。 */
+function lintStructure(htmlText) {
+  var w = [];
+  if (!/<script id="annotations-store"/.test(htmlText)) return w;   // 非批注页不体检
+  ['<aside id="annot-nav"', '<button id="annot-fab"', '<script id="annotations-store"', '<aside id="annot-panel"'].forEach(function (sig) {
+    var n = htmlText.split(sig).length - 1;
+    if (n > 1) w.push('批注层骨架重复 ' + n + ' 份（' + sig + ' …）——疑似整段复制腐蚀，以 rev 最大的一份为数据基准重建壳');
+  });
+  /* article 存在性必须在剥 script 后测：inject 页的 article 字样全在运行时 JS 注释/字符串里
+     （模板源码自含 </article> 字面量），直接全文测=每次 read/reply 假报「闭合丢失」（v1.32.2 实证） */
+  var lintNoScript = htmlText.replace(new RegExp('<' + 'script[\\s\\S]*?<' + '/script>', 'g'), '');
+  if (/<article[\s>]/.test(lintNoScript) &&
+      !/<\/article>\s*(?:<\/div>\s*)?(?:<!--[\s\S]{0,200}?AI批注数据 BEGIN|<script id="annotations-store")/.test(htmlText)) {
+    w.push('article 闭合标签疑似丢失（批注尾巴被吞进正文，正文区可能被污染）');
+  }
+  var ms = htmlText.match(/<script id="annotations-store" type="application\/json">([\s\S]*?)<\/script>/);
+  if (ms) { try { JSON.parse(ms[1]); } catch (e) { w.push('批注数据 store JSON 解析失败：' + e.message); } }
+  if (htmlText.indexOf('</scr' + 'ipt></article') !== -1) w.push('存在裸 </script></article> 序列——主脚本可能被截断（下次解析整层哑火）');
+  if (!/<meta name="annotatable-html"/.test(htmlText)) w.push('无版本 meta（v1.26.1 前旧层页）——建议重建壳升级');
+  /* v1.31.0：通用重复 id 体检——第三方运行时壳被烤入磁盘的典型症状（重载后静态壳+运行时壳
+   * 并存，getElementById 命中静态死元素=控件失灵）。先剥 script 区再扫，防模板/脚本源码字面量假阳性 */
+  var markupOnly = htmlText.replace(/<script[\s\S]*?<\/script>/gi, ' ');
+  var idCount = {};
+  (markupOnly.match(/\sid="[^"]+"/g) || []).forEach(function (m) {
+    var idv = m.slice(5, -1);
+    idCount[idv] = (idCount[idv] || 0) + 1;
+  });
+  var idDups = Object.keys(idCount).filter(function (k) { return idCount[k] > 1; });
+  if (idDups.length) w.push('重复 id ' + idDups.length + ' 个（' + idDups.slice(0, 3).join(' / ') + '）——疑似运行时 DOM 被烤入磁盘（第三方脚本建壳需注册 __annotSaveStrip），重载会双实例撞车');
+  return w;
+}
+function printLintWarnings(htmlText) {
+  var w = lintStructure(htmlText);
+  if (w.length) {
+    console.log('⚠ 结构体检 ' + w.length + ' 项（页面可能被腐蚀，先抢救数据再写回）:');
+    w.forEach(function (x) { console.log('  ! ' + x); });
+  }
+  return w;
+}
+
+/* 列出待回应批注（含完整对话线）。v1.29.0：仅划线（无文字）不进待回应清单，单列计数保持静默 */
+function readPending(htmlPath) {
+  silentUpgrade(htmlPath);   // v1.36.0 触碰即换装：旧层页先升最新层再读（用户无感）
+  var t = fs.readFileSync(htmlPath, 'utf8');
+  var o = readStore(t);
+  if (!o) { console.log('NO_STORE（该文件没有批注区块）'); return; }
+  var neu = o.annotations.filter(function (a) { return a.status !== 'answered' && hasUserText(a); });
+  var marks = o.annotations.filter(function (a) { return a.status !== 'answered' && !hasUserText(a); });
+  console.log('文件: ' + htmlPath);
+  console.log('rev=' + o.rev + ' · 总批注=' + o.annotations.length + ' · 待回应=' + neu.length + ' · 版本记录=' + o.history.length);
+  var gapNote = watchGapNote(htmlPath, neu.map(function (a) { return a.created || 0; }));
+  if (gapNote) console.log(gapNote);   // v1.33.0 断档补捞：值守离线期收到的批注一眼定优先级
+  printLintWarnings(t);
+  var replay = o.control && o.control.replay;
+  if (replay) {
+    console.log('⚠ 排队正文改动待重做 ' + ((replay.ops || []).length) + ' 处（人类随后大改正文，原文锚不上）——请重读正文，基于新文重新生成这些改动再 annot_edit 提交（提交即视为已处理）:');
+    (replay.ops || []).forEach(function (s, i) {
+      var o0 = String(s.o || ''), n0 = String(s.n == null ? '' : s.n);
+      console.log('  [' + (i + 1) + '] 原:「' + (o0.length > 40 ? o0.slice(0, 40) + '…' : o0) + '」 新:「' + (n0.length > 40 ? n0.slice(0, 40) + '…' : n0) + '」');
+    });
+  }
+  neu.forEach(function (a, i) {
+    var streaming = (a.thread || []).some(function (x) { return x.role === 'ai' && x.streaming; });
+    console.log('---【' + (i + 1) + '】id=' + a.id + (a.section ? ' §' + a.section : '') + (a.scope ? ' （AI回答子批注，父=' + a.scope + '）' : '') + (streaming ? ' ⏳流式作答中' : '') + '（' + relTime(a.created) + '创建）');
+    console.log('原句:', a.quote);
+    console.log('上下文: …' + (a.prefix || '') + '⟨原句⟩' + (a.suffix || '') + '…');
+    console.log('对话线（共 ' + ((a.thread || []).length) + ' 轮）:');
+    (a.thread || []).forEach(function (x) {
+      console.log('  [' + (x.role === 'ai' ? 'AI' : '你') + '] ' + x.text);
+    });
+    if (!a.thread || !a.thread.length) console.log('  [你] ' + (a.comment || '(仅划线)'));
+  });
+  if (!neu.length) console.log('（无待回应批注）');
+  if (marks.length) console.log('（另有 ' + marks.length + ' 条仅划线批注：人类划重点，保持静默，无需回应）');
+}
+function relTime(ts) {
+  if (!ts) return '未知时间';
+  var d = Date.now() - ts;
+  if (d < 60e3) return Math.max(1, Math.round(d / 1e3)) + '秒前';
+  if (d < 3600e3) return Math.round(d / 60e3) + '分钟前';
+  if (d < 86400e3) return Math.round(d / 3600e3) + '小时前';
+  return Math.round(d / 86400e3) + '天前';
+}
+
+/* ---------- 值守心跳（v1.33.0，issue#6）----------
+ * poll 生存期写 .annotatable/<文件名>.watch.json：{pid,file,startedAt,lastBeat,state}。
+ * state 'watching'=在岗轮询（每 tick 续跳）；退出（命中/超时）改写 'handoff'=已交班。
+ * serve /__annot/status 与页面值守灯据此区分 在岗/心跳超龄/换班中/无人值守；
+ * watchGapNote 对比 pending 批注出生时间与最后心跳，read/poll 报「值守离线期收到 N 条」
+ * ＝断档补捞（两班之间收到的批注不再只靠进程考古才发现）。 */
+function watchBeatPath(htmlPath) {
+  return path.join(path.dirname(htmlPath), HIST_DIR, path.basename(htmlPath) + '.watch.json');
+}
+function readWatchBeat(htmlPath) {
+  try { return JSON.parse(fs.readFileSync(watchBeatPath(htmlPath), 'utf8')); } catch (e) { return null; }
+}
+function writeWatchBeat(htmlPath, state, startedAt) {
+  try {
+    fs.mkdirSync(path.join(path.dirname(htmlPath), HIST_DIR), { recursive: true });
+    fs.writeFileSync(watchBeatPath(htmlPath), JSON.stringify({
+      pid: process.pid, file: path.basename(htmlPath),
+      startedAt: startedAt || Date.now(), lastBeat: Date.now(), state: state
+    }));
+  } catch (e) { /* 心跳尽力而为：档案目录不可写不阻塞值守 */ }
+}
+function watchGapNoteFrom(beat, createdArr) {
+  if (!beat || !beat.lastBeat || !Array.isArray(createdArr) || !createdArr.length) return '';
+  var missed = createdArr.filter(function (ts) { return ts > beat.lastBeat; });
+  if (!missed.length) return '';
+  var oldest = Math.min.apply(null, missed);
+  return '⚠ 值守离线期收到 ' + missed.length + ' 条批注（最后心跳 ' + relTime(beat.lastBeat) +
+    '，最早一条 ' + relTime(oldest) + '创建）——断档期间无人监听，请优先处理';
+}
+function watchGapNote(htmlPath, createdArr) {
+  return watchGapNoteFrom(readWatchBeat(htmlPath), createdArr);
+}
+
+/* ---------- poll：挂起等待新批注（v1.11.0，借鉴 human-review 的 poll 等待体验）----------
+ * 供 agent 配 harness 后台任务使用：无待回应批注时阻塞轮询，人类划线批注保存后
+ * 打印 POLL_HIT <json> 并以 0 退出唤醒 agent；--timeout 秒数到点以 3 退出。
+ * 轮询只比对 {rev,总数,待回应} 签名，文件被写盘中（EBUSY 等）时静默跳过本轮。
+ * v1.29.0：①仅划线（无文字）不响铃不计数（纯高亮静默）；②铃带每条批注的出生时间
+ * （agent 可自判「这条刚出生」）；③排队正文改动重做请求（control.replay）同样响铃。 */
+function pendingState(htmlPath) {
+  var o = readStore(fs.readFileSync(htmlPath, 'utf8'));
+  if (!o) return null;
+  var neu = o.annotations.filter(function (a) { return a.status !== 'answered' && hasUserText(a); });
+  return {
+    rev: o.rev || 0, total: o.annotations.length, pending: neu.length, ids: neu.map(function (a) { return a.id; }),
+    created: neu.map(function (a) { return a.created || 0; }),
+    replay: (o.control && o.control.replay) || null
+  };
+}
+function pollAnnotations(htmlPath, opts) {
+  silentUpgrade(htmlPath);   // v1.36.0 值守挂上即换装：旧层页先升最新层再开等
+  opts = opts || {};
+  var intervalSec = Math.max(1, parseInt(opts.interval, 10) || 3);
+  var timeoutSec = parseInt(opts.timeout, 10) || 0;   // 0 = 一直等
+  var startedAt = Date.now();
+  var st = pendingState(htmlPath);
+  if (!st) throw new Error('NO_STORE（该文件没有批注区块）');
+  var prevBeat = readWatchBeat(htmlPath);   // 上一班心跳（补捞基线）——必须在本班开跳前取走，否则被自己的心跳冲掉（探针揪出）
+  writeWatchBeat(htmlPath, 'watching', startedAt);
+  console.log('文件: ' + htmlPath);
+  console.log('rev=' + st.rev + ' · 总批注=' + st.total + ' · 待回应=' + st.pending + (st.replay ? ' · ⚠有排队正文改动待重做' : ''));
+  var gap0 = watchGapNoteFrom(prevBeat, st.created);
+  if (gap0) console.log(gap0);
+  function hit(s) {
+    var gap = watchGapNoteFrom(prevBeat, s.created);
+    if (gap) console.log(gap);
+    writeWatchBeat(htmlPath, 'handoff', startedAt);   // 退出前留交班心跳：页面灯据此显示「换班中/无人值守 X 分钟」
+    var payload = { file: htmlPath, rev: s.rev, pending: s.pending, ids: s.ids, created: s.created };
+    if (s.replay) payload.replay = s.replay;
+    console.log('POLL_HIT ' + JSON.stringify(payload));
+    process.exit(0);
+  }
+  if (st.pending || st.replay) hit(st);
+  console.log('已有批注都已回应，等待新批注…（每 ' + intervalSec + 's 检查' + (timeoutSec ? '，最长 ' + timeoutSec + 's' : '') + '，Ctrl+C 退出）');
+  var lastSig = st.rev + ':' + st.total + ':' + st.pending + ':' + (st.replay ? st.replay.at : 0);
+  var deadline = timeoutSec > 0 ? Date.now() + timeoutSec * 1000 : 0;
+  return setInterval(function () {
+    var s2;
+    try { s2 = pendingState(htmlPath); } catch (e) { return; }   // 写盘中 → 下轮再看
+    if (!s2) return;
+    writeWatchBeat(htmlPath, 'watching', startedAt);   // v1.33.0 心跳：进程活着的可观测证据（死了一跳就停）
+    var sig = s2.rev + ':' + s2.total + ':' + s2.pending + ':' + (s2.replay ? s2.replay.at : 0);
+    if (sig !== lastSig) {
+      lastSig = sig;
+      if (s2.pending > 0 || s2.replay) hit(s2);   // rev 变了但无新批注且无重做请求（如 AI 自己写回）→ 静默继续
+    }
+    if (deadline && Date.now() > deadline) {
+      writeWatchBeat(htmlPath, 'handoff', startedAt);
+      console.log('TIMEOUT · 待回应=' + s2.pending); process.exit(3);
+    }
+  }, intervalSec * 1000);
+}
+
+/* 把 AI 回复追加为 ai 轮次，维护镜像/状态/快照/rev。
+ * v1.26.0：全程持文档锁；写前复验磁盘未变（被浏览器抢先落盘则在最新状态上重放同一批回复，
+ * 幂等：按 id 覆盖式追加）；原子写+记写票。目标批注已被删除 → 跳过并在输出明报，不整单失败。 */
+function applyReplies(htmlPath, repliesPath) {
+  silentUpgrade(htmlPath);   // v1.36.0 触碰即换装
+  if (wordLockActive(fs.readFileSync(htmlPath, 'utf8'))) {   // v1.37.0 编辑礼让：人类举旗期间回复不落盘
+    console.log('WORD_MODE 人类编辑中（wordLock 旗鲜活）：回复挂起不落盘，等收笔再发');
+    process.exitCode = 6;
+    return { status: 'wordmode' };
+  }
+  var replies = JSON.parse(fs.readFileSync(repliesPath, 'utf8'));
+  printLintWarnings(fs.readFileSync(htmlPath, 'utf8'));   // v1.26.3：落笔前体检，腐坏页先暴露
+  var out = withDocLock(htmlPath, function () {
+    var attempt = 0;
+    for (;;) {
+      attempt++;
+      var t = fs.readFileSync(htmlPath, 'utf8');
+      var m = t.match(/(<script id="annotations-store" type="application\/json">\s*)([\s\S]*?)(\s*<\/script>)/);
+      if (!m) throw new Error('NO_STORE（未找到批注区块）');
+      var o = JSON.parse(m[2]);
+      if (!Array.isArray(o.history)) o.history = [];
+      var by = {}, emptySkip = [];
+      replies.forEach(function (r) {
+        /* v1.29.0 空回复防呆：空串回复落盘就是空气泡，拒绝而非静默入账 */
+        if (typeof r.reply === 'string' && !r.reply.trim()) { emptySkip.push(r.id); return; }
+        by[r.id] = r.reply;
+      });
+      var n = 0, missing = [];
+      o.annotations.forEach(function (a) {
+        if (by[a.id] === undefined) return;
+        if (!Array.isArray(a.thread)) {
+          a.thread = [];
+          if (a.comment) a.thread.push({ role: 'user', text: a.comment, time: a.created || Date.now() });
+        }
+        if (!a.thread.length) a.thread.push({ role: 'user', text: a.comment || '', time: a.created || Date.now() });
+        a.thread.forEach(function (x) { if (x.role === 'ai' && x.streaming) delete x.streaming; });   // v1.37.3：该批注残留的流式轮旗全部落定（旧版只摘最后一轮）
+        a.thread.push({ role: 'ai', text: by[a.id], time: Date.now() });
+        a.reply = by[a.id];
+        if (!a.comment && a.thread[0]) a.comment = a.thread[0].text;
+        a.status = 'answered';
+        n++;
+      });
+      replies.forEach(function (r) { if (!o.annotations.some(function (a) { return a.id === r.id; })) missing.push(r.id); });
+      if (o.control) delete o.control.stop;   // AI 正式写回 = 值守在岗，打断标志随之失效
+      /* 写前复验：读取期间磁盘又被写（浏览器抢先保存）→ 丢掉本次结果，在最新状态上重来 */
+      var diskNow = fs.readFileSync(htmlPath, 'utf8');
+      if (diskNow !== t && attempt < 8) continue;
+      if (diskNow !== t) throw new Error('并发写回冲突：重试 8 轮磁盘仍在变化，本轮未写盘（稍后重试即可）');
+      var res = null, sideNote = '';
+      if (n > 0) {
+        o.rev = (o.rev || 0) + 1;
+        res = commitHistory(htmlPath, t, o, {
+          rev: o.rev, time: Date.now(), op: 'AI回应 ' + n + ' 条', n: o.annotations.length,
+          snap: JSON.parse(JSON.stringify(o.annotations))
+        });
+        sideNote = res.sideOk
+          ? '（全量账本 → ' + HIST_DIR + '/' + path.basename(htmlPath) + '.hist.json）'
+          : '（外置档案不可写，快照保留在主文件）';
+      }
+      var t2 = t.replace(m[0], m[1] + '\n' + JSON.stringify(storePayload(o)).replace(/</g, '\\u003c') + '\n' + m[3]);
+      writeDocAtomic(htmlPath, t2);
+      if (n > 0) appendWriteTicket(htmlPath, 'cli', o.rev);
+      return { n: n, rev: o.rev, missing: missing, emptySkip: emptySkip, sideNote: sideNote, histLen: res ? res.full.length : o.history.length };
+    }
+  });
+  console.log('已追加 ' + out.n + ' 条 AI 回复 · rev=' + out.rev + ' · 版本记录=' + out.histLen + ' ' + out.sideNote);
+  if (out.missing.length) console.log('⚠️ 未找到的批注id（可能已被删除，已跳过）: ' + out.missing.join(', '));
+  if (out.emptySkip.length) {
+    console.log('⛔ ' + out.emptySkip.length + ' 条空回复被拒绝（回复前请重读批注；每条批注最后 AI 轮必须非空）: ' + out.emptySkip.join(', '));
+    process.exitCode = 2;
+  }
+}
+
+/* ---------- 流式回答（v1.21.0）----------
+ * 值守协议的作答通道：agent 每生成一段就调一次，页面 live-sync 实时渲染出
+ * 打字中的回答；人类点「⏹ 停止」会把 control.stop 写进文件，下一次追加就地
+ * 终止；批注被整条删除 → 目标消失，同样终止。返回 {status, annId, rev}：
+ *   ok           追加/开始/收尾成功
+ *   interrupted  人类已打断（本轮作答到此为止，agent 不应再追加）
+ *   target-gone  目标批注已被删除/不存在
+ *   no-stream    没有进行中的流式轮（未带 id 的追加找不到落点）
+ * rev 每次写入 +1（浏览器靠 rev 防互相覆盖）；history 只在 流开始/收尾/打断
+ * 三种节点记账——中间段不进账本，防骨架账本被长回答刷爆；收尾/打断条目持有
+ * 全量快照，回滚语义不变。 */
+function findStreamTurn(o, annId) {
+  var hit = null;
+  o.annotations.forEach(function (a) {
+    if (annId && a.id !== annId) return;
+    (a.thread || []).forEach(function (x) {
+      if (x.role === 'ai' && x.streaming) {
+        /* v1.37.3：按开始时间取最近——旧版按数组序取最后一条，多开流式轮/残留轮时
+           不带 --id 的续段会串线到早已收尾的批注（实测三次）。时间缺失退数组序（保底）。 */
+        if (!hit || ((x.time || 0) >= (hit.turn.time || 0))) hit = { ann: a, turn: x };
+      }
+    });
+  });
+  return hit;
+}
+/* v1.37.3：流式轮全系统至多一条打开。开始新流/收尾/打断时，把其他批注上遗留的打开轮
+   就地封轮（摘 streaming 旗，已写文本保留）——残留打开轮是不带 --id 续段串线的根源。 */
+function closeOrphanStreams(o, keepAnnId) {
+  var closed = [];
+  o.annotations.forEach(function (a) {
+    if (keepAnnId && a.id === keepAnnId) return;
+    (a.thread || []).forEach(function (x) {
+      if (x.role === 'ai' && x.streaming) { delete x.streaming; if (closed.indexOf(a.id) === -1) closed.push(a.id); }
+    });
+  });
+  return closed;
+}
+/* 摘掉一条批注线程里全部 streaming 旗（end/打断后兜底，防旧版多旗残留漏摘） */
+function clearAnnStreamFlags(a) {
+  (a.thread || []).forEach(function (x) { if (x.role === 'ai' && x.streaming) delete x.streaming; });
+}
+function streamBuild(t, m, o) {
+  var out = { rev: o.rev, annotations: o.annotations, history: o.history, histCaps: o.histCaps };
+  if (o.control && Object.keys(o.control).length) out.control = o.control;
+  return t.replace(m[0], m[1] + '\n' + JSON.stringify(out).replace(/</g, '\\u003c') + '\n' + m[3]);
+}
+function streamReply(htmlPath, opts) {
+  opts = opts || {};
+  var text = String(opts.text == null ? '' : opts.text);
+  if (!text && !opts.end) return { status: 'empty' };   // 空段落是误调用，别烧掉打断标志也别建空轮
+  silentUpgrade(htmlPath);   // v1.36.0 触碰即换装（误调用不升，真作答先升）
+  if (wordLockActive(fs.readFileSync(htmlPath, 'utf8'))) return { status: 'wordmode' };   // v1.37.0 编辑礼让：举旗期间不落盘
+  /* v1.26.0：每段写入都持锁+写前复验（人在流式期间插追问/保存 → 段与段都落在最新状态上，线程交错但零丢失） */
+  return withDocLock(htmlPath, function () {
+    var attempt = 0;
+    for (;;) {
+      attempt++;
+      var t = fs.readFileSync(htmlPath, 'utf8');
+      var m = t.match(/(<script id="annotations-store" type="application\/json">\s*)([\s\S]*?)(\s*<\/script>)/);
+      if (!m) throw new Error('NO_STORE（未找到批注区块）');
+      var o = JSON.parse(m[2]);
+      if (!Array.isArray(o.history)) o.history = [];
+      if (!o.control || typeof o.control !== 'object') o.control = {};
+      var stopped = !!o.control.stop;
+      var hit = findStreamTurn(o, opts.id || null);
+      var book = null;   // 需要记账（history 条目）的分支在这里备料
+      /* 打断优先：有人按过 ⏹ 且存在进行中的流式轮 → 本次写入就地终止它 */
+      if (stopped && hit) {
+        delete hit.turn.streaming;
+        hit.turn.interrupted = true;
+        clearAnnStreamFlags(hit.ann);   // v1.37.3：同线程残余旗一并摘（旧版多旗残留兜底）
+        var closedI = closeOrphanStreams(o, hit.ann.id);
+        delete o.control.stop;
+        o.rev = (o.rev || 0) + 1;
+        book = { op: 'AI回应被打断', done: false, status: 'interrupted', annId: hit.ann.id, closed: closedI };
+      } else {
+        if (stopped) delete o.control.stop;   // 陈旧标志（已无流式轮）：清掉不拦新回答
+        if (opts.end) {
+          var ann = null;
+          var keptStream = false;
+          if (hit) {
+            /* v1.29.0 空收尾防呆：收尾没带全文＝误调用，保留已流式内容收尾，绝不静默清空 */
+            if (!text && (hit.turn.text || '').length) { text = hit.turn.text; keptStream = true; }
+            ann = hit.ann;
+            delete hit.turn.streaming; hit.turn.text = text;
+          }
+          else if (opts.id) {
+            if (!text) return { status: 'empty-end' };   // 没有流式轮还收空尾＝要落一条空回答，拒绝
+            ann = o.annotations.find(function (a) { return a.id === opts.id; });
+            if (!ann) return { status: 'target-gone', annId: opts.id };
+            ann.thread.push({ role: 'ai', text: text, time: Date.now() });   // 没 start 就 end：按一次性回答落
+          } else return { status: 'no-stream' };
+          clearAnnStreamFlags(ann);   // v1.37.3：目标线程残余旗兜底摘净
+          var closedE = closeOrphanStreams(o, ann.id);   // v1.37.3：别的批注上遗留的打开轮就地封轮
+          ann.status = 'answered';
+          ann.reply = text;
+          o.rev = (o.rev || 0) + 1;
+          book = { op: 'AI回应', done: true, status: 'ok', annId: ann.id, kept: keptStream, closed: closedE };
+        } else if (hit) {
+          hit.turn.text += text;
+          o.rev = (o.rev || 0) + 1;
+        } else {
+          if (!opts.id) return { status: 'no-stream' };
+          var ann2 = o.annotations.find(function (a) { return a.id === opts.id; });
+          if (!ann2) return { status: 'target-gone', annId: opts.id };
+          var closedS = closeOrphanStreams(o, ann2.id);   // v1.37.3：新流开始前封掉全部遗留打开轮（不变量：至多一条）
+          if (!Array.isArray(ann2.thread)) ann2.thread = [];
+          ann2.thread.push({ role: 'ai', text: text, time: Date.now(), streaming: true });
+          ann2.status = 'answered';
+          o.rev = (o.rev || 0) + 1;
+          book = { op: 'AI回应(流式开始)', done: false, status: 'ok', annId: ann2.id, started: true, closed: closedS };
+        }
+      }
+      /* 写前复验：读取期间磁盘被写（人类追问抢先保存）→ 在最新状态上重放本段 */
+      var diskNow = fs.readFileSync(htmlPath, 'utf8');
+      if (diskNow !== t && attempt < 8) continue;
+      if (diskNow !== t) throw new Error('并发写回冲突：重试 8 轮磁盘仍在变化，本段未写盘（下一段会带上重试）');
+      if (book) {
+        /* 记账（开始/收尾/打断三种节点）在序列化前：骨架随本次落盘，单次原子写 */
+        commitHistory(htmlPath, t, o, {
+          rev: o.rev, time: Date.now(), op: book.op, n: o.annotations.length,
+          snap: JSON.parse(JSON.stringify(o.annotations))
+        });
+      }
+      var t2 = streamBuild(t, m, o);
+      writeDocAtomic(htmlPath, t2);
+      appendWriteTicket(htmlPath, 'cli', o.rev);
+      if (book) return { status: book.status, annId: book.annId, rev: o.rev, done: !!book.done, started: !!book.started, kept: !!book.kept, closed: book.closed || [], chars: book.kept ? text.length : undefined };
+      return { status: 'ok', annId: (hit ? hit.ann.id : null), rev: o.rev };
+    }
+  });
+}
+
+/* ---------- answer：长答/教学卡写入（v1.18.0）----------
+ * answers-store 与批注 store 分离成两个区块：agent 读待回应批注只读 annotations-store，
+ * 不必吞教学全文；页面只读渲染（回答大页教学卡），浏览器保存原样保留区块，写方只有本工具。
+ * 合并语义：entry.id 命中 → 整卡替换；annId+title 命中 → 整卡替换（「继续」时全量带上旧阶+新阶）；否则新增。
+ * 账本：annotations-store rev+1 + history 快照——教学写入也是一次文件写回，浏览器靠 rev 防互相覆盖。 */
+function readAnswers(t) {
+  var m = t.match(/<script id="answers-store" type="application\/json">\s*([\s\S]*?)\s*<\/script>/);
+  if (!m) return null;
+  var v;
+  try { v = JSON.parse(m[1]); } catch (e) { return null; }
+  if (v && Array.isArray(v.answers)) return { rev: v.rev || 0, answers: v.answers };
+  return { rev: 0, answers: [] };
+}
+
+function validateAnswerEntry(e, i) {
+  if (!e || typeof e !== 'object' || Array.isArray(e)) return '第 ' + (i + 1) + ' 条不是对象';
+  if (!Array.isArray(e.rungs) || !e.rungs.length) return '第 ' + (i + 1) + ' 条（' + (e.title || '无标题') + '）rungs 为空数组';
+  for (var j = 0; j < e.rungs.length; j++) {
+    var r = e.rungs[j];
+    if (!r || typeof r !== 'object' || typeof r.body !== 'string' || !r.body.trim())
+      return '第 ' + (i + 1) + ' 条第 ' + (j + 1) + ' 阶缺 body（阶正文必填）';
+  }
+  return null;
+}
+
+/* 列出教学卡（annotatable answer 不带 json 参数时）：agent「继续」前先看既有阶次 */
+function listAnswers(htmlPath) {
+  var t = fs.readFileSync(htmlPath, 'utf8');
+  var a = readAnswers(t);
+  if (!a) { console.log('NO_ANSWERS（该文件没有教学区块，agent 直接写入即可）'); return; }
+  console.log('文件: ' + htmlPath);
+  console.log('教学卡 rev=' + a.rev + ' · 共 ' + a.answers.length + ' 张');
+  a.answers.forEach(function (x, i) {
+    console.log('---【' + (i + 1) + '】id=' + x.id + (x.annId ? ' · 批注=' + x.annId : '') + ' · ' + (x.rungs || []).length + ' 阶 · ' + fmtTime(x.created));
+    console.log('    ' + (x.title || '(无标题)'));
+    (x.rungs || []).forEach(function (r, j) {
+      console.log('    阶' + (j + 1) + ': ' + (r.title || '(无阶标题)') + (r.checkpoint ? ' ＋检查点' : ''));
+    });
+  });
+  if (!a.answers.length) console.log('（暂无教学卡）');
+}
+
+function applyAnswers(htmlPath, answersPath) {
+  silentUpgrade(htmlPath);   // v1.36.0 触碰即换装
+  if (wordLockActive(fs.readFileSync(htmlPath, 'utf8'))) {   // v1.37.0 编辑礼让：人类举旗期间教学卡不落盘
+    console.log('WORD_MODE 人类编辑中（wordLock 旗鲜活）：教学卡挂起不落盘，等收笔再发');
+    process.exitCode = 6;
+    return { status: 'wordmode' };
+  }
+  var entries = JSON.parse(fs.readFileSync(answersPath, 'utf8'));
+  if (!Array.isArray(entries)) throw new Error('answers.json 顶层须为数组：[{ annId, title, rungs: [{ title, body, checkpoint?, answer? }] }]');
+  for (var i = 0; i < entries.length; i++) {
+    var verr = validateAnswerEntry(entries[i], i);
+    if (verr) throw new Error(verr);
+  }
+  /* v1.26.0：持锁+写前复验+原子写（教学写入也是一次文件写回，同样不许冲掉并发的人类批注） */
+  var out = withDocLock(htmlPath, function () {
+    var attempt = 0;
+    for (;;) {
+      attempt++;
+      var t = fs.readFileSync(htmlPath, 'utf8');
+      var m = t.match(/(<script id="annotations-store" type="application\/json">\s*)([\s\S]*?)(\s*<\/script>)/);
+      if (!m) throw new Error('NO_STORE（未找到批注区块）');
+      var o = JSON.parse(m[2]);
+      if (!Array.isArray(o.history)) o.history = [];
+      var a0 = readAnswers(t) || { rev: 0, answers: [] };
+
+      var nIns = 0, nUpd = 0;
+      entries.forEach(function (e, idx) {
+        var hit = null;
+        if (e.id) hit = a0.answers.filter(function (x) { return x.id === e.id; })[0];
+        if (!hit && e.annId) hit = a0.answers.filter(function (x) { return x.annId === e.annId && (x.title || '') === (e.title || ''); })[0];
+        var clean = {
+          id: hit ? hit.id : ('ans-' + Date.now().toString(36) + '-' + idx + Math.random().toString(36).slice(2, 5)),
+          annId: e.annId || (hit ? hit.annId : '') || '',
+          title: e.title || (hit ? hit.title : '') || '',
+          rungs: e.rungs.map(function (r) {
+            var rr = { title: r.title || '', body: r.body };
+            if (r.checkpoint) rr.checkpoint = r.checkpoint;
+            if (r.answer) rr.answer = r.answer;
+            return rr;
+          }),
+          created: hit ? hit.created : Date.now()
+        };
+        if (hit) { a0.answers[a0.answers.indexOf(hit)] = clean; nUpd++; }
+        else { a0.answers.push(clean); nIns++; }
+      });
+
+      var missing = [];
+      entries.forEach(function (e) {
+        if (e.annId && !o.annotations.some(function (a) { return a.id === e.annId; })) missing.push(e.annId);
+      });
+
+      /* 写前复验：读取期间磁盘又被写 → 在最新状态上重放 */
+      var diskNow = fs.readFileSync(htmlPath, 'utf8');
+      if (diskNow !== t && attempt < 8) continue;
+      if (diskNow !== t) throw new Error('并发写回冲突：重试 8 轮磁盘仍在变化，本轮未写盘（稍后重试即可）');
+
+      var sideNote = '';
+      if (nIns + nUpd > 0) {
+        o.rev = (o.rev || 0) + 1;
+        var res = commitHistory(htmlPath, t, o, {
+          rev: o.rev, time: Date.now(), op: '🎓 教学卡 ' + (nIns + nUpd) + ' 条', n: o.annotations.length,
+          snap: JSON.parse(JSON.stringify(o.annotations))
+        });
+        sideNote = res.sideOk
+          ? '（全量账本 → ' + HIST_DIR + '/' + path.basename(htmlPath) + '.hist.json）'
+          : '（外置档案不可写，快照保留在主文件）';
+        a0.rev = (a0.rev || 0) + 1;
+      }
+
+      var scriptOpen = '<script id="answers-store" type="application/json">';
+      var scriptClose = '</' + 'script>';
+      var newScript = scriptOpen + '\n' + JSON.stringify({ rev: a0.rev, answers: a0.answers }).replace(/</g, '\\u003c') + '\n' + scriptClose;
+      /* 批注区块与教学区块基于同一份原文一次性重写：rev+1+history 骨架落主文件，
+         否则浏览器拿旧 rev 会误判无外部修改；answers 区块不存在时随后插入（老文件补建） */
+      var annotNew = m[1] + '\n' + JSON.stringify({ rev: o.rev, annotations: o.annotations, history: o.history, histCaps: o.histCaps }).replace(/</g, '\\u003c') + '\n' + m[3];
+      var am0 = t.match(/(<script id="answers-store" type="application\/json">\s*)([\s\S]*?)(\s*<\/script>)/);
+      var t2;
+      if (am0) {
+        t2 = t.replace(m[0], function () { return annotNew; });
+        t2 = t2.replace(am0[0], function () { return newScript; });
+      } else {
+        var block = '<!-- ═══ AI教学数据 BEGIN — agent 用 annotatable answer 写入；页面只读；浏览器保存原样保留 ═══ -->\n' +
+          newScript + '\n<!-- ═══ AI教学数据 END ═══ -->';
+        t2 = t.replace(m[0], function () { return annotNew + '\n\n' + block; });
+      }
+      writeDocAtomic(htmlPath, t2);
+      if (nIns + nUpd > 0) appendWriteTicket(htmlPath, 'cli', o.rev);
+      return { nIns: nIns, nUpd: nUpd, rev: o.rev, ansRev: a0.rev, total: a0.answers.length, sideNote: sideNote, missing: missing };
+    }
+  });
+  console.log('已写入教学卡：新增 ' + out.nIns + ' · 更新 ' + out.nUpd + ' · 批注 rev=' + out.rev + ' · 教学 rev=' + out.ansRev + ' · 卡总数=' + out.total + ' ' + out.sideNote);
+  if (out.missing.length) console.log('⚠️ 未找到关联的批注id（annId 可能已失效）: ' + out.missing.join(', '));
+}
+
+/* ---------- teach：从源文档批注生成教学文档脚手架（v1.18.0）----------
+ * CLI 没有 AI：本命令把源文档的批注（原句+批语）按主题铺成分节骨架（每节含 原句引用块 +
+ * 教学正文占位 + 检查点占位），agent 随后用 annotatable edit 逐节填充（走锚定管线、入版本账本）；
+ * 产物是完整可批注 HTML（同模板同主题机制），批注循环与源文档相互独立。 */
+function teachDoc(srcPath, opts, pkgRoot) {
+  opts = opts || {};
+  var src = path.resolve(srcPath || '');
+  if (!fs.existsSync(src)) throw new Error('找不到源文档: ' + src);
+  var t = fs.readFileSync(src, 'utf8');
+  var o = readStore(t);
+  if (!o || !o.annotations.length) throw new Error('源文档没有任何批注——先在浏览器里划线批注，再生成教学文档');
+  var name = opts.out ||
+    path.join(path.dirname(src), path.basename(src).replace(/\.html?$/i, '') + '-教学.html');
+  if (!/\.html?$/i.test(name)) name += '.html';
+  var dst = path.resolve(name);
+  if (fs.existsSync(dst)) throw new Error('文件已存在: ' + dst);
+
+  var rsl = resolveTemplate(path.dirname(dst), pkgRoot, opts);
+  var tpl = rsl.tpl, tplSrc = rsl.src;
+  var theme = loadThemeChain(path.dirname(dst), opts);
+  tpl = applyTheme(tpl, theme);
+
+  function esc(s) { return String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'); }
+  function cutTitle(s, n) { s = String(s || '').replace(/\s+/g, ' ').trim(); n = n || 26; return s.length > n ? s.slice(0, n) + '…' : s; }
+
+  var srcTitle = '';
+  var tm = t.match(/<title>([\s\S]*?)<\/title>/);
+  if (tm) srcTitle = tm[1].replace(/<[^>]+>/g, '').trim();
+  var title = (opts.title || srcTitle || path.basename(dst).replace(/\.html?$/i, '')) + ' · 教学版';
+  var docSeed = Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
+
+  var body = '<h1>' + esc(title) + '</h1>\n';
+  body += '<section data-title="来源与用法" id="sec-src">\n';
+  body += '<h2>📋 来源与用法</h2>\n';
+  body += '<p>本文档由源文档 <strong>' + esc(path.basename(src)) + '</strong> 的批注汇总生成（' + o.annotations.length + ' 个主题）。两个文档的批注循环相互独立：在这里划线批注 = 对教学本身提问或纠偏；回到原文语境请打开源文件。</p>\n';
+  body += '<p>agent 将用 <code>annotatable edit</code> 逐节替换下面的占位段落（锚定自动重算、每节入版本账本可回滚）。批语含「继续」= 推进下一节；「重讲」= 本节换一种讲法。</p>\n';
+  body += '</section>\n';
+
+  /* 每节预置一条任务批注（锚定在占位段上）：agent 无需等待人类批注即可 edit 填充，
+     填充后该批注自动变成这一节的讨论线（锚定随 newText 重算） */
+  var teachAnns = [];
+  o.annotations.forEach(function (a, i) {
+    var q = '';
+    (a.thread || []).forEach(function (x) { if (x.role === 'user' && x.text) q = x.text; });
+    if (!q) q = a.comment || '';
+    var st = a.status === 'answered' ? '（已回应过——本次教学可更系统）' : '（待回应——回答时引用本文档）';
+    var ph = '（agent 待撰写：围绕「' + cutTitle(q || a.quote, 30) + '」分阶展开——从动机讲到机制再落到边界与失效场景，每阶结尾给一个检查点。）' + st;
+    body += '<section data-title="' + esc((i + 1) + '. ' + cutTitle(q || a.quote)) + '" id="sec-t' + (i + 1) + '">\n';
+    body += '<h2>❓ ' + (i + 1) + '. ' + esc(cutTitle(q || a.quote, 44)) + '</h2>\n';
+    body += '<blockquote><p><strong>原句：</strong>' + esc(a.quote) + '</p>' + (q ? '<p><strong>批语：</strong>' + esc(q) + '</p>' : '') + '</blockquote>\n';
+    body += '<p>' + esc(ph) + '</p>\n';
+    body += '<p><strong>✅ 检查点（占位）：</strong>学完本节，不看原文回答：这一节的核心机制是什么？它在哪里失效？</p>\n';
+    body += '</section>\n';
+    teachAnns.push({
+      id: 'teach-' + i + '-' + docSeed, quote: ph, prefix: '', suffix: '', ordinal: 0,
+      section: (i + 1) + '. ' + cutTitle(q || a.quote),
+      comment: '🎓 教学占位：请把本节教学正文直接写进这个段落（对 agent：edit 本条批注，newText=教学正文）',
+      created: Date.now(), status: 'new',
+      thread: [{ role: 'user', text: '🎓 教学占位：请把本节教学正文直接写进这个段落', time: Date.now() }]
+    });
+  });
+
+  tpl = tpl.replace(/<title>[\s\S]*?<\/title>/, '<title>' + esc(title) + '</title>');
+  tpl = tpl.replace(/<article>[\s\S]*?<\/article>/, '<article>\n' + body + '\n  </article>');
+  var docId = 'doc-' + docSeed + Math.random().toString(36).slice(2, 8);
+  tpl = tpl.replace(/var DOC_ID\s*=\s*'[^']*';/, "var DOC_ID = '" + docId + "';");
+  tpl = tpl.replace(/var FILE_NAME = '[^']*';/, "var FILE_NAME = '" + path.basename(dst) + "';");
+  tpl = stampPageVersion(tpl, pkgRoot);
+  /* 预置任务批注写进 store：agent 打开即可 read → edit，无需等人类先批注 */
+  tpl = tpl.replace(/(<script id="annotations-store" type="application\/json">\s*)([\s\S]*?)(\s*<\/script>)/, function (all, p1, p2, p3) {
+    return p1 + '\n' + JSON.stringify({ rev: 0, annotations: teachAnns, history: [] }).replace(/</g, '\\u003c') + '\n' + p3;
+  });
+
+  fs.writeFileSync(dst, tpl);
+  console.log('已从源文档批注生成教学文档: ' + dst);
+  console.log('  来源: ' + src + ' · 主题数: ' + o.annotations.length + ' · 模板: ' + tplSrc + (theme ? ' + 主题(' + THEME_FILE + ')' : ''));
+  console.log('下一步: agent 用 annotatable edit 逐节填充占位段落；填充完让人类用浏览器打开批注/推进。');
+  return dst;
+}
+
+/* ---------- edit：按批注指令修改正文，同步重算锚定 ----------
+ * 与模板锚定算法（buildIndex/normalizeWS）对齐的充分近似：
+ * 跳过 script/style/注释/批注层UI（#annot-*、#toc、#toc-toggle）与 store；
+ * 空白折叠规则一致；块级标签边界插一个空格；常见实体解码为单字符。
+ * 定位失败或全部失败时不写盘（宁可不改也不改错地方）。 */
+var EDIT_SKIP_IDS = ['annot-panel', 'annot-popover', 'annot-selbar', 'annot-toast', 'annot-fab', 'annot-savestate', 'hist-view', 'toc', 'toc-toggle', 'annot-list', 'annot-nav'];   /* v1.37.3 补 annot-nav：导航窗格烤入的标题副本（开过一次导航就整树在文件里）同属预渲染区 */
+var EDIT_BLOCK_TAGS = /^\/?(p|h1|h2|h3|h4|h5|h6|li|blockquote|td|th|pre|dd|dt|figcaption|section)$/i;
+var EDIT_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', nbsp: ' ', hellip: '…', mdash: '—', ndash: '–', ldquo: '“', rdquo: '”', lsquo: '‘', rsquo: '’', middot: '·', copy: '©', reg: '®', times: '×', divide: '÷' };
+
+function buildHtmlIndex(html) {
+  var norm = '', map = [];
+  var i = 0, n = html.length, skipName = null, skipDepth = 0;
+  function boundary() {
+    if (norm.length && norm.charAt(norm.length - 1) !== ' ') { norm += ' '; map.push(null); }
+  }
+  function pushCh(decoded, off, len) {
+    if (/\s/.test(decoded)) {
+      if (norm.length && norm.charAt(norm.length - 1) !== ' ') { norm += ' '; map.push({ off: off, len: len }); }
+    } else { norm += decoded; map.push({ off: off, len: len }); }
+  }
+  while (i < n) {
+    var ch = html.charAt(i);
+    if (ch === '<') {
+      if (html.substr(i, 4) === '<!--') { var eC = html.indexOf('-->', i); i = eC === -1 ? n : eC + 3; continue; }
+      var mt = html.slice(i, i + 512).match(/^<(\/?)([a-zA-Z][a-zA-Z0-9-]*)([^>]*)>/);
+      if (!mt) { i++; continue; }
+      var tag = mt[2].toLowerCase(), closing = mt[1] === '/', selfClosed = /\/\s*>$/.test(mt[0]);
+      if (skipName) {
+        if (!closing && !selfClosed && tag === skipName) skipDepth++;
+        else if (closing && tag === skipName) { skipDepth--; if (skipDepth <= 0) { skipName = null; skipDepth = 0; } }
+      } else if (!closing && (tag === 'script' || tag === 'style')) {
+        var eS = html.toLowerCase().indexOf('</' + tag, i);
+        i = eS === -1 ? n : eS;   /* 停在闭合标签处，下一轮正常处理 */
+        continue;
+      } else {
+        var idm = mt[3].match(/id\s*=\s*["']?([^"'\s>]+)/i);
+        if (idm && EDIT_SKIP_IDS.indexOf(idm[1]) !== -1 && !selfClosed) { skipName = tag; skipDepth = 1; i += mt[0].length; continue; }
+        if (EDIT_BLOCK_TAGS.test(tag)) boundary();
+      }
+      i += mt[0].length;
+      continue;
+    }
+    if (skipName) { i++; continue; }
+    if (ch === '&') {
+      var em = html.slice(i, i + 12).match(/^&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/);
+      if (em) {
+        var dec = em[1].charAt(0) === '#'
+          ? String.fromCodePoint(parseInt(em[1].charAt(1) === 'x' || em[1].charAt(1) === 'X' ? em[1].slice(2) : em[1].slice(1), em[1].charAt(1) === 'x' || em[1].charAt(1) === 'X' ? 16 : 10))
+          : (EDIT_ENTITIES.hasOwnProperty(em[1]) ? EDIT_ENTITIES[em[1]] : null);
+        if (dec !== null) { pushCh(dec, i, em[0].length); i += em[0].length; continue; }
+      }
+    }
+    pushCh(ch, i, 1);
+    i++;
+  }
+  return { norm: norm, map: map };
+}
+
+function allIndices(hay, needle) {
+  var out = [], i = 0;
+  while ((i = hay.indexOf(needle, i)) !== -1) { out.push(i); i += 1; }
+  return out;
+}
+
+/* ---------- 锚定消歧打分（v1.11.0，借鉴 human-review 的 bestHit）----------
+ * 多处命中同一 quote 时，按 prefix/suffix 上下文与每个候选的贴近度打分：
+ * 前缀从右端对齐比（紧邻字符权重自然最高）+ 后缀从左端对齐比。
+ * 全 0 分（无上下文/上下文也对不上）回退 ordinal，保持 v1.10 前的协议语义。 */
+function commonSuffixLength(a, b) {
+  var n = 0;
+  while (n < a.length && n < b.length && a.charAt(a.length - 1 - n) === b.charAt(b.length - 1 - n)) n++;
+  return n;
+}
+function commonPrefixLength(a, b) {
+  var n = 0;
+  while (n < a.length && n < b.length && a.charAt(n) === b.charAt(n)) n++;
+  return n;
+}
+function bestOccurrence(norm, occ, qLen, prefix, suffix, wantOrdinal) {
+  var bestI = 0, bestScore = -1, i, score;
+  for (i = 0; i < occ.length; i++) {
+    score = commonSuffixLength(prefix, norm.slice(Math.max(0, occ[i] - prefix.length), occ[i])) +
+            commonPrefixLength(suffix, norm.slice(occ[i] + qLen, occ[i] + qLen + suffix.length));
+    if (score > bestScore) { bestScore = score; bestI = i; }
+  }
+  if (bestScore <= 0) return occ[wantOrdinal] !== undefined ? occ[wantOrdinal] : occ[0];
+  if (occ[wantOrdinal] !== undefined) {          /* ordinal 命中同等分时优先（老协议语义） */
+    var w = occ[wantOrdinal];
+    var ws = commonSuffixLength(prefix, norm.slice(Math.max(0, w - prefix.length), w)) +
+             commonPrefixLength(suffix, norm.slice(w + qLen, w + qLen + suffix.length));
+    if (ws === bestScore) return w;
+  }
+  return occ[bestI];
+}
+
+/* 定位批注原句：单一命中直接用；多处命中按 prefix/suffix 打分消歧，无上下文回退 ordinal。
+ * v1.26.0 返回值扩展：occ（全部命中的规范化偏移）、scores（各候选上下文分）——
+ * applyEdits 的怀疑标记（分差/距离）靠它们判断，不再二次扫描。 */
+function findQuoteHit(idx, a) {
+  var q = String(a.quote || '').replace(/\s+/g, ' ').trim();
+  if (!q) return null;
+  var occ = allIndices(idx.norm, q);
+  if (!occ.length) return null;
+  var prefix = String(a.prefix || ''), suffix = String(a.suffix || '');
+  var scores = occ.map(function (o) {
+    return commonSuffixLength(prefix, idx.norm.slice(Math.max(0, o - prefix.length), o)) +
+           commonPrefixLength(suffix, idx.norm.slice(o + q.length, o + q.length + suffix.length));
+  });
+  var s = occ.length === 1 ? occ[0]
+    : bestOccurrence(idx.norm, occ, q.length, prefix, suffix, a.ordinal || 0);
+  return { s: s, e: s + q.length, q: q, ambiguous: occ.length > 1, occ: occ, scores: scores };
+}
+
+/* 前后缀模糊重找（v1.26.0 锚定三级）：引用原文不在，但前后缀仍能框出「原引用位置」的
+ * 唯一候选——前缀在正文中定位左界，后缀唯一定位右界，两界之间的文字即疑似改写后的内容。
+ * 宁缺勿滥：后缀不唯一 / 前缀找不到 / 空洞（整段删了）/ 离谱长，一律不给候选。
+ * 返回 {s,e,text}（规范化坐标+预览文本）或 null。 */
+function fuzzyFindByContext(idx, a) {
+  var suffix = String(a.suffix || ''), prefix = String(a.prefix || '');
+  if (suffix.replace(/\s+/g, '').length < 6) return null;   // 后缀太短框不住
+  var occSuf = allIndices(idx.norm, suffix);
+  if (occSuf.length !== 1) return null;                     // 后缀必须全文唯一
+  var at = occSuf[0];
+  if (!prefix) return null;                                 // 无前缀无法框左界
+  var occPre = allIndices(idx.norm, prefix);
+  var p = -1;
+  for (var i = occPre.length - 1; i >= 0; i--) {            // 取 suffix 之前最近的 prefix 出现
+    if (occPre[i] <= at) { p = occPre[i] + prefix.length; break; }
+  }
+  if (p === -1) return null;
+  if (at - p <= 0 || at - p > 200) return null;             // 空洞（整段删了）或离谱长 → 不给候选
+  var text = idx.norm.slice(p, at);
+  return { s: p, e: at, text: text };
+}
+
+var WORD_LOCK_TTL = 30 * 60 * 1000;   // v1.29.0 wordLock 旗有效期：页面崩了忘撤旗，半小时自动作废，不永久堵 AI
+
+function applyEdits(htmlPath, editsPath) {
+  silentUpgrade(htmlPath);   // v1.36.0 触碰即换装
+  var edits = JSON.parse(fs.readFileSync(editsPath, 'utf8'));
+  if (!Array.isArray(edits) || !edits.length) throw new Error('edits.json 应为非空数组 [{"id","newText","reply"?}]');
+  /* v1.26.0：持锁+写前复验+原子写；锚定三级（唯一/多现怀疑/模糊重找/失效追溯）全部在
+     本函数内部机器代码里完成，agent(LLM) 只管发命令读输出。 */
+  var out = withDocLock(htmlPath, function () {
+    var attempt = 0;
+    for (;;) {
+      attempt++;
+      var t = fs.readFileSync(htmlPath, 'utf8');
+      var storeRe = /(<script id="annotations-store" type="application\/json">\s*)([\s\S]*?)(\s*<\/script>)/;
+      var sm = t.match(storeRe);
+      if (!sm) throw new Error('NO_STORE（未找到批注区块）');
+      var o = JSON.parse(sm[2]);
+      if (!Array.isArray(o.history)) o.history = [];
+      if (!o.control || typeof o.control !== 'object') o.control = {};
+      /* v1.29.0 排队制：人类正在编辑正文（wordLock 旗在且新鲜）→ AI 对正文不落笔，改动进待办槽，
+         人类收笔瞬间由页面铺上；铺不上（正文大改锚不准）→ control.replay 立即唤醒 AI 重做 */
+      var queued = !!(o.control.wordLock && (Date.now() - (o.control.wordLock.at || 0)) < WORD_LOCK_TTL);
+      if (o.control.wordLock && !queued) delete o.control.wordLock;   // 过期旗顺手作废
+      if (o.control.replay) delete o.control.replay;                  // 本次提交即视为已处理（排队或直写都是消费重做请求）
+      var byId = {};
+      o.annotations.forEach(function (a) { byId[a.id] = a; });
+      var docId = docIdOf(t) || ('doc-unknown-' + path.basename(htmlPath));
+      var brief = function (x) { x = String(x); return x.length > 40 ? x.slice(0, 40) + '…' : x; };
+
+      var html = t, changed = [], pendingC = [], lost = [], failed = [], queuedIds = [];
+      var strips = [];   // bodyOps：每次替换的 {o:原文,n:新文,b:前文30字符,a:后文30字符}（均为原始 HTML 串，供回滚逆替换精确定位）
+      edits.forEach(function (ed) {
+        var a = byId[ed.id];
+        if (!a) { failed.push(ed.id + '（批注id不存在）'); return; }
+        var newText = ed.newText === undefined || ed.newText === null ? '' : String(ed.newText);
+        var idx = buildHtmlIndex(html);
+        var hit = findQuoteHit(idx, a);
+        if (!hit) {
+          /* 锚定三级之二：模糊重找——引用不在但前后缀框出唯一候选 → 给候选不自动执行 */
+          var fz = fuzzyFindByContext(idx, a);
+          if (fz) {
+            a.pendingAnchor = {
+              reason: 'notfound', quote: a.quote, newText: newText,
+              candidates: [{ s: fz.s, e: fz.e, text: fz.text,
+                             prefix: idx.norm.slice(Math.max(0, fz.s - 30), fz.s),
+                             suffix: idx.norm.slice(fz.e, fz.e + 30) }],
+              created: Date.now()
+            };
+            if (!Array.isArray(a.thread)) a.thread = [];
+            a.thread.push({ role: 'ai', text: '⚠️ AI 未自动执行：引用原文「' + brief(a.quote) + '」已不在正文，疑似改写为「' + brief(fz.text) + '」（前后缀上下文吻合）。确认后本次修改将应用到新文字；放弃则本条批语保持原样（不催不过期）。', time: Date.now() });
+            pendingC.push(ed.id + '（疑似改写为「' + brief(fz.text) + '」）');
+            return;
+          }
+          /* 锚定三级之三：失效——追溯侧车账本给「回退恢复原文」的出路，不再让用户手改 */
+          var trace = findLastRevWithQuote(htmlPath, docId, a.quote);
+          a.lostAnchor = { quote: a.quote, lastWith: trace ? trace.lastWith : null, goneAt: trace ? trace.goneAt : null, created: Date.now() };
+          if (!Array.isArray(a.thread)) a.thread = [];
+          a.thread.push({ role: 'ai', text: '⛔ AI 未动手：引用原文「' + brief(a.quote) + '」已不在正文' + (trace ? '（最后见于 r' + trace.lastWith + '，疑在 r' + trace.goneAt + ' 被替换）' : '') + '。可在版本历史回退到原文还在的版本（锚会自动复活）、放弃本条批语，或重新划选——正文保持可读，不催不过期。', time: Date.now() });
+          lost.push(ed.id + (trace ? '（原文最后见于 r' + trace.lastWith + '，页面可一键回退恢复）' : ''));
+          return;
+        }
+        /* 锚定三级之一：多现时的怀疑标记（三个纯计算，纳秒级）——任一命中即不自动落笔 */
+        if (hit.ambiguous) {
+          var suspects = [];
+          var sorted = (hit.scores || []).slice().sort(function (x, y) { return y - x; });
+          if (sorted.length > 1 && sorted[0] - sorted[1] < 6) suspects.push('上下文分差不大');
+          if (a.docLen && Math.abs(idx.norm.length - a.docLen) > ANCHOR_SUSPECT_LEN) suspects.push('文档发生过大编辑');
+          if (a.pos !== undefined && a.pos !== null) {
+            var ds = (hit.occ || []).map(function (o2) { return Math.abs(o2 - a.pos); }).sort(function (x, y) { return x - y; });
+            if (ds.length > 1 && ds[1] - ds[0] < ANCHOR_SUSPECT_LEN) suspects.push('多个候选离上次锚定位置都近');
+          }
+          if (suspects.length) {
+            var cands = (hit.occ || []).map(function (o2, oi) { return { s: o2, score: hit.scores ? hit.scores[oi] : 0 }; })
+              .sort(function (x, y) { return y.score - x.score; }).slice(0, 2)
+              .map(function (c) {
+                return { s: c.s, e: c.s + hit.q.length, text: idx.norm.substr(c.s, hit.q.length),
+                         prefix: idx.norm.slice(Math.max(0, c.s - 30), c.s),
+                         suffix: idx.norm.slice(c.s + hit.q.length, c.s + hit.q.length + 30) };
+              });
+            a.pendingAnchor = { reason: 'multi', quote: a.quote, newText: newText, suspects: suspects, candidates: cands, created: Date.now() };
+            if (!Array.isArray(a.thread)) a.thread = [];
+            a.thread.push({ role: 'ai', text: '⚠️ AI 未自动执行：引用「' + brief(a.quote) + '」在全文出现 ' + (hit.occ || []).length + ' 处（' + suspects.join('、') + '）。候选已在下方列出，确认迁移到哪一处后执行；放弃则本条批语保持原样。', time: Date.now() });
+            pendingC.push(ed.id + '（同文 ' + (hit.occ || []).length + ' 处：' + suspects.join('、') + '）');
+            return;
+          }
+          /* 无怀疑 → bestOccurrence 打分裁决（hit.s 即裁决结果），照常执行 */
+        }
+        var sp = idx.map[hit.s], ep = idx.map[hit.e - 1];
+        if (!sp || !ep) { failed.push(ed.id + '（锚点映射失败）'); return; }
+        var qStart = sp.off, qEnd = ep.off + ep.len;
+        var replacedHtml = html.slice(qStart, qEnd);
+        var oldQ = hit.q;
+        strips.push({ o: replacedHtml, n: newText, b: html.slice(Math.max(0, qStart - 30), qStart), a: html.slice(qEnd, qEnd + 30) });
+        html = html.slice(0, qStart) + newText + html.slice(qEnd);   // 排队模式＝虚拟替换：只为后续纸条上下文连续，最终不落盘
+        /* 重算锚定：quote 换成新文本，prefix/suffix/ordinal 围绕新位置重建（排队模式正文未变，跳过） */
+        var q2 = newText.replace(/\s+/g, ' ').trim();
+        if (q2 && !queued) {
+          var idx2 = buildHtmlIndex(html);
+          var s2 = -1;
+          for (var k = 0; k < idx2.map.length; k++) {
+            if (idx2.map[k] && idx2.map[k].off >= qStart) { s2 = k; break; }
+          }
+          var occ2 = allIndices(idx2.norm, q2);
+          if (s2 < 0 || idx2.norm.substr(s2, q2.length) !== q2) s2 = occ2.length ? occ2[0] : -1;
+          if (s2 >= 0) {
+            a.quote = q2;
+            a.prefix = idx2.norm.slice(Math.max(0, s2 - 40), s2).replace(/^\s+/, '');
+            a.suffix = idx2.norm.slice(s2 + q2.length, s2 + q2.length + 40).replace(/\s+$/, '');
+            var ord = occ2.indexOf(s2);
+            if (ord >= 0) a.ordinal = ord;
+            /* v1.26.0：pos/docLen 快照（新位置+当时文档长度），供下次消歧做距离裁决 */
+            a.pos = s2;
+            a.docLen = idx2.norm.length;
+          }
+        }
+        if (!Array.isArray(a.thread)) a.thread = [];
+        if (queued) {
+          a.thread.push({ role: 'ai', text: '📥 已排队：人类正在编辑正文，AI 暂不动笔；收笔后自动铺上（「' + brief(oldQ) + '」→「' + (q2 ? brief(newText) : '(已删除)') + '」）', time: Date.now() });
+          queuedIds.push(ed.id);
+          return;
+        }
+        var note = ed.reply || ('✅ 已按批注修改正文：「' + brief(oldQ) + '」→「' + (q2 ? brief(newText) : '(已删除)') + '」' + (replacedHtml.indexOf('<') !== -1 ? '（原句含格式标签，替换后为纯文本）' : ''));
+        a.thread.push({ role: 'ai', text: note, time: Date.now() });
+        a.reply = note;
+        a.status = 'answered';
+        /* v1.37.2：本次权威落笔后，早先挂起的锚点待确认/失效出路一并作废（避免页面残留待点卡片） */
+        delete a.pendingAnchor;
+        delete a.lostAnchor;
+        changed.push(ed.id);
+      });
+
+      /* 写前复验：读取期间磁盘又被写（浏览器抢先保存）→ 在最新状态上重放同一批修改
+         （edit 的锚定本就按「当前正文重新定位」设计，重放即 v1.9 语义的自然延伸） */
+      var diskNow = fs.readFileSync(htmlPath, 'utf8');
+      if (diskNow !== t && attempt < 8) continue;
+      if (diskNow !== t) throw new Error('并发写回冲突：重试 8 轮磁盘仍在变化，本轮未写盘（稍后重试即可）');
+
+      if (!changed.length && !queuedIds.length && !pendingC.length && !lost.length) {
+        throw new Error('没有任何一条修改成功，文件未改动。失败原因：\n  - ' + failed.join('\n  - '));
+      }
+      o.rev = (o.rev || 0) + 1;
+      var newEntry = queued
+        ? { rev: o.rev, time: Date.now(), op: 'AI正文改动排队 ' + queuedIds.length + ' 处（人类编辑中，收笔即铺）', n: o.annotations.length, snap: JSON.parse(JSON.stringify(o.annotations)) }
+        : { rev: o.rev, time: Date.now(), op: 'AI执行修改 ' + changed.length + ' 处' + (pendingC.length ? '（待确认 ' + pendingC.length + '）' : '') + (lost.length ? '（失效 ' + lost.length + '）' : ''), n: o.annotations.length, snap: JSON.parse(JSON.stringify(o.annotations)) };
+      if (strips.length && !queued) newEntry.bodyOps = strips;
+      if (queued && strips.length) o.control.pendingBodyOps = (o.control.pendingBodyOps || []).concat(strips);   // 待办槽：随 store 落盘，页面收笔时铺上
+      var res = commitHistory(htmlPath, t, o, newEntry);
+      var sideNote = res.sideOk
+        ? '（全量账本 → ' + HIST_DIR + '/' + path.basename(htmlPath) + '.hist.json）'
+        : '（外置档案不可写，快照保留在主文件）';
+      if (!html.match(storeRe)) throw new Error('修改后丢失批注区块，文件未写盘');
+      var opens = (html.match(/<script[^>]*>/g) || []).length;
+      var closes = (html.match(/<\/script>/g) || []).length;
+      if (opens !== closes) throw new Error('script 标签不平衡(' + opens + '/' + closes + ')，文件未写盘');
+      if (queued) html = t;   // 排队模式：正文一字不动，只落 store（旗子/待办槽/对话线）
+      html = html.replace(storeRe, function (all, p1, p2, p3) {
+        return p1 + '\n' + JSON.stringify(storePayload(o)).replace(/</g, '\\u003c') + '\n' + p3;
+      });
+      writeDocAtomic(htmlPath, html);
+      appendWriteTicket(htmlPath, 'cli', o.rev);
+      return { changed: changed, pendingC: pendingC, lost: lost, failed: failed, queuedIds: queuedIds, byId: byId, rev: o.rev, histLen: res.full.length, sideNote: sideNote };
+    }
+  });
+  var doneMsg = [];
+  if (out.changed.length) doneMsg.push('已执行 ' + out.changed.length + ' 处正文修改');
+  if (out.queuedIds.length) doneMsg.push('已排队 ' + out.queuedIds.length + ' 处（人类编辑正文期间 AI 不落笔，收笔自动铺上；铺不上会立即唤醒重做）');
+  console.log(doneMsg.join(' · ') + ' · rev=' + out.rev + ' · 版本记录=' + out.histLen + ' ' + out.sideNote + (out.changed.length ? '（浏览器刷新后批注锚定已随新文本重算）' : ''));
+  out.changed.forEach(function (id) {
+    var a = out.byId[id];
+    var last = (a.thread || [])[a.thread.length - 1];
+    console.log('  ✓ ' + id + ' — ' + (last ? last.text : ''));
+  });
+  out.queuedIds.forEach(function (id) {
+    var a = out.byId[id];
+    var last = (a.thread || [])[a.thread.length - 1];
+    console.log('  ⬇ ' + id + ' — ' + (last ? last.text : ''));
+  });
+  if (out.pendingC.length) {
+    console.log('⏳ ' + out.pendingC.length + ' 条待确认（AI 未自动落笔，页面对话线已给候选与按钮）:');
+    out.pendingC.forEach(function (s) { console.log('  ? ' + s); });
+  }
+  if (out.lost.length) {
+    console.log('⛔ ' + out.lost.length + ' 条锚定失效（页面已给出回退/放弃/追问出路）:');
+    out.lost.forEach(function (s) { console.log('  ! ' + s); });
+  }
+  if (out.failed.length) console.log('⚠ 未执行的批注id: ' + out.failed.join('; '));
+}
+
+/* 读某文档的侧车账本（供 serve /__annot/hist 用）：读文件取 DOC_ID → 归属校验读侧车；
+ * 无档案时返回空账本形状（浏览器端零特判）。 */
+function histForFile(target) {
+  var docId = docIdOf(fs.readFileSync(target, 'utf8'));
+  var side = docId ? readSideHist(target, docId) : null;
+  return side || { annotatableHist: 1, DOC_ID: docId || '', FILE_NAME: path.basename(target), rev: 0, entries: [] };
+}
+
+/* ---------- 主题与自定义模板 ---------- */
+var THEME_FILE = 'annotatable.theme.css';
+var USER_TEMPLATE_FILE = 'annotatable.template.html';
+
+/* v1.17.0 全局自定义层 ~/.annotatable/（template.html + theme.css）。
+ * 模板优先级：--template 显式 > 目录内 annotatable.template.html > 全局默认 > 内置；
+ * 主题优先级：目录内 theme.css > 全局 theme.css。
+ * opts.home 可注入假目录供测试（与 installSkill 的 baseDir 同惯例）。 */
+function globalDir(opts) {
+  return path.join((opts && opts.home) || require('os').homedir(), '.annotatable');
+}
+function globalTemplatePath(opts) { return path.join(globalDir(opts), 'annotatable.template.html'); }
+function globalThemePath(opts) { return path.join(globalDir(opts), THEME_FILE); }
+function loadThemeChain(dir, opts) {
+  return loadTheme(dir) || loadTheme(globalDir(opts));
+}
+function resolveTemplate(dir, pkgRoot, opts) {
+  opts = opts || {};
+  if (opts.template && fs.existsSync(opts.template)) {
+    return { tpl: fs.readFileSync(opts.template, 'utf8'), src: opts.template };
+  }
+  var local = path.join(dir, USER_TEMPLATE_FILE);
+  if (fs.existsSync(local)) {
+    return { tpl: fs.readFileSync(local, 'utf8'), src: local + '（自定义模板）' };
+  }
+  var g = globalTemplatePath(opts);
+  if (fs.existsSync(g)) {
+    return { tpl: fs.readFileSync(g, 'utf8'), src: g + '（全局默认模板）' };
+  }
+  return {
+    tpl: fs.readFileSync(path.join(pkgRoot, 'templates', 'annotatable-doc.html'), 'utf8'),
+    src: '内置模板'
+  };
+}
+
+function loadTheme(dir) {
+  var p = path.join(dir, THEME_FILE);
+  if (!fs.existsSync(p)) return null;
+  return fs.readFileSync(p, 'utf8');
+}
+function applyTheme(tpl, theme) {
+  if (!theme) return tpl;
+  var rest = theme;
+  var rootMatch = theme.match(/:root\s*\{[^}]*\}/);
+  if (rootMatch) {
+    rest = theme.replace(rootMatch[0], '');
+    tpl = tpl.replace(/:root\s*\{[^}]*\}/, rootMatch[0]);   // 替换文档默认变量块
+  }
+  if (rest.trim()) tpl = tpl.replace('</style>', rest + '\n</style>');  // 追加覆盖样式
+  return tpl;
+}
+
+/* init：把工作流文件装进目标目录（已存在的不覆盖） */
+function initKit(dir, pkgRoot) {
+  dir = dir || process.cwd();
+  var items = [
+    ['templates/AGENTS.md', 'AGENTS.md'],
+    ['templates/annotatable-doc.html', '可批注文档.html'],
+    ['templates/annotatable.theme.css', THEME_FILE],
+    ['agent/annot_read.js', 'agent/annot_read.js'],
+    ['agent/annot_reply.js', 'agent/annot_reply.js'],
+    ['agent/annot_edit.js', 'agent/annot_edit.js'],
+    ['agent/annot_answer.js', 'agent/annot_answer.js'],
+    ['agent/annot_poll.js', 'agent/annot_poll.js'],
+    ['lib/core.js', 'lib/core.js']
+  ];
+  var created = [], skipped = [];
+  items.forEach(function (it) {
+    var src = path.join(pkgRoot, it[0]);
+    var dst = path.join(dir, it[1]);
+    if (fs.existsSync(dst)) { skipped.push(it[1]); return; }
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(src, dst);
+    created.push(it[1]);
+  });
+  console.log('初始化完成 → ' + dir);
+  created.forEach(function (f) { console.log('  + ' + f); });
+  skipped.forEach(function (f) { console.log('  = 已存在，跳过: ' + f); });
+  console.log('\n下一步：');
+  console.log('  1. 用 Edge/Chrome 打开 可批注文档.html，左下角绑定文件；');
+  console.log('  2. 人类划线批注后，agent 运行: node agent/annot_read.js <html路径> 查看待回应批注；');
+  console.log('  3. 生成 replies.json 后运行: node agent/annot_reply.js <html路径> replies.json 写回。');
+  console.log('  4. 想换外观：编辑 annotatable.theme.css（annotatable new 时自动应用）。');
+  console.log('工作流细节见 AGENTS.md。');
+}
+
+/* new：从模板新建可批注文档
+ * 模板优先级见 resolveTemplate；主题：目录内/全局 annotatable.theme.css 存在则自动注入 */
+function newDoc(dir, name, pkgRoot, opts) {
+  opts = opts || {};
+  dir = dir || process.cwd();
+  if (!/\.html$/i.test(name)) name += '.html';
+  var dst = path.join(dir, name);
+  if (fs.existsSync(dst)) throw new Error('文件已存在: ' + dst);
+
+  var rsl = resolveTemplate(dir, pkgRoot, opts);
+  var tpl = rsl.tpl, tplSrc = rsl.src;
+  var theme = loadThemeChain(dir, opts);
+  tpl = applyTheme(tpl, theme);
+  if (opts.lang === 'en') tpl = applyLangEn(tpl).html;
+
+  fs.writeFileSync(dst, tpl);
+  // 每份文档独立的浏览器存储命名空间与正确文件名
+  var docId = 'doc-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  tpl = tpl.replace(/var DOC_ID\s*=\s*'[^']*';/, "var DOC_ID = '" + docId + "';");
+  tpl = tpl.replace(/var FILE_NAME = '[^']*';/, "var FILE_NAME = '" + name + "';");
+  /* v1.26.2：页签/侧栏标题 = 文件名（此前恒为模板占位「可批注文档（标题）」零信息；
+     写入正文 h1 后由模板 boot 自愈接管为文章标题） */
+  tpl = tpl.replace(/<title>[\s\S]*?<\/title>/, '<title>' + escHtml(name.replace(/\.html?$/i, '')) + '</title>');
+  tpl = stampPageVersion(tpl, pkgRoot);
+  fs.writeFileSync(dst, tpl);
+  console.log('已创建可批注文档: ' + dst);
+  console.log('  模板来源: ' + tplSrc + (theme ? ' + 主题(' + THEME_FILE + ')' : ''));
+  console.log('把内容写进各 section，然后用 Edge/Chrome 打开即可批注。');
+}
+
+/* 导出默认主题文件供修改 */
+function exportTheme(dir, pkgRoot) {
+  dir = dir || process.cwd();
+  var dst = path.join(dir, THEME_FILE);
+  if (fs.existsSync(dst)) throw new Error('已存在: ' + dst);
+  fs.copyFileSync(path.join(pkgRoot, 'templates', 'annotatable.theme.css'), dst);
+  console.log('已导出主题文件: ' + dst + '\n修改变量后，annotatable new 会自动应用。');
+}
+
+/* 导出内置模板供深度改造 */
+function exportTemplate(dir, name, pkgRoot) {
+  dir = dir || process.cwd();
+  var dst = path.join(dir, name || USER_TEMPLATE_FILE);
+  if (fs.existsSync(dst)) throw new Error('已存在: ' + dst);
+  fs.copyFileSync(path.join(pkgRoot, 'templates', 'annotatable-doc.html'), dst);
+  var g = globalTemplatePath({});
+  console.log('已导出模板: ' + dst + '\n改完后命名为 annotatable.template.html 放在目录里，new 时自动使用；或用 --template 指定。');
+  if (fs.existsSync(g)) console.log('（注意：已存在全局默认模板 ' + g + '，目录级文件与 --template 优先于它）');
+}
+
+/* template --use：把用户自己的 HTML 一键设为全局默认模板（v1.17.0，整页变模板）。
+ * 保留用户全部样式与结构：本地 <link> 样式内联；正文容器择优（article > main >
+ * content 系 div > body 整体包裹）改为批注层锚点 <article id="annot-article">；
+ * 我们的 :root 变量块插在最前（applyTheme 首 :root 交换命中，用户自己的 :root 在后仍胜出）；
+ * 批注层四件套不带 --annot- 前缀、不带 __ANNOT_NO_TOC__（new/md 完整能力）。
+ * opts.home 可注入假目录供测试。 */
+function templateUse(srcPath, pkgRoot, opts) {
+  opts = opts || {};
+  srcPath = path.resolve(srcPath || '');
+  if (!fs.existsSync(srcPath)) throw new Error('文件不存在: ' + srcPath);
+  var orig = fs.readFileSync(srcPath, 'utf8');
+  var srcDir = path.dirname(srcPath);
+  var t = orig;
+
+  if (t.indexOf('<script id="annotations-store"') !== -1) {
+    /* 已是可批注文档：直接收编，无需再装配 */
+    t = orig;
+  } else {
+    /* 1) 本地 <link rel=stylesheet> 内联（远程/读不到的保留原标签） */
+    t = t.replace(/<link\b[^>]*>/gi, function (tag) {
+      if (!/rel\s*=\s*["']?stylesheet/i.test(tag)) return tag;
+      var hm = tag.match(/href\s*=\s*["']([^"']+)["']/i);
+      if (!hm || /^(https?:|data:|\/\/)/i.test(hm[1])) return tag;
+      try {
+        var css = fs.readFileSync(path.resolve(srcDir, hm[1]), 'utf8');
+        return '<style data-from="' + hm[1].replace(/"/g, '&quot;') + '">\n' + css + '\n</style>';
+      } catch (e) { return tag; }
+    });
+
+    /* 2) viewport 兜底（批注层在窄屏可用） */
+    if (!/name\s*=\s*["']?viewport/i.test(t)) {
+      if (/<head[^>]*>/i.test(t)) {
+        t = t.replace(/<head[^>]*>/i, function (all) { return all + '\n<meta name="viewport" content="width=device-width, initial-scale=1">'; });
+      } else {
+        t = '<meta name="viewport" content="width=device-width, initial-scale=1">\n' + t;
+      }
+    }
+
+    /* 3) 正文容器择优 → 批注层锚点 <article id="annot-article"> */
+    var artCount = (t.match(/<article\b/gi) || []).length;
+    if (artCount > 0) {
+      if (artCount > 1) console.log('  ⚠ 页面含 ' + artCount + ' 个 article，锚定第一个（其余不进导航/批注区）');
+      t = t.replace(/<article\b([^>]*)>/i, function (all, attrs) {
+        return /(^|\s)id\s*=/i.test(attrs) ? all : '<article id="annot-article"' + attrs + '>';
+      });
+    } else {
+      var mo = /<main\b[^>]*>/i.exec(t);
+      var dm = !mo && /<(div|section)\b[^>]*(?:\bid\b|\bclass\b)\s*=\s*["'][^"']*(?:content|post|article|entry|markdown-body|rich-text)[^"']*["'][^>]*>/i.exec(t);
+      if (mo) {
+        var io = t.indexOf(mo[0]);
+        var ic = t.toLowerCase().indexOf('</main>', io);
+        if (ic === -1) throw new Error('页面有 <main> 但找不到 </main>，无法改造');
+        var mAttrs = mo[0].slice(5, -1);
+        t = t.slice(0, io) + '<article' + (/(^|\s)id\s*=/i.test(mAttrs) ? '' : ' id="annot-article"') +
+          mAttrs + '>' + t.slice(io + mo[0].length, ic) + '</article>' + t.slice(ic + 7);
+      } else if (dm) {
+        var tag = dm[1], io2 = dm.index, openLen = dm[0].length;
+        var re = new RegExp('<' + tag + '\\b|</' + tag + '>', 'gi');
+        re.lastIndex = io2 + openLen;
+        var depth = 1, mm, ic2 = -1;
+        while ((mm = re.exec(t))) {
+          depth += /^<\//i.test(mm[0]) ? -1 : 1;
+          if (depth === 0) { ic2 = mm.index; break; }
+        }
+        if (ic2 === -1) throw new Error('正文容器 <' + tag + '> 找不到配对闭标签');
+        var dAttrs = dm[0].slice(1 + tag.length, -1);
+        t = t.slice(0, io2) + '<article' + (/(^|\s)id\s*=/i.test(dAttrs) ? '' : ' id="annot-article"') + dAttrs + '>' +
+          t.slice(io2 + openLen, ic2) + '</article>' + t.slice(ic2 + tag.length + 3);
+      } else {
+        /* 无任何内容容器：整段 body 内容包进 article（该文件即一篇正文） */
+        var bm = /<body[^>]*>/i.exec(t);
+        var bClose = t.toLowerCase().lastIndexOf('</body>');
+        if (!bm || bClose === -1) throw new Error('不是完整的 HTML 文档（缺 <body>/</body>）');
+        t = t.slice(0, bm.index + bm[0].length) + '\n<article id="annot-article">\n' +
+          t.slice(bm.index + bm[0].length, bClose) + '\n</article>\n' + t.slice(bClose);
+      }
+    }
+
+    /* 4) 装配批注层：变量块进 head 最前（首 :root 交换命中），其余在 </body> 前 */
+    var tpl = fs.readFileSync(path.join(pkgRoot, 'templates', 'annotatable-doc.html'), 'utf8');
+    var parts = annotParts(tpl);
+    var headVars = '<style id="annot-tpl-vars">' + parts.varBlock + '</style>';
+    var payload = '<style id="annot-tpl-css">\n' + parts.annotCSS + '\n</style>\n' +
+      parts.skeleton + '\n' + annotStoreBlock() + '<script>\n' + parts.mainJs + '\n</' + 'script>';
+    if (/<head[^>]*>/i.test(t)) {
+      t = t.replace(/<head[^>]*>/i, function (all) { return all + '\n' + headVars; });
+    } else {
+      t = headVars + '\n' + t;
+    }
+    var bodyClose = t.toLowerCase().lastIndexOf('</body>');
+    if (bodyClose === -1) throw new Error('不是完整的 HTML 文档（缺 </body>）');
+    t = t.slice(0, bodyClose) + payload + '\n' + t.slice(bodyClose);
+  }
+
+  /* 相对路径引用在 ~/.annotatable 位置会失效，收集提示 */
+  var warnRefs = [];
+  (t.match(/(?:src|href)\s*=\s*["']([^"']+)["']/gi) || []).forEach(function (all) {
+    var v = all.replace(/^(?:src|href)\s*=\s*["']/i, '').replace(/["']$/, '');
+    if (v && !/^(https?:|data:|#|\/\/|mailto:|[A-Za-z]:)/.test(v) && warnRefs.indexOf(v) === -1) warnRefs.push(v);
+  });
+  if (warnRefs.length > 5) warnRefs = warnRefs.slice(0, 5).concat(['…']);
+
+  var gdir = globalDir(opts);
+  fs.mkdirSync(gdir, { recursive: true });
+  var dst = globalTemplatePath(opts);
+  fs.writeFileSync(dst, t.replace(/\s+$/, '\n') + '\n<!-- ' + VER_TAG + pkgVersion(pkgRoot) + ' 全局默认模板 · annotatable template --reset 可撤销 -->\n');
+  console.log('✅ 已把该 HTML 设为全局默认模板: ' + dst);
+  console.log('  来源: ' + srcPath);
+  console.log('  之后 annotatable new / md 默认即用这份模板（目录内 annotatable.template.html 或 --template 可覆盖）。');
+  console.log('  撤销: annotatable template --reset');
+  if (warnRefs.length) console.log('  ⚠ 相对路径引用在新位置会失效，建议内联或改线上地址: ' + warnRefs.join(', '));
+}
+
+/* 主题工坊页生成（v1.17.0）：壳 templates/theme-studio.html + 当前模板全文。
+ * 模板全文以 JSON 字符串内嵌（</script 统一转义为 <\/script，防脚本块提前闭合），
+ * 工坊在浏览器端按 applyTheme 同规则把主题烤入模板副本做实时预览——单源不双写。
+ * 由 `annotatable studio` 挂到 serve 的 GET /__annot/studio 内存直出，不落盘。 */
+function studioHtml(pkgRoot) {
+  var tpl = fs.readFileSync(path.join(pkgRoot, 'templates', 'annotatable-doc.html'), 'utf8');
+  var shell = fs.readFileSync(path.join(pkgRoot, 'templates', 'theme-studio.html'), 'utf8');
+  var tplCss = tpl.slice(tpl.indexOf('<style>') + 7, tpl.indexOf('</style>'));
+  var tplSrcJs = JSON.stringify(tpl).replace(/<\//g, '<\\/');
+  return shell
+    .replace('/*__TPL_CSS__*/', function () { return tplCss; })
+    .replace('"__TPL_SRC__"', function () { return tplSrcJs; })
+    .replace('__PKG_VER__', function () { return pkgVersion(pkgRoot); });
+}
+
+/* template --reset：撤销全局默认模板（全局主题文件保留——那是主题工坊的产物，单独删） */
+function templateReset(opts) {
+  opts = opts || {};
+  var g = globalTemplatePath(opts);
+  if (!fs.existsSync(g)) {
+    console.log('未设置全局默认模板，无需撤销。');
+    return;
+  }
+  fs.unlinkSync(g);
+  console.log('已撤销全局默认模板（删除 ' + g + '），new / md 恢复内置模板。');
+  var gt = globalThemePath(opts);
+  if (fs.existsSync(gt)) console.log('全局主题 ' + gt + ' 仍生效，不需要时手动删除。');
+  try { fs.rmdirSync(globalDir(opts)); } catch (e) { /* 目录非空则保留 */ }
+}
+
+/* ---------- skill 副本版本自检（过期检测与自动升级） ----------
+ * 版本唯一来源是 package.json；安装/升级时由 CLI 在副本末尾盖版本注释，
+ * 模板本身不含标记，避免双源失同步。null=副本不存在，''=无标记（旧版安装）。 */
+var VER_TAG = 'annotatable-html v';
+function pkgVersion(pkgRoot) {
+  try { return JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version || ''; }
+  catch (e) { return ''; }
+}
+/* 生成页版本烤入（v1.26.1）：模板占位 __ANNOT_VER__ → package.json 真实版本。
+ * 每份页自带「出生时的层版本」，agent/人 grep meta 即可验层；页内无 meta = 本版之前的旧层页。 */
+function stampPageVersion(tpl, pkgRoot) {
+  return tpl.replace(/__ANNOT_VER__/g, pkgVersion(pkgRoot) || 'unknown');
+}
+function escHtml(s) { return String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'); }
+function skillVersionOf(file) {
+  if (!fs.existsSync(file)) return null;
+  var m = fs.readFileSync(file, 'utf8').match(new RegExp('<!-- ' + VER_TAG + '([\\w.-]+) -->'));
+  return m ? m[1] : '';
+}
+function stampVersion(file, ver) {
+  var t = fs.readFileSync(file, 'utf8').replace(new RegExp('\\s*<!-- ' + VER_TAG + '[\\w.-]+ -->', 'g'), '');
+  fs.writeFileSync(file, t.replace(/\s+$/, '\n') + '<!-- ' + VER_TAG + ver + ' -->\n');
+}
+/* CLI 启动自检：已装 skill 副本落后于当前包时返回一行提示 */
+function staleSkillNotice(pkgRoot, baseDir) {
+  try {
+    var os = require('os');
+    var home = baseDir || os.homedir();
+    var ver = pkgVersion(pkgRoot);
+    var stale = [];
+    ['.zcode', '.claude'].forEach(function (d) {
+      var f = path.join(home, d, 'skills', 'annotatable-html', 'SKILL.md');
+      var v = skillVersionOf(f);
+      if (v !== null && v !== ver) stale.push(f);
+    });
+    if (!stale.length) return '';
+    return '⚠ 已安装的 skill 副本落后于当前包 v' + ver + '（' + stale.length + ' 份），运行 annotatable skill 可自动升级';
+  } catch (e) { return ''; }
+}
+
+/* 安装平台 skill + slash 命令（让「读批注」「/读批注」在任意目录自动触发）
+ * 副本已存在且与包同版本则跳过，版本落后（含无标记旧副本）则自动覆盖升级；
+ * baseDir 用于测试覆盖（默认 os.homedir()） */
+function installSkill(opts, pkgRoot, baseDir) {
+  opts = opts || {};
+  var os = require('os');
+  var home = baseDir || os.homedir();
+  var ver = pkgVersion(pkgRoot);
+  var targets = [];
+  if (opts.zcode || (!opts.zcode && !opts.claude)) targets.push({ name: 'ZCode', base: path.join(home, '.zcode') });
+  if (opts.claude || (!opts.zcode && !opts.claude)) targets.push({ name: 'Claude Code', base: path.join(home, '.claude') });
+  /* v1.37.1：~/.agents 是跨 harness 实体仓（atomcode 直读，codex 经符号链接共享）——收编进自动安装，
+     消除每版手工盖章的掉队隐患。此处多投一份 AGENTS.md（atomcode 双文件公约）；命令不投（slash 是 zcode/claude 公约）。 */
+  targets.push({ name: 'agents(共享仓)', base: path.join(home, '.agents'), agentsHub: true });
+  var srcSkill = path.join(pkgRoot, 'templates', 'SKILL.md');
+  var cmdDir = path.join(pkgRoot, 'templates', 'commands');
+  var installed = [], skipped = 0;
+  targets.forEach(function (t) {
+    var skillDst = path.join(t.base, 'skills', 'annotatable-html', 'SKILL.md');
+    var sv = skillVersionOf(skillDst);
+    if (sv === ver) {
+      skipped++; console.log('  = skill 已是最新 v' + ver + '，跳过: ' + skillDst);
+    } else {
+      fs.mkdirSync(path.dirname(skillDst), { recursive: true });
+      fs.copyFileSync(srcSkill, skillDst);
+      stampVersion(skillDst, ver);
+      installed.push(sv === null ? (t.name + ' skill → ' + skillDst)
+                                 : (t.name + ' skill 升级 ' + (sv || '无版本标记(旧)') + ' → v' + ver + '：' + skillDst));
+    }
+    if (t.agentsHub) {
+      var agSrc = path.join(pkgRoot, 'templates', 'AGENTS.md');
+      var agDst = path.join(t.base, 'skills', 'annotatable-html', 'AGENTS.md');
+      var av = skillVersionOf(agDst);
+      if (av === ver) { skipped++; }
+      else {
+        fs.mkdirSync(path.dirname(agDst), { recursive: true });
+        fs.copyFileSync(agSrc, agDst);
+        stampVersion(agDst, ver);
+        installed.push(av === null ? (t.name + ' AGENTS.md → ' + agDst)
+                                   : (t.name + ' AGENTS.md 升级 ' + (av || '无版本标记(旧)') + ' → v' + ver));
+      }
+    }
+    // 命令独立于 skill 处理（升级时清理旧命令、安装新命令）
+    if (fs.existsSync(cmdDir) && !t.agentsHub) {
+      // 清理 v1.3.0 的旧命令文件（已被 html4agent.md 取代）
+      ['读批注.md', '可批注文档.md'].forEach(function (old) {
+        var oldDst = path.join(t.base, 'commands', old);
+        if (fs.existsSync(oldDst)) { fs.unlinkSync(oldDst); installed.push(t.name + ' 清理旧命令 /' + old.replace(/\.md$/, '')); }
+      });
+      fs.readdirSync(cmdDir).forEach(function (f) {
+        var cdst = path.join(t.base, 'commands', f);
+        var cv = skillVersionOf(cdst);
+        if (cv !== null && cv === ver) { skipped++; return; }
+        fs.mkdirSync(path.dirname(cdst), { recursive: true });
+        fs.copyFileSync(path.join(cmdDir, f), cdst);
+        stampVersion(cdst, ver);
+        installed.push(cv === null ? (t.name + ' 命令 → /' + f.replace(/\.md$/, ''))
+                                   : (t.name + ' 命令升级 /' + f.replace(/\.md$/, '') + ' → v' + ver));
+      });
+    }
+  });
+  console.log('触发器安装完成：');
+  installed.forEach(function (l) { console.log('  + ' + l); });
+  if (skipped) console.log('  = 跳过已存在项 ' + skipped + ' 个');
+  if (!installed.length && !skipped) console.log('  （无内容安装）');
+  console.log('生效后（新开终端/新会话），任意目录可说「生成可批注报告」或 /html4agent 触发；批注后说「已批」即进入读批回答循环。');
+}
+
+function annotVarPrefix(css) {
+  return css.replace(/--([A-Za-z][\w-]*)/g, function (all, name) {
+    return /^annot-/.test(name) ? all : '--annot-' + name;
+  });
+}
+
+/* v1.17.0：批注层四件套提取器——inject 与 template --use（整页变模板）共用，防双源失同步。
+ * 返回原始切片（变量块/批注层样式均未加前缀），由调用方决定是否过 annotVarPrefix。
+ * 新增 UI 元素必须放进模板的「批注层骨架 BEGIN/END」哨兵对内。 */
+function annotParts(tpl) {
+  var sS = tpl.indexOf('<style>') + 7, sE = tpl.indexOf('</style>');
+  var styleAll = tpl.slice(sS, sE);
+  var aStart = styleAll.indexOf('/* ═══ 批注层样式 BEGIN');
+  var aEnd = styleAll.indexOf('/* ═══ 批注层样式 END');
+  if (aStart === -1 || aEnd === -1 || aEnd <= aStart) throw new Error('模板缺少批注层样式哨兵（BEGIN/END）');
+  var annotCSS = styleAll.slice(aStart, aEnd);
+  var rootM = tpl.match(/:root\s*\{[^}]*\}/);
+  var varBlock = rootM ? rootM[0] : '';
+  var jsS = tpl.lastIndexOf('<script>'), jsE = tpl.lastIndexOf('</script>');
+  var mainJs = tpl.slice(jsS + 9, jsE);
+  /* v1.12.1：骨架改按哨兵抽取。旧逻辑只切到 toast 为止，而 v1.12 的 Word 模式
+   * 五件套（✏️/🧭/wordbar/nav/find）位于 popover 之后、toast 之前，
+   * 旧 fab→toast 切割把它们留在骨架外——注入版缺按钮且 init 绑定事件时报错。 */
+  var kS = tpl.indexOf('<!-- ═══ 批注层骨架 BEGIN');
+  var kEm = tpl.indexOf('<!-- ═══ 批注层骨架 END');
+  var skeleton;
+  if (kS !== -1 && kEm !== -1 && kEm > kS) {
+    skeleton = tpl.slice(tpl.indexOf('>', kS) + 1, tpl.lastIndexOf('<!--', kEm));
+  } else {
+    kS = tpl.indexOf('<button id="annot-fab"');
+    var tIdx = tpl.indexOf('id="annot-toast"');
+    var kE = tpl.indexOf('</div>', tIdx) + 6;
+    skeleton = tpl.slice(kS, kE);
+  }
+  /* 骨架自带空 popover/toast；自定义模板若塞了演示内容，装配前清空 */
+  skeleton = skeleton.replace(/(<div id="annot-popover"[^>]*>)[\s\S]*?<\/div>/, '$1</div>');
+  skeleton = skeleton.replace(/(<div id="annot-toast"[^>]*>)[\s\S]*?<\/div>/, '$1</div>');
+  return { annotCSS: annotCSS, varBlock: varBlock, skeleton: skeleton, mainJs: mainJs };
+}
+
+function annotStoreBlock() {
+  return '<!-- ═══ AI批注数据 BEGIN — agent 读取协议见 AGENTS.md ═══ -->\n' +
+    '<script id="annotations-store" type="application/json">\n' +
+    JSON.stringify({ rev: 0, annotations: [], history: [] }) + '\n</' + 'script>\n' +
+    '<!-- ═══ AI批注数据 END ═══ -->\n';
+}
+
+/* inject：给任意 HTML 注入批注层（CSS+UI骨架+脚本+空白store）
+ * 目标保持原有外观；无 <article> 时给 <body> 盖章作为锚定根；
+ * 自动备份原文件到同目录 .annotatable/（*.pre-inject.bak）；已含批注层的文件拒绝重复注入。
+ * 宿主隔离：批注层样式只取模板 BEGIN/END 哨兵区（不带目录/正文排版规则），
+ * 自定义属性统一加 --annot- 前缀并自带定义块，杜绝与宿主 :root 变量互相覆盖；
+ * 脚本置 __ANNOT_NO_TOC__ 标志，不接管宿主已有目录。 */
+function injectHtml(targetPath, pkgRoot, opts) {
+  opts = opts || {};
+  targetPath = path.resolve(targetPath);
+  if (!fs.existsSync(targetPath)) throw new Error('文件不存在: ' + targetPath);
+  var orig = fs.readFileSync(targetPath, 'utf8');
+  var target = orig;
+  /* 判定认真实的 store script 标签，而不是正文文字（讲到批注协议的文档会提到这个词） */
+  if (target.indexOf('<script id="annotations-store"') !== -1) throw new Error('该文件已包含批注层，无需注入');
+
+  /* 从模板提取批注层四件套（注入态统一加 --annot- 前缀做宿主隔离） */
+  var tpl = fs.readFileSync(path.join(pkgRoot, 'templates', 'annotatable-doc.html'), 'utf8');
+  if (opts.lang === 'en') tpl = applyLangEn(tpl).html;
+  var parts = annotParts(tpl);
+  var annotCSS = annotVarPrefix(parts.annotCSS);
+  var varBlock = parts.varBlock ? annotVarPrefix(parts.varBlock) : '';
+  var mainJs = parts.mainJs;
+  var skeleton = parts.skeleton;
+
+
+  /* DOC_ID / FILE_NAME 唯一化 + 注入环境标志（不接管宿主目录） */
+  var docId = 'doc-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  var fileName = path.basename(targetPath);
+  mainJs = '(function(){try{window.__ANNOT_NO_TOC__=1}catch(e){}})();\n' + mainJs;
+  mainJs = mainJs.replace(/var DOC_ID\s*=\s*'[^']*';/, "var DOC_ID = '" + docId + "';");
+  mainJs = mainJs.replace(/var FILE_NAME = '[^']*';/, "var FILE_NAME = '" + fileName + "';");
+  /* 版本烤入（v1.26.1）：宿主 head 盖 meta（重注入则刷新），无 head 则静默跳过 */
+  var injVer = pkgVersion(pkgRoot) || 'unknown';
+  if (/<meta name="annotatable-html" content="[^"]*">/.test(target)) {
+    target = target.replace(/<meta name="annotatable-html" content="[^"]*">/, '<meta name="annotatable-html" content="' + injVer + '">');
+  } else {
+    target = target.replace(/<head(\s[^>]*)?>/i, function (m) { return m + '\n<meta name="annotatable-html" content="' + injVer + '">'; });
+  }
+
+  /* 锚定根：目标无 <article> 且无盖章时，给 <body> 加 id */
+  if (!/<article[\s>]/.test(target) && target.indexOf('id="annot-article"') === -1) {
+    target = target.replace(/<body([^>]*)>/, function (all, attrs) {
+      return / id=/.test(attrs) ? all : '<body id="annot-article"' + attrs + '>';
+    });
+  }
+
+  /* 主题：目标目录 > cwd > 全局 ~/.annotatable 的 annotatable.theme.css 自动应用（同样过前缀变换） */
+  var theme = loadTheme(path.dirname(targetPath)) || loadTheme(process.cwd()) || loadTheme(globalDir(opts));
+  var themeRoot = '', themeRest = '';
+  if (theme) {
+    var rm = theme.match(/:root\s*\{[^}]*\}/);
+    themeRoot = rm ? annotVarPrefix(rm[0]) : '';
+    themeRest = annotVarPrefix(rm ? theme.replace(rm[0], '') : theme);
+  }
+  var cssBlock = '<style id="annot-injected-css">\n' +
+    [varBlock, themeRoot, annotCSS, themeRest].filter(Boolean).join('\n') + '\n</style>';
+
+  var store = annotStoreBlock();
+  var payload = cssBlock + '\n' + skeleton + '\n' + store + '<script>\n' + mainJs + '\n</' + 'script>';
+
+  var bodyClose = target.lastIndexOf('</body>');
+  if (bodyClose === -1) throw new Error('未找到 </body>，不是完整的 HTML 文档');
+  /* 备份统一放同目录 .annotatable/（与版本历史外置档案同一处，不散落在文件旁边）；重名加时间戳保护最早那份 */
+  var bakDir = path.join(path.dirname(targetPath), HIST_DIR);
+  fs.mkdirSync(bakDir, { recursive: true });
+  var bakPath = path.join(bakDir, fileName + '.pre-inject.bak');
+  if (fs.existsSync(bakPath)) {
+    var d = new Date();
+    var st = d.getFullYear() + ('0' + (d.getMonth() + 1)).slice(-2) + ('0' + d.getDate()).slice(-2) + '-' +
+      ('0' + d.getHours()).slice(-2) + ('0' + d.getMinutes()).slice(-2) + ('0' + d.getSeconds()).slice(-2);
+    bakPath = path.join(bakDir, fileName + '.' + st + '.pre-inject.bak');
+  }
+  fs.writeFileSync(bakPath, orig);
+  fs.writeFileSync(targetPath, target.slice(0, bodyClose) + payload + '\n' + target.slice(bodyClose));
+  console.log('注入完成: ' + targetPath);
+  console.log('  DOC_ID: ' + docId + ' · 原文件备份: ' + path.join(HIST_DIR, path.basename(bakPath)));
+  console.log('  用 Edge/Chrome 打开，点右侧 🔗 同步球绑定后即可划线批注。');
+}
+
+/* ---------- v1.36.0 旧层页静默升级（touch = upgrade）----------
+ * 背景：批注层在生成时整份烤进 HTML，包升级触达不了存量页——旧层页永远跑旧代码，
+ * 新 UI/新防线全享受不到。这里把升级做成「agent 触碰即顺手换装」：
+ * read/reply/poll/edit/answer 与 serve 启动自动执行，用户无感；annotatable upgrade 可显式批量。
+ * 铁律：只换批注层——注入页=整个注入尾巴重建（store 原样搬回）；模板页=样式/骨架哨兵区+主脚本三件。
+ * 正文、store、DOC_ID、教学块、<title>、主题 :root 一个字节不动 → 锚点全保、rev 不变、伴生档案继续有效。
+ * 安全阀：定位失败/疑似腐蚀/DOC_ID 缺失一律拒动；备份 .annotatable/<名>.pre-upgrade-<旧版>-<ts>.bak →
+ * 持锁（与 serve 保存串行）锁内复验 → 原子写 → 写后读回比对，任一不过即放弃，绝不阻塞原操作。 */
+function layerVerOf(html) {
+  var m = String(html || '').match(/<meta name="annotatable-html" content="([^"]*)">/);
+  return m ? m[1] : '';
+}
+function verKey(v) {   // '1.36.0' → 10306；非数值段按 0（'unknown'/空串=最老）
+  var p = String(v || '').split('.');
+  return (parseInt(p[0], 10) || 0) * 10000 + (parseInt(p[1], 10) || 0) * 100 + (parseInt(p[2], 10) || 0);
+}
+function storeRegionOf(html) {   // 含首尾 ═══ 注释的完整 store 区（byte-exact，注入页重建尾巴时原样搬回）
+  var b = html.indexOf('<!-- ═══ AI批注数据 BEGIN');
+  if (b === -1) return null;
+  var e = html.indexOf('AI批注数据 END', b);
+  if (e === -1) return null;
+  var eEnd = html.indexOf('-->', e);
+  return eEnd === -1 ? null : html.slice(b, eEnd + 3);
+}
+function upgradeLayerFile(targetPath, pkgRoot, opts) {
+  opts = opts || {};
+  targetPath = path.resolve(targetPath);
+  var orig = fs.readFileSync(targetPath, 'utf8');
+  var cur = pkgVersion(pkgRoot) || 'unknown';
+  if (orig.indexOf('<script id="annotations-store"') === -1) return { status: 'skip', note: '非批注页' };
+  if (orig.split('<script id="annotations-store"').length - 1 > 1 || orig.split('<button id="annot-fab"').length - 1 > 1)
+    return { status: 'skip', note: '结构疑似腐蚀（骨架/store 重复），拒绝自动换层——先人工抢救数据' };
+  var oldVer = layerVerOf(orig);
+  if (oldVer === cur) return { status: 'current' };
+  if (verKey(oldVer) > verKey(cur))
+    return { status: 'skip', note: '页面层 v' + oldVer + ' 比当前包 v' + cur + ' 还新（他机新页/本机包未同步），拒绝降级' };
+  var docIdM = orig.match(/var DOC_ID\s*=\s*'([^']*)'/);
+  if (!docIdM || !docIdM[1]) return { status: 'skip', note: '找不到 DOC_ID（过旧或非标页），拒绝自动换层' };
+  var docId = docIdM[1];
+  var fnM = orig.match(/var FILE_NAME = '([^']*)'/);
+  var fileName = fnM ? fnM[1] : path.basename(targetPath);
+  var isEn = /var DOC_LANG = 'en';/.test(orig);   // en 页换装后还得是 en
+  var tplRaw = fs.readFileSync(path.join(pkgRoot, 'templates', 'annotatable-doc.html'), 'utf8');
+  var tpl = isEn ? applyLangEn(tplRaw).html : tplRaw;
+
+  function stampMeta(html) {
+    if (/<meta name="annotatable-html" content="[^"]*">/.test(html))
+      return html.replace(/<meta name="annotatable-html" content="[^"]*">/, '<meta name="annotatable-html" content="' + cur + '">');
+    return html.replace(/<head(\s[^>]*)?>/i, function (m) { return m + '\n<meta name="annotatable-html" content="' + cur + '">'; });
+  }
+  function stampIds(js) {   // 盖回旧 DOC_ID/FILE_NAME；模板占位没盖成=语法结构漂移，宁可不做
+    var out = js.replace(/var DOC_ID\s*=\s*'[^']*';/, "var DOC_ID = '" + docId + "';")
+      .replace(/var FILE_NAME = '[^']*';/, "var FILE_NAME = '" + fileName + "';");
+    if (out.indexOf("var DOC_ID = '" + docId + "';") === -1) throw new Error('DOC_ID 盖章失败（模板主脚本结构漂移）');
+    return out;
+  }
+
+  var out;
+  var isInject = orig.split('<style id="annot-injected-css">').length - 1 === 1;
+  if (isInject) {
+    /* 注入页：尾巴 [annot-injected-css 起 → 主脚本 </script> 止] 整体重建（注入时就在 </body> 前） */
+    var i0 = orig.indexOf('<style id="annot-injected-css">');
+    var bodyClose = orig.lastIndexOf('</body>');
+    var jsClose = bodyClose === -1 ? -1 : orig.lastIndexOf('</' + 'script>', bodyClose);
+    var storeRegion = storeRegionOf(orig);
+    if (bodyClose === -1 || i0 === -1 || jsClose === -1 || i0 > bodyClose ||
+        !/^\s*$/.test(orig.slice(jsClose + 9, bodyClose)) || !storeRegion ||
+        storeRegionOf(orig.slice(0, i0)) !== null || i0 < orig.indexOf('<body'))
+      return { status: 'skip', note: '注入尾巴定位失败（尾部有非层内容或非标页），拒绝自动换层' };
+    var parts = annotParts(tpl);
+    var annotCSS = annotVarPrefix(parts.annotCSS);
+    var varBlock = parts.varBlock ? annotVarPrefix(parts.varBlock) : '';
+    var mainJs = stampIds('(function(){try{window.__ANNOT_NO_TOC__=1}catch(e){}})();\n' + parts.mainJs);
+    var theme = loadTheme(path.dirname(targetPath)) || loadTheme(process.cwd()) || loadTheme(globalDir(opts));
+    var themeRoot = '', themeRest = '';
+    if (theme) {
+      var rm = theme.match(/:root\s*\{[^}]*\}/);
+      themeRoot = rm ? annotVarPrefix(rm[0]) : '';
+      themeRest = annotVarPrefix(rm ? theme.replace(rm[0], '') : theme);
+    }
+    var cssBlock = '<style id="annot-injected-css">\n' + [varBlock, themeRoot, annotCSS, themeRest].filter(Boolean).join('\n') + '\n</style>';
+    var payload = cssBlock + '\n' + parts.skeleton + '\n' + storeRegion + '\n<script>\n' + mainJs + '\n</' + 'script>';
+    out = stampMeta(orig.slice(0, i0) + payload + '\n' + orig.slice(jsClose + 9));
+  } else {
+    /* 模板页（new/md/teach/--use 产物）：三件哨兵区原位换装，正文/主题/标题不动 */
+    function sentRegion(html, beginMark, endMark) {
+      var b = html.indexOf(beginMark);
+      if (b === -1) return null;
+      var e = html.indexOf(endMark, b);
+      return e === -1 ? null : { b: b, e: e + endMark.length };
+    }
+    var CSS_B = '/* ═══ 批注层样式 BEGIN', CSS_E = '批注层样式 END ═══ */';
+    var SK_B = '<!-- ═══ 批注层骨架 BEGIN', SK_E = '批注层骨架 END ═══ -->';
+    var cs = sentRegion(orig, CSS_B, CSS_E), cn = sentRegion(tpl, CSS_B, CSS_E);
+    var ks = sentRegion(orig, SK_B, SK_E), kn = sentRegion(tpl, SK_B, SK_E);
+    var jsS = orig.lastIndexOf('<script>'), jsE = jsS === -1 ? -1 : orig.indexOf('</' + 'script>', jsS);
+    var tjS = tpl.lastIndexOf('<script>'), tjE = tpl.indexOf('</' + 'script>', tjS);
+    if (!cs || !cn || !ks || !kn || jsS === -1 || jsE === -1 || tjS === -1 || tjE === -1 || ks.e > jsS)
+      return { status: 'skip', note: '哨兵区/主脚本定位失败（v1.17 前旧层页），请重建壳升级' };
+    var newJs = stampIds(tpl.slice(tjS, tjE + 9));
+    /* 从后往前换，坐标不漂移 */
+    out = orig.slice(0, jsS) + newJs + orig.slice(jsE + 9);
+    out = out.slice(0, ks.b) + tpl.slice(kn.b, kn.e) + out.slice(ks.e);
+    out = out.slice(0, cs.b) + tpl.slice(cn.b, cn.e) + out.slice(cs.e);
+    out = stampMeta(out);
+  }
+  if (layerVerOf(out) !== cur) return { status: 'skip', note: '版本戳盖不上（无 <head>？），拒绝自动换层' };
+
+  /* 写前体检：store 必须逐字节一致；换装产物不得自带腐蚀项 */
+  var oldStoreM = orig.match(/<script id="annotations-store" type="application\/json">[\s\S]*?<\/script>/);
+  var newStoreM = out.match(/<script id="annotations-store" type="application\/json">[\s\S]*?<\/script>/);
+  if (!oldStoreM || !newStoreM || oldStoreM[0] !== newStoreM[0]) return { status: 'skip', note: 'store 比对不一致，拒绝写入' };
+  function rotten(t) {
+    var bad = [];
+    if (t.split('<button id="annot-fab"').length - 1 > 1) bad.push('骨架重复');
+    try { JSON.parse((t.match(/<script id="annotations-store" type="application\/json">([\s\S]*?)<\/script>/) || [])[1]); }
+    catch (e) { bad.push('store解析失败'); }
+    return bad;
+  }
+  if (rotten(out).length) return { status: 'skip', note: '换装产物自检未过（' + rotten(out).join('/') + '），拒绝写入' };
+
+  /* 备份 + 持锁原子写 + 写后读回比对 */
+  return withDocLock(targetPath, function () {
+    var now = fs.readFileSync(targetPath, 'utf8');
+    if (now !== orig) return { status: 'skip', note: '锁内发现文件刚被写过，本次放弃（下次触碰再升）' };
+    var bakDir = path.join(path.dirname(targetPath), HIST_DIR);
+    fs.mkdirSync(bakDir, { recursive: true });
+    var d = new Date();
+    var ts = d.getFullYear() + ('0' + (d.getMonth() + 1)).slice(-2) + ('0' + d.getDate()).slice(-2) + '-' +
+      ('0' + d.getHours()).slice(-2) + ('0' + d.getMinutes()).slice(-2) + ('0' + d.getSeconds()).slice(-2);
+    var bakPath = path.join(bakDir, path.basename(targetPath) + '.pre-upgrade-' + (oldVer || 'old') + '-' + ts + '.bak');
+    fs.writeFileSync(bakPath, orig);
+    var tmp = targetPath + '.upgrading';
+    fs.writeFileSync(tmp, out);
+    fs.renameSync(tmp, targetPath);
+    if (fs.readFileSync(targetPath, 'utf8') !== out) {
+      fs.writeFileSync(targetPath, orig);   // 读回不一致（极端：写坏）→ 回滚
+      return { status: 'error', note: '写后读回不一致，已回滚' };
+    }
+    return { status: 'upgraded', from: oldVer || '(无版本戳)', to: cur, bak: bakPath };
+  });
+}
+/* agent 触碰即换装：六个读写命令与 serve 启动的统一钩子。任何失败只提示一行，绝不阻塞原操作。 */
+function silentUpgrade(htmlPath) {
+  try {
+    var r = upgradeLayerFile(htmlPath, path.join(__dirname, '..'));
+    if (r && r.status === 'upgraded')
+      console.log('ℹ 批注层已静默升级 ' + r.from + ' → v' + r.to + '（正文与批注原样保留 · 备份 ' + HIST_DIR + '/' + path.basename(r.bak) + '）');
+    return r;
+  } catch (e) {
+    try { console.log('⚠ 批注层静默升级跳过（不影响本次操作）: ' + (e.message || e)); } catch (e2) { /* stdout 关闭 */ }
+    return null;
+  }
+}
+function upgradeDir(dirPath) {   // serve 启动 / annotatable upgrade <目录>：扫一层目录逐页换装
+  var n = 0, files;
+  try { files = fs.readdirSync(dirPath); } catch (e) { return 0; }
+  files.forEach(function (f) {
+    if (!/\.html?$/i.test(f)) return;
+    var r = silentUpgrade(path.join(dirPath, f));
+    if (r && r.status === 'upgraded') n++;
+  });
+  return n;
+}
+
+/* ---------- v1.37.0 图纸页安全重生成（regen）+ 回复编辑礼让 ----------
+ * 背景：页面从生成器图纸造出、又被人类在 Word 模式手改——重生成若直接按图纸重建正文，
+ * 手改会被无声盖掉（全景页目录事件：人类删的目录被图纸原样盖回）。把安全管线产品化：
+ *   regenDoc(live, fresh)            报表：剥层取可见文本 diff，列出手改清单，不动盘
+ *   regenDoc(live, fresh, {go})      上盘：fresh 注入当前层 + live 的 store/DOC_ID 原样搬回；
+ *                                    有未收割手改 → 拒绝（--force 显式丢弃才放行）
+ * 铁律：正文以盘为准——图纸必须先追认手改，永远不许倒过来。wordLock 活跃一律让路。
+ * 回复礼让：人类举旗编辑期间 reply/answer 不落盘（退出码 6），agent 等收笔再发。 */
+function stripAnnotLayer(html) {
+  var st = html.replace(/<meta name="annotatable-html" content="[^"]*">\n?/, '');
+  var i0 = st.indexOf('<style id="annot-injected-css">');
+  if (i0 === -1) return null;
+  var bodyClose = st.lastIndexOf('</body>');
+  var jsClose = bodyClose === -1 ? -1 : st.lastIndexOf('</' + 'script>', bodyClose);
+  if (bodyClose === -1 || jsClose === -1 || jsClose < i0) return null;
+  if (!/^\s*$/.test(st.slice(jsClose + 9, bodyClose))) return null;
+  return st.slice(0, i0) + st.slice(jsClose + 9);
+}
+function bodyTextLines(html) {   // 剥标签取可见文本行：Word 手改都是文本级，浏览器序列化噪音（属性顺序/自闭合形态）天然消失
+  return String(html).split(/<[^>]*>/).map(function (s) {
+    return s.replace(/&nbsp;/g, ' ').replace(/\s+/g, ' ').trim();
+  }).filter(function (s) { return s.length > 1; });
+}
+function wordLockActive(htmlText) {
+  var o = readStore(htmlText);
+  var wl = o && o.control && o.control.wordLock;
+  return !!(wl && Date.now() - (wl.at || 0) < WORD_LOCK_TTL);
+}
+function rottenOf(t) {
+  var bad = [];
+  if (t.split('<button id="annot-fab"').length - 1 > 1) bad.push('骨架重复');
+  try { JSON.parse((t.match(/<script id="annotations-store" type="application\/json">([\s\S]*?)<\/script>/) || [])[1]); }
+  catch (e) { bad.push('store解析失败'); }
+  return bad;
+}
+function regenDoc(livePath, freshPath, opts) {
+  opts = opts || {};
+  livePath = path.resolve(livePath);
+  freshPath = path.resolve(freshPath);
+  var live = fs.readFileSync(livePath, 'utf8');
+  var fresh = fs.readFileSync(freshPath, 'utf8');
+  if (live.indexOf('<script id="annotations-store"') === -1) throw new Error('live 不是可批注页（无 store 区块）');
+  if (wordLockActive(live)) return { status: 'wordmode' };
+  var liveBody = stripAnnotLayer(live);
+  if (liveBody === null) throw new Error('live 不是注入页（找不到注入尾巴）——regen 目前只支持 inject 维护的图纸页');
+  if (fresh.indexOf('<script id="annotations-store"') !== -1) throw new Error('fresh 应为图纸直出的无层纯页，请勿先 inject');
+  if (!/<\/body>/i.test(fresh)) throw new Error('fresh 不是完整 HTML（无 </body>）');
+  var a = bodyTextLines(liveBody), b = bodyTextLines(fresh);
+  var sb = {};
+  b.forEach(function (l) { sb[l] = 1; });
+  var lost = a.filter(function (l) { return !sb[l]; });
+  if (lost.length && !(opts.go && opts.force))
+    return { status: 'manual-edits', lost: lost, wouldLose: !!(opts.go && !opts.force) };
+  if (!opts.go) return { status: 'clean' };
+  /* 上盘：fresh 落临时文件 → 注入当前层 → live 的 store/DOC_ID/FILE_NAME 搬回 → 断言 → 备份原子替换 */
+  var tmp = path.join(path.dirname(livePath), path.basename(livePath) + '.regen-tmp.html');
+  fs.writeFileSync(tmp, fresh);
+  var fileName = path.basename(livePath);
+  try {
+    injectHtml(tmp, path.join(__dirname, '..'), { lang: /var DOC_LANG = 'en';/.test(live) ? 'en' : undefined });
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch (e2) {}
+    throw new Error('fresh 注入失败：' + (e.message || e));
+  }
+  var t = fs.readFileSync(tmp, 'utf8');
+  var liveStoreM = live.match(/(<script id="annotations-store" type="application\/json">)([\s\S]*?)(<\/script>)/);
+  var liveDoc = live.match(/var DOC_ID\s*=\s*'([^']*)'/);
+  if (!liveStoreM || !liveDoc || !liveDoc[1]) {
+    try { fs.unlinkSync(tmp); } catch (e2) {}
+    throw new Error('live 的 store/DOC_ID 读取失败');
+  }
+  t = t.replace(/var DOC_ID\s*=\s*'[^']*';/, "var DOC_ID = '" + liveDoc[1] + "';");
+  t = t.replace(/var FILE_NAME = '[^']*';/, "var FILE_NAME = '" + fileName + "';");
+  t = t.replace(/(<script id="annotations-store" type="application\/json">)[\s\S]*?(<\/script>)/, '$1' + liveStoreM[2] + '$2');
+  var newStoreM = t.match(/<script id="annotations-store" type="application\/json">[\s\S]*?<\/script>/);
+  var chk = rottenOf(t);
+  if (!newStoreM || newStoreM[0] !== liveStoreM[0] || chk.length) {
+    try { fs.unlinkSync(tmp); } catch (e2) {}
+    throw new Error('上盘前自检未过（store 不一致/' + chk.join('/') + '），fresh 已弃置');
+  }
+  fs.writeFileSync(tmp, t);   // 搬回修改后的整页写回临时文件，再进锁替换
+  return withDocLock(livePath, function () {
+    var now = fs.readFileSync(livePath, 'utf8');
+    if (now !== live) {
+      try { fs.unlinkSync(tmp); } catch (e2) {}
+      return { status: 'stale', note: '锁内发现 live 刚被写过，本次放弃（重新跑一遍 regen 即可）' };
+    }
+    var bakDir = path.join(path.dirname(livePath), HIST_DIR);
+    fs.mkdirSync(bakDir, { recursive: true });
+    var d = new Date();
+    var ts = d.getFullYear() + ('0' + (d.getMonth() + 1)).slice(-2) + ('0' + d.getDate()).slice(-2) + '-' +
+      ('0' + d.getHours()).slice(-2) + ('0' + d.getMinutes()).slice(-2) + ('0' + d.getSeconds()).slice(-2);
+    var bakPath = path.join(bakDir, fileName + '.pre-regen-' + ts + '.bak');
+    fs.writeFileSync(bakPath, live);
+    fs.renameSync(tmp, livePath);
+    try { fs.unlinkSync(path.join(bakDir, path.basename(tmp) + '.pre-inject.bak')); } catch (e2) {}
+    if (fs.readFileSync(livePath, 'utf8') !== t) {
+      fs.writeFileSync(livePath, live);
+      return { status: 'error', note: '写后读回不一致，已回滚' };
+    }
+    var st = readStore(t);
+    return { status: 'swapped', rev: st ? st.rev : 0, ann: st ? st.annotations.length : 0, bak: bakPath };
+  });
+}
+
+/* ---------- md：一键 Markdown → 可批注 HTML ---------- */
+/* 正文完全遵照原文（marked GFM：表格/删除线/任务列表/代码围栏照常），只叠加批注层。
+   marked 惰性加载——其余命令不付 require 成本；headerIds/mangle 关掉，
+   导航跳转走绝对坐标不需要 id，中文标题也不会被转成转义 id。表格外包 .table-wrap 套模板容器样式。 */
+
+/* ---- v1.38.0 公式渲染：$...$ 与 $$...$$ 经 temml 编译为 MathML 烤进产物 ----
+ * 产物仍零依赖：MathML 由浏览器原生渲染（Chrome 109+/Firefox/Safari），无运行时 JS/CSS/字体；
+ * 编译发生在生成时，temml 是构建期依赖（与 marked 同待遇：包依赖、惰性加载）。
+ * 降级链：temml 缺失或单条编译失败 → 该处保留 LaTeX 原文，绝不让坏公式毁掉整篇文档。
+ * 防误伤：pre/code 整块豁免；只处理标签之间的文本段；行内 $...$ 两端不得是空白、
+ * 须含字母/命令/花括号（成对美元金额「$5 和 $3」不命中）。 */
+function decodeMathEntities(s) {
+  return s.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+function mdMathPass(html) {
+  var temml;
+  try { temml = require('./vendor/temml.cjs'); } catch (e) { return html; }
+  if (!temml || typeof temml.renderToString !== 'function') return html;
+  var stash = [];
+  var h = html.replace(/<(pre|code)\b[^>]*>[\s\S]*?<\/\1>/gi, function (m) {
+    stash.push(m); return '\u0000M' + stash.length + '\u0000';
+  });
+  var parts = h.split(/(<[^>]*>)/);
+  for (var i = 0; i < parts.length; i += 2) {   // 偶数下标 = 标签之间的文本段
+    parts[i] = parts[i]
+      .replace(/\$\$([^$]+?)\$\$/g, function (m, tex) {
+        try {
+          return temml.renderToString(decodeMathEntities(tex),
+            { displayMode: true, throwOnError: true, annotate: true });
+        } catch (e) { return m; }
+      })
+      .replace(/\$([^$\n]+?)\$/g, function (m, tex) {
+        var t = decodeMathEntities(tex);
+        if (/^\s|\s$/.test(t)) return m;          // 两端空白 → 更像美元金额
+        if (!/[A-Za-z\\{]/.test(t)) return m;     // 无字母/命令/花括号 → 不像公式
+        try {
+          return temml.renderToString(t,
+            { displayMode: false, throwOnError: true, annotate: true });
+        } catch (e) { return m; }
+      });
+  }
+  h = parts.join('');
+  return h.replace(/\u0000M(\d+)\u0000/g, function (m, n) { return stash[n - 1] || m; });
+}
+
+function mdToBody(mdText) {
+  var marked = require('./vendor/marked.cjs');
+  var fn = typeof marked.parse === 'function' ? marked.parse.bind(marked)
+    : (marked && marked.marked && typeof marked.marked.parse === 'function') ? marked.marked.parse.bind(marked.marked)
+    : typeof marked === 'function' ? marked : null;
+  if (!fn) throw new Error('marked 加载失败，请重装依赖（npm install）');
+  return mdMathPass(fn(mdText, { gfm: true, breaks: false, headerIds: false, mangle: false })
+    .replace(/<table>/g, '<div class="table-wrap"><table>')
+    .replace(/<\/table>/g, '</table></div>'));
+}
+
+function mdDoc(srcPath, opts, pkgRoot) {
+  opts = opts || {};
+  var src = path.resolve(srcPath || '');
+  if (!fs.existsSync(src)) throw new Error('找不到 Markdown 文件: ' + src);
+  if (fs.statSync(src).isDirectory()) throw new Error('这是目录，不是 Markdown 文件: ' + src);
+  var name = opts.out ||
+    path.join(path.dirname(src), path.basename(src).replace(/\.(md|markdown|mdown|mkd)$/i, '') + '.html');
+  if (!/\.html?$/i.test(name)) name += '.html';
+  var dst = path.resolve(name);                       // 默认与 md 同目录同名；--out 可指定（相对路径按 cwd 解析）
+  if (fs.existsSync(dst)) throw new Error('文件已存在: ' + dst);
+
+  var rsl = resolveTemplate(path.dirname(dst), pkgRoot, opts);
+  var tpl = rsl.tpl, tplSrc = rsl.src;
+  var theme = loadThemeChain(path.dirname(dst), opts);
+  tpl = applyTheme(tpl, theme);
+  if (opts.lang === 'en') tpl = applyLangEn(tpl).html;
+
+  var body = mdToBody(fs.readFileSync(src, 'utf8'));
+  var mTitle = body.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
+  var title = opts.title || (mTitle ? mTitle[1].replace(/<[^>]+>/g, '').trim() : '') ||
+    path.basename(dst).replace(/\.html?$/i, '');
+  tpl = tpl.replace(/<title>[\s\S]*?<\/title>/, '<title>' + title + '</title>');
+  tpl = tpl.replace(/<article>[\s\S]*?<\/article>/, '<article>\n' + body + '\n  </article>');
+
+  var docId = 'doc-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  tpl = tpl.replace(/var DOC_ID\s*=\s*'[^']*';/, "var DOC_ID = '" + docId + "';");
+  tpl = tpl.replace(/var FILE_NAME = '[^']*';/, "var FILE_NAME = '" + path.basename(dst) + "';");
+  tpl = stampPageVersion(tpl, pkgRoot);
+
+  fs.writeFileSync(dst, tpl);
+  console.log('已从 Markdown 创建可批注文档: ' + dst);
+  console.log('  来源: ' + src + ' · 模板: ' + tplSrc + (theme ? ' + 主题(' + THEME_FILE + ')' : ''));
+  console.log('用 Edge/Chrome 打开即可批注与编辑；正文完全遵照原文，仅叠加批注层。');
+  return dst;
+}
+
+var path = require('path');
+
+module.exports = {
+  readPending: readPending, applyReplies: applyReplies,
+  readAnswers: readAnswers, applyAnswers: applyAnswers, listAnswers: listAnswers, teachDoc: teachDoc,
+  initKit: initKit, newDoc: newDoc,
+  mdDoc: mdDoc, mdToBody: mdToBody, mdMathPass: mdMathPass,
+  exportTheme: exportTheme, exportTemplate: exportTemplate,
+  templateUse: templateUse, templateReset: templateReset,
+  studioHtml: studioHtml, annotParts: annotParts,
+  installSkill: installSkill, injectHtml: injectHtml,
+  upgradeLayerFile: upgradeLayerFile, silentUpgrade: silentUpgrade, upgradeDir: upgradeDir, layerVerOf: layerVerOf,
+  regenDoc: regenDoc, wordLockActive: wordLockActive,
+  readStore: readStore, applyTheme: applyTheme, loadTheme: loadTheme,
+  pkgVersion: pkgVersion, skillVersionOf: skillVersionOf,
+  stampVersion: stampVersion, staleSkillNotice: staleSkillNotice,
+  applyEdits: applyEdits, buildHtmlIndex: buildHtmlIndex, findQuoteHit: findQuoteHit,
+  answersBlockOf: answersBlockOf, closeOrphanStreams: closeOrphanStreams, clearAnnStreamFlags: clearAnnStreamFlags,
+  applyLangEn: applyLangEn,
+  commonSuffixLength: commonSuffixLength, commonPrefixLength: commonPrefixLength, bestOccurrence: bestOccurrence,
+  pendingState: pendingState, pollAnnotations: pollAnnotations, streamReply: streamReply, hasUserText: hasUserText,
+  watchBeatPath: watchBeatPath, readWatchBeat: readWatchBeat, writeWatchBeat: writeWatchBeat,
+  watchGapNote: watchGapNote, watchGapNoteFrom: watchGapNoteFrom,
+  histSidePath: histSidePath, readSideHist: readSideHist, writeSideHist: writeSideHist, writeHistForFile: writeHistForFile,
+  mergeHistory: mergeHistory, commitHistory: commitHistory, docIdOf: docIdOf,
+  histCapsOf: histCapsOf,
+  withDocLock: withDocLock, writeDocAtomic: writeDocAtomic, appendWriteTicket: appendWriteTicket,
+  saveDocHtml: saveDocHtml, docLockPath: docLockPath, docWritesLogPath: docWritesLogPath,
+  findLastRevWithQuote: findLastRevWithQuote, fuzzyFindByContext: fuzzyFindByContext, normSnippet: normSnippet,
+  histForFile: histForFile, lintStructure: lintStructure,
+  ANCHOR_SUSPECT_LEN: ANCHOR_SUSPECT_LEN,
+  globalTemplatePath: globalTemplatePath, globalThemePath: globalThemePath, globalDir: globalDir,
+  HIST_DIR: HIST_DIR, HIST_MAIN_MAX: HIST_MAIN_MAX, HIST_SIDECAR_MAX: HIST_SIDECAR_MAX, THEME_FILE: THEME_FILE
+};