jerlin-weread-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WeRead — 微信读书助手

WeRead — WeChat Reading Assistant

所有接口通过

scripts/weread.sh

调用。脚本处理鉴权和参数平铺。查看子命令列表：

weread.sh -h

；查看某个子命令的参数和回包字段：

weread.sh <subcmd> -h

。

All interfaces are called via

scripts/weread.sh

. The script handles authentication and parameter flattening. View the list of subcommands:

weread.sh -h

; view the parameters and response fields of a specific subcommand:

weread.sh <subcmd> -h

能力路由

Capability Routing

用户意图	子命令	领域知识
搜书/找书	`search`	`references/search.md`
书籍详情/章节/进度	`book-info` `chapters` `progress`	`references/book.md`
书架	`shelf`	`references/shelf.md`
阅读统计/时长/偏好	`readdata`	`references/readdata.md`
笔记/划线/想法	`notebooks` `bookmarks` `my-reviews`	`references/notes.md`
热门划线/划线下想法	`best-bookmarks` `read-reviews` `underlines`	`references/notes.md`
公开点评	`reviews`	`references/review.md`
推荐好书	`recommend` `similar`	`references/discover.md`
用户阅读概况	(组合)	`references/profile.md`

调用任何接口前，必须先阅读对应 reference 确认字段含义、计数口径和工作流。回包字段名和直觉含义冲突时，服从 reference 说明。

User Intent	Subcommand	Domain Knowledge
Search for books	`search`	`references/search.md`
Book details/chapters/progress	`book-info` `chapters` `progress`	`references/book.md`
Bookshelf	`shelf`	`references/shelf.md`
Reading statistics/duration/preferences	`readdata`	`references/readdata.md`
Notes/underlines/thoughts	`notebooks` `bookmarks` `my-reviews`	`references/notes.md`
Popular underlines/thoughts under underlines	`best-bookmarks` `read-reviews` `underlines`	`references/notes.md`
Public reviews	`reviews`	`references/review.md`
Recommend good books	`recommend` `similar`	`references/discover.md`
User reading profile	(Combination)	`references/profile.md`

Before calling any interface, you must read the corresponding reference to confirm field meanings, counting standards, and workflows. When response field names conflict with intuitive meanings, follow the reference instructions.

鉴权

Authentication

环境变量
```
$WEREAD_API_KEY
```
，格式
```
wrk-xxxxxxxx
```
未设置时提示用户：
```
export WEREAD_API_KEY=<你的apikey>
```
API Key 绑定用户身份（vid），无需手动传

Environment variable
```
$WEREAD_API_KEY
```
in the format
```
wrk-xxxxxxxx
```
If not set, prompt the user:
```
export WEREAD_API_KEY=<your apikey>
```
The API Key is bound to the user identity (vid), no need to pass it manually

通用规则

General Rules

```
errcode
```
非 0 表示错误，给出中文提示。回包出现
```
upgrade_info
```
时按其 message 指引完成升级后重试。
用户输入书名时，先调
```
weread.sh search
```
获取 bookId，再执行后续操作。
对话中记住已查询的 bookId，后续操作无需用户重复提供。
列表用编号展示方便选择。展示回包信息时，字段禁止直接翻译，参考 reference 中的说明。
时间戳展示为 YYYY-MM-DD 格式，不得直接展示原始数字。
阅读时长单位为秒，展示时转为「X 小时 Y 分钟」。

A non-zero
```
errcode
```
indicates an error, provide a Chinese prompt. When
```
upgrade_info
```
appears in the response, follow its message to complete the upgrade and retry.
When the user enters a book title, first call
```
weread.sh search
```
to get the bookId, then perform subsequent operations.
Remember the queried bookId during the conversation, no need for the user to provide it repeatedly in subsequent operations.
Display lists with numbers for easy selection. When displaying response information, do not translate fields directly; refer to the explanations in the reference.
Display timestamps in YYYY-MM-DD format, do not show raw numbers directly.
Reading duration is in seconds; convert it to "X hours Y minutes" when displaying.

深度链接

Deep Links

展示书籍、章节、划线等内容时，回包字段足以构造链接的，附上跳转链接方便用户在 App 中打开。

场景 URL Schema

打开书籍

场景	URL Schema
打开书籍	`weread://reading?bId={bookId}`
跳转章节	`weread://reading?bId={bookId}&chapterUid={chapterUid}`
跳转划线位置	`weread://bestbookmark?bookId={bookId}&chapterUid={chapterUid}&rangeStart={rangeStart}&rangeEnd={rangeEnd}&userVid={userVid}`

weread://reading?bId={bookId}

跳转章节

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

跳转划线位置

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

range 解析：划线接口返回的 range 格式为

起始-结束

（如

900-2004

），拆分后分别填入 rangeStart 和 rangeEnd。

划线位置链接的生成条件：回包同时包含 chapterUid 和 range。整本书评或无法定位到划线的点评不生成此链接。userVid 从上下文获取或省略。

When displaying content such as books, chapters, underlines, etc., if the response fields are sufficient to construct a link, attach the jump link to facilitate users to open it in the App.

Scenario URL Schema

Open book

Scenario	URL Schema
Open book	`weread://reading?bId={bookId}`
Jump to chapter	`weread://reading?bId={bookId}&chapterUid={chapterUid}`
Jump to underline position	`weread://bestbookmark?bookId={bookId}&chapterUid={chapterUid}&rangeStart={rangeStart}&rangeEnd={rangeEnd}&userVid={userVid}`

weread://reading?bId={bookId}

Jump to chapter

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

Jump to underline position

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

Range parsing: The range format returned by the underline interface is

start-end

(e.g.,

900-2004

). Split it and fill in rangeStart and rangeEnd respectively.

Conditions for generating underline position links: The response contains both chapterUid and range. Do not generate this link for full-book reviews or reviews that cannot be located to underlines. userVid is obtained from the context or omitted.