| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.6 KB |
| book.md | markdown | 3.7 KB |
| discover.md | markdown | 5.7 KB |
| notes.md | markdown | 13.0 KB |
| profile.md | markdown | 2.8 KB |
| readdata.md | markdown | 12.0 KB |
| review.md | markdown | 4.1 KB |
| search.md | markdown | 9.0 KB |
| shelf.md | markdown | 8.0 KB |
SKILL.md
View on GitHub---
name: weread-skills
description: 微信读书助手 — 搜索书籍、管理书架、查看笔记划线、浏览书评、阅读统计、发现推荐好书
version: 1.0.6
---
# WeRead — 微信读书助手
通过 Agent API Gateway 调用微信读书接口,提供搜索、书架、笔记、书评和好书推荐等能力。
## 支持的能力
| 能力 | 说明 | 用户示例 | 详细说明 |
|------|------|----------|----------|
| 搜索书籍 | 在书城搜索 | "帮我搜一下三体" | `search.md` |
| 书籍信息 | 查看书籍详情、章节目录、阅读进度 | "这本书有多少章" "我读到哪了" | `book.md` |
| 书架管理 | 查看书架 | "看看我的书架" | `shelf.md` |
| 阅读统计 | 阅读时长、天数、偏好分析、阅读统计摘要 | "我这个月读了多久" "今年读了几本书" | `readdata.md` |
| 笔记划线 | 查看个人笔记数量与内容,包括划线、想法/点评、书签数量 | "看看我在三体里的笔记" "导出我的划线" "在这本书有多少笔记" | `notes.md` |
| 章节热门划线 | 查看书籍/章节热门划线、划线热度及划线下想法 | "看看这章有什么热门划线" "这段话下面有什么想法" | `notes.md` |
| 书籍点评 | 查看书籍的公开点评 | "三体这本书有什么点评?" "看看推荐的点评" | `review.md` |
| 推荐好书 | 个性化推荐/相似推荐 | "给我推荐几本书" | `discover.md` |
根据用户意图参考对应说明文件了解接口参数、回包结构和工作流。
---
## 接口调用规范
### 统一入口
```
POST https://i.weread.qq.com/api/agent/gateway
```
### 鉴权
- Header:`Authorization: Bearer $WEREAD_API_KEY`
- `WEREAD_API_KEY` 从环境变量获取,格式 `wrk-xxxxxxxx`
- 若未设置,提示用户:`export WEREAD_API_KEY=<你的apikey>`
- API Key 绑定用户身份(vid),需要用户身份的接口会自动注入,无需手动传 vid
### 请求格式
- **Method**:POST
- **Content-Type**:application/json
- **Body**:JSON,`api_name` 指定接口,其余为接口参数,**每次请求必须带 `skill_version`**
```bash
curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
-H "Authorization: Bearer $WEREAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"api_name": "/store/search", "keyword": "三体", "scope": 10, "context": "帮我搜一下三体", "skill_version": "1.0.6"}'
```
### 请求 few-shot
**正确:业务参数平铺在 body 顶层。**
```json
{"api_name":"/user/notebooks","count":100,"skill_version":"1.0.6"}
```
**正确:下一页继续平铺 `lastSort`。**
```json
{"api_name":"/user/notebooks","count":100,"lastSort":1516907353,"skill_version":"1.0.6"}
```
**错误:不要把业务参数包在 `params` 内。**
```json
{"api_name":"/user/notebooks","params":{"count":100,"lastSort":1516907353},"skill_version":"1.0.6"}
```
上面的错误写法会导致 `count`、`lastSort` 未被转发,后端按默认值返回第一页,看起来像分页失效。
### 响应格式
- JSON,回包经过字段裁剪,只返回核心字段
- `errcode` 非 0 时表示错误,给出中文提示
- 发送 `{"api_name": "/_list"}` 可查看所有可用接口及参数定义
### 通用规则
1. **版本上报**:每次请求 body 必须包含 `"skill_version": "1.0.6"`(取本文件顶部 version 字段的值),用于服务端提示版本更新。如果回包中出现 `upgrade_info`,它只是非阻塞升级通知:先使用同一回包中的业务数据完成当前用户请求,再简要提示用户后续可升级。不要暂停、重试或重新执行当次请求,也不要未经用户授权下载或替换文件。
2. **参数平铺**:业务参数必须和 `api_name`、`skill_version` 放在同一层;不要包在 `params`、`data`、`body` 等对象里。只有接口文档明确声明的数组/对象字段(如 `/book/readreviews` 的 `reviews`)才允许作为业务字段传入。
3. **能力文档预检**:调用任何接口前,必须先根据「支持的能力」表阅读对应说明文件(如阅读统计先读 `readdata.md`,书架先读 `shelf.md`),确认接口参数、字段含义、单位、计数口径和工作流;禁止仅凭字段名或经验猜测含义。
4. **字段解释优先级**:解释接口回包时,以对应说明文件中的字段说明为准;如果回包字段名和直觉含义冲突,必须服从说明文件,不得直接翻译字段名。
5. **bookId 解析**:用户输入书名时,先调 `/store/search` 获取 bookId,再执行后续操作
6. **书架数量**:使用 `/shelf/sync` 回答“书架有多少本书/多少条目”时,必须按 `books.length + albums.length + (mp 非空 ? 1 : 0)` 计算;`albums[]` 是专辑/有声书,也属于书架里的书,详细规则见 `shelf.md`
7. **结果展示**:列表用编号展示方便选择;搜索结果重点展示书名、作者、评分;展示接口回包信息时,字段**禁止**直接翻译,应该参考文件中的说明内容提供
8. **上下文衔接**:对话中记住已查询的 bookId,后续操作无需用户重复提供
9. **搜索与推荐上下文上报**:调用 `/store/search`、`/book/recommend` 或 `/book/similar` 时必须传 `context`。单轮请求传用户触发本次调用的原始问题;依赖多轮对话时传“当前原话 + 必要上下文摘要”。只包含理解本次搜索或推荐所需的信息,不上传无关对话、系统提示、完整工具回包、API Key 或其他凭据。具体规则见 `search.md` 和 `discover.md`
10. **书籍跳转链接**:优先使用接口回包中的 `readerLink` 作为直达阅读器链接,展示为 `[打开阅读]({readerLink})`;没有 `readerLink` 但有 `deepLink` 时,将 `deepLink` 展示为 `[查看详情]({deepLink})`;两个字段都没有时不要自行拼接链接
11. **数据展示规范**:
- **时间戳**:所有 Unix 时间戳字段(如 `updateTime`、`createTime`、`finishTime`、`readUpdateTime` 等),**展示时须转为 YYYY-MM-DD 格式**(如 `1748563200` 展示为"2025-05-30"),不得直接展示原始数字
- **阅读时长**:单位为秒,展示时转为"X小时Y分钟"格式
---
## 书籍跳转链接
在展示书籍、章节、划线、想法等内容时,直接使用接口回包中的链接字段,不要自行拼接 URL。
- 回包有 `readerLink` 时,展示为 `[打开阅读]({readerLink})`。
- 回包没有 `readerLink` 但有 `deepLink` 时,展示为 `[查看详情]({deepLink})`。
- 两个字段同时存在时,优先返回 `readerLink`;仅在用户需要书籍详情入口时额外展示 `deepLink`。
- 两个字段都没有时,不要尝试手动拼接 `weread://` 或 `https://weread.qq.com/` 链接。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |