mcpField
W
weread

weread

github.com/shiquda生产力24389 次安装14 周前更新
代码仓库

关于 weread

这是一份指导 Agent 使用本地 WeRead 命令行的技能，涵盖图书搜索、阅读数据和笔记处理。它强调 JSON 输出、规范化错误，并按需加载详细参考资料。

主要功能

  1. 01检查命令行状态与身份验证
  2. 02搜索图书和阅读内容
  3. 03获取书架与阅读统计
  4. 04查看笔记、划线和书评
  5. 05将笔记导出为 Markdown

适用场景

  1. 01按书名或内容查找图书
  2. 02查看阅读进度和统计数据
  3. 03导出并总结个人笔记

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shiquda/weread-cli --skill weread

安装后在 Claude Code 中输入/weread确认已加载。

附带文件references/domain-rules.mdreferences/first-use.md

详细介绍

微信读书

本地 weread CLI 是你需要的唯一接口。它会处理身份验证、请求格式、skill_version、JSON 解析、升级检查和规范化错误——如果自行编写 curl 请求，就必须重新实现这些功能，还会失去规范化错误层。

Agent 默认应使用 --json。仅当用户明确需要可在终端中阅读的命令输出时，才使用人类可读格式。

对于书架、笔记本、书签或导出等大型输出，先将 JSON 或 Markdown 写入文件，再在聊天中概述结果。不要在对话中粘贴完整的大型 JSON 数据或完整的导出笔记。

对于 notes export，默认使用 --output <path>。仅当用户明确要求在对话中查看完整导出内容时，才将导出内容流式输出到 stdout。

首要判断

开始任何微信读书操作前，检查身份验证状态和 CLI 是否正常：

weread doctor

如果缺少 weread 命令，或 auth_configured 为 false，请阅读 references/first-use.md 并引导用户完成设置。

命令速查

weread search "三体" --scope book --count 10
weread book resolve "三体" --limit 5
weread book info <bookId>
weread book chapters <bookId>
weread book progress <bookId>
weread shelf list
weread shelf recent --limit 10
weread readdata detail --mode monthly
weread readdata summary --mode monthly
weread notes notebooks --count 100
weread notes top --limit 20
weread notes bookmarks <bookId>
weread notes export <bookId> --format markdown --output notes.md
weread notes mine <bookId> --count 20
weread notes underlines <bookId> <chapterUid>
weread notes best <bookId> --chapter-uid <chapterUid>
weread notes readreviews <bookId> <chapterUid> --reviews-json '[{"range":"900-2004","count":20}]'
weread reviews list <bookId> --type 1 --count 20
weread reviews single <reviewId>
weread discover recommend --count 12
weread discover similar <bookId> --count 12
weread discover friends --count 20
weread api list

如果受支持的 API 没有对应的专用命令，请使用原始请求接口：

weread api call /store/search --param keyword=三体 --param scope=10

何时阅读参考资料

按需加载参考资料，以减少启动时的上下文占用。仅在任务需要时加载：

  • 首次设置、缺少身份验证或有关 API Key 的问题：阅读 references/first-use.md
  • 书架总数、公开／私密数量、有声书或文章合集处理：阅读 references/domain-rules.md
  • 笔记、划线、书签、个人想法、公开书评或导出：阅读 references/domain-rules.md
  • 阅读统计、历史时间段、跨年范围或时间单位解释：阅读 references/domain-rules.md
  • 图书、章节、划线或想法的深层链接：阅读 references/domain-rules.md

意图路由

搜索
  • 查找图书、获取 bookId，或用户说 搜书／找书：weread search "<keyword>" --scope book
  • 泛指“搜一下”或意图混杂：--scope all
  • 网络小说或 网文：--scope fiction
  • 有声读物、播客、听书、有声书 或 专辑：--scope audio
  • 作者：--scope author
  • 全文搜索或用户说“书里提到”：--scope fulltext
  • 书单：--scope list
  • 公众号：--scope mp
  • 文章：--scope article
图书详情

如果用户提供的是书名而不是 ID，优先使用 weread --json book resolve "<title>" --limit 5，并使用 items[].bookId。

  • 元数据：book info
  • 章节 UID（按章节获取笔记／划线时需要）：book chapters
  • 阅读进度：book progress——progress 是整数百分比；1 表示 1%，只有 100 表示已读完
书架

使用 weread --json shelf list。查看最近阅读时，使用 weread --json shelf recent --limit 10。涉及较复杂的情况（公开／私密分类、有声书处理）时，阅读 references/domain-rules.md。

阅读统计

常见统计使用 weread --json readdata summary --mode monthly；也可以使用 weread --json readdata detail，并设置 --mode weekly、monthly、annually 或 overall。结构化输出中的时间字段单位为秒。进行历史或跨时间段计算时，阅读 references/domain-rules.md。

笔记和划线
  • 查看所有图书的概览：weread --json notes notebooks
  • 查看个人笔记／划线最多的图书：weread --json notes top --limit 20
  • 导出单本图书：weread notes export <bookId> --format markdown --output <path>；选择本地 Markdown 路径，并概述数量／内容，不要粘贴整个文件
  • 如果要手动合并数据，同时使用 weread --json notes bookmarks <bookId> 和 weread --json notes mine <bookId>
  • 涉及计数规则、导出限制或热门划线查询时，阅读 references/domain-rules.md
书评

公开书评：weread --json reviews list <bookId>，其中 --type 可取 0（全部）至 4。查看单条书评：weread --json reviews single <reviewId>。

推荐
  • 个性化推荐：weread --json discover recommend
  • 相似图书：weread --json discover similar <bookId>
  • 好友的阅读动态：weread --json discover friends；继续获取时，将 nextMaxIdx 作为 --max-idx 传入，刷新时重复使用 synckey

分页

默认只获取少量结果——只有当用户明确要求完整导出、排名或需要遍历所有页面才能得出的总数时，才继续分页。使用 --limit 设置显示数量，并在支持时使用 --all。手动分页时，使用 --json，并传入上一次 JSON 结果中的原生游标：

  • 搜索：hasMore == 1 → 将最后一项的 searchIdx 作为 --max-idx 传入
  • 笔记本：hasMore == 1 → 将最后一项的 books[].sort 作为 --last-sort 传入
  • 书评：将最后一条书评的 idx 作为 --max-idx 传入，并将返回的 synckey 作为 --synckey 传入
  • 相似图书：将最后一项的 idx 作为 --max-idx 传入，并将 booksimilar.sessionId 作为 --session-id 传入
  • 好友动态：将 nextMaxIdx 作为 --max-idx 传入；刷新动态流时重复使用返回的 synckey

错误处理

命令行会将错误规范化为 JSON：

{
  "ok": false,
  "skill_version": "1.0.4",
  "error": {
    "type": "missing_auth",
    "message": "..."
  }
}
  • missing_auth：阅读 references/first-use.md，并帮助配置密钥
  • upgrade_required：立即停止，并按照 upgrade_info.message 操作；升级完成前不要继续原任务
  • upstream_timeout、network_error：这些错误可以重试；命令行已在返回错误前重试暂时性故障
  • api_error、http_error、invalid_json：报告故障；仅在重复操作安全时重试

面向用户的输出

  • 默认使用 --json；当命令返回的元数据过多、不适合当前任务时，使用 --compact
  • 将 Unix 时间戳转换为易读的日期
  • 将秒转换为小时和分钟
  • 搜索结果、书架条目、笔记、书评和推荐内容使用编号列表
  • 在适当时附上微信读书深层链接；格式规则见 references/domain-rules.md

评论

支持 Markdown