soia-pkm-library-book-cataloglisted
Install: claude install-skill soia-team/soia-open-skills
# soia-pkm-library-book-catalog
PKM 书库的本地 catalog 层：只读取和写入 vault 内的 Markdown 与 YAML frontmatter，补建缺失的待读记录，并生成三份可供 Obsidian 浏览的总览。它不调用微信读书 API、不需要第三方 skill，也不会因为缺少微信读书配置而停止。
## 客户可读说明
### 这个技能可以做什么
这个技能适合在已有书卡或阅读记录的基础上整理本地书库。它会按书卡的分类字段生成图书馆总览和阅读记录总览，也可以把“有书卡但没有阅读记录”的书幂等地补成“待读”记录，并生成按类型分组的视图。
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 补建待读记录 | 扫描书卡与阅读记录，创建缺失记录，已有目标则跳过 | 新建、跳过和失败数量 |
| 重新生成图书馆总览 | 读取本地书卡并生成分类嵌套视图 | 输出文件与书目统计 |
| 更新阅读记录总览 | 以书卡分类为准汇总 7 态阅读生命周期 | 状态、分类和处理统计 |
| 书库整理 | 依次执行补建与三份视图生成 | 每阶段回执和可重复执行结果 |
### 客户如何使用
1. 用自然语言说明要补建待读记录、更新某份总览，或整理整个书库。
2. 提供 `--vault <path>`，或在私有配置中设置 `OBSIDIAN_VAULT`；不需要 `WEREAD_API_KEY` 或微信读书登录态。
3. 生成脚本支持 `--output <path>` 预览，确认内容后再省略该参数写回 vault。
4. 执行后核对真实输出与统计；所有脚本均可安全重复运行。
### 依赖与安装
安装本技能：
```bash
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-library-book-catalog -y
```
运行依赖只有 Python 3 和本地 vault 中的 Markdown 文件；不依赖微信读书、`weread-skills`、`WEREAD_API_KEY`、网络或额外 pip 包。
私有配置路径：
```text
~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-library-book-catalog/config.yml
SOIA_PKM_LIBRARY_BOOK_CATALOG_CONFIG_FILE=<custom-config-path>
SOIA_PKM_LIBRARY_BOOK_CATALOG_ENV_FILE=<compat-config-path>
```
示例：
```yaml
env:
OBSIDIAN_VAULT: "<vault-path>"
```
为兼容旧调用方式，脚本也接受 `SOIA_PKM_LIBRARY_CONFIG_FILE` 和 `SOIA_PKM_LIBRARY_ENV_FILE`；新配置优先使用上面的 catalog 专用名称。配置只保存本机路径，不提交私密数据。
### 日志与完成回执
每次运行都会输出扫描范围、创建/更新/跳过/失败数量、输出类别和下一步建议。涉及 vault 的日志只报告泛化位置和资源类别，不打印密钥或不必要的本机绝对路径。结束时必须说明实际文件变化和验证方式。
## 能做什么
| 脚本 | 功能 | 何时运行 |
|-