核心用法
Hardcover 技能通过官方 GraphQL API 实现个人阅读数据的全量查询。用户需先从 hardcover.app/settings 获取 API Token 并配置为环境变量 HARDCOVER_API_TOKEN，技能自动携带 Bearer Token 完成认证。核心工作流分为三步：首先调用 me 查询获取用户 ID，随后通过 user_books 配合 status_id 过滤（1=想读/2=在读/3=已读/4=暂停/5=弃读）拉取书单，最后按需嵌套查询阅读进度、作者信息、封面图等关联数据。
技能支持多维度查询：当前阅读进度（含页码百分比）、书库按状态分页检索、书名/作者/系列的全局搜索（支持 Book/Author/Series/Character 等类型），以及单本详情（ISBN、出版社、版本格式）。对于大量藏书，需使用 limit/offset 分页并添加 distinct_on: book_id 去重。
显著优点
- 数据主权清晰：Token 直连个人账户，无第三方数据中转
- GraphQL 灵活取数：单次请求可嵌套书籍、作者、阅读记录、目标进度等多层数据
- 生态兼容性强：JSON 输出便于导入 Obsidian、Notion 等笔记工具，适合构建个人阅读看板
- 社区属性：可访问关注用户的公开书单（需对方隐私设置允许）
潜在局限
- 只读接口：暂不支持写操作（标记在读、更新进度等需回官网操作）
- 搜索能力弱：无模糊匹配或全文检索，需精确书名或依赖全局搜索端点
- Token 年抛：API Token 有效期一年，需定期轮换
- 速率限制：60 请求/分钟对重度批量同步场景可能吃紧
- 隐私边界：仅能访问自己的数据、公开数据及已关注用户数据
适合人群
- 使用 Hardcover 记录阅读且希望数据本地化的深度读者
- 需要将书库与笔记系统（Obsidian/Notion）联动的效率工具用户
- 跟踪年度阅读目标、分析阅读偏好的量化自我爱好者
常规风险
- Token 泄露风险：Bearer Token 若暴露可被读取个人全部阅读数据，需妥善保管环境变量
- API 变动：Hardcover 处于快速迭代期，字段或认证方式可能调整
- 依赖外部服务：API 可用性完全依赖 Hardcover 平台稳定性