#Agent#AI#数字花园

把微信读书接进我的数字花园

官方 Agent 网关实战：拿 Key、调网关、把划线和想法按原文配对，再加一套防覆盖的同步设计——脚本可直接抄。

种下2026/07/15 约6 分钟 常青

这个站的书架板块，最早是我手写的几本假书。做着做着就觉得不对：我真正的阅读痕迹——那些深夜划下的线、页边冒出来的念头——全在微信读书里沉睡，而网站上摆着一排手工维护的书皮，像在书房里挂了一幅《书架》的静物画。

画得再像，也不会翻页。我想要的是书架本身：读到哪、划了什么、当时想了什么，原样长到网站上来。

官方终于开门了

以前想拿到微信读书的数据，只有一条路：登录网页版，把 Cookie 抠出来喂给第三方脚本。能用，但 Cookie 时效短、接口随时会变，整个管线立在”官方懒得管你”的默许上。

今年 5 月，微信读书发布了官方 Agent Skill——一个用个人 API Key 鉴权的 Agent 网关，把书架、阅读进度、划线、想法这些数据正式开放给了 AI 客户端。拿 Key 的过程简单到不像腾讯系产品：去 weread.qq.com/r/weread-skills 扫码登录，就能领到一枚 wrk- 开头的 Key。

从被爬到发钥匙，这个转变本身比接口更值得琢磨——App 生态对 Agent 的态度正在拐弯。这个话题够单独写一篇，这里先按住不表。

网关只有一个入口

所有能力走同一个 endpoint，用 api_name 区分：

curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
  -H "Authorization: Bearer $WEREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_name": "/user/notebooks", "count": 20, "skill_version": "1.0.4"}'

两个容易踩的规矩：业务参数必须平铺在 JSON 顶层，包一层 params 后端就收不到；分页走 count + lastSort 游标，传 offset/limit 不会报错，只会安静地给你错误的结果。

skill_version 是个有意思的设计：版本过旧时，网关不报错，而是在回包里塞一个 upgrade_info，指向最新接口文档的下载地址。文档跟着协议走，工具自己告诉你怎么升级——这是为 Agent 设计的接口，不是为人。

三个接口就够了

  • /shelf/sync：完整书架。包括自己导入的 epub（CB_ 开头的 bookId），每本都有封面 URL 和”私密阅读”标记。
  • /user/notebooks：所有写过笔记的书。注意口径：noteCount 不是笔记总数，是划线条数；想法和点评在 reviewCount 里。
  • /book/bookmarklist + /review/list/mine：单本书的划线内容和想法内容。

最关键的配对逻辑在最后这对接口上。划线带着 range（原文位置），而每条想法自带一个 abstract 字段——它评论的那段原文。用 range 一对，“划线 + 挂在划线下的想法”这个结构就原样复原了：

const byRange = new Map(reviews.filter(r => r.range).map(r => [r.range, r]));
const notes = highlights.map(m => ({
  chapter: chapterName.get(m.chapterUid),
  highlight: m.markText,
  thought: byRange.get(m.range)?.content,  // 同一段原文上的想法
}));

挂不上划线的（章节点评、整本书评）单独成条。整个数据模型里我最喜欢的就是 abstract 这个字段——它保住了”想法是对着哪句话说的”这层语境，而语境正是读书笔记和金句摘抄的区别。

数据归机器，品味归自己

同步脚本（一个百来行的 Node 脚本，零依赖）的核心不是拉数据，是合并规则：

  • 脚本维护：书名、作者、封面、进度、划线与想法
  • 人工保留：评分、读后感正文、书封色——同步永不覆盖
  • preserveNotes：手工补录的老书（在纸书上读完的那些）打上这个标记，不会被”接口里没笔记”的空同步冲掉

文件按 frontmatter 里的 wereadId 匹配，文件名随便改。封面顺手下载到本地托管——导入书的封面是微信读书解析 epub 时提取的，URL 会 302 到带签名的临时地址，跟着重定向走一次就好，别做热链。

于是日常只剩下三个动作：读书，划线，写想法。 剩下的交给一句 node scripts/sync-weread.mjs——像给花园浇一次水。

踩过的坑，替你踩了

  • /review/list/mine 的参数是小写 bookid，隔壁 /book/bookmarklist 却是驼峰 bookId。别问，问就是历史。
  • 私密阅读的书也会从接口返回（带 secret: 1）。App 里的”私密”挡的是书友，不是你自己——要不要公开到网站，得自己再做一次决定。
  • /book/bookmarklist 已经滤掉了书签（type=0），返回的都是划线，不用自己再筛。
  • Key 放 .env，进 .gitignore。它能读你的完整阅读记录，别提交到仓库里。

尾声

现在，每当我在深夜里划下一道线、写下一句想法，它们不再沉进 App 的深处。同步一次，推送一次——第二天清晨，它们已经安安静静地长在这座花园里，带着章节的名字，和那一晚的日期。

书架的副标题是这么写的：“书页翻过，划线留下。那些未完的念头，也在这里慢慢生长。”

写下它的时候，是愿景。现在，它只是每天都在发生的事。