把长笔记做成可离线翻阅的电子书

假设你有一份写了很久的笔记。几千字，十几个小节，存在手机里。想在等人的一刻钟里重看“河边的座椅”那一段，就得打开搜索，或者凭记忆一直滚；地铁里断了网，在线笔记连打开都成问题。更麻烦的是内容会变：你改了一句记录，之前发出去的那份旧文件还躺在聊天记录里，下次翻出来的是哪一版，自己也说不清。

这个场景里要交付的东西很具体：一本电子书。带书名和作者，带能点的目录——点“河边的座椅”直接跳到那一段；中文正文一字不少，不摘要、不改写；离线也能翻。改了内容之后，回源文件改，重新导出一版新的，发出前再核对文件版本。

本课用的笔记是一份原创的教学合成材料《周末步行笔记》：街道、观察和对话都是虚构的，约两千四百字，四个章节，有节标题、连续段落和原创引文。它专为这个练习而写，文中还故意留了一句待核对的树荫记录——第04节改源文重导，改的就是它。自己的纯文字笔记也可以沿同样的整理、生成和交接路线尝试。

先把这件事拆开：把文字变成能翻阅的书，真正需要工具做的是什么？是把标题结构变成书的结构。Markdown里的#一级标题、##二级标题，人眼看是层次，电子书里需要变成章、节和能点击的目录条目——这部分交给技能；标题怎么写、内容对不对，仍然由你决定。

本课固定使用markdown-to-epub-converter这个技能，来源是 smerchek/claude-epub-skill（github.com/smerchek/claude-epub-skill）。它不是孤零零一个说明文件：连同配套脚本、一个负责调用的转换脚本和依赖说明，打包成下文使用的“转换能力包”，02节直接下载。

它对一份笔记做四件事：读文稿里的标题，按#拆成章，##及以下生成章内小节链接；正文逐段原样放进书里；文稿最开头的元数据——书名、作者、语言——写成这本书的元数据；最后生成带目录的EPUB文件。目录层级由标题层级决定：本课两份电子书的目录都是章在第一层、章内小节并列在第二层；更深的标题会怎样，本课没有验证，不替它下结论。

这也解释了00里的需求怎么被满足：目录能点，因为标题变成了导航；离线能翻，因为EPUB是存在设备上的文件；改一句能重导，因为源文件始终在你手里，电子书只是每次导出的产物。

边界也要说清。这版技能处理的是文本结构：图片、复杂表格、脚注插件或代码块，本课没有实测，也不承诺和所有阅读器、Kindle兼容——如果你的笔记主要靠这些表达，先换一条路线。反过来，如果你手头的导出工具已经能生成可点目录的EPUB，也不必为换而换；下面02节的准备检查和03节的核对方法，对任何转换工具都是同一套。

任务定义

这次要完成的完整任务：把一份Markdown笔记变成一本EPUB电子书——书名、作者、语言取自文稿开头的元数据，正文原样保留，目录按标题生成、可以点击跳转；随后修改源文里的一个小节名和一句话，重新导出修订版；最后把修订版交给阅读器，确认改动真的能被看到。

需要准备三样东西：一台能运行Python的电脑；一个能读取本地文件、能执行Python的本地智能体——你平时把文件发给它、让它跑脚本的助手就可以；一个EPUB阅读器，本例用的是macOS自带的图书（Books）。

所有操作在一个新建的任务目录里进行，生成的电子书统一放进这个目录下的outputs文件夹。

技能安装

本课没有演示把技能“安装”进某个产品，也没有测过产品能否自动发现技能。实际做法更直接：技能文件原样放进任务目录，让智能体完整读取之后，用Python执行包里的调用脚本。

能力包保留固定技能与配套脚本，并附上本站补充的调用器convert_notes.py和依赖说明。调用器使用原版的解析和生成接口，也会拒绝覆盖已有输出；具体文件、来源和许可保留在包内及下方补充区。

技能运行需要几个Python库（EbookLib、markdown2、Pygments等）。怎么取得，包里的DEPENDENCIES.md写得很具体：优先用已经装好这些库的环境，让智能体报告实际的解释器和版本；缺了才在本机建独立环境、按包内的requirements安装。提醒一句：这条“从包索引新装”的路，本课没有在新环境里重新走一遍，包里也没有附带任何依赖的安装文件。

素材准备

上面说的能力包和笔记材料分成两个压缩包，都从下面的入口下载。纯输入包里只有初始笔记、初次请求和使用说明；能力包就是上一小节的技能部分。展开源文预览，可以完整看到《周末步行笔记》，包括文稿开头的元数据和那句待核对的树荫记录。两个包里没有现成的电子书，也没有那份修订后的源文——电子书由你生成，修订源文到第04节才登场。

把两个包解压到同一个新建的任务目录，应该能看到相邻的两个文件夹：notes-to-epub-inputs/和notes-to-epub-capability/。

先不发生成任务，发下面这条准备请求。它和能力包里的“准备请求.txt”逐字相同，可以直接复制。说明一点：这条请求是为跟练拟定的，本课没有把它实际发给模型；你原样发给自己智能体即可。就绪状态本身是实际核过的——制作时在新解包的任务目录里，用固定Python环境把模块导入、帮助命令和outputs写入各跑了一遍。

智能体读完技能和配套文件、备好依赖之后，应该报告四项结果：它实际使用的Python路径和版本；所需模块能成功导入且版本匹配；convert_notes.py --help能正常显示参数说明；任务目录下的outputs目录已创建且可写。连同源文可读，这就是“可以开始生成”的就绪标志。任何一项出问题，把实际报错原样交给智能体处理，解决了再往下走。

实际用到的依赖版本、各个库的许可，以及本课的就绪检查做到了哪一步，放在下面的补充区；主线里记住四项就绪结果和输出位置就够了。

四项都齐了，源文也能读，就可以发第一次生成请求了。

把输入包里的“初次请求.txt”原样发给智能体。跟练时沿用02核对过的Python和调用器，把初稿另存到outputs。下面的真实示范保留了当时实际返回的保存路径。

回复里有几个名称和数字值得对照源文核一遍。书名《周末步行笔记：把熟悉的街道重新看一遍》、作者“AI Navigation 教学编辑”，都来自文稿开头的元数据，不是智能体编的——书名是书名，第一章标题是章名，两者本来就不同。四个章节正好对应源文的四个#一级标题；“河边的座椅”这类##小节作为章内小节保留。初稿里那句树荫记录还是原样：“上午十点，树荫盖住了整张长椅。”它现在留着，第04节就改它。你也可以随手抽几段正文和源文对读，确认没有被摘要或改写。

这份回复是智能体自己报告的结果；初稿在制作时另外经过本课检查程序的逐字核对——正文顺序、元数据、目录条目都对得上源文，这项全量核对不是智能体做的。还要说清一步：程序读得出内容还不算完，文件后缀对、页面预览像样，都不等于阅读器里显示正常。阅读器的实际打开、跳转和重开，留到第05节交接修订版时一起验证。

如果出了状况，先回源文找原因。回复里的章节数和源文的#数量对不上，就让智能体对照源文标题和导出报告查缺了哪章；这版技能按#拆章，所以写在第一个#之前的正文进不了任何章节，两个小节重名也可能让目录链接指错位置——把标题补齐、改成唯一的名称，再重新导出。文件打不开或中文变成乱码，就把实际报错连同源文一起交回，查编码和文件结构。这几条是遇到问题时的处理建议，本课的主线没有走到它们。

初稿核对完，该改两处。材料里那句“上午十点，树荫盖住了整张长椅。”被标为待核对记录；本课制作负责人作出的编辑选择，是将它改为：“上午十点，树荫只盖住长椅靠河的一半。”小节名“河边的座椅”也一并改成“河边座椅与树影”：那一段讲的既是座椅，也是树影的移动，改后的名字更贴内容。改名有个连带动作——正文里还有两处提到“河边的座椅”（开头说能从目录迅速找到它，结尾请朋友特别看那一节），目录名一改，这两处回指必须同步改，否则同一篇文章里出现两个叫法，读者对不上号。

改动只发生在Markdown源文上，另存为一份修订源文；初始源文和初稿电子书都不动。这份修订副本的来历交代一下：它由本课制作负责人预先准备，属于合成材料的编辑决定。所以流程上没有“智能体自己发现错误再修改”，也不是要你想象成刚刚亲手改完——跟练到这一步时，改源文的动作由你在自己的副本上完成；本课则是初稿检查完之后，才把修订副本交给新会话。

导出交给一个新的会话做。新会话没有上一次的记忆，“上次那个文件”这类话它无从查起，所以请求里把该说的说完：用哪份源文、书名作者沿用、初稿保留、修订版另存、改了哪里要核对。这也是你以后换会话、换工具时的交接方式——把修订源文、初稿和转换能力包一并交给新会话，沿用02核对过的环境后再发请求，不依赖隐含的上下文。

这一轮拿到的是区块里的实际程序返回和修订版文件，要如实说明的是：转换器正常返回，修订版EPUB也确实生成了，但这轮会话在生成之后没能给出正常的最终回复。本课保留这个不完整的结果，没有为它重跑；文件本身随后由检查程序逐字对照修订源文核对通过。区块里是实际发生的程序返回和文件，不是一段补写出来的聊天回复。

拿到修订版后核对四处：目录里的小节名变成“河边座椅与树影”；正文两处回指同步更新；树荫句是改后的说法；书名、作者不变。初稿电子书应该还在——调用器拒绝覆盖已有输出，修订版是另存的新文件，两版文件名分开保留，阅读器里再核对修订目录和这句记录。

现在手里有两本电子书：初稿和修订版。交给别人的应该是修订版——开头说的“改了一句还把旧版发出去”，发之前核对文件名，再在阅读器里确认修订句。

本课实际的阅读器验证在macOS的图书（Books 9.0）里完成。把修订版导入，从目录点进“河边座椅与树影”，正文里能看到那句修订句；关闭这本书，再从同一个修订文件重新打开——恢复到的阅读位置上，仍然是那句修订句。重开之后没有再点目录，阅读位置是恢复出来的。初稿也做过一轮导入、跳到第二章和关闭重开，其中重开时窗口一度落到另一块屏幕上，回到原来的屏幕后才继续核对——该次环境检查失败的记录继续保留。

这次实测的范围要说准：以上是Books 9.0里这几个指定动作的结果——导入、目录跳转、中文正文显示、关闭重开。整本书逐页的排版效果、其他阅读器和其他设备会怎样，本课没有测，不能替它们打包票。

交接时留两句话给对方：只想读的，发电子书就行；还想一起补写的，把Markdown源文一起给，并说明哪份是这次的成品。以后每次改动，都回源文改、重新导出新文件，不直接改电子书。

路线本身不用换：02下载的能力包和已经就绪的Python环境继续用，把自己的笔记存成一个Markdown文件放进任务目录，输出另起一个新文件名，然后按03的方式发请求——输入输出路径写清楚就行。

给自己的笔记做书之前，有两处值得先整理。标题层级就是目录：#一级标题拆章、##二级标题变章内小节，通篇没有分章标题时，先补标题再转换；书名、作者、语言照本例的格式写在文稿开头的元数据里，和正文的章标题分开。章名和小节名用唯一的、能辨认内容的说法，重名会让目录指不清。

生成之后，围绕你自己的用途检查：目录能不能点到最常要找的段落；引文和正文是不是原样保留；以后改动时，像04那样改源文、另存新文件，并确认接收者打开的是新版而不是上一版。换了电脑或重装过环境，先重做02的四项就绪检查再生成。

范围还是那一条：这版技能实测过的是纯文字的中文笔记，图片、复杂表格、脚注插件或代码块没有实测，不承诺和所有阅读器、Kindle兼容；如果你的笔记主要靠这些表达，先改选路线。缺章、乱码这些状况，按03的办法处理——先回源文，把实际问题交给智能体，再重新导出。