# weread-shelf

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

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

[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![DuckDB](https://img.shields.io/badge/DuckDB-1.3+-yellow.svg)](https://duckdb.org)

## 为什么需要这个？

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

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

```sql
-- 完读率按类别统计
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;
```

## 安装

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

**前置**：
- [weread CLI](https://github.com/Tencent/WeChatReading) 已装 (`npm i -g weread-agent-cli`)
- DuckDB ≥ 1.3（CLI 自带）

## 4 种使用方式

### 1. CLI 模板查询（无需写 SQL）
```bash
weread-shelf analysis                  # 全量画像
weread-shelf finish-rate --category   # 按类别完读率
weread-shelf recent --days 30         # 最近 30 天加的书
weread-shelf top-authors              # 高产作者
weread-shelf categories               # 类别饼图（ASCII）
```

### 2. 直通 SQL
```bash
weread-shelf sql "SELECT * FROM shelf WHERE finishReading=0 LIMIT 5"
weread-shelf sql --file ./my-query.sql
```

### 3. MCP Server（Agent 可调）
```json
{
  "mcpServers": {
    "weread-shelf": {
      "command": "weread-shelf-mcp",
      "args": []
    }
  }
}
```

### 4. Skill（Hermes / Claude Code / OpenClaw）
```bash
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.