思考

微信读书接入Family Garden

2026年8月7日2 分钟阅读
#design#family garden

微信读书数据接入（Family Garden）

本文档描述 Family Garden 如何通过微信读书官方 API Gateway 同步阅读数据，包括接口说明、脚本实现、数据文件结构、增量同步机制与使用方式。

目录

1. 总览

阅读数据通过微信读书官方 API Gateway 拉取，不再解析 Obsidian / WeRead 导出 Markdown。数据以结构化 JSON 输出到 src/content-data/weread/，由 Astro 直接消费。

  • 官方统一入口，鉴权简单
  • 返回字段完整（封面、作者、划线、想法、统计等）
  • 数据按官方分层，Astro 无需自己维护结构
  • 支持增量同步，避免每次全量拉取

2. API Gateway

  • 入口：POST https://i.weread.qq.com/api/agent/gateway
  • 鉴权：Authorization: Bearer WEREAD_API_KEY
  • 请求体格式：
{
  "skill_version": "1.0.4",
  "api_name": "shelf/sync"
}

所有接口共用同一入口，仅 api_name 与参数不同。

3. 核心接口

接口 说明 用途
shelf/sync 完整书架（电子书 + 有声书） 首页、最近阅读
user/notebooks 有笔记的书籍列表 阅读资产分类
book/bookmarklist 单本书全部划线 划线正文
review/list/mine 我的想法/点评 阅读心得
readdata/detail 阅读统计（周/月/年/总体） 统计页
book/info 书籍详情 备用
book/getprogress 阅读进度 备用
store/search 搜索书籍 备用

注意：所有阅读时间的单位均为秒。

4. 脚本结构

脚本 说明
scripts/weread_client.py API Gateway 统一封装，自动读取 WEREAD_API_KEY
scripts/collect-weread.py 同步脚本（增量优先），生成 src/content-data/weread/ 数据

4.1 weread_client.py

  • 从根目录 .env（已 gitignore）或环境变量读取 WEREAD_API_KEY，环境变量优先级更高
  • 核心类 WeReadClient，方法对应上述接口（shelf()、bookmark_list()、reading_stats() 等）
  • get_all_notebooks() / get_all_reviews() 自动翻页拉取全量

4.2 collect-weread.py

分 5 个阶段：

  1. sync_shelf — 书架（全量，1 次调用）
  2. sync_notes — 划线（增量）
  3. sync_reviews — 个人想法（增量）
  4. sync_stats — 阅读统计（全量，4 次调用）
  5. sync_latest — 最近阅读（复用 notes 数据，不额外调用接口）

5. 数据文件

输出目录：src/content-data/weread/

文件 说明
shelf.json 完整书架（电子书 + 有声书）
notes.json 全部划线，按书组织
reviews.json 全部个人想法/点评
stats.json 阅读统计（总体/年/月/周）
latest.json 最近阅读（兼容原 reading.json 格式）
sync-meta.json 增量同步元数据（每本书的变化指纹）

6. 同步机制

6.1 为什么需要增量

notes / reviews 每本书都要一次 API 调用，是成本大头。全量拉取时的开销：

  • notes：每本有笔记的书全量拉划线（约 248 本 ≈ 248 次调用）
  • reviews：每本有想法的书全量拉想法（约 109 次调用）
  • latest：最近 30 本再各拉一次划线

一次完整运行约 400 次 API 调用。

6.2 增量策略

  • shelf / stats 调用次数固定（1 + 4 次），始终全量

  • 每本书记录变化指纹：

    [readUpdateTime, reviewCount, noteCount, bookmarkCount]

    存入 sync-meta.json

  • notes / reviews 只重拉指纹变化的书，其余沿用上次数据

  • latest 直接复用 notes.json 的划线，不再调用接口

每轮同步降到：约 8 次固定调用 + 仅变化书目的拉取。

6.3 关键点

  • 指纹包含 bookmarkCount / reviewCount，新增划线、想法即使 readUpdateTime 未变也能被检测到
  • 单本书的划线整本替换，不会新旧混杂
  • 书被移除时自动从输出中删除
  • 拉取失败的书沿用旧数据，不会清空
  • 首次运行（无 sync-meta.json）自动全量

7. 使用说明

7.1 配置

推荐把 WEREAD_API_KEY 写入根目录 .env（已 gitignore）：

WEREAD_API_KEY=wrk-xxxxxx

7.2 运行

# 增量同步（默认）
python scripts/collect-weread.py

# 强制全量重拉 notes/reviews
python scripts/collect-weread.py --force

# 或临时用环境变量（Windows PowerShell）
set WEREAD_API_KEY=wrk-xxxxxx && python scripts/collect-weread.py

首次运行会自动全量拉取并生成 sync-meta.json。

8. 前端适配

  • LatestActivity.astro — 优先读取 weread/latest.json，回退到 reading.json
  • archiveStats.ts — 同上