annotatable-html 1.38.3 → 1.45.3

package/templates/commands/html4agent.md

@@ -1,37 +1,6 @@
 ---
-description: HTML4agent：生成可批注 HTML（划线批注+AI流式回答+版本回滚），值守监听批注
+description: HTML4agent：生成可批注 HTML、读批注或接管指定页面
 ---
-参数 $ARGUMENTS：首次使用 = 文档需求（主题与内容要求）；之后 = 可省略（值守中自动接批注），或写批注反馈。
 
-本命令是**值守循环工作流**，按对话阶段执行对应一节（只执行当前阶段，不要越步）：
-
-## 阶段一：生成并开始值守（用户给出文档需求，或本会话尚未生成文档时）
-
-1. 目录无 AGENTS.md → 运行 `npx annotatable-html init`（已存在自动跳过）；
-2. 运行 `npx annotatable-html new <名称>.html`（名称从需求推断，中文即可）；
-3. 把内容写进生成的 html 的各 section；**不要动**批注层脚本与 annotations-store 区块；
-4. 起伴随服务器（后台任务，会话期间保持）：`npx annotatable-html serve <文档所在目录> --port 8980`；
-5. 有浏览器操作能力 → 自己打开 `http://localhost:8980/<文档名>.html`；没有 → 把 URL 给用户；
-6. 挂监听（后台任务）：`npx annotatable-html poll <文档路径>`；
-7. 告知用户：「打开这个地址直接划线批注，我在值守——批完不用喊我，回答会在页面上实时长出来。」
-
-记住文档路径（后续阶段要用）。
-
-## 阶段二：值守应答（POLL_HIT 唤醒，或用户直接给批注反馈时）
-
-1. 运行 `npx annotatable-html read <文档路径>` 列出待回应批注（含对话线）；
-   （无待回应批注：温和告知"还没看到新批注"；继续值守。）
-2. 逐条处理 status:"new" 的批注：通读 thread 全部轮次与原文上下文。批语是祈使句（「这里改成X」）→ 走 edit（见规则）；疑问句 → 流式回答：
-   - `npx annotatable-html reply <文档路径> --stream '<第一段>' --id <批注id>`（开始，必带 --id）；
-   - `npx annotatable-html reply <文档路径> --stream '<后续段>'`（续段）；
-   - `npx annotatable-html reply <文档路径> --stream-end '<完整全文>'`（收尾）；
-   - **退出码 4 = 用户按了⏹，5 = 批注已被删除：两种都立即停手，不要重试、不要续写**；
-   - 长回答（>5 行）若适合分阶教学 → 改用 `npx annotatable-html answer` 写教学卡，reply 只留摘要；
-3. 一轮答完**重新挂 poll**（后台任务）。除非用户喊停，值守持续整个会话。
-
-## 规则
-
-- 批语含「暂存/留着」→ 划线内容进 ANSWER.md 暂存区；含「沉淀(到：文件名)」→ 整理进 docs/Learn/；
-- 每次写回 rev+1 并维护快照（reply/edit 工具已封装；手工改务必遵守）；
-- 起不了 serve 时才让用户双击文件打开（file:// 兜底）：告知用 Edge/Chrome 打开，同文件夹绑过一次后其余文档自动互联；其余流程不变；
-- 目录存在 AGENTS.md 时以其细节为准；用户明确要"普通 html"时才输出不带批注层的文件。
+读取并执行 annotatable-html skill。将 $ARGUMENTS 作为用户的文档需求、文件路径或 localhost 页面地址。
+按当前任务选择生成、读取或恢复值守；已有页面不重建。流程与写回规则统一以 skill 为准。

package/templates/opencode/annotatable-html.js

@@ -0,0 +1,12 @@
+// The official shell.env hook supplies context only; it never starts a model or changes permissions.
+export const AnnotatableHtmlContext = async ({ serverUrl, directory }) => ({
+  'shell.env': async (input, output) => {
+    if (!input.sessionID) {
+      delete output.env.ANNOTATABLE_OPENCODE_SESSION_ID;
+      return;
+    }
+    output.env.ANNOTATABLE_OPENCODE_SESSION_ID = input.sessionID;
+    output.env.ANNOTATABLE_OPENCODE_SERVER_URL = serverUrl.toString();
+    output.env.ANNOTATABLE_OPENCODE_DIRECTORY = directory;
+  }
+});

package/templates/references/compatibility.md

@@ -0,0 +1,14 @@
+# 既有扩展回答数据
+
+旧文档可能含 answers-store。普通批注回复不会创建或更新它；页面保存、旧页升级和回复须保留其内容。
+
+独立内容工具需要维护既有数据时，可显式调用兼容接口：
+
+```sh
+annotatable answer 文档
+annotatable answer 文档 数据.json
+```
+
+数据格式仍为 `[{annId,title,rungs:[{title,body,checkpoint?,answer?}]}]`，用于兼容已有文件。
+本接口只保存数据，不选择教学方式、分阶内容或检查点。用户未要求时不调用。
+旧 teach 命令已停用。课程生成与教学模式由独立工作流实现，批注工具只提供通用的读写与展示。

package/templates/references/hosts.md

@@ -0,0 +1,47 @@
+# 后台监听
+
+在目标会话里启动 poll；命中后读批注、回复，再挂同一命令。不要让前台 shell 长期阻塞。
+
+## Codex
+
+```sh
+annotatable poll 文档或localhost页面地址 --codex
+```
+
+默认读取 CODEX_THREAD_ID；可用 --codex-thread ID 指定会话。桌面会话优先使用继承的 CODEX_APP_TOOLS_PIPE_PATH，通过桌面接口向同一会话发送“批注工具自动通知”。启动后台进程时保留此环境变量；不要改用其他服务恢复该会话。
+无桌面连接时需要 Node.js 22+ 和托管当前会话的 app-server。仅有历史记录、会话未加载时会提前报错。--codex-transport desktop|app-server 可指定入口。--codex-turn ID 可指定当前来源轮次；省略时工具只读查询历史。找不到原生程序时用 --codex-bin 指定其路径。
+收到自动通知或 annotatable_poll 工具输出中的 POLL_HIT 后回到主流程。CODEX_NOTIFY_ERROR 表示预检或通知失败；发送超时先核对会话，不要直接重发。CODEX_READY 只表示预检通过，CODEX_NOTIFIED 只表示接口接受；以空闲唤醒、文档中的完成回复和重挂监听确认结果。
+
+用户要求桌面退出后继续回复时，在目标桌面聊天内显式运行 `annotatable duty 文档或HTTP页面地址 --codex`（Windows、Node.js 22+）。使用输出的 pageUrl；后台程序管理保存服务和监听。收到自动续接通知后只读批注、回复并核对落盘，不再重挂 poll。同页同聊天只保留一个控制器。`duty 文档 --status` 查看状态，`duty 文档 --stop` 请求停止。该模式确认桌面进程退出后才无头接管；模型和权限不匹配时保留待办。它不设置系统自启。
+
+## OpenCode
+
+先运行 `annotatable skill --opencode`，重启 OpenCode 加载会话插件。
+
+```sh
+annotatable poll 文档或localhost页面地址 --opencode
+```
+
+插件传递当前会话、服务地址和目录。手动连接可加 --opencode-url URL 和 --opencode-session ID。服务认证沿用 OPENCODE_SERVER_PASSWORD 与可选的 OPENCODE_SERVER_USERNAME；密码不写入 URL。
+收到带 POLL_HIT 的监听消息后回到主流程。OPENCODE_NOTIFY_ERROR 表示失败；OPENCODE_NOTIFIED 只表示接口接受。
+
+Windows 使用 PowerShell 的 Start-Process -WindowStyle Hidden 启动 Node CLI，并把输出与错误重定向到日志。全局 CLI 路径可用 npm.cmd root -g 查询；脚本路径和文档路径含空格时分别加双引号。Node detached 不能保证 OpenCode 的 bash 工具及时返回。
+其他系统可用 shell 后台执行和输出重定向。
+
+需要原服务退出后继续时，在原会话运行 `annotatable duty 文档或HTTP页面地址 --opencode`。上下文参数与 poll 相同；同一控制器管理保存服务、在线通知及退出后的同编号恢复。后台确认原服务退出后才接班；重新发现唯一原服务后交还。原模型、提供方或权限变化时保留待办。它不新增插件或配置自启。
+
+## Claude Code
+
+普通监听使用 `annotatable poll 文档 --exit-code 1 --exit-code-timeout 0`。
+
+用户要求退出后继续时，用原生 Bash 工具以 `run_in_background=true` 运行 `annotatable duty 文档或HTTP页面地址 --claude`。缺少原会话信息时加 `--claude-session 原会话UUID`；原生程序可用 --claude-bin 指定。不要把命令挂在前台阻塞，也不要为在线通知另外启动 --resume 进程。
+
+首次注册会在该项目的 `.claude/settings.local.json` 安装一组 SessionStart、Stop 原生异步钩子，保留用户现有权限与钩子。首次命令的标准错误输出 CLAUDE_DUTY_READY；命中后输出处理指令，以退出码 1 通知原会话。当前进程尚未载入新钩子时，按通知由 agent 后台续挂 --listen；无需用户操作。原生钩子命中使用退出码 2 唤醒，之后 Stop 钩子自动接回，无需续挂命令。收到 POLL_HIT 就读批注、写 UTF-8 JSON 回复文件、运行 reply，再回读。不要重新注册已停止的控制器。
+
+后台确认原会话进程退出后，用原生 --resume 同一 UUID 无头回复。在原项目重开同一 UUID 即由 SessionStart 钩子自动接回，无需发送启动提示或手动重挂。钩子只查项目内已有会话锁，其他会话、无头子进程和已停止的注册直接退出。最后一个注册停止后移除本工具的项目钩子，保留用户配置。项目策略禁用钩子时如实报告，不修改策略。无需另挂 poll；控制器、保存服务和进程互斥均与 Codex、OpenCode 共用。
+
+## ZCode
+
+使用 `annotatable poll 文档`。当前不提供无头自动续接。
+
+普通超时和纯高亮不需要回答。监听心跳新鲜只代表进程在运行，确认自动回复须读回文档。

package/templates/references/operations.md

@@ -0,0 +1,37 @@
+# 正文与数据操作
+
+## 批量回复
+
+写 replies.json，再执行 `annotatable reply 文档 replies.json`：
+
+```json
+[{"id":"批注id","reply":"回复全文"}]
+```
+
+日常回复使用主流程的流式命令；文本很长时可用 --stdin 从文件传入。
+
+## 按批注修改正文
+
+写 edits.json，再执行 `annotatable edit 文档 edits.json`：
+
+```json
+[{"id":"批注id","newText":"替换后的正文","reply":"修改说明"}]
+```
+
+newText 为空表示删除原句。工具重算锚定并维护版本快照。混合指令与提问可在同一条目的 reply 中回答。
+用户正在编辑正文时，按工具的排队或让路结果处理，不抢写。收到 replay 重做请求时先重读正文，再生成新的改动。
+
+## 生成器重建
+
+纯文字修改使用 edit。确需重建时运行 `annotatable regen 活页 图纸直出` 查看手改清单；把手改同步进图纸后加 --go 写入。
+仅在用户明确要求丢弃手改时使用 --force。用户编辑期间，regen 退出码 3，应等收笔。
+
+## 版本与数据
+
+批注数据在 annotations-store；thread 保留完整对话，纯高亮不进入待回应清单。
+工具负责 rev、history、文档锁、原子写与侧车档案。不要手改这些字段，也不要手动删除 .annotatable 账本。
+默认 read 只输出待回应批注，无需读取整份 HTML 或扩展回答数据。
+
+## file:// 兜底
+
+无法起 serve 时才让用户直接打开文件，并授权浏览器写回。其余读取、回复和监听流程相同。

package/templates/AGENTS.md

@@ -1,107 +0,0 @@
-# 可批注 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 自动采用；人类要求换肤/改版式时，优先改这两个文件而不是改生成的文档。