KStudio · 配图工作室

一键把一整段文案变成一套能像翻书一样连着看的配图：第 N+1 张就是第 N 张的下一步， 专门用来做科普 / 教学图文视频的配图。Go + Wails 原生桌面应用，Windows 单文件 exe，无需 Node/npm。

┌─────────────────────────────────────────────────────────────┐
│  决策模型（主模型，不会画图，会调用工具）                   │
│  · 通读全文，把这件事拆成有先后顺序的几步                   │
│  · 自主决定这篇文案配几张图最合适（一步一张）               │
│  · 定一条讲解主线 + 一个贯穿全组的固定主体                  │
│  · 逐张写明「承接上一张什么」「本张推进什么」               │
│  · 写出一份「全组统一视觉设定」（画风/主色/光线/镜头/人物）  │
│  · 通过 function call 逐张驱动生图、检查结果、必要时重画     │
└───────────────────────────┬─────────────────────────────────┘
                            │  tool call
┌───────────────────────────▼─────────────────────────────────┐
│  生图模型（qwen-image-3.0-pro 等，只管出图）                │
│  百炼同步/异步、OpenAI 图像/对话、Gemini 原生、自定义模板   │
└─────────────────────────────────────────────────────────────┘

两个模型使用两套完全独立的 Base URL / API Key / 模型名。生图这一侧不绑定阿里云， 选对「接入方式」就能接任意服务商，见生图模型可以换成任何服务商。

每张图都会带上这一段文案的完整讲解文字（小标题 + 若干条要点），所以关掉声音只看图 也能读完整篇，见每张图都是一页讲解板。

比例可以交给主模型判断，分辨率由你定档（快速 / 标准 / 高清 / 自定义）；单张失败 会自动重试，一整轮跑完还有没成的可以一键批量重试。

---

快速开始

1. 环境

依赖	说明
Go 1.23+	go version
Wails CLI	go install github.com/wailsapp/wails/v2/cmd/wails@latest
WebView2	Windows 10/11 一般已自带；缺失时首次运行会提示安装

国内网络建议先设好 Go 代理：

go env -w GOPROXY=https://goproxy.cn,direct

2. 构建

build.bat

或手动：

CGO_ENABLED=0 wails build -platform windows/amd64 -clean

产物：build\bin\KStudio.exe（可直接拷走使用）。

CGO_ENABLED=0 不是可选项：Wails 在 Windows 上不需要 cgo，关掉它才能在 32 位 gcc 环境下正常交叉编译 amd64。

开发调试用 dev.bat（wails dev，改完前端文件刷新即可，无需重新编译）。

3. 首次配置

首次启动会自动弹出设置窗口，两块配置互不影响：

决策模型 · 主模型

项	示例
Base URL	https://dashscope.aliyuncs.com/compatible-mode/v1
模型名	qwen-max / qwen-plus / qwen3-max
API Key	百炼控制台的 sk-…

要求：支持 OpenAI 兼容的 tools / tool_calls（function call）。不需要绘画能力。 决策模型不限于阿里云，任何 OpenAI 兼容接口都能用：

服务商	Base URL 填	模型名
阿里云百炼	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-max / qwen-plus
DeepSeek	https://api.deepseek.com	deepseek-chat
Kimi	https://api.moonshot.cn/v1	kimi-k2-0905-preview
火山方舟	https://ark.cn-beijing.volces.com/api/v3	你的接入点 ID
本地 Ollama	http://localhost:11434/v1	支持 tools 的模型

DeepSeek 请用 deepseek-chat。deepseek-reasoner 不支持 function call，本软件靠工具 调用驱动整个流程，用它会直接报错或退化成兜底分段。

生图模型

项	示例
Base URL	https://dashscope.aliyuncs.com
模型名	qwen-image-3.0-pro
API Key	独立填写，可以和上面不同
接入方式	自动识别

如果你在百炼开了专属部署，把 Base URL 换成专属域名即可，例如 https://llm-e53voc5tsftei314.cn-beijing.maas.aliyuncs.com。

两处都有「测试连接」：

• 决策模型：发一条 64 token 的最小请求，返回模型原话。
• 生图模型：不花钱。OpenAI 形状的接口先查 /v1/models，模型名在列表里就直接报「已就绪」； 查不到列表时才退回探针 —— 故意发一个不完整的请求，接口回「参数缺失」就说明 URL / Key / 模型名三者都对。 模型名不对会明确说出来，并列出这个接口自己有哪些图像模型，不会再报「连接成功」。

---

生图模型可以换成任何服务商

生图这一侧不绑定阿里云。不同服务商的差别其实只有请求和响应长什么样，所以设置里 用「接入方式」来选，一种接入方式覆盖所有抄了同一套格式的网关：

接入方式	谁在用	Base URL 填	参考图
自动识别（默认）	按 Base URL 猜下面某一种，认不出就按 OpenAI 图像接口	—	—
DashScope 多模态生成	阿里云百炼 qwen-image-3.0 / -pro，含专属部署	https://dashscope.aliyuncs.com	支持
DashScope 异步文生图	百炼 wan2.2-t2i-* / wanx-*：先提交任务再轮询	https://dashscope.aliyuncs.com	支持
OpenAI 图像接口	OpenAI、Azure、硅基流动、ModelScope、one-api / new-api 中转站	https://api.siliconflow.cn/v1	支持
OpenAI 对话接口出图	中转站把 gemini-*-image / gpt-image 挂在对话接口上	https://your-relay.com/v1	支持
Gemini 原生接口	Google generateContent，图片走 inline_data	https://generativelanguage.googleapis.com	支持
自定义请求模板	以上都不是的自建 / 冷门服务	见下	看模板

Base URL 填写很宽容，只填域名就行，剩下的路径按接入方式补全；已经是完整地址就原样使用。 设置面板下方的灰色小字实时显示「接入方式 → 真正会被请求的完整地址」：

接入方式	你填的	实际请求
DashScope 多模态	https://dashscope.aliyuncs.com	…/api/v1/services/aigc/multimodal-generation/generation
DashScope 异步	https://dashscope.aliyuncs.com	…/api/v1/services/aigc/text2image/image-synthesis
OpenAI 图像	https://dashscope.aliyuncs.com	…/compatible-mode/v1/images/generations
OpenAI 图像	https://api.siliconflow.cn/v1	…/v1/images/generations
Gemini	https://generativelanguage.googleapis.com	…/v1beta/models/<模型名>:generateContent

几件不用你操心的事：

• 响应格式不用配。图片在 output.choices[].message.content[].image、data[].url、 data[].b64_json、candidates[].content.parts[].inlineData.data，还是只在回复正文里写了 个链接，都能找到；base64 直接解码存盘，扩展名按图片字节判断。
• 异步接口不用配。回的是任务号就自动轮询到出图为止。
• 参数不兼容会自动降级。先按完整参数发，服务商嫌某个字段不认识（尺寸、负向提示词等）， 同一条提示词立刻用最小请求重发一次，图片列表里会标注「已降级」。
• 参考图会自动换端点。OpenAI 图像接口的 /v1/images/generations 没有图片字段，所以带参考图时 自动改发 /v1/images/edits（multipart，重复的 image[]）。真正放不下参考图的只剩没写 {{ref_image}} 的自定义模板，选它时设置面板会提示「用首图锁定风格」本次不生效，整组图的统一 靠全局视觉设定的文字维持 —— 而不是悄悄丢掉。

自定义请求模板

上面六种都对不上时选「自定义请求模板」，自己写请求体。占位符会在发送前替换：

占位符	含义
{{prompt}} / {{negative_prompt}}	提示词 / 负向提示词
{{model}} / {{api_key}}	模型名 / API Key
{{size}} / {{size_x}}	1664*928 / 1664x928
{{width}} / {{height}} / {{n}}	纯数字，不带引号也合法
{{aspect_ratio}}	16:9
{{ref_image}}	参考图地址，写了它才有参考图一致性
{{task_id}}	只在「轮询地址」里可用

例如一个 POST 到自建服务、把图片放在 result.images[0] 的模板：

{
  "model": "{{model}}",
  "prompt": "{{prompt}}",
  "negative_prompt": "{{negative_prompt}}",
  "width": {{width}},
  "height": {{height}}
}

其余几栏：

• 请求地址：留空就用上面的 Base URL；可以带 ?key={{api_key}}。
• 请求头：一行一个 名称: 值，# 开头是注释。没写 Authorization 就自动加 Bearer <你的 Key>；写了 {{api_key}} 就不再重复加。
• 图片字段路径：留空自动查找，填了就优先，例如 result.images.0。
• 轮询地址 / 任务号路径：只有异步接口需要，例如 https://…/jobs/{{task_id}}。

提示词里的引号和换行会自动做 JSON 转义，撑不破模板；填完的请求体如果不是合法 JSON， 会在生成前就报错，而不是发出去等对方拒绝。

自定义模板的「测试连接」只做离线校验（地址、请求头、请求体能不能拼成合法 JSON、 有没有 {{prompt}}）。因为这是你自己写的请求，真发出去就是一次真实出图、要计费 —— 所以能不能出图，请点一次「一键生成配图」试。

---

使用

1. 左上「新建配图」。
2. 粘贴文案（口播稿、脚本、图文正文都行）。也可以留空 —— 留空就是 无文字模式：不往画面里加任何文字，由生图模型自由发挥。
3. 画面风格提示词：完全自己写，软件不提供任何预设风格。这段文字会 原样附加到每一张图的提示词末尾，并被主模型吸收进全局视觉设定，优先级最高。
4. 可选项：画面比例（留「由主模型决定」就让它自己判断）、分辨率档位、 最多张数（上限，实际张数由主模型决定）、并发数。
5. 「一键生成配图」或 Ctrl + Enter。

比例与分辨率

比例交给主模型（它按内容判断该横还是该竖），分辨率永远由你决定 —— 出图像素 是计费项，不该让模型替你花钱。选择器下方那行小字实时显示这一组图真正会请求的 像素尺寸。

档位	1:1	16:9	9:16	4:3	3:4	3:2	2:3
快速	1024×1024	1280×720	720×1280	1152×864	864×1152	1248×832	832×1248
标准	1328×1328	1664×928	928×1664	1472×1104	1104×1472	1584×1056	1056×1584
高清	2048×2048	2560×1440	1440×2560	2304×1728	1728×2304	2400×1600	1600×2400

• 标准档是 qwen-image 官方文档给出的尺寸表，兼容性最好，默认就用它。
• 自定义：手写 宽*高（1920x1080、1920 × 1080 都能识别），两边取值 512–4096。填了自定义尺寸就以它为准，比例设置不再生效，卡片框会按这个尺寸显示。
• 一个项目的比例和分辨率在开跑时就定下来，写进 project.json。之后单张重生成、 改提示词重画、批量重试都沿用同一套 —— 一组配图里混着不同尺寸会直接破坏一致性。
• 快速档和高清档不在官方表里。万一某个部署不认，发送 size 参数 的自动降级机制 会兜住：软件会去掉 size 重试，并在日志里警告。

右侧「决策过程」实时显示主模型每一步在想什么、调了哪个工具；分镜卡片会从骨架屏 逐张变成成品图。

配图为什么能像翻书一样连着看

做科普和教学的图文视频，观众是按顺序一张一张往下看的。所以这里要的不是「几张 风格统一的插图」，而是第 N+1 张就是第 N 张的下一步。判断标准很硬：把标题 全遮住，只把相邻两张并排放，能看出这是同一件事的前后两步才算成功。

这件事分两层，各管各的，别混为一谈：

内容连贯（主）—— 靠分镜与提示词

1. 一条讲解主线：主模型先写 narrative —— 第 1 张讲什么 → 第 2 张讲什么 → …… 一句一步。配图数量 = 讲清这件事需要的步数，一张只讲一步。
2. 一个贯穿全组的固定主体：recurring_subject 指定同一个人物 / 同一件器物 / 同一处场景 / 同一套图解装置，并给出可复现的固定外观。它是把每张图串起来的线。
3. 每张写明承接与推进：carry_over 是与上一张画法完全相同的那件具体东西， change 是本张唯一的变化。合法的承接关系有四种：时间推进（水刚冒泡→水翻滚）、 空间推进（全景→细节特写）、因果推进（按下开关→灯丝亮起）、结构推进 （画出主干→挂上分支）。
4. 发给生图模型时把上一张也带上：软件在每条提示词后自动附加「上一张画的是 ……／必须延续……／唯一的推进……」，所以生图模型知道自己在画第几页、上一页 长什么样。这是链式的 —— 第 3 张承接第 2 张，不是都去承接第 1 张。
5. 主模型还被要求复用措辞：描述延续元素时用与上一张完全相同的词。生图模型 只认字面，换个说法就会画成另一个东西。

分镜卡片上直接显示 承接 和 推进 两行，右侧「连贯契约」显示讲解主线和 固定主体 —— 图还没出你就能先校对逻辑对不对。哪一张漏了承接关系，日志会点名警告。

视觉一致（次）—— 靠视觉设定与基准图

1. 统一视觉契约：style_guide 固定画风、主色调、光线、镜头语言、质感， 全组共用，附加在每条提示词后面，模型无法"忘记"。
2. 基准图参考（默认开启）：第 1 张单独渲染，再作为 reference image 传给后续 每一张，用像素约束画风和主体长相。它只锁定长相，不锁定构图 —— 传给生图模型的 提示词明确禁止照抄参考图的取景，每张的机位、景别、姿势表情由这一张自己的 image_prompt 决定（见动感与构图变化），否则整套图会像同一个 镜头复制粘贴一样死板。相邻两张不再互当参考图。不想要这种像素级约束就关掉它， 画风统一改由视觉设定文字维持。

单张改提示词或重生成后，整条链会重新拼一遍：改了第 3 张，第 4 张引用的「上一张」 也跟着更新。

动感与构图变化

一套图最怕「复制粘贴」：同一个机位拍了十张，只换文字。系统提示词要求每一张都 有自己的机位与构图——镜头高度、景别、角度、主体在画面里的位置、人物的姿势与 表情，结合这一张要讲的内容重新设计；相邻两张的取景必须明显不同。分镜的 image_prompt 里会写明本张的机位（例如「低角度仰拍」「俯拍斜构图」）。

如果整组风格是漫画 / 插画，还会主动上漫画语言：夸张透视、仰角俯角、斜线构图、 速度线与动势线、夸张表情与动作张力。这不是把风格写死，而是「连贯但每张都活」。

每张图都是一页讲解板

做出来的是图文视频，观众可能只看图不听声，也可能只听声不看图 —— 两种都得拿到 完整信息。所以每张图上都要有字，而且不是一句标题，是这一段文案的完整内容： 第一行小标题，换行后 2–4 条要点。

• 主模型从这一张对应的 script_segment 里写出这块文字，不设字数上限：关键的 数字、术语、结论都要写进去。检验标准是「把声音关掉，只看这一张图，能不能读懂这一段」。
• 全部图的文字连起来读，本身就是一份能独立读完的图文稿。
• 文字区的位置、大小、衬底、字体写进全组统一视觉设定，所以每张都落在同一个地方， 连着看不会跳；具体怎么排由主模型自己定。
• 页码、序号、1/7 这类进度标记会被拦掉 —— 一旦画进角落，后面每张都会把它当参考图抄下去。
• 分镜卡片上直接显示这块文字（保留换行），分镜说明.md 里也有，方便你对着成图逐条核。

字给得越多，生图模型写中文越容易缺笔画、漏掉后面几条要点，或者把上一张的字抄过来。 提示词里已经反复强调「一字不差、一条不漏、不要改写不要缩写」，主模型每画完一张也会 收到这块文字以便自查，但成图请你自己核一遍：发现问题就重画这一张，或让它把要点拆得更短。

无文字模式

口播稿留空时进入无文字模式：整组图不往画面里加任何文字，标题、要点、说明都不画， 把全部精力留给画面本身——构图、动态、氛围、主体的表现力，由生图模型自由发挥。

• 主模型从项目标题出发自由规划分镜（建议张数 3–8），screen_text 一律留空， 提示词里也不会出现「画面内文字」那一节。
• 这一模式与「动感与构图变化」天然合拍：没有文字区的约束，构图更自由。
• 想要文字就填一口播稿，填了自动切回讲解板模式；同一个项目中途改口播稿， 从下一次生成起生效。

失败自动重生成

单张图失败时软件不会就这么放着，而是自己重发，默认 2 次（设置里 0–5 次）。 等待间隔递增 4s → 10s → 18s → 28s → 40s，避免在限流时越撞越死。生成中的卡片会 显示「第 N 次尝试…」，最终失败的卡片会注明「已自动重试 N 次」。

不是所有失败都值得重试，软件会先判断错误类型：

错误类型	处理
超时、连接中断、限流（429）、5xx、空响应	自动重试
Key 错误、URL 错误、模型不存在、额度不足（401/403/404 等）	不重试，直接报错。重发一模一样的请求不可能变好，只会拖时间
内容审核拒绝	不重试，交回决策模型 —— 它会用 revise_shot 改写提示词再画，这才是解法

重试次数会写进 project.json，也会回报给决策模型，它在收尾时能看到"这张已经 试过 3 次"，从而决定是改写提示词还是放弃这一张。

整轮跑完后如果还有没成的，项目标题右边会出现 重试未成功的 N 张，一次把它们 全部重新排队（沿用项目原本的比例与分辨率）。

逐张微调

每张卡片下方：

• 重生成 —— 用同一条提示词重画（换个采样结果）
• 改提示词 —— 只改这一张的画面描述；展开可以看到"实际发送给生图模型的 完整提示词"（场景 + 与上一张的承接 / 推进 + 固定主体 + 全局视觉设定 + 你的风格）
• 复制 / 定位 —— 复制提示词、在资源管理器里定位图片文件

---

文件管理

每个项目一个文件夹，输出目录可在设置里改（默认 ~\Documents\KStudio）：

20260806-215430-a3f1-城市夜骑三分钟/
├── 01-霓虹下的车流.png
├── 02-骑行者侧脸特写.png
├── 03-空荡的高架桥.png
├── project.json        完整项目数据（分镜、提示词、日志、token 用量）
└── 分镜说明.md          人类可读：讲解主线 / 固定主体 / 每张的承接与推进 / 画面文字 / 提示词 / 原文

• 全部图库：跨项目浏览所有成品图，点开大图，左右方向键翻页。
• 导出：把成品图 + 分镜说明.md 拷到你选的任意目录。
• 重命名：改显示标题，磁盘文件夹名保持不变（不会破坏已有引用）。
• 删除：连同文件夹一起从磁盘移除，会二次确认。
• 生成中途关掉软件，下次打开项目会自动把"卡在生成中"的分镜标回失败，之后可以 单张重生成，也可以用 重试未成功的 N 张 一次全部重排。

配置文件在 %AppData%\KStudio\config.json（权限 0600，API Key 存在这里）。

软件早先叫 QwenImageStudio。第一次启动新版会自动把 %AppData%\QwenImageStudio 整个改名过来，Key 和设置都在，不用重填；~\Documents\QwenImageStudio 里的作品 也会一起搬到新目录并更新配置——前提是你没改过输出目录，改过的一律原样保留。

---

设置项说明

选项	作用
生图接入方式	决定请求发成什么格式，见生图模型可以换成任何服务商
默认画面比例	新建项目的初始值；由主模型决定 让它按内容判断
默认分辨率	快速 / 标准 / 高清 / 自定义，见比例与分辨率
失败自动重试	0–5 次，默认 2。只重试有可能好转的失败，见失败自动重生成
prompt_extend	让生图模型自动扩写提示词，细节更丰富，但会略微偏离原描述
参考图一致性	每张带第一张作参考图，只锁画风与主体长相，构图由每张自己设计；关掉后每张图独立生成，画风统一只靠视觉设定文字
发送 size 参数	按上面的档位指定分辨率（标准档 16:9 → 1664×928）。若接口不认这个参数，软件会自动降级只发 prompt_extend 重试一次，并在日志里给出警告
水印	图片角落添加模型水印
负向提示词	所有图共用，例如 水印, logo, 多余的手指, 畸变。不要写「文字」 —— 每张图的讲解文字要靠生图模型画出来
决策模型 max_tokens	分镜多、文案长时可以调大
并发生成	同时请求几张图。基准图永远单独先跑完

---

代码结构

main.go                  Wails 入口、窗口、embed 前端、/media 静态图片服务
app.go                   暴露给前端的全部 API（设置、项目、导出、剪贴板…）
internal/config/         两套 Provider 配置、URL 推导、持久化
internal/llm/            OpenAI 兼容 chat client，function call + 重试 + 错误提取
internal/imagegen/       生图 client：参数自动降级、异步轮询、多格式响应兼容
internal/imagegen/protocol.go 六种接入方式的请求驱动 + 自定义模板的占位符替换
internal/store/          项目文件夹读写、图库、导出、原子保存
internal/engine/         主模型工具循环（分镜 → 生图 → 修图 → 收尾）
internal/engine/prompts.go   系统提示词、5 个工具的 JSON Schema、逐张提示词与画面文字的链式拼接
frontend/dist/           手写静态前端（无构建步骤）：index.html / app.css / app.js / logo.png
logo.png                 logo 源文件（1254×1254）；build/appicon.png 与 build/windows/icon.ico 由它缩放而来

前端故意不用任何框架和打包器：wails.json 里 frontend:install 与 frontend:build 都是空字符串，frontend/dist 直接被 go:embed 打进 exe。 改前端只要编辑那三个文件。

主模型可用的五个工具：

工具	用途
create_storyboard	提交图片数量、画面比例、讲解主线、贯穿主体、全局视觉设定，以及逐张的承接 / 推进 / 提示词 / 画面文字
generate_next	画一张。一次只画一张，画完立刻把结果返回给主模型，它必须先读结果再决定下一步
update_shots	只改后面还没画的分镜的文字（不出图）：前面实际画成的样子和原方案对不上时，让承接措辞跟着改
revise_shot	改写某一张的提示词并立刻重画（每张最多 2 次），可同时改承接 / 推进 / 画面文字
finish	收尾并给出总结

---

常见问题

「InvalidApiKey」/ 401 — Key 填错，或把决策模型的 Key 填进了生图模型那栏（两栏独立）。 报错里会附上「本次发送的 Key：长度 N，结尾 xxxx」，对一下就知道发出去的是不是你以为的那串。 如果结尾是 .com，说明网址被粘到 Key 那一栏了 —— 现在这种情况会在发请求前就被拦住并直接说明。

404 Not Found — Base URL 与接入方式对不上。报错里会点出当前用的是哪种接入方式； 再看设置面板里灰色小字显示的「接入方式 → 实际地址」，和你在控制台看到的接口地址对比。 比如把中转站的 /v1 填进去却留着「DashScope 多模态生成」，就会 404。

「生图响应里没有图片地址」 — 请求通了但回复里找不到图。报错会附上接口原文： 如果原文里其实有图片字段，只是路径少见，选「自定义请求模板」把图片字段路径填上 （例如 result.images.0）即可；如果原文是模型在道歉，那就是这个模型不出图。

「model not exist」 — 模型名拼写或该 Key 没开通该模型。

决策模型不调用工具 — 换一个支持 function call 的模型（qwen-max、qwen-plus）。 软件会先提醒它两次，仍不调用就退化成自己按段落切分兜底，但效果不如模型自己规划。

画面里的字不对 — 每张图本来就要有字（见每张图都是一页讲解板）， 所以负向提示词里不要写「文字」，写了会把该有的讲解文字一起压掉；水印, logo 可以留。 缺笔画、漏掉后面几条要点、或者抄了上一张的字，都用「改提示词」重画这一张，或让主模型把要点拆得更短。

参数被降级的警告 — 说明你的接口（尤其是专属部署）不支持 size / negative_prompt / watermark。软件已自动重试成功，可以在设置里关掉「发送 size 参数」消掉警告。

相邻两张看不出前后关系 — 先看卡片上的 承接 / 推进 两行：那是主模型自己写的 逻辑，图只是它的执行结果。承接写成「风格一致」「氛围延续」这类空话，或者两张的推进 其实是同一件事，说明是规划没写好，不是生图模型的问题 —— 换一个更强的决策模型，或者 在文案里把步骤讲得更清楚。承接写得具体（指名了某件东西）而图还是没接上，就用 「编辑提示词」把那件东西直接写进画面描述，用与上一张一模一样的措辞。

---

致谢

感谢 ztoken 提供算力支持。

本项目的开发与调试离不开它稳定的模型接入 —— 决策模型和生图模型的大量真机联调、 逐张出图的反复验证，都跑在它的算力上。