SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssoia-pkm-library-weread-sync

soia-pkm-library-weread-sync

Office & productivity

View repository

Updated 10-16 08:43

About this skill

soia-pkm-library-weread-sync

The data sync layer of the PKM library: writes the WeRead bookshelf, read status, highlights, and thoughts into Obsidian, and supplements single-book details through the WeRead API. Local backfilling of book cards and reading records, and overview generation, are handled by the adjacent soia-pkm-library-book-catalog responsible for.

Customer-readable description

What this skill can do

This skill handles all actions that require access to WeRead: syncing read books, syncing highlights/thoughts, and supplementing the introduction, chapters, similar books, and reading progress for a specified book card. It reads the vault path and private configuration provided by the user, and idempotently writes the results into book cards and reading records.

Customer wants Skill will do Customer can see
Sync WeRead bookshelf Pull read books, create or update book cards and reading records Processing count, added/updated/skipped/failed statistics
Sync highlights Pull highlights and thoughts, overwrite machine-maintained sections and preserve user notes Processing progress and write results for each book
Fill in the details of this book Call the WeRead API to supplement book information, chapters, similar books, and reading progress API stage, write category, and failure reason

How customers use it

  1. Use natural language to state that you want to sync the bookshelf, sync highlights, or provide the book title whose details you want to fill in.
  2. Provide --vault <path>, or set it in the private configuration OBSIDIAN_VAULT; before syncing, confirm that weread-skills and WEREAD_API_KEY are available.
  3. First use the highlight 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, run soia-pkm-library-book-catalog generation script.

Dependencies and installation

Install this skill:

npx skills add soia-team/soia-open-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-open-skills/soia-pkm/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>

The configuration only contains local values; do not commit secrets:

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; the new configuration preferentially uses the new names above.

Logs and completion receipt

The terminal log will explain the start stage, processing count, write category, skip/failure reasons, and next-step suggestions. API keys, cookies, tokens, or private configuration contents must not be output. When dependencies or keys are missing, API calls must stop, and installation commands or the official acquisition address 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 → machine sections of existing reading records When you want to sync highlight notes
enrich_book_details.py <书名>... Supplement introduction, chapters, progress, and similar books through the WeRead API When you want to fill in 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; command line takes priority.
  • --base <relpath>: path of the library relative to the vault; when another library is needed, override it explicitly.
  • --config <json>: override the category, status, or field mapping (supported by the specific script).
  • Private configuration uses SOIA_PKM_LIBRARY_WEREAD_SYNC_CONFIG_FILE, a compatible alias, or the default configuration path to load; 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

The category/subcategory in a book card is the authoritative source for categories; reading records are looked up back to book cards via book: "[[书名]]" . The book cards and reading records produced by the sync scripts are inputs to downstream local catalog scripts; the catalog skill is optional to install and does not affect local organization of existing data or view generation.

sync_weread_highlights.py maintains the ## 📌 划线 / ## 💭 想法 machine section; user-written content should be placed in the ### 用户笔记 sub-block within it, otherwise it may be overwritten on the next sync.

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 of env.WEREAD_API_KEY, or is provided by the process environment.
  • OBSIDIAN_VAULT is configured, or passed in on the command line as --vault。
  • The local 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。

If 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 acquisition 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 file name Highlight sync matches first by bookId , with title matching as a fallback

Receipt after completion

For complex sync tasks, first run a forward test on a small scope, a single book, or a fixture, checking 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).