annotatable-html 0.0.0-stage → 1.45.3

package/package.json

@@ -1,6 +1,51 @@
-{
-  "name": "annotatable-html",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "annotatable-html",
+  "version": "1.45.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",
+    "test:hosts": "node tests/codex-duty.test.cjs && node tests/duty-hosts.test.cjs && node tests/cli-reply.test.cjs && node tests/codex-duty-e2e.test.cjs && node tests/codex-desktop.test.cjs && node tests/codex-notify.test.cjs && node tests/opencode-notify.test.cjs && node tests/page-takeover.test.cjs"
+  },
+  "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/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: annotatable-html
+description: 可批注 HTML 工作流（配合 /html4agent）。用户要求生成可批注 HTML、加批注层、读批注、恢复值守或接管指定 localhost 批注页面时使用；普通 HTML 生成请求不适用。
+---
+
+# 可批注 HTML
+
+管理用户指定文档的批注、回复和正文修改。内容教学由独立工作流决定；本工具不按“教我、入门”等关键词切换教学模式，不默认生成教学卡或课程。
+不要向项目或全局 AGENTS.md 写入批注规则、值守状态或悬单清单。
+
+## 选择当前任务
+
+- 从零生成：`annotatable new 名称.html`，把正文写进各 section，不改批注脚本或数据区块。
+- Markdown 转换：`annotatable md 文件.md`，保留原文内容。
+- 已有 HTML 加批注：`annotatable inject 文件.html`。保留原内容、结构和样式，不用 new 重建。
+- 读批注或接管页面：`annotatable read 文件路径或localhost页面地址`。已有文档不重新生成。
+- 需要目录内工具或主题时才运行 `annotatable init`；它不安装工作区指令文件。
+
+## 交付即值守
+
+用户明确要求宿主退出后继续处理时，按 [监听说明](references/hosts.md) 使用 duty。它管理保存服务和监听，同页不再另挂 serve 或 poll。其他情况使用下面的 poll 流程。
+
+1. 起后台服务：`annotatable serve 文档目录 --port 0`。读取它返回的实际地址并打开页面。已有可用服务时复用。
+2. 在当前会话挂后台 poll，保持工具调用及时返回。按当前宿主读取 [监听说明](references/hosts.md)。
+3. 给用户页面地址。serve 模式自动保存，批完无需回聊天框喊“已批”。
+
+## 恢复指定页面
+
+用户给 localhost 地址时，先 `annotatable read 地址`。新版服务会返回对应的本地文档信息；记录输出中的实际文件路径。
+复用该页面的服务，在新会话重新挂 poll。若该页有运行中的 duty，接管前先查状态、停止旧控制器并等待其无头轮次结束。已有待回应批注会立即命中，无需等用户再次保存。
+旧服务缺少定位接口时，按报错更新并重启该服务；服务未运行或文档无访问权限时如实说明。
+只接管用户指定的页面，不扫描全局悬单。
+
+## 值守循环
+
+1. 收到 POLL_HIT 后运行 `annotatable read 文档`，读待回应批注的完整对话。纯高亮不答。
+2. 疑问或求解释直接回复；明确要求改正文时，按 [正文修改说明](references/operations.md) 使用 edit。
+3. 续接通知要求 UTF-8 JSON 文件时，按通知运行 reply 并回读核对；其他情况用流式命令，不按长度改成教学卡或外部交付文档：
+
+   ```sh
+   annotatable reply 文档 --stream '第一段' --id 批注id
+   annotatable reply 文档 --stream '后续段'
+   annotatable reply 文档 --stream-end '完整回答'
+   ```
+
+4. 退出码 4（用户停止）或 5（目标已删）时停下本轮；6（用户编辑中）时等其收笔；7 表示没有打开的流式轮，需要带 --id 开始。
+5. poll 模式答完重新后台挂同一命令。duty 模式按通知续接；Claude 当前进程可能需由 agent 续挂 --listen，重开原会话后由项目钩子自动接回，无需用户操作。不重新注册已停止的控制器。
+
+## 写回边界
+
+批注回复走 reply，正文修改走 edit，生成器重建走 regen。工具维护版本和历史；不手改 store JSON。
+用户明确要导出、归档或调用独立内容工作流时，按其要求处理；本技能不决定教学方法、检查点或学习进度。
+只在需要处理旧 answers-store 数据时读取 [兼容说明](references/compatibility.md)。