annotatable-html 0.0.0-stage → 1.38.3

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "annotatable-html",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.38.3",
+  "description": "可批注 HTML：人类在浏览器划线批注，AI agent 读批注并回答（对话追问 + 版本回滚）。一条命令给任意 agent 装上批注工作流。Annotatable HTML docs with an AI-agent reply loop, threads and version history.",
+  "bin": {
+    "annotatable": "bin/cli.js"
+  },
+  "main": "lib/core.js",
+  "files": [
+    "bin",
+    "lib",
+    "agent",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/run.js"
+  },
+  "keywords": [
+    "annotation",
+    "annotator",
+    "highlight",
+    "html",
+    "ai",
+    "agent",
+    "llm",
+    "code-review",
+    "workflow",
+    "批注",
+    "划词",
+    "标注"
+  ],
+  "author": "山居岁月",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "devDependencies": {
+    "gpt-tokenizer": "^4.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alidadei/HTML4agent.git"
+  },
+  "homepage": "https://github.com/Alidadei/HTML4agent#readme",
+  "bugs": {
+    "url": "https://github.com/Alidadei/HTML4agent/issues"
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,107 @@
+# 可批注 HTML 工作流（agent 必读）
+
+本目录内的 `*.html` 是"可批注文档"：人类在浏览器里划线批注，批注数据由页面自动写回 HTML 文件内部。你（agent）负责读取批注并回应。适用于任何具备"读文件 + 改文件（+ 可选运行 node）"能力的编码 agent。
+
+## 0. 启用边界
+
+本工作流**仅**在以下情况启用：用户使用 /html4agent 命令，或**同时**明确提到「可批注」和
+「html/html 文档」（如「把这份 html 做成可批注版」）。单独的「读批注」「已批」是会话内循环指令，
+不构成触发条件；普通 HTML 生成请求输出普通文件，不要自动套用本工作流。
+（需要生成可批注文档时：目录未初始化先 npx annotatable-html init；再 npx annotatable-html new <名称>.html；
+内容写进各 section，不动批注层与 store 区块。）
+已有成品 HTML（有既定版式/其他工具产出）要可批注：只准 `npx annotatable-html inject <文件.html>`
+最小贴层——内容/结构/样式一字不动，不加目录等任何排版元素；禁止用 new 重建。
+图纸/生成器维护的页面要重建：只准 `npx annotatable-html regen 活页 图纸直出`（先报表、把手改同步进图纸再 --go），
+禁止任何形式直接覆盖活页；人类编辑模式中（wordLock 鲜活）回复/重建一律让路（退出码 6/3），等收笔。
+# 1. 批注数据在哪（唯一需要读取的位置）
+HTML 内哨兵注释之间的 JSON 区块：
+
+    <!-- ═══ AI批注数据 BEGIN ... ═══ -->
+    <script id="annotations-store" type="application/json">{...}</script>
+    <!-- ═══ AI批注数据 END ═══ -->
+
+结构：{ rev, annotations: [...], history: [...] }
+每条批注：{ id, quote原句, prefix/suffix上下文, ordinal出现序号, section小节, thread:[{role:'user'|'ai',text,time}]完整对话线, status:'new'|'answered', reply(最新AI轮镜像) }
+
+另有 `answers-store` 区块（v1.18.0 教学卡，见 §5）：长答/教学全文存这里，与批注区块分离——读批注不必吞教学全文，写教学时才碰它。
+
+**v1.10.0 起 history 拆两层**：文件内 history 只是骨架（{rev,time,op,n,bodyOps?}，近期约 60 条，不含快照）；全量账本（含批注层快照 snap）在 HTML 同目录 `.annotatable/<文件名>.hist.json`，由 annot_reply/annot_edit 工具自动维护（含 DOC_ID 归属校验，复制文件不会互染）。**日常读批注/回应仍然只看 HTML 内区块即可**，不需要读外置档案。
+`bodyOps`（正文编辑纸条）：edit 条目上的 `[{o原文,n新文,b前文30字符,a后文30字符}]`，均为原始串——回滚时页面靠它把正文精确逆放回去。
+
+## 2. 人类说「读批注」时你要做什么
+1. **只读上面那个区块**（不要读整份 HTML，省 token）；
+2. 只处理 status:"new" 的批注；通读该条的 thread 全部对话轮次再回答；
+3. 只答批注所问，引用少量上下文，不扩写成章节总览；
+4. 长回答（>5 行）**默认写入页内教学卡**（§5：annotatable answer，回答大页直接渲染全文），reply 只放 1~3 行摘要+卡片标题；用户点名「归档成 md」或内容需跨文档沉淀时，才写本目录 `answers/{项目名}_ANSWER__{主题}__{agent}.md`（结构：暂存区+本轮回答区；同主题复用不新建），回复放摘要+该 md 相对路径；
+5. 批语含「暂存」或「留着」→ 划线内容整理进该 ANSWER.md 暂存区；含「沉淀」或「沉淀到：文件名」→ 整理进 docs/Learn/（或指定文件）。
+
+## 3. 写回方式
+**首选（推荐）**：用本目录 `agent/` 下的零依赖 node 工具：
+
+    node agent/annot_read.js  <html路径>                 # 列出待回应批注（含对话线；仅划线不列——静默勿答）
+    # 生成 replies.json：[{"id":"批注id","reply":"回答"}]（空串回复会被拒绝，退码2——每条最后AI轮必须非空）
+    node agent/annot_reply.js <html路径> <replies.json>   # 追加ai轮次+快照+rev+1
+    # 流式回答（v1.21.0 值守协议）：每段一调，页面实时渲染打字中的回答
+    node agent/annot_reply.js <html路径> --stream '增量段落' --id 批注id    # 开始（必带 --id）
+    node agent/annot_reply.js <html路径> --stream '后续段落'               # 续段（自动接最近流式轮）
+    node agent/annot_reply.js <html路径> --stream-end '完整全文' [--id 批注id]   # 收尾：全文替换+快照
+    #   收尾必须带全文；空串收尾=拒绝（退码2）；已有流式内容时空收尾=保留已发内容收尾（有 ⚠️ 提示）
+    #   退出码：0=成功 2=空段落/空收尾被拒 4=人类按⏹打断（立即停止作答） 5=批注已删除/无流式轮（同样停止）
+    #   长文本经管道进更稳：node agent/annot_reply.js <html路径> --stream --stdin --id 批注id < 段落.txt
+    # 生成 edits.json：[{"id":"批注id","newText":"改后正文","reply":"可选说明"}]
+    node agent/annot_edit.js <html路径> <edits.json>      # 改正文+重算锚定+快照+rev+1
+    #   人类正在 Word 模式编辑正文时（输出「已排队」）：改动进待办槽不落笔，人类收笔自动铺上；
+    #   铺不上会以 POLL_HIT 的 replay 字段立即唤醒你——看到 replay 请重读正文、重新生成改动再 edit 提交
+    # 长答/教学卡（见 §5）：answers.json = [{"annId":"批注id","title":"..","rungs":[{title,body,checkpoint?,answer?}]}]
+    node agent/annot_answer.js <html路径> <answers.json>  # 写入 answers-store+快照+rev+1；不带 json 参数=列出既有卡
+    # （可选）答完一轮后挂起等新批注，配 harness 后台任务：
+    node agent/annot_poll.js  <html路径> [--timeout 秒]   # 无新批注时阻塞；人类批注保存后
+    #   打印 POLL_HIT <json> 并以 0 退出唤醒 agent；超时以 3 退出。等价 CLI：annotatable poll
+
+**无 node 时的手工等价操作**：在 annotations-store 区块内，对每条 status:"new" 的批注——thread 追加 {"role":"ai","text":回答,"time":时间戳毫秒}，reply 字段写同样内容，status 改 "answered"；**rev 加 1**；history 追加一条 {rev,time,op:"AI回应",n:批注数,snap:整个annotations数组}。⚠️ 手工改 JSON 后务必确认 <script> 开/闭标签仍配对。手写的 snap 会留在文件内，下次任一工具写盘时自动搬入外置档案并瘦身。
+
+## 3.5 值守与流式回答（v1.21.0）
+
+默认工作方式是**值守**，不是等人类回聊天框说「已批」：
+
+1. 交付文档后立刻挂起监听：`node agent/annot_poll.js <html路径>`（后台任务）。人类批注/追问保存后进程打印 `POLL_HIT <json>`、以 0 退出——harness 唤醒你，进入「读批注→回答」；**仅划线（没打字的批注）不响铃——那是人类划重点，保持静默，别去回答**；POLL_HIT 带 `created`（每条批注出生时间），可自判「这条刚出生可能还在打字」；
+2. 回答走流式（§3 的 --stream 三步）：每想好一段就追加一次，页面 1.5s 内自动热载（人类不用刷新、不用切回聊天框）；
+3. 人类随时会：划新批注、删批注、页内追问、按 ⏹、进 Word 模式改正文。前三种 = POLL_HIT 唤醒；POLL_HIT 带 `replay` 字段 = 你此前的排队正文改动被人类大改锚不上，**立即重读正文、重新生成该改动、重新 edit 提交**；⏹ 不唤醒，但你的下一次 --stream 会以退出码 4 失败——**看到 4 或 5 都立即停手**，不要重试；
+4. 一轮答完重新挂 poll。除非人类喊停，值守持续整个会话；
+5. 收尾前批注被删：--stream-end 对已删批注返回 target-gone（退出码 5），不要补写。
+
+页面侧（人类视角）：划线→自动保存→AI 流式回答原地长出来；⏹ 按钮在打字中的回答旁，点了就停。
+
+## 4. 指令型批注：人类要求改正文时（edit）
+批语是**祈使句**（「这里改成X」「删掉这句」「加上：X」）→ 执行正文修改而不是只回答：
+1. 生成 edits.json：`[{"id":"批注id","newText":"改后的正文","reply":"可选，默认自动生成「已按批注修改正文」说明"}]`；
+2. 运行 `annotatable edit`（或 agent/annot_edit.js）。工具自动完成：定位原句 → 替换正文 → **记 bodyOps 纸条（原文/新文/前后文，供回滚逆放）** → **重算该批注的锚定**（quote/prefix/suffix/ordinal 指向新文本，浏览器刷新后高亮落在新句上）→ 追加 ai 轮次 → 快照 + rev+1；
+3. 注意事项：
+   - newText 为空字符串 = 删除原句（批注保留在面板，正文高亮消失）；
+   - 原句若跨格式标签（如加粗片段），替换后变为纯文本，reply 里会注明；
+   - **混合批注**（既下指令又提问）→ 用 edit 的 reply 字段写完整回答，一次搞定；
+   - 不要手工改正文——手改不会重算锚定，会让批注失锚。改不了/定位失败时工具会报错并列出原因，此时如实在 reply 里向人类说明。
+
+## 5. 教学模式：长答/教学卡/教学文档（v1.18.0）
+人类批语在**问机制、要入门、要系统学习**（「展开讲讲」「教我」「入门」「系统性讲」「分阶讲」）时，回答不必挤在对话线里：
+
+**页内教学卡（默认）**——生成 `answers.json` 并运行 `annotatable answer`（或 agent/annot_answer.js）：
+`[{"annId":"批注id","title":"卡片标题","rungs":[{"title":"阶标题","body":"阶正文","checkpoint":"检查点问题","answer":"参考答案(可选)"}]}]`
+- 多阶或带 checkpoint 的卡在页面「回答大页」渲染为**分阶教学卡**：人类逐阶阅读、自评检查点后解锁下一阶（进度在页内，不进文件）；单阶无 checkpoint 的卡渲染为整卡长答；
+- reply 照常写 1~3 行摘要（内容如「已生成 🎓 教学卡《上下文窗口》共 3 阶，在对话详情里查看」），让人类知道去页内看；
+- **「继续/下一阶」**：先 `annotatable answer <文件>`（不带 json）列既有卡，再带**全量 rungs（旧阶+新阶）**重发同一 `annId+title` 的条目——工具按 annId+title 命中整卡替换；
+- 教学卡全文存文件内 answers-store 区块，浏览器保存原样保留它，写入口只有本工具（同样 rev+1 入账本）；老文件没有该区块时工具自动补建。
+
+**专门教学文档（长教学任务）**——教学内容超过一张卡（整门课级、多主题体系）时：
+1. 运行 `annotatable teach <源文档.html> [-o 输出.html] [--title 标题]`：从源文档批注汇总生成教学文档**脚手架**（每主题一节：原句引用+批语+教学正文占位+检查点占位）；
+2. 用 `annotatable edit` 逐节替换占位段落写入教学正文（每节入版本账本可回滚）；
+3. 教学文档与源文档批注循环相互独立（都在这里划线 = 对教学本身提问）；告知人类两个文件的关系。
+
+## 6. 铁律
+- 任何修改必须 **rev+1** 并追加 history 快照（页面靠 rev 检测外部修改，防止互相覆盖）；
+- 除批注区块外**不要动 HTML 其他部分**；人类批语要求修改正文时，**必须走 edit 命令**（自动重算锚定+记 bodyOps），禁止手工改正文——手改不但失锚定，还会让版本账本对不上正文，回滚时会被拒；
+- 人类可能用页面右下角「✏️ 编辑」直接改正文（v1.12.0 Word 模式）：同样走版本账本（op 含「正文编辑」+ bodyOps 纸条），agent 无需特殊处理，但改正文前先 read 最新文件再下指令；
+- history 是版本账本（人类可在页面里回滚到任意版本，含正文），不要删改其结构；`.annotatable/` 是它的外置档案目录，同样不要手工删改；
+- answers-store 区块（教学卡）只能经 `annotatable answer` 工具写入（它自己维护 rev 与批注账本的联动），不要手工改 JSON——手工改会让页面渲染与账本脱钩；
+- 批注锚定信息（quote/prefix/suffix/ordinal）指向正文位置，edit 工具会同步维护；若用其他方式动过正文，先检查未回应批注是否失锚。
+- 外观定制：目录内 annotatable.theme.css（CSS 变量+覆盖样式，new 时自动注入）与 annotatable.template.html（自定义模板）可被 annotatable new 自动采用；人类要求换肤/改版式时，优先改这两个文件而不是改生成的文档。

package/templates/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: annotatable-html
+description: 可批注 HTML 工作流（配合 /html4agent）。仅当用户提到「可批注」「划线批注」「读批注」「已批」或要求批注相关操作时使用；普通 HTML 生成请求不适用。
+---
+
+# 可批注 HTML 工作流
+
+人类在浏览器里对 HTML 划线批注，你（agent）值守监听批注、流式回答并写回文件。
+
+## 生成可批注文档（仅限从零写新文档）
+
+用户明确要求可批注文档、且没有现成 HTML 时（通常经 /html4agent 触发）：
+
+    npx annotatable-html init        # 目录未初始化时先执行（已存在自动跳过）
+    npx annotatable-html new 名称.html
+
+把内容写进生成文件的各 section；**不要改动**批注层脚本与 annotations-store 区块。
+已有 HTML 成品（有既定版式的页面，尤其 PPT 复刻页）**不走本节**——用下方 inject，禁止 new 重建。
+
+## 交付即值守（默认交付方式）
+
+文档写完后，不要让用户「打开文件→绑定→批完说已批」。直接做三件事：
+
+1. 起伴随服务器（后台任务，会话期间保持运行）：
+   `npx annotatable-html serve 文档所在目录 --port 8980`
+2. 有浏览器操作能力就自己打开 `http://localhost:8980/文档名.html`；没有就把 URL 给用户。服务器模式下批注**零绑定、零授权**、自动保存；
+3. 挂监听（后台任务）：`npx annotatable-html poll 文档.html`。有新批注、新追问时进程打印 `POLL_HIT <json>` 并以退出码 0 结束，harness 会唤醒你。
+
+告知用户：「打开这个地址直接划线批注，我在值守，批完不用喊我。」
+
+## 值守循环（POLL_HIT 唤醒后）
+
+1. `npx annotatable-html read 文档.html` 列出待回应批注（含完整对话线）。只处理 status:"new" 的条目；通读每条 thread 全部轮次再回答；只答所问、引用少量上下文、不扩写。
+2. 批语是**疑问句/求讲解** → 流式回答（见下节）。批语是**祈使句**（「这里改成X」「删掉这句」）→ 走下方 edit 流程，不流式。
+3. 一轮答完，**重新挂 poll**（后台任务），继续值守。除非用户喊停，值守持续整个会话。
+
+## 流式回答（一边批注一边出答案）
+
+回答不攒整段。每想好一段就追加一次，人类在页面上实时看到打字中的回答：
+
+    npx annotatable-html reply 文档.html --stream '第一段…' --id 批注id     # 开始（必带 --id）
+    npx annotatable-html reply 文档.html --stream '第二段…'                # 续段（自动接最近的流式轮）
+    npx annotatable-html reply 文档.html --stream-end '完整全文'           # 收尾（全文替换，落快照）
+
+退出码即指令：
+
+- **4 = 人类按了页面上的 ⏹ 停止**：本轮作答就地终止。不要重试、不要续写。人类可能在准备追问。
+- **5 = 目标批注已被删除（或没有进行中的流式轮）**：同样终止本轮。
+
+人类随时可以：划新的线、删旧批注、页内追问——下一次轮询都会唤醒你。若被 ⏹ 打断后收到新批注，按新批注重新作答。
+
+## Markdown 一键转可批注
+
+用户给 .md 文件（或说「把 Markdown 做成可批注版」）时：
+
+    npx annotatable-html md 文件.md        # 生成同名 .html；-o 改输出路径，--title 改标题
+
+正文完全遵照原文（GFM 表格/代码围栏/任务列表/删除线照常），只叠加批注层；转换后按「交付即值守」走。LaTeX 公式（`$...$` 行内、`$$...$$` 独立式）在生成时编译为 MathML 烤进页面，浏览器原生渲染、产物零依赖；编译失败的单条保留 LaTeX 原文，代码块内的 `$` 一律不转。
+
+## 给已有 HTML 加批注层
+
+用户对任何 HTML（其他工具产出亦可）说「加批注层 / 做成可批注版 / 变成可批注的」时：
+
+    npx annotatable-html inject 文件.html
+
+自动备份原文件到同目录 .annotatable/（*.pre-inject.bak）；已含批注层的文件会拒绝重复注入。
+**最小注入铁律**：原文件的内容、结构、样式一字不动，不加目录/导航/任何排版元素——批注层只贴上去。
+
+## 长答/教学卡
+
+批语含「教我/入门/展开讲/系统性讲」→ 不走流式，默认写页内教学卡：
+`npx annotatable-html answer 文档.html answers.json`（json=[{annId,title,rungs:[{title,body,checkpoint?,answer?}]}]，不带 json 参数=列既有卡；「继续」时全量带上旧阶重发即整卡更新），reply 只留摘要。教学任务超过一张卡时 `npx annotatable-html teach 源文档.html` 生成教学文档脚手架（每节预置任务批注），用 edit 逐节填充。用户点名「归档成 md」或「暂存/沉淀」时才按 ANSWER 工作流写 answers/*.md。
+
+## 批语是修改指令时：改正文
+
+批语为祈使句（「这里改成X」「删掉这句」）→ 生成 edits.json：[{"id":"批注id","newText":"改后正文","reply":"可选"}]，然后：
+
+    npx annotatable-html edit 文档.html edits.json
+
+（自动定位替换正文 + 重算该批注锚定 + 快照 + rev+1；混合批注用 reply 字段一并回答。禁止手工改正文。）
+
+## 图纸/生成器维护的页面：重建只走 regen
+
+页面由生成器脚本（图纸）产出、又被人手/编辑模式改过时：**纯文字改动直接 edit 或小改，禁止整页重生成**。必须重生成（改图/大改版）时只准：
+
+    npx annotatable-html regen 活页.html 图纸直出.html          # 报表：列出盘上手改清单，不动盘
+    npx annotatable-html regen 活页.html 图纸直出.html --go    # 上盘：store/DOC_ID 原样保留
+
+报表列出的手改必须先同步进图纸、重出 fresh 再 --go；确要丢弃手改才 --force（留痕）。人类编辑模式中（wordLock 旗鲜活）regen 退出码 3、reply/answer 退出码 6——一律让路等收笔，绝不抢写。
+
+## 无法起 serve 时（file:// 兜底）
+
+起不了服务器（如纯终端环境）才让用户双击文件用 Edge/Chrome 打开。此时批注写回靠浏览器文件授权：同文件夹绑过一次后，其余文档自动互联（新文件打开时点页面任意位置授权即可）。其余流程（poll/流式回答）不变。
+
+## 铁律
+
+- 每次写回必须 rev+1 并维护 history 快照（工具已封装；手工改则务必遵守），否则浏览器端会检测到冲突拒绝覆盖；
+- 流式回答被打断（退出码 4/5）后立即停手；收尾（--stream-end）前若批注被删，不要补写；
+- 目录已初始化时以目录内 AGENTS.md 为准（本文件是其触发壳）。