draw-prompt

把一句话画图需求，转化成高质量、可稳定复现、可直接交给下游出图的 gpt-image-2 Prompt / handoff 指令。

默认只产 Prompt，不出图。 出图交给下游（/codex-image:generate、codex exec、 或 gpt-image skill）。当用户接受高成本择优时，best-of 可以接入真实 renderer， 同时生成 direct 与 skill 候选，记录评分并只交付胜出的最终图。

快速上手（前 5 分钟）

# 1) 装到你的 agent（Claude Code 或 Codex）的 skills 目录
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest install-skill --target claude

# 2) 自检：确认包文件、版本、核心转化链路都 OK
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest doctor

# 3) 产出第一条 prompt（直接给 gpt-image-2 出图）
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest convert "茶饮新品海报，写冷泡系列，价格 16/19 元"

装好后在 Claude Code 里直接说画图需求（如「按我的风格写个茶饮新品海报的生图 prompt」）就会触发。

运行环境：优先装 uv，它会自动处理 PEP723 依赖、运行链路最稳； 没有 uv 时退回 python3（≥3.9）也能跑核心转化。注意：overlay / visual-check / edit-check 这几个像素级命令需要 Pillow，缺它时会给出明确提示——core 的 convert / lint / handoff 不需要它。

为什么是这个分工

| 能力 | 谁负责 | |---|---| | 自然语言画图需求 → 高质量 Prompt / handoff | draw-prompt（本 skill） | | 原始意图保真、只做质量增强 | draw-prompt（本 skill） | | Prompt 转化质量检查 | draw-prompt（本 skill） | | 记录风格偏好、采纳/弃用样本、评分 | draw-prompt（辅助能力） | | 把 Prompt 变成图 | 下游：Codex（/codex-image、codex exec）或 gpt-image CLI；best-of --renderer-cmd 可编排真实出图与择优 |

主入口是 convert：需求理解 → 细分模板 → 结构化 Prompt Spec → Prompt 渲染 → lint 自检 → handoff 交付。真实用户场景由一组专门入口覆盖：compose 处理长输入拆多图， variants 处理同一输入的多风格探索，series 处理系列图一致性，edit 处理参考图/改图， brand / character 处理品牌和角色一致性，data-viz 处理数据图表，rewrite 处理烂 prompt 改写，adapt 处理多尺寸适配。 默认输出是一阶段 single-pass prompt，保留用户原文并让 gpt-image-2 直接生成完整图。 只有当用户明确要求“文字必须绝对精确/可后处理”时，才用 --strict-text 输出 visual prompt + text_overlay_spec 作为兜底。完整方案见 references/conversion-skill-plan.md。

如果目标是“最终图必须优于直出”，使用高成本 best-of：它会同时产出 direct baseline、 默认 skill_default_style 候选、多个补充 skill 候选 prompt、每张图的 handoff、文字 overlay 兜底信息， 并可通过 --renderer-cmd 调用真实出图通道。宿主 agent 看图后用 --scores 或 --winner 回填选择结果；只有候选胜过 direct 才交付，候选没赢时继续修订或返回 direct。只需要执行计划时用 ab-plan。

两条路径（理解靠 LLM、渲染靠脚本）：

• 主路径（有宿主 Claude 时）：宿主 Claude 在理解阶段直接按 references/spec-schema.md 填好结构化的 Spec（品类、画幅、硬文案、版式、 风格锚点、负向约束等），再交给 render --spec 做确定性渲染——语义判断靠 LLM、 排版渲染靠脚本，同一个 Spec 渲染出的 prompt 可复现。
• fallback 路径（纯命令行 / CI / 无 LLM 时）：convert / compose 内部用一组 正则/关键词推断（route_asset_type、extract_required_texts、infer_* 等，源码里 标注为 no-LLM fallback heuristic）把自由文本猜成 Spec 再渲染。理解全靠正则， 质量次之，但保证脱离 LLM 也能跑、行为稳定。

两条路径共用同一个确定性渲染器与同一套 lint / intent-check 质量门，只是「谁来填 Spec」不同。

Prompt 的默认结构是三段：User visual brief 原始视觉需求、Style / quality envelope 风格质量层、Intent preservation 意图保真层。风格质量层只能控制视觉语言、质感、光照、 配色、留白、层级和可读性；一旦和用户原始需求冲突，永远以用户原始需求为准。 默认情况下，CLI 还会按场景自动注入 style_recipe：PPT、路线图、架构图、产品图、SaaS UI、 信息图和海报各有一套结构化配方，覆盖构图、字体层级、图标密度、留白、配色和负向约束。 这不是改写用户需求，而是让默认 style 不只是一组形容词，而是一套可执行的视觉生成策略。

npx 使用

发布到 npm 后可以直接：

npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest status
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest doctor
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest convert "茶饮新品海报，写冷泡系列"
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest install-skill --target codex

npx 包内置同一份 Python CLI 和 references。执行时优先使用 uv run 自动处理 PEP723 依赖；没有 uv 时退回 python3。overlay、visual-check、edit-check 需要 Pillow，推荐用户安装 uv 获得最稳运行链路。 显式 --registry=https://registry.npmjs.org/ 是为了避开公司/镜像 registry 的同步延迟； 如果你的 npm 默认 registry 已经是公网 npm，也可以省略。

如果当前目录就是本仓库源码目录，npx @yuhan1124/draw-prompt ... 可能被 npm 解析到同名本地 package 而失败；本地开发请直接用 node bin/draw-prompt.js ... 或 python3 scripts/prompt_cli.py ...。

visual-regress / benchmark 用到的回归集只保留在开发仓库本地，不随 npm 包发布。

安装 skill

普通用户优先从公网 npm 安装到 agent 的 skills 目录：

# 安装到 Codex：~/.codex/skills/draw-prompt
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest install-skill --target codex

# 安装到 Claude Code：~/.claude/skills/draw-prompt
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest install-skill --target claude

# 同时安装两边；更新已有安装时加 --force
npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest install-skill --target both --force

install-skill 默认复制 npm 包内的运行文件，避免软链到 npx 缓存导致后续路径失效。它只复制 SKILL.md、CLI、references 和必要元数据；开发仓库里的 tests/、tmp/、golden-cases.jsonl、 visual-cases.jsonl 不会进入 npm 包或安装目录。安装后可直接跑 doctor，它会检查 包文件、版本一致性、核心单图转化、真实长输入 compose 链路，以及 variants / series / adapt 等主工作流 smoke。 brand / character / data-viz / edit / rewrite 这类主入口也在 doctor 中做命令级 smoke。

开发者本地调试也可以软链 repo：

# 克隆/进入本 repo（这里假设在 ~/Desktop/draw-prompt）
ln -s ~/Desktop/draw-prompt ~/.claude/skills/draw-prompt

依赖：uv（推荐，PEP723 自动装 pyyaml）或 python3。检查环境：

node bin/draw-prompt.js status
# 或
python3 scripts/prompt_cli.py status

怎么用

在 Claude Code 里直接说画图需求即可触发，例如「按我的风格写个茶饮新品海报的生图 prompt」。agent 应优先使用 convert 产出可执行 prompt / handoff；需要更高抛光时再读 references/compile.md 和 references/gallery.md 做人工增强。出图后可把反馈写回 Harness，作为下一次转化的辅助信号。

核心原则：用户原始意图是 source of truth。本 skill 只扩充画幅、构图、质感、光照、 配色、层级、可读性和模型可执行细节；不得替用户改变主题、布局、栏目顺序、信息结构， 也不得新增用户没有要求或没有直接暗示的模块、人物、品牌、图表、文案或故事元素。 需要控风格时用 --style、--style-preset、--style-strength 或 variants --style-presets， 它们只进入风格质量层，不改写需求主体。未指定风格时会自动选择默认 style_recipe； 复杂文字/标签场景自动降到 light，产品/海报等轻文字场景可走 strong。

内置风格预设已扩展到 420 个，可用 styles --json 查看完整清单和默认 style recipe；常用类别包括：

| preset | 作用 | |---|---| | corporate | 克制企业汇报、网格和演示文稿质感 | | premium | 高级编辑感、控制配色和留白 | | minimal | 极简、低噪音、强层级 | | flat-vector | 现代扁平矢量、图标/信息图一致笔触 | | photoreal | 写实渲染、自然材质和光照 | | clean-ui | 产品级 UI 视觉语言、组件一致性 | | editorial / cinematic / isometric | 编辑设计、电影感、等距插画 | | technical-blueprint / data-journalism | 技术蓝图、数据新闻图 | | hand-drawn / watercolor / monochrome-ink | 手绘、水彩、黑白墨线 | | retro-print / bold-typographic | 复古印刷、强字体海报 | | luxury-product / soft-3d | 奢侈品广告、柔和 3D 插画 |

CLI 速查

convert "自然语言画图需求" [--style-preset premium] [--style-strength medium] [--strict-text] [--out p]
doctor                                                       # 安装后运行时自检：包文件、版本、核心场景转化
compose "长输入/文档内容" --max-images 6                     # 长输入 → 多图视觉计划
variants "自然语言画图需求" --style-presets all              # 同一输入 → 多风格 Prompt 组
ab-plan "自然语言画图需求" --candidate-count 5 --out-dir ab   # 高成本 A/B：直出基线 + 默认 style + 多候选 + 择优规则
best-of "自然语言画图需求" --candidate-count 5 --out-dir run  # 高成本闭环：生成候选、可接 renderer、评分后选择赢家
styles --json                                                # 查看内置风格预设
series --brief "图1" --brief "图2" --style "…"               # 系列图 → 风格一致 Prompt 组
edit --goal "改图目标" --reference product:ref.png            # 参考图/改图 → 编辑 Prompt
brand --name "品牌名" --request "品牌主视觉"                  # 品牌一致性档案 + 可选编译
character --name "角色" --description "…" --scene "…"        # 角色 bible + 场景 Prompt
data-viz --file metrics.csv --request "展示趋势"              # 数据/报表 → 信息图 Prompt
data-viz --request "W1 12%, W2 18%, W3 21%"                  # 无文件时从需求内提取轻量数据点
rewrite "低质量 prompt"                                      # 烂 prompt → 结构化高质量 Prompt
adapt "画图需求" --aspects 1:1,3:4,16:9,9:16                 # 同需求 → 多尺寸适配
overlay --image out.png --spec spec.json --out final.png      # 按 overlay spec 精确叠中文字
visual-check --image final.png --spec spec.json               # 单图质量门：尺寸/画幅/亮度/对比度
edit-check --reference ref.png --output edited.png            # 改图质量门：主体保留 + 有效变化
intent-check --request "原始需求" --prompt "生成prompt"       # 检查是否新增/偏离用户未要求内容
visual-regress references/visual-cases.jsonl                  # 开发仓库本地：多场景/多输出 prompt 回归，支持 expect_/forbid_ 断言
lint --prompt "…" [--asset-type poster] [--text 必显文字]    # 生图转化硬约束检查
benchmark references/golden-cases.jsonl --runs 3             # 开发仓库本地：golden cases 稳定性基准
revise --sample-id last --reason text_error                  # 按失败分类修订 Prompt
profile show|init|set KEY VAL|note "…"|path     # 风格偏好档案
samples add|search "…"|list                     # 出图样本库（few-shot；add 可带 --size/--quality）
feedback [id|last] --verdict reject --category text_error    # 回填采纳/弃用和失败分类
judge rubric|record|list                         # 评分回路（agent 评分、CLI 存储）
handoff --request "…" --prompt "…" [--record-pending]       # 手写 prompt 转下游指令
status                                            # 数据 + 下游通道健康检查

实际场景覆盖

| 场景 | 命令 | 覆盖点 | |---|---|---| | 长文档/会议纪要/PRD 整理成多张图 | compose | 自动拆信息单元、路由海报/架构/信息图/UI/插画、整组共享风格 | | 密集中文标签架构图/流程图 | convert / compose | 自动切换到文字优先的宽横条布局，减少窄卡片导致的中文短语换行 | | 同一个输入探索多种风格 | variants | 同一 User visual brief，输出多个只改变风格质量层的 prompt/handoff | | 一次生成一组风格统一的图 | series | 共享 style/palette，逐张输出 spec/prompt/handoff | | 图文混排资产、中文标题、价格、标签 | convert / compose | 默认 single-pass，保留原文并要求模型清晰渲染；绝对精确时再加 --strict-text | | 参考图/改图 | edit | 明确 reference、preserve、change，防止身份和构图漂移 | | 品牌一致性 | brand | 生成品牌 prompt block，强调原创标识和禁用真实商标 | | 角色/IP 一致性 | character | 角色 bible、参考表、场景图 prompt，避免已有 IP 相似 | | PPT/汇报页/演示文稿单页 | convert | 路由到 slide，single-pass 保留用户显式区域、栏目结构、图标语义、页脚和中文文案 | | 数据可视化/报告图 | data-viz | 读取 CSV/TSV/JSON；无文件时可从请求中的 W1 12% 这类轻量数据点生成图表 prompt | | 烂 prompt 改写 | rewrite | 重新结构化资产类型、布局、材料、光照、否定项和安全改写 | | 多尺寸投放 | adapt | 同一主体和文案适配 1:1、3:4、16:9、9:16 等画幅 | | 品牌/版权/风格风险 | convert / rewrite | 把内置词表里已知的真实 IP/品牌引用改写成原创视觉语言并加避让项（非完备过滤，见下方「安全与边界声明」） |

出图稳定链

所有场景的默认质量门是：

1. convert / compose / series 等入口默认生成 single-pass prompt：原文需求独立成 User visual brief，风格和质量只作为 envelope 追加，不拆掉或重写用户需求。
2. intent-check 检查 prompt 是否新增用户未要求内容，或把用户否定项又正向写回 prompt。
3. 对中文标题、价格、图表标签、品牌名等，默认仍让模型直接渲染；prompt 会逐字引用并要求清晰可读。
4. 只有当用户明确要求“文字必须绝对准确/可后处理”或出图反馈属于 text_error 时，才切到 --strict-text + overlay 两段式兜底。
5. 用 visual-check 验证成品图尺寸、画幅、亮度、对比度和基础细节。
6. 参考图改图用 edit-check 验证“主体保留 + 背景/目标确实变化”。
7. 模板或策略变动后，在开发仓库本地跑 visual-regress references/visual-cases.jsonl，确认多场景回归通过；它会真实编译 convert、rewrite、edit、variants、series、adapt、compose、brand、character、data-viz 等单图/多输出入口。用 expect_count、expect_asset_type(s)、expect_aspect(s)、expect_required_text(_all)、forbid_required_text、expect_safety_rewrite、expect_prompt_contains、forbid_prompt_contains 把真实场景的产品意图固化成门禁。

这条链路的默认目标不是替 gpt-image-2 重做排版引擎，而是减少跑偏、遗漏和廉价风格； 两段式 overlay 只是文字极端稳定性兜底，不作为普通用户的默认体验。

高成本 best-of 择优链

当用户接受额外成本并要求“最终效果必须比直出好”时，不再只交付一个 prompt，而是：

1. best-of 生成 direct 原始需求直出基线。
2. 同时生成默认 skill_default_style 候选，它使用场景 style_recipe 控制构图、字体、图标、留白和配色。
3. 继续生成 3-5 个补充候选：结构优先、风格优先、产品/UI 专项、轻增强、文字安全 overlay。
4. 宿主 agent 用 Image 2 真实生成所有图，或用 --renderer-cmd 接入可执行的出图命令。
5. 视觉评审按意图保真、视觉质量、默认风格收益、结构匹配、文字风险、未请求内容风险打分，并用 --scores / --winner 回填。
6. 只有候选在意图保真不低于 direct 的前提下明显更好，才交付候选；否则继续修订或返回 direct。

示例：

python3 scripts/prompt_cli.py best-of \
  "画一张 16:9 产品路线图，主题：研发质量治理平台路线图，按 Q1-Q4 展示关键能力" \
  --candidate-count 5 \
  --out-dir ./best-of-run \
  --renderer-cmd 'your-image-renderer --prompt-file {prompt_file} --out {out}' \
  --json

如果当前宿主已经有内置 Image 2 工具，也可以先跑 best-of 生成候选清单，再由 agent 真实出图， 看图后用 --winner skill_default_style 或 --scores @scores.json 写回同一运行目录。

Harness：三层偏好，越用越贴合你

数据都在 ~/.local/share/draw-prompt/（可用 DRAW_PROMPT_HOME 覆盖，不进 git）：

1. 偏好档案 style_profile.md：长期口味（default_style_preset、常用风格、默认画幅/质量、排斥元素）。
2. 样本库 samples.jsonl：每次出图的采纳/弃用记录，作 few-shot 参照。
3. 评分回路 judgements.jsonl（可选）：成品图四轴打分，沉淀质量轨迹。

实现边界（请如实理解）：convert 真正自动读取的只有 ① 偏好档案里的结构化字段—— 写进 profile 的默认画幅 / 风格预设 / 排斥项会直接改变下一次产出。② 样本 few-shot 的「借用」和 ③ 成品图打分，都由 agent（具备视觉与检索能力） 在工作流里完成；CLI 只负责存储这两层， 自己不看图、不检索样本。除显式 best-of --renderer-cmd 外，CLI 不调用任何出图通道。也就是说「越用越贴合你」依赖 agent 持续把反馈写回 这三个文件、并在下一次转化时主动参考；如果你纯命令行单独用 convert，只有 ① 会自动生效。 详见 references/harness.md。

把 Prompt 交给 Codex 出图

uv run scripts/prompt_cli.py convert \
  "茶饮新品海报，国风一点，写冷泡系列，价格 16/19 元" \
  --out poster.png --record-pending
# 输出 single-pass prompt + lint + intent_check + /codex-image:generate ...

开发仓库本地跑稳定性基准：

uv run scripts/prompt_cli.py benchmark references/golden-cases.jsonl --runs 3

三条下游通道与 gpt-image-2 模型锁定的说明见 references/codex-handoff.md。

安全与边界声明

请按实际能力使用，别把下面几项当成"完备保证"：

• IP / 品牌改写不是版权过滤器。rewrite / convert 的安全改写基于内置词表，覆盖常见名称 （迪士尼、米老鼠、星巴克、宝可梦、皮卡丘、哈利波特、Nike、Apple、可口可乐、乐高 等）； 长尾 IP、明星肖像、特定作品仍可能漏网。它降低风险、不构成法律合规保证——最终出图前请人工把关。
• intent-check 是有界的辅助检查，不是任意语义的完整保证。它覆盖一组预定义高风险类别的 "否定写回"和"未请求注入"（人物 / 图标 / 卡片 / 图表 / 栏目 / 模块 / 品牌板 / logo / 二维码 / 水印 / 价格 / 背景场景 等），并对常见否定词（不要 / 别 / 去掉 / 避免…）做匹配。超出这些类别的偏离， 应由 agent 或人工做最终意图判断。
• Harness 会在本机落盘。偏好 / 样本 / 评分写入 ~/.local/share/draw-prompt/ （可用 DRAW_PROMPT_HOME 覆盖），仅本地、不外传、不进 git。
• 范例库归属：自带 references/gallery.md 为本项目原创、可随包自由使用；可选扩展 gpt-image skill 的 gallery / craft 版权归其原作者，仅在本机已安装时作为额外检索源，不随本包分发。

目录结构

draw-prompt/
├── SKILL.md                  # 主运行手册（8 步工作流 + harness 约定）
├── references/
│   ├── compile.md            # 「需求 → prompt」编译方法论（核心）
│   ├── conversion-skill-plan.md # 生图转化 Skill 完整方案与验收标准
│   ├── golden-cases.jsonl    # 稳定性基准用例（开发仓库本地，不随 npm 包发布）
│   ├── visual-cases.jsonl    # 多场景视觉回归用例（开发仓库本地，不随 npm 包发布）
│   ├── harness.md            # 三层偏好学习机制 + 数据格式
│   └── codex-handoff.md      # 交给 Codex 的现成指令与边界
├── agents/openai.yaml        # skill 接口元信息卡
└── scripts/prompt_cli.py     # PEP723 单文件 CLI（uv 运行）

知识底座：自带高质量 baseline

skill 自带一份原创金标准范例库（references/gallery.md，12 类主流品类）+ 编译法则 （references/compile.md），保证开箱即出的 Prompt 就已经很好——不依赖任何外部 skill。 个人偏好（profile/samples）只是在这个 baseline 上叠你的口味 delta，不从零学起。

两层 few-shot 模型：

第 0 层  自带金标准库（gallery.md + compile.md）   ← 人人共享，托起 baseline 质量
第 2 层  个人 profile + samples                    ← 只调你的口味 delta

本机若装了 gpt-image skill，会把它的 162 条 gallery + craft 当可选扩展额外检索 （注意其外部作者归属）；没有也完全不影响。gpt-image 还可作为一条直接出图通道。