baoyu-comic

知识漫画创作工具（Knowledge Comic Creator）

支持画风与情绪基调的自由组合，轻松创作原创知识漫画。

用户交互工具

当本 Skill 需要向用户提问时，请按以下优先级选择交互工具：

1. 优先使用内置交互工具：优先使用当前 Agent 运行时暴露的原生用户输入工具，如 AskUserQuestion、request_user_input、clarify、ask_user 或任何同效工具。
2. 降级方案（Fallback）：若无此类工具，则输出带编号的纯文本消息，引导用户回复对应序号或答案。
3. 合并提问（Batching）：若工具支持单次发起多项提问，应将所有相关问题合并为一次调用；若仅支持单问，则按优先级逐个提问。

下文中出现的 AskUserQuestion 均为示例，在其它运行时中请自动替换为对应的本地工具。

图像生成工具

当本 Skill 需要渲染图片时，按以下顺序确定生图后端：

1. 单次请求覆盖：如果用户在当前消息中明确指定了某个生图后端，直接使用该后端。
2. 已保存的偏好：如果 EXTEND.md 中配置的 preferred_image_backend 在当前环境中可用，则优先使用它。
3. 自动选择（当偏好设为 auto、未配置，或指定的后端不可用时）：
   • Codex (imagegen) — 首先检查可用 Skill / 工具列表。如果包含名为 imagegen 的 Skill，说明当前运行在 Codex 环境中，此时必须使用它：通过 Skill 工具调用（指定 skill: "imagegen"），并传入已保存提示词文件的内容（以及 Codex imagegen 所需的输出路径与宽高比参数）。Codex 的 imagegen 是该运行时的官方位图后端，其优先级高于任何非原生 Skill（如 baoyu-image-gen），除非用户显式锁定了其它 preferred_image_backend。
   • 通过 codex exec 的 Codex (codex-imagegen) — 若当前运行时未提供原生 imagegen Skill，但系统的 PATH 中包含 codex CLI 且已完成 codex login 登录，则优先通过 baoyu-image-gen --provider codex-cli 进行路由；若 baoyu-image-gen 不可用，直接调用内置包装脚本。详细信息、参数及运行时探测流程参见 references/codex-imagegen.md（仅在走到该分支时加载此文件）。
   • Cursor (GenerateImage) — 如果运行时暴露了原生的 GenerateImage 工具，说明当前运行在 Cursor 环境中，其优先级同样高于非原生 Skill。注意两个硬性限制：(a) 它不支持宽高比参数，必须在传入 description 的提示词文本中显式说明目标宽高比/尺寸；(b) 它不支持指定输出目录，生成的图片会保存在工具托管的位置，因此生成后需将文件复制/移动到 Skill 预期的输出路径（例如 outputs/.../NN-xxx.png）。参考图填入 reference_image_paths。
   • 其它运行时原生工具 — 如果运行时暴露了其它原生生图工具（如 Hermes 的 image_generate），按照相同规则使用。
   • 否则，如果仅安装了一个非原生后端（如 baoyu-image-gen），则直接使用它。
   • 否则（存在多个非原生后端且无原生工具），向用户询问一次选择（可与其它初始问题合并提问）。
4. 无可用后端时：告知用户并询问后续处理方式。

⛔ 绝不使用 SVG、HTML、Canvas 或其它代码渲染替代位图图像生成。 Codex 的 imagegen 描述中已明确指出其适用于“需要输出位图资源而非项目代码或矢量图”的场景。如果无法通过步骤 3 确定位图后端，请降级至步骤 4 向用户提问——切勿默默输出 SVG、写入内联 <svg> 标签或生成 HTML/CSS 艺术图作为替代品。即便文章/章节看起来像“图表”，调用本规则的上游 Skill 也已经明确要求输出位图。

⛔ 绝不通过覆盖绘制修改已生成的位图文字。 禁止使用 ImageMagick、Pillow、Canvas、SVG、HTML/CSS、OCR 脚本或任何代码覆盖层去遮盖、重写、擦除、加边框或替换已生成漫画页面中的对话框、音效、分镜标签或其它任何文字。如果文字出现错误或模糊，应使用修正后的提示词重新生成、重新绘制文字更少/无文字的页面，或让用户在现有不完美候选图中做出选择。

设置 preferred_image_backend: ask 会在每次运行时强制触发步骤 3 的询问，无论当前有哪些可用后端。用户可以通过下文的 ## 偏好设置修改 章节修改锁定的后端配置。

提示词文件硬性要求：在调用任何生图后端之前，必须将每张图片的完整最终提示词保存为 prompts/ 目录下的独立文件（命名格式：NN-{type}-[slug].md）。后端接收该提示词文件（或其内容）；该文件是可复现性的存档记录，同时也支持在无需重新生成提示词的情况下切换后端。

上文提到的具体工具名称（imagegen、GenerateImage、image_generate、baoyu-image-gen）均为示例，按相同规则替换为本地环境中的等效工具即可。

批量生成策略

在当前生成组的所有提示词文件均已保存并校验完毕后，默认采用批量方式生成图片。

优先级顺序：

1. 若所选后端支持原生批量/多任务接口，优先使用该接口。每个任务必须保留各自的提示词文件、输出路径、宽高比、Session ID 以及直接参考图。
2. 若后端无原生批量接口，但运行时支持并发工具调用，可单次并发发送最多 generation_batch_size 张生图请求。默认值：4。若用户在当前消息中做出显式要求（如 --batch-size 4 或“并行4张一起生成”），优先级高于 EXTEND.md 中的配置。
3. 若原生批量与并发工具调用均不可用，则采取串行依次生成。

规则：

• 严格遵守工作流依赖关系：必须先生成 characters/characters.png（角色设定图），再生成需要引用该图的漫画页面。
• 只有在所有选中页面的提示词文件均已写入磁盘后，才能开始第一批页面的生图。
• 失败项允许重试一次，无需重新生成已成功的项目。
• 禁止仅为了并行生图而创建 Subagent（子 Agent）。Subagent 应当仅用于独立的提示词迭代或创意探索。

参考图（Reference Images）

用户可以提供参考图来指引画风、配色、画面构图或主体造型。这与自动生成的角色设定图（步骤 7.1）是相互独立的——两者可以共存：用户参考图用于把控整体视觉风格，角色设定图用于固定常驻角色的形象一致性。

输入方式：支持通过 --ref <files...> 传入，或由用户在对话中直接提供文件路径 / 粘贴图片。

• 文件路径 → 复制到漫画输出目录下的 refs/NN-ref-{slug}.{ext}
• 无法获取路径的粘贴图片 → 询问用户文件路径（参考上文“用户交互工具”规则），或通过文字提取其风格特征作为降级方案
• 未提供参考图 → 跳过本节

使用模式（按每张参考图设置）：

使用模式	作用效果
direct	将该文件作为参考图直接传递给生图后端（应用于所有页面或指定页面）
style	提取画风特征（线条处理、质感、氛围），并追加到每页提示词的正文中
palette	提取 Hex 色值，并追加到每页提示词的正文中

当存在参考图时，在每页提示词的 Frontmatter 中记录：

references:
  - ref_id: 01
    filename: 01-ref-scene.png
    usage: direct

生成时要求：

• 校验引用的每个文件是否真实存在于磁盘上
• 若 usage: direct 且所选后端支持多张参考图 → 在后端的参考图参数中同时传入角色设定图（步骤 7.2）和用户参考图；请按步骤 7.1 的建议先压缩图片，避免由于 Payload 过大导致请求失败
• 若后端仅支持单张参考图 → 对于包含常驻角色的页面，优先传入角色设定图；用户参考图的特征改为嵌入到提示词正文中
• 对于 style / palette 模式 → 将提取的特征嵌入到每一页的提示词文本中（不受生图后端功能限制）

参数选项（Options）

视觉维度选项

参数	可选值	描述
--art	ligne-claire（默认/清晰线条）, manga（漫画/日漫）, realistic（写实）, ink-brush（水墨）, chalk（粉笔手绘）, minimalist（极简）	艺术画风 / 渲染技法
--tone	neutral（默认/中性）, warm（温暖）, dramatic（戏剧化）, romantic（浪漫/唯美）, energetic（活力/高昂）, vintage（复古）, action（热血/动作）	情绪基调 / 画面氛围
--layout	standard（默认/标准分镜）, cinematic（电影级）, dense（高密度/多格）, splash（跨页/大图）, mixed（混合 layout）, webtoon（条漫）, four-panel（四格漫画）	分镜排版方式
--aspect	3:4（默认/竖版）, 4:3（横版）, 16:9（宽屏）	页面宽高比
--lang	auto（默认/自动匹配）, zh, en, ja 等	输出语言
--ref <files...>	文件路径	应用于所有页面的参考图，用于指引画风/配色/构图。详见上文参考图。
--batch-size <n>	1-8	本次运行的临时单批次生图数量。默认值：优先取 EXTEND.md 中的 generation_batch_size，否则为 4。

局部工作流选项

参数	描述
--storyboard-only	仅生成分镜脚本（Storyboard），跳过提示词生成与图片渲染
--prompts-only	生成分镜脚本与提示词，跳过图片渲染
--images-only	仅基于已有的 prompts 目录渲染图片
--regenerate N	仅重新生成指定页码的图片（例如 3 或 2,5,8）

详细说明参见：references/partial-workflows.md

画风、基调与预设预制库（Catalogue）

• 画风风格 (6种)：ligne-claire（清晰线条）、manga（日漫）、realistic（写实）、ink-brush（水墨）、chalk（粉笔手绘）、minimalist（极简）。完整定义见 references/art-styles/<style>.md。

• 情绪基调 (7种)：neutral（中性）、warm（温暖）、dramatic（戏剧化）、romantic（浪漫）、energetic（活力）、vintage（复古）、action（动作/热血）。完整定义见 references/tones/<tone>.md。

• 预设模式 (5种)：在基础画风与基调之外附带专属规则：

  预设模式	对应配置组合	视觉卖点与特色（Hook）
  ohmsha	manga + neutral	视觉隐喻、拒绝大头说教（no talking heads）、道具揭示
  wuxia	ink-brush + action	气功特效、打斗视觉、意境氛围
  shoujo	manga + romantic	装饰性元素、眼神细节、情感名场面
  concept-story	manga + warm	视觉符号体系、成长弧线、对话与动作平衡
  four-panel	minimalist + neutral + four-panel layout	起承转合结构、黑白+点缀色、火柴人/简笔画角色

  完整规则详见 references/presets/<preset>.md——在选中特定预设时加载对应文件。

• 兼容性矩阵与内容特征到预设的映射表位于 references/auto-selection.md。在步骤 2 中向用户推荐组合前请先阅读该文件。

脚本目录（Script Directory）

重要提示：所有脚本均位于本 Skill 的 scripts/ 子目录下。

Agent 执行指南：

1. 获取本 SKILL.md 文件所在目录路径，记为 {baseDir}
2. 脚本实际路径 = {baseDir}/scripts/<script-name>.ts
3. 将本文档中所有的 {baseDir} 替换为实际物理路径
4. 解析 ${BUN_X} 运行时环境：若已安装 bun → 使用 bun；若可用 npx → 使用 npx -y bun；否则提示用户安装 Bun

脚本清单：

脚本	用途
scripts/merge-to-pdf.ts	将生成的漫画页面合并为 PDF 文档

文件目录结构

输出目录：comic/{topic-slug}/

• Slug：根据主题提炼 2-4 个英文单词，采用 kebab-case 格式（如 alan-turing-bio）
• 命名冲突：追加时间戳后缀（如 turing-story-20260118-143052）

目录内容：

文件 / 目录	描述
source-{slug}.{ext}	原始源文件
analysis.md	内容分析报告
storyboard.md	包含分镜拆解的故事板
characters/characters.md	角色设定与定义