kimigaiiwuyi RH_ComfyUI 开发与维护完整指南(核心入口)
本 SKILL 按章节拆分为主入口 +
references/子文档。需要某专题细节时, 顺着下文相对路径按需读取对应文件,不要一次性把所有内容塞进上下文。
文档目录索引
| 章节 | 主题 | 链接 |
|---|---|---|
| 一 | 架构总览(分层图、目录地图、一次生成的完整数据流、双注册表) | references/01-architecture-overview.md |
| 二 | core 内核(ABC 生命周期、schema 类型、错误族、公开接口边界) | references/02-core-kernel.md |
| 三 | 新增/修改模型(defs.py 范式、PortSpec、NodeDef、跨字段校验、知识库) | references/03-adding-models.md |
| 四 | 通道与供应商(ProviderChannel、多通道负载均衡、熔断、新增一家供应商) | references/04-channels-and-providers.md |
| 五 | 计费与统计(BillingPolicy、dispatch 失败语义、取消摘要、wire 摘要) | references/05-billing-and-telemetry.md |
| 六 | 三大入口(命令 / AI Agent / HTTP、cancel/resume API、HTTP 契约红线、动态参数进 params §6.6) | references/06-entry-points.md |
| 七 | 外部插件接入(注册途径、覆盖内置模型、私有数据隔离、独立钱包) | references/07-closed-source-extension.md |
| 八 | 测试、代码红线与上线自查清单 | references/08-testing-and-redlines.md |
| 九 | 后端 Adapter、映射器与配置体系(六后端、Seedance Provider 子层、SERVICE/PLUGIN_CONFIG 全键) | references/09-backends-and-config.md |
| 十 | 命令清单与数据库(触发词、to_ai、RHBind、RHComfyuiTaskRecord 全列) | references/10-commands-and-database.md |
| 十一 | 凭证热更新(中途改 key 不重启)— @property / refresh_config / update_credentials 三种写法 |
references/11-credential-hot-reload.md |
| 十二 | 供应商通道 / Gemini 生图 / 能力一致性 — 单层负载均衡、AdapterChannel 翻错、/models 可用性、Gemini SDK 双模、图在 steps、input_schema 与能力同步、计费退款 | references/12-provider-channels-and-gemini.md |
| 十三 | OpenAI 兼容供应商池(网页配置零代码挂供应商、OpenAI_Image_Providers、rh 刷新供应商、resync 语义) |
references/13-openai-provider-pool.md |
| 十四 | 语音情绪体系与自动音色克隆(EmotionStyle 基类归一、内联/剥离/枚举收敛、参考音频持久去重、fish_tts 样例) | references/14-speech-emotion-and-voice-clone.md |
| 十五 | 积分计价规则总览(公式推导、9 类计费曲线、改价流程、6 个已知 bug 列表、防踩指南) | references/15-billing-pricing-formulas.md |
| 十六 | 模型目录与 estimate API 契约(/models 系列端点、input_schema 结构、point_range 双重作用、兼容性矩阵) |
references/16-models-catalog-api.md |
| 十七 | 新增/修改模型 与 计费改动 完整交接清单(改文件顺序、跑测试、常见出错模式、提交前自检) | references/17-adding-models-billing-handoff.md |
| 十八 | 图片像素量压缩(上传/传输前瘦身、compress_to_max_pixels、1080P 阈值、格式保持、调用方接入) | references/18-image-compression.md |
| 十九 | Seedance 2.5 与输入视频时长计费(模型 seedance2.5、ark+gateway、费率、input_video_duration、task_mode、宿主透传) | references/19-seedance25-and-input-duration.md |
| 二十 | 取消 / resume-poll / 最终 wire 落库(cancel_generation、rh_app≠comfyui、vendor_task_id、resume_poll、wire_capture、开源边界) | references/20-cancel-resume-and-wire-audit.md |
快速决策表(先看这里)
| 你要做的事 | 走哪条路 | 详见 |
|---|---|---|
| 加一个参数面简单的新模型(复用现有 backend) | models/<模态>/defs.py 加一个类 + 追加 ALL_MODELS |
三 |
| 新模型动态档位(frame_mode / image_size / task_mode / 新 enum) | PortSpec 名 = params 键;submit 未知顶层 kwargs 会透传进 params;不要给每个 enum 加 dataclass 字段 |
六 §6.6、十七 |
| 加一个有跨字段约束的模型 | defs 类 + overrides.py 校验类 |
三 |
| 加一个全新执行链的模型(新 HTTP 上游) | backends 客户端 + ProviderChannel + 继承模态 ABC + @register_model |
三、四 |
| 给现有模型加一家供应商 | channel_bindings() 追加 ChannelBinding |
四 |
| 调用方指定供应商通道 | submit(..., channel="ark");空/auto=负载均衡;resolve_channel_pin |
四、六 |
| 改模型积分价格 | defs 类的 point_cost(node_def 里) |
三 |
| 排查"扣了积分没出图" | dispatch 失败语义 + 统计表 status/refunded |
五 |
| 取消进行中任务 / 上游 DELETE | cancel_generation + bind_vendor_cancel + 模型 cancel 标志 |
二十、五 |
| rh_app 能否取消 / 与 comfyui 区别 | 通道级 supports_remote_cancel;AI 应用无 cancel |
二十 |
| 进程重启后继续轮询上游结果 | resume_poll + extra_params.vendor_task_id |
二十 |
| 消费页 prompt 与上游不一致 | wire_capture 最终 body;backend 须 set_wire_* |
二十、五 |
| 调用方要新字段 | HTTP 契约只增不改,ModelEntry 加带默认值的字段 |
六、十六 |
| 写外部插件模型 | 独立插件 model_registry.register() 或 entry points |
七 |
| 接一个全新上游 API | backends 新 Adapter(或 ProviderChannel)+ 配置键 | 九、四 |
| 加/改一个图片供应商(如 Gemini)/ 给模型加第二家供应商 | ProviderChannel + channel_registry.register_binding |
十二、四 |
| 给图片模型挂一家 OpenAI 兼容供应商(如千帆,零代码) | 网页控制台 OpenAI_Image_Providers + rh 刷新供应商 |
十三 |
| 开关通道/改 Slot 模型勾选后 registry 没跟上 | 网页 set_config 自动重绑;外部插件 register_resync_hook |
七、十三 |
| 加一个语音/TTS 模型 / 改某模型情绪风格(内联/枚举/自然语言) | overrides 声明 emotion_style,基类 normalize() 统一整形 |
十四 |
| 参考音频自动克隆 / 克隆结果持久复用去重 | mapper 复用 RHVoiceCloneCache(按内容哈希全局去重) |
十四 |
| 改模型能不能传参考图 / 参考图上限 | defs 的 images 端口(有无 + max_items),需与 supported_shapes/supports_edit 同步 |
十二、三 |
| 改请求组装 / workflow 注入 | utils/mappers/ 对应函数 |
九 |
| 改命令触发词 / to_ai 文案 | rh_generate(触发词是兼容承诺,慎改) | 十 |
| 加统计维度 / 查积分逻辑 | RHComfyuiTaskRecord / RHBind | 十、五 |
| 改积分价格 / 加新计费维度 / 排查积分不准 | defs 的 estimate_cost / point_range + utils/mappers/<model>_billing.py 常量 |
十五 |
| 预扣后按供应商 usage 实扣(防双重扣费) | settle_cost + BillingPolicy.settle;调用方差额对齐 |
五、十五、十九 |
| 历史 Seedance 2.x 按 raw usage 回算积分 | reconcile_seedance_usage_billing |
五 |
| 改 schema 字段 / 加新参数面 / 排查 estimate 失效 | defs 的 node_def() inputs + rh_models/webapi.py 路由 handler + rh_models/api.py:estimate_model_points;catalog-only 键进 params |
十六、十七、六 §6.6 |
| 调用方报"积分不变" / 不调 estimate / 422 / 4K 反便宜 | 跨引擎与调用方双侧排查 | 十五 |
| 上传/传输前压缩图片(4K→1080P、格式不变) | RH_ComfyUI.utils.image_process.compress_to_max_pixels_async |
十八 |
| 加/改 Seedance 2.5 / 输入视频时长影响积分 | defs seedance2.5 + billing input_video_duration + 宿主透传 |
十九、十五 |
| 新异步 backend 接入 | create 后 bind_vendor_cancel + POST 前 set_wire + 可选 resume | 二十、四、九 |
三条最高红线(违反必被打回)
- 不要绕过
core.dispatch.dispatch()直接调model.run()—— 计费与统计会丢。 check_available()/validate()禁止网络请求与副作用 —— 路由阶段会批量调用。- 开源仓库零宿主业务耦合 —— 不写宿主 URL、不写条件 import 宿主包、 不按产品来源分叉;宿主能力用扩展点注入(见 §七、§二十)。 代码与注释用中性词「调用方 / 宿主 / 外部插件」,不暴露具体前端或宿主后端。
验证命令
# 在插件根目录(<gsuid_core 仓库>/gsuid_core/plugins/RH_ComfyUI)
# 用 gsuid_core 的 venv 解释器跑(系统 Python 的 fastapi/starlette 版本可能不配套)
python -m pytest tests/ -q # 内核单测,全离线,必须全绿
# 取消 / wire / 契约相关子集:
python -m pytest tests/test_cancel_generation.py tests/test_statistics_request_body.py tests/test_http_contract.py -q
ruff check RH_ComfyUI # 代码风格