# Soia Pkm Reading Plan

> 把书单、主题或观点映射组织成按字数排期的可执行阅读计划，并落为 Obsidian 笔记。触发：「做读书计划」「书单排期」「规划下半年阅读」

- Skill: `soia-team/soia-pkm-reading-plan` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add soia-team/soia-pkm-reading-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soia-team/soia-pkm-reading-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: soia-team (https://skillmd.com/u/soia-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/soia-team/soia-pkm-reading-plan

---


# soia-pkm-reading-plan

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

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

## 客户可读说明

### 这个技能可以做什么

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

| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 完成本技能覆盖的工作 | 读取用户请求、必要上下文和本技能正文流程，执行最小可靠步骤 | 客户会看到 Obsidian/vault 文件变更、终端日志、生成产物路径和最终回执。 |
| 缺少依赖、权限、配置或 key | 停止需要外部状态的动作，明确指出缺什么 | 安装命令、申请地址、配置路径或需要客户确认的问题 |
| 执行完成 | 汇总成功、跳过、失败、文件变更和验证结果 | 一段可复制进工单/日志的完成回执 |

### 客户如何使用

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

### 依赖与安装

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

```bash
claude plugin marketplace add soia-team/soia-open-skills
```

```bash
claude plugin install soia-pkm-vault@soia
```

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 `~/.agents/skills`；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

```bash
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-reading-plan -y
```

配置约定：

```text
~/.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](https://github.com/soia-team/soia-open-skills/blob/main/docs/install/workbuddy.md)。

### 日志与完成回执

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

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

日志摘要：
- 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 本」对上班族几乎必然失败。正确做法：

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. 输出用表格，直观第一

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

```markdown
| # | 阶段 | 书名 | 作者 | 字数 | 预计用时 | 排期 | 状态 |
|---|------|------|------|------|---------|------|------|
| 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`

```yaml
---
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 | 跳过字数/评分核实，用估算值并全部标「约」 |


---

## 完成后回执

回执包含：

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