jerlin-weread-skill

WeRead — WeRead Assistant

All interfaces are called via scripts/weread.sh . The script handles authentication and parameter flattening. To view the list of subcommands:weread.sh -h; to view the parameters and response fields of a subcommand:weread.sh <subcmd> -h。

Capability Routing

User Intent	Subcommand	Domain Knowledge
Search books/find 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/highlights/thoughts	notebooks bookmarks my-reviews	references/notes.md
Popular highlights/thoughts on highlights	best-bookmarks read-reviews underlines review-detail	references/notes.md
Public reviews	reviews	references/review.md
Recommended good books	recommend similar	references/discover.md
User reading overview	(composite)	references/profile.md
Reading profile	(composite + AskUser)	references/reading-profile.md

CRITICAL: Before calling any interface, first read the corresponding reference to confirm field meanings, counting criteria, and workflows. When response field names conflict with intuitive meanings, follow the reference description.

Authentication

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

General Rules

1. errcode Non-zero indicates an error, provide a Chinese prompt. When the response contains upgrade_info , follow its message guidance to complete the upgrade and retry.
2. When the user inputs a book title, first call weread.sh search to get the bookId, then perform subsequent operations.
3. Remember the queried bookId in the conversation, so subsequent operations do not require the user to provide it again.
4. Display lists with numbers for easy selection. When displaying response information, fields must not be translated directly; refer to the descriptions in the reference.
5. Display timestamps in YYYY-MM-DD format; do not display raw numbers directly.
6. The reading duration unit is seconds; when displaying, convert to "X hours Y minutes".

Deep Links

When displaying content such as books, chapters, and highlights, if the response fields are sufficient to construct a link, attach a jump link for the user to open in the App.

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

range parsing: The range format returned by the highlight interface is 起始-结束(e.g., 900-2004), after splitting, fill in rangeStart and rangeEnd respectively.

Conditions for generating the highlight position link: the response contains both chapterUid and range. This link is not generated for whole-book reviews or reviews that cannot be located to a highlight. userVid is obtained from context or omitted.