热点画册批量生成 (hot-canvas-batch)

概述

两阶段，职责分明：

1. 选题（你来做，需联网+人工判断）：联网搜当日热点，挑 1-3 个流量高的选题， 为每个选题写一份 themes.json——含根图主题 + ≥10 个下钻 label。
2. 建册（脚本全自动）：build_canvases.mjs 自己挑空闲端口启动 flipbook server （强制 ENABLE_CODEBUDDY=1，用 codebuddy 出图，不依赖 OpenAI）→ 逐个建竖版 画册 → 每册根图 + 10 个 label 下钻 → 写带日期的历史记录 → 无论成功/报错/Ctrl-C 都 kill 掉 server。(脚本耗时较长，30min~1h)

何时使用

• "收集网络热点做成画册" / "批量生成画册" / "热搜做成 canvas"。
• 用户要一次产出多个画册、每册要够多图（≥10 张下钻）。

唯一铁律

选题阶段必须过滤政治敏感话题——不碰政治人物、政治制度、政府机构、选举、 地缘冲突等。只选娱乐、科技、体育、游戏、生活、文化等安全热点。这条优先级最高。

阶段一 —— 选题，写 themes.json

1. 先看已发布的主题（去重前置）：选题前先列出近 N 天已经做过的画册主题， 避免重复选题、白费搜索功夫。运行：

   node ./scripts/list_recent_topics.mjs           # 人读列表，近 90 天，最新在前
   # node ./scripts/list_recent_topics.mjs --json  # 机读 JSON
   # RECENT_DAYS=30 node ./scripts/list_recent_topics.mjs  # 收窄时间窗
   

   这个脚本直接读 topics-history/*/run.json、不起服务、不联网。把输出里的 topic + aliases 当作"黑名单"：搜热点 / 挑选题时就主动避开这些已发布主题 （含近义说法）。这样在选题阶段就完成去重，而不是等到阶段二建册时才被 SKIP。

2. 用 WebSearch 搜当日热点（如票房榜、电竞赛事、AI 动态、热门影视/综艺等）， 抓取具体事实（数字、事件、名称），这些会成为下钻 label。挑选题时对照第 1 步 的已发布列表，命中（或近义）的直接换别的热点。

3. 按 scripts/themes.example.json 的结构写一份 themes 文件。字段：

[
  {
    "topic": "根图主题（一句话，作画册根图标题）",
    "aliases": ["去重关键词1", "去重关键词2"],
    "style": "按主题挑的风格（见下方风格列表，如 popart/goldluxe/kawaii…）",
    "branches": 5,
    "drills": ["下钻子图1", "下钻子图2", "...", "下钻子图10"]
  }
]

• topic：根节点主题，会触发一张全景信息图。
• aliases：去重用的近义关键词（脚本归一化后做包含匹配）。写全一点，避免下次 换个说法又重复生成。
• style：为每个 theme 挑一个最契合的视觉风格（从下方「风格列表（12 种）」 里按"适用主题"列匹配）。这是避免产出趋同的关键——不要清一色 cinematic。同一批 多个 theme 尽量挑不同风格，特色越鲜明越好。themes.json 里的 style 字段 优先级高于命令行 STYLE=（见下方优先级）。
• drills：每条是一个下钻子图的主题 label。脚本走 /api/canvas/:id/click/upload 的 label 覆盖路径——子图内容由 label 决定，不靠点击坐标语义（坐标只用来在 画面上铺开热点锚点，避免引导线重叠）。所以 label 要写成具体、自洽的主题句。
• 至少写 10 条 drills（DRILL_PER 默认取前 10 条）。

阶段二 —— 跑脚本（单条命令，服务自启自关）

node ./scripts/build_canvases.mjs --themes /path/to/themes.json

脚本会：挑空闲端口 → spawn server → 等就绪 → 去重 → 建册 → 写历史 → kill server。 不需要你手动起服务，也不需要你记得关。

flag / env

注：批量建册默认关闭 OCR 与音频——下游 canvas-to-social 导出不消费文字层/旁白， 且二者各自给每张图增加一次额外处理开销。需要时用 ENABLE_OCR=1 / ENABLE_AUDIO=1 开回。

建议先 DRY_RUN=1 跑一遍确认选题不会被去重命中，再正式建。

视觉风格（STYLE 开关）

默认用项目原始风格（米色 isometric 信息图，即"百科知识"风）——当既没指定 themes.json 的 style、也没传 STYLE= / PROMPTS_DIR= 时生效，对应 app/prompts/ 目录。通过 STYLE= 切换风格包，支持按主题指定或全局轮询。

风格列表（12 种 + 默认）

默认风格（不传任何 STYLE/style/PROMPTS_DIR）：米色 isometric 信息图， 偏中性百科知识感，适合工具/教程/通用科普。下面 12 种是可显式切换的风格包。

重要：模型必须按主题为每个 theme 自动挑选最契合的风格（见阶段一第 4 步）， 不要清一色用 cinematic。同一批多个 theme 尽量挑不同风格，让产出有辨识度、不趋同。

使用方式

方式一（推荐）：按主题指定风格——themes.json 中每个 theme 带一个 style 字段， 模型选题时就按"适用主题"挑好，这是避免趋同的关键：

[
  {
    "topic": "顶流明星塌房始末",
    "style": "popart",
    "aliases": ["塌房", "明星八卦"],
    "drills": ["事件时间线", "粉丝反应", "..."]
  },
  {
    "topic": "新能源汽车销量榜",
    "style": "goldluxe",
    "aliases": ["新能源", "销量榜"],
    "drills": ["销量第一", "续航对比", "..."]
  }
]

不带 style 字段时，回退到命令行 STYLE= 或项目默认。

方式二：全局统一风格（整批用同一种）

STYLE=glassmorphism node ./scripts/build_canvases.mjs --themes /path/to/themes.json

方式三：多风格轮询（逗号分隔，多个 canvas 时依次轮用）

STYLE=popart,kawaii,pixel node ./scripts/build_canvases.mjs --themes /path/to/themes.json

方式四：完全自定义——复制任意 prompts-<style>/ 目录，改写后直接用 PROMPTS_DIR 指向：

PROMPTS_DIR=/path/to/my-custom-prompts node ./scripts/build_canvases.mjs --themes ...

风格包结构

每个风格对应 prompts-<style>/ 目录（位于 skills/hot-canvas-batch/ 下），包含：

• system.md — 全局视觉约束
• image-prompt.md — 风格后缀（引擎用 > 引用 + 反引号格式提取）
• planner.md — 文案风格（标题字数/正文语气）
• click-label.md、decide-search.md — 通常复用，无需修改

优先级

显式 PROMPTS_DIR=xxx > themes.json 中 style 字段 > STYLE= 环境变量 > 项目默认（米色 isometric）

去重机制（两道防线）

两个阶段都基于同一份历史数据 <app>/topics-history/*/run.json，归一化口径一致 （topic+aliases 去空格/标点/大小写后做包含匹配）：

1. 选题阶段（前置，推荐）：跑 list_recent_topics.mjs 列出近 RECENT_DAYS 天 已发布主题，搜热点时就主动避开——从源头省掉重复选题与无谓搜索。
2. 建册阶段（兜底）：build_canvases.mjs 起服务后会再扫一遍历史，对本次 themes 逐条做包含匹配，命中则 SKIP（控制台打印 SKIP "..." (recent duplicate of "...")）。

两层用同一逻辑，前置那层让你尽早换题，兜底那层保证万一漏了也不会重复生成。 所以每次换新热点即可，老主题不会被重复生成。

产物

• 画册数据：<app>/server/data/canvases/<canvasId>/（manifest / tree.json / nodes / images）。
• 历史记录：<app>/topics-history/<YYYY-MM-DD_HHMMSS>/run.json，含 {canvasId, topic, aliases, orientation, nodeCount}。不存 url——端口是临时的、 服务会被关掉，url 没有意义；要看画册时另起服务再访问 /?c=<canvasId>。

每册图片数与结构

• 根图 1 张（全景信息长卷）+ 10 个一级下钻 = 11 张，每册稳定 ≥10 张。
• 想要更多层级/更多图：建完后对某些一级子节点再 click 下钻一层（depth 2）， 或调大 DRILL_PER。

常见坑

• codebuddy planner 偶发 JSON 解析失败 → 个别下钻节点缺图（tree 有节点但 images/ 下无对应 .png）。补救：POST /api/canvas/:id/nodes/:hash/regenerate，或对根图再补 一个 label 下钻。脚本的 settle 阶段会等重试落盘。
• 每个父节点并发上限 4（server 端 MAX_PARALLEL_CLICKS_PER_NODE）。脚本按 ~800ms 间隔投递、整体串行等待，不会触顶；手动批量 click 时注意别一次性超过 4 个。
• 根图较慢：planner（联网搜索+规划，≤90s）+ 图片生成（≤180s），根图就绪通常 1-4 分钟，属正常，不要误判卡死。
• --app-dir：脚本默认从自身路径上溯 4 级定位 app 根。若把脚本拷到别处运行， 必须用 --app-dir 指向 flipbook app 根目录（含 server/src/index.js 的那层）。