annotatable-html 0.0.0-stage → 1.38.3

package/bin/cli.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+'use strict';
+
+/* annotatable-html 命令行入口
+ *   annotatable init [dir]                  初始化目录（AGENTS.md + 工具 + 模板 + 主题）
+ *   annotatable new <名称.html> [--template 路径]
+ *                                           新建可批注文档（自动应用目录内主题/自定义模板）
+ *   annotatable md <文件.md> [-o 输出.html] [--title 标题] [--template 路径]
+ *                                           一键 Markdown → 可批注 HTML（正文遵照原文，仅加批注层）
+ *   annotatable theme                       导出默认主题文件（annotatable.theme.css）供微调
+ *   annotatable studio [--port 端口]        打开可视化主题工坊（配色/字体/字号/页宽，实时预览）
+ *   annotatable template [名称.html]        导出内置模板供深度改造
+ *   annotatable template --use <文件.html>  把你的 HTML 一键设为全局默认模板（整页保留原样式）
+ *   annotatable template --reset            撤销全局默认模板，恢复内置
+ *   annotatable read <file.html>            列出待回应批注
+ *   annotatable reply <file.html> <replies.json>
+ *                                           写回 AI 回复（追加ai轮次+快照+rev+1）
+ *   annotatable poll <file.html> [--timeout 秒] [--interval 秒]
+ *                                           阻塞等待新批注（配后台任务：出批注即退出唤醒）
+ */
+
+var path = require('path');
+var core = require('../lib/core.js');
+
+var args = process.argv.slice(2);
+/* 短旗标别名：usage 宣传的 -o（md/teach）等价 --out——解析器只认 -- 长旗标，不归一化则 -o 静默落进位置参数（v1.37.3 及之前 -o 一直没生效的根因） */
+args = args.map(function (a) { return a === '-o' ? '--out' : a; });
+var cmd = args[0] || 'help';
+var positional = [], flags = {};
+var boolFlags = { zcode: true, claude: true, reset: true, stdin: true, go: true, force: true };
+for (var i = 1; i < args.length; i++) {
+  if (args[i].indexOf('--') === 0) {
+    var k = args[i].slice(2);
+    if (boolFlags[k]) { flags[k] = true; }
+    else if (args[i + 1] && args[i + 1].indexOf('--') !== 0) { flags[k] = args[i + 1]; i++; }   // 下一个是旗标时不当成值（--stream --id x）
+    else { flags[k] = ''; }
+  } else positional.push(args[i]);
+}
+
+/* 长文本（流式段落）经管道进：annotatable reply f.html --stream --stdin < 段落.txt */
+function readStdinSync() {
+  try { return require('fs').readFileSync(0, 'utf8'); } catch (e) { return ''; }
+}
+
+function usage() {
+  console.log([
+    'annotatable-html — 可批注 HTML：人类划线批注，AI agent 读批注回答',
+    '',
+    '用法:',
+    '  annotatable init [目录]                  初始化（AGENTS.md + agent 工具 + 模板 + 主题）',
+    '  annotatable new <名称.html> [--template 路径] [--lang en]',
+    '                                           新建可批注文档（自动应用主题/自定义模板）',
+    '  annotatable md <文件.md> [-o 输出.html] [--title 标题] [--lang en]',
+    '                                           一键 Markdown → 可批注 HTML（正文遵照原文，仅加批注层）',
+    '  annotatable theme                        导出主题文件 annotatable.theme.css 供微调',
+    '  annotatable studio [--port 端口]          打开可视化主题工坊（配色/字体/字号/页宽，实时预览）',
+    '  annotatable template [名称.html]         导出内置模板供深度改造',
+    '  annotatable template --use <文件.html>   把你的 HTML 一键设为全局默认模板（整页保留原样式）',
+    '  annotatable template --reset             撤销全局默认模板，恢复内置',
+    '  annotatable skill [--zcode] [--claude]   安装 skill + /html4agent 命令（任意目录触发）',
+    '  annotatable serve [目录] [--port N]      启动本地服务器（全自动保存，全浏览器支持；--port 0=系统挑空闲端口）',
+    '  annotatable inject <file.html>           给任意 HTML 注入批注层',
+  '  annotatable regen <活页.html> <图纸.html> [--go]  图纸页安全重建：报表手改清单，--go 上盘（store/DOC_ID 保留）',
+  '  annotatable upgrade <文件或目录>          旧层页批量静默换新层（read/reply/poll/serve 触达时也会自动做）',
+    '  annotatable read <file.html>             列出待回应批注（含对话线＋结构体检）',
+    '  annotatable reply <file.html> <replies.json>  写回 AI 回复（json 是文件路径，非内联）：[{"id":"..","reply":".."}]',
+    '  annotatable reply <file.html> --stream \'<段落>\' --id <批注id>',
+    '                                           流式追加一段回答（值守协议；不带 --id 自动接最近打开的流式轮；退出码 4=被打断 5=目标已删 6=人类编辑中，让路 7=没有打开中的流式轮）',
+    '  annotatable reply <file.html> --stream-end \'<全文>\' [--id <批注id>]',
+    '                                           收尾流式回答（全文替换段落累计，落快照）',
+    '  annotatable edit <file.html> <edits.json>   按批注指令改正文（json 是文件路径）：[{"id":"..","newText":".."}]',
+    '  annotatable answer <file.html> [json]    写入长答/教学卡（不带 json=列出既有卡）；',
+    '                                           json: [{"annId":"..","title":"..","rungs":[{"title":"..","body":"..","checkpoint":"..","answer":".."}]}]',
+    '  annotatable teach <源.html> [-o 输出.html] [--title 标题]',
+    '                                           从源文档批注生成教学文档脚手架（agent 随后用 edit 填充）',
+    '  annotatable poll <file.html> [--timeout 秒] [--interval 秒]',
+    '                                           阻塞等待新批注：有新批注打印 POLL_HIT 并退出（0=有批注 3=超时），',
+    '',
+    '图纸页维护：纯文字改动直接 edit/手改，别整页重生成；必须重生成（改图/大改版）时走 regen：',
+    '先报表（默认），把手改同步进图纸后 --go 上盘。人类编辑模式中，回复/教学卡退出码 6、regen 退出码 3——让路等收笔。',
+    '',
+    '典型循环: 人类在浏览器批注 → AI 运行 read → 生成 replies.json → 运行 reply → 人类刷新可见。'
+  ].join('\n'));
+}
+
+try {
+  /* skill 副本过期自检（skill 命令自身就会刷新升级，不再提示） */
+  if (['init', 'new', 'md', 'theme', 'template', 'studio', 'inject', 'upgrade', 'regen', 'read', 'reply', 'edit', 'answer', 'teach', 'poll', 'serve'].indexOf(cmd) !== -1) {
+    var notice = core.staleSkillNotice(path.join(__dirname, '..'));
+    if (notice) console.log(notice);
+  }
+  if (cmd === 'init') {
+    core.initKit(positional[0] || process.cwd(), path.join(__dirname, '..'));
+  } else if (cmd === 'new') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    core.newDoc(process.cwd(), positional[0], path.join(__dirname, '..'), { template: flags.template, lang: flags.lang });
+  } else if (cmd === 'md') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    core.mdDoc(positional[0], { out: flags.out, title: flags.title, template: flags.template, lang: flags.lang }, path.join(__dirname, '..'));
+  } else if (cmd === 'theme') {
+    core.exportTheme(process.cwd(), path.join(__dirname, '..'));
+  } else if (cmd === 'template') {
+    if (flags.use) {
+      core.templateUse(flags.use, path.join(__dirname, '..'), {});
+    } else if (flags.reset) {
+      core.templateReset({});
+    } else {
+      core.exportTemplate(process.cwd(), positional[0], path.join(__dirname, '..'));
+    }
+  } else if (cmd === 'studio') {
+    var sServe = require('../lib/serve.js');
+    var sPort = parseInt(flags.port, 10);
+    if (isNaN(sPort)) sPort = 8974;
+    var sPkg = path.join(__dirname, '..');
+    sServe.start(process.cwd(), sPort, { studioProvider: function () { return core.studioHtml(sPkg); } })
+      .then(function (info) {
+        var url = info.url + '/__annot/studio';
+        console.log('🎨 主题工坊已启动: ' + url);
+        console.log('  左侧调配色/字体/字号/页宽，右侧实时预览（批注、导航窗格可直接试）。');
+        console.log('  调好后点「保存到当前目录」或「设为全局默认」，之后 new / md 自动应用。按 Ctrl+C 停止。');
+        try {
+          if (!process.env.ANNOT_NO_OPEN) {   // e2e 等无人值守场景置 1 跳过自动开浏览器
+            var opener = process.platform === 'win32' ? 'start "" "' + url + '"'
+              : process.platform === 'darwin' ? 'open "' + url + '"' : 'xdg-open "' + url + '"';
+            require('child_process').exec(opener, function () { /* 打不开就手动复制地址 */ });
+          }
+        } catch (e) { /* 同上 */ }
+      });
+  } else if (cmd === 'skill') {
+    core.installSkill({ zcode: flags.zcode, claude: flags.claude }, path.join(__dirname, '..'), flags.dir);
+  } else if (cmd === 'serve') {
+    var fs = require('fs');
+    var serve = require('../lib/serve.js');
+    var dir = positional[0] || process.cwd();
+    var port = parseInt(flags.port, 10);
+    if (isNaN(port)) port = 8973;   // --port 0 = 系统挑空闲端口（合法值，不能用 || 吞掉）
+    serve.start(dir, port).then(function (info) {
+      console.log('可批注文档服务器已启动: ' + info.url);
+      console.log('伺服目录: ' + info.root);
+      core.upgradeDir(info.root);   // v1.36.0 开服即扫目录：旧层页静默换新层（有升级会各打一行）
+      try {
+        fs.readdirSync(info.root).forEach(function (f) {
+          if (/\.html?$/i.test(f)) console.log('  文档 → ' + info.url + '/' + encodeURIComponent(f));
+        });
+      } catch (e) { /* 目录尚为空或未创建，浏览器访问时再列 */ }
+      console.log('服务器模式：批注自动保存进文件，无需绑定/授权。按 Ctrl+C 停止。');
+    });
+  } else if (cmd === 'inject') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    core.injectHtml(positional[0], path.join(__dirname, '..'), { lang: flags.lang });
+  } else if (cmd === 'upgrade') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    var fsU = require('fs');
+    var upT = path.resolve(positional[0]);
+    var upIsDir;
+    try { upIsDir = fsU.statSync(upT).isDirectory(); } catch (e) { throw new Error('路径不存在: ' + upT); }
+    if (upIsDir) {
+      var upN = core.upgradeDir(upT);
+      console.log(upN ? '✅ 静默升级完成：' + upN + ' 个旧层页已换新层。' : '没有需要升级的旧层页（已是最新或不可自动换装）。');
+    } else {
+      var upR = core.silentUpgrade(upT);
+      if (!upR || upR.status === 'skip') console.log('未升级：' + ((upR && upR.note) || '定位失败') + '（正文未动）');
+      else if (upR.status === 'current') console.log('✅ 已是当前层 v' + core.pkgVersion(path.join(__dirname, '..')) + '，无需升级');
+      else if (upR.status === 'error') console.log('⚠ ' + (upR.note || '升级失败'));
+    }
+  } else if (cmd === 'regen') {
+    if (!positional[0] || !positional[1]) { usage(); process.exit(2); }
+    var rg = core.regenDoc(positional[0], positional[1], { go: !!flags.go, force: !!flags.force });
+    if (rg.status === 'wordmode') {
+      console.log('WORD_MODE 人类编辑中（wordLock 旗鲜活）：重生成挂起，等收笔再跑');
+      process.exitCode = 3;
+    } else if (rg.status === 'manual-edits') {
+      console.log('MANUAL_EDITS 盘上有 ' + rg.lost.length + ' 行手改内容是图纸里没有的——直接上盘会盖掉它们：');
+      rg.lost.slice(0, 20).forEach(function (l) { console.log('  · ' + l.slice(0, 90)); });
+      console.log('  把手改同步进图纸、重出 fresh 后再 --go；确要丢弃手改加 --force（此报表已记名）');
+      process.exitCode = 2;
+    } else if (rg.status === 'clean') {
+      console.log('CLEAN 图纸与盘面对齐、无手改残留——加 --go 即可安全上盘');
+    } else if (rg.status === 'swapped') {
+      console.log('✅ 重生成上盘完成：store rev=' + rg.rev + '（' + rg.ann + ' 条批注）逐字节保留 · 备份 ' + rg.bak);
+    } else if (rg.status === 'stale' || rg.status === 'error') {
+      console.log('⚠ ' + (rg.note || rg.status));
+      process.exitCode = 1;
+    }
+  } else if (cmd === 'read') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    core.readPending(positional[0]);
+  } else if (cmd === 'reply') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    var sText, sEnd = false;
+    if (flags.stream !== undefined) { sText = flags.stream; }
+    else if (flags['stream-end'] !== undefined) { sText = flags['stream-end']; sEnd = true; }
+    if (sText !== undefined) {
+      if (flags.stdin || sText === '--stdin') sText = readStdinSync();
+      var sr = core.streamReply(positional[0], { text: sText, id: flags.id, end: sEnd });
+      if (sr.status === 'ok') {
+        console.log((sr.done ? '✅ 回答完成' : sr.started ? '▶️ 流式回答开始' : '➕ 已追加段落') + ' · 批注 ' + sr.annId + ' · rev=' + sr.rev);
+        if (sr.closed && sr.closed.length) console.log('ℹ️ 顺手封轮（未收尾的遗留流式轮，文本保留）: ' + sr.closed.join(', '));
+      } else if (sr.status === 'wordmode') {
+        console.log('WORD_MODE 人类编辑中（wordLock 旗鲜活）：回答挂起不落盘，等收笔再发');
+        process.exitCode = 6;
+      } else if (sr.status === 'interrupted') {
+        console.log('INTERRUPTED 人类已按⏹停止（批注 ' + sr.annId + ' · rev=' + sr.rev + '）——本轮作答终止，不要再追加');
+        if (sr.closed && sr.closed.length) console.log('ℹ️ 顺手封轮（未收尾的遗留流式轮，文本保留）: ' + sr.closed.join(', '));
+        process.exitCode = 4;
+      } else if (sr.status === 'target-gone') {
+        console.log('TARGET_GONE 批注 ' + sr.annId + ' 已被删除——本轮作答终止');
+        process.exitCode = 5;
+      } else if (sr.status === 'empty') {
+        console.log('空段落：--stream 需要文本或 --stdin');
+        process.exitCode = 2;
+      } else {
+        console.log('NO_STREAM 没有打开中的流式回答——首段请带 --id 批注id（退出码 7）');
+        process.exitCode = 7;
+      }
+    } else {
+      if (!positional[1]) { usage(); process.exit(2); }
+      core.applyReplies(positional[0], positional[1]);
+    }
+  } else if (cmd === 'edit') {
+    if (!positional[0] || !positional[1]) { usage(); process.exit(2); }
+    core.applyEdits(positional[0], positional[1]);
+  } else if (cmd === 'answer') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    if (!positional[1]) core.listAnswers(positional[0]);       // 不带 json = 列出既有教学卡（「继续」前先看阶次）
+    else core.applyAnswers(positional[0], positional[1]);
+  } else if (cmd === 'teach') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    core.teachDoc(positional[0], { out: flags.out, title: flags.title }, path.join(__dirname, '..'));
+  } else if (cmd === 'poll') {
+    if (!positional[0]) { usage(); process.exit(2); }
+    core.pollAnnotations(positional[0], { timeout: flags.timeout, interval: flags.interval });
+  } else {
+    usage();
+  }
+} catch (e) {
+  console.error('错误: ' + (e.message || e));
+  process.exit(1);
+}