@chiimagnus/applebookscli 0.1.3 → 0.1.4

package/README.md

@@ -17,6 +17,16 @@ npm install --global @chiimagnus/applebookscli
 applebookscli --version
 ```
 
+Beta 版本使用独立 npm dist-tag，不会改动稳定版 `latest`：
+
+```sh
+npm install --global @chiimagnus/applebookscli@beta
+```
+
+## Release channels
+
+Git tag 是 release 版本的唯一 owner；源码不保存手工版本号。稳定版 tag 使用 `vMAJOR.MINOR.PATCH`（如 `v1.2.1`），beta 使用 `vMAJOR.MINOR.PATCH-beta` 或后续迭代的 `vMAJOR.MINOR.PATCH-beta.N`。release tag 必须指向当前 `main` HEAD，且该 SHA 的 CI 已成功；Release workflow 不重复跑完整测试，只构建一次正式 package 后发布 npm 与 GitHub Release。稳定版进入 npm `latest` 并成为普通 GitHub Release，beta 进入 npm `beta` 并标记 GitHub prerelease。普通开发构建的 `applebookscli --version` 显示 `dev`；release binary 的版本由对应 tag 注入。
+
 ## 配置
 
 默认配置文件是 `~/.config/applebookscli/config.json`，不存在时按空配置运行。仓库提供 `Config/applebookscli.example.json` 示例；当前配置只用于：

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@chiimagnus/applebookscli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Native Apple Books CLI for macOS on Apple Silicon.",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/chiimagnus/AppleBooksCLI.git"
+    "url": "https://github.com/chiimagnus/AppleBooksCLI.git"
   },
   "homepage": "https://github.com/chiimagnus/AppleBooksCLI",
   "bugs": {
@@ -17,6 +17,9 @@
   "cpu": [
     "arm64"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
     "applebookscli": "bin/applebookscli"
   },

package/share/applebookscli/skill/applebookscli/SKILL.md

@@ -1,27 +1,50 @@
 ---
 name: applebookscli
-description: 在 macOS 上需要使用已安装的 applebookscli 访问本机 Apple Books 数据，或执行其受保护写入与备份恢复时使用。
+description: 通过 `applebookscli` 查询、定位、导出或受保护地修改 Apple Books 图书、阅读状态、EPUB/PDF、批注笔记与藏书，以及执行备份恢复或访问诊断时使用。
 ---
 
 # AppleBooksCLI
 
-使用已安装的 `applebookscli` 作为 Apple Books 数据操作的唯一执行入口。需要精确命令或参数时读取对应 `applebookscli <group> [<subcommand>] --help`；不要在 Skill 中维护第二份命令手册。
+使用已安装的 `applebookscli` 作为 Apple Books 数据操作的唯一入口。用户询问自己的 Apple Books 数据时，实际查询后再回答，不用能力说明代替结果。
 
-## 按任务选择路径
+## 回答前先查阅
 
-- **查询**：书籍、阅读状态、统计、批注和 collection 直接使用对应只读命令。普通查询不要机械先跑 `doctor`；只有用户本来就在诊断，或实际返回 permission / unavailable 时，再用 `doctor --json` 定位环境条件。用户只给标题、名称等展示文本时，先 search/list；只有唯一匹配后才把稳定 identity 传给后续命令，不静默选择多个候选中的第一项。
-- **EPUB / PDF**：先解析 exact book/source，再直接调用完成请求所需的最窄 content/PDF 命令；只有需要解释 EPUB 为什么不可用时才用 `content status --json` 诊断 materialization、DRM/encryption 或 not-downloaded。不可用时按结果报告，不自行绕过或触发额外下载。PDF 没有 exact book/path 时先 `pdf list --json` 解析唯一 source；worker failure 与“没有 highlights”是不同结果。
-- **导出**：先确定用户要求的范围、格式和输出目标，再运行 `export`。用户没有要求覆盖时保持 no-clobber，不因为文件已存在就自行升级 overwrite policy。“完整笔记归档”必须使用 complete-notes 路径；安全或完整性校验失败时停止并报告，不能降级成普通 export 后声称归档完整。
-- **写入**：只有用户明确要求 annotation 或 collection 变更时才执行 mutation。涉及既有对象时先只读解析 exact target，并用 `--json` 执行写命令。以 `committed` / `changed` 判定结果；已 committed 的操作不能因后续 warning 自动重试，`changed=false` 是成功的幂等 no-op。只有 CLI 报 read-back warning，或返回值仍不足以证明用户要求的最终状态时，才补一条最窄只读确认。
-- **Restore**：只在用户明确要求时执行，不作为普通 mutation 的自动 fallback。用户给了 exact backup handle 就直接使用，否则先 `backups list --json` 解析唯一目标，并用 `--json` 执行 restore。以 `changed` / `status` 判定结果；`changed=true` 或 `restored_unverified` 都不能自动再 restore。只有返回状态仍不足以证明用户要求的最终结果时，才补最窄只读检查。
+CLI 自身是命令契约。需要确认命令、参数或枚举值时，优先读取当前帮助，不依赖记忆，也不在 Skill 中维护第二份命令手册：
 
-## 硬规则
+- `applebookscli --help`
+- `applebookscli <group> --help`
+- `applebookscli <group> <subcommand> --help`
 
-- 不直接读写 Apple Books SQLite，也不自行复制 backup/restore、EPUB/CFI、PDF 或 export 逻辑来绕过 CLI；写入/restore 时也不要额外手工 quit/launch Books.app。
-- 优先使用稳定 identity：book asset ID、annotation UUID、collection ID、backup handle；local PK 只在没有稳定 identity 或用户明确指定时使用。
-- 只读取完成请求所需的最小内容；不要为了预检扩大 EPUB/PDF 正文或批注范围。
-- 自定义 DB/config override 只在用户明确指定或任务本来就是 fixture/test 场景时使用，不作为故障 fallback。
-- 只清理当前任务明确创建的临时文件；用户指定的导出产物、CLI 创建的 safety backup、既有 Apple Books 数据与配置默认保留。
-- mutation/restore 的调用结果若因超时、中断等变成未知，先只读确认目标状态，不直接重发副作用；其它失败也只有在出现新证据、输入或环境变化后才重试。
+使用完成目标所需的最窄命令；普通查询、写入和状态判断需要结构化结果时优先 `--json`。`export` 的 JSON 输出使用 `--format json`，不要把 operational `--json` 套到 export。`doctor` 只用于诊断请求，或实际出现 permission、unavailable、schema readiness 一类问题时。`--library-db`、`--annotations-db`、`--config` 只用于用户明确指定或 fixture/test，不作为故障 fallback。
 
-任务结束时返回用户真正要的结果，并明确必要的 empty / unavailable / degraded / warning 状态。不要把“命令执行成功”本身当成完成。
+## Identity
+
+优先使用稳定 identity：book asset ID、annotation UUID、collection ID、backup handle。标题、作者和名称只是搜索条件；先 search/list，唯一匹配后再继续。不要静默选择多个候选中的第一项；local PK 只在没有稳定 identity 或用户明确指定时使用。
+
+阅读状态以 `reading` 的 canonical 结果为准，不从进度百分比推断 finished/in-progress/unstarted。“最近打开”也不等于“当前正在前台阅读”；用户说“当前这本书”时优先复用已经唯一解析的上下文，若只能得到 recent 结果就按 recent 候选表述。
+
+## Annotations
+
+用户问“最新笔记”时，只在 `note` 非空的 annotation 中比较；“最新”默认按创建时间，“最近修改”按修改时间。不要把普通高亮误报成笔记。
+
+展示一条具体 annotation 时，优先返回高亮文本、note、必要时间和 `appleBooksURL`。不要自行拼接 `ibooks://`，也不要为了生成 deep link 调用 `content locate`。只有用户需要高亮前后正文时才使用 `content context`。
+
+`annotations update-note` 的 `--note` 是**整段替换文本**。用户要求追加、补充或加评论时，先读取原 note，保留原文构造完整新 note，再用 exact UUID 和 `--json` 写回。`annotations delete` soft-delete 的是整条 annotation，不要用它代替“清空 note 文本”。
+
+## 写入与恢复
+
+只有用户明确要求修改 annotation、collection 或恢复备份时才执行写操作。CLI 的 guarded mutation rail 已负责安全备份、Books.app 生命周期、事务与 read-back；不要直接读写 Apple Books SQLite，也不要额外手工 quit/launch Books.app。
+
+`committed=true` 表示事务已经提交，不能因为后续 warning 自动重试；`changed=false` 是成功的幂等 no-op。出现 `read_back_failed`，或调用超时/中断导致结果未知时，先做最窄只读确认，再决定是否还需要写入。CLI 创建的 safety backup 默认保留。
+
+`backups list/restore` 只面向 library database；不要假定 annotation mutation 返回的 backup handle 可以交给这个恢复面。Restore 以返回的 `changed`、`status`、`verified` 为准；`restored_unverified` 表示恢复已经应用但验证失败，不能自动再 restore。
+
+## EPUB、PDF 与导出
+
+EPUB 内容不可用时，只有需要解释原因才运行 `content status --json`；不要绕过 DRM/encryption，也不要主动触发下载。PDF 没有 exact book/path 时先用 `pdf list --json` 解析唯一 source；worker failure/timeout 与“成功读取但没有 highlights”是不同结果。
+
+用户要求完整笔记归档时必须使用 `--complete-notes` 的 fail-closed 路径；完整性校验失败就停止并报告，不能降级为普通 export 后声称归档完整。普通导出遵守用户给定的输出与 overwrite 策略，不擅自覆盖已有文件。
+
+## 返回结果
+
+不要把 exit 0 当成用户目标已经完成；以实际返回数据证明结果，并区分 empty、not found、unavailable、degraded 和 warning。本地 mutation 成功也不等于已经同步到 iCloud；没有另一设备或其它端到端证据时，只确认本地 Apple Books 状态。