> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作原理

> 工具背后的运作模型 —— 传输方式、ComfyUI-Manager API，以及本地 / 远程 / 云端三种模式。

## 心智模型

ComfyUI MCP 是盖在**正在运行的 ComfyUI 实例**上面的一层薄、描述清楚的封装。大多数工具
通过它的 HTTP/WebSocket API 交谈，所以无论 ComfyUI 在本地、远程（`--comfyui-url`）还是
[Comfy Cloud](https://cloud.comfy.org)（`COMFYUI_API_KEY`），行为都一样。

<Steps>
  <Step title="生成与工作流 → ComfyUI HTTP API">
    `generate_image`、`enqueue_workflow`、队列 / 历史 / 系统状态，以及工作流编写工具，
    都会调用 ComfyUI 的 `/prompt`、`/queue`、`/history`、`/object_info` 等。入队是
    fire-and-forget：你立刻拿到一个 `prompt_id`，结果通过完成通知到达。云端模式下，
    另一套 `cloud-client` 把同样的操作用 `X-API-Key` 派发到 `cloud.comfy.org`。
  </Step>

  <Step title="自定义节点与模型 → ComfyUI-Manager（HTTP），并带回退到子进程">
    节点安装 / 更新 / 快照 / 二分，以及工作流依赖安装，优先走
    [ComfyUI-Manager](https://github.com/Comfy-Org/ComfyUI-Manager) HTTP API
    （因此对远程实例也能用），API 做不到的部分再回退到对着本地安装跑 `cm-cli` / `git` /
    `pip`/`uv`。
  </Step>

  <Step title="安装与文件系统操作 → 仅本地">
    安装 ComfyUI、更新核心、删除模型文件、读服务器日志、列出输出目录，都作用在本地
    文件系统上。它们需要已知的 `COMFYUI_PATH`，在远程或云端模式下会返回明确错误。
  </Step>

  <Step title="WebSocket → 本地 + 远程，不含云端">
    任务完成通知在可用时挂到 ComfyUI 的 WebSocket。Comfy Cloud 没有 WebSocket ——
    任务监视器会落到已有的 HTTP 轮询路径。
  </Step>
</Steps>

<Note>
  经验法则：任何**读取或运行**已连接服务器的事情，三种模式都能用；任何**安装软件或
  碰磁盘上文件**的事情，都需要本地安装。完整功能对照表见
  [配置 → 部署模式](/docs/docs/zh/configuration#部署模式)。
</Note>

## 自愈：队列 / 渲染监视狗

以前，一个卡住的高分辨率采样步骤会让智能体在它看不见也杀不掉的僵尸渲染后面继续堆任务。
三道尽力而为的护栏补上这个缺口，于是智能体不会再对着卡住的渲染盲目重入队：

* **背压** —— 已经有渲染在跑时，`panel_run` 会在结果里追加一条 QUEUE WARNING，
  这样智能体就不会再往后面堆。
* **停滞检测** —— 一条被动 WebSocket 跟踪正在跑的 prompt / 节点 / 进度；某一步超过
  阈值还没推进
  （[`COMFYUI_MCP_STALL_S`](/docs/docs/zh/configuration#面板编排器与桥接)，默认 180 秒）
  时，会在智能体下一轮前面预置一行 STALL/BACKLOG 说明。
* **升级取消** —— `queue`（action:"cancel"）会中断、**核实**任务确实停了
  （在 [`COMFYUI_MCP_INTERRUPT_S`](/docs/docs/zh/configuration#任务监视) 内，默认 30 秒），
  然后升级到 `/free`，如果它还不肯死就报告渲染 WEDGED（并建议 `restart_comfyui`）；
  `clear_pending` 在同一次调用里丢掉所有待处理任务。

全部是故障安全：监视狗 WebSocket 如果从没打开，什么都不会变。智能体也可以通过
`get_image (action:"analyze_color")` 在不走视觉往返的情况下推理一张图的颜色
（主色板、平均 + 亮度统计、对比度检查）。

## 工具分类

<CardGroup cols={2}>
  <Card title="图像生成" icon="image" href="/docs/docs/tools/image-generation" />

  <Card title="工作流执行" icon="play" href="/docs/docs/tools/workflow-execution" />

  <Card title="工作流编写" icon="pen-ruler" href="/docs/docs/tools/workflow-authoring" />

  <Card title="工作流库" icon="folder-open" href="/docs/docs/tools/workflow-library" />

  <Card title="资源与图像" icon="images" href="/docs/docs/tools/assets-images" />

  <Card title="模型" icon="box" href="/docs/docs/tools/models" />

  <Card title="自定义节点" icon="puzzle" href="/docs/docs/tools/custom-nodes" />

  <Card title="API 节点" icon="cloud" href="/docs/docs/tools/api-nodes" />

  <Card title="安装与环境" icon="wrench" href="/docs/docs/tools/install-environment" />

  <Card title="进程控制" icon="power" href="/docs/docs/tools/process-control" />

  <Card title="默认值、统计与技能" icon="sliders" href="/docs/docs/tools/defaults-stats-skills" />
</CardGroup>

<Info>
  工具参考由实时 MCP 工具 schema 生成（`npm run docs:gen`），所以它不会和代码脱节。
</Info>