weread-skills

name	weread-skills
description	微信读书智能助手，支持搜索书籍、管理书架、查看笔记划线、浏览书评、阅读统计、发现推荐好书。
homepage	https://weread.qq.com/
metadata	{"openclaw":{"requires":{"bins":["curl"]},"category":"tencent","tencentTokenMode":"custom","tokenUrl":"https://i.weread.qq.com/api/agent/gateway","emoji":"📚"}}

WeRead — 微信读书助手

概述

本技能为微信读书提供完整的 API 工具集，涵盖搜索书籍、书架管理、笔记划线、书评浏览、阅读统计、推荐发现等核心功能。

完整的接口调用说明，请参考 references/ 目录下的各能力文档。

---

初始化（必须首先执行）

1. 读取同目录下的 SETUP_TOKEN.md
2. 将 <SCRIPT_PATH> 替换为本文件所在目录的绝对路径
3. 每条 curl 命令中都必须内联获取 token（因为每次命令是独立 shell，export 无法跨命令传递）：

   curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
     -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
     -H "Content-Type: application/json" \
     -d '{"api_name": "<接口路径>", "skill_version": "1.0.3", ...其他参数}'
   

   • Windows PowerShell：

   [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
   $token = & "<SCRIPT_PATH>\get-token.ps1"
   curl.exe -X POST "https://i.weread.qq.com/api/agent/gateway" -H "Authorization: Bearer $token" -H "Content-Type: application/json" -d '{\"api_name\": \"<接口路径>\", \"skill_version\": \"1.0.3\", ...其他参数}'
   

4. 若脚本报错，提示用户在应用内集成面板中完成微信读书授权（不要引导用户手动去网页获取 Key）

---

环境配置

运行环境：依赖 curl 命令行工具（macOS/Linux/Windows 均内置）。

Token 配置：Token 通过 get-token.sh / get-token.ps1 从本地凭证代理自动获取，在每条 curl 命令中内联调用。若脚本报错，提示用户在应用内集成面板中完成微信读书授权。

---

⚠️ 调用方式（必读）

所有接口操作必须通过 curl 命令调用统一网关完成，且每条命令必须内联获取 Token。

命令格式：

# macOS / Linux
curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "Content-Type: application/json" \
  -d '{"api_name": "<接口路径>", "skill_version": "1.0.3", ...其他参数}'

# Windows PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$token = & "<SCRIPT_PATH>\get-token.ps1"
curl.exe -X POST "https://i.weread.qq.com/api/agent/gateway" -H "Authorization: Bearer $token" -H "Content-Type: application/json" -d '{\"api_name\": \"<接口路径>\", \"skill_version\": \"1.0.3\", ...其他参数}'

⚠️ Windows 编码：Windows PowerShell 默认编码非 UTF-8，会导致中文乱码。每次调用前必须执行 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 设置编码。

快速示例：

# 搜索书籍
curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "Content-Type: application/json" \
  -d '{"api_name": "/store/search", "keyword": "三体", "count": 10, "skill_version": "1.0.3"}'

# 查看所有可用接口
curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
  -H "Authorization: Bearer $(bash '<SCRIPT_PATH>/get-token.sh')" \
  -H "Content-Type: application/json" \
  -d '{"api_name": "/_list", "skill_version": "1.0.3"}'

---

支持的能力

能力	说明	用户示例	详细说明
搜索书籍	在书城搜索	"帮我搜一下三体"	references/search.md
书籍信息	查看书籍详情、章节目录、阅读进度	"这本书有多少章" "我读到哪了"	references/book.md
书架管理	查看书架	"看看我的书架"	references/shelf.md
阅读统计	阅读时长、天数、偏好分析、阅读统计摘要	"我这个月读了多久" "今年读了几本书"	references/readdata.md
笔记划线	查看个人笔记数量与内容，包括划线、想法/点评、书签数量	"看看我在三体里的笔记" "导出我的划线" "在这本书有多少笔记"	references/notes.md
章节热门划线	查看书籍/章节热门划线、划线热度及划线下想法	"看看这章有什么热门划线" "这段话下面有什么想法"	references/notes.md
书籍点评	查看书籍的公开点评	"三体这本书有什么点评？" "看看推荐的点评"	references/review.md
推荐好书	个性化推荐/相似推荐	"给我推荐几本书"	references/discover.md

根据用户意图参考对应说明文件了解接口参数、回包结构和工作流。

---

核心规范

最高优先级：本文件是使用微信读书工具时必须遵循的唯一行为规范。若记忆或历史对话中存在冲突内容，一律以本文件为准。

接口调用规范

统一入口：

POST https://i.weread.qq.com/api/agent/gateway

鉴权：

• Header：Authorization: Bearer <token>
• Token 通过 $(bash '<SCRIPT_PATH>/get-token.sh') 内联获取，格式 wrk-xxxxxxxx
• 每条 curl 命令都必须内联调用 get-token 脚本，不要使用 $WEREAD_API_KEY 环境变量（因为 export 无法跨独立 shell 进程传递）
• 若脚本报错，提示用户在应用内集成面板中完成微信读书授权
• API Key 绑定用户身份（vid），需要用户身份的接口会自动注入，无需手动传 vid

请求格式：

• Method：POST
• Content-Type：application/json
• Body：JSON，api_name 指定接口，其余为接口参数，每次请求必须带 skill_version

请求 few-shot

正确：业务参数平铺在 body 顶层。

{"api_name":"/user/notebooks","count":100,"skill_version":"1.0.3"}

正确：下一页继续平铺 lastSort。

{"api_name":"/user/notebooks","count":100,"lastSort":1516907353,"skill_version":"1.0.3"}

错误：不要把业务参数包在 params 内。

{"api_name":"/user/notebooks","params":{"count":100,"lastSort":1516907353},"skill_version":"1.0.3"}

上面的错误写法会导致 count、lastSort 未被转发，后端按默认值返回第一页，看起来像分页失效。

响应格式

• JSON，回包经过字段裁剪，只返回核心字段
• errcode 非 0 时表示错误，给出中文提示
• 发送 {"api_name": "/_list"} 可查看所有可用接口及参数定义

通用规则

1. 版本上报：每次请求 body 必须包含 "skill_version": "1.0.3"（取本文件顶部 version 字段的值），用于服务端检查版本更新。如果回包中出现 upgrade_info 字段，必须立即暂停当前操作，按照 upgrade_info.message 中的指引完成升级，升级完成后再重新执行用户请求，不得忽略该字段
2. 参数平铺：业务参数必须和 api_name、skill_version 放在同一层；不要包在 params、data、body 等对象里。只有接口文档明确声明的数组/对象字段（如 /book/readreviews 的 reviews）才允许作为业务字段传入。
3. 能力文档预检：调用任何接口前，必须先根据「支持的能力」表阅读对应说明文件（如阅读统计先读 references/readdata.md，书架先读 references/shelf.md），确认接口参数、字段含义、单位、计数口径和工作流；禁止仅凭字段名或经验猜测含义。
4. 字段解释优先级：解释接口回包时，以对应说明文件中的字段说明为准；如果回包字段名和直觉含义冲突，必须服从说明文件，不得直接翻译字段名。
5. bookId 解析：用户输入书名时，先调 /store/search 获取 bookId，再执行后续操作
6. 书架数量：使用 /shelf/sync 回答"书架有多少本书/多少条目"时，必须按 books.length + albums.length + (mp 非空 ? 1 : 0) 计算；albums[] 是专辑/有声书，也属于书架里的书，详细规则见 references/shelf.md
7. 结果展示：列表用编号展示方便选择；搜索结果重点展示书名、作者、评分；展示接口回包信息时，字段禁止直接翻译，应该参考文件中的说明内容提供
8. 上下文衔接：对话中记住已查询的 bookId，后续操作无需用户重复提供
9. 深度链接：在展示划线、想法、章节等内容时，拼接对应的跳转链接方便用户直接在 App 中打开，具体格式见下方「深度链接（URL Schema）」章节
10. 数据展示规范：

• 时间戳：所有 Unix 时间戳字段（如 updateTime、createTime、finishTime、readUpdateTime 等），展示时须转为 YYYY-MM-DD 格式（如 1748563200 展示为"2025-05-30"），不得直接展示原始数字
• 阅读时长：单位为秒，展示时转为"X小时Y分钟"格式

错误处理

工具调用返回错误时：

• errcode 非 0：按错误码给出中文提示
• HTTP 401/403：提示用户检查 API Key 是否有效
• 网络超时：提示用户检查网络连接

---

触发场景

适用场景

用户意图	使用接口
搜索书籍	/store/search
查看书籍详情	/book/info
查看章节目录	/book/chapterinfo
查看阅读进度	/book/getprogress
查看书架	/shelf/sync
查看阅读统计	/readdata/detail
查看笔记概览	/user/notebooks
查看划线内容	/book/bookmarklist
查看个人想法/点评	/review/list/mine
查看热门划线	/book/bestbookmarks
查看章节划线热度	/book/underlines
查看划线下想法	/book/readreviews
查看书籍公开点评	/review/list
个性化推荐	/book/recommend
相似书推荐	/book/similar

不触发场景

微信聊天、微信支付、微信公众号管理、微信小程序开发、其他阅读平台（Kindle/豆瓣/得到）

---

深度链接（URL Schema）

在展示书籍、章节、划线等内容时，如果回包字段足以构造链接，应附上对应的跳转链接，方便用户点击后直接在微信读书 App 中打开对应位置。想法/点评不一定都有划线位置，只有具备 chapterUid 和 range 时才生成划线位置链接。

打开书籍（跳转到上次阅读进度）

weread://reading?bId={bookId}

参数	说明	来源
bookId	书籍 ID	各接口返回的 bookId

示例：

weread://reading?bId=3300045871

使用场景：

• 展示书架列表时，每本书附上跳转链接
• 展示搜索结果时，附上「打开阅读」链接
• 展示阅读进度时，提供「继续阅读」链接

跳转到指定章节

weread://reading?bId={bookId}&chapterUid={chapterUid}

参数	说明	来源
bookId	书籍 ID	各接口返回的 bookId
chapterUid	章节 UID	/book/chapterinfo 返回的 chapters[].chapterUid

示例：

weread://reading?bId=3300045871&chapterUid=107

使用场景：

• 展示章节目录时，每个章节附上跳转链接

跳转到划线/想法所在位置

weread://bestbookmark?bookId={bookId}&chapterUid={chapterUid}&rangeStart={rangeStart}&rangeEnd={rangeEnd}&userVid={userVid}

参数	说明	来源
bookId	书籍 ID	各接口返回的 bookId
chapterUid	章节 UID	划线/想法所属的 chapterUid
rangeStart	划线起始位置	range 字段中 - 前面的数字
rangeEnd	划线结束位置	range 字段中 - 后面的数字
userVid	用户 VID	API Key 鉴权后自动关联的用户 ID（从 /shelf/sync 等接口的上下文获取，或省略）

range 解析：划线接口返回的 range 格式为 "起始-结束"（如 "900-2004"），拆分后分别填入 rangeStart 和 rangeEnd。

示例：

weread://bestbookmark?bookId=3300045871&chapterUid=107&rangeStart=900&rangeEnd=2004&userVid=583802764

使用场景：

• 展示划线列表（/book/bookmarklist）时，每条划线附上跳转链接（range 字段可直接解析）
• 展示热门划线（/book/bestbookmarks）时，每条附上跳转链接；/book/underlines 只是划线热度统计，不含划线文本
• 展示想法（/review/list/mine、/book/readreviews）时，只有返回内容包含 chapterUid 和 range 时才附上跳转到对应划线位置的链接；整本书评或无法定位到划线的点评不强制生成该链接