参考与故障排查

生成调用的是你自己配置的模型提供商，费用由提供商侧结算。本软件不代收任何费用， 因此这类报错几乎都出在提供商账户上。

排查顺序：

1. 登录对应提供商控制台，确认余额或剩余额度充足（免费额度用尽也会直接失败）。
2. 设置 → 模型：确认密钥填写正确、未过期、未被吊销。
3. 确认所需模型已勾选启用，并分别设好了默认的文本 / 图片 / 视频模型。
4. 换一个模型试跑同一节点，用于区分是「账户问题」还是「单个模型问题」。

1. 检查密钥前后是否混入空格或换行；重新复制粘贴一次通常能解决。
2. 确认该密钥在提供商侧已开通对应模型的权限，部分模型需要单独申请。
3. 若使用代理或中转服务，确认中转地址填写完整（含 /v1 等路径）。
4. 网络受限时可在设置中配置代理后重试；公司网络常见的 HTTPS 拦截也会导致拉取失败。

端口严格区分单数与复数，类型不同连不上，且单数不能进复数： image 进不了 images，video / voice / text 同理。

常见处理方式：

1. 需要列表输入时（如「选取图片 / 视频 / 声音 / 文本」），请从上游的 方形口（out-all，导演台为 out-shots / out-actions）连线，默认圆形 out 连不上。
2. 结构化目录类端口使用 world / worldEntities / beat（世界元素 / 世界元素实体 / 场），不能与普通 text 混连。
3. 剧本节点的 text 也不能直接接进「选取文本」，需要走对应的列表口。

详见 §8 节点图。

1. 打开节点的执行日志，查看具体报错（多数是模型返回错误或参数不合法）。
2. 确认上游节点已成功执行：上游没跑完，下游不会有输入。
3. 检查任务队列是否被其他长任务占满；可暂停或取消排队中的任务。
4. 图库生成节点有 out（当前选中）与 out-all（全部历史）两个出口， 若接的是 out，请在右侧 Inspector 中确认已选中期望的那条。

这是纯文生图最容易踩的坑，靠参考而非反复描述来解决：

1. 使用锚点图：先从 9 宫格 / 4 宫格拼图中按格拆出参考图，再作为后续生成的参考输入， 可锁住长相、服装与场景。
2. 把角色、场景、道具登记为世界元素，让各场共用同一份设定，避免每次重新描述。
3. 检查中途是否有节点更换了模型或大幅改写提示词，风格漂移往往来自这里。
4. 短剧流程中善用 review1~review4 审核节点，及时打回不达标结果。

详见 §2 核心概念 与 短剧制作教程。

1. 在生成链末端接入高清放大节点；短剧模板已内置该步骤。
2. 确认生成节点参数中的分辨率设置，部分模型需显式指定尺寸。
3. 避免过度压缩：导出时留意缩放比例与导出格式。

1. 确认动态提示词已正确填写；静态描述会生成近乎静止的画面。
2. 确认所选视频模型支持目标时长与分辨率。
3. 参考视频需要可访问的外链：请配置对象存储（TOS / OSS / COS / 兼容 Amazon S3， 同时仅可启用一个）；纯本地预览可先不配置，但参考视频功能会受限。S3 填法见 Yandex Object Storage 示例。
4. 详见 视频教程。

1. 同一时间只能启用一个对象存储（火山 TOS / 阿里云 OSS / 腾讯云 COS / 兼容 Amazon S3）， 启用新的前请先关闭旧的。
2. 私有桶可以保持私有。未填公网域名时，应用会给出约 24 小时有效的签名链接，模型可以拉取；过期后重新上传即可。
3. 核对 AccessKey 是否具备该 Bucket 的读写权限，以及地域（Region）是否填对。Yandex Object Storage 的 Region 是 ru-central1，见 配置示例。
4. 需要固定公开地址时再填公网访问域名。国内 CDN 域名按服务商要求完成备案。

1. 确认本机 comfy-api-proxy 已启动，且端口与软件中填写的一致。
2. 确认 ComfyUI 本体已启动并可正常访问。
3. 必须使用 API 格式的 workflow（在 ComfyUI 中开启 Dev Mode 后「Save (API Format)」导出），界面格式（含 nodes / links 数组）不可用。
4. 详见 ComfyUI 教程。

1. 确认安装包与系统架构匹配（macOS 需区分 Intel / Apple 芯片）。
2. 首次启动若被系统安全策略拦截，需在系统设置中允许该应用运行。
3. 更新失败时可在设置 → 通用 → 关于与更新 中重新检查，或从 Releases 手动下载覆盖安装。
4. 仍异常时，先备份工程目录，再重置配置后重试；记得反馈时附上日志与系统版本。

应用内置 MCP 工具服务，接入后 Claude Code 等 AI Agent 可直接对话 规划工作流、编辑节点图、运行生成、查询任务。前提是应用处于运行状态， 两种方式任选其一：

1. stdio 桥（推荐，需 Node.js 18+）：执行 claude mcp add aiartengine -- node <安装目录>/resources/mcp-bridge.mjs。
2. HTTP 直连（无需 Node.js）：打开 设置 → MCP，复制「Claude Code 接入命令」后执行； 或手动执行 claude mcp add --transport http aiartengine <接入地址> --header "Authorization: Bearer <token>" （接入地址与 token 见应用侧 mcp.json，跨重启持久复用）。

注册后需重启 Agent 会话才会出现工具；应用侧 mcp.json （%APPDATA%/aiartengine/mcp.json）由应用自动维护，不要手改。 注册命令报错（如 Script not found）多为本机 Claude Code 安装异常，重装后再试。 详细步骤与工具清单见 MCP 接入教程。

1. 模型不可用（HTTP_404 等）：对话面板的模型走「模型」下拉中选中的文本模型， 模型 ID 以所选提供商实际存在的名称为准；改用已在提供商后台开通的模型， 或换一家已配好 Key 的提供商。
2. 未选模型 / 无可用模型：先在 设置 → 模型 中启用至少一个文本模型并填好密钥。
3. 一直转圈不执行：确认本机 Node.js ≥ 22.19（安装包已内置运行体）；查看面板状态行与日志。
4. 工具执行失败：检查工具卡片的错误信息，常见为工程未打开或 API Key 额度不足。