auto-draw-plot
根据用户描述生成高质量绘图 prompt,并按通用、roadmap、schematic 模式通过 BenszAPI 直接完成 gpt-image-2 或 Nano Banana/Gemini 出图、编辑和多轮迭代;这是自包含的图片生成工作流,选中后不得调用或依赖 imagegen,除非用户明确要求同时使用 imagegen。
Install
npx skills add https://github.com/huangwb8/skills/tree/main/skills/alpha/auto-draw-plot
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install huangwb8-skills@llmmart
git clone https://github.com/huangwb8/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole huangwb8/skills collection as a plugin from our marketplace. Git is the plain clone.
README
auto-draw-plot — 用户使用指南
本 README 面向使用者:如何触发并正确使用 auto-draw-plot skill。
执行规范在 SKILL.md;默认模式、画布尺寸和生成轮数在 config.yaml。
快速开始
启动前路径声明
通过 AI 助手调用本 skill 时,助手在正式检查 API、初始化工作区或开始出图前,应先明确声明本次任务 .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot 工作区根目录的绝对路径,例如:
本次 auto-draw-plot .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot 工作区绝对路径:/abs/project/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot
如果你指定了自定义 workspace_base,这里应显示该自定义目录解析后的绝对路径。初始化完成后,实际 run 目录会写入 run-manifest.json,通常形如 .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/。
推荐 Prompt(最小可用)
请使用 auto-draw-plot skill 生成一张科研展示图。
输入:展示上下游信号链,6 个节点,用箭头连接,突出关键蛋白;白底,文字清晰。
输出:至少 1 张可用 JPEG;中间文件保存在 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/`。
进阶 Prompt(带比例参数)
请使用 auto-draw-plot skill 生成一张科研展示图。
输入:展示上下游信号链,6 个节点,用箭头连接,突出关键蛋白;白底,文字清晰。
输出:至少 1 张可用 JPEG;中间文件保存在 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/`。
另外,还有下列参数约束:
- mode:general
- 期望布局比例:1600 x 900
- 画布比例:16:9
- max_rounds:3
尺寸可以用自然语言写在 Prompt 里作为布局参考,例如 画布比例:16:9、期望布局:1800 x 1697。如果你直接运行脚本,--canvas-width 和 --canvas-height 只影响布局提示,不承诺最终像素。为控制真实调用成本,OpenAI 图片模型默认使用 gpt-image-2.5-flare,并显式请求 quality=low、最小方形原生尺寸 1024x1024 和 output_format=jpeg。
模式选择
| 你的需求 | 推荐 mode |
默认画布 | 适合场景 |
|---|---|---|---|
| 普通展示图、概念图、信息图 | general |
1600 x 900 |
默认模式,适合汇报图和自由描述 |
| 技术路线图、roadmap、flowchart | roadmap |
1800 x 1697 |
阶段、任务、主链、风险/备选 |
| 原理图、机制图、架构图 | schematic |
1920 x 1200 |
模块分组、机制链、算法/实验闭环 |
nsfc-roadmap 和 nsfc-schematic 可作为别名触发对应模式,但这里只迁移光栅图片的 prompt 与评估经验,不再迁移 draw.io、SVG/PDF、TEX 抽取等 legacy 渲染栈。
roadmap / schematic 默认偏向正常字宽的中文标签:现代黑体/思源黑体/Noto Sans CJK 风格、常规到半粗体、深灰或黑色。标签过长时优先自然换行,不使用窄体、长体、压缩体或横向压缩字形。
使用示例
示例:技术路线图
请使用 auto-draw-plot skill 生成技术路线图。
输入:把这段研究内容整理成 3-5 个阶段,突出主链、风险控制和备选方案。
输出:A4 缩印仍可读的白底 JPEG。
另外,还有下列参数约束:
- mode:roadmap
- 期望布局比例:1800 x 1697
- 字体:中文标签使用正常字宽,禁止窄体/压缩体
示例:原理图/机制图
请使用 auto-draw-plot skill 生成机制图。
输入:展示输入层、模型处理层、验证层和输出层之间的关系;保留这些中文术语,不要改写关键标签。
输出:分组清晰、箭头方向正确、中文标签可读的 JPEG。
另外,还有下列参数约束:
- mode:schematic
- 期望布局比例:1920 x 1200
- 字体:中文标签使用正常字宽,禁止窄体/压缩体
示例:带参考图微调
请使用 auto-draw-plot skill 根据参考图生成一张新版架构图。
输入:参考图是 `./old-figure.png`;保留三层结构,但改成白底、低饱和蓝灰配色,并让中文标签更清晰。
输出:一张适合论文补充材料的 JPEG。
另外,还有下列参数约束:
- mode:schematic
- 期望布局比例:2560 x 1600
- max_rounds:4
分辨率怎么理解
默认策略是“原生优先”:provider 返回多少像素,最终图片就保存多少像素。--canvas-width / --canvas-height 和 Prompt 中的尺寸描述用于表达布局比例,并帮助脚本选择 provider 支持的原生请求尺寸;它们不是超分辨率或 4K 导出开关。
| 场景 | 适合用途 | 推荐写法 | 脚本参数 |
|---|---|---|---|
| 16:9 汇报图 | 普通展示图、概念图 | 画布比例:16:9 |
--canvas-width 1600 --canvas-height 900 |
| 技术路线图 | roadmap 首轮生成与多轮优化 | 接近 A4 的技术路线图比例 |
--canvas-width 1800 --canvas-height 1697 |
| 宽幅机制图 | schematic 首轮生成与多轮优化 | 宽幅机制图,约 16:10 |
--canvas-width 1920 --canvas-height 1200 |
| 竖版 A4 | 需要接近 A4 竖版比例 | 竖版 A4 比例 |
--canvas-width 2400 --canvas-height 3394 |
OpenAI 图片模型默认固定请求最低成本的 1024x1024 原生尺寸;画布宽高仍会进入 prompt 作为布局意图,但不会把 provider 请求提高到更大的原生尺寸。Nano Banana/Gemini 会按 provider 的 aspectRatio / imageSize 能力返回图片。若要出版级清晰文字,优先使用矢量重排、程序化绘图或后续排版处理,不要依赖插值放大。
工作原理
auto-draw-plot 会由当前宿主 AI 把你的需求拆成主体、结构、风格、硬约束和禁止项,然后按模式生成图片 prompt。第 1 轮按文本出图;第 2 轮起会自动把上一轮 output.jpg 作为第一参考图,并追加保留主体、构图和背景的保真约束。首轮已有用户参考图时也会正确记录为 image-to-image。
它是自包含的图片生成工作流:本 skill 自己通过 BenszAPI 完成 prompt、出图、编辑与迭代,不依赖 imagegen skill。仅当你明确要求同时使用 imagegen 或其特有能力时,助手才应额外调用它,并说明两者独立的职责;正常使用 auto-draw-plot 时,不应出现“先由它写 prompt、再交给 imagegen 出图”的说法。
图片生成默认使用 auto provider 选择:运行前按优先级寻找一个配置、连接和鉴权检查通过的图片 provider。这里的 /v1/models 探测不执行完整 Images 计费资格检查,因此输出 connectivity/authentication_ok 只表示“能连通且 Key 可鉴权”,不表示当前请求已经 generation_eligible。真实生成资格以 /images/jobs/generations 或 /images/jobs/edits 的 submit 响应为准。
生成过程中默认不跨模型回退;如果你明确要求“用 gpt-image-2.5-sunburst 画图”或“用 gpt-image-2 画图”,对应模型失败时会停止并报告原因,不会自动改用 Nano Banana / Gemini。只有你明确说“provider 故障时可以换模型”时,才允许开启 provider fallback;订阅、余额、权限、overage、计费服务错误,以及 submit 空/非 JSON 等无法确认 job 是否已创建的协议错误,即使开启该选项也不会跨 provider,以免掩盖真实业务故障或重复生成计费。
gpt-image-2.5-flare、gpt-image-2.5-sunburst 与 gpt-image-2 共享 OpenAI Images provider,默认主动使用 Sub2API 的 image job endpoint:文本出图提交到 /v1/images/jobs/generations,参考图编辑提交到 /v1/images/jobs/edits。配置为 https://<subdomain>.benszresearch.com 的根地址时,客户端会在安全校验后自动规范为 .../v1;已显式配置 /v1 时保持不变。这样长耗时图片任务会在服务端 job 中运行,客户端只负责轮询,避免同步 /v1/images/generations 或 /v1/images/edits 长连接更容易暴露在 504 风险下。
同步接口只作为兼容回退:当 job endpoint 明确返回 404/405/501 时,脚本才会改用旧同步端点。服务端尚未确认持久幂等语义前,submit 固定只提交一次;BILLING_PRICING_NOT_CONFIGURED 等 retryable=false 错误不会退避重试,2xx 空/非 JSON 响应也不会重放,poll/result 的临时故障独立处理。JSON 与 multipart 请求都会发送单次生成的安全 X-Client-Request-ID;此类协议错误会在 image-debug/gpt-image-2-error.json 中记录服务端回传的安全 X-Request-ID / X-Client-Request-ID、HTTP 状态、origin/path、Content-Type、声明/实际长度、正文 SHA-256、首字节类别和重定向变化,但不会保存 query、鉴权头、prompt 或原始响应正文。参考图证据同样只记录 SHA-256,不记录 API Key 或内部订阅明细。
配置
推荐配置在 ~/.bensz-skills/config/remote.env 或环境变量中。如果只使用 OpenAI 图片模型,不需要配置 Gemini。
# OpenAI 图片模型主路径;不设置 OPENAI_IMAGE_MODEL 时默认 gpt-image-2.5-flare
OPENAI_BASE_URL=https://api.benszresearch.com/v1
OPENAI_API_KEY=你的密钥
OPENAI_IMAGE_MODEL=gpt-image-2.5-flare
# Nano Banana/Gemini 图片 provider 路径(仅在使用该 provider 或明确允许图片回退时需要)
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_API=你的密钥
GEMINI_MODEL=nano-banana-preview
默认情况下,skill 会先读取本地 Codex 配置:从 ~/.codex/config.toml 获取 BenszAPI base URL,从 ~/.codex/auth.json 获取 OPENAI_API_KEY / OPENAI_API。只有 Codex 本地配置缺少对应字段时,才使用环境变量或 remote.env 作为兜底。Windows 会优先按 %USERPROFILE%、%HOMEDRIVE%%HOMEPATH% 解析 ~,同时兼容 Git Bash/PowerShell 的 HOME。每次运行会在脱敏诊断证据中记录实际配置路径、来源和 API Key 短指纹;如果 Codex 配置与 BenszAPI 环境变量冲突,会在发图前停止并指出 base_url_mismatch 或 api_key_mismatch,避免静默读取旧配置。
输出结果
- 最终图片:默认
draw-plot.jpg,或你传入的--output-image(--output-png保留为兼容别名) - 启动前声明:AI 助手应先输出
.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot根目录绝对路径,便于实时监督 - 隐藏工作区:
.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/ - 追溯文件:
meta/analysis.json、meta/result.json - 每轮证据:
rounds/round-XX/prompt.txt、output.jpg、evaluation.json - provider 与参考图记录:
meta/result.json中的providers_used,以及meta/analysis.json每轮的reference_strategy
备选用法(脚本)
Prompt 调用是推荐用法;当你需要固定参数、批量跑图或接入自动化流程时,再直接运行脚本。
python3 auto-draw-plot/scripts/run_draw_plot.py \
--mode roadmap \
--provider gpt-image-2.5-flare \
--request-text "画一张白底技术路线图:三阶段研究任务,包含风险控制和验证闭环。" \
--canvas-width 1800 \
--canvas-height 1697 \
--output-image ./roadmap.jpg
常用参数:
| 参数 | 说明 |
|---|---|
--mode |
general / roadmap / schematic |
--max-rounds |
最大迭代轮数,默认 3 |
--canvas-width |
期望布局宽度/比例参考,不承诺最终图片像素 |
--canvas-height |
期望布局高度/比例参考,不承诺最终图片像素 |
--postprocess-resize |
显式启用尺寸后处理;必须同时提供 --postprocess-width 与 --postprocess-height |
--postprocess-width |
后处理目标宽度,需配合 --postprocess-resize |
--postprocess-height |
后处理目标高度,需配合 --postprocess-resize |
--quality |
OpenAI 图片模型画质:low / medium / high / auto,默认 low |
--provider-size |
OpenAI 图片模型原生尺寸枚举,默认 1024x1024 |
--output-format |
jpeg / png / webp,默认 jpeg |
--output-compression |
0-100,默认 85 |
--reference-image |
用户参考图;第 2 轮起上一轮输出图会自动排在这些参考图之前 |
--provider |
图片 provider/model:auto / gpt-image-2.5-flare / gpt-image-2.5-sunburst / gpt-image-2 / nano_banana;用户点名模型时应显式传入 |
--allow-provider-fallback |
只有用户明确允许 provider 故障时换模型才使用;计费、权限与客户端策略错误仍不回退 |
--api-env |
自定义 env 文件 |
--allow-outside-project |
允许输出或工作区写到 project_root 外部 |
长耗时图片任务由配置项 api.async_image_job.submit_mode、fallback_to_sync_on_unsupported、max_wait_s、poll_interval_s 和 poll_timeout_s 控制。一般不需要改;只有目标 Sub2API 部署没有 job endpoint,或服务端排队明显超过默认 30 分钟时再调整。
检查 provider:
python3 auto-draw-plot/scripts/nano_banana_check.py
这个命令名保留旧兼容性,实际会检查当前图片 provider 优先级。对 OpenAI 图片模型,它只检查配置、连接与鉴权;看到 generation_eligible=unknown_until_image_submit 是正常结果,真正的准入判断发生在图片 submit。
FAQ
Q:分辨率写在 Prompt 里就够了吗?
A:可以写,但它只作为布局和 provider 尺寸选择参考。默认最终图片保留 provider 原生尺寸;如果 meta 里看到 native_size 与 output_size 一致,说明没有后处理插值。
Q:为什么指定 OpenAI 图片模型后没有自动回退到 Nano Banana?
A:这是预期行为。用户点名模型时,skill 会尊重这个选择;如果配置、额度或端点失败,会停止并报告原因。只有你明确允许 provider 故障时换模型,脚本才会使用 --allow-provider-fallback;订阅、余额、权限、overage 与计费服务错误不会借此切换模型。
Q:为什么 provider 检查显示 OK,提交图片时仍可能失败?
A:检查阶段的 OK connectivity/authentication_ok 只证明 base URL 可连接且 Key 可鉴权。图片请求的模型、分组、订阅、余额、overage 等条件只有真实 submit 才能完整判断;请以 submit 返回的 SUBSCRIPTION_REQUIRED、BILLING_SERVICE_ERROR、OVERAGE_LIMIT_EXCEEDED 等结构化错误码为准。
Q:PROVIDER_EMPTY_RESPONSE 或 PROVIDER_NON_JSON_RESPONSE 是什么?
A:它表示 HTTP 客户端收到了成功状态,但正文为空或不是 Sub2API Images 约定的 JSON。由于客户端无法确认服务端是否已经创建 job,脚本不会自动重试,也不会跨 provider 再生成;请保留 image-debug/gpt-image-2-error.json,用其中不含密钥和正文的 request_id、client_request_id、状态、路径、长度、类型与指纹联系管理员排查边缘/代理链路。
Q:使用 OpenAI 图片模型时还会调用 Gemini 做文本规划或评估吗?
A:不会。OpenAI 图片路径默认不需要 Gemini 配置;prompt 规划由当前宿主 AI 和脚本本地模板完成,脚本评估默认是启发式检查,最终语义质量由宿主 AI 根据图片把关。
Q:多轮优化是在重画,还是沿着上一张图继续改?
A:沿着上一张图继续改。第 1 轮是 text-to-image;从第 2 轮开始,第 n+1 轮会把第 n 轮 JPEG 作为第一参考图,并结合反馈做 image-to-image 保真微调。
Q:为什么 roadmap / schematic 里的中文默认不用窄体?
A:中文标签以正常字宽更接近论文图和汇报图的常规排版,也更利于缩印阅读。roadmap / schematic 会默认要求现代黑体/思源黑体/Noto Sans CJK 风格,优先自然换行,避免窄体、长体、压缩体、横向压缩和瘦长字体。只有你明确要求海报感、窄体标题或压缩排版时,才应覆盖这个默认偏好。
Q:roadmap / schematic 会输出 draw.io 吗?
A:不会。它们现在是 auto-draw-plot 的特殊光栅图片模式;legacy draw.io/SVG/PDF 能力不在本 skill 内继续维护。
Skill manifest
Auto Draw Plot
目标
- 以用户需求为起点,由宿主 AI 进行语义规划,再构造适用于当前图片 provider 的 prompt,通过 BenszAPI 直接完成“parallel-vibe 规划留痕 → prompt → 出图 → 视觉评估 → 继续/停止”的闭环;脚本默认不调用额外 Gemini 文本接口。
- 触发边界:默认模式是
general;用户明确要技术路线图/roadmap/flowchart 时使用roadmap,明确要原理图/机制图/架构图时使用schematic。后续新增类型应作为config.yaml:modes.presets扩展,不改主流程。 parallel-vibe是必选工作流的一部分,不是可选增强;默认通过scripts/run_draw_plot.py在独立隐藏工作区里完成整个闭环。auto-draw-plot独立负责需求拆解、prompt 生成、图片 generation/edit、多轮保真微调、评估与交付;图片请求由本 skill 的脚本通过 BenszAPI 提交,不调用也不依赖imagegenskill。完整的imagegen技能边界见「Skill 专属约束」。
流程
输入
user_need(必需):自然语言描述的图像需求、输出用途、必要的视觉语义与格式要求。mode(可选):general/roadmap/schematic;默认general。模式只改变 prompt preset、默认画布和评估口径,不引入 legacy draw.io 渲染器。三种模式的语义与文字策略:general:通用绘图模式,适合普通信息图、封面图、概念图和自由描述。roadmap:技术路线图模式,强调 3-5 阶段、阶段标题条、主链箭头、风险/备选虚线、A4 打印可读。schematic:原理图/机制图模式,强调分组大框、圆角节点、机制链/模块关系、主链与辅助箭头分层。roadmap/schematic的文字策略:优先把标签自然换成 2-3 行,也不要横向压缩字形;默认使用现代黑体/思源黑体/Noto Sans CJK 风格的正常字宽、常规到半粗体。除非用户明确要求窄体标题或压缩排版,否则禁止窄体、长体、压缩体、condensed/narrow/compressed font、横向压缩和瘦长拉伸字体。- 不要把
roadmap/schematic回退成 draw.io、SVG/PDF 或 TEX 强绑定流程;这些 legacy 能力只作为 prompt 和评估经验迁移。
api_config(可选):Codex 本机配置优先使用~/.codex/config.toml中当前 BenszAPI provider 的base_url与experimental_bearer_token;~/.codex/auth.json仅作为兼容认证来源,~/.bensz-skills/config/remote.env只作为缺失字段的兜底。默认auto只在运行前按优先级选择连接与鉴权检查通过的 provider,真实生成资格以 Images submit 响应为准。image_provider(可选):用户明确指定的图片模型/provider,如gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2或nano_banana。显式指定后必须只用该 provider/model,失败时暂停并报告原因,不得切换到其他模型。allow_provider_fallback(可选):只有用户明确说“失败可以换模型/可以回退到另一个 provider”时才为 true;该授权仅覆盖已确认未创建任务的 provider 故障,不覆盖订阅、余额、权限、overage、计费服务错误或 submit 空/非 JSON 等任务创建状态不确定的协议错误。max_rounds(可选):最大优化轮数,默认 3;若用户另有指定,以用户为准。visual_constraints(可选):比例、期望布局、色调、字体等硬约束。尺寸只作为 provider 原生尺寸选择参考,不承诺最终导出像素。quality/provider_size/output_format/output_compression(可选):OpenAI 图片模型显式 provider 参数;默认模型为gpt-image-2.5-flare,默认参数分别为low、1024x1024、jpeg、85,均执行白名单或范围校验。reference_images(可选):用于 prompt 引导的风格/布局图;第 2 轮起上一轮output.jpg会自动作为第一参考图,用户参考图排在其后。workspace_base(可选):用户显式指定的隐藏工作区根目录;未指定时使用当前目录.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/。
执行步骤
理解需求与模式:宿主 AI 先把用户需求拆成“主体 / 结构 / 风格 / 硬约束 / 禁止项”,并解析
mode;未指定时用general。需要时参考 references/prompt-guidelines.md。声明监督路径:若用户传入
workspace_base,解析该路径;否则解析project_root/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot。必须把解析后的绝对路径用可见消息在 API 检查、init_workspace.py、run_draw_plot.py或任何图片生成调用之前告诉用户,例如:本次 auto-draw-plot .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot 工作区绝对路径:/abs/project/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot。不要只把路径写进run-manifest.json;初始化后可再补充实际run_dir,但不能用run_dir补充替代启动前的根目录声明。检查 API:运行
scripts/nano_banana_check.py。默认优先读取本地 Codex 配置:从~/.codex/config.toml当前 BenszAPI provider 获取 base URL 和experimental_bearer_token(或 provider 内兼容 token 字段),再从~/.codex/auth.json获取兼容 key;环境变量与remote.env只作为缺失字段的兜底来源。Windows 同时兼容%USERPROFILE%、%HOMEDRIVE%%HOMEPATH%与 Git Bash/PowerShell 的HOME。配置加载必须记录实际配置文件路径、来源和 API Key 不可逆短指纹;若 Codex 配置与 BenszAPI 环境变量同时存在且 Base URL/API Key 不一致,必须在发图前停止并报告冲突字段,不得静默使用旧配置;诊断证据不得写入完整密钥。gpt-image-2.5-flare、gpt-image-2.5-sunburst与gpt-image-2共享 OpenAI Images provider,只能绑定benszresearch.com子域名 base URL;非 HTTPS、裸域、非白名单域名或缺少 key 时不得绕过校验。若配置只提供子域名根地址,客户端会在校验后统一规范为带/v1的 API 基址,避免 Images 请求落入站点 HTML fallback。- 若用户点名
gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2、Nano Banana、Gemini或其他具体 provider/model,运行前检查和后续出图都必须固定在该 provider/model,并给主脚本传--provider <name>;失败时输出可执行的配置/额度/端点错误,不自动切到另一个模型。 - 默认
auto会按 provider 优先级检查配置、连接和鉴权;/v1/models成功只能表述为connectivity/authentication_ok,不得写成“可生图”或generation_eligible=true,真实 Images submit 才是当前请求的准入判断。此步骤不执行完整 Images 计费资格检查,不要把“指定模型失败”改写成“自动使用另一个模型”。
- 若用户点名
初始化隐藏工作区:运行
scripts/init_workspace.py,默认建立.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/,写出run-manifest.json。生成 parallel-vibe 计划:每一轮开始前,必须生成该轮的
parallel-vibeplan;即使宿主 AI 最终不真正启动parallel-vibeCLI,也必须按它的 thread/workspace 协议为每一轮写出合法plan.json,至少写出:parallel-vibe/parallel-plan.round-XX.jsonparallel-vibe/parallel-plan.json(latest)rounds/round-XX/parallel-plan.json
主入口
scripts/run_draw_plot.py已经会为每一轮自动生成 parallel-vibe plan,用户无需额外手工执行;若宿主 AI 想把“下一轮 prompt 草案”真正交给独立线程处理,则直接复用该轮parallel-plan.round-XX.json。parallel-vibeworker 当前仍只负责在隔离 workspace 里产出 prompt 草案与评估请求模板;真正的出图与评估继续由本 skill 的主脚本完成,避免跨 workspace 回写导致不稳定。生成第 1 轮 prompt:
- 优先由宿主 AI 在调用脚本前完成需求拆解与 prompt 规划;
run_draw_plot.py只做本地模板拼装与护栏合并,不默认调用 Gemini / Nano Banana 等远端文本规划接口;- prompt 仍需忠实反映用户需求,不得暴露密钥或绝对路径。
调用图片模型:运行
scripts/generate_image.py或主入口scripts/run_draw_plot.py;OpenAI 图片模型默认使用gpt-image-2.5-flare,也支持显式指定gpt-image-2.5-sunburst或gpt-image-2。纯文本出图默认提交到/v1/images/jobs/generations,存在参考图时默认提交到/v1/images/jobs/edits。配置仅给出 BenszAPI 子域名根地址时,客户端会先规范为带/v1的 API 基址;同步端点只在 job endpoint 明确不支持时兼容回退。submit 在服务端尚无持久幂等契约时只提交一次;结构化retryable=false(包括BILLING_PRICING_NOT_CONFIGURED)立即停止,2xx空/非 JSON 响应也不重试或跨 provider,poll/result 的暂时故障独立处理。默认请求quality=low、最小匹配原生尺寸和output_format=jpeg,输出扩展名、magic bytes、MIME 与 meta 必须一致;PNG/WebP 回退结果导出 JPEG 时以白色合成透明背景。参考图编辑会追加“只改明确要求、保留主体/构图/背景”的契约,并记录原始参考图 SHA-256。- 回退授权:只有用户主动要求允许回退时,才设置
allow_provider_fallback=true或脚本参数--allow-provider-fallback;回退路径使用~/.bensz-skills/config/remote.env中的GEMINI_BASE_URL、GEMINI_API | GEMINI_API_KEY、GEMINI_MODEL。即使已授权,计费、订阅、余额、权限、overage、BILLING_SERVICE_ERROR与 submit 空/非 JSON 等任务创建状态不确定的协议错误仍必须停在原 provider 并展示结构化错误。
- 回退授权:只有用户主动要求允许回退时,才设置
视觉评估:
scripts/evaluate_image.py默认只做启发式文件/分辨率检查并标记fallback_mode=heuristic,不调用 Gemini 文本接口;- 宿主 AI 必须根据最终图片、用户需求与
evaluation.json做语义把关,必要时人工触发下一轮。
多轮优化:上一轮若未通过,第
n+1轮必须把第n轮output.jpg作为第一参考图传给可消费参考图的图片 provider,并把反馈拼进 prompt,要求模型保真微调而不是从零重画;首轮用户参考图也必须标记为image-to-image,来源使用user_reference/previous_round/mixed。交付:输出至少 1 张最终 JPEG;隐藏目录里保留
meta/result.json供追溯。
输出
- 至少 1 张合乎需求的图像;OpenAI 图片模型正式输出默认为
jpeg。 - 隐藏目录里的
meta/analysis.json/meta/result.json:记录每轮 prompt、模型参数、参考图策略、评估结果、最终选图和停止原因。 - 每轮图片 meta 必须区分
requested_provider_size、native_size、output_size与postprocess_resize_applied;默认postprocess_resize_applied=false。 image-debug/gpt-image-2-error.json只保留错误类别、HTTP 状态和服务端安全返回的error.type/error.code/error.message。JSON 与 multipart 请求发送安全X-Client-Request-ID;2xx空正文或非 JSON 正文分别记录PROVIDER_EMPTY_RESPONSE/PROVIDER_NON_JSON_RESPONSE,附经白名单校验的request_id/client_request_id、origin/path、响应类型、声明/实际长度、SHA-256、首字节类别和重定向布尔值;不得写入 query、Authorization、API Key、Cookie、prompt、原始正文、订阅明细或原始内部错误对象。- 每轮目录:
rounds/round-XX/prompt.txt、rounds/round-XX/prompt-plan.json、rounds/round-XX/parallel-plan.json、rounds/round-XX/output.jpg、rounds/round-XX/evaluation.json以及image-debug//evaluation-debug/;OpenAI 图片模型默认主动使用 Sub2API image job endpoint,generation/edit 均显式发送quality=low、原生尺寸和output_format=jpeg,并在 debug meta 中保留参考图 SHA-256。 - run 级
parallel-vibe/parallel-plan.json与parallel-vibe/parallel-plan.round-XX.json:每轮必留痕的 parallel-vibe plan。
输出管理
- 默认工作区是当前目录下的
.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/;所有中间文件必须留在隐藏目录里,正式交付物不写入该目录。 - 同一任务复用一个任务根目录;多 Skill 协作才创建
shared/,本 Skill 专属材料放入auto-draw-plot/的input/、output/、log/子目录。 - 轻量测试目录固定为
./tests/draw-plot,中间文件限定在tests/draw-plot/_artifacts/(见「校验」)。
校验
- 轻量测试必须在
tests/draw-plot下完成;每次执行都应该在该目录内生成TEST_PLAN.md/TEST_REPORT.md,并把中间文件限定在tests/draw-plot/_artifacts/。 - auto-test-skill 的 A/B 轮也只能操作 tests 目录,确保
p0-p2问题均闭环。 - 视觉语义把关不可脚本化:宿主 AI 必须依据最终图片、用户需求与
evaluation.json复核启发式评估结论后才可交付。
失败与恢复
- 配置冲突:Codex 配置与 BenszAPI 环境变量的 Base URL/API Key 不一致时,必须在发图前停止并报告冲突字段,不得静默使用旧配置。
- 域名校验失败:OpenAI 图片模型出现非 HTTPS、裸域、非白名单域名或缺少 key 时停止,不得绕过校验。
- 指定 provider 失败:暂停并报告原因,输出可执行的配置/额度/端点错误,不自动切到另一个模型;provider 回退仅按「执行步骤」第 7 步的授权边界执行,任务创建状态不确定的协议错误一律停在原 provider 并展示结构化错误。
- submit 失败:服务端尚无持久幂等契约时只提交一次;结构化
retryable=false(包括BILLING_PRICING_NOT_CONFIGURED)立即停止,2xx空/非 JSON 响应不重试、不跨 provider;poll/result 的暂时故障独立处理。 - 评估未通过:按「执行步骤」第 9 步进入多轮保真微调;达到
max_rounds或得分平台期仍不达标时,交付当前最优结果并在meta/result.json记录停止原因。
约束
公共硬约束
本块由 docs/templates/skill-common-constraints.md 统一维护;每个 SKILL.md 的 ## 约束 必须逐字同步本块,不得在副本中改写公共规则。
- 任务需要落盘时,使用唯一的
./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/根目录;共享材料放入shared/,Skill 专属材料放入该 Skill 的input/、output/、log/。 - 正式交付物、源代码和正式计划按项目约定保存,不写入任务工作区;未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要;BAC 只做过程审计,不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内;外部 URL、子进程和网络访问遵循最小权限,防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身
config.yaml:skill_info.version;公开 API、协议、目录或配置变更同步文档与CHANGELOG.md。 bensz-collect-bugs是一个 Agent Skill;仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入~/.bensz-skills/bugs/,当前任务不中断,只有用户明确要求才公开上报,禁止直接修改用户已安装的 Skill 源码。
Skill 专属约束
imagegen技能边界:用户要求用auto-draw-plot画图、改图或基于上一轮继续微调时,只使用本 skill 完成完整链路。不得把它表述或编排为“先生成 prompt,再交给imagegen出图/编辑”的前处理步骤;这种说法会错误暗示依赖关系,并可能造成重复生图与重复计费。- 只有用户明确点名同时使用
imagegen,或明确要求其独有能力时,才允许额外调用imagegen;调用前说明两者各自独立的职责,且不得将imagegen伪装成auto-draw-plot的内部依赖。默认用户可见说明应写明:本次使用 auto-draw-plot,由其经 BenszAPI 完成 prompt、出图和后续编辑。不得默认承诺后续会调用imagegen。 gpt-image-2.5-flare、gpt-image-2.5-sunburst与gpt-image-2只能绑定benszresearch.com子域名 base URL;非 HTTPS、裸域、非白名单域名或缺少 key 时不得绕过校验。- 错误诊断与
image-debug/gpt-image-2-error.json不得写入 query、Authorization、API Key、Cookie、prompt、原始正文、订阅明细或原始内部错误对象;诊断证据中的 API Key 只允许不可逆短指纹。 - 历史隐藏目录只允许显式兼容读取、迁移或清理,不做静默处理。
- 因本 skill 设计缺陷导致的 bug 先按公共约束记录到
~/.bensz-skills/bugs/;只在用户明确要求 “report bensz skills bugs” 时,才通过本地gh调用将新 bug 推送到huangwb8/bensz-bugs,上传前必须先脱敏本地路径/用户名等隐私。 - prompt 结构模板与迭代策略见 references/prompt-guidelines.md;合法的
parallel-vibeshell plan 模板见 references/parallel-plan.md。
Files (skills)
-
references
-
parallel-plan.md 1.5 KB
Loading… -
prompt-guidelines.md 3.3 KB
Loading…
-
-
scripts
-
build_parallel_plan.py 2.8 KB
Loading… -
common.py 4.5 KB
Loading… -
env_utils.py 3 KB
Loading… -
evaluate_image.py 9.6 KB
Loading… -
generate_image.py 9.9 KB
Loading… -
image_provider_client.py 80.7 KB
Loading… -
init_workspace.py 7.3 KB
Loading… -
modes.py 3.9 KB
Loading… -
nano_banana_check.py 1.1 KB
Loading… -
nano_banana_client.py 17.1 KB
Loading… -
parallel_round_worker.py 1.9 KB
Loading… -
run_draw_plot.py 25.5 KB
Loading…
-
-
CHANGELOG.md 10.7 KB
Loading… -
config.yaml 9.5 KB
Loading… -
README.md 16.1 KB
# auto-draw-plot — 用户使用指南 本 README 面向**使用者**:如何触发并正确使用 `auto-draw-plot` skill。 执行规范在 `SKILL.md`;默认模式、画布尺寸和生成轮数在 `config.yaml`。 ## 快速开始 ### 启动前路径声明 通过 AI 助手调用本 skill 时,助手在正式检查 API、初始化工作区或开始出图前,应先明确声明本次任务 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot` 工作区根目录的绝对路径,例如: ```text 本次 auto-draw-plot .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot 工作区绝对路径:/abs/project/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot ``` 如果你指定了自定义 `workspace_base`,这里应显示该自定义目录解析后的绝对路径。初始化完成后,实际 run 目录会写入 `run-manifest.json`,通常形如 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/`。 ### 推荐 Prompt(最小可用) ```text 请使用 auto-draw-plot skill 生成一张科研展示图。 输入:展示上下游信号链,6 个节点,用箭头连接,突出关键蛋白;白底,文字清晰。 输出:至少 1 张可用 JPEG;中间文件保存在 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/`。 ``` ### 进阶 Prompt(带比例参数) ```text 请使用 auto-draw-plot skill 生成一张科研展示图。 输入:展示上下游信号链,6 个节点,用箭头连接,突出关键蛋白;白底,文字清晰。 输出:至少 1 张可用 JPEG;中间文件保存在 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/`。 另外,还有下列参数约束: - mode:general - 期望布局比例:1600 x 900 - 画布比例:16:9 - max_rounds:3 ``` 尺寸可以用自然语言写在 Prompt 里作为布局参考,例如 `画布比例:16:9`、`期望布局:1800 x 1697`。如果你直接运行脚本,`--canvas-width` 和 `--canvas-height` 只影响布局提示,不承诺最终像素。为控制真实调用成本,OpenAI 图片模型默认使用 `gpt-image-2.5-flare`,并显式请求 `quality=low`、最小方形原生尺寸 `1024x1024` 和 `output_format=jpeg`。 ## 模式选择 | 你的需求 | 推荐 `mode` | 默认画布 | 适合场景 | | --- | --- | --- | --- | | 普通展示图、概念图、信息图 | `general` | `1600 x 900` | 默认模式,适合汇报图和自由描述 | | 技术路线图、roadmap、flowchart | `roadmap` | `1800 x 1697` | 阶段、任务、主链、风险/备选 | | 原理图、机制图、架构图 | `schematic` | `1920 x 1200` | 模块分组、机制链、算法/实验闭环 | `nsfc-roadmap` 和 `nsfc-schematic` 可作为别名触发对应模式,但这里只迁移光栅图片的 prompt 与评估经验,不再迁移 draw.io、SVG/PDF、TEX 抽取等 legacy 渲染栈。 `roadmap` / `schematic` 默认偏向正常字宽的中文标签:现代黑体/思源黑体/Noto Sans CJK 风格、常规到半粗体、深灰或黑色。标签过长时优先自然换行,不使用窄体、长体、压缩体或横向压缩字形。 ## 使用示例 ### 示例:技术路线图 ```text 请使用 auto-draw-plot skill 生成技术路线图。 输入:把这段研究内容整理成 3-5 个阶段,突出主链、风险控制和备选方案。 输出:A4 缩印仍可读的白底 JPEG。 另外,还有下列参数约束: - mode:roadmap - 期望布局比例:1800 x 1697 - 字体:中文标签使用正常字宽,禁止窄体/压缩体 ``` ### 示例:原理图/机制图 ```text 请使用 auto-draw-plot skill 生成机制图。 输入:展示输入层、模型处理层、验证层和输出层之间的关系;保留这些中文术语,不要改写关键标签。 输出:分组清晰、箭头方向正确、中文标签可读的 JPEG。 另外,还有下列参数约束: - mode:schematic - 期望布局比例:1920 x 1200 - 字体:中文标签使用正常字宽,禁止窄体/压缩体 ``` ### 示例:带参考图微调 ```text 请使用 auto-draw-plot skill 根据参考图生成一张新版架构图。 输入:参考图是 `./old-figure.png`;保留三层结构,但改成白底、低饱和蓝灰配色,并让中文标签更清晰。 输出:一张适合论文补充材料的 JPEG。 另外,还有下列参数约束: - mode:schematic - 期望布局比例:2560 x 1600 - max_rounds:4 ``` ## 分辨率怎么理解 默认策略是“原生优先”:provider 返回多少像素,最终图片就保存多少像素。`--canvas-width` / `--canvas-height` 和 Prompt 中的尺寸描述用于表达布局比例,并帮助脚本选择 provider 支持的原生请求尺寸;它们不是超分辨率或 4K 导出开关。 | 场景 | 适合用途 | 推荐写法 | 脚本参数 | | --- | --- | --- | --- | | 16:9 汇报图 | 普通展示图、概念图 | `画布比例:16:9` | `--canvas-width 1600 --canvas-height 900` | | 技术路线图 | roadmap 首轮生成与多轮优化 | `接近 A4 的技术路线图比例` | `--canvas-width 1800 --canvas-height 1697` | | 宽幅机制图 | schematic 首轮生成与多轮优化 | `宽幅机制图,约 16:10` | `--canvas-width 1920 --canvas-height 1200` | | 竖版 A4 | 需要接近 A4 竖版比例 | `竖版 A4 比例` | `--canvas-width 2400 --canvas-height 3394` | OpenAI 图片模型默认固定请求最低成本的 `1024x1024` 原生尺寸;画布宽高仍会进入 prompt 作为布局意图,但不会把 provider 请求提高到更大的原生尺寸。Nano Banana/Gemini 会按 provider 的 `aspectRatio` / `imageSize` 能力返回图片。若要出版级清晰文字,优先使用矢量重排、程序化绘图或后续排版处理,不要依赖插值放大。 ## 工作原理 `auto-draw-plot` 会由当前宿主 AI 把你的需求拆成主体、结构、风格、硬约束和禁止项,然后按模式生成图片 prompt。第 1 轮按文本出图;第 2 轮起会自动把上一轮 `output.jpg` 作为第一参考图,并追加保留主体、构图和背景的保真约束。首轮已有用户参考图时也会正确记录为 `image-to-image`。 它是自包含的图片生成工作流:本 skill 自己通过 BenszAPI 完成 prompt、出图、编辑与迭代,不依赖 `imagegen` skill。仅当你明确要求同时使用 `imagegen` 或其特有能力时,助手才应额外调用它,并说明两者独立的职责;正常使用 `auto-draw-plot` 时,不应出现“先由它写 prompt、再交给 imagegen 出图”的说法。 图片生成默认使用 `auto` provider 选择:运行前按优先级寻找一个配置、连接和鉴权检查通过的图片 provider。这里的 `/v1/models` 探测不执行完整 Images 计费资格检查,因此输出 `connectivity/authentication_ok` 只表示“能连通且 Key 可鉴权”,不表示当前请求已经 `generation_eligible`。真实生成资格以 `/images/jobs/generations` 或 `/images/jobs/edits` 的 submit 响应为准。 生成过程中默认不跨模型回退;如果你明确要求“用 `gpt-image-2.5-sunburst` 画图”或“用 `gpt-image-2` 画图”,对应模型失败时会停止并报告原因,不会自动改用 Nano Banana / Gemini。只有你明确说“provider 故障时可以换模型”时,才允许开启 provider fallback;订阅、余额、权限、overage、计费服务错误,以及 submit 空/非 JSON 等无法确认 job 是否已创建的协议错误,即使开启该选项也不会跨 provider,以免掩盖真实业务故障或重复生成计费。 `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` 与 `gpt-image-2` 共享 OpenAI Images provider,默认主动使用 Sub2API 的 image job endpoint:文本出图提交到 `/v1/images/jobs/generations`,参考图编辑提交到 `/v1/images/jobs/edits`。配置为 `https://<subdomain>.benszresearch.com` 的根地址时,客户端会在安全校验后自动规范为 `.../v1`;已显式配置 `/v1` 时保持不变。这样长耗时图片任务会在服务端 job 中运行,客户端只负责轮询,避免同步 `/v1/images/generations` 或 `/v1/images/edits` 长连接更容易暴露在 504 风险下。 同步接口只作为兼容回退:当 job endpoint 明确返回 404/405/501 时,脚本才会改用旧同步端点。服务端尚未确认持久幂等语义前,submit 固定只提交一次;`BILLING_PRICING_NOT_CONFIGURED` 等 `retryable=false` 错误不会退避重试,`2xx` 空/非 JSON 响应也不会重放,poll/result 的临时故障独立处理。JSON 与 multipart 请求都会发送单次生成的安全 `X-Client-Request-ID`;此类协议错误会在 `image-debug/gpt-image-2-error.json` 中记录服务端回传的安全 `X-Request-ID` / `X-Client-Request-ID`、HTTP 状态、origin/path、Content-Type、声明/实际长度、正文 SHA-256、首字节类别和重定向变化,但不会保存 query、鉴权头、prompt 或原始响应正文。参考图证据同样只记录 SHA-256,不记录 API Key 或内部订阅明细。 ## 配置 推荐配置在 `~/.bensz-skills/config/remote.env` 或环境变量中。如果只使用 OpenAI 图片模型,不需要配置 Gemini。 ```bash # OpenAI 图片模型主路径;不设置 OPENAI_IMAGE_MODEL 时默认 gpt-image-2.5-flare OPENAI_BASE_URL=https://api.benszresearch.com/v1 OPENAI_API_KEY=你的密钥 OPENAI_IMAGE_MODEL=gpt-image-2.5-flare # Nano Banana/Gemini 图片 provider 路径(仅在使用该 provider 或明确允许图片回退时需要) GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta GEMINI_API=你的密钥 GEMINI_MODEL=nano-banana-preview ``` 默认情况下,skill 会先读取本地 Codex 配置:从 `~/.codex/config.toml` 获取 BenszAPI base URL,从 `~/.codex/auth.json` 获取 `OPENAI_API_KEY` / `OPENAI_API`。只有 Codex 本地配置缺少对应字段时,才使用环境变量或 `remote.env` 作为兜底。Windows 会优先按 `%USERPROFILE%`、`%HOMEDRIVE%%HOMEPATH%` 解析 `~`,同时兼容 Git Bash/PowerShell 的 `HOME`。每次运行会在脱敏诊断证据中记录实际配置路径、来源和 API Key 短指纹;如果 Codex 配置与 BenszAPI 环境变量冲突,会在发图前停止并指出 `base_url_mismatch` 或 `api_key_mismatch`,避免静默读取旧配置。 ## 输出结果 - 最终图片:默认 `draw-plot.jpg`,或你传入的 `--output-image`(`--output-png` 保留为兼容别名) - 启动前声明:AI 助手应先输出 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot` 根目录绝对路径,便于实时监督 - 隐藏工作区:`.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/` - 追溯文件:`meta/analysis.json`、`meta/result.json` - 每轮证据:`rounds/round-XX/prompt.txt`、`output.jpg`、`evaluation.json` - provider 与参考图记录:`meta/result.json` 中的 `providers_used`,以及 `meta/analysis.json` 每轮的 `reference_strategy` ## 备选用法(脚本) Prompt 调用是推荐用法;当你需要固定参数、批量跑图或接入自动化流程时,再直接运行脚本。 ```bash python3 auto-draw-plot/scripts/run_draw_plot.py \ --mode roadmap \ --provider gpt-image-2.5-flare \ --request-text "画一张白底技术路线图:三阶段研究任务,包含风险控制和验证闭环。" \ --canvas-width 1800 \ --canvas-height 1697 \ --output-image ./roadmap.jpg ``` 常用参数: | 参数 | 说明 | | --- | --- | | `--mode` | `general` / `roadmap` / `schematic` | | `--max-rounds` | 最大迭代轮数,默认 `3` | | `--canvas-width` | 期望布局宽度/比例参考,不承诺最终图片像素 | | `--canvas-height` | 期望布局高度/比例参考,不承诺最终图片像素 | | `--postprocess-resize` | 显式启用尺寸后处理;必须同时提供 `--postprocess-width` 与 `--postprocess-height` | | `--postprocess-width` | 后处理目标宽度,需配合 `--postprocess-resize` | | `--postprocess-height` | 后处理目标高度,需配合 `--postprocess-resize` | | `--quality` | OpenAI 图片模型画质:`low` / `medium` / `high` / `auto`,默认 `low` | | `--provider-size` | OpenAI 图片模型原生尺寸枚举,默认 `1024x1024` | | `--output-format` | `jpeg` / `png` / `webp`,默认 `jpeg` | | `--output-compression` | `0-100`,默认 `85` | | `--reference-image` | 用户参考图;第 2 轮起上一轮输出图会自动排在这些参考图之前 | | `--provider` | 图片 provider/model:`auto` / `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst` / `gpt-image-2` / `nano_banana`;用户点名模型时应显式传入 | | `--allow-provider-fallback` | 只有用户明确允许 provider 故障时换模型才使用;计费、权限与客户端策略错误仍不回退 | | `--api-env` | 自定义 env 文件 | | `--allow-outside-project` | 允许输出或工作区写到 `project_root` 外部 | 长耗时图片任务由配置项 `api.async_image_job.submit_mode`、`fallback_to_sync_on_unsupported`、`max_wait_s`、`poll_interval_s` 和 `poll_timeout_s` 控制。一般不需要改;只有目标 Sub2API 部署没有 job endpoint,或服务端排队明显超过默认 30 分钟时再调整。 检查 provider: ```bash python3 auto-draw-plot/scripts/nano_banana_check.py ``` 这个命令名保留旧兼容性,实际会检查当前图片 provider 优先级。对 OpenAI 图片模型,它只检查配置、连接与鉴权;看到 `generation_eligible=unknown_until_image_submit` 是正常结果,真正的准入判断发生在图片 submit。 ## FAQ ### Q:分辨率写在 Prompt 里就够了吗? A:可以写,但它只作为布局和 provider 尺寸选择参考。默认最终图片保留 provider 原生尺寸;如果 meta 里看到 `native_size` 与 `output_size` 一致,说明没有后处理插值。 ### Q:为什么指定 OpenAI 图片模型后没有自动回退到 Nano Banana? A:这是预期行为。用户点名模型时,skill 会尊重这个选择;如果配置、额度或端点失败,会停止并报告原因。只有你明确允许 provider 故障时换模型,脚本才会使用 `--allow-provider-fallback`;订阅、余额、权限、overage 与计费服务错误不会借此切换模型。 ### Q:为什么 provider 检查显示 OK,提交图片时仍可能失败? A:检查阶段的 `OK connectivity/authentication_ok` 只证明 base URL 可连接且 Key 可鉴权。图片请求的模型、分组、订阅、余额、overage 等条件只有真实 submit 才能完整判断;请以 submit 返回的 `SUBSCRIPTION_REQUIRED`、`BILLING_SERVICE_ERROR`、`OVERAGE_LIMIT_EXCEEDED` 等结构化错误码为准。 ### Q:`PROVIDER_EMPTY_RESPONSE` 或 `PROVIDER_NON_JSON_RESPONSE` 是什么? A:它表示 HTTP 客户端收到了成功状态,但正文为空或不是 Sub2API Images 约定的 JSON。由于客户端无法确认服务端是否已经创建 job,脚本不会自动重试,也不会跨 provider 再生成;请保留 `image-debug/gpt-image-2-error.json`,用其中不含密钥和正文的 `request_id`、`client_request_id`、状态、路径、长度、类型与指纹联系管理员排查边缘/代理链路。 ### Q:使用 OpenAI 图片模型时还会调用 Gemini 做文本规划或评估吗? A:不会。OpenAI 图片路径默认不需要 Gemini 配置;prompt 规划由当前宿主 AI 和脚本本地模板完成,脚本评估默认是启发式检查,最终语义质量由宿主 AI 根据图片把关。 ### Q:多轮优化是在重画,还是沿着上一张图继续改? A:沿着上一张图继续改。第 1 轮是 text-to-image;从第 2 轮开始,第 `n+1` 轮会把第 `n` 轮 JPEG 作为第一参考图,并结合反馈做 image-to-image 保真微调。 ### Q:为什么 roadmap / schematic 里的中文默认不用窄体? A:中文标签以正常字宽更接近论文图和汇报图的常规排版,也更利于缩印阅读。`roadmap` / `schematic` 会默认要求现代黑体/思源黑体/Noto Sans CJK 风格,优先自然换行,避免窄体、长体、压缩体、横向压缩和瘦长字体。只有你明确要求海报感、窄体标题或压缩排版时,才应覆盖这个默认偏好。 ### Q:`roadmap` / `schematic` 会输出 draw.io 吗? A:不会。它们现在是 `auto-draw-plot` 的特殊光栅图片模式;legacy draw.io/SVG/PDF 能力不在本 skill 内继续维护。 -
SKILL.md 18.4 KB
--- name: auto-draw-plot description: 根据用户描述生成高质量绘图 prompt,并按通用、roadmap、schematic 模式通过 BenszAPI 直接完成 gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2 或 Nano Banana/Gemini 出图、编辑和多轮迭代;这是自包含的图片生成工作流,选中后不得调用或依赖 imagegen,除非用户明确要求同时使用 imagegen。 metadata: author: Bensz Conan short-description: 模式化需求理解 + multi-round image-to-image optimization + GPT 图片模型低成本 JPEG keywords: - auto-draw-plot - nano-banana - gemini - parallel-vibe - visual evaluation - 图像生成 --- # Auto Draw Plot ## 目标 - 以用户需求为起点,由宿主 AI 进行语义规划,再构造适用于当前图片 provider 的 prompt,通过 BenszAPI 直接完成“parallel-vibe 规划留痕 → prompt → 出图 → 视觉评估 → 继续/停止”的闭环;脚本默认不调用额外 Gemini 文本接口。 - 触发边界:默认模式是 `general`;用户明确要技术路线图/roadmap/flowchart 时使用 `roadmap`,明确要原理图/机制图/架构图时使用 `schematic`。后续新增类型应作为 `config.yaml:modes.presets` 扩展,不改主流程。 - `parallel-vibe` 是必选工作流的一部分,不是可选增强;默认通过 `scripts/run_draw_plot.py` 在独立隐藏工作区里完成整个闭环。 - `auto-draw-plot` 独立负责需求拆解、prompt 生成、图片 generation/edit、多轮保真微调、评估与交付;图片请求由本 skill 的脚本通过 BenszAPI 提交,不调用也不依赖 `imagegen` skill。完整的 `imagegen` 技能边界见「Skill 专属约束」。 ## 流程 ### 输入 - `user_need`(必需):自然语言描述的图像需求、输出用途、必要的视觉语义与格式要求。 - `mode`(可选):`general` / `roadmap` / `schematic`;默认 `general`。模式只改变 prompt preset、默认画布和评估口径,不引入 legacy draw.io 渲染器。三种模式的语义与文字策略: - `general`:通用绘图模式,适合普通信息图、封面图、概念图和自由描述。 - `roadmap`:技术路线图模式,强调 3-5 阶段、阶段标题条、主链箭头、风险/备选虚线、A4 打印可读。 - `schematic`:原理图/机制图模式,强调分组大框、圆角节点、机制链/模块关系、主链与辅助箭头分层。 - `roadmap` / `schematic` 的文字策略:优先把标签自然换成 2-3 行,也不要横向压缩字形;默认使用现代黑体/思源黑体/Noto Sans CJK 风格的正常字宽、常规到半粗体。除非用户明确要求窄体标题或压缩排版,否则禁止窄体、长体、压缩体、condensed/narrow/compressed font、横向压缩和瘦长拉伸字体。 - 不要把 `roadmap` / `schematic` 回退成 draw.io、SVG/PDF 或 TEX 强绑定流程;这些 legacy 能力只作为 prompt 和评估经验迁移。 - `api_config`(可选):Codex 本机配置优先使用 `~/.codex/config.toml` 中当前 BenszAPI provider 的 `base_url` 与 `experimental_bearer_token`;`~/.codex/auth.json` 仅作为兼容认证来源,`~/.bensz-skills/config/remote.env` 只作为缺失字段的兜底。默认 `auto` 只在运行前按优先级选择连接与鉴权检查通过的 provider,真实生成资格以 Images submit 响应为准。 - `image_provider`(可选):用户明确指定的图片模型/provider,如 `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`、`gpt-image-2` 或 `nano_banana`。显式指定后必须只用该 provider/model,失败时暂停并报告原因,不得切换到其他模型。 - `allow_provider_fallback`(可选):只有用户明确说“失败可以换模型/可以回退到另一个 provider”时才为 true;该授权仅覆盖已确认未创建任务的 provider 故障,不覆盖订阅、余额、权限、overage、计费服务错误或 submit 空/非 JSON 等任务创建状态不确定的协议错误。 - `max_rounds`(可选):最大优化轮数,默认 3;若用户另有指定,以用户为准。 - `visual_constraints`(可选):比例、期望布局、色调、字体等硬约束。尺寸只作为 provider 原生尺寸选择参考,不承诺最终导出像素。 - `quality` / `provider_size` / `output_format` / `output_compression`(可选):OpenAI 图片模型显式 provider 参数;默认模型为 `gpt-image-2.5-flare`,默认参数分别为 `low`、`1024x1024`、`jpeg`、`85`,均执行白名单或范围校验。 - `reference_images`(可选):用于 prompt 引导的风格/布局图;第 2 轮起上一轮 `output.jpg` 会自动作为第一参考图,用户参考图排在其后。 - `workspace_base`(可选):用户显式指定的隐藏工作区根目录;未指定时使用当前目录 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/`。 ### 执行步骤 1. **理解需求与模式**:宿主 AI 先把用户需求拆成“主体 / 结构 / 风格 / 硬约束 / 禁止项”,并解析 `mode`;未指定时用 `general`。需要时参考 [references/prompt-guidelines.md](references/prompt-guidelines.md)。 2. **声明监督路径**:若用户传入 `workspace_base`,解析该路径;否则解析 `project_root/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot`。必须把解析后的绝对路径用可见消息在 API 检查、`init_workspace.py`、`run_draw_plot.py` 或任何图片生成调用之前告诉用户,例如:`本次 auto-draw-plot .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot 工作区绝对路径:/abs/project/.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot`。不要只把路径写进 `run-manifest.json`;初始化后可再补充实际 `run_dir`,但不能用 `run_dir` 补充替代启动前的根目录声明。 3. **检查 API**:运行 `scripts/nano_banana_check.py`。默认优先读取本地 Codex 配置:从 `~/.codex/config.toml` 当前 BenszAPI provider 获取 base URL 和 `experimental_bearer_token`(或 provider 内兼容 token 字段),再从 `~/.codex/auth.json` 获取兼容 key;环境变量与 `remote.env` 只作为缺失字段的兜底来源。Windows 同时兼容 `%USERPROFILE%`、`%HOMEDRIVE%%HOMEPATH%` 与 Git Bash/PowerShell 的 `HOME`。配置加载必须记录实际配置文件路径、来源和 API Key 不可逆短指纹;若 Codex 配置与 BenszAPI 环境变量同时存在且 Base URL/API Key 不一致,必须在发图前停止并报告冲突字段,不得静默使用旧配置;诊断证据不得写入完整密钥。`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` 与 `gpt-image-2` 共享 OpenAI Images provider,只能绑定 `benszresearch.com` 子域名 base URL;非 HTTPS、裸域、非白名单域名或缺少 key 时不得绕过校验。若配置只提供子域名根地址,客户端会在校验后统一规范为带 `/v1` 的 API 基址,避免 Images 请求落入站点 HTML fallback。 - 若用户点名 `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`、`gpt-image-2`、`Nano Banana`、`Gemini` 或其他具体 provider/model,运行前检查和后续出图都必须固定在该 provider/model,并给主脚本传 `--provider <name>`;失败时输出可执行的配置/额度/端点错误,不自动切到另一个模型。 - 默认 `auto` 会按 provider 优先级检查配置、连接和鉴权;`/v1/models` 成功只能表述为 `connectivity/authentication_ok`,不得写成“可生图”或 `generation_eligible=true`,真实 Images submit 才是当前请求的准入判断。此步骤不执行完整 Images 计费资格检查,不要把“指定模型失败”改写成“自动使用另一个模型”。 4. **初始化隐藏工作区**:运行 `scripts/init_workspace.py`,默认建立 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/`,写出 `run-manifest.json`。 5. **生成 parallel-vibe 计划**:每一轮开始前,必须生成该轮的 `parallel-vibe` plan;即使宿主 AI 最终不真正启动 `parallel-vibe` CLI,也必须按它的 thread/workspace 协议为每一轮写出合法 `plan.json`,至少写出: - `parallel-vibe/parallel-plan.round-XX.json` - `parallel-vibe/parallel-plan.json`(latest) - `rounds/round-XX/parallel-plan.json` 主入口 `scripts/run_draw_plot.py` 已经会为每一轮自动生成 parallel-vibe plan,用户无需额外手工执行;若宿主 AI 想把“下一轮 prompt 草案”真正交给独立线程处理,则直接复用该轮 `parallel-plan.round-XX.json`。`parallel-vibe` worker 当前仍只负责在隔离 workspace 里产出 prompt 草案与评估请求模板;真正的出图与评估继续由本 skill 的主脚本完成,避免跨 workspace 回写导致不稳定。 6. **生成第 1 轮 prompt**: - 优先由宿主 AI 在调用脚本前完成需求拆解与 prompt 规划; - `run_draw_plot.py` 只做本地模板拼装与护栏合并,不默认调用 Gemini / Nano Banana 等远端文本规划接口; - prompt 仍需忠实反映用户需求,不得暴露密钥或绝对路径。 7. **调用图片模型**:运行 `scripts/generate_image.py` 或主入口 `scripts/run_draw_plot.py`;OpenAI 图片模型默认使用 `gpt-image-2.5-flare`,也支持显式指定 `gpt-image-2.5-sunburst` 或 `gpt-image-2`。纯文本出图默认提交到 `/v1/images/jobs/generations`,存在参考图时默认提交到 `/v1/images/jobs/edits`。配置仅给出 BenszAPI 子域名根地址时,客户端会先规范为带 `/v1` 的 API 基址;同步端点只在 job endpoint 明确不支持时兼容回退。submit 在服务端尚无持久幂等契约时只提交一次;结构化 `retryable=false`(包括 `BILLING_PRICING_NOT_CONFIGURED`)立即停止,`2xx` 空/非 JSON 响应也不重试或跨 provider,poll/result 的暂时故障独立处理。默认请求 `quality=low`、最小匹配原生尺寸和 `output_format=jpeg`,输出扩展名、magic bytes、MIME 与 meta 必须一致;PNG/WebP 回退结果导出 JPEG 时以白色合成透明背景。参考图编辑会追加“只改明确要求、保留主体/构图/背景”的契约,并记录原始参考图 SHA-256。 - 回退授权:只有用户主动要求允许回退时,才设置 `allow_provider_fallback=true` 或脚本参数 `--allow-provider-fallback`;回退路径使用 `~/.bensz-skills/config/remote.env` 中的 `GEMINI_BASE_URL`、`GEMINI_API | GEMINI_API_KEY`、`GEMINI_MODEL`。即使已授权,计费、订阅、余额、权限、overage、`BILLING_SERVICE_ERROR` 与 submit 空/非 JSON 等任务创建状态不确定的协议错误仍必须停在原 provider 并展示结构化错误。 8. **视觉评估**: - `scripts/evaluate_image.py` 默认只做启发式文件/分辨率检查并标记 `fallback_mode=heuristic`,不调用 Gemini 文本接口; - 宿主 AI 必须根据最终图片、用户需求与 `evaluation.json` 做语义把关,必要时人工触发下一轮。 9. **多轮优化**:上一轮若未通过,第 `n+1` 轮必须把第 `n` 轮 `output.jpg` 作为第一参考图传给可消费参考图的图片 provider,并把反馈拼进 prompt,要求模型保真微调而不是从零重画;首轮用户参考图也必须标记为 `image-to-image`,来源使用 `user_reference` / `previous_round` / `mixed`。 10. **交付**:输出至少 1 张最终 JPEG;隐藏目录里保留 `meta/result.json` 供追溯。 ### 输出 - 至少 1 张合乎需求的图像;OpenAI 图片模型正式输出默认为 `jpeg`。 - 隐藏目录里的 `meta/analysis.json` / `meta/result.json`:记录每轮 prompt、模型参数、参考图策略、评估结果、最终选图和停止原因。 - 每轮图片 meta 必须区分 `requested_provider_size`、`native_size`、`output_size` 与 `postprocess_resize_applied`;默认 `postprocess_resize_applied=false`。 - `image-debug/gpt-image-2-error.json` 只保留错误类别、HTTP 状态和服务端安全返回的 `error.type` / `error.code` / `error.message`。JSON 与 multipart 请求发送安全 `X-Client-Request-ID`;`2xx` 空正文或非 JSON 正文分别记录 `PROVIDER_EMPTY_RESPONSE` / `PROVIDER_NON_JSON_RESPONSE`,附经白名单校验的 `request_id` / `client_request_id`、origin/path、响应类型、声明/实际长度、SHA-256、首字节类别和重定向布尔值;不得写入 query、Authorization、API Key、Cookie、prompt、原始正文、订阅明细或原始内部错误对象。 - 每轮目录:`rounds/round-XX/prompt.txt`、`rounds/round-XX/prompt-plan.json`、`rounds/round-XX/parallel-plan.json`、`rounds/round-XX/output.jpg`、`rounds/round-XX/evaluation.json` 以及 `image-debug/` / `evaluation-debug/`;OpenAI 图片模型默认主动使用 Sub2API image job endpoint,generation/edit 均显式发送 `quality=low`、原生尺寸和 `output_format=jpeg`,并在 debug meta 中保留参考图 SHA-256。 - run 级 `parallel-vibe/parallel-plan.json` 与 `parallel-vibe/parallel-plan.round-XX.json`:每轮必留痕的 parallel-vibe plan。 ### 输出管理 - 默认工作区是当前目录下的 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/auto-draw-plot/{yyyy-mm-dd-hh-mm}/`;所有中间文件必须留在隐藏目录里,正式交付物不写入该目录。 - 同一任务复用一个任务根目录;多 Skill 协作才创建 `shared/`,本 Skill 专属材料放入 `auto-draw-plot/` 的 `input/`、`output/`、`log/` 子目录。 - 轻量测试目录固定为 `./tests/draw-plot`,中间文件限定在 `tests/draw-plot/_artifacts/`(见「校验」)。 ### 校验 - 轻量测试必须在 `tests/draw-plot` 下完成;每次执行都应该在该目录内生成 `TEST_PLAN.md`/`TEST_REPORT.md`,并把中间文件限定在 `tests/draw-plot/_artifacts/`。 - auto-test-skill 的 A/B 轮也只能操作 tests 目录,确保 `p0-p2` 问题均闭环。 - 视觉语义把关不可脚本化:宿主 AI 必须依据最终图片、用户需求与 `evaluation.json` 复核启发式评估结论后才可交付。 ### 失败与恢复 - 配置冲突:Codex 配置与 BenszAPI 环境变量的 Base URL/API Key 不一致时,必须在发图前停止并报告冲突字段,不得静默使用旧配置。 - 域名校验失败:OpenAI 图片模型出现非 HTTPS、裸域、非白名单域名或缺少 key 时停止,不得绕过校验。 - 指定 provider 失败:暂停并报告原因,输出可执行的配置/额度/端点错误,不自动切到另一个模型;provider 回退仅按「执行步骤」第 7 步的授权边界执行,任务创建状态不确定的协议错误一律停在原 provider 并展示结构化错误。 - submit 失败:服务端尚无持久幂等契约时只提交一次;结构化 `retryable=false`(包括 `BILLING_PRICING_NOT_CONFIGURED`)立即停止,`2xx` 空/非 JSON 响应不重试、不跨 provider;poll/result 的暂时故障独立处理。 - 评估未通过:按「执行步骤」第 9 步进入多轮保真微调;达到 `max_rounds` 或得分平台期仍不达标时,交付当前最优结果并在 `meta/result.json` 记录停止原因。 ## 约束 <!-- BEGIN COMMON CONSTRAINTS --> <!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 --> <!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block --> ### 公共硬约束 本块由 `docs/templates/skill-common-constraints.md` 统一维护;每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块,不得在副本中改写公共规则。 - 任务需要落盘时,使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录;共享材料放入 `shared/`,Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。 - 正式交付物、源代码和正式计划按项目约定保存,不写入任务工作区;未经授权不覆盖、删除、迁移或远程写入。 - 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要;BAC 只做过程审计,不替代署名、责任或合规判断。 - 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。 - 文件路径必须规范化并限制在授权项目范围内;外部 URL、子进程和网络访问遵循最小权限,防止路径遍历、SSRF 和命令注入。 - Skill 版本唯一记录在自身 `config.yaml:skill_info.version`;公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。 - `bensz-collect-bugs` 是一个 Agent Skill;仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`,当前任务不中断,只有用户明确要求才公开上报,禁止直接修改用户已安装的 Skill 源码。 <!-- End of canonical common constraints. --> <!-- END COMMON CONSTRAINTS --> ### Skill 专属约束 - `imagegen` 技能边界:用户要求用 `auto-draw-plot` 画图、改图或基于上一轮继续微调时,只使用本 skill 完成完整链路。不得把它表述或编排为“先生成 prompt,再交给 `imagegen` 出图/编辑”的前处理步骤;这种说法会错误暗示依赖关系,并可能造成重复生图与重复计费。 - 只有用户明确点名同时使用 `imagegen`,或明确要求其独有能力时,才允许额外调用 `imagegen`;调用前说明两者各自独立的职责,且不得将 `imagegen` 伪装成 `auto-draw-plot` 的内部依赖。默认用户可见说明应写明:`本次使用 auto-draw-plot,由其经 BenszAPI 完成 prompt、出图和后续编辑。` 不得默认承诺后续会调用 `imagegen`。 - `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` 与 `gpt-image-2` 只能绑定 `benszresearch.com` 子域名 base URL;非 HTTPS、裸域、非白名单域名或缺少 key 时不得绕过校验。 - 错误诊断与 `image-debug/gpt-image-2-error.json` 不得写入 query、Authorization、API Key、Cookie、prompt、原始正文、订阅明细或原始内部错误对象;诊断证据中的 API Key 只允许不可逆短指纹。 - 历史隐藏目录只允许显式兼容读取、迁移或清理,不做静默处理。 - 因本 skill 设计缺陷导致的 bug 先按公共约束记录到 `~/.bensz-skills/bugs/`;只在用户明确要求 “report bensz skills bugs” 时,才通过本地 `gh` 调用将新 bug 推送到 `huangwb8/bensz-bugs`,上传前必须先脱敏本地路径/用户名等隐私。 - prompt 结构模板与迭代策略见 [references/prompt-guidelines.md](references/prompt-guidelines.md);合法的 `parallel-vibe` shell plan 模板见 [references/parallel-plan.md](references/parallel-plan.md)。
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.