dsh-comfyUI-control
DeepSeek Harness（DSH）0.2 bundle：
把本地 ComfyUI 接进一个名为 绘图模式 的 Agent 预设里，完整复刻
xingxue-ux/good-comfyui-mcp 的 13 个工具，
并补齐 ComfyUI 控制面与复刻自检，共 19 个 comfyui_* 工具。
安装：dsh plugin add --profile <profile> dsh-comfyui-control（见安装）。
只在「绘图模式」预设里生效：标准模式、极简模式、PTC 模式、创造模式等其他预设都不挂载这个插件，
也就看不到任何 comfyui_* 工具。
零运行时依赖：只用 Node 内置模块 + 全局 fetch，不需要 pip、不需要常驻 Python MCP 进程。
0.2 与旧版预设机制的区别（重要） DSH 0.1 从
$DSH_HOME/.agent-presets/<id>/读取用户预设；0.2 已经不再读这个目录。 0.2 的预设是 bundle patch 里的@deepseek-ai/dsh-agent-preset声明，必须用plugin_manager安装 bundle 才能出现在预设选择器里。本包就是按 0.2 机制交付的。
功能（19 个工具）
| 工具 | 说明 | 对应上游 |
|---|---|---|
comfyui_status |
依赖自检：ComfyUI / 管线模型 / 8899 对比页服务 / camofox / Civitai 凭据 / 视觉服务状态，返回 missing[] 与 on_demand[] |
server_info |
comfyui_setup_guide |
初始化清单（每步含操作 / 验证 / 是否必需） | setup_guide |
comfyui_get_model_guide |
Anima 官方用法：模型版本、采样参数、提示词规则、限制 | get_model_guide |
comfyui_list_models |
列出 ComfyUI 各模型目录（loras / diffusion_models / text_encoders / vae / upscale_models …） | — |
comfyui_generate |
出图：Anima 管线（默认）或 Krea2 引擎；可覆盖 steps/cfg/sampler/尺寸/seed；参考图自动生成对比页 | generate |
comfyui_repro_check |
复刻自检：按上游样例元数据原样出图（1216 宽 × 30 步 / CFG 4 / euler_ancestral + 5 件套 LoRA），把结果与上游原图并排展示给你自己目视对比；不做自动评分 | run_example.py |
comfyui_run_workflow |
提交任意 workflow JSON 并等待结果 | — |
comfyui_history |
历史记录查询与 mcp/manual 来源标注 |
— |
comfyui_queue |
队列查看 / 中断 / 清空 | — |
comfyui_node_info |
节点输入输出定义查询 | — |
comfyui_extract_image_info |
PNG 元数据解析：ComfyUI prompt/workflow、WebUI parameters、LoRA 配置 | extract_image_info |
comfyui_describe_image |
识图，默认关闭（你通常已有多模态模型，直接读图）；显式 enable_vision=true 后优先用宿主视觉模型 deepseek-v4.1-flash，Ollama 为可选的本地回退（qwen3-vl:8b → llava:7b，detail 11 问模式） |
describe_image |
comfyui_deconfuse_image |
小番茄（Gilbert 曲线）混淆图还原，可 enc/dec 多次 |
deconfuse_image |
comfyui_lookup_character_tags |
Danbooru 角色规范 tag（camofox 反检测浏览器，30 天缓存） | lookup_character_tags |
comfyui_lookup_character_appearance |
角色外貌 tag 统计（solo 图 tag 频率） | lookup_character_appearance |
comfyui_list_cached_characters |
已缓存角色列表（离线） | list_cached_characters |
comfyui_search_lora |
Civitai LoRA 精确版搜索（网页搜索端点 models_v9，比 API 全） | search_lora |
comfyui_download_lora |
Civitai 下载 + safetensors 头校验 | download_lora |
comfyui_lookup_lora_hash |
本地文件 SHA256 → by-hash 反查精确来源 | lookup_lora_hash |
安装
已发布到 npm：dsh-comfyui-control（dsh.bundle.patch 已声明，装进 profile 即自动成为一层 bundle）。
方式一：npm / dsh plugin add（推荐）
dsh plugin add --profile <你的 profile> dsh-comfyui-control
它做三件事：pnpm 把包装进 <DSH_HOME>/profiles/<profile>/node_modules/、写完 package.json 依赖、
并把 dsh-comfyui-control 追加到该 profile 的 dsh.profile.bundles。装完重启 DSH 即可。
也可以手动把包放进 profile：在 profile 目录跑 npm i dsh-comfyui-control（或 pnpm add），
再在 package.json 的 dsh.profile.bundles 里加上 "dsh-comfyui-control"。
方式二：本地目录
git clone https://github.com/xingxue-ux/dsh-comfyUI-control
对 Agent 说：
用 plugin_manager 安装
E:\AI\ComfyUI\dsh-comfyUI-control这个 bundle（action: install_bundle）。
也可以在「设置 → 插件」里安装同一个目录。
选择预设
预设名 绘图模式（id drawing）。装完后 plugin_manager 的 list_bundles 会列出这个 bundle，
list_plugins 里会出现 preset-drawing 行。在 Agent 预设选择器里选 绘图模式，或设为默认预设后新建会话。
预设只对新会话生效；已在运行的会话保持启动时的插件版本。
环境依赖
| 依赖 | 必需 | 说明 |
|---|---|---|
ComfyUI（默认 http://127.0.0.1:8188） |
✅ | 出图与模型列表 |
| Anima 管线模型 | ✅ | anima-base-v1.0.safetensors（models/diffusion_models/）、qwen_3_06b_base.safetensors（models/text_encoders/）、qwen_image_vae.safetensors（models/vae/）、RealESRGAN_x2plus.pth（models/upscale_models/，开 upscale 时用） |
| 默认 5 件套 LoRA | ✅（默认挂载） | 见下节；缺了就用 comfyui_search_lora + comfyui_download_lora 拉 |
| 8899 对比页服务 | ✅ | 出图返回的 view_url 指向它。启动：npm run serve-compare（即 node tools/serve-compare.mjs，只读服务 <DSH_HOME>/storages/dsh-comfyui-control/compare/）；没启动时 comfyui_status 会把它列进必需项并从 missing[] 报告，comfyui_generate 也会在结果里带 view_warning |
camofox-browser（默认 http://127.0.0.1:9377） |
可选 | npm install -g @askjo/camofox-browser && camofox-browser；不装则角色 tag / 外貌统计不可用 |
| Civitai 凭据 | 可选 | CIVITAI_TOKEN（下载）、CIVITAI_SEARCH_KEY（搜索）；不配时 by-hash 反查仍可用 |
| 视觉服务 | 可选（默认关闭） | comfyui_describe_image 默认不发请求 —— 你通常就是多模态模型，直接读图即可。需要时传 enable_vision=true，默认走宿主视觉模型 deepseek-v4.1-flash（opencode-go），用不到 Ollama；想走本地 Ollama 则传 model=qwen3-vl:8b 并先 ollama pull qwen3-vl:8b（+ llava:7b 作为 NSFW 回退） |
装好后在新会话里先调 comfyui_status，它会返回 missing[] 逐项告诉你缺什么。
默认 5 件套 LoRA（需要自己下载，插件不会自动拉）
comfyui_generate 不传 lora_text 时自动挂这 5 个；本包不包含任何模型文件，缺任何一个都会提交失败：
| LoRA | 权重 | 用途 |
|---|---|---|
ushikani_kassen_lora-000013.safetensors |
0.3 | 画风 |
anima-darklight-style-v1-000194.safetensors |
0.3 | 朦胧氛围 |
anima-base-1-photo-background-v4.safetensors |
0.6 | 写实背景 |
RealSkin SliderV2.safetensors |
0.8 | 写实皮肤 |
surtr945_v1.safetensors |
0.8 | 画风 |
补齐方式（四选一）：
- 让 Agent 代下（推荐，需要
CIVITAI_TOKEN）：comfyui_search_lora(filename='surtr945_v1.safetensors')→comfyui_download_lora(version_id=3023314, filename='surtr945_v1.safetensors')→comfyui_lookup_lora_hash核对来源。内置KNOWN_EXACT表让这 5 个都能离线命中精确版。 - 自己下：从 Civitai 下到
<COMFYUI_ROOT>/models/loras/，文件名保持一致。 - 不用默认套：显式传
lora_text=""空载，或传lora_text='<lora:你的LoRA:0.7>'覆盖。 - 补齐后复查：
comfyui_status的default_loras.missing应为[]，models_ok才会是true。
comfyui_status会单独检查这 5 个文件（default_loras.present/missing）：它们不在pipeline.json里， 是生成时动态注入的，所以不检查的话新装环境会误报ready: true。
复刻自检（comfyui_repro_check）
移植了上游 run_example.py 的目的，但不做 MAE 自动判定：用上游两个样例的元数据原样出图，
然后把生成图与上游原图并排放在对比页里，由你目视判断本地环境是否与上游参考一致。
| 样例 | 尺寸 | seed | 说明 |
|---|---|---|---|
repro_anima_00015 |
1216×912 | 8682388855765119 | 双人沙发月光夜 |
repro_sofa_rose |
1216×832 | 2075224187 | 沙发玫瑰写实 |
两张都用 30 步、CFG 4、euler_ancestral/simple、同一套 5 件套 LoRA（含 darklight 0.4、RealSkin 0.8/0.7 的差异也与上游一致）。
元数据固定在 repro/samples.json，并有测试逐字段比对上游 examples/*.json，防止漂移。
用法：
comfyui_repro_check # 两个样例都跑（需要参考图已缓存）
comfyui_repro_check(allow_download=true) # 首次：同意从上游仓库下载参考原图（约 5MB/张）
comfyui_repro_check(sample='repro_sofa_rose')# 只跑一个
- 上游参考图不随包发布（两张共约 10MB）。首次必须显式
allow_download=true，下载后按清单里的 sha256 校验并缓存在<DSH_HOME>/storages/dsh-comfyui-control/repro/；校验不过就报错，不会拿错图对比。 - 生成的图与上游原图都写到
compare/repro/下，8899 服务在线时返回的view_url可直接打开并排对比。 - 前置：底模与 5 件套 LoRA 齐全、ComfyUI 运行中、8899 在跑。
配置
全部通过环境变量，都有可用默认值：
| 变量 | 默认 | 说明 |
|---|---|---|
COMFYUI_ROOT |
从插件位置向上探测含 models/ 的那一级 |
ComfyUI 安装根目录；models/、output/ 都在其下。兼容上游写法 MODELS_ROOT。强烈建议显式设置，例如 E:\AI\ComfyUI：插件装在 bundle store 里时，它离你的 ComfyUI 安装目录很远，自动探测不到 |
COMFYUI_URL |
http://127.0.0.1:8188 |
ComfyUI 地址 |
PIPELINE |
bundle 内 pipeline.json |
Anima 管线 workflow 路径 |
COMFYUI_OUTPUT |
<COMFYUI_ROOT>/output |
出图目录（对比页复制源文件用） |
DSH_COMFYUI_STATE |
<DSH_HOME>/storages/dsh-comfyui-control |
角色缓存 cache/ 与对比页 compare/ 的根目录 |
OLLAMA_URL |
http://127.0.0.1:11434 |
Ollama 地址 |
CAMOFOX_URL |
http://127.0.0.1:9377 |
camofox-browser 地址 |
COMFYUI_VIEW_BASE |
http://127.0.0.1:8899 |
对比页 URL 前缀 |
CIVITAI_HOST |
https://civitai.red |
Civitai 镜像（civitai.com 会过滤内容） |
CIVITAI_TOKEN |
空 | 下载 / 详情接口用 |
CIVITAI_SEARCH_KEY |
空 | 网页搜索端点用 |
与上游 good-comfyui-mcp 的对应关系
- 工具语义一致：同样的参数名、同样的返回字段（
prompt_id/outputs/view_url/character_info/canonical_tag/appearance_tags/exact/kind/model_id/version_id/sha256/valid_safetensors…）。 - 行为一致：Anima 与 Krea2 两套引擎的参数、LoRA 动态注入、默认 5 件套、
30 天角色缓存与缓存键规则、Danbooru wiki 解析规则、Civitai 搜索匹配与打分、
小番茄 Gilbert 曲线置换与
--preserve-meta、识图拒绝关键词与 fallback 逻辑。 - 实现方式不同：上游是 Python MCP 进程；本插件是 DSH 进程内的原生工具，
用
fetch直连各服务，不再需要mcp/httpx/numpy/pillow。 PNG 编解码（含 tEXt/iTXt/zTXt 与 Gilbert 置换）用 Node 的zlib自己实现。 - 命名不同：所有工具加
comfyui_前缀，避免和宿主/其他插件撞名。
目录结构
package.json bundle 元数据：dsh.bundle.patch -> cordis.patch.yml
cordis.patch.yml 【生成】preset-drawing 声明 + 插件列表
preset/
preset.yml 预设显示名「绘图模式」、描述、order
agent.cordis.yml 预设的插件列表（唯一真源，build 时嵌入 patch）
dsh-comfyui-control/ 预设加载的插件（随 bundle 一起安装）
lib/entry.js 插件入口（人工维护）
lib/index.js 【生成】自包含单文件插件（19 个工具）
pipeline.json 【生成】Anima 管线 workflow
LORA_GUIDE.md 【生成】LoRA 选用规范
lib/ 插件实现（打包进 lib/index.js）
plugin.js 注册 19 个工具 + 释放
tool.js 工具定义与参数校验（对齐 harness schema DSL）
env.js 路径与环境变量解析
http.js fetch 封装（超时 / 非 2xx 报错 / 只读探活）
comfyui.js 管线、Krea2、提交轮询、历史/队列、对比页
danbooru.js camofox 会话 + Danbooru 角色查询与缓存
lora-search.js Civitai 搜索/反查/下载引擎（每个请求都有超时）
png.js PNG 编解码与文本元数据
xfq.js 小番茄 Gilbert 曲线置换
tools/ 每个领域的工具定义（comfyui / danbooru / civitai / vision）
docs/LORA_GUIDE.md LoRA 规范源文件
tools/
build-bundle.mjs 【构建】生成 cordis.patch.yml + 自包含插件
bundle.mjs ESM 自包含打包器
serve-compare.mjs 8899 对比页静态服务（必需依赖）
verify.mjs bundle 结构与插件自检
verify-live.mjs 逐工具真实调用并打印结果
test/ node:test 套件
为什么插件是自包含的单文件
bundle store 里的预设行不保证能解析 harness 的 @deepseek-ai/* 包，所以
tools/bundle.mjs 把 lib/ 内联进 preset/dsh-comfyui-control/lib/index.js 这一个文件：
只保留 Node 内置模块的外部 import，import.meta.url 指向打包产物自身
（插件因此把 dsh-comfyui-control/ 当作自己的根目录）。
lib/tool.js 自带一份与 harness 等价的 schema 编译器与参数校验，
test/harness-schema.test.js 对每个工具的编译结果和校验结果与 harness 真实实现逐一比对。
预设行为什么是相对路径（0.2 的一个坑）
预设里挂插件的那一行写成：
- id: comfyui-control
name: './node_modules/dsh-comfyui-control/preset/dsh-comfyui-control/lib/index.js'
因为 0.2 的 Loader 对相对 specifier 做的是 new URL(name, ctx.baseUrl)，而 profile 级 Loader 的
ctx.baseUrl 是 profile 目录，所以相对路径要相对 profile 目录来写（bundle 被 link 进
profile 的 node_modules，所以这正好命中）。
两个踩过的坑，写在这里省得再踩：
- 文档里说的"插入行的相对路径锚定在 patch 文件旁"在 0.2.0-rc.2 上不成立（至少在 bundle
被
install_bundle装配之后）：按包目录写的相对路径（如./preset/...）解析不到。 - 想在行里用
!!js new URL(..., import.meta.url)也不行：!!js表达式的求值方式是new Function('ctx', ...)，里面没有import.meta，表达式会抛错。 同理可用的是 loader 上下文提供的dshHomePath(...)（例如!!js dshHomePath('sessions')）。
开发与验证
npm run build # 生成 cordis.patch.yml 与自包含插件（改代码后必跑）
npm test # 102 用例：单元 + 契约 + bundle 结构 + 实时冒烟（服务不在时跳过）
node tools/verify.mjs # bundle 结构与插件自检
node tools/verify-live.mjs # 逐个真实调用需要服务的工具并打印结果
Node 25 把 node --test <目录> 当成模块入口，所以用 glob 形式（npm test 已是该命令）。
本机验证记录（2026-10-07）：
npm test→ 108 用例 / 106 通过 / 1 跳过 / 0 失败node tools/verify.mjs→ 15/15（bundle 声明、插件行可解析、构建产物与源码一致、19 工具注册）- 真实出图：
comfyui_generate（Anima，512x512，8 步，CFG 2）17 秒完成，输出 1024x1024； 回读 PNG 元数据可见 KSampler 参数与注入的 5 个 LoraLoader - 真实角色查询：
comfyui_lookup_character_tags('hatsune miku')→hatsune_miku（147090 posts） - 真实 by-hash 反查：
surtr945_v1.safetensors→ model 2692601 / version 3023314 / base Anima - 小番茄解混淆：enc/dec 两次往返像素完全一致
comfyui_status实测：view_server=online（npm run serve-compare起着时），comfyui_describe_image默认返回「视觉服务默认关闭」且零网络请求
已知限制
- 视觉服务默认关闭，且默认走宿主模型：
comfyui_describe_image不传enable_vision=true时 只回一句说明、不发任何请求。开启后优先用opencode-go/deepseek-v4.1-flash（不存在或不支持图片时 依次退到deepseek-official/deepseek-flash、deepseek-account/deepseek-flash）； 只有显式传 Ollama 模型名（如model=qwen3-vl:8b）才会走本地 Ollama， 该路径沿用上游行为：qwen3-vl 会拒 NSFW，自动回退llava:7b（无审查但多角色图容易幻觉）。 未安装模型时会明确提示ollama pull <模型>。 - 8899 服务是必需依赖：
view_url只是 URL，服务没起就打不开。serve-compare只读服务 compare 目录、不写盘、不联网；端口用COMFYUI_VIEW_PORT或--port改。 - Civitai：搜索端点需要
CIVITAI_SEARCH_KEY，下载需要CIVITAI_TOKEN；by-hash 反查免凭据。publishedAt异常的条目 API 搜索搜不到（网页端点可以）；个别模型两端都不收录。 - 解混淆：只支持小番茄（Gilbert 曲线）混淆；带密钥的像素混淆无密钥无法还原。
输入必须是 PNG（不引入 JPEG 解码器），
times上限 64（每次都是主机进程内的整幅像素遍历）。 - PNG 编解码：支持 8 位灰度 / RGB / 调色板 / RGBA；隔行 PNG 会明确报错而不是猜。
- 出图元数据处理：非 PNG（如 JPEG）只读取 JPEG
COM注释段的文本元数据并报告格式与尺寸； EXIF 标签数量与 WebUIparameters的深度解析没有复刻。 - 磁盘增长：
compare/与角色缓存只增不减，需要时自行清理<DSH_HOME>/storages/dsh-comfyui-control/。
License
MIT
No comments yet. Be the first to write one.