微信读书 API 接口

最近我把读书笔记插件里的微信读书同步功能，从原来的 Cookie 网页版接口模式，迁移到了现在的 SKILL API 官方接口模式。

这个过程不只是换了几个请求地址，而是把整个微信读书同步链路重新梳理了一遍：书架、有笔记书籍、划线、想法、热门划线、公众号文章、阅读统计，都统一到了新的接口模式下。

这篇文章主要记录一下两套接口的区别、现在使用的接口清单，以及为什么我最终决定放弃旧 Cookie 方案。

一、旧方案：Cookie + Web 接口

早期的微信读书同步，大多是模拟网页版请求。基本思路是：

1. 用户提供微信读书 Cookie。

2. 插件通过代理请求微信读书 Web 接口。

3. 接口返回书籍、划线、评论、章节等数据。

4. 再把这些数据整理成笔记文档。

旧方案能用，但它的问题也很明显：

• Cookie 有过期风险，也有隐私风险；

• Web 接口不稳定；

• 有些接口还需要特殊方式绕过浏览器环境限制。

维护时间久了，整个同步链路会越来越脆弱。

旧接口大致包括

旧接口返回的数据一般包括：

• 书籍列表

• 书籍详情

• 章节列表

• 个人划线

• 个人想法 / 书评

• 热门划线

• 书架数据

这些接口曾经支撑了很长一段时间的同步功能，但它们毕竟不是一个更适合长期维护的接入方式。

二、新方案：SKILL API 官方接口模式

现在的新方案是使用 API Key 调用统一网关。

API Key 申请入口：https://weread.qq.com/r/weread-skills

当前统一请求入口是：https://weread.qq.com/api/agent/gateway​

请求方式是 POST​，通过 Header 传入 API Key：

这里有一个需要注意的点：业务参数不要再包一层 params​，而是直接和 api_name​、skill_version​ 放在同一层。

比如请求书籍详情时，本质上是向统一网关提交：

正常响应不一定都有 errcode​。只要返回了业务字段，就可以按成功结果处理。鉴权失败时，通常会返回类似 errcode: -2013​ 的错误。

三、当前主要接口清单

1. API Key 验证

这个接口主要用于判断 Key 是否有效。错误 Key 会返回鉴权失败，正确 Key 会返回接口能力列表。

2. 有笔记书籍

这个接口用于获取用户做过笔记的书籍。返回结果里会包含：

• 书籍数量

• 笔记数量

• 是否还有更多

• 翻页游标

• 书籍基本信息

• 笔记数量

• 划线数量

• 想法数量

这个接口是同步入口里非常重要的一环，因为它能告诉插件：哪些书是有必要同步的。

3. 书架数据

这个接口返回的是书架全量数据。结构上通常包含：

需要注意的是，books​ 里面普通书和公众号账号是混在一起的。公众号账号的 bookId​ 通常以 MP_WXS_​ 开头。

4. 普通书详情

常见返回字段包括：

• ​bookId​

• ​title​

• ​author​

• ​translator​

• ​cover​

• ​intro​

• ​publisher​

• ​publishTime​

• ​isbn​

• ​category​

• ​price​

• ​totalWords​

这个接口主要用于补全书籍元数据，比如书名、作者、ISBN、出版社、封面等。

5. 章节信息

返回结果通常包含章节列表，例如：

• ​chapterUid​

• ​chapterIdx​

• ​title​

• ​level​

• ​anchors​

章节信息主要用于把划线、想法归属到具体章节里。

公众号账号调用这个接口时可能为空，所以公众号同步不能依赖章节信息。

6. 个人划线

返回结果通常包含：

• 划线 ID

• 书籍 ID

• 章节 ID

• 划线文本

• 划线范围

• 创建时间

• 更新时间

普通书和公众号都可以用这个接口获取划线。但公众号文章有一个特殊点：有些纯划线数据里不一定直接带文章标题，需要通过其他接口补全。

7. 个人想法 / 书评

返回结果通常包含：

• ​reviewId​

• ​bookId​

• ​content​

• ​abstract​

• ​range​

• ​chapterUid​

• ​createTime​

• ​updateTime​

这个接口既用于普通书想法，也用于公众号文章想法。公众号文章里，refMpInfo​ 通常可以用于补充文章信息。

8. 单条想法详情

这个接口在公众号同步里很有用。因为有些公众号文章只有划线，没有想法，此时 /book/bookmarklist​ 里的信息可能不足以拿到完整文章标题。通过 /review/single​ 可以补充 mpInfo​，从而完善文章标题。

9. 热门划线

这个接口用于获取一本书中被很多人划线的内容。常见返回字段包括：

• ​items​

• ​markText​

• ​totalCount​

• ​chapterUid​

• ​range​

• ​chapters​

其中：

这个接口对应旧版里的热门划线能力，目前已经迁移到新接口模式中。

10. 搜索

这个接口可以用于查找微信读书里的书籍或公众号内容。返回结果通常包含：

• 书籍 ID

• 标题

• 作者

• 封面

• 类型

• 简介

11. 阅读统计

​/readdata/detail​ 支持不同统计周期：

返回结构里比较重要的字段包括：

这里有几个细节：

• ​readTimes​ 的 key 是时间戳字符串。

• ​readTimes​ 的 value 是秒。

• 周统计、月统计通常按日展示。

• 年统计通常按月展示。

• 总计通常按年展示。

• ​preferCategory​ 里包含分类名、阅读时长、阅读数量，可以用来做雷达图之类的可视化。

四、当前不使用的接口

虽然接口能力列表里可能能看到更多接口，但当前同步主线暂时不使用下面这些：

原因很简单：没有稳定需求时，不要为了“看起来能用”就盲目接入。每多一个接口，就多一份字段适配、异常处理和后续维护成本。

五、为什么要从 Cookie 切到 API Key

这次迁移的主要原因有几个。

1. 安全性更好

Cookie 本质上是登录态。让用户复制 Cookie，本身就比较敏感。
API Key 相对更适合作为接口访问凭证，边界更清楚，也更容易让用户理解：这是用于接口调用的 Key，而不是完整登录态。

2. 接口模式更稳定

旧 Web 接口依赖网页版结构。一旦微信读书前端或接口参数变化，插件就容易失效。
API Key 模式统一通过网关调用，接口边界更明确，维护起来更轻。

3. 代码结构更清晰

迁移后，数据来源统一成 API 接口。同步流程可以明确拆成：

1. 获取书籍列表

2. 获取书籍详情

3. 获取章节

4. 获取划线

5. 获取想法

6. 获取热门划线

7. 渲染模板

8. 写入笔记文档

这样比旧的 Cookie fallback 和多套数据来源混在一起更容易维护。

4. 更适合扩展

迁移到 API Key 之后，后面继续加功能会更自然，比如：

• 阅读统计

• 书架视图

• 公众号文章同步

• 新书确认

• 热门划线

• 本地文档匹配

• 阅读偏好分析

这些功能都更适合建立在统一接口数据层上。

5. 用户体验更好

以前 Cookie 失效后，用户往往不知道哪里出了问题。
现在可以直接验证 API Key，失败就是 Key 问题，成功就进入同步流程，错误边界更清晰。

六、迁移后的能力变化

迁移后，原本旧接口里的主要能力基本都保留了：

其中，公众号同步和阅读统计是新接口模式下更适合扩展的部分。