hardcover

核心用法

Hardcover Skill 是一个纯文档型的 API 查询指南，用于连接 Hardcover.app 的 GraphQL 服务。用户需先从 Hardcover 设置页获取 API Token，配置为环境变量后即可使用。核心工作流分为三步：首先通过 me 查询获取用户 ID，随后利用 status_id 参数筛选不同阅读状态（1=想读、2=在读、3=已读、4=暂停、5=弃读），最后通过分页参数处理大量数据。支持的功能包括：查询当前阅读进度（含页数统计）、按状态检索个人书库、搜索书籍/作者/系列信息，以及获取图书详细元数据（ISBN、出版社、封面图等）。

显著优点

该 Skill 的最大优势在于纯文档零风险——不包含任何可执行代码，仅提供标准化的 API 调用示例，内容完全透明可审计。其次，它直接对接 Hardcover.app 官方服务，数据来源权威可靠，且严格遵循只读设计，杜绝了误操作修改数据的可能。查询语法采用直观的 GraphQL，支持精确字段选择，避免过度获取数据。对于 Obsidian 等笔记工具用户，该 Skill 提供了将阅读数据同步至外部系统的标准化路径，填补了个人知识管理与阅读追踪之间的空白。

潜在缺点与局限性

功能层面存在明显约束：目前仅支持查询（Read-only），无法执行添加书籍、更新进度等写操作；缺乏文本搜索能力，不支持 _like、_ilike、_regex 等模糊匹配操作符，只能通过精确标题或 ID 查询；数据访问范围受限，仅能获取本人数据、公开数据及关注用户的数据。技术层面，API 存在 60 请求/分钟的速率限制、30 秒超时限制以及最大 3 层查询深度限制，大规模数据同步时需注意分页策略。此外，Token 有效期仅 1 年，需定期维护更新。

适合的目标群体

该 Skill 最适合以下用户：重度使用 Hardcover.app 追踪阅读进度的数字阅读者；希望将阅读数据整合至 Obsidian、Notion 等笔记系统的知识管理爱好者；需要定期生成阅读报告或统计阅读目标的自我量化实践者；以及开发阅读相关工具、需要标准化数据源整合的独立开发者。对于仅偶尔记录阅读、或依赖 Goodreads 等其他平台的用户，迁移成本可能较高。

使用风险

常规风险主要集中在配置与运维层面：API Token 泄露可能导致个人阅读数据被未授权访问，需严格遵循环境变量配置而非硬编码；Token 过期会导致服务中断，建议设置到期提醒；高频查询可能触发 429 速率限制，批量操作时应实现退避重试机制。由于该 Skill 本身无代码执行，不存在供应链攻击或恶意代码注入风险，整体安全可控。