微信读书 API 接口

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

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

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

一、旧方案：Cookie + Web 接口

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

用户提供微信读书 Cookie。
插件通过代理请求微信读书 Web 接口。
接口返回书籍、划线、评论、章节等数据。
再把这些数据整理成笔记文档。

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

Cookie 有过期风险，也有隐私风险；
Web 接口不稳定；
有些接口还需要特殊方式绕过浏览器环境限制。

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

旧接口大致包括

旧接口	作用
https://weread.qq.com/api/user/notebook	获取有笔记的书籍列表
https://weread.qq.com/web/book/info?bookId=xxx	获取书籍详情
https://weread.qq.com/web/shelf/sync	获取书架数据
https://weread.qq.com/web/book/bookmarklist?bookId=xxx	获取个人划线
https://weread.qq.com/web/review/list	获取评论、想法、书评
https://weread.qq.com/web/book/bestbookmarks?bookId=xxx	获取热门划线
https://weread.qq.com/web/book/chapterInfos	获取章节信息

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

书籍列表
书籍详情
章节列表
个人划线
个人想法 / 书评
热门划线
书架数据

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

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

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

API Key 申请入口：

微信读书 AI 助手

连接你的微信读书账号，用 AI 搜书、查笔记、看书评、分析阅读数据

weread.qq.com

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

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

项目	说明
请求方式	POST
请求入口	https://weread.qq.com/api/agent/gateway
鉴权方式	Authorization: Bearer {API Key}
参数形式	参数直接放在请求体顶层
必带字段	api_name、skill_version
当前版本字段	skill_version: "1.0.3"

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

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

字段	说明
api_name	接口名称，例如 /book/info
bookId	书籍 ID
skill_version	接口协议版本

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

三、当前主要接口清单

1. API Key 验证

接口	作用
/_list	验证 API Key 是否可用，并查看可调用接口能力

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

2. 有笔记书籍

接口	作用
/user/notebooks	获取有笔记的书籍列表

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

书籍数量
笔记数量
是否还有更多
翻页游标
书籍基本信息
笔记数量
划线数量
想法数量

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

3. 书架数据

接口	作用
/shelf/sync	获取微信读书书架数据

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

字段	说明
books	书架里的书籍和公众号账号
mp	收藏或文章相关入口
albums	专辑数据
archive	归档数据

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

4. 普通书详情

接口	作用
/book/info	获取书籍详情

常见返回字段包括：

bookId
title
author
translator
cover
intro
publisher
publishTime
isbn
category
price
totalWords

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

5. 章节信息

接口	作用
/book/chapterinfo	获取普通书章节信息

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

chapterUid
chapterIdx
title
level
anchors

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

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

6. 个人划线

接口	作用
/book/bookmarklist	获取个人划线

返回结果通常包含：

划线 ID
书籍 ID
章节 ID
划线文本
划线范围
创建时间
更新时间

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

7. 个人想法 / 书评

接口	作用
/review/list/mine	获取个人想法、书评、评论

返回结果通常包含：

reviewId
bookId
content
abstract
range
chapterUid
createTime
updateTime

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

8. 单条想法详情

接口	作用
/review/single	获取单条想法 / 评论详情

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

9. 热门划线

接口	作用
/book/bestbookmarks	获取热门划线

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

items
markText
totalCount
chapterUid
range
chapters

其中：

字段	说明
markText	热门划线文本
totalCount	有多少人划过
chapterUid	所属章节
range	划线范围

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

10. 搜索

接口	作用
/store/search	搜索书籍、公众号账号、公众号文章

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

书籍 ID
标题
作者
封面
类型
简介

11. 阅读统计

接口	作用
/readdata/detail	获取阅读统计
/shelf/sync	辅助统计书架条目

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

mode	含义
weekly	本周
monthly	本月
annually	本年
overall	总计

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

字段	说明
totalReadTime	总阅读时长，单位秒
dayAverageReadTime	日均阅读时长，单位秒
readDays	阅读天数
readTimes	按时间聚合的阅读时长
readLongest	阅读时间较长的书
readStat	阅读分布统计
preferCategory	偏好分类

这里有几个细节：

readTimes 的 key 是时间戳字符串。
readTimes 的 value 是秒。
周统计、月统计通常按日展示。
年统计通常按月展示。
总计通常按年展示。
preferCategory 里包含分类名、阅读时长、阅读数量，可以用来做雷达图之类的可视化。

四、当前不使用的接口

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

接口	当前状态
/book/getprogress	暂不使用
/book/underlines	暂不使用
/book/readreviews	暂不使用

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

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

1. 安全性更好

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

2. 接口模式更稳定

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

3. 代码结构更清晰

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

获取书籍列表
获取书籍详情
获取章节
获取划线
获取想法
获取热门划线
渲染模板
写入笔记文档

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

4. 更适合扩展

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

阅读统计
书架视图
公众号文章同步
新书确认
热门划线
本地文档匹配
阅读偏好分析

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

5. 用户体验更好

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

六、迁移后的能力变化

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

能力	当前状态
有笔记书籍	已支持
普通书同步	已支持
划线同步	已支持
想法 / 书评同步	已支持
热门划线	已支持
书架数据	已支持
公众号账号同步	已支持
公众号文章标题补全	已支持
阅读统计	已支持
AI 总结	官方 API 暂不提供，不再支持

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