soia-team soia-pkm-reading-plan
属 SOIA 个人知识管理域（
soia-pkm-*）的「加工」环节，与soia-pkm-bootstrap-vault-base（搭建）同族。
把「想读的一批书」变成「排得进日程、读得完」的计划。
客户可读说明
这个技能可以做什么
场景化阅读计划生成器。把一批书（来自文章书单、观点映射或主题）组织成带表格、按真实字数排期的可执行阅读计划，落地成 Obsidian 笔记。可选用 weread-skills 增强字数/评分/书架核实，缺少时降级估算；可选参考 huashu-weread-advisor 方法论但不依赖它。当用户说「做个读书计划」「按 XX 场景排个计划」「把这篇文章的书单排...
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 完成本技能覆盖的工作 | 读取用户请求、必要上下文和本技能正文流程，执行最小可靠步骤 | 客户会看到 Obsidian/vault 文件变更、终端日志、生成产物路径和最终回执。 |
| 缺少依赖、权限、配置或 key | 停止需要外部状态的动作，明确指出缺什么 | 安装命令、申请地址、配置路径或需要客户确认的问题 |
| 执行完成 | 汇总成功、跳过、失败、文件变更和验证结果 | 一段可复制进工单/日志的完成回执 |
客户如何使用
- 用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
- 能 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 | reading-planner | 计划的组织与落地 |
| 数据层（可选增强） | weread-skills (Tencent/WeChatReading) |
拿真实字数、评分、书架、进度；没有也能跑（体量改用公开出版信息估算） |
| 方法论层（可选复用） | huashu-weread-advisor (alchaincyf/huashu-weread) |
若已安装，选书/推荐环节沿用其「书架+笔记交叉分析」方法论与检查点原则；本 skill 不修改它的任何文件 |
| 非依赖 | book-to-skill / find-skills |
与阅读计划生成无运行关系 |
设计原则：依赖声明而非代码修改。第三方 skill 随上游更新，直接改它的文件会被覆盖。
本 skill 没有第三方 skill 强依赖。缺少 weread-skills 或 WEREAD_API_KEY 时，只能降级为估算字数/公开评分/用户手动确认；缺少 huashu-weread-advisor 时，只是不复用其顾问方法论，仍可独立生成阅读计划。
三种输入模式
| 模式 | 输入 | 任务 |
|---|---|---|
| A · 外部书单 | 一篇文章 / 现成书单 | 排序 + 分阶段 + 按字数排期 + 与用户已有藏书交叉比对 |
| B · 观点映射 | 讲道理但没列书的文章（能力框架/方法论） | 把观点拆成条目，逐条映射到书（优先用户已有藏书），再按模式 A 组织 |
| C · 主题 | 一个方向（如「投资入门」） | 先判断用户段位（若装了 huashu-weread-advisor 可借其 path 段位逻辑），再组织成计划 |
核心方法
1. 节奏按字数算，不按本数拍脑袋
「一个月 X 本」对上班族几乎必然失败。正确做法：
- 拿每本书的真实字数：微信读书
/book/chapterinfo返回每章wordCount，全部加总即全书字数（/book/info不含字数字段，别用错接口）。 - 显式假设，用户可调：默认「工作日 30 分钟/天 + 周末 60 分钟/天 ≈ 每周 4.5 小时；阅读速度 350 字/分钟 ≈ 每周 9 万字」。把假设写进计划顶部，并告诉用户「想改节奏直接说，AI 会重排」。
- 每本预计用时 = 字数 ÷ 每周字数，硬书（哲学/理论）在此基础上再放宽 30%。
- 排期宁可拉长也不虚报。总量超出半年就诚实排到明年。
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。可选变量名包括 OBSIDIAN_VAULT 与 WEREAD_API_KEY；不要在开源 skill、vault 正文或 shell 启动文件中写入实际值。
异常处理
| 场景 | 处理 |
|---|---|
| 书在微信读书搜不到 | 标「未收录」，字数用公开出版信息估算并注明「约」 |
| 书名多个疑似匹配 | 列出让用户确认，别猜 |
| 候选超 15 本 | 建议拆成两份场景计划 |
| 没有 WEREAD_API_KEY | 跳过字数/评分核实，用估算值并全部标「约」 |
完成后回执
回执包含：
- 做了什么 — 一句话总结完成的工作。
- 文件变更 — 列出新建 / 修改 / 移动的文件（完整路径）；未改动文件则说明"未改动文件"。
- 下一步 — 可选的后续建议（如衔接的下一个 skill）。