weread

WeRead

仅使用已安装的 CLI 作为唯一接口。始终传入 --json，将成功时的 stdout 解析为 JSON，并向用户概述结果。退出码非零时，从 stderr 解析 JSON 错误。切勿泄露凭据或粘贴原始令牌。

账号选择

为本次会话恰好选择一个账号，并在每次 CLI 调用中保持使用该账号。使用用户或操作员提供的别名。如果未提供，weread-omni accounts --json 必须恰好显示一个已配置的账号。以下示例中的 $ACCOUNT 表示该别名。失败后不要切换账号。

除非操作员设置了 WEREAD_READONLY，否则允许写入。被拒绝的写入会报错 disabled by WEREAD_READONLY；应将此限制说明为策略限制，切勿取消设置该变量，也不要代表用户改用其他账号重试。

会话预检

在首次执行需要身份验证的操作之前，运行：

weread-omni --account "$ACCOUNT" doctor --json

只有结果包含 ok: true、cli.package: "weread-omni" 和 auth.status: "authenticated" 时才继续。遇到身份验证错误时，必须先确认 JSON 错误中的 cli.package 相同，然后再遵循其中的 hint。未经用户确认，不要启动二维码登录。遵循返回的账号专属提示；必须先更正或移除格式错误或无法读取的状态。使用同一账号重试一次 doctor。如果返回的内容不是 JSON，或名称指向其他程序包，则停止并报告 command -v weread-omni 返回的路径；不要猜测其他命令。

读取工作流

从能够回答请求的最精简读取操作开始。保留搜索或书架结果中的 bookId 值，以供后续命令使用。

首次读取后，图书元数据、章节列表和已下载的公众号文章会从本地资料库提供，因此重复读取可能返回存储的副本，而非最新内容。如果结果看起来已过时，应如实说明，并提供 --refresh 以重新获取并替换；--no-library 可让单条命令完全跳过资料库。切勿将存储的内容说成是刚刚获取的。

weread-omni --account "$ACCOUNT" public-accounts read-article 'https://mp.weixin.qq.com/s/ARTICLE' --json
weread-omni --account "$ACCOUNT" search books "三体" --json
weread-omni --account "$ACCOUNT" search books "刘慈欣" --scope 6 --json
weread-omni --account "$ACCOUNT" book info BOOK_ID --json
weread-omni --account "$ACCOUNT" shelf sync --count 20 --json
weread-omni --account "$ACCOUNT" public-accounts subscriptions --count 20 --json
weread-omni --account "$ACCOUNT" public-accounts articles MP_WXS_123 --count 20 --json
weread-omni --account "$ACCOUNT" public-accounts resolve-article 'https://mp.weixin.qq.com/s/ARTICLE' --json
weread-omni --account "$ACCOUNT" notes notebooks --count 10 --json
weread-omni --account "$ACCOUNT" notes recent --count 10 --json
weread-omni --account "$ACCOUNT" notes mine BOOK_ID --count 10 --json
weread-omni --account "$ACCOUNT" notes underlines BOOK_ID CHAPTER_UID --json
weread-omni --account "$ACCOUNT" notes read-reviews BOOK_ID CHAPTER_UID --reviews '[{"range":"393-401","count":10}]' --json
weread-omni --account "$ACCOUNT" review single REVIEW_ID --json
weread-omni --account "$ACCOUNT" read-data detail --mode weekly --json
weread-omni --account "$ACCOUNT" discover recommend --count 10 --json
weread-omni --account "$ACCOUNT" ai ask-book BOOK_ID "Summarize the central argument" --json

search books 默认对电子书使用 --scope 10。根据请求选择范围：0 表示全部，10 表示电子书，16 表示网络小说，14 表示音频，6 表示作者，12 表示全文，13 表示书单，2 表示公众号，4 表示文章。不要对所有意图都使用范围 10。hasMore 为 1 时，将最后一个结果的 searchIdx 作为 --max-idx 传入；单页并不代表完整结果集。

仅使用对应命令的游标：

• 对于 shelf sync，将 nextOffset 作为 --offset 传入。
• 对于 public-accounts articles，首次调用时省略 --offset；增量刷新时，传入之前的 synckey 作为 --synckey。绝不要同时使用两者。 如果响应包含 nextOffset，将其作为 --offset 传入；若没有该字段，则停止。
• 对于 notes notebooks，将最后一本书的 sort 作为 --last-sort 传入。
• notes recent 是账号范围内的有限快照；它没有分页游标。
• 对于 notes best 和 review list，将返回的条目数加到之前的 --max-idx 上。
• 仅使用 synckey 刷新之前获取的数据。它不是分页游标。

准确保留每个上游 hasMore 和游标；不要根据结果较少或缺少 hasMore 推断已完成。

shelf sync 默认返回精简分页。只有用户需要精确的上游同步字段时才使用 --full；它不能与 --count 或 --offset 一起使用。 使用 book detail 获取商品图片，以及同一作者或权利方的其他书籍。默认情况下，每个相关目录会返回 6 条结果；如果较少的结果已足够，可使用 --count（1-12）。查看对应内容时，请使用 book chapters 或 book progress。 book chapters 会返回目录，其中每个条目都带有 chapterUid，供笔记和书评命令定位书中的位置。查看相应类型的笔记时，请使用 notes bookmarks、notes best 或 notes underlines。要阅读热门划线下的想法，请从 notes best 中获取其 chapterUid 和 range，调用 notes read-reviews，然后在用户想要完整查看某条想法时使用 review single。查看书评、相关书籍和推荐问题时，请使用 review list、discover similar 和 ai suggest。

对于用户提供的文章 URL，请直接使用 public-accounts read-article URL --json；无需搜索公众号或订阅。resolve-article 只会返回 ID，而 review single 可能只包含元数据或摘要。 请使用返回的 markdown 或 contentHtml，并引用 sourceUrl。缓存命中会标记为 fromCache: true，并带有 cachedAt 和空值 fetchedAt。status: readable 本身并不能证明内容完整（completeness: unverified）；需要确认完整性时，请检查文章结构和结尾。partial 表示只获取到了预览。若正文不可用，命令会以非零状态退出，并在 stderr 中输出 JSON 诊断信息；切勿将元数据总结成正文。

发现和订阅公众号时，请遵循以下顺序：

1. 使用 weread-omni --account "$ACCOUNT" search books KEYWORD --scope 2 --json 进行搜索。
2. 展示匹配结果，并让用户选择确切的 MP_WXS_<digits> ID。 切勿自动选择或订阅第一个模糊匹配项。
3. 仅在用户提出请求时订阅，然后使用 public-accounts subscriptions、 articles、feed 或 export。
4. 仅在确认公众号准确无误后才取消订阅。

weread-omni --account "$ACCOUNT" public-accounts subscribe MP_WXS_123 --json
weread-omni --account "$ACCOUNT" public-accounts feed MP_WXS_123 --format rss --out /private/path/feed.xml --json
weread-omni --account "$ACCOUNT" public-accounts feed subscriptions --format json --out /private/path/feed.json --json
weread-omni --account "$ACCOUNT" public-accounts export MP_WXS_123 --out /private/path/archive --json
weread-omni --account "$ACCOUNT" public-accounts unsubscribe MP_WXS_123 --yes --json

Feed 和导出输出默认最多包含 20 项，最多可包含 100 项。对于聚合 Feed，这是最终输出限制；收集时，每个公众号最多可检索相同数量的候选项。CLI 输出路径绝不会被覆盖。只有在 manifest.json 存在时，导出才算完整；如果路径中的内容不完整，请报告该路径，而不要删除它。 文章检索会使用 WeRead 的 E-Ink User-Agent，从经过验证的 HTTPS mp.weixin.qq.com/s 源 URL 执行一次有界的直接检索尝试。该尝试最多跟随 3 次经过验证的重定向，并且不会向该主机发送 WeRead 身份验证标头。如果诊断信息报告 SOURCE_CLOUDFLARE_CHALLENGE 或 SOURCE_WECHAT_CHALLENGE，请告知用户在浏览器中打开其 sourceUrl。不要声称存档完整，也不要暗示 CLI 可以执行 JavaScript 挑战或解决 CAPTCHA。

如果用户询问书籍内容，请优先使用 ai ask-book：服务会直接回答，无需预先获取任何内容。

账号变更

只有在用户明确要求进行变更时，才执行写入操作。操作前说明目标。不要根据用户先前的读取操作推断其已同意。

weread-omni --account "$ACCOUNT" shelf add BOOK_ID --json
weread-omni --account "$ACCOUNT" review add BOOK_ID "A concise review" --star 100 --json
weread-omni --account "$ACCOUNT" review edit REVIEW_ID "Replacement text" --json
weread-omni --account "$ACCOUNT" import book /absolute/path/to/book.epub --json

import book 接受用户已有的 EPUB、PDF、MOBI、TXT 或 AZW3 文件；它会将该文件上传到用户自己的 WeRead 账号。

书架状态默认使用肯定状态，反向操作则使用否定选项：

weread-omni --account "$ACCOUNT" shelf pin BOOK_ID --json
weread-omni --account "$ACCOUNT" shelf pin BOOK_ID --no-top --json
weread-omni --account "$ACCOUNT" shelf set-private BOOK_ID --json
weread-omni --account "$ACCOUNT" shelf set-private BOOK_ID --no-secret --json
weread-omni --account "$ACCOUNT" shelf mark-finished BOOK_ID --json
weread-omni --account "$ACCOUNT" shelf mark-finished BOOK_ID --no-finished --json
weread-omni --account "$ACCOUNT" shelf mark-reading BOOK_ID --json
weread-omni --account "$ACCOUNT" shelf mark-reading BOOK_ID --no-reading --json

书评评分使用协议规定的等级：20、40、60、80 或 100。

添加划线（划线）时，请提供章节、字符范围和划线文本：

weread-omni --account "$ACCOUNT" notes add-bookmark BOOK_ID CHAPTER_UID "777-778" "the highlighted text" --json
weread-omni --account "$ACCOUNT" notes update-bookmark BOOKMARK_ID --style 2 --color-style 5 --json

删除操作具有破坏性。请先与用户确认确切目标，然后加入 --yes；切勿在写入失败后盲目重试。

weread-omni --account "$ACCOUNT" shelf delete BOOK_ID --yes --json
weread-omni --account "$ACCOUNT" notes remove-bookmark BOOKMARK_ID --yes --json
weread-omni --account "$ACCOUNT" review delete REVIEW_ID --yes --json
weread-omni --account "$ACCOUNT" public-accounts unsubscribe MP_WXS_123 --yes --json

结果处理

• 成功时，报告有用字段，并保留相关 ID 以便后续操作。
• 响应可能省略某些字段，或返回的条目少于请求数量。只使用实际返回的值；不要虚构缺失字段，也不要将其描述为零或空。
• 使用精简书架响应中的 totalCount。在 --full 响应中，总数为 books.length + albums.length + (non-empty mp ? 1 : 0)。不要只根据 bookCount 作答。
• 笔记本的笔记总数为 reviewCount + noteCount + bookmarkCount。noteCount 仅包含划线，reviewCount 已包含个人想法和书评。导出内容需要同时使用 notes bookmarks 和 notes mine；划线文本会返回，但 type-0 书签文本不会返回。
• 除 preferAuthor[].readTime 已是格式化文本外，所有阅读时长字段都以秒为单位。阅读进度是整数百分比：1 表示 1%，只有 100 表示已读完。
• 公开书评的评分使用 20、40、60、80、100，分别对应一到五颗星。个人笔记中的书评评分则可能是 0–5，或 -1 表示无评分。
• 直接使用返回的 deepLink 作为打开链接。响应未提供时，绝不要自行构造链接。展示日期前，先将 Unix 时间戳转换为日期。
• 遇到 { "error": ... } 时，说明错误，不要猜测，也不要悄悄改用其他命令。
• errCode -2010 和 -2013 是服务端自身作出的限流和权益判定。应如实报告，不要循环重试，也不要尝试换用其他命令绕过。
• 只有在用户需要更多结果时才分页。仅当后端返回所需的下一页信号（hasMore=1、nextOffset 或命令文档中规定的游标）时才继续。如果响应未提供完成信号，应说明当前页有数量限制，不要声称这是完整结果集。
• 在适当情况下保留中文源数据；只有在用户提出要求时才翻译或总结。
• 中文回复应以中文原创表达，而不是逐句翻译英文。措辞应简短、具体、自然；先说明用户可以做什么，再说明命令和限制；保留更清晰易懂的既有技术名称；回复前删除翻译腔和泛泛的 AI 营销用语。