cy-carousel: AI explainers as image carousels

# AI 科技图文轮播 讲清一个 AI 概念、一篇论文或一个产品。读者不是专业人士，要让他一张张翻下去：反差钩子 → 一个看得懂的大例子 → 一句话定义 → 三条编号思考。样板（用户认定最好的两篇，先看它们的节奏和密度）：`examples/01-ELIZA`（暗底）、`examples/02-Dots`（浅色纸底）。另有 `examples/03-聪明汉斯`（老照片＋原书书页＋论文，含完整手排脚本）、`examples/04-AI幻觉`（一场官司讲清一个概念：案卷原文纸条、聊天截图、大字定义）。 ## 红线（违反任何一条就不合格） 1. **事实可回溯**：每个数字、引文、日期都回到论文原文、官方页面或一手史料，写进 `research/事实表.md`（陈述、原句、页码/URL、状态、用在哪页）。数字的主语要对（哪个模型、在什么考卷上）；单篇论文的案例不能写成「AI 都这样」；流传但没证据的说法不写。 2. **只用开放授权素材**：公有领域、CC0、CC BY、CC BY-SA，或开放获取论文。记下原链接、许可、SHA256 和用页。不用生成的人物、无关古画、可辨认的陌生人；同一个真实人物含封面最多 3 页。 3. **图上不写出处、授权说明**。出处放置顶评论和 `来源.md`，CC BY 素材在置顶评论里署名。可以有黑底白字的人名/物件小标签；后来年份的照片要在标签里写清，别让人当成事件现场。 4. **不改原文**：纸条和截图是原样裁切，红圈、下划线是后加的标注。为了去掉半个词或无关的前后句可以涂白，置顶评论里说明。位图最多放大 1.25 倍。 5. **不用 `build.py` 的自动版式库**排页面，那套出来的页面「不如之前做的」。`build.py` 只作为渲染和断行的底层库。 6. **不发布**：脚本只出文件，不上传。 7. **参照图不外传**：参照账号/对标作者的图只在本机看和量，不上传到任何外部网站（以图搜图、在线 OCR、图床等），除非用户在对话里明确同意。 ## 版式 - **底色**：暗底 `#080808`（`check_all` 只认 ≤8 为纯黑），或浅色纸底（例 02 Dots）；一篇只用一种，不混。浅底上字直接压底，不加白框。拼贴层透明底；整页压暗的照片用 `backdrop()`，darken 0.30–0.70，不要烤进拼贴。 - **标题**：马善政毛笔两行，第一行米白 `#F3F1E9`，第二行电子青 `#00E5FF`，立体投影；英文和数字自动换黑体（`render.py` 的 `latin_font`，`headline()` 已设好）。离页面上边 ≥40px。 - **原文纸条**：论文用 `strip()` 按目标宽度矢量渲染；扫描书页用 `scan_strip()`，词框由 macOS Vision 找（`scripts/ocrfind.swift`，首次自动编译）。只截含关键词的 1–2 行，满宽贴边、不倾斜。关键词画红圈；行距密时改用下划线（`unders`）或页边红竖线（`bars`）；切进来的半个词、半行、无关前后句涂白（`whiteout`）。 - **照片和截图**：`photo()` 不倾斜，`put(..., bleed='right'|'left'|'full')` 贴页边出血，一页一个主角。 - **大字**：关键数字用 `big()`，电子青黑体 120–220px；定义页可以排成大字公式（例 01 第 7 页、例 03 第 7 页）。 - **问句贴条**：`sticker()`，青底深字，每页最多一个，≤20 字。 - **正文**：`body()` 52–66px，每页最多两段、每段 ≤60 字。**字体按题材选**：`body(font=...)` 候选 宋体粗（默认）/宋体/仿宋/楷体/文楷/苹方细；先用 `S.font_sample(同一句, 'out.png')` 出同字对比小样再定，**一篇内只用一款**（标题照旧是毛笔）。 - **排字规则**：`body(..., typo=True)`：「——」画成两段带间隙细线（每段 0.74em、推进 0.86em）、省略号画三个等距圆点、【】约 0.44em、「·」约 0.3em、正文里的数字和拉丁字母换 Times（非 macOS 找不到时回退随包 Noto Serif SC 并警告）并放大 1.07（`latin_scale` 1.05–1.10）。`justify=True` 两端对齐（增量肉眼几乎看不出：字缝最多加 0.05em、空格最多 0.5em，超了整行左对齐；先用标点挤压吸收余量）。`hscale` 横向压缩文字层（参照账号正文约 0.95，默认 1.0）；`headline/big` 也有 `hscale`。数值和原理见 `references/排字细节.md`。 - **图层顺序**：默认文字压在图上。要图片压住文字边缘时用 `Canvas(split_shadow=True)` ＋ `page(..., layer_order='text-under-images')`，顺序变成「底色 → 投影 → 文字 → 图片」。 - **emoji**：组合 emoji（1️⃣ 2️⃣ 👉）用 `S.emoji('1️⃣', 64)` 出透明 PNG 再 `put`，不要塞进正文让字体去画。 - **收尾**：毛笔金句＋三条编号思考；署名只写账号名（水印）。 ## 流程 1. **选题**：先列 2–4 个候选，比素材（人物照/截图够不够清晰、许可干不干净、能否凑够 12 份以上不同原素材）、体裁（是不是「什么是 X」或反常识）、事实风险（有没有一手出处、争议多不多），选一个。 2. **查证**：建事实表，写「不写的内容」和「争议与写法」两节。论文用 PyMuPDF 定位要上版面的原句（页码＋0–1 框）。 3. **找素材**：下载原图和论文 PDF，记许可和 SHA256，逐张看图（画面、人脸位置、能不能裁 3:4）。Wikimedia 请求放慢，遇 429 等一分钟。 4. **手排**：先出同字对比小样定正文字体；写 `制作.py`，`import 手排 as S`，`S.init(笔记目录)`；逐页用 `Canvas().put()` 摆图和纸条，用 `headline/big/body/sticker/label` 写字，`page(..., backdrop=...)` 组页，最后 `S.write_script(题目, '制作.py')` 生成 `页面脚本.json`。完整写法见 `examples/03-聪明汉斯/制作.py`。 5. **渲染**：`python3 scripts/render.py 页面脚本.json --out pages --assets-root .`；`S.preview('pages', '全套预览.jpg')` 出缩略图，逐页看：文字出界、压字、红圈标错、纸条带半截字、大块空白。 6. **对照**（有参照页时）：`python3 scripts/对照.py 参照.jpg pages/p03.png` 出左右并排图（同高）和文字行偏差表（四边、字高，1440 宽 px 与 %，超 1% 标红），按表调字号和位置再渲染。 7. **检查**：`python3 scripts/check_all.py 页面脚本.json --pages pages --assets-root .`，`errors` 必须为零。 8. **给用户看**：全套预览、对照图、小样复制到会话工作目录，直接把图发给用户（用户看不到文件面板的预览）。 9. **文稿**：标题 3 个（≤20 字）、正文、置顶评论（一手出处、几处说明、逐页配图出处）、`来源.md`。 10. **打包**：`python3 scripts/package.py --note . --pages pages --out 交付 --assets-root .`。 ## 常见坑 - 封面毛笔字里的「AI」要用黑体，否则像「刈」：用 `headline()` 就不会。 - 扫描书页常把数字认错（「14」认成「I4」），找不到词时直接传 0–1 框。 - 整页压暗底图上的文字要避开图里的关键部位（比如马鼻子和数字卡）。 - iCloud 同步目录在磁盘快满时会把文件清出本地（读文件卡死）：长任务前先看 `df -h`；被清出时先 `brctl download <路径>`，或把工程复制到本地临时目录跑，跑完再同步回来。 - 换了正文字体后标点默认用字库自带的全角标点（`tight=False`），只有宋体粗按墨迹收紧；破折号、省略号别用字库字形，开 `typo=True`。 - `hscale` 只压文字，不压图片；位图仍然只能等比缩放。