@chiimagnus/applebookscli 0.2.0 → 0.3.0

package/README.md

@@ -1,40 +1,38 @@
 # AppleBooksCLI
 
-[AppleBooksCLI](https://github.com/chiimagnus/AppleBooksCLI) 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
+English | [简体中文](README.zh.md)
 
-## 主要功能
+[AppleBooksCLI](https://github.com/chiimagnus/AppleBooksCLI) is a command-line tool for Apple Books on macOS. It can query your library, reading state, highlights, and notes; read available EPUB/PDF content; export notes; and safely update existing notes or collections when requested.
 
-- 浏览、搜索 Apple Books 书库与阅读状态。
-- 查询划线、笔记、最近批注，并按书籍或时间定位。
-- 查看单条批注时获得可直接跳回 Apple Books 对应划线位置的链接。
-- 读取可用 EPUB 的目录、章节、元数据与批注上下文。
-- 提取 PDF 划线与笔记。
-- 导出 JSON、CSV、Markdown 或 HTML。
-- **安全修改笔记、管理藏书，并在写入前自动备份。**
-- 提供标准 `applebookscli` Agent Skill。
+## Features
 
-## 系统要求
+- Browse and search the Apple Books library and reading state.
+- Query highlights, notes, and recent annotations, with book- and time-based filtering.
+- Open a single annotation back at its Apple Books location when a deep link is available.
+- Read available EPUB tables of contents, chapters, metadata, and annotation context.
+- Extract PDF highlights and notes.
+- Export JSON, CSV, Markdown, or HTML.
+- **Safely update notes and manage collections, with an automatic backup before writes.**
+- Review the last 24 hours of AppleBooksCLI write/sync tool calls through local operation history.
+- Provide a standard `applebookscli` Agent Skill in English and Chinese.
 
-- 读取 Apple Books 数据时，macOS 可能要求为终端或调用进程授予 Full Disk Access。
-- 未下载的 EPUB、DRM 内容或当前系统无法读取的内容会明确提示不可用或能力受限；AppleBooksCLI 不绕过系统保护。
+## Requirements
 
-## 安装
+- macOS may require Full Disk Access for the terminal or calling process before Apple Books data can be read.
+- Undownloaded EPUBs, DRM-protected content, or content the current system cannot read are reported as unavailable or capability-limited. AppleBooksCLI does not bypass system protections.
+
+## Install
 
 ```sh
-# 安装 CLI
 npm install --global @chiimagnus/applebookscli@latest
-
-# 安装 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
-
+npx -y skills@1.5.23 add "chiimagnus/AppleBooksCLI#v$(applebookscli --version)" --skill applebookscli --global
 ```
 
-之后通过 npm 升级 CLI 时，若该 Skill 仍由 Agent Skills CLI 管理，npm `postinstall` 会把它自动切到相同的 `v<CLI版本>` tag 并调用官方 updater；没有安装 Skill 的用户不会受到影响。使用 `--ignore-scripts` 会显式关闭这条自动联动。此前手工复制的 Skill 没有 source tracking，只需按上面的标准命令重新安装一次即可接入后续自动更新。
+Future npm upgrades keep an Agent Skills CLI-managed Skill on the same CLI release tag automatically. `--ignore-scripts` disables that automatic update.
 
-## 获取帮助
+## Help
 
-CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
+The installed CLI is the source of truth for current commands and arguments:
 
 ```sh
 applebookscli --help
@@ -42,68 +40,68 @@ applebookscli <group> --help
 applebookscli <group> <subcommand> --help
 ```
 
-## 快速开始
+## Quick start
 
 ```sh
-# 浏览书库
+# Browse the library
 applebookscli books list
 
-# 查看正在阅读的书
+# Show books currently in progress
 applebookscli reading in-progress
 
-# 查看最近创建的批注
+# Show recently created annotations
 applebookscli annotations recent
 
-# 查看书库统计
+# Show library statistics
 applebookscli stats
 ```
 
-需要结构化结果时，大多数查询命令支持 `--json`：
+Most query commands support `--json` when structured output is needed:
 
 ```sh
 applebookscli books list --json
 applebookscli annotations recent --json
 ```
 
-## 笔记、划线与定位
+## Notes, highlights, and locations
 
-先找到批注，再用 UUID 查看具体内容：
+Find an annotation first, then inspect it by UUID:
 
 ```sh
 applebookscli annotations recent --json
 applebookscli annotations get <annotation-uuid>
 ```
 
-单条批注结果会包含对应的 `appleBooksURL`，可以直接跳回 Apple Books 中该书或对应划线位置。
+A single-annotation result includes an `appleBooksURL` when available so you can jump back to the book or highlight location in Apple Books.
 
-如果需要查看划线前后的正文：
+To read text around a highlight:
 
 ```sh
 applebookscli content context <annotation-uuid>
 ```
 
-搜索、按书筛选、颜色、时间范围等能力以当前帮助为准：
+Use the current help for search, book filters, colors, and time ranges:
 
 ```sh
 applebookscli annotations --help
 ```
 
-## EPUB 与 PDF
+## EPUB and PDF
 
 ```sh
-# EPUB 内容相关命令
+# EPUB content commands
 applebookscli content --help
 
-# 查看 PDF inventory
+# List PDF inventory
 applebookscli pdf list
 
-# 提取某个 PDF 的 highlights
+# Extract highlights from a PDF
 applebookscli pdf highlights --help
 ```
 
-EPUB 在读取正文前会先检查本地 materialization 状态，不主动触发 iCloud hydration，也不会绕过 DRM。PDF 只处理当前可解析为可读本地文件的 source；对 iCloud placeholder 的 non-hydrating 行为尚未建立等价保证。
+Before reading EPUB text, AppleBooksCLI checks local materialization state without intentionally triggering iCloud hydration and does not bypass DRM. PDF commands only operate on sources that currently resolve to readable local files; equivalent non-hydrating behavior for iCloud placeholders has not been established.
 
-## 导出
+## Export
 
 ```sh
 # Markdown
@@ -113,15 +111,15 @@ applebookscli export --format markdown --output ~/Desktop/apple-books.md
 applebookscli export --format json --output ~/Desktop/apple-books.json
 ```
 
-还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项。有 CFI 的 EPUB 批注在 HTML/Markdown 中会把 `Location` 本身做成 Apple Books deep link；无 CFI 时退化为书籍级链接。JSON/CSV 保留对应 `appleBooksURL`：
+CSV, HTML, grouping by book, highlight/note filtering, Obsidian formatting, covers, and complete-notes archives are also available. EPUB annotations with a CFI make the `Location` text itself an Apple Books deep link in HTML/Markdown; without a CFI, the link falls back to the book level. JSON/CSV preserve the corresponding `appleBooksURL`:
 
 ```sh
 applebookscli export --help
 ```
 
-## 安全写入
+## Safe writes
 
-AppleBooksCLI 可以修改已有笔记和管理藏书。写入前会自动创建备份，并在写入后验证结果；普通查询不会隐式修改 Apple Books 数据。
+AppleBooksCLI can update existing notes and manage collections. It creates a backup before writing and verifies the result afterward. Ordinary queries do not implicitly modify Apple Books data.
 
 ```sh
 applebookscli annotations update-note --help
@@ -129,13 +127,13 @@ applebookscli collections --help
 applebookscli backups --help
 ```
 
-单条 collection / annotation mutation 可加 `--sync`，在本地 commit + cloud projection 后等待当前 Mac 的 CloudKit acknowledgement：
+A single collection or annotation mutation can add `--sync` to wait for current-Mac CloudKit acknowledgement after the local commit and cloud projection:
 
 ```sh
 applebookscli collections create "My Shelf" --sync --json
 ```
 
-连续多条写入时，优先正常提交各 mutation，最后只 flush 一次：
+For several writes, commit the normal mutations first and flush once at the end:
 
 ```sh
 applebookscli collections create "Shelf A" --json
@@ -143,19 +141,30 @@ 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。
+`sync` only processes already pending collection/member/annotation cloud records and does not trigger the lifecycle when none are pending. Acknowledgement proves only that **this Mac** completed the Apple Books CloudKit upload; it does not prove that another device already displays the change. A post-commit `cloud_sync_failed` must not cause an automatic mutation retry, and restoring a BKLibrary snapshot is not equivalent to replaying individually flushable cloud mutations.
+
+## Operation history
+
+AppleBooksCLI keeps a private local history of the last 24 hours of its annotation/collection mutations, backup restores, and explicit `sync` calls. `history list` returns only summaries; `history get` is the explicit full-detail read and may contain the original note/title/details/selectors plus captured stdout/stderr.
+
+```sh
+applebookscli history list --json
+applebookscli history get <history-id> --json
+```
+
+History is stored only for the current user under AppleBooksCLI's Application Support directory. AppleBooksCLI does not send it as telemetry or sync it between devices, and history is evidence of prior tool calls rather than an undo engine.
 
-## 可选配置
+## Optional configuration
 
-大多数用户不需要配置文件。只有需要指定额外的 EPUB 目录，或给历史批注补充书名/作者信息时，才需要 `~/.config/applebookscli/config.json`。
+Most users do not need a configuration file. `~/.config/applebookscli/config.json` is only needed for an additional EPUB directory or to supplement title/author metadata for historical annotations.
 
-示例见 [`Config/applebookscli.example.json`](Config/applebookscli.example.json)。
+See [`Config/applebookscli.example.json`](Config/applebookscli.example.json).
 
-## 开发与维护
+## Development and maintenance
 
-架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
+Start with [`docs/index.md`](docs/index.md) for architecture, CLI contract, write safety, release workflow, and other maintainer documentation.
 
 ## License
 
-AppleBooksCLI 使用 [AGPLv3 LICENSE](LICENSE) 。
-第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。
+AppleBooksCLI is licensed under the [AGPLv3 LICENSE](LICENSE).
+Third-party notices and license texts are in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) and [`ThirdPartyLicenses/`](ThirdPartyLicenses/).

package/README.zh.md

@@ -0,0 +1,170 @@
+# AppleBooksCLI
+
+[English](README.md) | 简体中文
+
+[AppleBooksCLI](https://github.com/chiimagnus/AppleBooksCLI) 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
+
+## 主要功能
+
+- 浏览、搜索 Apple Books 书库与阅读状态。
+- 查询划线、笔记、最近批注，并按书籍或时间定位。
+- 查看单条批注时获得可直接跳回 Apple Books 对应划线位置的链接。
+- 读取可用 EPUB 的目录、章节、元数据与批注上下文。
+- 提取 PDF 划线与笔记。
+- 导出 JSON、CSV、Markdown 或 HTML。
+- **安全修改笔记、管理藏书，并在写入前自动备份。**
+- 通过本地 operation history 查看最近 24 小时的 AppleBooksCLI 写入/同步 tool calls。
+- 提供标准 `applebookscli` Agent Skill，并提供英文/中文两个版本。
+
+## 系统要求
+
+- 读取 Apple Books 数据时，macOS 可能要求为终端或调用进程授予 Full Disk Access。
+- 未下载的 EPUB、DRM 内容或当前系统无法读取的内容会明确提示不可用或能力受限；AppleBooksCLI 不绕过系统保护。
+
+## 安装
+
+```sh
+npm install --global @chiimagnus/applebookscli@latest
+npx -y skills@1.5.23 add "chiimagnus/AppleBooksCLI#v$(applebookscli --version)" --skill applebookscli-zh --global
+```
+
+以后通过 npm 升级 CLI 时，由 Agent Skills CLI 管理的 Skill 会自动跟随到相同的 CLI release tag。使用 `--ignore-scripts` 会关闭这项自动更新。
+
+## 获取帮助
+
+CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
+
+```sh
+applebookscli --help
+applebookscli <group> --help
+applebookscli <group> <subcommand> --help
+```
+
+## 快速开始
+
+```sh
+# 浏览书库
+applebookscli books list
+
+# 查看正在阅读的书
+applebookscli reading in-progress
+
+# 查看最近创建的批注
+applebookscli annotations recent
+
+# 查看书库统计
+applebookscli stats
+```
+
+需要结构化结果时，大多数查询命令支持 `--json`：
+
+```sh
+applebookscli books list --json
+applebookscli annotations recent --json
+```
+
+## 笔记、划线与定位
+
+先找到批注，再用 UUID 查看具体内容：
+
+```sh
+applebookscli annotations recent --json
+applebookscli annotations get <annotation-uuid>
+```
+
+单条批注结果会包含对应的 `appleBooksURL`，可以直接跳回 Apple Books 中该书或对应划线位置。
+
+如果需要查看划线前后的正文：
+
+```sh
+applebookscli content context <annotation-uuid>
+```
+
+搜索、按书筛选、颜色、时间范围等能力以当前帮助为准：
+
+```sh
+applebookscli annotations --help
+```
+
+## EPUB 与 PDF
+
+```sh
+# EPUB 内容相关命令
+applebookscli content --help
+
+# 查看 PDF inventory
+applebookscli pdf list
+
+# 提取某个 PDF 的 highlights
+applebookscli pdf highlights --help
+```
+
+EPUB 在读取正文前会先检查本地 materialization 状态，不主动触发 iCloud hydration，也不会绕过 DRM。PDF 只处理当前可解析为可读本地文件的 source；对 iCloud placeholder 的 non-hydrating 行为尚未建立等价保证。
+
+## 导出
+
+```sh
+# Markdown
+applebookscli export --format markdown --output ~/Desktop/apple-books.md
+
+# JSON
+applebookscli export --format json --output ~/Desktop/apple-books.json
+```
+
+还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项。有 CFI 的 EPUB 批注在 HTML/Markdown 中会把 `Location` 本身做成 Apple Books deep link；无 CFI 时退化为书籍级链接。JSON/CSV 保留对应 `appleBooksURL`：
+
+```sh
+applebookscli export --help
+```
+
+## 安全写入
+
+AppleBooksCLI 可以修改已有笔记和管理藏书。写入前会自动创建备份，并在写入后验证结果；普通查询不会隐式修改 Apple Books 数据。
+
+```sh
+applebookscli annotations update-note --help
+applebookscli collections --help
+applebookscli backups --help
+```
+
+单条 collection / annotation mutation 可加 `--sync`，在本地 commit + cloud projection 后等待当前 Mac 的 CloudKit acknowledgement：
+
+```sh
+applebookscli collections create "My Shelf" --sync --json
+```
+
+连续多条写入时，优先正常提交各 mutation，最后只 flush 一次：
+
+```sh
+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。
+
+## 操作历史
+
+AppleBooksCLI 会在本机私有保存最近 24 小时的批注/藏书 mutation、backup restore 与显式 `sync` 调用。`history list` 只返回摘要；只有显式 `history get` 才返回完整记录，其中可能包含原始 note/title/details/selector 以及捕获的 stdout/stderr。
+
+```sh
+applebookscli history list --json
+applebookscli history get <history-id> --json
+```
+
+History 只存放在当前用户的 AppleBooksCLI Application Support 目录中；AppleBooksCLI 不把它作为 telemetry 上传，也不跨设备同步。它只是既往 tool call 的证据，不是 undo engine。
+
+## 可选配置
+
+大多数用户不需要配置文件。只有需要指定额外的 EPUB 目录，或给历史批注补充书名/作者信息时，才需要 `~/.config/applebookscli/config.json`。
+
+示例见 [`Config/applebookscli.example.json`](Config/applebookscli.example.json)。
+
+## 开发与维护
+
+架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
+
+## License
+
+AppleBooksCLI 使用 [AGPLv3 LICENSE](LICENSE)。
+第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。

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

@@ -3,16 +3,16 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 
-const skillName = "applebookscli";
+const skillNames = ["applebookscli", "applebookscli-zh"];
 const source = "chiimagnus/AppleBooksCLI";
 const sourceURL = "https://github.com/chiimagnus/AppleBooksCLI.git";
 const skillsVersion = "1.5.23";
 
-async function runUpdater() {
+async function runUpdater(names) {
   return new Promise((resolve, reject) => {
     const child = spawn(
       "npx",
-      ["-y", `skills@${skillsVersion}`, "update", skillName, "-g", "-y"],
+      ["-y", `skills@${skillsVersion}`, "update", ...names, "-g", "-y"],
       {
         stdio: "ignore",
         env: { ...process.env, DISABLE_TELEMETRY: "1" },
@@ -40,25 +40,24 @@ async function main() {
   }
 
   const lock = JSON.parse(rawLock);
-  const entry = lock.skills?.[skillName];
-  if (
-    !entry ||
-    entry.sourceType !== "github" ||
-    (entry.source !== source && entry.sourceUrl !== sourceURL)
-  ) {
-    return;
-  }
+  const managed = skillNames.filter((name) => {
+    const entry = lock.skills?.[name];
+    return entry?.sourceType === "github" &&
+      (entry.source === source || entry.sourceUrl === sourceURL);
+  });
+  if (managed.length === 0) return;
 
   const targetRef = `v${packageJSON.version}`;
-  if (entry.ref !== targetRef) {
+  const changed = managed.some((name) => lock.skills[name].ref !== targetRef);
+  if (changed) {
     const mode = (await stat(lockPath)).mode & 0o777;
     const temporary = `${lockPath}.${process.pid}.tmp`;
-    entry.ref = targetRef;
+    for (const name of managed) lock.skills[name].ref = targetRef;
     await writeFile(temporary, `${JSON.stringify(lock, null, 2)}\n`, { mode });
     await rename(temporary, lockPath);
   }
 
-  const code = await runUpdater();
+  const code = await runUpdater(managed);
   if (code !== 0) {
     console.warn(
       `applebookscli: Skill update to ${targetRef} did not complete; Agent Skills CLI can retry later.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chiimagnus/applebookscli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Native Apple Books CLI for macOS on Apple Silicon.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -27,6 +27,7 @@
     "bin/applebookscli",
     "libexec/applebookscli/applebookscli-pdf-worker",
     "libexec/applebookscli/sync-installed-skill.mjs",
+    "README.zh.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
     "ThirdPartyLicenses"