读一本 307 页的开源书，顺手做了 10 页会动的摘要

书是李博杰的《深入理解 AI Agent：设计原理与工程实践》，原书在 GitHub 开源（Apache 2.0），307 页、10 章，配了几十个能独立跑的实验。这种书读一遍容易忘，摘抄又只是「抄过」，不是「读过」——所以我给自己定了个复述任务：每章做一页动画摘要，做不出来就算没读懂。

10 页全部放在本站伴读页，下面拆这条生成流水线。

为什么是「生成」而不是手写 10 页

第 1、2 章是先手写的 HTML，探完路就停手了：一页 60 到 110KB，手写意味着每章重复一遍 CSS、动画器、版式，改一个全局规则要动 10 个文件。所以从第 3 章起抽了生成器，最后落成两个分层：

• kit.py（440 行）：场景套件 —— 公共 CSS、通用动画器 JS、文字盒版式原语
• kitdraw.py（268 行）：SVG 绘制层，9 个原语（box / cir / face / ln / curve / pill / lane / bar / env），全部返回 <g data-step> 节点，天然接逐拍动画
• d3.py ~ d10.py（共 2687 行）：每章一个场景数据字典，主题色、概览、场景列表
• build.py（71 行）：把数据渲染成自包含 HTML

加上 lint 和校验脚本，生成器一共 884 行，章节数据 2687 行。数据和行为分离之后，改一处全局规则只动 kit，加一个场景只动对应章的 py 文件。

流水线五步

1. 拆场景：读一章，挑出 9 到 12 个值得动画的点。每个场景先定一个视觉隐喻——台阶、VS 对照、泳道、漏斗、点阵、时间线、关系链、拟物，选不出隐喻的场景说明还没想清楚，不许只是把文字盒换成 SVG 盒子
2. 写章节数据：场景列表、每拍的文字与图形，写进对应章的 py 文件
3. 渲染：build.py 输出自包含 HTML，零外部依赖
4. 静态检查：lint.py 专门抓一种静默丢内容的写法——把 kit 原语当语句调用、返回值被丢弃，页面不报错但少一块
5. 浏览器终审：verify_all.py 用 Playwright 全量跑一遍，四条硬指标——默认完整可见、每场景至少 2 个动效步、重播播放后能复原、无控制台错误

三条铁律（SVG 动画的坑）

1. 动画器对 SVG 只能动透明度。CSS transform 会覆盖 SVG 元素自带的 transform 属性，图形直接被拍回原点
2. 探针不能用 offsetWidth / offsetHeight。SVG 元素这两个值恒为 0，要量尺寸必须用 getBoundingClientRect
3. 改文案必须复查坐标。SVG 文字不自动换行，改长一点就溢出或被裁——而且自动溢出检测查不出「文字被底边裁切」，必须逐场景截图目检

内容纪律

比技术坑更重要的是内容纪律，动画摘要最容易变成「好看的空话」：

• 场景内容必须来自原书——具体数字、代码、案例名，不编
• 场景正文控制在 170 到 330 字符，超过就是文字没删干净
• 场景内文字元素尽量不超过 8 个汉字，解释性长句下沉到场景底部的 note
• 字号基线 16px，等宽代码块 14.5px 是唯一例外

产出

• 10 页动画，共 109 个场景（第 1 章 9 个，第 2 到 9 章各 11 个，第 10 章 12 个）
• 总体积 860KB，自包含、零外部请求——断网也能看
• 打开即完整显示，点「重新播放」才逐拍动

实际收益是复习方式变了：重读一章从翻 30 页书，变成看 1 页动画。书我还会回去查细节，但「这一章讲了什么」的检索，动画页快一个量级。

判断一本书有没有读进去，可以试试这个标准：能不能把它做出来。摘抄是搬运，做成另一种形态是复述——哪里卡住，哪里就是没懂的地方。

目录在伴读页，原书请去上游仓库拿最新版，本站不托管 PDF。