@chiimagnus/applebookscli 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +134 -37
  2. package/bin/applebookscli +0 -0
  3. package/libexec/applebookscli/applebookscli-pdf-worker +0 -0
  4. package/package.json +1 -1
  5. package/share/applebookscli/skill/applebookscli/SKILL.md +15 -29
package/README.md CHANGED
@@ -1,86 +1,183 @@
1
1
  # AppleBooksCLI
2
2
 
3
- AppleBooksCLI 是一个面向 macOS Apple Books 本地数据的 Swift CLI。它提供稳定的只读查询、EPUB/PDF 内容读取、导出、受保护的 collection/annotation 写入、SQLite backup/restore，以及随安装包分发的 `applebookscli` Skill。
3
+ AppleBooksCLI 是一个用于 macOS Apple Books 的命令行工具。你可以直接查询自己的书库、阅读状态、划线与笔记，读取可用的 EPUB/PDF 内容，导出笔记，并在需要时安全地修改笔记或藏书。
4
4
 
5
- ## 平台与运行边界
5
+ ## 主要功能
6
+
7
+ - 浏览、搜索 Apple Books 书库与阅读状态。
8
+ - 查询划线、笔记、最近批注，并按书籍或时间定位。
9
+ - 查看单条批注时获得可直接跳回 Apple Books 对应划线位置的链接。
10
+ - 读取可用 EPUB 的目录、章节、元数据与批注上下文。
11
+ - 提取 PDF 划线与笔记。
12
+ - 导出 JSON、CSV、Markdown 或 HTML。
13
+ - 安全修改笔记、管理藏书，并在写入前自动备份。
14
+ - 安装随 CLI 一起分发的 `applebookscli` Skill，供 Codex/AI 直接使用。
15
+
16
+ ## 系统要求
6
17
 
7
18
  - macOS 12 或更高版本。
8
- - Swift 6 / SwiftPM 项目；预编译 release 只发布 macOS Apple Silicon（arm64），不提供 Intel/x86_64 binary。
9
- - Apple Books 数据库读取默认使用 read-only SQLite 连接。
10
- - 部分 Apple Books 数据访问可能需要为终端或调用进程授予 Full Disk Access。
11
- - EPUB 未下载、DRM、schema 不兼容或 PDF 解析失败时会返回结构化 unavailable/degraded 结果，不绕过系统保护。
19
+ - npm 发布的预编译版本目前支持 Apple Silicon（arm64）。
20
+ - 读取 Apple Books 数据时，macOS 可能要求为终端或调用进程授予 Full Disk Access。
21
+ - 未下载的 EPUB、DRM 内容或当前系统无法读取的内容会明确提示不可用或能力受限；AppleBooksCLI 不绕过系统保护。
12
22
 
13
23
  ## 安装
14
24
 
25
+ 安装稳定版：
26
+
15
27
  ```sh
16
28
  npm install --global @chiimagnus/applebookscli
17
29
  applebookscli --version
18
30
  ```
19
31
 
20
- Beta 版本使用独立 npm dist-tag，不会改动稳定版 `latest`：
32
+ 如果需要试用 beta：
21
33
 
22
34
  ```sh
23
35
  npm install --global @chiimagnus/applebookscli@beta
24
36
  ```
25
37
 
26
- ## Release channels
38
+ 更新到最新稳定版：
39
+
40
+ ```sh
41
+ npm install --global @chiimagnus/applebookscli@latest
42
+ ```
43
+
44
+ ## 快速开始
45
+
46
+ ```sh
47
+ # 浏览书库
48
+ applebookscli books list
49
+
50
+ # 查看正在阅读的书
51
+ applebookscli reading in-progress
52
+
53
+ # 查看最近创建的批注
54
+ applebookscli annotations recent
55
+
56
+ # 查看书库统计
57
+ applebookscli stats
58
+ ```
59
+
60
+ 需要结构化结果时，大多数查询命令支持 `--json`：
61
+
62
+ ```sh
63
+ applebookscli books list --json
64
+ applebookscli annotations recent --json
65
+ ```
66
+
67
+ ## 笔记、划线与定位
68
+
69
+ 先找到批注，再用 UUID 查看具体内容：
70
+
71
+ ```sh
72
+ applebookscli annotations recent --json
73
+ applebookscli annotations get <annotation-uuid>
74
+ ```
75
+
76
+ 单条批注结果会包含对应的 `appleBooksURL`，可以直接跳回 Apple Books 中该书或对应划线位置。
77
+
78
+ 如果需要查看划线前后的正文：
79
+
80
+ ```sh
81
+ applebookscli content context <annotation-uuid>
82
+ ```
83
+
84
+ 搜索、按书筛选、颜色、时间范围等能力以当前帮助为准：
27
85
 
28
- 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 注入。
86
+ ```sh
87
+ applebookscli annotations --help
88
+ ```
29
89
 
30
- ## 配置
90
+ ## EPUB 与 PDF
31
91
 
32
- 默认配置文件是 `~/.config/applebookscli/config.json`，不存在时按空配置运行。仓库提供 `Config/applebookscli.example.json` 示例；当前配置只用于：
92
+ ```sh
93
+ # EPUB 内容相关命令
94
+ applebookscli content --help
33
95
 
34
- - `epub_root`：为 current Book 提供 exact-basename packed EPUB supplemental root；
35
- - `historical_assets`：按 exact asset ID 补充 historical annotation 的 title/author metadata。
96
+ # 查看 PDF inventory
97
+ applebookscli pdf list
36
98
 
37
- 也可以用全局 `--config <path>` 指定其它配置文件；`--library-db` / `--annotations-db` 用于显式 DB override、fixture 与诊断。配置不会把 historical metadata 升级成 current Book/content identity。
99
+ # 提取某个 PDF 的 highlights
100
+ applebookscli pdf highlights --help
101
+ ```
38
102
 
39
- ## 命令概览
103
+ EPUB 在读取正文前会先检查本地 materialization 状态，不主动触发 iCloud hydration，也不会绕过 DRM。PDF 只处理当前可解析为可读本地文件的 source；对 iCloud placeholder 的 non-hydrating 行为尚未建立等价保证。
104
+
105
+ ## 导出
106
+
107
+ ```sh
108
+ # Markdown
109
+ applebookscli export --format markdown --output ~/Desktop/apple-books.md
40
110
 
41
- | 命令 | 用途 |
42
- | --- | --- |
43
- | `doctor` | 检查数据库、配置、内容与已安装 PDF worker 的可用性 |
44
- | `books` | 列出、读取、搜索书籍与 annotated-only 视图 |
45
- | `reading` / `stats` | 阅读状态、最近阅读、当前位置与统计 |
46
- | `content` | EPUB status、metadata、ToC、chapter、CFI/context |
47
- | `annotations` | 批注读取、搜索、时间范围，以及显式 note update / soft-delete |
48
- | `collections` | collection 读取、创建、重命名、membership 与 soft-delete |
49
- | `pdf` | PDF inventory 与 highlight extraction |
50
- | `export` | JSON、CSV、Markdown、HTML 与 complete-note archive |
51
- | `backups` | 列出安全 backup handle，并按 handle restore |
52
- | `skill install` | 安装随 CLI 分发的 `applebookscli` Skill |
111
+ # JSON
112
+ applebookscli export --format json --output ~/Desktop/apple-books.json
113
+ ```
53
114
 
54
- 具体参数以对应命令的 `--help` 为准，例如：
115
+ 还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项。有 CFI 的 EPUB 批注在 HTML/Markdown 中会把 `Location` 本身做成 Apple Books deep link；无 CFI 时退化为书籍级链接。JSON/CSV 保留对应 `appleBooksURL`：
55
116
 
56
117
  ```sh
57
- applebookscli books --help
58
118
  applebookscli export --help
119
+ ```
120
+
121
+ ## 安全写入
122
+
123
+ AppleBooksCLI 可以修改已有笔记和管理藏书。写入前会自动创建备份，并在写入后验证结果；普通查询不会隐式修改 Apple Books 数据。
124
+
125
+ ```sh
126
+ applebookscli annotations update-note --help
59
127
  applebookscli collections --help
128
+ applebookscli backups --help
129
+ ```
130
+
131
+ 单条 collection / annotation mutation 可加 `--sync`，在本地 commit + cloud projection 后等待当前 Mac 的 CloudKit acknowledgement：
132
+
133
+ ```sh
134
+ applebookscli collections create "My Shelf" --sync --json
135
+ ```
136
+
137
+ 连续多条写入时，优先正常提交各 mutation，最后只 flush 一次：
138
+
139
+ ```sh
140
+ applebookscli collections create "Shelf A" --json
141
+ applebookscli annotations update-note <annotation-uuid> --note "New note" --json
142
+ applebookscli sync --json
60
143
  ```
61
144
 
62
- Operational command 的 `--json` 输出保持单一机器可解析值；human diagnostics 不混入 machine stdout。完整 process-level contract 见 `docs/cli-contract.md`。
145
+ `sync` 只处理已存在的 pending collection/member/annotation cloud records；无 pending 时不触发生命周期。acknowledgement 只证明**当前 Mac** 已完成 Apple Books CloudKit upload，不等于另一台设备已经显示。post-commit `cloud_sync_failed` 不能触发自动重试；BKLibrary restore 也不等同于可逐条 flush 的 cloud mutation。
63
146
 
64
- ## Skill
147
+ ## 安装 AppleBooksCLI Skill
65
148
 
66
- 安装包包含唯一的 `applebookscli` Skill 资源；Skill 只描述如何调用 CLI，不包含第二套 Apple Books 数据实现。
149
+ npm 包中包含配套的 `applebookscli` Skill：
67
150
 
68
151
  ```sh
69
152
  applebookscli skill install
70
153
  ```
71
154
 
72
- 默认目标为 `${CODEX_HOME:-~/.codex}/skills/applebookscli`。已有目标不会被默认覆盖；只有用户显式要求时才使用：
155
+ 它会安装到 `${CODEX_HOME:-~/.codex}/skills/applebookscli`。如果目标已经存在，CLI 默认不会覆盖；需要明确替换时使用：
73
156
 
74
157
  ```sh
75
158
  applebookscli skill install --force
76
159
  ```
77
160
 
78
- `--force` 使用 staging + rename + rollback，并拒绝跟随已有 target symlink；它不会递归删除未知目标目录。
161
+ ## 可选配置
162
+
163
+ 大多数用户不需要配置文件。只有需要指定额外的 EPUB 目录，或给历史批注补充书名/作者信息时，才需要 `~/.config/applebookscli/config.json`。
164
+
165
+ 示例见 [`Config/applebookscli.example.json`](Config/applebookscli.example.json)。
166
+
167
+ ## 获取帮助
168
+
169
+ CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
170
+
171
+ ```sh
172
+ applebookscli --help
173
+ applebookscli <group> --help
174
+ applebookscli <group> <subcommand> --help
175
+ ```
79
176
 
80
- ## 文档
177
+ ## 开发与维护
81
178
 
82
- 长期产品文档从 `docs/index.md` 开始。能力范围以 `docs/capability-matrix.md` 为准；架构与 identity/source 边界见 `docs/architecture.md`；CLI process contract 见 `docs/cli-contract.md`；mutation/restore safety 见 `docs/write-safety.md`。
179
+ 架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
83
180
 
84
181
  ## License
85
182
 
86
- AppleBooksCLI 使用 GNU Affero General Public License v3（AGPLv3）。实际构建依赖的第三方 notice 与许可证文本见 `THIRD_PARTY_NOTICES.md` 和 `ThirdPartyLicenses/`。
183
+ AppleBooksCLI 使用 GNU Affero General Public License v3（AGPLv3）。第三方 notice 与许可证文本见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 和 [`ThirdPartyLicenses/`](ThirdPartyLicenses/)。
package/bin/applebookscli CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chiimagnus/applebookscli",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "Native Apple Books CLI for macOS on Apple Silicon.",
5
5
  "license": "AGPL-3.0-only",
6
6
  "repository": {
package/share/applebookscli/skill/applebookscli/SKILL.md CHANGED
@@ -1,50 +1,36 @@
1
1
  ---
2
2
  name: applebookscli
3
- description: 通过 `applebookscli` 查询、定位、导出或受保护地修改 Apple Books 图书、阅读状态、EPUB/PDF、批注笔记与藏书，以及执行备份恢复或访问诊断时使用。
3
+ description: 通过 `applebookscli` 查询、定位、导出或受保护地修改 Apple Books 图书、阅读状态、EPUB/PDF、批注笔记与藏书，以及执行云同步、备份恢复或访问诊断时使用。
4
4
  ---
5
5
 
6
6
  # AppleBooksCLI
7
7
 
8
- 使用已安装的 `applebookscli` 作为 Apple Books 数据操作的唯一入口。用户询问自己的 Apple Books 数据时，实际查询后再回答，不用能力说明代替结果。
8
+ 使用已安装的 `applebookscli` 作为 Apple Books 数据操作入口。用户询问自己的数据时，实际查询后再回答，不用能力说明代替结果。
9
9
 
10
- ## 回答前先查阅
10
+ ## 命令与 identity
11
11
 
12
- CLI 自身是命令契约。需要确认命令、参数或枚举值时，优先读取当前帮助，不依赖记忆，也不在 Skill 中维护第二份命令手册：
12
+ 命令、参数和枚举以当前 `--help` 为准；需要机器结果时优先 `--json`，`export` 使用 `--format json`。`doctor` 只用于诊断实际的 permission / unavailable / schema 问题。
13
13
 
14
- - `applebookscli --help`
15
- - `applebookscli <group> --help`
16
- - `applebookscli <group> <subcommand> --help`
14
+ 优先使用稳定 identity：book asset ID、annotation UUID、collection ID、backup handle。标题/作者/名称先 search/list 并确认唯一；local PK 只在用户明确指定或没有稳定 identity 时使用。不要静默选择多候选中的第一项。
17
15
 
18
- 使用完成目标所需的最窄命令；普通查询、写入和状态判断需要结构化结果时优先 `--json`。`export` 的 JSON 输出使用 `--format json`，不要把 operational `--json` 套到 export。`doctor` 只用于诊断请求，或实际出现 permission、unavailable、schema readiness 一类问题时。`--library-db`、`--annotations-db`、`--config` 只用于用户明确指定或 fixture/test，不作为故障 fallback。
16
+ ## Annotation 与写入
19
17
 
20
- ## Identity
18
+ “最新笔记”只在 nonempty note 中比较；“最新”默认按创建时间，“最近修改”按修改时间。具体 annotation 优先返回高亮、note、必要时间与 `appleBooksURL`；需要前后正文时才用 `content context`。
21
19
 
22
- 优先使用稳定 identity：book asset ID、annotation UUID、collection ID、backup handle。标题、作者和名称只是搜索条件；先 search/list，唯一匹配后再继续。不要静默选择多个候选中的第一项；local PK 只在没有稳定 identity 或用户明确指定时使用。
20
+ `annotations update-note --note` 是整段替换。用户要求追加时先读原 note，再构造完整新值。`annotations delete` soft-delete 整条 annotation，不用于清空 note。
23
21
 
24
- 阅读状态以 `reading` 的 canonical 结果为准，不从进度百分比推断 finished/in-progress/unstarted。“最近打开”也不等于“当前正在前台阅读”；用户说“当前这本书”时优先复用已经唯一解析的上下文，若只能得到 recent 结果就按 recent 候选表述。
22
+ 只有用户明确要求修改或 restore 时才写。不要直接读写 Apple Books SQLite，也不要额外手工 quit/launch Books；guarded mutation rail 已负责 backup、Books lifecycle、事务、read-back 与 cloud projection。
25
23
 
26
- ## Annotations
24
+ `committed=true` 后出现 warning 不能自动重试；结果未知时先做最窄只读确认。单条 mutation 只有在用户要求立即确认上传时才加 `--sync`。连续多条写入先正常执行，最后一次 `applebookscli sync --json`，避免每条都触发 lifecycle。
27
25
 
28
- 用户问“最新笔记”时，只在 `note` 非空的 annotation 中比较；“最新”默认按创建时间，“最近修改”按修改时间。不要把普通高亮误报成笔记。
29
-
30
- 展示一条具体 annotation 时，优先返回高亮文本、note、必要时间和 `appleBooksURL`。不要自行拼接 `ibooks://`，也不要为了生成 deep link 调用 `content locate`。只有用户需要高亮前后正文时才使用 `content context`。
31
-
32
- `annotations update-note` 的 `--note` 是**整段替换文本**。用户要求追加、补充或加评论时，先读取原 note，保留原文构造完整新 note，再用 exact UUID 和 `--json` 写回。`annotations delete` soft-delete 的是整条 annotation，不要用它代替“清空 note 文本”。
33
-
34
- ## 写入与恢复
35
-
36
- 只有用户明确要求修改 annotation、collection 或恢复备份时才执行写操作。CLI 的 guarded mutation rail 已负责安全备份、Books.app 生命周期、事务与 read-back；不要直接读写 Apple Books SQLite，也不要额外手工 quit/launch Books.app。
37
-
38
- `committed=true` 表示事务已经提交，不能因为后续 warning 自动重试；`changed=false` 是成功的幂等 no-op。出现 `read_back_failed`，或调用超时/中断导致结果未知时，先做最窄只读确认，再决定是否还需要写入。CLI 创建的 safety backup 默认保留。
39
-
40
- `backups list/restore` 只面向 library database；不要假定 annotation mutation 返回的 backup handle 可以交给这个恢复面。Restore 以返回的 `changed`、`status`、`verified` 为准；`restored_unverified` 表示恢复已经应用但验证失败，不能自动再 restore。
26
+ `--sync` / `sync` 成功只证明当前 Mac 的 Apple Books cloud records 获得 CloudKit acknowledgement；没有 second-device 证据时不要声称另一设备已经显示。`cloud_sync_failed` 是 post-commit warning。`backups restore` 是 BKLibrary snapshot replacement，不要把 restore 后的 `sync` 解释成 snapshot diff 已逐条上传。
41
27
 
42
28
  ## EPUB、PDF 与导出
43
29
 
44
- EPUB 内容不可用时，只有需要解释原因才运行 `content status --json`；不要绕过 DRM/encryption，也不要主动触发下载。PDF 没有 exact book/path 时先用 `pdf list --json` 解析唯一 source；worker failure/timeout 与“成功读取但没有 highlights”是不同结果。
30
+ EPUB 不可用时按需要用 `content status --json` 解释原因；不绕过 DRM，也不主动 hydration。PDF 只处理当前可解析的本地 source；不要把 PDF 命令当作已证明 non-hydrating 的 iCloud placeholder probe。
45
31
 
46
- 用户要求完整笔记归档时必须使用 `--complete-notes` 的 fail-closed 路径；完整性校验失败就停止并报告，不能降级为普通 export 后声称归档完整。普通导出遵守用户给定的输出与 overwrite 策略，不擅自覆盖已有文件。
32
+ 完整笔记归档使用 `--complete-notes` 的 fail-closed 路径；失败时不能降级成普通 export 后声称完整。普通导出遵守用户给定的输出与 overwrite 策略。
47
33
 
48
- ## 返回结果
34
+ ## 完成判断
49
35
 
50
- 不要把 exit 0 当成用户目标已经完成；以实际返回数据证明结果，并区分 empty、not found、unavailable、degraded 和 warning。本地 mutation 成功也不等于已经同步到 iCloud；没有另一设备或其它端到端证据时，只确认本地 Apple Books 状态。
36
+ 不要把 exit 0 当成目标完成；以返回数据证明结果，并区分 empty、not found、unavailable、degraded、warning 与 CloudKit acknowledgement。