微信读书助手 Skill:让 AI 帮你整理书架、笔记与阅读数据

🎯 一句话本质

weread-skills 就像给微信读书配了一位会听人话的图书管理员。你不必自己翻书架、抄笔记或统计阅读时间，只要说“看看我这个月读了多久”，Agent 就会调用对应接口，把结果整理给你。

😫 为什么要用它

微信读书里的信息分散在不同页面：书架在一处，划线和想法在另一处，阅读时长又藏在统计页面。想回顾一本书时，常常要来回点很多次。

这个 Skill 把操作入口统一成自然语言：

• 想找书：说“帮我搜一下《三体》”。
• 想复盘：说“看看我在《三体》里的笔记”。
• 想了解习惯：说“我这个月读了多久”。
• 不知道读什么：说“根据我的阅读偏好推荐几本书”。

🔑 4 个核心概念

概念 1：Skill 是操作说明书

• 类比：像给 Agent 一份岗位手册，告诉它遇到不同问题该查哪个系统。
• 定义：Skill 保存能力说明、接口参数和结果解释规则，让 Agent 按固定流程调用微信读书。
• 最小例子：用户说“看看我的书架”，Agent 会按 shelf.md 的规则查询，而不是凭经验猜接口。

概念 2：Agent API Gateway 是统一服务窗口

• 类比：像图书馆的总服务台。搜书、笔记、书评虽然是不同业务，但都从同一个窗口递交申请。
• 定义：所有请求都发送到 https://i.weread.qq.com/api/agent/gateway，通过 api_name 指定具体能力。
• 最小例子：搜索书籍时，api_name 使用 /store/search，关键词等业务参数与它放在 JSON 顶层。

概念 3：WEREAD_API_KEY 是个人借书证

• 类比：服务台先看借书证，才知道正在查询谁的书架和笔记。
• 定义：环境变量 WEREAD_API_KEY 用于鉴权，格式为 wrk-xxxxxxxx；它会关联用户身份，不需要手动传入用户 VID。
• 注意：不要把 API Key 写进文章、聊天记录或 Git 仓库。

概念 4：能力文档决定数据怎么解释

• 类比：同一个数字可能是“本数”、也可能是“秒数”，必须先看字段说明再下结论。
• 定义：主 Skill 会根据意图读取 search.md、book.md、shelf.md、notes.md、review.md、readdata.md 或 discover.md。
• 例子：阅读时长原始单位是秒，展示时要转换成“X 小时 Y 分钟”；时间戳要转换成日期。

📚 它能做什么

1. 搜索书籍，展示书名、作者和评分。
2. 查看书籍详情、章节目录与个人阅读进度。
3. 查看和管理个人书架。
4. 汇总阅读时长、阅读天数和阅读偏好。
5. 查看个人划线、想法、点评与书签数量。
6. 查看章节热门划线、热度和划线下的想法。
7. 浏览一本书的公开点评。
8. 根据兴趣发现个性化或相似书籍推荐。

当接口返回足够信息时，它还能生成 weread:// 深度链接，让你直接跳回微信读书 App 的书籍、章节或划线位置。

🚀 最小可运行流程

1. 安装 Skill

npx skills add Tencent/WeChatReading -g

安装完成后重启或新开 Agent 会话，让运行时发现 weread-skills。

2. 配置鉴权

export WEREAD_API_KEY=<你的apikey>

3. 用自然语言调用

帮我搜一下《三体》看看我的书架我这个月读了多久导出我在《三体》里的划线根据我的阅读偏好推荐 5 本书

Agent 会根据请求选择能力文档；如果用户只提供书名，它会先搜索得到 bookId，再执行后续查询。

⚠️ 新手最容易踩的 3 个坑

1. 没配置 WEREAD_API_KEY

• 现象：需要个人身份的书架、笔记或统计无法查询。
• 原因：接口不知道要读取哪个用户的数据。
• 解决：在本地环境变量中配置 Key，不要提交到 Git。

2. 请求参数多包了一层 `params`

• 现象：分页参数没有生效，看起来一直返回第一页。
• 原因：业务参数必须和 api_name、skill_version 放在 JSON 同一层。
• 解决：保持参数平铺，只有接口明确声明的对象或数组才能嵌套。

3. 忘记携带 skill_version

• 现象：服务端无法正确判断 Skill 版本；也可能错过升级提示。
• 原因：每次请求都必须上报当前 Skill 版本。
• 解决：按 SKILL.md 顶部版本发送；一旦响应出现 upgrade_info，先升级再继续操作。

🖼️ 一张图总结

顶部用一句话说明“自然语言管理微信读书”。中部按四个淡色区块展示“搜书与详情、书架与统计、笔记与书评、发现与推荐”。下部是一条三步流程：安装 Skill → 配置 WEREAD_API_KEY → 直接提问。底部警示条保留三个关键词：保护 Key、参数平铺、携带版本号。