适合对象：专科及以上毕业生，有 ComfyUI 或 Python 基础更佳，但零基础也能照抄命令跑通。
阅读收益：30 分钟内把任意 ComfyUI 工作流变成 Cursor / Claude Desktop 里“一句话就能调用”的 AI 工具，全程不写一行代码。

一、先回答你最想问的 6 个问题

常见问题 一句话答案
Pixelle MCP 到底是什么？ 一座“桥”，把 ComfyUI 的图形化工作流自动注册成 MCP 协议工具，让任何兼容 MCP 的 LLM 客户端（如 Cursor）直接调用。
我需要改代码吗？ 不需要。工作流文件重命名→拖进网页→发送消息，三步完成。
对电脑配置有硬性要求吗？ 能跑通 ComfyUI 就行；Pixelle 本体只占 200 MB 内存。
支持哪些模态？ 文本、图像、声音、视频（TISV）互转与生成，取决于你放进 ComfyUI 的节点。
与“把 Stable Diffusion 封装成 API”相比优势在哪？ 不用写后端、不用管鉴权、不用重启服务，工作流即插即用，且可被多 LLM 客户端共享。
会不会很难维护？ 反向操作同样零代码：删掉 data/custom_workflows 里的 json 文件即下线对应工具。

二、10 秒看懂整体架构

┌------------------┐
│  Cursor / Claude │←-----HTTP----→│  Pixelle MCP 统一进程 │←-----HTTP----→│ ComfyUI 8188 │
└------------------┘                │  9004 端口同时提供  │               │ 原生节点生态 │
                                    ├─ Web 聊天界面       │
                                    ├─ MCP 端点 /pixelle/mcp │
                                    └─ 文件上传/下载      │

一句话：只有 Pixelle 一个进程，端口 9004，把 LLM 与 ComfyUI 的“语言”翻译成彼此听得懂的 MCP 协议。

三、部署方式 3 选 1：抄命令即可

场景 命令 备注
只想尝鲜 uvx pixelle@latest 临时进程，Ctrl+C 即消失，配置向导会自动弹出。
长期自用 pip install -U pixelle 然后 pixelle 写入系统 PATH，升级用 pip install -U。
生产/团队协作 docker compose up -d 提前改好 .env，重启电脑也能自启动。

首次启动会检测三件事：ComfyUI 是否在 8188 端口、LLM 是否配了 key、工作流目录是否已生成。缺啥，向导会一步一步提示你。

四、5 分钟跑通第一个“高斯模糊”工具

步骤 1：在 ComfyUI 里搭工作流

  1. 新建空白流程。
  2. 拖入 LoadImage → GaussianBlur → SaveImage。
  3. 双击 LoadImage 节点标题，改成
    $image.image!:输入图片URL
    意思：把“image”字段暴露给 LLM，且为必填参数。
  4. 点击 ComfyUI 菜单 Export → API (json)，存为 i_blur.json。

步骤 2：把 json 喂给 Pixelle

  1. 浏览器打开 http://localhost:9004（默认账号 dev/dev）。
  2. 右下角“上传工作流”按钮→选 i_blur.json→发送。
  3. 页面会返回“新增工具 i_blur”提示，刷新即可见。

步骤 3：在聊天框里用自然语言调用

输入：
“请把 https://example.com/cat.jpg 高斯模糊 5 像素”
LLM 会自动解析出 i_blur(image="https://example.com/cat.jpg", blur=5)，执行完把结果图回传给你。

五、如何自定义更复杂的工具：以“FLUX 极速文生图”为例

节点规划 参数暴露写法 类型推断
CLIPTextEncode 正向提示词 $prompt.text!:正向提示 str
EmptyLatentImage 宽高 $width.width:宽度，默认 512 int
FluxTurboSampler 步数 $steps.steps:采样步数 int
SaveImage 输出 系统自动识别，无需标记 —

导出 api 格式后重命名 t2i_flux_turbo.json→上传→完成。
之后在任何 MCP 客户端里说“画一只赛博朋克猫，宽 768”，工具会被自动选中并填充参数。

六、工作流→工具的 DSL 速查表

标记位置 语法 示例 作用
节点标题 $参数名.字段名! $seed.seed!:随机种子 必填参数
节点标题 $参数名.~字段名! $video.~video!:视频URL 先下载再上传 ComfyUI
节点标题 $output.任意名 $output.mask 把该节点返回值作为工具输出
单独文本节点 标题=MCP 内容写“用于 xxx 的专用工具” 给工具加详细描述

规则小结

  1. 带 ! 的字段必须在画布留空或默认值，否则 LLM 不传参时会报错。
  2. 已与其他节点相连的输入不会被解析成参数。
  3. 文件名即工具名，避免中文与空格。

七、FAQ：踩坑与急救

Q1 上传后刷新页面找不到工具？
→ 看日志是否提示“xxx 字段未连接却标记为输出”，按提示把节点重新接好再导出。

Q2 执行返回 500，ComfyUI 日志显“模型文件缺失”？
→ Pixelle 只负责转发请求，模型仍需你自己放到 ComfyUI 的 models 目录。先确保原工作流在 ComfyUI 能跑通。

Q3 想给工具加分类或版本号？
→ 在文件名前加前缀即可，如 v2_i_blur.json，工具名会变成 v2_i_blur，方便迭代。

Q4 可以同时挂几个 LLM？
→ .env 里填多行 LITELLM_MODEL= 即可，Pixelle 会按轮询方式负载均衡。

Q5 端口冲突？
→ 启动前 export PORT=8080，或 .env 写 PORT=8080。

八、本地开发二次开发指北（可选）

  1. 克隆源码
    git clone https://github.com/AIDC-AI/Pixelle-MCP.git && cd Pixelle-MCP
  2. 安装依赖
    uv sync 或 pip install -e .
  3. 热重载运行
    uv run pixelle --reload
    修改 src/pixelle 下的 Python 文件会自动重启。
  4. 新增自定义路由
    在 src/pixelle/server.py 的 chainlit_app 对象上 @app.get("/your/path") 即可，Chainlit 兼容 FastAPI 语法。

九、如何把项目做成团队共享“模型超市”

需求 做法
统一模型库 把 ComfyUI 容器与模型目录挂到 NFS，所有 Pixelle 实例只读挂载。
权限隔离 前端用 Nginx 反向代理，加一层 basic auth；Pixelle 本身不改代码。
版本回滚 工作流 json 存 Git，推送后 CI 自动复制到 data/custom_workflows，回滚即 git revert。
计量计费 解析 Chainlit 日志里的 tool_call_id 与耗时，写入 Prometheus，Grafana 出报表。

十、写在最后：为什么值得现在动手

  1. 生态早班车：MCP 协议刚发布半年，官方客户端列表每周更新，早接入等于早占坑。
  2. 成本最低：你已有的 ComfyUI 工作流直接复用，无需重写推理代码。
  3. 风险最小：Pixelle 把文件服务、MCP 端点、Web 界面三合一，单容器即可跑，运维复杂度接近零。

把“高阶工作流”变成“一句话指令”的时代已经来了——
下一步，轮到你在群里甩一句：“@机器人，给我把这段视频转成 60 帧 4K 动漫风格。”
而对方只会回你一个 OK。

一键体验命令再贴一次：

uvx pixelle@latest

浏览器打开 http://localhost:9004，剩下的故事，由你的工作流决定。