babeliocli — 读取书架与图书（Read Shelves and Books）
babeliocli 提供对已登录用户书库的访问。它是只读的，绝不会修改 Babelio 的状态。
前置条件
必须存在一个会话。如有需要，参见 babeliocli-setup 技能，或运行：
babeliocli whoami # 确认会话
书架（Shelves）
babeliocli shelves # JSON（默认）
babeliocli shelves -f text # 人类可读视图
支持的书架键（Key）：
| Key | 标签 | Babelio 过滤器 |
|---|---|---|
| all | Mes livres | ?action=toute |
| lus | Lus | ?s1=1 |
| a-lire | À lire | ?s1=2 |
| en-cours | En cours | ?s1=0 |
| pense-bete | Pense-bête | ?s1=3 |
| abandonnes | Abandonnés | ?s1=4 |
| critiques | Critiqués | ?s3=10 |
| non-critiques | Non critiqués | ?s3=11 |
图书（Books）
babeliocli books --shelf lus # 所有“已读”图书，JSON
babeliocli books --shelf lus --limit 10 # 前 10 本图书
babeliocli books --shelf a-lire -f text # 人类可读视图
参数标志（Flags）：
- --shelf（必填，默认 all）：上述键之一。
- --limit N（默认 0 = 不限制）：在 N 本图书后停止。
- --max-pages N（默认 50）：HTTP 分页的安全上限。
分页是自动处理的。CLI 会先以该过滤器请求第一页，然后跟随 pageN=N，因为 Babelio 将当前活动过滤器存储在 PHP 会话中。
图书 JSON 结构（每条书架条目）
{
"id_biblio": "90486207",
"book_id": "1917163",
"title": "Une espèce en voie de disparition",
"author": "Lavie Tidhar",
"author_id": "271314",
"book_url": "https://www.babelio.com/livres/Tidhar-Une-espece-en-voie-de-disparition/1917163",
"status": "Lu",
"rating": 4,
"readers": 259,
"tags": [],
"read_start": "2025-09-01",
"read_end": "2025-09-05"
}
说明：
- id_biblio 是每个用户的书架条目（用于调试 Babelio URL 时很有用）；book_id 是全局共享的标识符，用于 /livres/.../BOOK_ID。
- rating 是 0–5 的整数（0 = 未评分）。
- read_start / read_end 是用户输入的日期（YYYY-MM-DD）。当用户从未填写时为空。
- status 与 Babelio 的法文标签一致：Lu、À lire、En cours、Pense bête、Abandonné、Possédé。
常见智能体用法（Common agent recipes）
按月份将已读图书分组：
babeliocli books --shelf lus |
jq -r '.books[] | select(.read_end != "") | "\(.read_end[0:7])\t\(.title)"' |
sort
统计每年已读图书数量：
babeliocli books --shelf lus |
jq -r '.books[] | select(.read_end != "") | .read_end[0:4]' |
sort | uniq -c | sort -rn
书库中评分最高的图书：
babeliocli books --shelf all |
jq '.books | map(select(.rating == 5)) | map({title, author})'
按部分标题查找你拥有的图书：
babeliocli books --shelf all |
jq --arg q "hyperion" '.books[] | select(.title | ascii_downcase | contains($q))'
注意事项（Gotchas）
- 如果一本书没有 read_end，不要假定为“尚未阅读”；它可能意味着用户从未填写该日期。
- Babelio 的 status “Lu” 具有权威性；日期只是元数据。
- 书架 critiques 和 non-critiques 与 lus 相交，因此对计数求和会造成重复计数。
- 会话过期会在 stderr 上返回 session expired: … 并带有非零退出码——你的脚本应检测到这一点并触发重新认证流程。