soia-pkm-library-weread-synclisted
Install: claude install-skill soia-team/soia-open-skills
# soia-pkm-library-weread-sync
PKM 书库的数据同步层：把微信读书书架、已读状态、划线和想法写入 Obsidian，并通过微信读书 API 补充单本书详情。书卡和阅读记录的本地补建、总览生成由相邻的 `soia-pkm-library-book-catalog` 负责。
## 客户可读说明
### 这个技能可以做什么
这个技能负责所有需要访问微信读书的动作：同步已读书目、同步划线/想法，以及为指定书卡补充简介、章节、相似书和阅读进度。它会读取用户提供的 vault 路径和私有配置，把结果幂等地落到书卡与阅读记录中。
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 同步微信读书书架 | 拉取已读书目，创建或更新书卡和阅读记录 | 处理数量、新增/更新/跳过/失败统计 |
| 同步划线 | 拉取划线和想法，覆��机器维护段并保留用户笔记 | 每本书的处理进度和写入结果 |
| 补一下这本书的详情 | 调用微信读书 API，补充书籍信息、章节、相似书和阅读进度 | API 阶段、写入类别和失败原因 |
### 客户如何使用
1. 用自然语言说明要同步书架、同步划线，或提供要补详情的书名。
2. 提供 `--vault <path>`，或在私有配置中设置 `OBSIDIAN_VAULT`；同步前确认 `weread-skills` 和 `WEREAD_API_KEY` 可用。
3. 先用划线脚本的默认预览或单本模式确认范围，再运行 `--all` 全量同步。
4. 执行后核对终端回执；如需刷新本地视图，再运行 `soia-pkm-library-book-catalog` 的生成脚本。
### 依赖与安装
安装本技能：
```bash
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-library-weread-sync -y
```
强依赖：
```bash
npx skills add Tencent/WeChatReading -g -y
```
微信读书 API Key 需在官方页面登录后获取：<https://weread.qq.com/r/weread-skills>。私有配置路径：
```text
~/.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>
```
配置只放本机值，不提交密钥：
```yaml
env:
OBSIDIAN_VAULT: "<vault-path>"
WEREAD_API_KEY: "<YOUR_WEREAD_API_KEY>"
```
为兼容旧调用方式，脚本仍接受 `SOIA_PKM_LIBRARY_CONFIG_FILE` 和 `SOIA_PKM_LIBRARY_ENV_FILE` 作为配置路径环境变量；新配置优先使用上面的新名称。
### 日志与完成回执
终端日志会说明开始阶段、处理数量、写入类别、跳过/失败原因和下一步建议。不得输出 API key、cookie、t