Data sync layer for the PKM library: writes the WeRead bookshelf, read status, highlights, and thoughts into Obsidian, and supplements single-book details via the WeRead API. Local backfilling of book cards and reading records, and overview generation, are handled by the adjacent soia-pkm-library-book-catalog .
Customer-readable description
What this skill can do
This skill handles all actions that require accessing WeRead: syncing read books, syncing highlights/thoughts, and supplementing the introduction, chapters, similar books, and reading progress for specified book cards. It reads the vault path and private configuration provided by the user, and idempotently writes the results into book cards and reading records.
| What the customer wants | What the skill does | What the customer can see |
|---|---|---|
| Sync the WeRead bookshelf | Fetch read books, create or update book cards and reading records | Number processed, added/updated/skipped/failed statistics |
| Sync highlights | Fetch highlights and thoughts, overwrite machine-maintained sections and preserve user notes | Processing progress and write results for each book |
| Fill in this book's details | Call the WeRead API to supplement book information, chapters, similar books, and reading progress | API stage, write category, and failure reason |
How the customer uses it
- In natural language, state that you want to sync the bookshelf or sync highlights, or provide the title of the book whose details you want to fill in.
- Provide
--vault <path>, or setOBSIDIAN_VAULTin the private configuration; before syncing, confirm thatweread-skillsandWEREAD_API_KEYare available. - First use the highlights script's default preview or single-book mode to confirm the scope, then run
--allfor a full sync. - After execution, check the terminal receipt; if you need to refresh the local view, then run
soia-pkm-library-book-catalog's generation script.
Dependencies and installation
Install this skill:
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will have two indexes that drift from each other, so it is recommended to choose one of the two:
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-library-weread-sync -y
Hard dependencies:
npx skills add Tencent/WeChatReading -g -y
The WeRead API Key must be obtained after logging in on the official page:https://weread.qq.com/r/weread-skills. Private configuration path:
~/.config/soia-skills/soia-pkm-library-weread-sync/config.yml
SOIA_PKM_LIBRARY_WEREAD_SYNC_CONFIG_FILE=<custom-config-path>
SOIA_PKM_LIBRARY_WEREAD_SYNC_ENV_FILE=<compat-config-path>
Store only local values in the configuration, and do not commit keys:
env:
OBSIDIAN_VAULT: "<vault-path>"
WEREAD_API_KEY: "<YOUR_WEREAD_API_KEY>"
For compatibility with older invocation methods, the script still accepts SOIA_PKM_LIBRARY_CONFIG_FILE and SOIA_PKM_LIBRARY_ENV_FILE as configuration path environment variables; new configurations should preferentially use the new names above.
WorkBuddy 's loading unit is a role-based expert rather than a plugin,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。
Logs and completion receipt
The terminal log will explain the starting phase, number processed, write category, skip/failure reasons, and next-step suggestions. API keys, cookies, tokens, or private configuration content must not be output. When dependencies or keys are missing, API calls must stop, and installation commands or official retrieval addresses must be provided.
What it can do
| Script | Function | When to run |
|---|---|---|
sync_weread_to_library.py |
WeRead read books → library book cards + reading records | When you want to sync the latest reading status |
sync_weread_highlights.py |
WeRead highlights/thoughts → existing reading-record machine section | When you want to sync highlight notes |
enrich_book_details.py <书名>... |
Supplement the introduction, chapters, progress, and similar books via the WeRead API | When you want to supplement details for a single book |
How to run
The following commands are executed from this skill's scripts/ directory:
python3 sync_weread_to_library.py --vault <vault-path>
python3 sync_weread_highlights.py # 预览 noteCount 前 30 本
python3 sync_weread_highlights.py --all # 全量同步
python3 sync_weread_highlights.py <书名> # 指定书名
python3 enrich_book_details.py <书名>
python3 enrich_book_details.py --all
python3 enrich_book_details.py --refresh-chapters
All scripts share the following parameterization conventions:
--vault <path>orOBSIDIAN_VAULT: vault root directory; the command line takes precedence.--base <relpath>: the library's path relative to the vault; explicitly override when another library is needed.--config <json>: override categories, status, or field mappings (supported by specific scripts).- Private configuration uses
SOIA_PKM_LIBRARY_WEREAD_SYNC_CONFIG_FILE, compatible aliases, or the default configuration path for loading; it will not override environment variables that already exist in the process.
Directory contract and upstream/downstream
The library directory is determined by --base , and the core structure is:
<base>/
├── 00_图书馆/书目/<分类目录>/<书名>.md
└── 阅读记录/<状态>/<书名>.md
In the book card, category/subcategory is the authoritative source for categories; reading records are used to look up book cards via book: "[[书名]]" . The book cards and reading records produced by the sync scripts are inputs to the downstream local catalog scripts; the catalog skill is optional to install and does not affect local organization and view generation of existing data.
sync_weread_highlights.py maintains the ## 📌 划线 / ## 💭 想法 machine section; user-written content should be placed in the ### 用户笔记 subsection within it, otherwise the next sync may overwrite it.
Hard dependency: weread-skills and API Key
All three scripts require the official WeRead weread-skills. Before syncing, the following must be satisfied:
weread-skillsis installed in the workspace or the user's agent skill directory.WEREAD_API_KEYhas been written to the privateconfig.yml'senv.WEREAD_API_KEY, or is provided by the process environment.OBSIDIAN_VAULTis configured, or passed in via the command line--vault。- This machine can access
https://i.weread.qq.com/api/agent/gateway。 - Python 3 is available; the scripts use only the Python standard library and this skill's bundled
library_env.py。
When dependencies are missing, run:
npx skills add Tencent/WeChatReading -g -y
When WEREAD_API_KEY is missing, open https://weread.qq.com/r/weread-skills to log in to WeRead and obtain it, then write it to the private configuration; do not use an old cookie as a Bearer key, and do not write the key into the vault or this repository.
Boundaries and exceptions
| Scenario | Handling |
|---|---|
Not installed weread-skills |
API-type scripts exit directly and provide the official installation command |
Not set WEREAD_API_KEY |
Exit and provide the official retrieval address and private configuration location |
| No vault specified | Exit and prompt to pass --vault or configure OBSIDIAN_VAULT |
| Local book card/reading record not found | Batch mode skips and prints a warning without interrupting other books |
| WeRead book title differs from the file name | Highlight sync prioritizes matching by bookId , with title matching as a fallback |
Completion receipt
For complex sync tasks, first run a forward test on a small scope, a single book, or a fixture, verify additions, updates, skips, failures, and outputs, then expand to the full set. After completion, you must report: sync scope, number of successes/skips/failures, file changes to book cards and reading records, problems encountered, and next steps (usually running the catalog overview generation script).