> For AI agents: the complete documentation index is available at https://docs.reelway.ai/llms.txt, the full documentation bundle is available at https://docs.reelway.ai/llms-full.txt.

# 节点协议

节点(worker)通道挂载于同一 WS 端点,按握手头分流;线协议 `{type, data: base64(JSON)}`,worker 侧单帧上限 8 MiB。客户端侧协议见 [SDK → Reelway 协议](https://docs.reelway.ai/sdk/protocol.md)。

## 握手

| 项             | 说明                             |
| ------------- | ------------------------------ |
| 端点            | `wss://rcn.reelway.ai/socket`  |
| `api-key`     | 节点用途的账户 API Key(建议独立子 Key)     |
| `app-id`      | 节点唯一 UUID,必填;缺失或认证失败关闭码 `4021` |
| `client-type` | `worker`(必填)                   |
| `worker-type` | 可选,默认 `Comfy.FastWorker`       |

同 `app-id` 的后连者以关闭码 `4015` 接管前连者。服务端 25 s ping / 60 s pong 窗口;空闲靠 pong 保活(`lastSeenAt`)。

## 时序

```
握手 → authenticated(空负载) → workerInfo(全量能力) → readyToAcceptJobs(ready=true) → 服务端 push jobRequest
```

## 上行帧

| type                 | 负载                                                                   | 说明                                      |
| -------------------- | -------------------------------------------------------------------- | --------------------------------------- |
| `workerInfo`         | `{workerModels[], loadedModelID, hardwareRating}`                    | 全量能力快照;字段名为 `workerModels`(非 workflows) |
| `workerModelsChange` | `{added[], removed[]}`                                               | 只按增量维护模型集;其余遥测不得触碰全量快照                  |
| `readyToAcceptJobs`  | `{ready, reason, postDisconnectCleanupComplete, readinessSessionId}` | `awaitingCleanup` 时未携清理完成标记则不派单         |
| `jobState`           | `type: jobStarted(stepCount) / jobCompleted`                         | 失败路径先 `jobResult` 后 `jobError`          |
| `jobProgress`        | `{jobID, imgID, step, stepCount, hasImage, etaSeconds}`              | 执行进度                                    |
| `jobResult`          | `{jobID, imageId, …结果元数据}`                                           | 服务端以 `(jobID, imageId)` 重建产物键并探测对象收敛    |
| `jobError`           | `{jobID, imgID, error, error_message}`                               | `5000` 执行失败 / `5001` 节点断线收敛失败;终态        |

## 下行帧

| type            | 负载                                                                                   | 说明                                 |
| --------------- | ------------------------------------------------------------------------------------ | ---------------------------------- |
| `authenticated` | 空负载                                                                                  | 确认鉴权通过                             |
| `jobRequest`    | `{jobID, imageId, workflowId, clientParams, assets, previews, outputFormat, isTest}` | 派单;`imageId` 即渲染身份 `imgID`,贯穿上传/下载 |
| `jobCancel`     | `{jobID, reason}`                                                                    | 客户端取消在途任务                          |

## 断线与清理

节点断线时在途任务收敛失败(`5001`),该 `app-id` 进入 `pendingCleanup`;其**下一次连接**的 `readyToAcceptJobs` 必须携带 `postDisconnectCleanupComplete: true` 才会恢复派单(断线清理就绪协议 v1)。

## REST 配置面(公开)


POSThttps://rcn.reelway.ai/v1/client/key鉴权:worker key

连接前密钥预检;body 为 text/plain 密钥原文



GEThttps://rcn.reelway.ai/v1/worker/config/comfy[?filter=<子串>]鉴权:公开

模型目录;filter 按 workflowDependencies 键子串过滤;1 分钟缓存



GEThttps://rcn.reelway.ai/v1/worker/config/comfy/loras鉴权:公开

LoRA 目录(当前恒空)



GEThttps://rcn.reelway.ai/v1/worker/config/prompt-safety鉴权:公开

提示词安全配置;fail-closed 口径端点常驻


## 产物上传

完成任务时凭任务能力 `(jobId, imageId)` 申请 `GET /v1/image|media/uploadUrl` 的 `complete` 槽位上传产物;无凭证。详见[媒体与图像 URL](https://docs.reelway.ai/api-reference/media.md)。