weread-vault 0.2.1

A local-first CLI and web preview for WeRead notes

WeRead Vault

微信读书的本地数据库 —— 一个带 Agent Skill 的 CLI。 把书架、划线、想法、阅读统计归档进本机 SQLite，可查询、可视化、可导出，AI 直接读，数据不上传。

个人数据归档工具，不是微信读书官方客户端。请遵守微信读书服务条款，只同步自己的数据。

特点

• 🔒 本地优先：所有数据只存在本机一个 SQLite 文件里，可备份、可迁移、可离线，永远不上传；网页只监听 127.0.0.1。
• 📚 完整书架：同步整个书架（含无笔记的书；公众号单独归类），不只是有笔记的那一部分。
• 📊 阅读统计看板：纯 SVG 零依赖渲染——本周/本月/今年/全部切换、同比、读得最多排行、偏好分类、24 小时时段、GitHub 式划线热力图、单次时长分布（还给「碎片化严重」这样的结论）。
• 🔥 不只是你自己：每本书能看「大家都在划的句子」（含人数、可按原文顺序）和公开书评；还能搜微信读书书城、看同作者的相关书。
• 🤖 AI 原生：CLI 暴露整套微信读书 API + 只读 SQL 查询 + 已解析统计 JSON，可直接交给 Claude Code、Codex、OpenClaw 等 agent；自带荐书 Skill。
• 📝 导出到你的知识库：Markdown（含封面、可合并他人热门划线并去重）、Obsidian、flomo、Notion。
• 🧰 零第三方依赖：纯 Python 标准库 + SQLite，有 Python 就能跑。

安装

最简单：下载安装包，无需 git clone。 到 Releases 下载：

• macOS：weread-vault-macos.dmg —— 打开后把 WeRead Vault.app 拖进「应用程序」，双击启动。
• Windows：weread-vault-windows.exe —— 双击启动。

启动后浏览器自动打开，在「同步设置」粘贴微信读书 API Key（从这里获取），点「同步」即可。

首次打开系统会提示「未签名」（没做付费签名公证，正常现象）：macOS 右键 App →「打开」→「打开」；Windows 点「更多信息」→「仍要运行」。一次即可。

想在终端也用 weread-vault 命令？macOS 用户可在 App 网页的「同步设置」里点「注册 weread-vault 命令」一键链接到 PATH（无需 sudo），或直接用下面的 pipx / uvx。

命令行（需 Python 3.10+）：

uvx weread-vault serve --open     # 免安装，临时环境直接跑
pipx install weread-vault         # 或常驻安装

让 AI agent 帮你装（Claude Code / Codex / OpenClaw 等）：

请用 pipx 安装并运行 WeRead Vault：pipx install weread-vault && weread-vault serve --open
打开网页后提醒我去 https://weread.qq.com/r/weread-skills 获取微信读书 API Key 粘贴同步。
数据只存我本机，别把 key 写进任何文件。

agent 若支持 Skill，可装本仓库的 skills/weread-vault-cli。

从源码（开发或兜底）：

git clone --recurse-submodules https://github.com/dull-bird/weread-vault.git
cd weread-vault && pip install -e .
weread-vault serve --open

升级：weread-vault update 检查新版，weread-vault update --download 下载安装包。安装包由 GitHub Actions 在打 v* tag 时自动构建。项目主页：https://dull-bird.github.io/weread-vault/。

阅读统计

按本周 / 本月 / 今年 / 全部切换，所有数字随之更新；GitHub 式热力图展示每日划线活跃度（多年）。全部来自历史快照，随每次同步累积，能看到长期趋势。

书籍详情

进度与推荐值用进度条体现书间差异，划线/想法用颜色标记。四个 tab：我的笔记 / 热门划线 / 书评 / 相关推荐——每条笔记都能一键复制，还能跳转到微信读书。

热门划线可按「原文顺序」或「按热度」排列，看到大家都在划的句子（含人数）：

常用命令

weread-vault sync                  # 日常增量同步（书架 + 笔记 + 统计）
weread-vault sync info             # 补全评分/字数/出版社/ISBN（一次性回填）
weread-vault status                # 本地库数量与最近同步状态
weread-vault serve --open          # 本地网页预览

# 导出
weread-vault export markdown --out ~/Documents/weread-notes
weread-vault sync popular && \
  weread-vault export markdown --out ~/Documents/weread-notes --with-popular   # 合并他人热门划线（去重）
weread-vault export flomo --webhook "$FLOMO_WEBHOOK"
weread-vault export notion --token "$NOTION_TOKEN" --database "$NOTION_DATABASE_ID"

# 备份 / 换账号
weread-vault backup --out ~/Backups/weread-vault.db
weread-vault reset --yes           # 清空本地阅读数据（换账号前用，不影响 API Key）

所有命令可加 --db /path/to/file.db 使用另一份数据库（不同账号开独立库，避免串扰）。

给 AI agent 的微信读书 API

CLI 把整套微信读书 Skill API 暴露成命令，输出 JSON，让 agent 直接取数据——书城搜索、他人热门划线、公开书评、富书籍信息等：

weread-vault apis                       # 列出全部接口及参数（agent 自助发现）
weread-vault search "三体" --count 5     # 书城搜索
weread-vault book <bookId> popular      # 他人热门划线（含人数）
weread-vault book <bookId> reviews      # 公开书评
weread-vault api <endpoint> key=value   # 任意接口原样透传

让 AI 灵活分析本地数据：

weread-vault query --schema     # 表结构 + 字段说明 + 示例 SQL（AI 据此写查询）
weread-vault query "SELECT title, rating FROM books WHERE rating>0 ORDER BY rating DESC LIMIT 10"
weread-vault stats              # 已解析统计 JSON（周期 / 热力图 / 单次时长 / 读得最多）

接入 Claude Code 后，问「我评分最高的书」「哪个分类笔记最多」，AI 会自己 query --schema 再写 SQL 回答。荐书 Skill skills/weread-recommend 会结合你的口味、书城和联网，按主题推荐不与已读重复的书。

一个具体例子 —— 你问「这周读得最久的书是哪本？」AI 会这样做（完整说明见 SKILL.md）：

1. 判断：阅读时长不在 SQL 表里，在统计快照里 → 用 weread-vault stats（不是 query）。
2. 跑 weread-vault stats，读返回 JSON 的 periods.weekly.longest[0]：

   { "title": "财富的真相", "author": "李笑来", "readSeconds": 916 }
   

3. 答你：「这周读得最久的是《财富的真相》（李笑来），约 15 分钟。」

（「笔记最多/评分最高的书」这类目录问题才转 query 写 SQL。选对工具是关键。）

官方接口不开放全书正文，「划线前后那一整段原文」拿不到；也不提供「某一年每本书读了多久」。这些限制我们如实标注，不虚构数据。

OpenClaw 定时同步

用 OpenClaw cron 每天唤起一个隔离任务，让 agent 跑同步并导出到 Obsidian：

{
  "name": "weread-vault daily sync",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "先读取 ~/.weread.env 获取 WEREAD_API_KEY，在 ~/projects/weread-vault 运行 weread-vault sync，成功后 weread-vault export markdown --out \"~/Documents/Obsidian Vault/微信读书\"。失败保留日志，不要打印 API Key。",
    "timeoutSeconds": 1800
  },
  "delivery": { "mode": "announce" }
}

同步是怎样保证安全的

weread-vault sync 分段进行：分页拉取书目并记录每本书的远端变更标记；只同步新增/有变更的书，每本书的划线和想法先完整拉取、两类请求都成功后才用一个 SQLite 事务写入并推进标记——失败的书不标记「已同步」，下次自动重试；阅读统计按时间快照保存，不覆盖旧快照。

vendor/tencent-weread-skill 是腾讯 Tencent/WeChatReading 的 submodule。更新官方协议：./scripts/update-official-skill.sh，审阅后再升级 SKILL_VERSION 并跑测试。

开发与测试

python -m unittest discover -s tests -v

License

MIT