weread-shelf

微信读书 + DuckDB = 用 SQL 分析你的书架

CLI · SQL · MCP · Skill · 跨源 join 你的其他本地数据

为什么需要这个？

weread CLI 能查书、查笔记、查阅读时长 —— 但不能跨源 join。 你想知道"我最近 30 天加的 AI 书有哪些还没读？" weread 给不了 SQL 答案。

weread-shelf 把 weread 数据塞进 DuckDB，让你能：

-- 完读率按类别统计
SELECT category, COUNT(*), SUM(finishReading) AS read,
       ROUND(SUM(finishReading)*100.0/COUNT(*),1) AS pct
FROM shelf
GROUP BY 1 ORDER BY pct DESC;

-- 跨源：join 你机器上其他 db
ATTACH '~/xiaozhi/data/devices.db' AS xz (TYPE SQLITE);
SELECT b.title, b.finishReading, xz.last_active
FROM shelf b
LEFT JOIN xz.devices xz ON xz.user_id = b.bookId;

安装

pip install weread-shelf
# 或本地 clone
git clone https://github.com/flybear16/weread-shelf
cd weread-shelf && pip install -e .

前置：

• weread CLI 已装 (npm i -g weread-agent-cli)
• DuckDB ≥ 1.3（CLI 自带）

4 种使用方式

1. CLI 模板查询（无需写 SQL）

weread-shelf analysis                  # 全量画像
weread-shelf finish-rate --category   # 按类别完读率
weread-shelf recent --days 30         # 最近 30 天加的书
weread-shelf top-authors              # 高产作者
weread-shelf categories               # 类别饼图（ASCII）

2. 直通 SQL

weread-shelf sql "SELECT * FROM shelf WHERE finishReading=0 LIMIT 5"
weread-shelf sql --file ./my-query.sql

3. MCP Server（Agent 可调）

{
  "mcpServers": {
    "weread-shelf": {
      "command": "weread-shelf-mcp",
      "args": []
    }
  }
}

4. Skill（Hermes / Claude Code / OpenClaw）

npx openskills add flybear16/weread-shelf

命令速查

命令	作用
weread-shelf doctor	检查 weread CLI + DuckDB + auth
weread-shelf sync	拉取最新数据到本地 DuckDB
weread-shelf analysis	全量画像
weread-shelf sql <query>	直通 SQL
weread-shelf join <path>	Attach 一个外部 db
weread-shelf export --format parquet/csv/json	导出

License

MIT © flybear16

Security

weread-shelf never sees, stores, or transmits your WeRead API key.

• All authentication is delegated to the local weread CLI
• Your wrk-... key lives in ~/.weread-cli/config.json (managed by weread config set-key)
• weread-shelf only calls the public weread commands (shelf list, doctor, etc.)
• No key material is required or read by this project
• The local DuckDB cache at ~/.weread-shelf/cache.duckdb contains only your book metadata (titles, authors, categories, finish status) — never your key

If you fork this project, you don't need to add a key. Each user runs weread config set-key themselves on their own machine.

Reporting vulnerabilities: open a GitHub issue with [security] prefix, or email flybear16@outlook.com.