@chiimagnus/applebookscli 0.1.5 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # AppleBooksCLI
 
-AppleBooksCLI 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
+[AppleBooksCLI](https://github.com/chiimagnus/AppleBooksCLI) 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
 
 ## 主要功能
 
@@ -10,35 +10,36 @@ AppleBooksCLI 是一个用于 macOS Apple Books 的命令行工具。你可以
 - 读取可用 EPUB 的目录、章节、元数据与批注上下文。
 - 提取 PDF 划线与笔记。
 - 导出 JSON、CSV、Markdown 或 HTML。
-- 安全修改笔记、管理藏书，并在写入前自动备份。
-- 安装随 CLI 一起分发的 `applebookscli` Skill，供 Codex/AI 直接使用。
+- **安全修改笔记、管理藏书，并在写入前自动备份。**
+- 提供标准 `applebookscli` Agent Skill。
 
 ## 系统要求
 
-- macOS 12 或更高版本。
-- npm 发布的预编译版本目前支持 Apple Silicon（arm64）。
 - 读取 Apple Books 数据时，macOS 可能要求为终端或调用进程授予 Full Disk Access。
 - 未下载的 EPUB、DRM 内容或当前系统无法读取的内容会明确提示不可用或能力受限；AppleBooksCLI 不绕过系统保护。
 
 ## 安装
 
-安装稳定版：
-
 ```sh
-npm install --global @chiimagnus/applebookscli
-applebookscli --version
-```
+# 安装 CLI
+npm install --global @chiimagnus/applebookscli@latest
 
-如果需要试用 beta：
+# 安装 SKILL.md；首次安装时由 Agent Skills CLI 选择目标 Agent
+CLI_VERSION="$(applebookscli --version)"
+npx -y skills@1.5.23 add "chiimagnus/AppleBooksCLI#v${CLI_VERSION}" --skill applebookscli --global
 
-```sh
-npm install --global @chiimagnus/applebookscli@beta
 ```
 
-更新到最新稳定版：
+之后通过 npm 升级 CLI 时，若该 Skill 仍由 Agent Skills CLI 管理，npm `postinstall` 会把它自动切到相同的 `v<CLI版本>` tag 并调用官方 updater；没有安装 Skill 的用户不会受到影响。使用 `--ignore-scripts` 会显式关闭这条自动联动。此前手工复制的 Skill 没有 source tracking，只需按上面的标准命令重新安装一次即可接入后续自动更新。
+
+## 获取帮助
+
+CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
 
 ```sh
-npm install --global @chiimagnus/applebookscli@latest
+applebookscli --help
+applebookscli <group> --help
+applebookscli <group> <subcommand> --help
 ```
 
 ## 快速开始
@@ -100,7 +101,7 @@ applebookscli pdf list
 applebookscli pdf highlights --help
 ```
 
-AppleBooksCLI 只读取本机当前可访问的内容；不会为了检查内容而主动触发 iCloud 下载，也不会绕过 DRM。
+EPUB 在读取正文前会先检查本地 materialization 状态，不主动触发 iCloud hydration，也不会绕过 DRM。PDF 只处理当前可解析为可读本地文件的 source；对 iCloud placeholder 的 non-hydrating 行为尚未建立等价保证。
 
 ## 导出
 
@@ -112,7 +113,7 @@ applebookscli export --format markdown --output ~/Desktop/apple-books.md
 applebookscli export --format json --output ~/Desktop/apple-books.json
 ```
 
-还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项：
+还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项。有 CFI 的 EPUB 批注在 HTML/Markdown 中会把 `Location` 本身做成 Apple Books deep link；无 CFI 时退化为书籍级链接。JSON/CSV 保留对应 `appleBooksURL`：
 
 ```sh
 applebookscli export --help
@@ -128,40 +129,33 @@ applebookscli collections --help
 applebookscli backups --help
 ```
 
-## 安装 AppleBooksCLI Skill
-
-npm 包中包含配套的 `applebookscli` Skill：
+单条 collection / annotation mutation 可加 `--sync`，在本地 commit + cloud projection 后等待当前 Mac 的 CloudKit acknowledgement：
 
 ```sh
-applebookscli skill install
+applebookscli collections create "My Shelf" --sync --json
 ```
 
-它会安装到 `${CODEX_HOME:-~/.codex}/skills/applebookscli`。如果目标已经存在，CLI 默认不会覆盖；需要明确替换时使用：
+连续多条写入时，优先正常提交各 mutation，最后只 flush 一次：
 
 ```sh
-applebookscli skill install --force
+applebookscli collections create "Shelf A" --json
+applebookscli annotations update-note <annotation-uuid> --note "New note" --json
+applebookscli sync --json
 ```
 
+`sync` 只处理已存在的 pending collection/member/annotation cloud records；无 pending 时不触发生命周期。acknowledgement 只证明**当前 Mac** 已完成 Apple Books CloudKit upload，不等于另一台设备已经显示。post-commit `cloud_sync_failed` 不能触发自动重试；BKLibrary restore 也不等同于可逐条 flush 的 cloud mutation。
+
 ## 可选配置
 
 大多数用户不需要配置文件。只有需要指定额外的 EPUB 目录，或给历史批注补充书名/作者信息时，才需要 `~/.config/applebookscli/config.json`。
 
 示例见 [`Config/applebookscli.example.json`](Config/applebookscli.example.json)。
 
-## 获取帮助
-
-CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
-
-```sh
-applebookscli --help
-applebookscli <group> --help
-applebookscli <group> <subcommand> --help
-```
-
 ## 开发与维护
 
 架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
 
 ## License
 
-AppleBooksCLI 使用 GNU Affero General Public License v3（AGPLv3）。第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。
+AppleBooksCLI 使用 [AGPLv3 LICENSE](LICENSE) 。
+第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。

package/libexec/applebookscli/sync-installed-skill.mjs

@@ -0,0 +1,75 @@
+import { readFile, rename, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+const skillName = "applebookscli";
+const source = "chiimagnus/AppleBooksCLI";
+const sourceURL = "https://github.com/chiimagnus/AppleBooksCLI.git";
+const skillsVersion = "1.5.23";
+
+async function runUpdater() {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      "npx",
+      ["-y", `skills@${skillsVersion}`, "update", skillName, "-g", "-y"],
+      {
+        stdio: "ignore",
+        env: { ...process.env, DISABLE_TELEMETRY: "1" },
+      },
+    );
+    child.once("error", reject);
+    child.once("exit", resolve);
+  });
+}
+
+async function main() {
+  const packageJSON = JSON.parse(
+    await readFile(new URL("../../package.json", import.meta.url), "utf8"),
+  );
+  // ponytail: skills@1.5.23 还没有公开的“只重绑 ref”命令；只改它自己的 source ref，target 更新仍完全交给官方 updater。
+  const lockPath = process.env.XDG_STATE_HOME
+    ? join(process.env.XDG_STATE_HOME, "skills", ".skill-lock.json")
+    : join(homedir(), ".agents", ".skill-lock.json");
+
+  let rawLock;
+  try {
+    rawLock = await readFile(lockPath, "utf8");
+  } catch {
+    return;
+  }
+
+  const lock = JSON.parse(rawLock);
+  const entry = lock.skills?.[skillName];
+  if (
+    !entry ||
+    entry.sourceType !== "github" ||
+    (entry.source !== source && entry.sourceUrl !== sourceURL)
+  ) {
+    return;
+  }
+
+  const targetRef = `v${packageJSON.version}`;
+  if (entry.ref !== targetRef) {
+    const mode = (await stat(lockPath)).mode & 0o777;
+    const temporary = `${lockPath}.${process.pid}.tmp`;
+    entry.ref = targetRef;
+    await writeFile(temporary, `${JSON.stringify(lock, null, 2)}\n`, { mode });
+    await rename(temporary, lockPath);
+  }
+
+  const code = await runUpdater();
+  if (code !== 0) {
+    console.warn(
+      `applebookscli: Skill update to ${targetRef} did not complete; Agent Skills CLI can retry later.`,
+    );
+  }
+}
+
+try {
+  await main();
+} catch (error) {
+  console.warn(
+    `applebookscli: optional Skill update skipped: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chiimagnus/applebookscli",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Native Apple Books CLI for macOS on Apple Silicon.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -17,16 +17,16 @@
   "cpu": [
     "arm64"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
   "bin": {
     "applebookscli": "bin/applebookscli"
   },
+  "scripts": {
+    "postinstall": "node libexec/applebookscli/sync-installed-skill.mjs"
+  },
   "files": [
     "bin/applebookscli",
     "libexec/applebookscli/applebookscli-pdf-worker",
-    "share/applebookscli/skill/applebookscli/SKILL.md",
+    "libexec/applebookscli/sync-installed-skill.mjs",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
     "ThirdPartyLicenses"

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

@@ -1,50 +0,0 @@
----
-name: applebookscli
-description: 通过 `applebookscli` 查询、定位、导出或受保护地修改 Apple Books 图书、阅读状态、EPUB/PDF、批注笔记与藏书，以及执行备份恢复或访问诊断时使用。
----
-
-# AppleBooksCLI
-
-使用已安装的 `applebookscli` 作为 Apple Books 数据操作的唯一入口。用户询问自己的 Apple Books 数据时，实际查询后再回答，不用能力说明代替结果。
-
-## 回答前先查阅
-
-CLI 自身是命令契约。需要确认命令、参数或枚举值时，优先读取当前帮助，不依赖记忆，也不在 Skill 中维护第二份命令手册：
-
-- `applebookscli --help`
-- `applebookscli <group> --help`
-- `applebookscli <group> <subcommand> --help`
-
-使用完成目标所需的最窄命令；普通查询、写入和状态判断需要结构化结果时优先 `--json`。`export` 的 JSON 输出使用 `--format json`，不要把 operational `--json` 套到 export。`doctor` 只用于诊断请求，或实际出现 permission、unavailable、schema readiness 一类问题时。`--library-db`、`--annotations-db`、`--config` 只用于用户明确指定或 fixture/test，不作为故障 fallback。
-
-## 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 状态。