annotatable-html 1.38.3 → 1.45.3

package/lib/codex.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/* Optional Codex notification transport. No settings or credentials are changed.
+ * The control socket uses WebSocket; app-server proxy forwards its raw bytes.
+ * Node 22+ supplies WebSocket, so the package keeps its zero-dependency install. */
+var fs = require('fs');
+var path = require('path');
+var os = require('os');
+var net = require('net');
+var cp = require('child_process');
+var runPoll = require('./poll-process.js').runPoll;
+
+function binaryFor(opts) {
+  if (opts.codexBin) return opts.codexBin;
+  if (process.platform === 'win32') {
+    var home = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    var managed = path.join(home, 'packages', 'app-server-daemon', 'current', 'bin', 'codex.exe');
+    if (fs.existsSync(managed)) return managed;
+  }
+  return 'codex';
+}
+
+class CodexRpc {
+  constructor(binary) {
+    if (typeof WebSocket !== 'function') throw new Error('Codex 通知需要 Node.js 22+；普通 poll 仍支持 Node.js 14+');
+    this.nextId = 0;
+    this.pending = new Map();
+    this.stderr = '';
+    this.child = cp.spawn(binary, ['app-server', 'proxy'], { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    this.child.stderr.on('data', chunk => { this.stderr = (this.stderr + chunk).slice(-2000); });
+    this.child.on('error', err => this.abort(err));
+    this.child.stdin.on('error', err => this.abort(err));
+    this.child.on('exit', code => {
+      if (!this.closing) this.abort(new Error('Codex proxy 已退出 (' + code + ')：' + this.stderr));
+    });
+    this.bridge = net.createServer(socket => {
+      this.socket = socket;
+      socket.on('error', err => this.abort(err));
+      socket.pipe(this.child.stdin);
+      this.child.stdout.pipe(socket);
+    });
+  }
+  abort(err) {
+    this.failure = err;
+    for (const waiter of this.pending.values()) { clearTimeout(waiter.timer); waiter.reject(err); }
+    this.pending.clear();
+    if (this.socket) this.socket.destroy();
+  }
+  request(method, params) {
+    return new Promise((resolve, reject) => {
+      if (this.failure) { reject(this.failure); return; }
+      const id = ++this.nextId;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error('Codex ' + method + ' 超时'));
+      }, 10000);
+      this.pending.set(id, { resolve, reject, timer });
+      try { this.ws.send(JSON.stringify({ id, method, params })); }
+      catch (err) { clearTimeout(timer); this.pending.delete(id); reject(err); }
+    });
+  }
+  async open() {
+    await new Promise((resolve, reject) => {
+      this.bridge.once('error', reject);
+      this.bridge.listen(0, '127.0.0.1', resolve);
+    });
+    if (this.failure) throw this.failure;
+    this.ws = new WebSocket('ws://127.0.0.1:' + this.bridge.address().port);
+    this.ws.addEventListener('message', event => {
+      let msg;
+      try { msg = JSON.parse(event.data); } catch (_) { return; }
+      const waiter = this.pending.get(msg.id);
+      if (!waiter) return;
+      this.pending.delete(msg.id);
+      clearTimeout(waiter.timer);
+      if (msg.error) waiter.reject(new Error(JSON.stringify(msg.error)));
+      else waiter.resolve(msg.result);
+    });
+    this.ws.addEventListener('close', () => {
+      if (!this.closing) this.abort(new Error('Codex 控制连接已关闭'));
+    });
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('Codex WebSocket 握手超时：' + this.stderr)), 10000);
+      this.ws.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+      this.ws.addEventListener('error', () => { clearTimeout(timer); reject(this.failure || new Error('Codex WebSocket 握手失败：' + this.stderr)); }, { once: true });
+    });
+    await this.request('initialize', {
+      clientInfo: { name: 'annotatable_html', title: 'Annotatable HTML', version: require('../package.json').version },
+      capabilities: { experimentalApi: true }
+    });
+    this.ws.send(JSON.stringify({ method: 'initialized', params: {} }));
+  }
+  async read(threadId, includeTurns) {
+    return (await this.request('thread/read', { threadId, includeTurns: !!includeTurns })).thread;
+  }
+  close() {
+    this.closing = true;
+    this.abort(new Error('Codex 连接已结束'));
+    if (this.ws) this.ws.close();
+    this.bridge.close();
+    this.child.stdin.end();
+    this.child.kill();
+  }
+}
+
+async function withRpc(opts, action) {
+  var rpc = new CodexRpc(binaryFor(opts));
+  try { await rpc.open(); return await action(rpc); }
+  finally { rpc.close(); }
+}
+
+async function pollAnnotations(htmlPath, opts) {
+  opts = opts || {};
+  var threadId = opts.codexThread || process.env.CODEX_THREAD_ID;
+  if (!threadId) throw new Error('缺少 Codex 会话 ID：在目标会话中运行，或传 --codex-thread ID');
+  var notifier;
+  try {
+    notifier = await createNotifier(threadId, opts);
+    console.log('CODEX_READY ' + JSON.stringify({ threadId: threadId, transport: notifier.kind }));
+    var result = await runPoll(htmlPath, opts);
+    if (result.hit) {
+      var notified = await notifier.notify(result.hit);
+      console.log('CODEX_NOTIFIED ' + JSON.stringify(Object.assign({ file: result.hit.file }, notified)));
+    }
+    process.exitCode = result.code;
+  } finally { if (notifier) notifier.close(); }
+}
+
+function requireLoaded(thread) {
+  if (!thread || !thread.status || !['active', 'idle'].includes(thread.status.type)) {
+    throw new Error('目标会话未加载到此 app-server；聊天记录存在不代表可通知。请从托管该会话的 Codex 桌面重新启动监听，勿在其他服务 resume 同一会话');
+  }
+}
+
+async function createNotifier(threadId, opts) {
+  opts = opts || {};
+  var mode = opts.codexTransport || 'auto';
+  if (!['auto', 'desktop', 'app-server'].includes(mode)) throw new Error('未知 Codex 通知方式：' + mode);
+  var pipePath = opts.codexPipe || process.env.CODEX_APP_TOOLS_PIPE_PATH;
+  var notifier;
+  try {
+    if (mode === 'desktop' || (mode === 'auto' && pipePath)) {
+      if (!pipePath) throw new Error('缺少 CODEX_APP_TOOLS_PIPE_PATH；请在 Codex 桌面会话中启动监听');
+      var turnId = opts.codexTurn || process.env.CODEX_TURN_ID;
+      if (!turnId) {
+        // Read only the persisted turn id for call provenance. Never resume a
+        // thread here: the desktop service remains the sole runtime owner.
+        var turns = await withRpc(opts, rpc => rpc.request('thread/turns/list', {
+          threadId: threadId, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded'
+        }));
+        turnId = turns.data && turns.data[0] && turns.data[0].id;
+        if (!turnId) throw new Error('无法读取来源轮次；请用 --codex-turn 指定当前轮次 ID');
+      }
+      notifier = new (require('./codex-desktop.js').DesktopNotifier)(pipePath, threadId, turnId);
+      await notifier.open();
+    } else {
+      var rpc = new CodexRpc(binaryFor(opts));
+      notifier = { kind: 'app-server', close: () => rpc.close(), notify: async hit => {
+        requireLoaded(await rpc.read(threadId));
+        var result = await rpc.request('turn/start', { threadId: threadId, input: [], toolOutput: {
+          name: 'annotatable_poll', output: 'POLL_HIT ' + JSON.stringify(hit)
+        } });
+        return { threadId: threadId, turnId: result.turn.id, transport: 'app-server' };
+      } };
+      await rpc.open();
+      requireLoaded(await rpc.read(threadId));
+    }
+    return notifier;
+  } catch (error) { if (notifier) notifier.close(); throw error; }
+}
+
+async function dutyBinding(file, options) {
+  var threadId = options.codexThread || process.env.CODEX_THREAD_ID;
+  if (!/^[a-f0-9-]{36}$/i.test(threadId || '')) throw new Error('续接必须绑定明确的 Codex 会话编号');
+  var pipePath = options.codexPipe || process.env.CODEX_APP_TOOLS_PIPE_PATH;
+  if (!pipePath) throw new Error('请从目标桌面会话注册页面，不根据最近聊天猜测目标');
+  var binary = options.codexBin || process.env.CODEX_APP_RUNTIME_CLI_PATH || binaryFor(options);
+  var notifier = await createNotifier(threadId, { codexTransport: 'desktop', codexPipe: pipePath, codexTurn: options.codexTurn, codexBin: binary });
+  var rpc, processes = require('./duty-process');
+  try {
+    var desktop = await processes.pipeOwners(pipePath);
+    rpc = new CodexRpc(binary); await rpc.open();
+    var settings = require('./codex-headless').readSettings(await rpc.read(threadId, false));
+    return { threadId: threadId, binary: binary, codexHome: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), settings: settings,
+      desktop: { pipePath: pipePath, turnId: notifier.context.turnId, owners: desktop.owners.map(processes.identity), main: processes.identity(desktop.main) } };
+  } finally { notifier.close(); if (rpc) rpc.close(); }
+}
+function createDutyAdapter(getBinding, updateBinding) {
+  var notifier, processes = require('./duty-process');
+  async function online() {
+    if (notifier) {
+      try { var r = await notifier.read(); return { available: true, active: r.thread.status.type === 'active', notify: hit => notifier.notify(hit, { managed: true }) }; }
+      catch (_) { notifier.close(); notifier = null; }
+    }
+    var current = getBinding(), successes = [];
+    for (var candidate of processes.pipeCandidates(current.desktop.pipePath)) {
+      var item;
+      try {
+        item = await createNotifier(current.threadId, { codexTransport: 'desktop', codexPipe: candidate, codexTurn: current.desktop.turnId, codexBin: current.binary });
+        var owner = await processes.pipeOwners(candidate);
+        successes.push({ notifier: item, owners: owner.owners.map(processes.identity), main: processes.identity(owner.main), pipe: candidate });
+      } catch (_) { if (item) item.close(); }
+    }
+    if (successes.length !== 1) { successes.forEach(x => x.notifier.close()); return null; }
+    var selected = successes[0]; notifier = selected.notifier;
+    updateBinding(Object.assign({}, current, { desktop: { pipePath: selected.pipe, owners: selected.owners, main: selected.main, turnId: current.desktop.turnId } }));
+    var result = await notifier.read();
+    return { available: true, active: result.thread.status.type === 'active', notify: hit => notifier.notify(hit, { managed: true }) };
+  }
+  return { online: online, released: () => processes.released(getBinding().desktop.owners),
+    run: (hit, onStart) => require('./codex-headless').runHeadless(getBinding(), hit, { onStart: onStart }),
+    close: () => { if (notifier) notifier.close(); } };
+}
+
+module.exports = { CodexRpc: CodexRpc, pollAnnotations: pollAnnotations,
+  createNotifier: createNotifier, requireLoaded: requireLoaded, dutyBinding: dutyBinding, createDutyAdapter: createDutyAdapter };

package/lib/core.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /* 可批注 HTML · 核心逻辑
- * 供 bin/cli.js 与 agent/ 薄封装共用；与 AGENTS.md 描述的工作流保持一致。 */
+ * 供 bin/cli.js 与 agent/ 薄封装共用；工作流协议随 annotatable-html skill 分发。 */
 
 var fs = require('fs');
 var path = require('path');
@@ -12,19 +12,13 @@ var LANG = require('./lang-en.js');
  * 词典本体（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 ═══ -->'
+  '<!-- ═══ ANNOTATION DATA BEGIN — data location for the annotatable-html skill:',
+  'Use annotatable read/reply/edit/poll. The tools maintain revisions and history; do not hand-edit store JSON.',
+  'The skill defines the workflow. Answer content and teaching methods belong to the user-selected content workflow ═══ -->'
 ].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 ═══ -->'
+  '<!-- ═══ LESSON DATA BEGIN — legacy extended-answer data. Preserve existing content.',
+  'Ordinary annotation replies use reply; this block is not a default teaching workflow ═══ -->'
 ].join('\n');
 function applyLangEn(tpl) {
   var pairs = LANG.pairs.slice().sort(function (a, b) { return b[0].length - a[0].length; });
@@ -510,7 +504,7 @@ function pollAnnotations(htmlPath, opts) {
     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);
+    process.exit(opts.exitCode || 0);   // v1.38.4 命中退出码可配（issue#8）：zcode 等任务退出即唤醒 → 默认 0；Claude Code 等非零才唤醒 → --exit-code 1
   }
   if (st.pending || st.replay) hit(st);
   console.log('已有批注都已回应，等待新批注…（每 ' + intervalSec + 's 检查' + (timeoutSec ? '，最长 ' + timeoutSec + 's' : '') + '，Ctrl+C 退出）');
@@ -528,7 +522,11 @@ function pollAnnotations(htmlPath, opts) {
     }
     if (deadline && Date.now() > deadline) {
       writeWatchBeat(htmlPath, 'handoff', startedAt);
-      console.log('TIMEOUT · 待回应=' + s2.pending); process.exit(3);
+      console.log('TIMEOUT · 待回应=' + s2.pending);
+      /* v1.38.4 超时退出码可配（issue#8）：默认 3 向后兼容；传 0 = 超时轮空静默退出
+       * 不叫醒 agent（Claude Code 等非零即唤醒的 harness 需要）。NaN/未传回 3。 */
+      var tec = parseInt(opts.timeoutExitCode, 10);
+      process.exit(isNaN(tec) ? 3 : tec);
     }
   }, intervalSec * 1000);
 }
@@ -875,85 +873,6 @@ function applyAnswers(htmlPath, answersPath) {
   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）对齐的充分近似：
@@ -1332,17 +1251,66 @@ function applyTheme(tpl, theme) {
   var rootMatch = theme.match(/:root\s*\{[^}]*\}/);
   if (rootMatch) {
     rest = theme.replace(rootMatch[0], '');
-    tpl = tpl.replace(/:root\s*\{[^}]*\}/, rootMatch[0]);   // 替换文档默认变量块
+    // Keep defaults that a partial theme omits; later declarations override them.
+    var overrides = rootMatch[0].slice(rootMatch[0].indexOf('{') + 1, -1);
+    tpl = tpl.replace(/:root\s*\{([^}]*)\}/, function (_, defaults) {
+      return ':root{' + defaults + '\n' + overrides + '\n}';
+    });
   }
-  if (rest.trim()) tpl = tpl.replace('</style>', rest + '\n</style>');  // 追加覆盖样式
+  if (rest.trim()) tpl = tpl.replace('</style>', function () { return rest + '\n</style>'; });
   return tpl;
 }
 
 /* init：把工作流文件装进目标目录（已存在的不覆盖） */
-function initKit(dir, pkgRoot) {
+/* ---------- v1.38.4 文档侧 kit 拷贝「触碰即同步」（issue#7 根因修复）----------
+ * init 分发的 lib/core.js + agent/annot_*.js 拷贝进文档目录后从不随包升级（initKit
+ * 对已存在文件一律跳过）——v1.29.0 纯划线静默等一切后续改进都触达不到存量项目，
+ * 文档侧值守行为随拷贝版本静止腐烂。实证：某文档项目拷贝停在 v1.18.0，纯划线
+ * 被 poll 判 pending=1 挂起即命中 → 空转循环，而 read 走全局新版却正确静默，
+ * 同一份数据两种判定。与页面层静默升级（v1.36.0）同哲学：永远新鲜的组件（全局包）
+ * 在触碰时把设施拉齐。只同步代码设施（agent/*.js + lib/core.js，无用户数据）；
+ * AGENTS.md、模板、主题可能含用户手改，不碰。覆盖前备份 .bak-kit-<时间戳>。
+ * 提示走 stderr：stdout 是 agent 的解析面（read 清单/POLL_HIT 载荷），不掺行。 */
+var KIT_CODE_FILES = [
+  'agent/annot_read.js', 'agent/annot_reply.js', 'agent/annot_edit.js',
+  'agent/annot_answer.js', 'agent/annot_poll.js', 'lib/core.js', 'lib/lang-en.js'
+];
+function syncKitCode(dir, pkgRoot) {
+  var updated = [];
+  KIT_CODE_FILES.forEach(function (rel) {
+    var dst = path.join(dir, rel), src = path.join(pkgRoot, rel), cur, nw;
+    try { cur = fs.readFileSync(dst, 'utf8'); } catch (e) { return; }   // 该目录没分发过 kit → 无事可做
+    try { nw = fs.readFileSync(src, 'utf8'); } catch (e) { return; }
+    if (cur === nw) return;
+    fs.writeFileSync(dst + '.bak-kit-' + Date.now(), cur);
+    fs.writeFileSync(dst, nw);
+    updated.push(rel);
+  });
+  if (updated.length) {
+    try {
+      console.error('ℹ 文档侧 agent 设施已同步到当前包版本（' + updated.length + ' 个文件；旧版留 .bak-kit-* 备份）');
+    } catch (e) { /* stdout/stderr 关闭（管道早闭）不阻塞 */ }
+  }
+  return updated;
+}
+
+/* 查找已安装的批注 skill；初始化不再向宿主指令文件写入协议。 */
+function skillProbe(home) {
+  /* v1.40.0：扫主流 harness 全集——.agents(共享仓)/.zcode/.claude/.codex/.config/opencode */
+  var dirs = ['.agents', '.zcode', '.claude', '.codex', path.join('.config', 'opencode')];
+  for (var i = 0; i < dirs.length; i++) {
+    if (fs.existsSync(path.join(home, dirs[i], 'skills', 'annotatable-html', 'SKILL.md'))) return true;
+  }
+  return false;
+}
+function initKit(dir, pkgRoot, opts) {
+  if (opts && opts.agentsMd !== undefined) {
+    throw new Error('init 不再写入 AGENTS.md；请运行 annotatable skill 安装批注工作流。');
+  }
   dir = dir || process.cwd();
+  var created = [], skipped = [], upgraded = [];
+  fs.mkdirSync(dir, { recursive: true });
   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'],
@@ -1350,13 +1318,25 @@ function initKit(dir, pkgRoot) {
     ['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']
+    ['lib/core.js', 'lib/core.js'],
+    ['lib/lang-en.js', 'lib/lang-en.js']   // v1.38.4：core.js require('./lang-en.js')，漏分发=文档侧薄封装加载即崩（e2e 实弹揪出）
   ];
-  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; }
+    if (fs.existsSync(dst)) {
+      /* v1.38.4：代码设施已存在不再是「跳过」——与包内不同则备份后升级（拷贝静止腐烂
+       * = issue#7 根因）；模板/主题可能含用户手改，维持跳过。 */
+      if (KIT_CODE_FILES.indexOf(it[0]) !== -1) {
+        var cur = fs.readFileSync(dst, 'utf8'), nw = fs.readFileSync(src, 'utf8');
+        if (cur !== nw) {
+          fs.writeFileSync(dst + '.bak-kit-' + Date.now(), cur);
+          fs.writeFileSync(dst, nw);
+          upgraded.push(it[1]);
+        }
+      } else skipped.push(it[1]);
+      return;
+    }
     fs.mkdirSync(path.dirname(dst), { recursive: true });
     fs.copyFileSync(src, dst);
     created.push(it[1]);
@@ -1364,12 +1344,13 @@ function initKit(dir, pkgRoot) {
   console.log('初始化完成 → ' + dir);
   created.forEach(function (f) { console.log('  + ' + f); });
   skipped.forEach(function (f) { console.log('  = 已存在，跳过: ' + f); });
+  upgraded.forEach(function (f) { console.log('  ↑ 已升级（旧版留 .bak-kit-* 备份）: ' + 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。');
+  console.log('批注工作流由 annotatable-html skill 提供；未安装时运行 annotatable skill。');
 }
 
 /* new：从模板新建可批注文档
@@ -1595,11 +1576,13 @@ function staleSkillNotice(pkgRoot, baseDir) {
     var home = baseDir || os.homedir();
     var ver = pkgVersion(pkgRoot);
     var stale = [];
-    ['.zcode', '.claude'].forEach(function (d) {
+    ['.zcode', '.claude', '.codex'].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);
     });
+    var foc = skillVersionOf(path.join(home, '.config', 'opencode', 'skills', 'annotatable-html', 'SKILL.md'));
+    if (foc !== null && foc !== ver) stale.push(path.join(home, '.config', 'opencode', 'skills', 'annotatable-html'));
     if (!stale.length) return '';
     return '⚠ 已安装的 skill 副本落后于当前包 v' + ver + '（' + stale.length + ' 份），运行 annotatable skill 可自动升级';
   } catch (e) { return ''; }
@@ -1613,12 +1596,17 @@ function installSkill(opts, pkgRoot, baseDir) {
   var os = require('os');
   var home = baseDir || os.homedir();
   var ver = pkgVersion(pkgRoot);
+  /* v1.40.0 兼容主流 harness（对外发布口径）：Codex(~/.codex/skills) 与 opencode(~/.config/opencode/skills)
+   * 均采 Agent Skills 开放标准的 SKILL.md 形态，拷入即生效；slash 命令仍是 zcode/claude 公约不投。
+   * 指定任一旗标则只投该家（+agents 共享仓），无旗标默认投全部主流四家。 */
+  var anyHarness = opts.zcode || opts.claude || opts.codex || opts.opencode;
   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 });
+  if (opts.zcode || !anyHarness) targets.push({ name: 'ZCode', base: path.join(home, '.zcode'), cmd: true });
+  if (opts.claude || !anyHarness) targets.push({ name: 'Claude Code', base: path.join(home, '.claude'), cmd: true });
+  if (opts.codex || !anyHarness) targets.push({ name: 'Codex', base: path.join(home, '.codex') });
+  if (opts.opencode || !anyHarness) targets.push({ name: 'opencode', base: path.join(home, '.config', 'opencode'), opencodePlugin: true });
+  /* 共享仓与各 harness 都安装完整 skill；补充协议只放在技能目录内。 */
+  targets.push({ name: 'agents(共享仓)', base: path.join(home, '.agents') });
   var srcSkill = path.join(pkgRoot, 'templates', 'SKILL.md');
   var cmdDir = path.join(pkgRoot, 'templates', 'commands');
   var installed = [], skipped = 0;
@@ -1634,21 +1622,40 @@ function installSkill(opts, pkgRoot, baseDir) {
       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));
+    var agDst = path.join(t.base, 'skills', 'annotatable-html', 'AGENTS.md');
+    if (fs.existsSync(agDst)) {
+      var legacy = fs.readFileSync(agDst, 'utf8');
+      if (skillVersionOf(agDst) && legacy.indexOf('# 可批注 HTML 工作流') !== -1) {
+        var skillRoot = path.resolve(path.dirname(agDst));
+        var legacyBackup = path.resolve(agDst + '.legacy-' + Date.now() + '.bak');
+        if (path.dirname(legacyBackup) !== skillRoot) throw new Error('技能协议备份路径异常');
+        fs.renameSync(path.resolve(agDst), legacyBackup);
+        installed.push(t.name + ' 旧技能协议已移入备份 → ' + legacyBackup);
       }
     }
+    ['hosts.md', 'operations.md', 'compatibility.md'].forEach(function (name) {
+      var refDst = path.join(path.dirname(skillDst), 'references', name);
+      if (skillVersionOf(refDst) === ver) { skipped++; return; }
+      fs.mkdirSync(path.dirname(refDst), { recursive: true });
+      fs.copyFileSync(path.join(pkgRoot, 'templates', 'references', name), refDst);
+      stampVersion(refDst, ver);
+      installed.push(t.name + ' 按需说明 → ' + refDst);
+    });
+    if (t.opencodePlugin) {
+      var pluginSrc = path.join(pkgRoot, 'templates', 'opencode', 'annotatable-html.js');
+      var pluginDst = path.join(t.base, 'plugins', 'annotatable-html.js');
+      var pluginText = fs.readFileSync(pluginSrc, 'utf8') + '\n// annotatable-html v' + ver + '\n';
+      var oldPlugin = null;
+      try { oldPlugin = fs.readFileSync(pluginDst, 'utf8'); } catch (e) { /* first install */ }
+      if (oldPlugin !== pluginText) {
+        fs.mkdirSync(path.dirname(pluginDst), { recursive: true });
+        if (oldPlugin !== null) fs.writeFileSync(pluginDst + '.bak-' + Date.now(), oldPlugin);
+        fs.writeFileSync(pluginDst, pluginText);
+        installed.push('opencode 会话上下文插件 → ' + pluginDst);
+      } else skipped++;
+    }
     // 命令独立于 skill 处理（升级时清理旧命令、安装新命令）
-    if (fs.existsSync(cmdDir) && !t.agentsHub) {
+    if (fs.existsSync(cmdDir) && t.cmd) {
       // 清理 v1.3.0 的旧命令文件（已被 html4agent.md 取代）
       ['读批注.md', '可批注文档.md'].forEach(function (old) {
         var oldDst = path.join(t.base, 'commands', old);
@@ -1714,7 +1721,7 @@ function annotParts(tpl) {
 }
 
 function annotStoreBlock() {
-  return '<!-- ═══ AI批注数据 BEGIN — agent 读取协议见 AGENTS.md ═══ -->\n' +
+  return '<!-- ═══ AI批注数据 BEGIN — agent 读取协议见 annotatable-html skill ═══ -->\n' +
     '<script id="annotations-store" type="application/json">\n' +
     JSON.stringify({ rev: 0, annotations: [], history: [] }) + '\n</' + 'script>\n' +
     '<!-- ═══ AI批注数据 END ═══ -->\n';
@@ -1943,6 +1950,7 @@ function upgradeLayerFile(targetPath, pkgRoot, opts) {
 }
 /* agent 触碰即换装：六个读写命令与 serve 启动的统一钩子。任何失败只提示一行，绝不阻塞原操作。 */
 function silentUpgrade(htmlPath) {
+  try { syncKitCode(path.dirname(htmlPath), path.join(__dirname, '..')); } catch (e) { /* 设施同步尽力而为 */ }
   try {
     var r = upgradeLayerFile(htmlPath, path.join(__dirname, '..'));
     if (r && r.status === 'upgraded')
@@ -2166,8 +2174,8 @@ var path = require('path');
 
 module.exports = {
   readPending: readPending, applyReplies: applyReplies,
-  readAnswers: readAnswers, applyAnswers: applyAnswers, listAnswers: listAnswers, teachDoc: teachDoc,
-  initKit: initKit, newDoc: newDoc,
+  readAnswers: readAnswers, applyAnswers: applyAnswers, listAnswers: listAnswers,
+  initKit: initKit, syncKitCode: syncKitCode, skillProbe: skillProbe, newDoc: newDoc,
   mdDoc: mdDoc, mdToBody: mdToBody, mdMathPass: mdMathPass,
   exportTheme: exportTheme, exportTemplate: exportTemplate,
   templateUse: templateUse, templateReset: templateReset,