soia-team soia-pkm-library-weread-sync
PKM 书库的数据同步层：把微信读书书架、已读状态、划线和想法写入 Obsidian，并通过微信读书 API 补充单本书详情。书卡和阅读记录的本地补建、总览生成由相邻的 soia-pkm-library-book-catalog 负责。
客户可读说明
这个技能可以做什么
这个技能负责所有需要访问微信读书的动作：同步已读书目、同步划线/想法，以及为指定书卡补充简介、章节、相似书和阅读进度。它会读取用户提供的 vault 路径和私有配置，把结果幂等地落到书卡与阅读记录中。
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 同步微信读书书架 | 拉取已读书目，创建或更新书卡和阅读记录 | 处理数量、新增/更新/跳过/失败统计 |
| 同步划线 | 拉取划线和想法，覆盖机器维护段并保留用户笔记 | 每本书的处理进度和写入结果 |
| 补一下这本书的详情 | 调用微信读书 API，补充书籍信息、章节、相似书和阅读进度 | API 阶段、写入类别和失败原因 |
客户如何使用
- 用自然语言说明要同步书架、同步划线，或提供要补详情的书名。
- 提供
--vault <path>，或在私有配置中设置OBSIDIAN_VAULT；同步前确认weread-skills和WEREAD_API_KEY可用。 - 先用划线脚本的默认预览或单本模式确认范围，再运行
--all全量同步。 - 执行后核对终端回执；如需刷新本地视图，再运行
soia-pkm-library-book-catalog的生成脚本。
依赖与安装
安装本技能：
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-library-weread-sync -y
强依赖：
npx skills add Tencent/WeChatReading -g -y
微信读书 API Key 需在官方页面登录后获取：https://weread.qq.com/r/weread-skills。私有配置路径：
~/.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>
配置只放本机值，不提交密钥：
env:
OBSIDIAN_VAULT: "<vault-path>"
WEREAD_API_KEY: "<YOUR_WEREAD_API_KEY>"
为兼容旧调用方式，脚本仍接受 SOIA_PKM_LIBRARY_CONFIG_FILE 和 SOIA_PKM_LIBRARY_ENV_FILE 作为配置路径环境变量；新配置优先使用上面的新名称。
WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。
日志与完成回执
终端日志会说明开始阶段、处理数量、写入类别、跳过/失败原因和下一步建议。不得输出 API key、cookie、token 或私有配置内容。缺少依赖或 key 时必须停止 API 调用，并给出安装命令或官方获取地址。
能做什么
| 脚本 | 功能 | 何时运行 |
|---|---|---|
sync_weread_to_library.py |
微信读书已读书目 → 图书馆书卡 + 阅读记录 | 想同步最新阅读状态时 |
sync_weread_highlights.py |
微信读书划线/想法 → 已有阅读记录的机器段 | 想同步划线笔记时 |
enrich_book_details.py <书名>... |
通过微信读书 API 补简介、章节、进度、相似书 | 想补单本书详情时 |
如何运行
以下命令从本技能的 scripts/ 目录执行：
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
所有脚本共享以下参数化约定：
--vault <path>或OBSIDIAN_VAULT：vault 根目录，命令行优先。--base <relpath>：书库相对 vault 的路径；需要其他书库时显式覆盖。--config <json>：覆盖分类、状态或字段映射（由具体脚本支持）。- 私有配置使用
SOIA_PKM_LIBRARY_WEREAD_SYNC_CONFIG_FILE、兼容别名或默认配置路径加载；不会覆盖进程中已经存在的环境变量。
目录契约与上下游
书库目录由 --base 决定，核心结构为：
<base>/
├── 00_图书馆/书目/<分类目录>/<书名>.md
└── 阅读记录/<状态>/<书名>.md
书卡中的 category/subcategory 是分类权威源；阅读记录通过 book: "[[书名]]" 反查书卡。同步脚本产生的书卡和阅读记录是下游本地 catalog 脚本的输入；catalog skill 可选安装，不影响已有数据的本地整理和视图生成。
sync_weread_highlights.py 维护 ## 📌 划线 / ## 💭 想法 机器段；用户手写内容应放在其中的 ### 用户笔记 子区块，否则下一次同步可能被覆盖。
强依赖：weread-skills 与 API Key
三个脚本都需要微信读书官方 weread-skills。同步前必须满足：
weread-skills已安装在 workspace 或用户的 agent skill 目录中。WEREAD_API_KEY已写入私有config.yml的env.WEREAD_API_KEY，或由进程环境提供。OBSIDIAN_VAULT已配置，或命令行传入--vault。- 本机可访问
https://i.weread.qq.com/api/agent/gateway。 - Python 3 可用；脚本只使用 Python 标准库与本技能自带的
library_env.py。
缺依赖时执行：
npx skills add Tencent/WeChatReading -g -y
缺少 WEREAD_API_KEY 时，打开 https://weread.qq.com/r/weread-skills 登录微信读书获取，再写入私有配置；不要用旧 cookie 冒充 Bearer key，也不要把 key 写入 vault 或本仓库。
边界与异常
| 场景 | 处理 |
|---|---|
未安装 weread-skills |
API 类脚本直接退出并给出官方安装命令 |
未设置 WEREAD_API_KEY |
退出并给出官方获取地址及私有配置位置 |
| 未指定 vault | 退出并提示传 --vault 或配置 OBSIDIAN_VAULT |
| 找不到本地书卡/阅读记录 | 批量模式跳过并打印警告，不中断其他书 |
| 微信读书书名与文件名不同 | 划线同步优先按 bookId 匹配，标题匹配兜底 |
完成后回执
复杂同步任务先用小范围、单本或 fixture 做一次前向测试，核对新增、更新、跳过、失败和产出，再扩大到全量。完成后必须回报：同步范围、成功/跳过/失败数量、书卡与阅读记录的文件变化、遇到的问题和下一步（通常是运行 catalog 的总览生成脚本）。