WeRead — WeRead Assistant

Call WeRead interfaces via Agent API Gateway, providing capabilities such as search, bookshelf management, notes, book reviews, etc.

Supported Capabilities

Capability	Description	User Example	Detailed Instructions
Search Books	Search in the book store	"Help me search for The Three-Body Problem"	`search.md`
Book Information	View book details, chapter catalog, reading progress	"How many chapters does this book have?" "Where did I leave off reading?"	`book.md`
Bookshelf Management	View bookshelf	"Show me my bookshelf"	`shelf.md`
Reading Statistics	Reading duration, days, preference analysis, reading statistics summary	"How long did I read this month?" "How many books have I read this year?"	`readdata.md`
Notes & Underlines	View personal note count and content, including underlines, thoughts/comments, bookmark count	"Show me my notes in The Three-Body Problem" "Export my underlines" "How many notes do I have in this book?"	`notes.md`
Popular Underlines in Chapters	View popular underlines in books/chapters, underline popularity and thoughts under underlines	"Show me the popular underlines in this chapter" "What thoughts are there under this passage?"	`notes.md`
Book Reviews	View public reviews of books	"What are the reviews for The Three-Body Problem?" "Show me recommended reviews"	`review.md`
Recommend Good Books	Personalized recommendations/similar recommendations	"Recommend some books to me"	`discover.md`

Refer to the corresponding instruction documents according to user intent to understand interface parameters, response structure and workflow.

Interface Calling Specifications

Unified Entry

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

Authentication

Header：
```
Authorization: Bearer $WEREAD_API_KEY
```
```
WEREAD_API_KEY
```
is obtained from environment variables, in the format
```
wrk-xxxxxxxx
```
If not set, prompt the user:
```
export WEREAD_API_KEY=<your apikey>
```
API Key is bound to user identity (vid), interfaces requiring user identity will automatically inject it, no need to manually pass vid

Request Format

Method: POST
Content-Type: application/json
Body: JSON,
```
api_name
```
specifies the interface, others are interface parameters, skill_version
must be included in each request

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": "三体", "count": 10, "skill_version": "1.0.3"}'

Request Few-Shot Examples

Correct: Business parameters are placed at the top level of the body.

json

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

Correct: Continue to place

lastSort

at the top level for next page.

json

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

Incorrect: Do not wrap business parameters in

params

json

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

The incorrect writing above will cause

count

and

lastSort

not to be forwarded, and the backend will return the first page according to default values, making it seem like pagination is invalid.

Response Format

JSON, the response is field-trimmed, only core fields are returned
Non-zero
```
errcode
```
indicates an error, with Chinese prompt message
Send
```
{"api_name": "/_list"}
```
to view all available interfaces and parameter definitions

General Rules

Version Reporting: Each request body must include
```
"skill_version": "1.0.3"
```
(take the value of the version field at the top of this file), which is used for the server to check for version updates. If the
upgrade_info
field appears in the response, you must immediately pause the current operation, complete the upgrade according to the guidelines in
upgrade_info.message
, and re-execute the user request after the upgrade is completed; do not ignore this field
Parameter Flattening: Business parameters must be placed at the same level as
```
api_name
```
and
```
skill_version
```
; do not wrap them in objects like
```
params
```
,
```
data
```
, or
```
body
```
. Only array/object fields explicitly declared in the interface documentation (such as
```
reviews
```
of
```
/book/readreviews
```
) are allowed to be passed as business fields.
Pre-check Capability Documentation: Before calling any interface, you must first read the corresponding instruction document according to the "Supported Capabilities" table (e.g., read
```
readdata.md
```
first for reading statistics,
```
shelf.md
```
first for bookshelf), confirm interface parameters, field meanings, units, counting calibers and workflows; it is forbidden to guess meanings solely based on field names or experience.
Field Interpretation Priority: When interpreting interface responses, take the field descriptions in the corresponding instruction documents as the standard; if the response field name conflicts with intuitive meaning, you must follow the instruction document and not directly translate the field name.
bookId Parsing: When the user enters a book title, first call
```
/store/search
```
to obtain the bookId, then perform subsequent operations
Bookshelf Count: When using
```
/shelf/sync
```
to answer "How many books/items are in the bookshelf?", you must calculate it as
```
books.length + albums.length + (mp is not null ? 1 : 0)
```
;
```
albums[]
```
are albums/audiobooks, which also belong to the books in the bookshelf, detailed rules can be found in
```
shelf.md
```
Result Display: Use numbered lists for display to facilitate selection; focus on displaying book title, author, and rating for search results; when displaying interface response information, forbid direct translation of fields, and should provide content based on the descriptions in the documents
Context Cohesion: Remember the queried bookId in the conversation, and users do not need to provide it repeatedly for subsequent operations
Deep Linking: When displaying underlines, thoughts, chapters and other content, splice the corresponding jump links to facilitate users to open the corresponding location directly in the App. For thoughts/reviews, not all have underline positions, only when
```
chapterUid
```
and
```
range
```
are available, generate the underline position link
Data Display Specifications:
- Timestamp: All Unix timestamp fields (such as
```
updateTime
```
  ,
```
createTime
```
  ,
```
finishTime
```
  ,
```
readUpdateTime
```
  , etc.) must be converted to YYYY-MM-DD format when displayed (e.g.,
```
1748563200
```
  is displayed as "2025-05-30"), raw numbers cannot be displayed directly
- Reading Duration: Unit is seconds, convert to "X hours Y minutes" format when displayed

Deep Linking (URL Schema)

When displaying books, chapters, underlines and other content, if the response fields are sufficient to construct a link, attach the corresponding jump link to facilitate users to open the corresponding location directly in the WeRead App. Thoughts/reviews do not necessarily have underline positions, only when

chapterUid

and

range

are available, generate the underline position link.

Open Book (Jump to last reading progress)

weread://reading?bId={bookId}

Parameter	Description	Source
`bookId`	Book ID	`bookId` returned by each interface

Example:

weread://reading?bId=3300045871

Usage Scenarios:

Attach a jump link to each book when displaying the bookshelf list
Attach an "Open to Read" link when displaying search results
Provide a "Continue Reading" link when displaying reading progress

Jump to Specified Chapter

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

Parameter	Description	Source
`bookId`	Book ID	`bookId` returned by each interface
`chapterUid`	Chapter UID	`chapters[].chapterUid` returned by `/book/chapterinfo`

Example:

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

Usage Scenarios:

Attach a jump link to each chapter when displaying the chapter catalog

Jump to Underline/Thought Location

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

Parameter	Description	Source
`bookId`	Book ID	`bookId` returned by each interface
`chapterUid`	Chapter UID	`chapterUid` belonging to the underline/thought
`rangeStart`	Underline start position	The number before `-` in the `range` field
`rangeEnd`	Underline end position	The number after `-` in the `range` field
`userVid`	User VID	User ID automatically associated after API Key authentication (obtained from the context of interfaces like `/shelf/sync` , or omitted)

range Parsing: The
range
field returned by the underline interface is in the format
"start-end"
(e.g.,
"900-2004"
), split it and fill in
rangeStart
and
rangeEnd
respectively.

Example:

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

Usage Scenarios:

Attach a jump link to each underline when displaying the underline list (
```
/book/bookmarklist
```
) (the
```
range
```
field can be directly parsed)
Attach a jump link to each when displaying popular underlines (
```
/book/bestbookmarks
```
);
```
/book/underlines
```
is only underline popularity statistics and does not contain underline text
When displaying thoughts (
```
/review/list/mine
```
,
```
/book/readreviews
```
), only attach the link to jump to the corresponding underline position if the returned content includes
```
chapterUid
```
and
```
range
```
; reviews for the entire book or reviews that cannot be located to an underline do not require generating this link

weread-skills

NPX Install

Tags

SKILL.md Content (Chinese)

WeRead — WeRead Assistant

Supported Capabilities

Interface Calling Specifications

Unified Entry

Authentication

Request Format

Request Few-Shot Examples

Response Format

General Rules

Deep Linking (URL Schema)

Open Book (Jump to last reading progress)

Jump to Specified Chapter

Jump to Underline/Thought Location