把 ComfyUI 包成一个能直接用的本地出图工作台。 填提示词、点生成,其余全在界面上。
面向 8–16GB 显存的消费级显卡:多架构预设、LoRA 按架构隔离、参数配方可存可分享。
不含推理引擎,也不含任何模型权重。 引擎(ComfyUI)与底模由
install.md指导安装——把仓库链接交给你的 agent 即可。
ComfyUI 本身很强,但有个日常成本:每换一个底模,就要重来一遍。
换 Anima 要 Euler + sgm-uniform、28 步、CFG 4;
换 Krea 2 要 Euler + Simple、8 步、CFG 1,而且 shift 是烤死在模型里的;
换 Z-Image 要 Res Multistep + Simple、9 步,编码器还得换成 lumina2 类型。
走错一步不会报错,只会给你一张糊图——然后你要花十分钟才意识到是采样器选错了。
KlockUI 把这些固化成代码里的架构知识:
# comfy_bridge.py 里的一小段
zimage: {
"sampler": "Res Multistep", "scheduler": "Simple",
"steps": 9, "cfg": 1.0, "shift": 3,
"clip_type": "lumina2", # 不是 stable_diffusion
"te": "qwen_3_4b_fp8_mixed.safetensors",
"vae": "ae.safetensors",
}换模型时它自动套用,你只关心画面。
选定底模,采样器、调度器、步数、CFG、shift、文本编码器类型、VAE 全部自动就位。 架构靠权重张量名判断,不看文件名——文件可以随便改名,权重不会说谎。
一支 Krea 2 的画风 LoRA 只会在 Krea 2 下出现,切到 Anima 就自动隐藏。 每支可单独拖权重,未启用的会显示建议默认值。
界面上调好的整套设置导出成一个 .json,拖回界面即还原:
模型 + 画质档 + 尺寸 + 步数 + CFG + 采样器 + 调度器 + shift + 种子 + LoRA 及其权重
| 仓库配方一键导入 | 「参数预设」里直接列出 presets/ 的示例,点导入即可,不用翻文件 |
| 配方编辑器 | 界面里直接改 JSON,实时校验语法,保存写回 presets/(覆盖前自动 .bak) |
| LoRA 搜索 | 按名称、触发词、说明即时过滤,几百支也不难找 |
| A/B 对比 | 两张图并排看,滚轮同步缩放,下方只列参数差异 |
| 提示词历史 | 最近 30 条提交过的提示词,可搜索、一键回填(含步数与底模) |
| 本地图库 | 生成的图带参数存档,可回填到界面重出 |
| 局部重绘 | 画蒙版只重画那一块,其余不动 |
| 高清二采 | latent / 像素放大 + 低噪重绘,一处开关 |
| 图反推标签 | WD14,拖张图进来出标签(需 onnxruntime,可选) |
| 控制图 | LLLite 等条件图,按架构显示 |
| 中文界面 | 提示词中英皆可,界面全中文 |
| 架构 | 参数 | 默认配方 | 许可 |
|---|---|---|---|
| Anima 2.9B | 2.9B | Euler + sgm-uniform,28–50 步,CFG 3.5–5 | 非商用 |
| Z-Image Turbo | 6B | Res Multistep + Simple,9 步,CFG 1 | Apache-2.0 |
| Krea 2 Turbo | 12.9B | Euler + Simple,8 步起,CFG 1 | 社区(年收 <100 万美元免费) |
| MOSS-Image | 5B | Euler + Simple,50 步,CFG 3 | Apache-2.0 |
| SDXL / Pony / Illustrious | 6–7B | DPM++ 2M SDE + Karras,20–30 步 | 见各模型 |
加一个新架构要改七处:后端四处(_classify 识别、_modules_for 依赖、build_graph 节点图、ALLOWED_ARCHS 白名单),
前端三处(MODEL_PROFILES、SAMPLER_SETS、archForModel)。
白名单那处最容易漏——漏了不会报"未知架构",而是把 arch 静默换成上一个用过的,
再以错误的编码器报一个看不懂的维度错。完整步骤见 skill.md 第六节。
方式 A · 仓库链接(agent 自己 clone)
把下面这句话发给你的 agent(Claude Code / Cursor / WorkBuddy 等都可以):
安装 https://github.com/KlockTX/KlockUI ,按仓库里的
install.md执行。
方式 B · 安装包(推荐 · 不用 git)
从 Releases 下载 KlockUI-x.y.z.zip,
把压缩包文件本身发给 agent,并说:
安装这个压缩包:
<拖入 KlockUI-x.y.z.zip>,按包里的install.md执行安装配置。
包里自带 AGENT-INSTALL.md,agent 解压后会按同一套流程装。不需要 agent 会 git clone,
也不需要它访问 GitHub。
两种方式拿到代码后,剩下的交给 agent:install.md 和 skill.md 会引导它
先探测本机已有的 ComfyUI(有就复用,不重复装)、建 Python 环境、按显卡选量化档、
问你要装哪些模型、逐个文件校验下载、装好 skill.md,最后跑一张测试图验收。
仓库和包里都不含模型权重——但不需要你自己下载:agent 会按你的选择逐个装并校验。
手动装也可以,install.md 里每一步都带断言,照着走即可。
装完后启动:
start.bat :: Windows:拉起引擎 + 界面,然后打开浏览器
stop.bat :: 只停界面,引擎保留# 任意平台
../ComfyUI/venv/bin/python server.py三个进程都在本机:浏览器只是界面,KlockUI 负责把表单翻译成节点图,ComfyUI 执行,GPU 出图。 没有任何云端调用,图片和提示词不出本机。
导出的 JSON 长这样:
{
"klockui": 1,
"name": "雨夜霓虹 · 回眸",
"model": "krea2_turbo_int8_convrot.safetensors",
"arch": "krea",
"prompt": "anime illustration, cel shading, clean lineart, ...",
"quality": "standard",
"size": { "ratio": "2:3", "width": 1024, "height": 1536 },
"steps": 12,
"cfg": 1,
"sampler": "Euler",
"scheduler": "Simple",
"loras": [
{ "name": "krea2_yoneyama_mai", "weight": 0.75 },
{ "name": "krea2_cyberpunk_anime", "weight": 0.6 }
]
}字段优先级:model → quality → 显式字段 → loras。
quality 是档位名(gacha/draft/standard/fine/hires),会一次性写入步数、CFG、二采;
JSON 里再写 steps 则以显式值为准。
presets/ 里有 26 个可直接使用的例子,字段说明见 presets/README.md。
二次元向的画师 LoRA 串、触发词与提示词模板整理在 docs/anime-recipes.md;
生成耗时的实测拆解见 docs/performance.md。
所有路径都有默认值,也可用环境变量覆盖:
| 变量 | 默认 | 说明 |
|---|---|---|
KLOCK_COMFY_URL |
http://127.0.0.1:8188 |
引擎地址 |
KLOCKUI_PORT |
7861 |
本服务端口 |
KLOCK_MODELS_ROOT |
自动探测 | 模型根目录 |
KLOCK_DIFFUSION_DIR |
<root>/diffusion_models |
DiT 族底模 |
KLOCK_CHECKPOINT_DIR |
<root>/checkpoints |
SDXL 系整模型 |
KLOCK_VAE_DIR |
<root>/vae |
VAE |
KLOCK_LORA_DIR |
<root>/loras |
LoRA |
模型根目录探测顺序:KLOCK_MODELS_ROOT → <repo>/../models → <repo>/models → <repo>/../ComfyUI/models。
为什么不用 ComfyUI 原生界面?
原生界面是给"搭工作流"用的,KlockUI 是给"今天出 50 张图"用的。 如果你的用法是每次都从零连节点,那原生界面更适合你——这不是替代品。
需要多少显存?
| 显存 | 能跑 |
|---|---|
| 6GB | Anima(int8)+ 较低分辨率 |
| 8GB | Anima / Z-Image 舒服,Krea 2 需 --lowvram 且较慢 |
| 12GB+ | 全部架构可用 |
| 16GB+ | 全部架构 + 更高分辨率与二采 |
模型从哪来?
models.manifest.json 里每个文件都有地址、精确字节数、许可。
安装时 agent 会问你要哪几个架构,只下你选的。仓库本身不含任何权重。
能商用吗?
代码 GPL-3.0。模型各自授权:Z-Image / MOSS 是 Apache-2.0,Krea 2 有营收门槛,
Anima 系是非商用。拿它接单前请先看清楚 license 字段。
图片会被上传吗?
不会。没有账号、没有遥测、没有外部请求,除非你自己去下载模型。
支持 macOS / AMD 吗?
代码是纯 Python + 原生前端,理论上都能跑。但只在 Windows + NVIDIA 上验证过, MPS / ROCm 下出问题不奇怪;提 issue 我会看,但不保证能修。
划清边界,省得你装了才发现不对:
- ❌ 不训练 LoRA —— 那是 AI Toolkit / kohya 的事
- ❌ 不做模型下载加速 —— 只给地址,不搭代理
- ❌ 不做云端 / 多人协作 —— 单机工具
- ❌ 不做移动端适配 —— 手机能看,但别指望好用
- ❌ 不保证复现论文级参数 —— 各架构配方来自官方文档与实测,不是推演
KlockUI/
├─ server.py # HTTP 服务、任务队列、图库、鉴权
├─ comfy_bridge.py # 参数 → ComfyUI 工作流;所有架构知识都在这
├─ interrogate.py # WD14 图反推(可选)
├─ index.html # 单页前端
├─ assets/
│ ├─ app.js # 前端逻辑:面板、预设、拖拽
│ ├─ artists.js # 画师词库
│ └─ characters*.js # 角色词库
├─ vendor/ # mdui + 图标字体(离线,无构建步骤)
├─ presets/ # 26 个示例配方
├─ docs/ # 架构图 · 二次元配方 · 前端约定
├─ install.md # 安装说明(写给 agent)
├─ AGENT-INSTALL.md # 仅发行包内有:告诉 agent「这是压缩包,照 install.md 装」
├─ scripts/
│ └─ make_release.py # 生成发行包(只打 git 受控文件)
├─ skill.md # 配置知识与排错(写给 agent)
└─ models.manifest.json # 模型清单
没有构建步骤:前端是原生 JS + CSS,vendor/ 里的依赖直接引用。
clone 下来就能跑,不需要 npm install。
欢迎 issue 和 PR。几个让合并更顺畅的约定:
- 架构相关改动:先在 issue 里说明依据(官方文档 / 实测数据),不要凭印象调参数
- 新增架构:四处一起改,别只改
_classify - 提交前自检:
python -c "import server, comfy_bridge"与node --check assets/app.js都要过 - 别提交模型文件:
.gitignore已挡,但 PR 里塞大文件会被拒
排错思路和已知坑写在 skill.md 里,改代码前建议先扫一眼。
代码:GPL-3.0。
模型权重不适用本许可。各架构授权见 models.manifest.json 的 license 字段,
其中 Anima 系为非商用,商用前请自行替换。
