soia-pkm-reading-plan

属 SOIA 个人知识管理域（soia-pkm-*）的「加工」环节，与 soia-pkm-bootstrap-vault-base（搭建）同族。

把「想读的一批书」变成「排得进日程、读得完」的计划。

客户可读说明

这个技能可以做什么

场景化阅读计划生成器。把一批书（来自文章书单、观点映射或主题）组织成带表格、按真实字数排期的可执行阅读计划，落地成 Obsidian 笔记。可选用 weread-skills 增强字数/评分/书架核实，缺少时降级估算；可选参考 huashu-weread-advisor 方法论但不依赖它。当用户说「做个读书计划」「按 XX 场景排个计划」「把这篇文章的书单排...

客户如何使用

1. 用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
2. 能 dry-run 或预览的动作先给预览；涉及删除、覆盖、发送、发布、写远端状态时先征求客户确认。

依赖与安装

安装（推荐：装整个领域插件，一次装好本仓全部技能）：

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-reading-plan -y

配置约定：

~/.config/soia-skills/soia-pkm-reading-plan/config.yml
SOIA_PKM_READING_PLAN_CONFIG_FILE=<custom-config-path>

• 如果本技能不需要私有配置，可以不创建 config.yml。
• 如果需要 API key、cookie、session、provider home 或本机路径，只能放进私有 config.yml、进程环境或 provider 自己的登录态里，不能写进仓库、vault 正文或日志。
• 第三方 skill 只能声明依赖和安装方式，不直接修改第三方 skill 文件。

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

日志与完成回执

每次执行都要让客户看见过程和结果。最低回执格式：

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

定位与依赖

设计原则：依赖声明而非代码修改。第三方 skill 随上游更新，直接改它的文件会被覆盖。

本 skill 没有第三方 skill 强依赖。缺少 weread-skills 或 WEREADAPIKEY 时，只能降级为估算字数/公开评分/用户手动确认；缺少 huashu-weread-advisor 时，只是不复用其顾问方法论，仍可独立生成阅读计划。

三种输入模式

核心方法

1. 节奏按字数算，不按本数拍脑袋

「一个月 X 本」对上班族几乎必然失败。正确做法：

1. 拿每本书的真实字数：微信读书 /book/chapterinfo 返回每章 wordCount，全部加总即全书字数（/book/info 不含字数字段，别用错接口）。
2. 显式假设，用户可调：默认「工作日 30 分钟/天 + 周末 60 分钟/天 ≈ 每周 4.5 小时；阅读速度 350 字/分钟 ≈ 每周 9 万字」。把假设写进计划顶部，并告诉用户「想改节奏直接说，AI 会重排」。
3. 每本预计用时 = 字数 ÷ 每周字数，硬书（哲学/理论）在此基础上再放宽 30%。
4. 排期宁可拉长也不虚报。总量超出半年就诚实排到明年。

2. 书单要用客观数据核实，不能光凭印象

对候选书逐本拉微信读书评分（/book/info 的 newRating + newRatingDetail.title）：

• ≥ 80%（脍炙人口/好评如潮/神作）→ 放心排入
• 70–80%（值得一读）→ 正常排入
• < 70%（褒贬不一）或评分不足 → 标注存疑，给用户看并建议替代
• 同时交叉用户自己的数据：已有笔记/划线的书说明用户真读过、有感觉，优先

3. 与用户已有藏书交叉比对（别让用户重复买）

对每本候选书核对现状（真去查，不要凭书名猜）：

4. 输出用表格，直观第一

计划主体是一张大表（勾选框放行首方便打勾）：

| # | 阶段 | 书名 | 作者 | 字数 | 预计用时 | 排期 | 状态 |
|---|------|------|------|------|---------|------|------|
| 1 | 一·打底 | [[系统之美]] | 德内拉·梅多斯 | 13.7万 | 1.5 周 | 7月上 | ⬜ |

• 书名用 [[wikilink]] 连到阅读记录/书卡
• 阶段列代替多级标题，一张表看全局
• 表格下方给「为什么这个顺序」的一段话 + 假设参数 + 调整方式

5. 写给人读的计划，不暴露技术细节

计划文件面向「正在读书的用户」，不是工程师：

• ❌ 「划线用 sync_xxx.py 同步进来」
• ✅ 「读完对 AI 说『同步这本书的划线』，笔记会自动进阅读记录」

脚本名、API 名只留在本 SKILL.md，不出现在产出的计划里。

检查点（必须过用户确认再落盘）

在写文件之前，把三要素给用户看一眼：

场景「X」，选入 N 本（M 本你已有），总量约 Y 万字；按你每周 Z 小时的节奏，预计 W 个月读完，排期到 [年月]。要加减书、改节奏、改场景名吗？

存疑书（低评分/映射不确定）单独列出让用户拍板。

产出位置与 frontmatter

写入 $OBSIDIAN_VAULT 下的阅读计划目录（默认 阅读记录/阅读计划/，可按用户 vault 结构调整）：

<YYYY-MM-DD>-<场景名>.md

---
tags: [阅读计划]
title: <场景名>
scenario: <场景分类>
book_count: <n>
total_words: <总字数，万字>
pace: <每周字数假设>
created: <YYYY-MM-DD>
source: "[[<来源文章>]]"   # 模式 A/B 才有
---

环境变量

脚本优先读取 --vault <vault路径>、进程环境或私有 config.yml。可选变量名包括 OBSIDIANVAULT 与 WEREADAPI_KEY；不要在开源 skill、vault 正文或 shell 启动文件中写入实际值。

异常处理

完成后回执

回执包含：

1. 做了什么 — 一句话总结完成的工作。
2. 文件变更 — 列出新建 / 修改 / 移动的文件（完整路径）；未改动文件则说明"未改动文件"。
3. 下一步 — 可选的后续建议（如衔接的下一个 skill）。