Hardcover图书查询

技能简介

通过 GraphQL API 连接 Hardcover.app，查询个人阅读列表、书籍元数据及馆藏信息。支持按阅读状态筛选、检索作者与系列作品、获取阅读进度百分比，并可将数据同步至 Obsidian 等外部系统。

业务背景

Hardcover图书查询帮助阅读爱好者集中管理个人藏书与阅读进度。通过GraphQL接口，可按"正在读""想读""已读"等状态快速筛选书单，实时掌握每本书的阅读完成度，并提取书籍元数据用于个人知识库整理或年度阅读回顾，解决多平台分散记录、手工统计繁琐的痛点。

落地案例：一位用户计划整理全年阅读报告，使用本工具调用API获取所有"已读"书籍列表，批量导出书名、作者、页数及阅读时间跨度；同时筛选"在读"书目监控当前进度百分比，将结构化数据同步至Obsidian笔记系统，自动生成可视化阅读看板，无需逐本手动录入。

能做什么

• 列出”正在读””想读””已读”等分类书单
• 查询单本书的页数、ISBN、出版社、封面图
• 搜索书籍、作者、系列名称
• 获取阅读页数进度与完成比例
• 导出数据用于个人知识库或年度统计

使用说明

1. 获取 API Token
   访问 hardcover.app/settings 生成令牌
2. 配置环境变量

   export HARDCOVER_API_TOKEN="your_token_here"

3. 验证连接

   curl -X POST https://api.hardcover.app/v1/graphql \
     -H "Authorization: Bearer $HARDCOVER_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "query { me { id username } }"}'

4. 常用查询示例
   获取正在阅读的书籍及进度：

   query {
     me {
       user_books(where: { status_id: { _eq: 2 } }) {
         user_book_reads { progress_pages }
         book {
           title
           pages
           image { url }
           contributions { author { name } }
         }
       }
     }
   }

   按状态查询馆藏（status_id: 1=想读, 2=在读, 3=已读, 4=暂停, 5=放弃）：

   query ($userId: Int!, $status: Int!) {
     user_books(
       where: { user_id: { _eq: $userId }, status_id: { _eq: $status } }
       limit: 25
       distinct_on: book_id
     ) {
       book { id title pages image { url } }
     }
   }

   搜索书籍/作者/系列：

   query ($q: String!, $type: String!) {
     search(query: $q, query_type: $type, per_page: 10) { results }
   }

   type 可选值：Book、Author、Series、Character、List、Publisher、User

输入与输出

见下方输入与输出表格。

风险提示

• Token 有效期为一年，到期需重新生成
• 限流 60 请求/分钟，超时 30 秒，查询深度最大 3 层
• 仅只读访问，不支持修改阅读状态或添加书籍
• 无法使用模糊搜索（无 _like/_regex 操作符）
• 仅能访问本人数据、公开数据及关注用户的数据

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/asaphko/hardcover/SKILL.md
来源类型：GitHub 仓库