SuperAPI AI Directory

soia-pkm-library-weread-sync

General & other

View repository

Updated 10-16 08:46

About this skill

soia-pkm-library-weread-sync

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

  1. 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.
  2. Provide --vault <path>, or set OBSIDIAN_VAULTin the private configuration; before syncing, confirm that weread-skills and WEREAD_API_KEY are available.
  3. First use the highlights script's default preview or single-book mode to confirm the scope, then run --all for a full sync.
  4. 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> or OBSIDIAN_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-skills is installed in the workspace or the user's agent skill directory.
  • WEREAD_API_KEY has been written to the private config.yml 's env.WEREAD_API_KEY, or is provided by the process environment.
  • OBSIDIAN_VAULT is 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).