weread-shelf

WeRead-Shelf — SQL-ify your 微信读书

The local weread-shelf CLI is the entry point. It loads weread CLI's JSON export into a local DuckDB cache, then exposes SQL queries.

When to use

User says:

• "查我微信读书的 XX" / "我的书架" / "完读率" / "最近读了什么"
• "用 SQL 分析我的读书数据"
• "把 weread 和 XX db 关联起来" / "join weread"
• "我的读书画像 / 统计 / 报告"

Quick Start

# 0. Verify environment
weread-shelf doctor

# 1. Pull latest shelf into DuckDB
weread-shelf sync

# 2. Run preset analysis
weread-shelf analysis

# 3. Custom SQL
weread-shelf sql "SELECT category, COUNT(*) FROM shelf GROUP BY 1 ORDER BY 2 DESC"

# 4. Cross-source join (e.g. attach xiaozhi device db)
weread-shelf join xz /path/to/xiaozhi.db
weread-shelf sql "SELECT s.title, x.last_active FROM shelf s LEFT JOIN xz.devices x ON x.user_id = s.book_id"

Pre-built Queries

Available via weread-shelf <command>:

Command	Returns
analysis	Full portrait (overall + by-category + recent + top authors)
sql "<query>"	Arbitrary SQL
export <path> --format parquet|csv|json	Dump shelf
join <alias> <path>	Attach external SQLite

The internal shelf table schema:

shelf (
    book_id         VARCHAR PRIMARY KEY,
    title           VARCHAR NOT NULL,
    author          VARCHAR,
    category        VARCHAR,    -- e.g. '经济理财-管理'
    finish_reading  INTEGER,    -- 0 or 1
    read_update_at  TIMESTAMP,
    update_at       TIMESTAMP,
    cover           VARCHAR,
    deep_link       VARCHAR
)

Cross-source Join

weread-shelf join <alias> <path-to-sqlite> attaches any local SQLite db.

Common join keys:

• bookId ↔ user-id in app DBs (xiaozhi, sbti-tools etc.)
• title ↔ product-name (lowercased match)
• category ↔ tag

Rules

1. Always run sync first if the user added new books since last query.
2. Prefer preset queries over raw SQL for simple metrics — they encode domain knowledge (e.g. category is '-'-delimited).
3. For agent use, prefer sql with structured JSON output: weread-shelf sql "..." --format json --output /tmp/result.json
4. Cache file is local at ~/.weread-shelf/cache.duckdb. Safe to delete for a fresh re-sync.
5. Never write to shelf from MCP/SQL — read-only by design. To refresh, run weread-shelf sync.