@chiimagnus/applebookscli 0.1.5 → 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.
package/README.md
CHANGED
|
@@ -100,7 +100,7 @@ applebookscli pdf list
|
|
|
100
100
|
applebookscli pdf highlights --help
|
|
101
101
|
```
|
|
102
102
|
|
|
103
|
-
|
|
103
|
+
EPUB 在读取正文前会先检查本地 materialization 状态，不主动触发 iCloud hydration，也不会绕过 DRM。PDF 只处理当前可解析为可读本地文件的 source；对 iCloud placeholder 的 non-hydrating 行为尚未建立等价保证。
|
|
104
104
|
|
|
105
105
|
## 导出
|
|
106
106
|
|
|
@@ -112,7 +112,7 @@ applebookscli export --format markdown --output ~/Desktop/apple-books.md
|
|
|
112
112
|
applebookscli export --format json --output ~/Desktop/apple-books.json
|
|
113
113
|
```
|
|
114
114
|
|
|
115
|
-
还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian
|
|
115
|
+
还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项。有 CFI 的 EPUB 批注在 HTML/Markdown 中会把 `Location` 本身做成 Apple Books deep link；无 CFI 时退化为书籍级链接。JSON/CSV 保留对应 `appleBooksURL`：
|
|
116
116
|
|
|
117
117
|
```sh
|
|
118
118
|
applebookscli export --help
|
|
@@ -128,6 +128,22 @@ applebookscli collections --help
|
|
|
128
128
|
applebookscli backups --help
|
|
129
129
|
```
|
|
130
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
|
|
143
|
+
```
|
|
144
|
+
|
|
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。
|
|
146
|
+
|
|
131
147
|
## 安装 AppleBooksCLI Skill
|
|
132
148
|
|
|
133
149
|
npm 包中包含配套的 `applebookscli` Skill：
|
package/bin/applebookscli
CHANGED
|
Binary file
|
|
Binary file
|
package/package.json
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
|
|
8
|
+
使用已安装的 `applebookscli` 作为 Apple Books 数据操作入口。用户询问自己的数据时，实际查询后再回答，不用能力说明代替结果。
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## 命令与 identity
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
命令、参数和枚举以当前 `--help` 为准；需要机器结果时优先 `--json`，`export` 使用 `--format json`。`doctor` 只用于诊断实际的 permission / unavailable / schema 问题。
|
|
13
13
|
|
|
14
|
-
|
|
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
|
-
|
|
16
|
+
## Annotation 与写入
|
|
19
17
|
|
|
20
|
-
|
|
18
|
+
“最新笔记”只在 nonempty note 中比较；“最新”默认按创建时间，“最近修改”按修改时间。具体 annotation 优先返回高亮、note、必要时间与 `appleBooksURL`；需要前后正文时才用 `content context`。
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
`annotations update-note --note` 是整段替换。用户要求追加时先读原 note，再构造完整新值。`annotations delete` soft-delete 整条 annotation，不用于清空 note。
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
只有用户明确要求修改或 restore 时才写。不要直接读写 Apple Books SQLite，也不要额外手工 quit/launch Books；guarded mutation rail 已负责 backup、Books lifecycle、事务、read-back 与 cloud projection。
|
|
25
23
|
|
|
26
|
-
|
|
24
|
+
`committed=true` 后出现 warning 不能自动重试；结果未知时先做最窄只读确认。单条 mutation 只有在用户要求立即确认上传时才加 `--sync`。连续多条写入先正常执行，最后一次 `applebookscli sync --json`，避免每条都触发 lifecycle。
|
|
27
25
|
|
|
28
|
-
|
|
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
|
|
30
|
+
EPUB 不可用时按需要用 `content status --json` 解释原因；不绕过 DRM，也不主动 hydration。PDF 只处理当前可解析的本地 source；不要把 PDF 命令当作已证明 non-hydrating 的 iCloud placeholder probe。
|
|
45
31
|
|
|
46
|
-
|
|
32
|
+
完整笔记归档使用 `--complete-notes` 的 fail-closed 路径；失败时不能降级成普通 export 后声称完整。普通导出遵守用户给定的输出与 overwrite 策略。
|
|
47
33
|
|
|
48
|
-
##
|
|
34
|
+
## 完成判断
|
|
49
35
|
|
|
50
|
-
不要把 exit 0
|
|
36
|
+
不要把 exit 0 当成目标完成；以返回数据证明结果，并区分 empty、not found、unavailable、degraded、warning 与 CloudKit acknowledgement。
|