WeRead — 微信读书助手

通过 scripts/weread.py CLI 调用微信读书接口，提供搜索、书架、笔记、书评等能力。

强制性规则：所有微信读书操作必须通过 CLI 完成，禁止手写 curl 或直接调 API。CLI 已内置鉴权、版本上报、分页、格式化输出、深度链接等所有逻辑。

需要 WEREAD_API_KEY 环境变量（从微信读书抓包获取 sk 值）。

快速参考

WR=./scripts/weread.py

# 搜索
$WR search <关键词> [--scope 10] [--page 1] [--per-page 10]

# 书架
$WR shelf [--page 1] [--per-page 10]

# 书籍详情 + 进度 + 目录
$WR book <bookId> [--progress] [--chapters] [--chapters-page 1]

# 笔记划分 — 概览 或 单本书
$WR notes [--book <bookId>] [--page 1] [--per-page 10] [--max-pages 5]

# 阅读统计
$WR readdata [--mode monthly|weekly|annually|overall] [--time 0]

# 公开点评
$WR review <bookId> [--type 0] [--per-page 10]

# 推荐发现 — 为你推荐 或 相似书
$WR discover [--book <bookId>] [--per-page 10]

子命令详解

search — 搜索书籍

$WR search 三体                           # 默认电子书 scope=10
$WR search 三体 --scope 0                  # 综合搜索
$WR search 三体 --scope 16                 # 网文小说
$WR search 三体 --scope 14                 # 有声书
$WR search 三体 --scope 6                  # 作者
$WR search 三体 --per-page 5 --page 2      # 分页

scope 选择指引详见 references/search.md。CLI 输出包含书名、作者、评分、在读人数、简介、weread:// 打开链接。

shelf — 书架

$WR shelf --per-page 5 --page 1

输出包含：总条目数（books + albums + mp）、公开/私密统计、每本书的类型标记（📖电子书/🎧有声书）、最近阅读时间、置顶/读完/私密标记、weread:// 链接。

book — 书籍详情

$WR book 695233                             # 基本信息
$WR book 695233 --progress                  # 含阅读进度
$WR book 695233 --chapters                  # 含章节目录
$WR book 695233 --progress --chapters       # 全部

CLI 已处理：评分 0-1000→百分制、字数→万字、时间戳→YYYY-MM-DD、阅读时长→X小时Y分钟。

notes — 笔记划线

$WR notes                                   # 笔记本概览 (所有有笔记的书，按笔记数排序)
$WR notes --per-page 10 --page 1            # 分页
$WR notes --max-pages 10                    # 拉更多页 (默认5页=250本)
$WR notes --book 695233                     # 单本书笔记：划线 + 个人想法
$WR notes --book 695233 --page 1 --per-page 5

概览输出：书名、作者、阅读进度、笔记总数（想法+划线+书签）、weread:// 链接。 单本书输出：划线内容（按章节分组，附带位置链接）、个人想法/点评。

readdata — 阅读统计

$WR readdata                                # 本月 (默认)
$WR readdata --mode weekly                  # 本周
$WR readdata --mode annually                # 本年
$WR readdata --mode overall                 # 总计
$WR readdata --mode monthly --time 1735689600  # 历史月份

输出：阅读天数、总时长、日均时长、与上期对比、读过/读完/笔记数、读得最多的书 TOP5、偏好分类/时段/作者。

review — 书籍点评

$WR review <bookId>                         # 全部点评
$WR review <bookId> --type 1                # 推荐 (1=推荐 2=不行 3=最新 4=一般)
$WR review <bookId> --per-page 5

输出：点评总数、资深会员推荐比例、每条点评（昵称、星级、内容摘要）。

discover — 发现推荐

$WR discover                                # 为你推荐
$WR discover --book <bookId>                # 基于此书的相似推荐
$WR discover --per-page 5

CLI 无法满足需求时：临时 Python 脚本

当现有 CLI 子命令不覆盖所需功能时，可以编写临时 Python 脚本直接调用 api.py 模块。api.py 封装了所有接口，内置认证和版本上报。

流程：

1. 查阅 references/ 下的文档了解接口结构和字段含义
2. 阅读 scripts/api.py 确认可用的函数和签名
3. 编写一个一次性 Python 脚本，import api 模块并调用对应函数
4. 运行：cd scripts && python3 -c "..." 或写入 /tmp/weread_temp.py

示例 — 获取用户主页信息（CLI 尚未封装此功能）：

cd scripts && python3 -c "
import api, json
result = api.get_profile()
print(json.dumps(result, indent=2, ensure_ascii=False))
"

注意事项：

• 临时脚本无需持久化，用完即弃
• 如发现该功能被反复使用，考虑将其加入 CLI 子命令
• 始终先检查 CLI 是否已支持该功能，避免重复实现

Agent 工作流规则

1. CLI 优先：始终使用 $WR <command> 而非 curl/API 直调。CLI 已处理版本上报 skill_version、鉴权、errcode 检测、upgrade_info 处理。
2. bookId 记忆：对话中记住首次查到的 bookId，后续操作无需用户重复提供书名。
3. 分页控制篇幅：默认 --per-page 10，数据量大时加 --page N 翻页，避免刷屏。
4. 书名查 bookId：用户给书名时先 $WR search <书名> 拿到 bookId，再进行后续操作。
5. 书架数量口诀：books.length + albums.length + (mp非空?1:0) — CLI 已内置此逻辑。
6. 阅读统计单位：CLI 自动将秒转为小时/分钟，时间戳转为日期，评分 0-1000 转为百分制。
7. 故障处理：CLI 报错时检查 WEREAD_API_KEY 是否有效；若遇 upgrade_info 提示，按指引升级。

参考文档

以下文件记录了各接口的字段含义、概念口径和工作流细节（CLI 已实现，仅作理解参考）：

已知 Pitfalls（API 与数据）

从开发过程中发现的陷阱，CLI 已处理但理解 API 行为时需知：

CLI 开发

脚本：scripts/weread.py（主 CLI）、scripts/api.py（API 封装）、scripts/test_weread.py（单元测试）。

运行测试：cd scripts && python3 test_weread.py