openlibrary 是用于查询 Open Library 公共目录(5,000 万条以上记录)的命令行技能,通过公开 HTTP API 完成读书相关检索,全部为免密钥的 GET 请求,无需注册或令牌。
用途与主要能力:搜索图书(含排序、语言偏好、分页、JSON 输出);搜索作者;查看作者与作品记录;用 ISBN-10/13 解析出对应版本;枚举某作品的全部版本;读取社区评分与书架统计(想读、在读、已读)。结果包含标题、作者、首次出版年、版本数以及后续命令所需的 work key。
使用方式:需 Python 3.8+ 与 requests;可选设置 export OL_EMAIL="you@example.com" 以获得约 3 倍限速(匿名约 1 请求/秒,标识后约 3 请求/秒)。子命令包括 search、search-authors、author、work、isbn、editions、ratings;全局参数 --json、--dry-run、--quiet、--verbose 位置无关。--dry-run 可在不联网的情况下预览请求 URL。建议配合 jq 处理 JSON。
数据涉及三个主机:openlibrary.org 提供元数据 JSON;covers.openlibrary.org 提供封面与作者照片;archive.org 承载扫描内容与批量转储。
限制与注意:ISBN 端点返回 302 重定向,需跟随跳转;作品被合并后旧 key 会在 HTTP 200 中返回重定向桩,需检测并重新获取;key 类型由后缀区分(M=版本、W=作品、A=作者),跨集合请求会 301;搜索无结果不是错误,而错误的排序值会导致纯文本 HTTP 500;速率限制是策略而非响应头,缺封面可能返回空白占位且为 200。该技能仅供读取,写入端点需经认证的 Internet Archive 会话,不在此覆盖范围。不适用于本地图书馆系统管理、商业授权数据源、引用格式排版或管理个人 Open Library 账户与书单;影视元数据应改用 tmdb。参考文件与脚本(scripts/openlibrary、test_openlibrary.py)及离线测试在源文档中说明。