soia-pkm-library-book-catalog

PKM 书库的本地 catalog 层：只读取和写入 vault 内的 Markdown 与 YAML frontmatter，补建缺失的待读记录，并生成三份可供 Obsidian 浏览的总览。它不调用微信读书 API、不需要第三方 skill，也不会因为缺少微信读书配置而停止。

客户可读说明

这个技能可以做什么

这个技能适合在已有书卡或阅读记录的基础上整理本地书库。它会按书卡的分类字段生成图书馆总览和阅读记录总览，也可以把“有书卡但没有阅读记录”的书幂等地补成“待读”记录，并生成按类型分组的视图。

客户想要	技能会做	客户能看到
补建待读记录	扫描书卡与阅读记录，创建缺失记录，已有目标则跳过	新建、跳过和失败数量
重新生成图书馆总览	读取本地书卡并生成分类嵌套视图	输出文件与书目统计
更新阅读记录总览	以书卡分类为准汇总 7 态阅读生命周期	状态、分类和处理统计
书库整理	依次执行补建与三份视图生成	每阶段回执和可重复执行结果

客户如何使用

用自然语言说明要补建待读记录、更新某份总览，或整理整个书库。
提供 --vault <path>，或在私有配置中设置 OBSIDIANVAULT；不需要 WEREADAPI_KEY 或微信读书登录态。
生成脚本支持 --output <path> 预览，确认内容后再省略该参数写回 vault。
执行后核对真实输出与统计；所有脚本均可安全重复运行。

依赖与安装

安装本技能：

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-book-catalog -y

运行依赖只有 Python 3 和本地 vault 中的 Markdown 文件；不依赖微信读书、weread-skills、WEREADAPIKEY、网络或额外 pip 包。

私有配置路径：

~/.config/soia-skills/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>

示例：

env:
  OBSIDIAN_VAULT: "<vault-path>"

为兼容旧调用方式，脚本也接受 SOIAPKMLIBRARYCONFIGFILE 和 SOIAPKMLIBRARYENVFILE；新配置优先使用上面的 catalog 专用名称。配置只保存本机路径，不提交私密数据。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

日志与完成回执

每次运行都会输出扫描范围、创建/更新/跳过/失败数量、输出类别和下一步建议。涉及 vault 的日志只报告泛化位置和资源类别，不打印密钥或不必要的本机绝对路径。结束时必须说明实际文件变化和验证方式。

能做什么

脚本	功能	何时运行
`backfillreadingrecords.py`	为有书卡、无阅读记录的书批量创建“待读”记录	想让书卡与阅读记录对齐时
`genlibrarymd.py`	按一级/二级分类生成图书馆总览	书卡变动后
`genrecordsmd.py`	按书卡权威分类和 7 态状态生成阅读记录总览	阅读记录变动后
`gengenrelibrary_md.py`	按单级类型生成图书馆总览	需要类型视图时

如何运行

以下命令从本技能的 scripts/ 目录执行：

python3 backfill_reading_records.py --vault <vault-path>
python3 gen_library_md.py --vault <vault-path> --output <preview-path>
python3 gen_records_md.py --vault <vault-path> --output <preview-path>
python3 gen_genre_library_md.py --vault <vault-path> --base <vault-book-library-dir> --output <preview-path>

确认预览后，去掉 --output 写回 vault。所有脚本共享以下参数化约定：

--vault <path> 或 OBSIDIAN_VAULT：vault 根目录，命令行优先。
--base <relpath>：书库相对 vault 的路径；按实际书库显式传入，不依赖固定个人目录名。
--config <json>：覆盖分类、状态、图标或字段透传设置（由具体脚本支持）。
私有配置使用 SOIAPKMLIBRARYBOOKCATALOGCONFIGFILE、兼容别名或默认配置路径加载；不会覆盖进程中已有的环境变量。

目录契约与上游关系

书库目录由 --base 决定，核心结构为：

<base>/
├── 00_图书馆/
│   ├── 图书馆.base
│   └── 书目/<分类目录>/<书名>.md
└── 阅读记录/
    ├── 阅读记录.base
    ├── 想读/  待读/  计划读/  在读/
    ├── 暂停/  搁置/  完成/
    └── 阅读记录-总览.md

书卡的 category/subcategory 是分类权威源；阅读记录通过 book: "[[书名]]" 反查书卡。没有任何记录指向的书卡，就是 backfillreadingrecords.py 的待补对象。生成脚本读本地 Markdown，不向远端请求数据。

soia-pkm-library-weread-sync 是可选上游：它可以先把微信读书数据落成书卡、阅读记录和机器段，本技能随后消费这些本地文件。catalog 也可以单独处理已有的本地数据，不安装上游同步 skill 仍能运行。

写盘与幂等边界

Markdown 视图属于 vault 的产品特性文件，默认写回由 --base 定位的书库目录。
三个 gen_* 脚本支持 --output <path> 预览，避免直接覆盖总览文件。
backfillreadingrecords.py 只在目标记录不存在时创建，已有文件跳过，不覆盖用户记录。
脚本不创建网络缓存、不写外部状态、不调用 provider；临时预览路径由用户通过 --output 传入，临时文件由调用方自行管理。
若书库已有 图书馆.base 或 阅读记录.base，查询必须在同一个 filters.and 中同时保留对应目录的 file.inFolder(...) 与书库/阅读记录标签；tag-only Base 不能作为完成状态。新增或移动文件后按索引同步合同重建地图，并用 vaultindexverify.py 逐个验证 Base 根路径。

边界与异常

场景	处理
未指定 vault	退出并提示传 `--vault` 或设置 `OBSIDIAN_VAULT`
书库目录不存在	输出可定位的缺失目录提示并退出，不伪造总览
目标待读记录已存在	跳过，不覆盖已有内容
书卡缺少标题或分类	按脚本默认值归类并在日志中提示
本地书名无法反查	跳过并打印警告，不中断批量整理
想确认生成内容	使用 `--output` 输出到临时预览文件

完成后回执

完成后必须回报：本次运行的脚本和范围、扫描/创建/更新/跳过/失败数量、实际写入的资源类别、预览或写回验证结果、地图统计，以及每个现有 Base 的目录根验证结果。没有 Base 时明确记录 not_applicable。不要把“命令返回 0”单独当作内容正确的证据；至少检查输出存在且包含预期标题或统计。

soia-pkm-library-book-catalog

Installation

Summary

Stronger alternatives

Similar popular skills

Also in this package

Agent compatibility

Repository health

Skill metadata

Package contents

History

SKILL.md

soia-pkm-library-book-catalog

客户可读说明

这个技能可以做什么

客户如何使用

依赖与安装

日志与完成回执

能做什么

如何运行

目录契约与上游关系

写盘与幂等边界

边界与异常

完成后回执