@chiimagnus/applebookscli 0.1.4-beta → 0.1.5
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
|
@@ -1,86 +1,167 @@
|
|
|
1
1
|
# AppleBooksCLI
|
|
2
2
|
|
|
3
|
-
AppleBooksCLI
|
|
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
|
-
-
|
|
9
|
-
- Apple Books
|
|
10
|
-
-
|
|
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
|
-
|
|
32
|
+
如果需要试用 beta：
|
|
21
33
|
|
|
22
34
|
```sh
|
|
23
35
|
npm install --global @chiimagnus/applebookscli@beta
|
|
24
36
|
```
|
|
25
37
|
|
|
26
|
-
|
|
38
|
+
更新到最新稳定版：
|
|
27
39
|
|
|
28
|
-
|
|
40
|
+
```sh
|
|
41
|
+
npm install --global @chiimagnus/applebookscli@latest
|
|
42
|
+
```
|
|
29
43
|
|
|
30
|
-
##
|
|
44
|
+
## 快速开始
|
|
31
45
|
|
|
32
|
-
|
|
46
|
+
```sh
|
|
47
|
+
# 浏览书库
|
|
48
|
+
applebookscli books list
|
|
33
49
|
|
|
34
|
-
|
|
35
|
-
|
|
50
|
+
# 查看正在阅读的书
|
|
51
|
+
applebookscli reading in-progress
|
|
36
52
|
|
|
37
|
-
|
|
53
|
+
# 查看最近创建的批注
|
|
54
|
+
applebookscli annotations recent
|
|
38
55
|
|
|
39
|
-
|
|
56
|
+
# 查看书库统计
|
|
57
|
+
applebookscli stats
|
|
58
|
+
```
|
|
40
59
|
|
|
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 |
|
|
60
|
+
需要结构化结果时，大多数查询命令支持 `--json`：
|
|
53
61
|
|
|
54
|
-
|
|
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
|
+
搜索、按书筛选、颜色、时间范围等能力以当前帮助为准：
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
applebookscli annotations --help
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## EPUB 与 PDF
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
# EPUB 内容相关命令
|
|
94
|
+
applebookscli content --help
|
|
95
|
+
|
|
96
|
+
# 查看 PDF inventory
|
|
97
|
+
applebookscli pdf list
|
|
98
|
+
|
|
99
|
+
# 提取某个 PDF 的 highlights
|
|
100
|
+
applebookscli pdf highlights --help
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
AppleBooksCLI 只读取本机当前可访问的内容；不会为了检查内容而主动触发 iCloud 下载，也不会绕过 DRM。
|
|
104
|
+
|
|
105
|
+
## 导出
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
# Markdown
|
|
109
|
+
applebookscli export --format markdown --output ~/Desktop/apple-books.md
|
|
110
|
+
|
|
111
|
+
# JSON
|
|
112
|
+
applebookscli export --format json --output ~/Desktop/apple-books.json
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
还支持 CSV、HTML、按书分组、筛选划线/笔记、Obsidian 格式、封面与完整笔记归档等选项：
|
|
55
116
|
|
|
56
117
|
```sh
|
|
57
|
-
applebookscli books --help
|
|
58
118
|
applebookscli export --help
|
|
59
|
-
applebookscli collections --help
|
|
60
119
|
```
|
|
61
120
|
|
|
62
|
-
|
|
121
|
+
## 安全写入
|
|
63
122
|
|
|
64
|
-
|
|
123
|
+
AppleBooksCLI 可以修改已有笔记和管理藏书。写入前会自动创建备份，并在写入后验证结果；普通查询不会隐式修改 Apple Books 数据。
|
|
65
124
|
|
|
66
|
-
|
|
125
|
+
```sh
|
|
126
|
+
applebookscli annotations update-note --help
|
|
127
|
+
applebookscli collections --help
|
|
128
|
+
applebookscli backups --help
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## 安装 AppleBooksCLI Skill
|
|
132
|
+
|
|
133
|
+
npm 包中包含配套的 `applebookscli` Skill：
|
|
67
134
|
|
|
68
135
|
```sh
|
|
69
136
|
applebookscli skill install
|
|
70
137
|
```
|
|
71
138
|
|
|
72
|
-
|
|
139
|
+
它会安装到 `${CODEX_HOME:-~/.codex}/skills/applebookscli`。如果目标已经存在，CLI 默认不会覆盖；需要明确替换时使用：
|
|
73
140
|
|
|
74
141
|
```sh
|
|
75
142
|
applebookscli skill install --force
|
|
76
143
|
```
|
|
77
144
|
|
|
78
|
-
|
|
145
|
+
## 可选配置
|
|
146
|
+
|
|
147
|
+
大多数用户不需要配置文件。只有需要指定额外的 EPUB 目录，或给历史批注补充书名/作者信息时，才需要 `~/.config/applebookscli/config.json`。
|
|
148
|
+
|
|
149
|
+
示例见 [`Config/applebookscli.example.json`](Config/applebookscli.example.json)。
|
|
150
|
+
|
|
151
|
+
## 获取帮助
|
|
152
|
+
|
|
153
|
+
CLI 自带完整帮助，具体命令与参数以当前安装版本为准：
|
|
154
|
+
|
|
155
|
+
```sh
|
|
156
|
+
applebookscli --help
|
|
157
|
+
applebookscli <group> --help
|
|
158
|
+
applebookscli <group> <subcommand> --help
|
|
159
|
+
```
|
|
79
160
|
|
|
80
|
-
##
|
|
161
|
+
## 开发与维护
|
|
81
162
|
|
|
82
|
-
|
|
163
|
+
架构、CLI contract、写入安全、发布流程和其它维护者文档从 [`docs/index.md`](docs/index.md) 开始。
|
|
83
164
|
|
|
84
165
|
## License
|
|
85
166
|
|
|
86
|
-
AppleBooksCLI 使用 GNU Affero General Public License v3（AGPLv3
|
|
167
|
+
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
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,27 +1,50 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: applebookscli
|
|
3
|
-
description:
|
|
3
|
+
description: 通过 `applebookscli` 查询、定位、导出或受保护地修改 Apple Books 图书、阅读状态、EPUB/PDF、批注笔记与藏书，以及执行备份恢复或访问诊断时使用。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# AppleBooksCLI
|
|
7
7
|
|
|
8
|
-
使用已安装的 `applebookscli` 作为 Apple Books
|
|
8
|
+
使用已安装的 `applebookscli` 作为 Apple Books 数据操作的唯一入口。用户询问自己的 Apple Books 数据时，实际查询后再回答，不用能力说明代替结果。
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## 回答前先查阅
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
- **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”是不同结果。
|
|
14
|
-
- **导出**：先确定用户要求的范围、格式和输出目标，再运行 `export`。用户没有要求覆盖时保持 no-clobber，不因为文件已存在就自行升级 overwrite policy。“完整笔记归档”必须使用 complete-notes 路径；安全或完整性校验失败时停止并报告，不能降级成普通 export 后声称归档完整。
|
|
15
|
-
- **写入**：只有用户明确要求 annotation 或 collection 变更时才执行 mutation。涉及既有对象时先只读解析 exact target，并用 `--json` 执行写命令。以 `committed` / `changed` 判定结果；已 committed 的操作不能因后续 warning 自动重试，`changed=false` 是成功的幂等 no-op。只有 CLI 报 read-back warning，或返回值仍不足以证明用户要求的最终状态时，才补一条最窄只读确认。
|
|
16
|
-
- **Restore**：只在用户明确要求时执行，不作为普通 mutation 的自动 fallback。用户给了 exact backup handle 就直接使用，否则先 `backups list --json` 解析唯一目标，并用 `--json` 执行 restore。以 `changed` / `status` 判定结果；`changed=true` 或 `restored_unverified` 都不能自动再 restore。只有返回状态仍不足以证明用户要求的最终结果时，才补最窄只读检查。
|
|
12
|
+
CLI 自身是命令契约。需要确认命令、参数或枚举值时，优先读取当前帮助，不依赖记忆，也不在 Skill 中维护第二份命令手册：
|
|
17
13
|
|
|
18
|
-
|
|
14
|
+
- `applebookscli --help`
|
|
15
|
+
- `applebookscli <group> --help`
|
|
16
|
+
- `applebookscli <group> <subcommand> --help`
|
|
19
17
|
|
|
20
|
-
|
|
21
|
-
- 优先使用稳定 identity：book asset ID、annotation UUID、collection ID、backup handle；local PK 只在没有稳定 identity 或用户明确指定时使用。
|
|
22
|
-
- 只读取完成请求所需的最小内容；不要为了预检扩大 EPUB/PDF 正文或批注范围。
|
|
23
|
-
- 自定义 DB/config override 只在用户明确指定或任务本来就是 fixture/test 场景时使用，不作为故障 fallback。
|
|
24
|
-
- 只清理当前任务明确创建的临时文件；用户指定的导出产物、CLI 创建的 safety backup、既有 Apple Books 数据与配置默认保留。
|
|
25
|
-
- mutation/restore 的调用结果若因超时、中断等变成未知，先只读确认目标状态，不直接重发副作用；其它失败也只有在出现新证据、输入或环境变化后才重试。
|
|
18
|
+
使用完成目标所需的最窄命令；普通查询、写入和状态判断需要结构化结果时优先 `--json`。`export` 的 JSON 输出使用 `--format json`，不要把 operational `--json` 套到 export。`doctor` 只用于诊断请求，或实际出现 permission、unavailable、schema readiness 一类问题时。`--library-db`、`--annotations-db`、`--config` 只用于用户明确指定或 fixture/test，不作为故障 fallback。
|
|
26
19
|
|
|
27
|
-
|
|
20
|
+
## Identity
|
|
21
|
+
|
|
22
|
+
优先使用稳定 identity：book asset ID、annotation UUID、collection ID、backup handle。标题、作者和名称只是搜索条件；先 search/list，唯一匹配后再继续。不要静默选择多个候选中的第一项；local PK 只在没有稳定 identity 或用户明确指定时使用。
|
|
23
|
+
|
|
24
|
+
阅读状态以 `reading` 的 canonical 结果为准，不从进度百分比推断 finished/in-progress/unstarted。“最近打开”也不等于“当前正在前台阅读”；用户说“当前这本书”时优先复用已经唯一解析的上下文，若只能得到 recent 结果就按 recent 候选表述。
|
|
25
|
+
|
|
26
|
+
## Annotations
|
|
27
|
+
|
|
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。
|
|
41
|
+
|
|
42
|
+
## EPUB、PDF 与导出
|
|
43
|
+
|
|
44
|
+
EPUB 内容不可用时，只有需要解释原因才运行 `content status --json`；不要绕过 DRM/encryption，也不要主动触发下载。PDF 没有 exact book/path 时先用 `pdf list --json` 解析唯一 source；worker failure/timeout 与“成功读取但没有 highlights”是不同结果。
|
|
45
|
+
|
|
46
|
+
用户要求完整笔记归档时必须使用 `--complete-notes` 的 fail-closed 路径；完整性校验失败就停止并报告，不能降级为普通 export 后声称归档完整。普通导出遵守用户给定的输出与 overwrite 策略，不擅自覆盖已有文件。
|
|
47
|
+
|
|
48
|
+
## 返回结果
|
|
49
|
+
|
|
50
|
+
不要把 exit 0 当成用户目标已经完成；以实际返回数据证明结果，并区分 empty、not found、unavailable、degraded 和 warning。本地 mutation 成功也不等于已经同步到 iCloud；没有另一设备或其它端到端证据时，只确认本地 Apple Books 状态。
|