一个本地小服务,把 AI skill 的规则动态喂给 ComfyUI 的 LLM 节点。
你只在节点里写一句场景声明(如 krea2 扩写),规则由桥从 skill 目录现场读取。
换底模时只改那一句声明,规则本身一个字都不用动。
🌐 English docs: README.en.md · deploy-with-dsh.md
🚀 如果你在用 DSH:不用手动装。把
deploy-with-dsh.zh.md的完整路径发给你的 DSH Agent, 说一句「按这个文件帮我装好」,它会自己探环境、识别可用的 LLM 服务、写配置、跑通实测再回报。
| 插件 | 必需性 | 提供什么 | 项目地址 |
|---|---|---|---|
| ComfyUI-ZML-Image | 必需 | LLM 节点全套:模型加载器V2(读 API 配置)、系统提示词(填场景声明的那一句)、参数设置(温度 / 最大 Token 数)、对话主程序(发请求拿回复)、过滤思考(去掉推理模型的思考块)。这套节点用官方 openai SDK,所以任何 OpenAI 兼容服务都能接 |
https://github.com/zml-w/ComfyUI-ZML-Image |
| skill-bridge-toolkit | 可选 | Anima 提示词校验 节点:确定性校验 tag(规范化 / 上位词折叠 / 槽位冲突 / 长度)+ 审核拒绝检测 |
本仓库 plugins/ 目录 |
| ComfyUI-NL-PromptForge | 可选 | NL Prompt Forge 黑名单过滤 节点:兜底清掉意外漏出的代码块标记。本仓库校验节点的审核拒绝检测判据(双重命中词表 + 标点折叠)参考了该插件的实现 |
https://github.com/Helives12580/ComfyUI-NL-PromptForge |
本仓库不含 skill,skill 需要自行安装并调用;规则内容不在仓库里。装好之后按第四节把
bridge_config.json的routes指向你自己的 skill 即可。
LoadImage / DanbooruGallery ← 图片(可选,要先缩到长边 1024~1536)
│
▼
BSK_Tagger (wd14 本地打标) ← 本机打标,不烧 token
│
▼
AnimaTKDanbooruTagGetter ← 分类过滤
│
▼
DanbooruTagSorterNode / TK String Router / PromptCleaner
│
▼
ZML_LLM 对话主程序 . user_input ──────┐
ZML_LLM 对话主程序 . input_image ─────┤ 图片与文本一起送进 user 消息
│ (OpenAI 多模态格式,base64)
ZML_LLM 模型加载器V2 ── . model_config┤
ZML_LLM 系统提示词 ── . system_prompt ← 只写一句场景声明:krea2 扩写
ZML_LLM 参数设置 ── . params ┘ 最大Token数 设 8192
│
│ 请求发往 http://127.0.0.1:8899/v1
▼
┌──────────────────────────────────────────────────┐
│ skill-bridge(本仓库) │
│ 1. 按场景声明选 skill 与参考文档 │
│ 2. 拼出两万多字的 system prompt(规则+覆盖层) │
│ 3. 命中缓存就直接回放,不碰上游 │
│ 4. 转发给真正的 LLM 服务 │
└──────────────────────────────────────────────────┘
│
▼
模型返回正文(三段式长稿)
│
▼
ZML_LLM 过滤思考 ← 去掉推理模型的思考块
│
▼
Anima 提示词校验 ← 节点侧兜底:校验 + 拒绝检测
│
▼
CLIPTextEncode → KSampler . positive → ControlNet 图生图
ZML 的 系统提示词 节点是静态的:你把规则全文写进去,它就一直发那一份。
这在换底模时很麻烦——krea2 要三段式长稿、anima 要短 tag 流、minimax 又是另一套,
每换一次就得把几十条规则重抄一遍。
桥把规则留在 skill 文件里,运行时现读现拼:你在 系统提示词 里只写一句
krea2 扩写,桥负责把对应的规则、格式规范、参考词库全部注入进去。
顺带解决的几件事:
- 换底模只改一句声明,规则一个字不动
- 抽卡时的重复请求直接命中缓存,不再每张图都重发两万多字
- 审核拒绝被识别出来换成一张提示卡,而不是把拒绝文本当提示词画出一张无关的图
- 带图时以图为准扩写,避免提示词与 ControlNet 控制图互相拉扯
ZML_LLM 系统提示词 节点的 system_prompt 只写一句,规则由桥自动补齐:
下表是示例声明(作者本机的配法)。桥认的是你
routes里写下的关键词——你的 routes 里若有别的关键词,就写那个。
| 你想做的事 | system_prompt 就写 |
|---|---|
| Krea2 长稿扩写(最常用,tag 口径) | krea2 扩写 |
| Krea2 且要传图 | krea2 扩写,并把图片接到 input_image |
| Krea2 自然语言(巨物 / 海报 / 随机) | krea2 巨构、krea2 图文海报、krea2 随机 |
| Krea2 自然语言 + 传图 | 同上,并把图片接到 input_image(图只当尺度 / 风格参考,不走打标反推) |
| Minimax | minimax 扩写 |
| Anima 场景 | anima 扩写(输出=tag 流 + 自然语言两段,受 512 token 硬约束) |
| SDXL 场景 | sdxl 扩写(同两段式) |
| 留空 | 走默认路由 |
只写这一句,不要把规则全文粘进去。 粘全文是「直连模式」才需要的做法——那是另一个方案, 详见
reference/目录里的krea2_pipeline_system_prompt.txt。
换底模时只改这一句,规则本身在 skill 文件里,一个字都不用动。
想临时换模型:在 zml_model_key.json 里多加几个指向同一个桥地址、只是 model 字段不同的 preset,
然后在 ComfyUI 面板切 preset_name 即可——不用改配置,也不用重启桥。
本地打标 + AI 扩写是两件事:
- wd14 打标很准,但产出的是 tag 串,缺少自然语言的组织与细节密度;
- 自然语言长稿需要 LLM,可每个底模(krea2 / anima / sdxl / minimax)要的写法都不同。
如果把规则静态粘进工作流,换一次底模就要重写一次,几十条规则手抄一遍。 这个桥把规则留在 skill 文件里,运行时现读现拼,工作流侧永远只有一句声明。
插件与节点的完整清单见开头的「用到的插件」。
- Python 3.8+ —— 用 ComfyUI 自带的那个解释器就够,桥只用标准库,零依赖
- 一个 OpenAI 兼容的 LLM 服务(本地网关 / 自建代理 / 各家云 API 都行)
- 你自己的 skill —— 本仓库不含,需自行安装(见第四节)
skill-bridge/
├─ README.md 中文说明(本文件)
├─ README.en.md 英文说明
├─ deploy-with-dsh.zh.md 交给 DSH Agent 自动部署(中文,可选)
├─ deploy-with-dsh.md 同上,英文版
├─ LICENSE MIT
├─ .gitignore
├─ bridge/
│ ├─ dsh_skill_bridge.py 桥本体(纯标准库)
│ ├─ bridge_config.json 配置:上游地址、密钥、场景路由、通用覆盖规则
│ ├─ start-bridge.bat 双击启动(Windows)
│ ├─ add_krea2_routes.py 注册 / 预演示例路由(`--check` 只预演,不写盘)
│ ├─ fix_anima_routes.py 给 anima 系路由配「两段式 + 512 硬约束」覆盖层(`--check` 只预演)
│ └─ zml_model_key.json ZML 节点的预设文件(填密钥用)
├─ plugins/
│ └─ skill-bridge-toolkit/ 「Anima 提示词校验」+数值转文本+H3 帧锚点栈
├─ updates/ 增量补丁(已装过旧版的人不用重下整包)
│ └─ 2026-10-10-anima-krea2.md anima 两段式 + krea2 自然语言路由
└─ reference/ 不想用桥的话看这里
├─ krea2_pipeline_system_prompt.txt 直连模式的静态规则全文
└─ krea2_wiring.md Krea2 Control 那套的接线参考
⚠️ 本仓库不含 skill,skill 需要自行安装并调用。仓库里的bridge_config.json也只是格式示例——routes要按你自己装好的 skill 来填,见「四、配置」里那段可以直接交给 agent 的短文。
本仓库不含 skill,把你自己的 skill 放到一个目录里即可。DSH 用户的默认约定是:
C:\Users\<你的用户名>\.dsh\skills\
放别处也行,第 2 步改 skills_dir 指过去即可。
只需改两处:
{
"upstream": {
"base_url": "https://你的服务地址/v1",
"api_key": "REPLACE_ME", ← 改成你的密钥
"model": "你的默认模型名"
},
"skills_dir": "C:\\Users\\<你的用户名>\\.dsh\\skills" ← 改成第 1 步的实际目录
}其余字段都有注释说明。注意 routes 是占位符示例——它必须按你自己装的 skill 填,见下一步。
仓库里的 bridge_config.json 只是一份格式示例:routes 里的 skill 名与 references 文件名都是占位符,
不指向任何具体 skill。把下面这段整段复制给你的 DSH / Claude / 任意 agent,它就会按你实际装好的 skill 生成 routes:
我的 skill-bridge 装在 <路径>,请帮我配好 bridge/bridge_config.json 里的 routes。
1. 列出我的 skills_dir 指向的目录下已安装的 skill,以及每个 skill 的 references/ 有哪些文件(读 SKILL.md 判断哪几份是必读)。
2. 读 bridge_config.json 里的 `_路由格式说明`,按它给每个可用的 skill 生成一条 route:
- key:一组能识别该 skill 的关键词,用 `|` 分隔多个别名,最常用的放最前——桥按「命中最长的别名」选路由,所以更专用的别名要写得比通用词长。
- skill:skill 的目录名(与 skills_dir 下的文件夹名一致)。
- refs:该 skill 的 references/ 下必须喂给模型的文件名数组。
- refs_image_only:若该 skill 在「只给图、没给文字」时要换一套文档,填这里;否则省略。
- model:可省略,省略就走 upstream.model。
3. 需要把「对话式输出」掰成「流水线输出」(只输出正文、不要代码块与解释、限制篇幅)时,在 route 里加 pipeline_overrides;不写则用全局那份。
4. 把 default_route 指向最常用的那条 route。
5. 不要动 upstream、skills_dir、port。改完校验 JSON 合法,并告诉我改了哪些字段。
配好之后的日常维护很简单:改规则不用改 ComfyUI——直接编辑 skill 目录里的 .md,桥按文件修改时间自动重载;
改 bridge_config.json(含 routes)也是热重载,不用重启桥(只有 port 要重启)。
- 双击
bridge/start-bridge.bat,看到[bridge] ready http://127.0.0.1:8899/v1就成了(窗口保持开着) - 把
zml_model_key.json放到任意目录,填上你的密钥,然后在 ComfyUI 里:ZML_LLM 模型加载器V2的config_folder填那个目录preset_name选SKILL-桥
ZML_LLM 系统提示词里写一句场景声明(下一节)
LoadImage / DanbooruGallery
└─→ BSK_Tagger (wd14 本地打标)
└─→ AnimaTKDanbooruTagGetter (分类过滤)
└─→ DanbooruTagSorterNode / TK String Router
└─→ PromptCleaner
└─→ ZML_LLM 对话主程序 . user_input
↑
ZML_LLM 模型加载器V2 ─ . model_config
ZML_LLM 系统提示词 ─ . system_prompt ← 只写一句:krea2 扩写
ZML_LLM 参数设置 ─ . params ← 最大Token数 设 8192
│
↓ 回复内容
ZML_LLM 过滤思考 (去掉 <think> 思考块)
↓
NL Prompt Forge 黑名单过滤 (可选,兜底)
↓
Anima 提示词校验 (可选,见下)
↓
CLIPTextEncode . text
↓
KSampler . positive
把图片接到 ZML_LLM 对话主程序 的 input_image,并同时接上 wd14 的 tag 文本。桥会自动判断:
| 输入 | 走哪条分支 | 输出形态 |
|---|---|---|
| 图 + tag | 扩写分支(tag 当已确认锚点,图作视觉参考) | 三段式长稿 |
| 仅图、无 tag | 反推分支 | tag 流 + 几句自然语言 |
| 仅 tag | 扩写分支 | 三段式长稿 |
ZML_LLM 对话主程序 不做任何缩放——它把整张原图直接转 base64 塞进请求。实测量级:
| 原图 | 送进上下文的大小 | |
|---|---|---|
| 不做缩放 | 2112×3840 PNG,9.3 MB | base64 后约 12.5 MB |
| 缩到长边 1024 | 563×1024 JPEG,108 KB | base64 后约 144 KB(差 87 倍) |
不缩图的后果是请求要么直接失败、要么贵得离谱,而且不会报错,只是变慢和烧额度; 更隐蔽的是有些上游会静默丢掉图片部分,于是模型只按 tag 扩写,你还以为它在参考图。
做法:在接进 input_image 之前加一个缩放节点(ImageScale / ImageScaleBy),
长边压到 1024~1536 就足够——ControlNet 不需要更高分辨率,视觉模型也读不出更多细节。
图接上后,模型会以图像为准来写长文:动作与姿态、人物朝向与视线、四肢位置、 构图与机位(景别 / 视角 / 主体占幅 / 前后景分层)、场景道具、光源方向与阴影落点, 全部照图写。tag 只负责钉住图上看不出精确取值的离散特征(发色、瞳色、服装款式、配饰)。
tag 与图冲突时以 tag 为准,但不会写出与图矛盾的内容。实测某次输入 tag 写 outdoors
而图是白背景,输出两项都保留了——按规则就该如此。
| 参数 | 值 | 为什么 |
|---|---|---|
ZML_LLM 对话主程序 → json_strategy |
仅提示词 (不强求) |
默认选项会往系统提示里追加「请按 JSON 输出」,把长稿形态搞乱 |
ZML_LLM 参数设置 → 最大Token数 |
8192 | 推理模型的思考会消耗大量 token,设小了正文会被压成空 |
ZML_LLM 系统提示词 的 system_prompt 只写一句,桥按关键词匹配(命中最长者优先)。
下表是示例(作者本机 routes 的配法)——桥只认你 routes 里写下的关键词:
| 声明(示例) | 该路由的写法 | 产出形态 |
|---|---|---|
krea2 扩写 |
一个「tag 扩写」型 skill,refs 挂它的扩写分支与格式规范 | 长稿;tag 当锚点钳制输入 |
krea2 巨构 / krea2 巨物 / krea2 巨怪 / krea2 克苏鲁 |
一个「巨物摄影」型 skill,refs 挂它的相关章节 | 摄影写实长段落(体量 / 尺度 / 留白) |
krea2 图文海报 / krea2 海报 / krea2 字体排版 |
一个「海报 / 排版」型 skill | 图文海报式输出(排版与文字为核心) |
krea2 随机 / krea2 随机流 / krea2 人文建筑 |
一个「无参考自主创意」型 skill | 模型自主选题 |
anima 扩写 |
一个「tag 流框架」型 skill + 两段式覆盖层 | tag 流 + 自然语言(受 512 token 硬约束) |
sdxl 扩写 |
同上,区别只在覆盖层的长度口径 | 同两段式 |
minimax 扩写 |
一个「视频提示词」型 skill | 视频提示词 |
| 留空 | — | 走 default_route |
krea2 两套并存:只写
krea2 扩写走 tag 长稿流程;带上主题词(krea2 巨构/krea2 图文海报/krea2 随机)走自然语言规则库——新别名都比裸词krea2长,桥按「命中最长者优先」自动分流,两套互不干扰。输入钳制:带主题词的三条 krea2 路由都挂了流水线覆盖层,第 0 条即「你在消息里给的人物 / 环境 / 动作 / 事件要素,必须作为主体、背景与事件内容写进提示词」,不会被模型自选的主题替换。
anima 的两个预算档:平时两段合计目标 ≤ 300 token(精简口径);需求里点名「神态生动」「细致场景」「构图饱满」「场景细节充分」时,放宽到 ≤ 480 token 抽更多神态 / 物品 / 环境 tag——两档都远低于 anima 1.0 base 的 512 token 硬上限。
想临时换模型:在 zml_model_key.json 里多加几个指向同一个桥地址、只是 model 不同的 preset,然后在 ComfyUI 面板切换即可——不用改配置、不用重启桥。
plugins/skill-bridge-toolkit 是配套的小工具集,其中 anima_validate_node.py 把某个 skill 自带的 tools/anima_validate.py 包成了节点:
- 输入:LLM 产出的文本
- 输出:修正后的文本 + 报告 + 退出码
- 它做:tag 规范化(下划线转空格、小写)、上位词折叠、槽位冲突检查
- 它不做:质量词、画师名、中文的过滤——那些要靠提示词规则拦住,节点会在报告里单独提醒
安装 / 升级:把 plugins/skill-bridge-toolkit 整个目录放进 ComfyUI/custom_nodes/,重启 ComfyUI。
节点默认去 ~/.dsh/skills 下某个 skill 里找校验器;skill 放在别处、或目录名不同,在节点的 skill_dir 里改。
⚠️ 这个包改过名字:升级必须先删旧包,再放新包。 旧目录名comfyui-anima-validate-node→ 现目录名skill-bridge-toolkit;内容也从单个校验节点扩成三个: 校验节点 + 数值转文本(number_to_text.py)+ H3 帧锚点栈(h3_guide_stack.py)。 ComfyUI 是按目录名认包的——直接覆盖、或者只把新目录放进去而不删旧的,会让两个包同时加载、节点重复注册, 工作流里那些节点可能指向被覆盖的那一份,表现为参数丢失、取值错乱甚至加载报错。# 1) 先删旧包(务必先删;全新安装跳过这一步) Remove-Item "<ComfyUI>\custom_nodes\comfyui-anima-validate-node" -Recurse -Force # 2) 再放新包 Copy-Item "<仓库>\plugins\skill-bridge-toolkit" "<ComfyUI>\custom_nodes\" -Recurse -Force # 3) 重启 ComfyUI
这个节点依赖 skill 目录里的
tools/anima_validate.py与models/t5_tokenizer/—— 它们随对应的 skill 一起分发,本仓库不重复打包。
上游模型触到审核边界时会直接回一段拒绝话(I'm sorry, but I can't help with that request.)。
不拦的话,这段拒绝文本会被当成提示词送进文本编码器,画出一张毫无关系的图——而且你多半看不出
发生了什么,只会反复重跑、白白烧额度。
节点会先做一次拒绝检测,命中后按 on_reject 处理:
on_reject |
行为 |
|---|---|
| 替换为提示卡(默认) | 换成 reject_card 里的提示词,画出一张举牌少女,把拒绝显示在图上 |
| 原样输出并报警 | 保留原文不动,只在报告里报警 |
| 中断执行 | 直接抛错停下 |
检测采用「拒绝动作词」+「审核对象词」双重命中判据(另有 content_filter 直通),
所以 Rate limit exceeded、Insufficient balance、unknown model、请求过于频繁 这类普通失败
不会被误判——这点很关键,否则真正的问题会被掩盖成「被审核了」。词表也覆盖中文拒绝
(该请求涉及政治敏感内容,已被拒绝)与自我声明式(As an AI, I am not able to…)。
它会先把印刷体标点折成 ASCII 再匹配,因为 I can’t help 用的是弯撇号,不折叠的话所有
can't 模式都会落空。
reject_card 是可编辑的,想换成自己的提示词直接改。
CN 图生图抽卡时,常出现同一张图 + 同一串 tag、只换随机种子反复跑的情况。 每次请求的 system prompt 都是同一份两万多字的规则——无条件重发等于每张都白烧一遍上下文, 还要多等十几秒。
开启缓存后(bridge_config.json 的 cache.enabled,默认开),桥按
**「最终组装的 system + 用户文本 + 模型 + token 上限」**建键,命中就直接回放上次的正文,
完全不碰上游。实测:
| 耗时 | 说明 | |
|---|---|---|
| 第一次 | 16.2 s | 走上游,正常生成 |
| 同输入第二次 | 0.0 s | 命中缓存,逐字相同的正文 |
| 换 tag | 14.6 s | 重新走上游 |
同 tag 但改 max_tokens |
14.1 s | 正确地视为不同请求 |
日志里会明确写出来:命中缓存 直接回放 3830 字(未调用上游;缓存共 N 条)。
改 skill 或改 config 会改变 system prompt,键自然失效 —— 不需要手动清缓存。
缓存是 LRU,超过 max_entries(默认 64)自动淘汰最旧的。
图片默认不参与建键。因为 CN 图生图的 tag 与图基本是硬绑定的,图略变 tag 就会变, 用 tag 判断已经足够,还能省掉对图片数据做哈希的开销。
但如果你遇到"换了图却拿到上一张的提示词",就把 include_image_in_key 打开——
代价是每次请求都要哈希一遍图片数据(几百 KB 的 base64,开销很小)。
如果你故意想让同样的输入产出不同结果(比如把 LLM 当灵感来源,同一组 tag 想多抽几种写法),
缓存会妨碍你——那种场景把 cache.enabled 设为 false。抽卡时不要关。
回复缓存按「system + 用户文本 + 模型 + token 上限」建键——只要这几项不变就回放上次的正文。 可「随机流」这类用法恰恰要求每次都不一样:场景声明不变、用户文本不变,输出却被缓存钉成同一份。
所以桥加了一条旁路:场景声明或用户文本里出现 随机 / random 时,直接跳过缓存,每次都真去上游抽一次。
词表写在 cache.bypass_keywords(未配该键时用内置默认 ["随机", "random"];设成 [] 即关闭这条旁路)。
只扫你传来的那一句声明与用户文本,不扫最终组装的 system——skill 规则里满篇「随机」,扫它等于把缓存整个关掉。 旁路命中时日志会写
命中「随机」:跳过缓存,直接请求上游;这类请求也不写缓存,不会挤占max_entries的名额。
Q:ComfyUI 报「返回空内容」
最大Token数 设小了,思考把预算吃光了。设 8192。桥的日志里会打出 max_tokens= 和 思考= 两个值,一眼能看出。
Q:输出里出现代码块或前言
检查 json_strategy 是否选了「仅提示词」。另外 bridge_config.json 里有一段 pipeline_overrides,专门压制「skill 原文要求打包进代码块」这类对话交付习惯——不要删它。
Q:双击启动脚本一闪而过
本包里的 start-bridge.bat 已是 纯 ASCII + CRLF 换行,不会再有这个问题。如果你自己改过它,注意两点:别在 bat 里写中文(cmd 按系统代码页解析会崩),换行必须是 CRLF。
Q:报 502,说「目标端口没有在监听(WinError 10061)」
上游网关没启动,或者 bridge_config.json 里的 base_url 写错了。这不是桥的问题——
桥自己还在跑。把上游启动起来即可。
Q:改了 bridge_config.json 要不要重启桥?
不用。除 port 外所有字段都是热重载的,存盘后下一次请求就生效。
(port 是监听端口,改它必须重启。)
这条以前是个坑:配置只在桥启动时读一次,改了不重启就会一直连旧地址,症状看起来 跟"上游挂了"一模一样。现在不存在了。
Q:传了图,但输出像是没看图、跟图对不上
两步排查。先看桥日志那一行——它会显示 输入=图+tag(N字) 或 输入=仅图(无tag);
若显示的是 输入=tag(...),说明图的线没接上。
再看图有没有缩过。原图过大时,部分上游会静默丢弃图片部分,模型就只按 tag 扩写,
表现和"没接图"一模一样,但日志里 输入=图+tag 是对的。把长边缩到 1024~1536 再试。
Q:配置里 skills_dir 写错了会怎样?
桥在启动时就会把每条 route 的落地情况打出来,不用等出问题才发现:
skills_dir = C:\Users\你\.dsh\skills
route <关键词> -> <skill 目录名> OK
route <关键词> -> <skill 目录名> 缺失 SKILL.md
目录不存在时直接提示「改成你放 skill 的目录;改完不必重启桥(配置是热重载的)」。 不会静默降级——改之前它会照常返回 200,只是 skill 规则一条都没加载, 用户只会觉得"输出莫名变差",而警告埋在日志深处、ComfyUI 端根本看不到。
Q:日志在哪
bridge/bridge.log。每行记录场景、输入类型、走的哪个分支、用的模型、system 提示长度、token 用量、耗时。排查问题先看它。
Q:怎么停掉桥
关掉那个窗口即可;也可以按端口结束进程(别用 taskkill /im python.exe,会连带杀掉 ComfyUI):
Get-NetTCPConnection -LocalPort 8899 -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
MIT,见 LICENSE。
本仓库不含任何 skill 的正文,也不含 wd14 模型权重—— 这些请从各自的来源获取,并遵循其原有许可。