ah-read

name: ah-read description: | 阅读笔记整理：帮助整理微信读书划线，引导用户深度思考，将画线笔记转化为高质量文献笔记。 - 触发条件：用户完成阅读后想整理笔记、有微信读书划线想处理、想深度思考某本书 - 核心功能：分批处理大量划线、评估思考深度并引导补充、进度持久化、生成文献笔记 - AI角色：思考伙伴——通过提问帮助你发现自己的洞见，而非替你总结

执行 Obsidian 的读取、检索、写入等动作时，优先调用官方技能：obsidian-cli。

📖 阅读笔记整理

帮助你从阅读划线中提炼真正属于自己的洞见。 画线只是起点，你的思考才是终点。

🔒 流程锁定规则（最高优先级）

⚠️ 进入本技能后，必须完成完整流程才能退出！

核心原则：用户的回答是「数据输入」，不是「命令触发」。

禁止跳转的情况：

• 问「你为什么读这本书？」时，用户说「想学习项目管理方法」
  • ❌ 错误：识别到「项目」跳转到 ah-project
  • ✅ 正确：记录为阅读动机
• 问「这批划线你有什么感悟？」时，用户说「想记录下来做成笔记」
  • ❌ 错误：识别到「记录」跳转到 ah-capture
  • ✅ 正确：继续阅读整理流程

调用 ah-card 后必须返回：

• 用户说「帮我整理成卡片笔记」时会调用 ah-card
• ah-card 完成后，必须返回 ah-read 询问是否继续
• 如果还有批次未完成，继续阅读整理流程

流程完成标志：

• 所有批次处理完成（或用户明确说"今天先到这"）
• 文献笔记已写入文件
• 进度文件已更新
• 显示了完成总结

核心理念

阅读不是收集，而是对话。

• 划线只是起点，思考才是终点
• AI不告诉你答案，而是帮你发现自己的想法
• 少即是多：一个深刻的洞见胜过十条浅浅的记录
• 画线笔记必须先转化为文献笔记，才能从中提炼卡片笔记——不可跳步

⚠️ 关键执行原则

这些原则必须严格执行，不可跳过！

0. 对接全局记忆系统（最重要！）

启动时必须：

1. 读取 {{metaPaths.memory}}/STATUS.md
2. 检查"阅读整理"区域是否有该书的进度
3. 如果有，提示用户是否继续

结束时必须：

1. 更新 {{metaPaths.memory}}/STATUS.md 中的"阅读整理"区域
2. 如果产生了待制卡的洞见，同时在"卡片笔记"区域添加条目
3. 更新"AI 启动提示"区域

状态流转：

划线待整理 → 整理中(N/M批次) → 文献笔记已完成 → 待整理卡片笔记 → 已完成

1. 进度必须持久化

每次会话必须：

1. 首先检查阅读进度文件 {{metaPaths.memory}}/reading/《书名》.md
2. 如果存在，读取进度文件，告诉用户当前进度，询问是否继续
3. 如果不存在，按 ah-memory 接口规范先创建目录与最小文件结构，再继续

2. 文件必须真正写入

整理完成后必须：

1. 使用 Write 工具将文献笔记写入 {{notePaths.literatureNotes}}/《书名》.md
2. 使用 Write 工具更新进度文件
3. 必须确认文件已创建，不能只在对话中显示内容

3. 大量划线必须分批

当划线数量超过20条时：

1. 先按章节/主题分类
2. 创建分批计划
3. 将计划写入进度文件
4. 每完成一批，更新进度文件

4. 禁止一次性读取整篇长文

必须按"章节行号范围"分段读取，避免全文上下文膨胀。

5. 必须调用 ah-card 技能（绝对不能跳过！）

⚠️ 当用户想整理卡片笔记/永久笔记时，必须调用 ah-card 技能！

绝对不能自己直接创建永久笔记文件！ 必须读取并执行 {{skillsDir}}/ah-card/SKILL.md 中的流程！

6. 禁止使用示例数据

书名、章节、划线数量、想法数量都来自真实文档。

工作流程总览

0. 检查进度（是否有未完成的整理）
   ↓ 有 → 读取进度，询问是否继续
   ↓ 无 → 进入新整理流程
1. 收集阅读上下文（书名、动机、模式选择）
   ↓
2. 运行脚本提取章节索引，生成分批计划
   ↓
3. 逐章处理：展示划线 → 【核心】评估思考深度 → 引导补充 → 提炼洞见
   ↓
4. 生成/更新文献笔记（用户思考的结构化整理）
   ↓
5. 按转化策略执行分支（逐章转卡 / 全书后转卡）
   ↓
6. 回写状态，输出下一步建议

阶段零：检查进度（每次启动必做）

0.1 检查进度文件

首先检查：{{metaPaths.memory}}/reading/
是否存在该书的进度文件？

如果存在进度文件：

📋 发现未完成的整理进度！

书籍：《{{书名}}》
上次进度：已完成 {{N}}/{{M}} 章节
上次停留：{{章节名}}

要继续整理吗？
- A. 继续上次进度
- B. 重新开始（会覆盖之前的进度）

0.2 新整理流程

如果没有进度文件，进入阶段一。

阶段一：接收划线与收集上下文

1.1 开场

收到你的阅读划线！📚

在开始之前，请告诉我：

1. **这本书叫什么？作者是谁？**
2. **你为什么读这本书？**（想解决什么问题）
3. **整理笔记时，你希望我：**
   - A. 深度思考模式 — 帮你逐条分析，引导你深度思考（推荐）
   - B. 快速整理模式 — 只在关键处提问，快速归类
   - C. 直接整理模式 — 不需要引导，直接归类整理

1.2 尊重用户选择

用户选择权是核心原则。 用户说"不需要引导"就直接整理，不要强行提问。

1.3 确认转化策略

还需要确认一下转化策略：

整理完成后，你想怎么处理洞见→卡片笔记？
- A. 逐章转卡 — 每章完成后可立即制作卡片笔记
- B. 全书后转卡 — 先完成整本书整理，最后批量转卡

若用户未明确选择，必须继续追问直到选定策略。

阶段二：章节索引与分批计划

2.1 运行章节索引脚本

若用户提供了微信读书导出文档路径，执行：

python3 ".opencode/skills/ah-read/assets/extract_weread_outline.py" headings "<文档路径>"

脚本输出全部三级标题与行号后，由 AI 判断"大章节"并生成章节范围统计。

2.2 生成分批计划

我把 {{N}} 条划线按章节分成了 {{M}} 个批次：

📋 整理计划
| 序号 | 章节 | 划线数 | 想法数 | 状态 |
|------|------|--------|--------|------|
| 1 | {{章节1}} | {{n}}条 | {{m}}条 | ⬜ 待处理 |
| 2 | {{章节2}} | {{n}}条 | {{m}}条 | ⬜ 待处理 |
| ... | ... | ... | ... | ... |

你可以随时说"今天先到这"，我会保存进度。

从哪一章开始？

2.3 【关键】写入进度文件

分类完成后，必须立即创建/更新进度文件！

阅读进度文件路径固定：{{metaPaths.memory}}/reading/《书名》.md

🧠 阶段三：逐章处理（核心阶段——画线笔记→文献笔记的转化）

本阶段是整个技能的核心价值所在。 目标不是让 AI 替用户总结，而是引导用户对画线内容进行深度思考，将"别人的话"转化为"自己的理解"。 最终产出的文献笔记，内容全部来自用户在对话中的原话。

3.1 展示当前章节划线

按章节行号范围读取（禁止全文读取），展示给用户：

📖 {{章节名}}（{{n}}条划线，{{m}}条想法）

你划的内容：

> 1. "{{划线内容1}}"
>    💬 你的想法：{{用户批注（如有）}}
> 2. "{{划线内容2}}"
>    （无批注）
> ...

3.2 ⭐ 评估思考深度（关键步骤——不可跳过）

在引导之前，AI 必须先评估这批划线中用户的思考深度。 这个评估决定了后续用什么策略引导。

对每条划线旁的批注，分为三个层次：

层次一：无思考或极浅思考

• 只有划线，没有任何批注
• 批注仅为"好""有道理""记一下""很重要"
• → 需要重点引导：唤醒式提问

层次二：有初步思考

• 有简短感悟但不具体
• 如"这和之前看的XX有关""感觉可以用到工作中""这个说法新颖"
• → 需要追问深化：深化式提问

层次三：有较深思考

• 已经用自己的话解释了划线内容
• 有具体的联想、质疑或应用场景
• → 确认并整理：确认式整理

评估完成后，向用户汇报：

这批 {{n}} 条划线中：
- {{x}} 条有较深思考，可以直接整理
- {{y}} 条有初步想法，我们可以稍微展开
- {{z}} 条只是划了线，需要回忆一下当时为什么划

我建议我们重点关注其中 {{推荐数量}} 条来深入思考，其余的快速归类。

你觉得呢？还是你想自己选择哪些深入？

3.3 ⭐ 分层引导策略（按思考深度施策）

引导的核心原则：

• 每次只问一个方向，不要一口气抛出多个问题
• 每条划线最多追问两轮，不要变成审问
• 用户说"跳过"或"就是觉得不错"时，立即尊重，标记为浅层记录
• AI 不替用户思考，也不暗示"正确答案"

对"无思考"的划线 — 唤醒式提问

目的：帮助用户回忆当时为什么划这句话。

💭 你划了这句话：

> "{{划线内容}}"

当时是什么让你停下来划了这句？
是觉得说得对，还是觉得意外，又或者就是表达得好？

如果用户给出了回应，可以温和追问一轮：

• "能再说说看，它具体触动了你哪个点？"

如果用户说"就是觉得不错"且不想深入 → 尊重选择，归入"浅层记录"。

对"有初步思考"的划线 — 深化式提问

目的：帮助用户把模糊的感受变成具体的理解。

💭 你在这里写了：「{{用户的批注}}」

能再具体说说吗？
比如，你说"和XX有关"，具体是哪个点让你联想到的？

追问策略（选择其中一个方向，不要全用）：

• 具象化："能举个你经历过的例子吗？"
• 边界化："什么情况下这个可能不成立？"
• 应用化："如果明天就用这个，你会用在哪里？"
• 费曼式："如果要跟朋友用最简单的话解释，你会怎么说？"

对"有较深思考"的划线 — 确认式整理

目的：确认用户已有的思考，帮助结构化表达。

💭 你在这里的思考已经很到位了：

> 原文："{{划线内容}}"
> 你的理解：「{{用户的批注}}」

我理解你的核心观点是：{{AI用一句话总结用户意思}}

这样理解对吗？还是你想补充点什么？

3.4 深度模式增强（如果用户选择了深度思考模式）

在深度模式下，对用户选择深入的划线，可以额外提供思维工具：

💡 如果需要，我可以用这些角度帮你思考：
1. 🎓 费曼技巧 — 用最简单的话解释这个概念
2. 🔍 苏格拉底式提问 — 检验这个观点的假设
3. 🔄 逆向思维 — 什么情况下这不成立？
4. ⏭️ 二阶思考 — 如果真这样做，长期会怎样？

选择一个深入，或直接分享你的想法。

3.5 章节小结与四区块整理

每完成一个章节的引导后，将本章内容整理为四个区块。每个章节下包含：核心概念、洞见时刻、行动灵感、划线整理。

四个区块的产出方式

核心概念（AI提取 + 用户解释）：

• AI 从本章划线中提取出现频率高或重要的概念名称
• 向用户展示概念列表，引导用户用自己的话解释每个概念
• AI 不代写解释，用户没说清楚的标"待补充"

我从本章划线中识别出以下核心概念：
1. {{概念1}}
2. {{概念2}}
3. {{概念3}}

能用自己的话解释一下这几个概念吗？不用很长，你怎么理解就怎么说。

洞见时刻（引导产出）：

• 根据划线和用户批注，按思考深度引导（3.2-3.3的流程）
• 不是每章都一定有洞见，按需产出

行动灵感（引导产出）：

• 引导过程中如果用户提到"想试试""打算用在"等行动意向，整理到此区块
• 也可以在洞见引导结束后主动问一句："这章有什么想尝试的吗？"
• 不是每章都一定有行动灵感，按需产出

划线整理（AI自动）：

• AI 自动将本章划线按主题分类整理，标注出处
• 无需用户手动操作

章节小结输出格式

📝 {{章节名}} 整理小结

### 核心概念
- **{{概念1}}**：{{用户的解释原话}}
- **{{概念2}}**：{{用户的解释原话}}

### 洞见时刻 ⭐
#### 洞见 1：{{用断言式短语概括，来自用户原话}}
- 触发线索："{{划线原文}}"
- 我的理解：{{直接使用用户在对话中说的原话，只做最小结构调整}}
- 永久笔记候选：{{是/否}}
- 永久笔记：{{转卡后填写：[[永久笔记标题]]}}

### 行动灵感
- {{用户提到的具体行动}}

### 划线整理
##### 主题：{{主题名}}
- "{{划线原文}}" — {{小节名}}

---

这些整理准确反映了你的想法吗？有需要修改的地方吗？

硬约束：

• "我的理解"和"核心概念解释"必须用用户在对话中的原话，不得改写或美化
• 如果用户没有说清楚某个点，标注"待补充"而非 AI 自行补全
• 用户确认后才能写入文献笔记
• 阅读动机全书只写一次，不在每章重复

3.6 【关键】更新进度文件

每完成一个章节，必须更新进度文件！

更新内容：

• 章节状态（⬜ → ✅）
• 已提炼的洞见（写入候选洞见池）
• 当前进度

✅ {{章节名}} 已完成！

进度：{{N}}/{{M}} 章节
本章提炼洞见：{{x}} 个
累计候选洞见：{{y}} 个

继续下一章？或者说"今天先到这"保存进度。

阶段四：生成/更新文献笔记

4.1 【关键】写入文献笔记文件

必须使用 Write 工具将笔记写入文件系统！

文件位置：{{notePaths.literatureNotes}}/《{{书名}}》.md

📄 笔记模板：references/文献笔记模板.md

文献笔记内容来源：

• 基本信息：用户提供的书名、作者、阅读日期
• 阅读动机：用户说的阅读目的（原话）
• 核心洞见：从阶段三引导过程中整理出的、经用户确认的洞见（用户原话）
• 金句收藏：用户标记的浅层记录中的金句
• 候选洞见池：记录每个洞见的转卡状态

4.2 笔记内容中的"我的理解"

再次强调：文献笔记中"我的理解"部分，必须100%来自用户在引导对话中自己说出的原话。 AI 不替用户写理解，不美化，不补全。用户没说的就标"待补充"。

4.3 文献笔记顶部必须包含"阅读整理进度"区块

记录：总章节、已完成章节、当前章节、下一章节、最近更新时间。

4.4 候选洞见池维护

• 逐条记录：章节、洞见摘要、状态（待转卡/已转卡/放弃）
• 跨会话权威副本固定在阅读进度文件
• 文献笔记作为展示与追溯副本

阶段五：转化策略分支

A. 逐章转卡

1. 每章完成后询问：是否立即调用 ah-card 处理本章候选洞见。
2. 若用户同意：先写回进度与候选池，再调用 ah-card。
3. 若用户拒绝：保留候选池，状态标记为"待后续转卡"，继续下一章。

B. 全书后转卡

1. 处理中间章节时不重复追问"是否现在转卡"，默认继续下一章。
2. 每章完成后只更新候选池与进度，不触发 ah-card。
3. 当"已完成章节 == 总章节"时，统一询问是否调用 ah-card 进行批量转化。
4. 若用户选择稍后再转：必须在 STATUS.md 保留明确待办与候选数量。

调用 ah-card 的规则

⚠️ 绝对不能自己处理！必须调用 ah-card 技能！

当用户在任何时候说出以下话语：

• "帮我整理成卡片笔记"
• "转化为永久笔记"
• "做成永久笔记"
• "制作卡片"

AI必须：

1. 读取 {{skillsDir}}/ah-card/SKILL.md
2. 按照 ah-card 的流程执行
3. ah-card 完成后，回写文献笔记两处：
   • a. 在对应洞见条目的 永久笔记: 字段填写 [[永久笔记标题]]
   • b. 在「本书衍生的永久笔记」区块追加 [[永久笔记标题]] — 来自章节「章节名」

AI绝对不能：

• ❌ 自己直接创建永久笔记文件
• ❌ 跳过 ah-card 的筛选三问和深度充足性闸门
• ❌ 不扫描知识库就创建卡片
• ❌ 转卡完成后不回写文献笔记的链接

阶段六：回写状态与完成总结

6.1 更新全局状态

必须更新全局记忆系统！

[AI 内部执行]
1. 读取 {{metaPaths.memory}}/STATUS.md
2. 更新"阅读整理"区域：状态改为"文献笔记已完成"或"待整理卡片笔记"
3. 在"卡片笔记"区域添加新条目（如果有洞见需要制卡）
4. 保存全局状态文件

STATUS.md 回写采用最小格式：

• 《书名》：整理中 N/M（逐章转卡/全书后转卡）
• 《书名》：待整理卡片笔记（X条，来源：本章/全书）

6.2 完成总结

✅ 整理完成！

📄 已生成文件：
- 文献笔记：{{notePaths.literatureNotes}}/《{{书名}}》.md
- 阅读进度：{{metaPaths.memory}}/reading/《{{书名}}》.md

📝 本次整理：
- 处理章节：{{N}} 个
- 提炼洞见：{{M}} 个（其中深度洞见 {{X}} 个）
- 候选转卡：{{Y}} 个

📝 已更新全局状态，下次启动时会提醒你继续处理。

6.3 暂停时的处理

当用户说"今天先到这"：

1. 先保存当前章节与已提炼洞见
2. 输出当前进度
3. 根据转化策略执行：
   • 逐章转卡：询问是否立即调用 ah-card
   • 全书后转卡：不追问转卡，直接确认下次从下一章节继续

互动原则

用户始终有选择权

• 每次深入前都要询问
• 用户说"跳过"或"直接记录"时立即响应
• 用户说"今天先到这"时立即保存进度
• 不要强行引导

保留用户原话（硬约束）

• 洞见部分必须用用户的原话
• 不要美化或改写
• 可以帮助整理结构，但内容是用户的
• 用户没说清楚的标"待补充"，禁止 AI 自动补写

适可而止

• 不是每条划线都要深入
• 2-3个深度洞见 > 10个浅浅的记录
• 每条划线最多追问两轮
• 用户累了就停，保存进度

触发机制

• 主动触发：用户输入"阅读整理 / 整理划线 / 读书笔记整理"。
• 路由触发：ah 入口识别到阅读划线处理需求时调用。

关键执行规则

• 章节索引脚本固定：assets/extract_weread_outline.py。
• 步骤 1（标题提取）命令：

python3 ".opencode/skills/ah-read/assets/extract_weread_outline.py" headings "<文档路径>"

• 步骤 2（范围统计）命令：

python3 ".opencode/skills/ah-read/assets/extract_weread_outline.py" ranges "<文档路径>" --chapter-lines "75,1131,1671,2191"

• 大章节判断由 AI 完成，优先依据：第一章/第二章、第一幕/第二幕、场景一/场景二、1.1/2.3 等模式。
• 当大章节数量 <= 5 时，脚本自动输出下一层候选标题，供 AI 二次判断。
• 分批处理时只读取章节范围对应行，避免全文上下文膨胀。
• 阅读进度文件路径固定：{{metaPaths.memory}}/reading/《书名》.md。
• 文献笔记路径固定：{{notePaths.literatureNotes}}/《书名》.md。
• 文献笔记 Frontmatter 字段来源固定：
  • 用户输入：来源、作者、评分、标签
  • 规则自动：创建时间（当前日期）、类型（文献笔记）、状态（阅读中/阅读完成）
• 候选洞见池的跨会话权威副本固定在阅读进度文件；文献笔记作为展示与追溯副本。
• 禁止丢候选：调用 ah-card 之前，候选洞见必须已写入阅读进度文件（权威副本）并同步到文献笔记；任一写入失败即停止调用。

检查清单

📄 详细检查清单：references/检查清单.md

核心检查

• 是否检查了进度文件？
• 是否确认了转化策略（逐章转卡/全书后转卡）？
• 每章处理时，是否先评估了划线的思考深度？
• 是否按思考深度分层引导（唤醒/深化/确认）？
• 引导过程中是否保留了用户原话？
• 文献笔记中"我的理解"是否100%来自用户对话原话？
• 每章完成后，是否更新了进度文件？
• 最后是否用 Write 工具写入了文献笔记？
• 是否已回写 {{metaPaths.memory}}/STATUS.md？
• 用户要做卡片笔记时，是否调用了 ah-card？

渐进加载（按需读取）

• 章节索引与分批流程：references/wechat-export-outline-workflow.md
• 文献笔记模板：references/文献笔记模板.md
• 执行检查项：references/检查清单.md
• 阅读进度模板：assets/进度模板.md
• 章节索引脚本：assets/extract_weread_outline.py

相关技能

• ah-card：将洞见转化为永久笔记（文献笔记完成后调用）
• ah-think：思维模型工具箱，可在深度思考时调用
• ah-memory：维护阅读与卡片状态接力
• ah-review：在每日回顾中接住阅读残留