fly-dsh-illustrations

一个为中文技术文章、方法论、工作流与观点内容生成正文配图的 Codex skill。它把抽象的流程、结构、状态与认知转折，翻译成纯白背景上的怪诞手绘解释图。

默认视觉 IP 是“黑色小鲸鱼”：黑色实心、白点眼、白色腹部负形、短胸鳍、上扬分叉尾鳍和克制的空表情。它必须参与画面的核心动作，不能只是漂在旁边当装饰。

这个 skill 能做什么

• 阅读中文 Markdown、博客、帖子、Notion 文档或截图，选择真正需要配图的认知锚点。
• 先输出 1-9 张图的 shot list，再按需逐张生成 16:9 正文配图。
• 为流程、分流、闭环、前后对比、方法分层、角色状态与概念隐喻发明新构图。
• 编辑已有图片，修复鲸鱼变形、身体断裂、尾巴悬空、风格太 PPT、文字过多等问题。
• 给出建议插入位置、文件名和 Markdown 引用，方便直接放回文章。

它不适合制作照片、写实插画、海洋场景、品牌吉祥物海报、复杂架构图或标准化商业信息图。

快速开始

1. 安装到 Codex skills 目录

在包含 fly-dsh-illustrations 的父目录中执行：

skill_target="${CODEX_HOME:-$HOME/.codex}/skills/fly-dsh-illustrations"
mkdir -p "$skill_target"
cp -R ./fly-dsh-illustrations/. "$skill_target/"

如果你正在 /Users/fly/code 下工作，也可以直接复制：

skill_target="${CODEX_HOME:-$HOME/.codex}/skills/fly-dsh-illustrations"
mkdir -p "$skill_target"
cp -R /Users/fly/code/fly-dsh-illustrations/. "$skill_target/"

安装后重新打开 Codex 任务，或让 Codex 重新发现 skills。

2. 明确调用

使用 $fly-dsh-illustrations，为这篇文章选择 4 个关键段落并生成正文配图。

只要方案、不生成图片：

使用 $fly-dsh-illustrations，先给这篇文章做配图策略和 shot list，不要生图。

修复已有图片：

使用 $fly-dsh-illustrations 修复这张图。保留构图和文字，只把黑色小鲸鱼修成一个完整连续的标准轮廓。

更多可复制指令见 examples/prompts.md。

黑色小鲸鱼的硬约束

标准轮廓来自 assets/black-whale.svg，生图参考使用 assets/black-whale-reference.png。

每张图默认只出现一只鲸鱼，并同时满足：

1. 头部、鲸身、尾柄和分叉尾鳍是一个物理连续的黑色剪影。
2. 纸张、管线、绳索、箭头、机器和白色通道不得穿过或替代鲸身与尾鳍的连接处。
3. 动作物件只能连接在嘴、胸鳍、尾鳍末端或喷水等轮廓外部接点。
4. 不得出现独立尾巴、悬空尾鳍、第二个半截鲸鱼或无归属的黑色身体碎片。
5. 小鲸鱼必须用鲸身、尾巴、鳍、嘴或喷水驱动画面的核心结构。

详细视觉规范见 docs/visual-ip-guide.md。

默认视觉语言

• 画幅：16:9 横版正文配图。
• 背景：纯白，无纸纹、阴影、渐变或噪点。
• 线条：黑色手绘线稿，略有不规整感，但结构清楚。
• 色彩：橙色表示主路径，红色表示重点或风险，蓝色表示补充、反馈或状态。
• 文字：短、少、能读，不放“Workflow”“系统架构图”“常见坑”等类型标题。
• 构图：一个画面只讲一个核心结构，主体占比通常不超过约 60%。
• 气质：认真、空表情、荒诞但成立；不卖萌、不做海洋吉祥物。

推荐工作流

1. 读取全文，提炼核心判断、认知转折、输入输出闭环、前后对比和常见坑。
2. 不平均撒图，优先选择 4-8 个真正需要视觉解释的认知锚点。
3. 为每张图写清插入位置、核心意思、结构类型、小鲸鱼动作、元素与短标注。
4. 每张图单独生成，并把标准 PNG 作为角色外形参考。
5. 先缩小检查鲸鱼剪影是否连续，再检查隐喻是否一秒可读。
6. 将成图保存到 assets/<article-slug>-illustrations/，按文章顺序编号。

完整流程见 docs/article-illustration-workflow.md，提示词和故障处理见 docs/prompt-and-troubleshooting.md。

示例

下面四张图展示了这个视觉系统如何解释插件运行链路、依赖生命周期、工具调用契约与 bundle/profile 组合。它们是构图质量参考，不是需要反复套用的模板。

插件运行链路	依赖生命周期

工具调用契约	Bundle 与 Profile

目录结构

fly-dsh-illustrations/
├── SKILL.md                         # Codex 的主入口与执行规则
├── README.md                        # 安装、使用和维护说明
├── LICENSE
├── NOTICE.md                        # 上游来源与致谢
├── agents/openai.yaml               # Codex 界面元数据
├── assets/
│   ├── black-whale.svg              # 标准轮廓源文件
│   └── black-whale-reference.png    # 生图参考图
├── references/                      # 执行时按需读取的权威规则
├── docs/                            # 面向使用者和维护者的详细文档
└── examples/                        # 可复制指令与成图案例

文档导航

• SKILL.md：模型执行本 skill 时的主说明。
• 黑色小鲸鱼视觉 IP 指南：角色轮廓、动作接口、禁区和验收方法。
• 文章配图工作流：从读文章到交付图片的完整过程。
• 提示词与故障处理：生成、修复与常见失败的处理方式。
• references/black-whale-ip.md：模型使用的角色细则。
• references/style-dna.md：线条、颜色、留白与文字密度。
• references/composition-patterns.md：构图模式与原创规则。
• references/prompt-template.md：权威生成与修复模板。
• references/qa-checklist.md：逐张成图验收清单。

致谢与来源

本项目由 ian-xiaohei-illustrations.git 改造而来，感谢 Ian 对原始视觉语言、中文正文配图方法和 skill 结构的设计与公开分享。

本版本将默认角色替换为“黑色小鲸鱼”，增加了标准 SVG/PNG、连续轮廓硬约束、角色动作接口、修复提示词与独立文档。为避免混淆，本独立目录不打包上游“小黑”案例图片。详细说明见 NOTICE.md。

License

沿用上游项目的 MIT License，见 LICENSE。