Qiaomu Read Helper

Qiaomu Read Helper

把一本书变成可持续的“章节共读”流程。

何时使用

当用户想要：

• 从一本书的某一章开始共读，创建飞书文档让用户批注
• 读取飞书文档里的评论、加粗、划线或重点标记
• 在飞书评论里给用户短点评、解答、启发
• 基于用户的批注和重点，写一篇站在用户视角的乔木风格读书笔记
• 继续下一章，并沿用同一套工作流

工作流

1. 准备章节

• 确认书籍来源：本地 EPUB/PDF、已下载文件、或先调用 qiaomu-ebook-downloader 下载。
• 优先从 EPUB 目录、章节标题、正文标题定位章节边界；PDF 转 EPUB 的 index_split_003.html 不等于自然章节，必须校验真实章节标题。
• 轻度清理正文：去掉页眉页码、合并断行、保留作者原文，不改写正文。

2. 创建飞书文档

• 使用 lark-doc / lark-cli docs +create --api-version v2 创建章节文档。
• 默认每章一个文档；如果用户要长期读一本书，优先为整本书创建或复用一个飞书文件夹，再把章节文档放入该文件夹。
• 文档开头放简短“共读批注区”，提醒用户可以加粗、划线、评论。

3. 读取用户批注

• 使用 lark-drive 读取未解决评论，默认 is_solved:false。
• 使用 docs +fetch --api-version v2 --doc-format xml --detail full 读取正文样式，抽取 <b> 加粗块；若 CLI 未暴露 underline 样式，说明并让用户用评论补充定位。
• 每条评论必须结合 quote 或所在 block 的前后文理解，不要只按评论短句猜。

4. 回复评论与重点

• 对用户显式评论：优先回复原评论线程。
• 对用户加粗/划线：在对应 block 新增本地评论。
• 回复目标是“更多启发和解答”，不是长篇讲章。每条回复控制在 1-4 句，抓住上下文、方法论、可迁移的洞见。

5. 写整体读书笔记

• 汇总用户评论、加粗重点、AI 回复和章节主线。
• 站在用户视角写，像“我读这一章时意识到……”而不是客观书摘。
• 使用乔木写作风格：清晰、有结构、有洞见、有个人反应，但不装腔。
• 如本地可用，调用或参考 qiaomu-writer；否则遵循本 skill 的读书笔记结构。

执行细节

详细流程见：

• references/lark-cli-setup.md
• references/workflow.md
• references/feishu-comments.md
• references/reading-note.md

边界

• 不替用户生成大段原书内容用于公开传播；章节文档默认面向用户个人阅读批注。
• 不在未读取评论 quote / block 上下文的情况下直接回复。
• 不自动把评论标记为已解决，除非用户明确要求。
• 不把 PDF 转换分片误当作自然章节。
• 不擅自开启高风险飞书权限、删除文档、转移 owner 或公开分享。

qiaomu-read-helper

把一本书读成一场持续对话：按章节创建飞书文档，让用户批注、加粗和提问，再由 AI 结合原文上下文逐条回应，并沉淀成乔木风格读书笔记。

Turn a book into an ongoing Feishu-based reading dialogue: chapter docs, human highlights, contextual AI replies, and Qiaomu-style reading notes.

   

[中文](#中文) | [English](#english)

---

<a name="中文"></a>

中文

qiaomu-read-helper 适合深读一本书，而不是快速扫一份摘要。它把“章节文本 -> 飞书批注 -> AI 点评 -> 个人读书笔记”变成一套可重复流程，让每一章都留下可追问、可复盘、可继续生长的阅读痕迹。

首屏预览

你读完一章后，飞书里会出现这样的回应：

用户评论：
“你的叙事逻辑会影响你的行为”

原文 quote：
“夏虫”如何构想宇宙，宇宙并不在意；但“夏虫”构想宇宙的叙事逻辑，却引导着他们自身的行为逻辑。

AI 回复：
这就是全章很核心的一句。人不只是被现实塑造，也被自己讲述现实的方式塑造。相信循环，就倾向顺应和等待；相信线性进步，就倾向改造和革命。叙事不是装饰，它会变成行动脚本。

加粗重点旁边也会新增短评：

加粗原文：
山水交错、多元生境的过渡地带，是重要的制度创生地，是解读人类历史演化动力机制的核心线索。

AI 点评：
这是本章可以反复带走的一条方法论：不要只盯文明中心，也要看过渡带。中心保存秩序，过渡带制造新组合；历史演化的动力常常来自后者。

为什么值得用

普通读书助手常常停在“总结这一章”。但真正有价值的阅读，发生在你停顿、划线、反对、惊讶和追问的地方。

这个 skill 会把你的飞书评论、加粗重点和原文 quote 放在一起读。它不会只看一句“有意思”就泛泛回应，而是回到上下文里判断：这句话在章节论证里起什么作用，为什么值得标记，它能迁移到什么更大的问题。

最后，它还会基于你的真实批注，写一篇站在你视角的读书笔记。不是书摘，不是客观摘要，而是“我读完这一章后，世界图景被怎样移动了一点”。

一行安装

npx skills add joeseesun/qiaomu-read-helper

本地验证：

ls ~/.agents/skills/qiaomu-read-helper

如果你维护的是本地 skill 目录，也可以直接 clone：

git clone https://github.com/joeseesun/qiaomu-read-helper.git ~/.agents/skills/qiaomu-read-helper

你可以这样说

• “用 qiaomu-read-helper 带我读《河山》第一章”
• “把这本书第二章提取出来，写到飞书文档”
• “我读完了，读取我的评论和加粗，逐条回复”
• “也点评我加粗的重点”
• “根据我的批注和加粗，写一篇这一章的读书笔记”
• “继续下一章”

它会做什么

flowchart LR
  A["本地图书 EPUB/PDF"] --> B["定位自然章节"]
  B --> C["清理正文并创建飞书章节文档"]
  C --> D["用户阅读：评论、加粗、划线"]
  D --> E["AI 读取 quote、上下文和样式标记"]
  E --> F["回复评论线程，点评重点块"]
  F --> G["写用户视角的乔木风格读书笔记"]

具体能力：

1. 从本地 EPUB/PDF 或已下载图书中定位自然章节。 2. 避免把 PDF 转 EPUB 的 index_split_003.html 误当作“第 003 章”。 3. 轻度清理页眉页码和断行，保留作者原文。 4. 创建飞书章节文档，提醒用户可批注、加粗、划线。 5. 读取飞书评论里的 quote，结合原文上下文短回复。 6. 读取 XML 中的 <b> 加粗块，在对应 block 新增点评评论。 7. 汇总用户显式评论、无声标记和 AI 回复，写成读书笔记。

前置条件

• [ ] 已安装 Agent Skills 运行环境。
• [ ] 已安装飞书官方 CLI：lark-cli --help
• [ ] 已完成飞书配置：lark-cli config show
• [ ] 已完成飞书授权：lark-cli auth status
• [ ] 本地已有图书文件，或可使用 qiaomu-ebook-downloader 下载。
• [ ] 可选：安装 qiaomu-writer，用于更稳定的乔木写作风格。

安装飞书 CLI

本 skill 依赖飞书官方 CLI：larksuite/cli。

如果你还没有安装：

npx @larksuite/cli@latest install
lark-cli config init --new
lark-cli auth login --recommend
lark-cli auth status

如果希望减少后续权限打断，可以在明确知情后授权常用文档域或全域权限：

lark-cli auth login --scope "docs:document.content:read docs:document.comment:read docs:document.comment:create docs:document.comment:update docs:document.comment:write_only docx:document:readonly"

或者：

lark-cli auth login --domain all --no-wait --json

AI Agent 使用设备授权时，必须把 CLI 返回的 verification_url 原样交给用户，不要改写、编码或包装成别的链接。

输出示例

Created chapter doc:
https://your-domain.feishu.cn/docx/...

Read comments:
27 comment threads with quote context

Added highlight comments:
25 bold blocks annotated

Drafted reading note:
《读〈河山〉第一章：尺度、过渡带与人的意义》

读书笔记会长什么样

默认不是“章节摘要”，而是一篇站在用户视角的阅读沉淀：

# 读《河山》第一章：尺度、过渡带与人的意义

这一章最先改变我的，是尺度。作者不是从王朝、人物或制度开始，而是把我拉到地质时间里：板块挤压、青藏高原隆起、河流改道、季风形成。

我以前更容易把文明理解成“人创造出来的东西”。这一章提醒我，文明首先是在自然给定的边界里长出来的。河流不是背景，山脉不是地图上的线，它们是历史问题的生成器。

推荐共读方式

1. 让 AI 创建本章飞书文档。 2. 你读正文，在飞书里：

• 对困惑处评论
• 对被击中的句子加粗
• 对想展开的段落划线或加评论

3. 读完告诉 AI：“我读完了，读评论和加粗，回复我。” 4. AI 逐条回复评论，并给加粗重点新增点评。 5. 你继续追问，或让 AI 写整体读书笔记。 6. 进入下一章。

配置

发布与安装验证

发布者可以用 qiaomu-skill-publisher 检查这个 skill：

python3 ~/.claude/skills/qiaomu-skill-publisher/scripts/publish_skill.py ~/.agents/skills/qiaomu-read-helper --dry-run

安装者可以验证 skill 是否可发现：

npx skills add joeseesun/qiaomu-read-helper
ls ~/.agents/skills/qiaomu-read-helper

Troubleshooting

风险与边界

• 会创建或更新飞书文档、评论。
• 默认不删除文档、不解决评论、不公开分享、不转移 owner。
• 章节正文默认用于用户个人阅读批注，不建议公开传播整章原文。
• 回复必须结合评论 quote 或 block 上下文，不应只按评论短句猜。
• 如果 CLI 无法暴露某种样式标记，应该说明限制，而不是假装读到了。

仓库结构

.
├── SKILL.md
├── README.md
├── agents/
│   └── interface.yaml
└── references/
    ├── feishu-comments.md
    ├── lark-cli-setup.md
    ├── reading-note.md
    └── workflow.md

致谢

这个 skill 沉淀自一次《河山》章节共读流程。它依赖飞书官方 larksuite/cli，并可与 qiaomu-ebook-downloader、qiaomu-writer 等本地技能协同。

License

MIT

---

<a name="english"></a>

English

qiaomu-read-helper is a reusable agent skill for slow, contextual reading.

It turns each chapter into a Feishu document, lets the reader highlight, underline, and comment while reading, then asks the AI to return to the exact quote and surrounding context before replying. The final output can be a Qiaomu-style reading note written from the reader's point of view.

Install

npx skills add joeseesun/qiaomu-read-helper

Typical Prompts

• "Use qiaomu-read-helper to read chapter 1 of this book with me."
• "Create a Feishu doc for the next chapter."
• "I finished reading. Read my comments and bold highlights, then reply."
• "Write a reading note from my highlights and comments."

Requirements

• lark-cli from larksuite/cli
• A configured Feishu/Lark app profile
• Document read and comment permissions
• A local EPUB/PDF book file, or another skill that can download it

Safety Notes

This skill creates and updates Feishu documents and comments. It does not delete documents, resolve comments, transfer ownership, or open public sharing unless explicitly requested.

飞书评论与重点处理

权限

如果 lark-cli 未安装或未初始化，先按 references/lark-cli-setup.md 完成安装、配置和登录。

常用权限：

• docs:document.content:read
• docx:document:readonly
• docs:document.comment:read
• docs:document.comment:create
• docs:document.comment:update
• docs:document.comment:write_only

如果用户希望减少打断，可用：

lark-cli auth login --domain all --no-wait --json

展示 verification_url 时必须原样输出，不要改写。

读取评论

默认读取未解决评论：

lark-cli drive file.comments list \
  --params '{"file_token":"DOC_TOKEN","file_type":"docx","is_solved":false}' \
  --page-all

返回的每个 item 是一张评论卡片。正文通常在：

item.reply_list.replies[0].content.elements[].text_run.text

原文锚点优先读取：

item.quote

若 quote 为空，再看 anchor、block_id 或用评论顺序和正文重点辅助定位。

回复评论线程

显式评论要回复原线程：

lark-cli drive file.comment.replys create \
  --params '{"file_token":"DOC_TOKEN","comment_id":"COMMENT_ID","file_type":"docx"}' \
  --data '{"content":{"elements":[{"type":"text_run","text_run":{"text":"回复内容"}}]}}'

回复要求：

• 1-4 句。
• 先回应用户的观察，再补充一层上下文或可迁移洞见。
• 不要每条都写“你说得对”；变化句式。
• 不要自动 resolve 评论。

读取加粗

读取完整 XML：

lark-cli docs +fetch --api-version v2 \
  --doc DOC_TOKEN \
  --doc-format xml \
  --detail full \
  --scope full \
  -q '.data.document.content'

抽取 <b> 所在段落，并读取前后 block 做上下文。

注意：

• 飞书导出的 XML 可能不暴露 underline 样式。
• 如果未检测到 <u>、underline、text-decoration，要说明“CLI 未暴露下划线样式”，并建议用户对下划线处加评论以便定位。

给加粗块新增评论

加粗/划线是“无声批注”。处理方式是在对应 block 新增本地评论：

lark-cli drive +add-comment \
  --doc DOC_TOKEN \
  --type docx \
  --block-id BLOCK_ID \
  --content '[{"type":"text","text":"点评内容"}]'

点评角度：

• 这句话在本节论证中承担什么功能
• 它为何值得被标记
• 它能迁移到什么更大的问题
• 它与用户已有评论是否形成呼应

质量检查

写完后复查：

lark-cli drive file.comments list \
  --params '{"file_token":"DOC_TOKEN","file_type":"docx","is_solved":false}' \
  --page-all

确认：

• 显式评论线程都有 AI 回复。
• 加粗块对应新增评论数量符合预期。
• 没有因为分页只读第一页而漏掉评论。

lark-cli 安装与初始化

本 skill 依赖飞书官方 CLI：<https://github.com/larksuite/cli>

如果用户没有安装 lark-cli，先完成这一节，不要直接执行飞书文档或评论命令。

检查是否已安装

command -v lark-cli
lark-cli --help
lark-cli config show

安装

官方推荐 npm 安装：

npx @larksuite/cli@latest install

如需从源码安装，参考官方仓库：

git clone https://github.com/larksuite/cli.git
cd cli
make install
npx skills add larksuite/cli -y -g

源码安装需要 Go v1.23+ 和 Python 3。普通用户优先使用 npm 安装。

初始化配置

首次使用需要配置飞书应用：

lark-cli config init --new

如果作为 AI Agent 帮用户初始化，命令可能输出授权 URL。必须把 URL 原样发给用户，不要改写、编码、包成 Markdown 链接或补标点。

登录授权

推荐先用常用权限登录：

lark-cli auth login --recommend

对于本 skill 的共读流程，常用到文档和评论权限：

lark-cli auth login --scope "docs:document.content:read docs:document.comment:read docs:document.comment:create docs:document.comment:update docs:document.comment:write_only docx:document:readonly"

如果用户希望减少后续权限打断，可在明确同意后申请全域权限：

lark-cli auth login --domain all --no-wait --json

Agent 模式建议：

lark-cli auth login --domain all --no-wait --json
# 用户完成授权后：
lark-cli auth login --device-code <DEVICE_CODE>

验证

lark-cli auth status
lark-cli docs +create --api-version v2 --help
lark-cli drive file.comments list --help

常见问题

乔木风格读书笔记

目标

基于用户的加粗、评论和 AI 回复，写一篇“站在用户视角”的读书笔记。

不是：

• 章节摘要
• 客观书评
• 逐条评论汇总

而是：

• 我读这一章时被什么击中
• 我原来的理解被哪里改写
• 这一章给了我什么新框架
• 我会如何把这个框架带回自己的问题

写作原则

1. 第一人称：像用户自己读完后的沉淀，而不是 AI 对用户说教。 2. 有主线：从用户标记中提炼 1 条核心线索，其他内容围绕它展开。 3. 有反应：保留“原来如此”“这个视角很大”“这里让我想到……”这类真实阅读反应。 4. 有洞见：从具体句子上升到方法论，但不要飘。 5. 不过长：默认 1200-2500 字；用户要求长文再展开。

推荐结构

# 读《书名》第 X 章：标题

开头：一句总反应，说明这一章如何改变我的视角。

## 1. 我先被“尺度”击中

结合用户标记的自然史、地理、时间尺度。

## 2. 我开始理解“过渡带”的力量

结合用户标记的绿洲、草原、走廊、结构洞。

## 3. 真正让我停下来的，是人如何讲故事

结合语言、叙事、道德、意义。

## 4. 这一章留给我的问题

写用户接下来想继续追的 2-4 个问题。

乔木写作风格提示

如可用，优先调用 qiaomu-writer。若不可用，遵循：

• 句子干净，有节奏。
• 抽象概念要落回具体句子。
• 不堆术语，术语出现后要解释。
• 用“我意识到 / 我以前以为 / 这一章让我看到 / 这个说法真正厉害的地方在于”带出个人视角。
• 结尾留下继续阅读的势能，而不是总结腔。

输入整理模板

写作前先整理：

章节主线：

用户显式问题：
- quote:
  comment:
  AI reply:

用户加粗重点：
- text:
  context:
  AI comment:

反复出现的主题：
- 尺度
- 过渡带
- 叙事
- 道德

输出去向

按用户意图选择：

• 只发给用户：直接在对话中输出。
• 写入飞书：创建“读书笔记”文档，或追加到章节文档末尾。
• 长期项目：在整本书文件夹中创建 读书笔记 - 第 X 章。

共读工作流

目标

把“读书”拆成可循环的四步：

1. 章节入飞书 2. 用户阅读、加粗、划线、评论 3. AI 读取上下文并短点评 4. 生成用户视角的读书笔记

每一章结束后，用户可以说“下一章”，继续同一流程。

章节提取

输入来源

• 本地 EPUB：优先使用 EPUB 内部目录、toc.ncx、content.opf、HTML 标题。
• PDF 转 EPUB：不要信任 index_split_003.html 这种文件名；它通常只是 Calibre 分片。
• 本地 PDF：先判断是否有文本层；必要时转 EPUB 或提取文本，但要告知排版风险。
• 未下载图书：先路由到 qiaomu-ebook-downloader。

定位章节边界

建议顺序：

1. 读目录或 toc。 2. 搜索自然标题，如 第一章、第 一 章、章节名。 3. 搜索下一章标题作为结束边界。 4. 输出前后片段进行 sanity check：开头应是本章标题，结尾不应包含下一章正文。

清理原则

• 去掉页码、页眉、重复 running header。
• 合并明显由 PDF 转换产生的断行。
• 保留作者原句，不做文学性改写。
• 不强行修复所有 OCR 错字；严重影响理解时备注来源质量。

飞书文档创建

文件夹策略

未来长期共读一本书时：

1. 先用 drive +search 查是否已有同名读书文件夹。 2. 没有则用 drive +create-folder 创建。 3. 每章文档放入该文件夹。

如果用户只是临时读一章，可以直接创建到 my_library。

文档结构

推荐 Markdown 创建：

# 《书名》第 X 章：章节标题

> 共读批注区：读的时候可以直接批注你被击中的句子、困惑处、不同意处，或写下“这和我理解的世界有什么冲突/照亮”。我读完你的批注后，会围绕你的问题和反应继续陪你聊。

---

正文……

创建命令示例：

lark-cli docs +create --api-version v2 --doc-format markdown \
  --parent-position my_library \
  --content @./chapter.md

注意：--content @file 通常需要相对路径，先 cd 到文件所在目录。

回复阶段

回复前必须读取：

• 评论列表：drive file.comments list
• 正文 XML：docs +fetch --doc-format xml --detail full
• 对每条评论，优先使用 quote 字段定位原文。
• 对加粗标记，抽取 <b> 所在段落，并读取前后 block。

不要只看到用户写了“牛逼”“有意思”就泛泛回复，要解释为什么这个点值得被标记。

读书笔记阶段

当用户说“写整体评论”“写读书笔记”“总结我这一章的批注”时：

1. 汇总用户显式评论。 2. 汇总用户加粗/划线重点。 3. 提炼用户真正关心的主题。 4. 写成第一人称读书笔记。 5. 可创建新飞书文档，也可追加到本章文档末尾，先按用户意图判断。