joeseesun/qiaomu-read-helper

# qiaomu-read-helper [](https://github.com/joeseesun/qiaomu-read-helper/stargazers) [](https://github.com/joeseesun/qiaomu-read-helper/commits/main) [](LICENSE) [](SKILL.md) **[中文](#中文) | [English](#english)** ## 中文 `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 中的 `` 加粗块，在对应 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](https://github.com/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. 进入下一章。 ## 配置 | 项目 | 必需 | 说明 | |---|---:|---| | `lark-cli` profile | 是 | 用于创建、读取、评论飞书文档 | | 飞书 OAuth scopes | 是 | 文档内容、评论读取、评论创建 | | 本地图书路径 | 否 | 用户可直接提供，也可先下载 | | `qiaomu-ebook-downloader` | 否 | 未下载图书时使用 | | `qiaomu-writer` | 否 | 写读书笔记时增强乔木风格 | ## 发布与安装验证 发布者可以用 `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 | 问题 | 原因 | 解决 | |---|---|---| | `command not found: lark-cli` | 未安装飞书 CLI 或 PATH 未生效 | 运行 `npx @larksuite/cli@latest install`，重开终端后再试 | | `config not found` | 尚未初始化飞书应用配置 | 运行 `lark-cli config init --new` | | 读不到评论 | 缺少 `docs:document.comment:read` | 运行 `lark-cli auth login --scope "docs:document.comment:read"` | | 能读评论但不能回复 | 缺少 `docs:document.comment:create` | 授权评论创建权限，或在明确同意后用 `--domain all` | | 加粗能读到，下划线读不到 | 飞书 XML 导出未暴露 underline 样式 | 对下划线处加一个短评论，让 AI 通过 `quote` 精确定位 | | 章节切错 | PDF 转 EPUB 分片被误当章节 | 搜索自然章节标题和下一章标题重新切分 | | `@file` 路径无效 | `lark-cli` 要求相对路径 | `cd` 到文件目录后用 `@./chapter.md` | ## 风险与边界 - 会创建或更新飞书文档、评论。 - 默认不删除文档、不解决评论、不公开分享、不转移 owner。 - 章节正文默认用于用户个人阅读批注，不建议公开传播整章原文。 - 回复必须结合评论 `quote` 或 block 上下文，不应只按评论短句猜。 - 如果 CLI 无法暴露某种样式标记，应该说明限制，而不是假装读到了。 ## 仓库结构 . ├── SKILL.md ├── README.md ├── agents/ │ └── interface.yaml └── references/ ├── feishu-comments.md ├── lark-cli-setup.md ├── reading-note.md └── workflow.md ## License MIT ## 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](https://github.com/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.