Weread

WeRead

The local weread CLI is the only interface you need. It handles authentication, request shape, skill_version, JSON parsing, upgrade checks, and normalized errors — writing ad hoc curl requests would mean reimplementing all of that and losing the normalized error layer.

Agents should use --json by default. Use human-readable output only when the user explicitly wants terminal-readable command output.

For large outputs such as shelf, notebooks, bookmarks, or exports, write JSON or Markdown to a file first, then summarize the result in chat. Do not paste full large JSON payloads or full exported notes into the conversation.

For notes export, use --output <path> by default. Only stream the export to stdout when the user explicitly asks to see the full export inline.

First Decision

Before any WeRead work, check auth and CLI health:

weread doctor

If the weread command is missing, or if auth_configured is false, read references/first-use.md and guide the user through setup.

Command Map

weread search "三体" --scope book --count 10
weread book resolve "三体" --limit 5
weread book info <bookId>
weread book chapters <bookId>
weread book progress <bookId>
weread shelf list
weread shelf recent --limit 10
weread readdata detail --mode monthly
weread readdata summary --mode monthly
weread notes notebooks --count 100
weread notes top --limit 20
weread notes bookmarks <bookId>
weread notes export <bookId> --format markdown --output notes.md
weread notes mine <bookId> --count 20
weread notes underlines <bookId> <chapterUid>
weread notes best <bookId> --chapter-uid <chapterUid>
weread notes readreviews <bookId> <chapterUid> --reviews-json '[{"range":"900-2004","count":20}]'
weread reviews list <bookId> --type 1 --count 20
weread reviews single <reviewId>
weread discover recommend --count 12
weread discover similar <bookId> --count 12
weread api list

When a supported API isn't covered by a first-class command, use the raw escape hatch:

weread api call /store/search --param keyword=三体 --param scope=10

When To Read References

References are loaded on demand to keep startup context lean. Load them only when the task requires it:

• First-time setup, missing auth, or API Key questions: read references/first-use.md
• Shelf totals, public/private counts, audiobook or article-collection handling: read references/domain-rules.md
• Notes, highlights, bookmarks, personal ideas, public reviews, or exports: read references/domain-rules.md
• Reading statistics, historical periods, cross-year ranges, or time-unit interpretation: read references/domain-rules.md
• Deep links to books, chapters, highlights, or ideas: read references/domain-rules.md

Intent Routing

Search

• Find a book, get a bookId, or user says 搜书/找书: weread search "<keyword>" --scope book
• Generic 搜一下 or mixed intent: --scope all
• Web fiction or 网文: --scope fiction
• Audiobooks, podcasts, 听书, 有声书, or 专辑: --scope audio
• Authors: --scope author
• Full-text search or 书里提到: --scope fulltext
• Book lists: --scope list
• Official accounts: --scope mp
• Articles: --scope article

Book Details

If the user gives a title rather than an ID, prefer weread --json book resolve "<title>" --limit 5 and use items[].bookId.

• Metadata: book info
• Chapter UIDs (needed for notes/highlights by chapter): book chapters
• Reading progress: book progress — progress is an integer percent; 1 means 1%, only 100 means finished

Shelf

Use weread --json shelf list. For recent reading, use weread --json shelf recent --limit 10. For anything nuanced (public/private split, audiobook handling), read references/domain-rules.md.

Reading Statistics

Use weread --json readdata summary --mode monthly for common summaries, or weread --json readdata detail with --mode weekly, monthly, annually, or overall. Time fields in structured output are seconds. For historical or cross-period calculations, read references/domain-rules.md.

Notes and Highlights

• Overview across all books: weread --json notes notebooks
• Books with the most personal notes/highlights: weread --json notes top --limit 20
• Single-book export: weread notes export <bookId> --format markdown --output <path>; choose a local Markdown path and summarize counts/content instead of pasting the whole file
• If manually combining data, use both weread --json notes bookmarks <bookId> and weread --json notes mine <bookId>
• For counting rules, export limits, or popular highlight queries, read references/domain-rules.md

Reviews

Public reviews: weread --json reviews list <bookId> with --type 0 (all) through --type 4. Single review: weread --json reviews single <reviewId>.

Recommendations

• Personalized: weread --json discover recommend
• Similar books: weread --json discover similar <bookId>

Pagination

Stay shallow by default — only paginate further when the user explicitly asks for a complete export, a ranking, or a total that requires all pages. Use --limit for display size and --all where supported. For manual pagination, use --json and pass the native cursor from the previous JSON result:

• Search: hasMore == 1 → pass last item searchIdx as --max-idx
• Notebooks: hasMore == 1 → pass last books[].sort as --last-sort
• Reviews: pass last review idx as --max-idx and returned synckey as --synckey
• Similar: pass last item idx as --max-idx and booksimilar.sessionId as --session-id

Error Handling

The CLI normalizes errors to JSON:

{
  "ok": false,
  "skill_version": "1.0.3",
  "error": {
    "type": "missing_auth",
    "message": "..."
  }
}

• missing_auth: read references/first-use.md and help configure the key
• upgrade_required: stop immediately and follow upgrade_info.message; don't continue the original task until upgraded
• upstream_timeout, network_error: these are retryable; the CLI already retries transient failures before returning the error
• api_error, http_error, invalid_json: report the failure; retry only when repeating is safe

User-Facing Output

• Default to --json; use --compact when a command returns too much metadata for the task
• Convert Unix timestamps to readable dates
• Convert seconds to hours and minutes
• Use numbered lists for search results, shelf entries, notes, reviews, and recommendations
• Include WeRead deep links when useful; format rules are in references/domain-rules.md

WeRead Domain Rules

Use this reference for field meanings and user-facing interpretation. It intentionally avoids low-level request mechanics because the weread CLI handles those.

Shelf Rules

Use weread --json shelf list.

Visible shelf total:

books.length + albums.length + (mp ? 1 : 0)

Important distinctions:

• books[] contains electronic/imported/book-like entries.
• albums[] contains audiobooks or audio albums. They count as shelf items.
• mp is the article-collection entry. If present, it counts as one visible shelf item.
• Do not use bookCount as the total shelf count unless the user specifically asks for electronic books only.

Public/private counts:

• Private = books[].secret == 1 + albums[].albumInfoExtra.secret == 1 + (mp ? 1 : 0)
• Public = books[].secret == 0 + albums[].albumInfoExtra.secret == 0
• Count only returned visible entries.

Reading Progress

Use weread --json book progress <bookId>.

• progress is an integer percentage from 0 to 100.
• 1 means 1%, not complete.
• Only 100 means finished.
• Reading time fields are seconds.

Reading Statistics

Use weread --json readdata detail.

Modes:

• weekly: natural week
• monthly: natural month
• annually: natural year
• overall: all history

Time fields are seconds, including:

• totalReadTime
• dayAverageReadTime
• readLongest[].readTime
• dailyReadTimes values

Interpretation:

• Prefer totalReadTime for totals.
• readTimes is for bucketed detail, not the primary total.
• dayAverageReadTime is averaged over natural days, not only reading days.
• For "reading-day average", calculate totalReadTime / readDays and say that this is derived.

Historical and cross-period ranges:

• The API is based on fixed periods, not arbitrary start/end dates.
• For a whole year, use --mode annually with a timestamp inside that year.
• For cross-year requests, query each natural year and sum totalReadTime.
• For partial boundary periods, use dailyReadTimes when available. If it is not available, use month/year approximation and state the approximation.

Notes, Highlights, And Bookmarks

Notebook overview:

weread --json notes notebooks --count 100

Single-book exportable content usually needs:

weread --json notes bookmarks <bookId>
weread --json notes mine <bookId>

Counting rules:

• Notebook total notes = reviewCount + noteCount + bookmarkCount.
• noteCount means highlight count, not total notes.
• reviewCount includes personal ideas/reviews and should not be added again under another label.

Export rules:

• Exportable content = highlight text + personal ideas/reviews.
• Bookmark positions are counted by bookmarkCount, but bookmark content is not exportable through the current CLI commands.
• If the user explicitly asks for bookmark content, explain that only the count is available.

Popular highlights:

• weread --json notes underlines <bookId> <chapterUid> returns heat/statistics and ranges, not highlight text.
• weread --json notes best <bookId> returns popular highlight text and counts.
• weread --json notes readreviews <bookId> <chapterUid> --reviews-json '[...]' returns ideas/comments under specific highlight ranges.

Reviews

Personal notes and public reviews are different:

• Personal content: weread --json notes mine <bookId>
• Public book reviews: weread --json reviews list <bookId>

Public review filter values:

• --type 0: all
• --type 1: recommended
• --type 2: negative
• --type 3: recent
• --type 4: normal

For user-facing display, convert review star values when present:

• 100: five stars
• 80: four stars
• 60: three stars
• 40: two stars
• 20: one star

Search Scope Rules

Use these scopes:

• book: electronic books
• all: mixed search when the user only says "搜一下"
• fiction: web fiction
• audio: audiobooks, podcasts, albums
• author: authors
• fulltext: full-text search inside books
• list: book lists
• mp: official accounts
• article: articles

When resolving a title to a bookId, use --scope book unless the user clearly asks for a different type.

Deep Links

Add deep links when useful and when the required fields are available.

Book:

weread://reading?bId={bookId}

Chapter:

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

Highlight or idea position:

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

Range parsing:

• range is usually shaped like 900-2004.
• rangeStart is the number before -.
• rangeEnd is the number after -.
• userVid may be omitted if unavailable.

Only generate a highlight-position link when bookId, chapterUid, and range are available.

First Use And API Key Setup

Use this reference when weread doctor reports missing auth, when the weread command is not installed, when the user asks how to get an API Key, or when the user is setting up WeRead for the first time.

Install The CLI

If the weread command is missing, install the published CLI package:

npm install -g weread-agent-cli

Then verify the command:

weread --version
weread doctor

Get An API Key

1. Open the official WeRead Skills page:

   https://weread.qq.com/r/weread-skills

2. Sign in with the WeRead account whose reading data the user wants to access. 3. Find the API Key section on that page and copy the key. It should look like:

   wrk-...

4. Configure the local CLI:

   weread config set-key "wrk-..."

5. Verify:

   weread doctor

Where The Key Is Stored

The CLI stores the key in:

~/.weread-cli/config.json

The environment variable WEREAD_API_KEY takes priority over the config file. This is useful for temporary overrides or CI:

export WEREAD_API_KEY="wrk-..."
weread doctor

Safety Notes

• Treat the API Key as a private credential.
• Do not commit the key to a repository.
• Do not paste the key into issue trackers, README examples, or shared logs.
• weread config list and weread doctor only show a masked preview.

Common Setup Problems

• If doctor still says auth is missing, run weread config path and confirm the key was saved in that file.
• If an environment variable is set to the wrong key, it overrides the config file. Clear WEREAD_API_KEY and rerun doctor.
• If the key was copied with spaces or quotes, run weread config set-key again with the clean key.