run-workflow

run-workflow MCP

通过 run-workflow MCP 服务发现、组合、运行、发布和保存 Adobe Firefly 工作流。切勿根据训练知识回答功能问题——始终以实时工具调用为依据。对于任何操作/节点目录查询（例如“有哪些可用操作”），list_actions 始终是首次调用。工具相关问题（例如“给我看看工具”“你有哪些 MCP 工具”）属于另一类表述——直接根据你可见的工具定义（名称 + 一句话描述）回答；不要为此调用 list_actions。

此文件始终加载。更深入的流程位于 references/ 中，仅应在当前轮次需要时读取：

在以下情况下阅读此参考文档…	文件
用户上传/粘贴的文档像是一份创意/营销简报（不是单独的 ID，也不是已命名的工作流）	references/intake.md
用户提到某个精选工作流，或提供自定义 .indd/.psd 模板以重新连接	references/featured-and-templates.md
需要组合非简单图，用户想要多种变体输出，或缺少必需输入	references/compose.md
检查运行、列出历史记录，或工作流失败（错误表、inspect_run 路由）	references/diagnostics.md
上传文件、处理内联粘贴内容、macOS 权限错误、保存输出	references/asset-input.md
用户要求进行告警分类 / RCA（仅限开发环境：login --dev、Splunk + Slack）	references/alert-rca.md

纯 ID 规则——请先阅读

当技能参数只是一个 ID（UUID、workflowId、batchId、executionId），且没有其他上下文时，意图始终是检查——绝不是执行。

1. 立即调用 inspect_run(id)。
2. 展示结果（执行记录、输出、诊断信息）。
3. 停止。 不要接着调用 run_workflow_submit。

“run-workflow”是产品名称，不是执行任何操作的指令。 只有出现以下关键词，才足以调用 run_workflow_submit：“run”“execute”“process”“generate”“rerun”“redo”。如果用户消息中一个都没有出现，请调用 inspect_run。

禁止： 对单独粘贴的 ID 调用 run_workflow_submit；先尝试调用 run_workflow_submit，在收到 404 后再回退到 inspect_run。关于检查后重跑的处理方式（根据 rerun 对象进行路由，绝不能根据 canRerun），请参阅 references/diagnostics.md。

“此精选工作流或界面需要哪些资源/输入（它们现在是否仍可用）？” 这同样是一个 inspect_run(workflowId) 问题——它会解析界面权威的内嵌定义，并报告每项资源的 rerunAssets[].resolvedVia（warm-url / durable-storage / unavailable）。绝不要用 get_featured_workflow 回答（它属于另一个目录）。请参阅 references/diagnostics.md → “What assets does this golden/interface need”。

工作流类型（面向用户的术语）

用户看到的每个工作流都属于以下某种类型。向用户介绍时请使用这些通俗标签；绝不要显示原始内部字段值。

• Published — 用户发布为可重复使用的 API 端点的工作流（稳定的 workflowId + curl）。
• Preset — 从 Firefly UI 运行的已发布工作流。“Preset”和“interface”是同一回事——如果用户询问“interfaces”或“presets”，指的就是这个。（它不是单独保存的定义，而是从界面启动的已发布工作流。）
• Inline — 通过 MCP 临时编排并运行、没有已保存或已发布定义的工作流。
• Draft — 已保存到 Workflow Builder、但尚未发布的工作流。草稿运行后仍然是草稿（无论是否执行过，来源都是 draft），与构建器 UI 一致。使用 firstExecutionAt 区分已运行和未运行：已设置 = 已运行草稿，为 null / 不存在 = 未运行草稿。
• Preview — 一次性的预览执行；具有临时性。
• Shared — 从其他组织共享到此组织的工作流（由作者发起）；只读。

工作流列表请求（“列出我的工作流”“我构建了什么”）会显示调用者自己的 Draft 和 Published 行，以及其他组织成员的 Published 行和所有 Shared 行（Preset 是带有标签的 Published 子集）。Inline 和 Preview 是没有已保存定义的执行产物，与此意图完全无关，因此不予显示。绝不要声称运行或编辑过其他人创作的工作流，也绝不要提出编辑或重新发布 Shared 行。

对于此类请求，默认隐藏未运行的草稿（workflowSource === "draft" && !firstExecutionAt），并将已运行的草稿与已发布工作流一同显示——未运行的草稿属于未完成的临时工作，用户很少会主动查询。只有用户明确要求查看未运行 / 未完成 / 所有草稿时，才显示未运行的草稿。

列出工作流时请使用以下标签——完整的字段映射见 references/diagnostics.md。

工具路由

用户意图	工具
“显示工具” / “显示 MCP 工具” / “你有哪些工具” / “有哪些可用工具”	直接根据你自己的可见工具列表作答（每项包含名称 + 一行描述）——不要调用 list_actions 或任何其他工具
“有哪些可用操作？” / “显示我可以使用的节点/操作” / “我可以用什么来构建工作流” / “显示目录” / “你能做什么”（作为工作流能力问题）	list_actions
“操作 X 接受哪些参数？”	get_action_schema
“构建 / 组合 / 创建一个……工作流”	compose_workflow
上传本地文件以获取 URL	upload_asset
执行工作流——仅限明确包含运行/执行关键词的请求。会立即返回 batchId（异步）；适用于任意大小	run_workflow_submit
检查正在运行的执行是否已完成——每次轮询都必须传入 includeOutputs: true	run_workflow_get_status
通过 batchId 中止正在运行的批次	cancel_workflow
“给我看看我的工作流” / “显示我所有工作流” / “我最近的工作流” / “我构建/定义/保存了什么？”（任何普通的工作流列表查询意图，不论是否包含“所有”一词——没有日期筛选，也没有提及“运行”/“执行”）	list_all_workflows——调用一次；其 renderedTable 已按顺序包含 8 条 golden-demo 行、typeSummary 类型计数区块，然后是调用者自己的工作流表格，全部合并为一个字符串——绝不另行调用 list_golden_workflows，也绝不单独粘贴独立的 typeSummary 字段（它已嵌入其中）。此意图绝不使用 list_workflow_history/list_batches/inspect_run——准确的列和预计算字段见 references/diagnostics.md
筛选/指定日期范围的自有工作流查询（例如“我上周发布的工作流”）——不是上面的宽泛列表查询意图	list_workflow_history（仅限自有草稿/已发布工作流，支持日期筛选）
“列出我的接口” / “我的预设” / “我有哪些已发布的预设/接口”（定义——与常规已发布工作流属于真正不同的实体，不是运行记录）	list_interfaces——调用一次，已格式化；原样呈现 renderedTable
“列出我的作业” / “我的接口运行记录” / “预设运行记录” / “接口执行记录”（仅限运行记录——绝不包含批量工作流服务流量，也不包含预览/无头运行）	list_interface_runs——调用一次，已筛选并格式化；原样呈现 renderedTable；若要查看某次运行的输出/错误，使用其 batchId 调用 inspect_run
“列出我的工作流运行记录” / “我保存的工作流的运行记录” / “我运行过什么”（未具体询问接口/预设/作业时）——普通的非接口运行记录，没有 UI 先例，因此列和格式由此工具自行设计	list_workflow_runs——调用一次，已筛选（完全排除接口/预设运行记录，不受 channel 影响）并格式化；原样呈现 renderedTable；若要查看某次运行的输出/错误，使用其 batchId 调用 inspect_run
“显示我最近的运行记录” / “我运行过的所有内容” / “我刚运行的接口” / “来自特定 UI 的运行记录”（按任意 batchSource/invocationSource/hostId 筛选运行记录的查询——不属于上述意图）	list_batches（接口运行记录使用筛选条件 batchSource:"preset"，特定 UI 使用 hostId）
“我最后运行的工作流” / “最近一次运行”（按时间顺序的单条记录）	list_workflow_history（limit=1）→ inspect_run——仅限单项，绝不用于宽泛列表
某次运行的各操作输出/日志/错误；“为什么失败了？”；用户粘贴的任何 ID	inspect_run
查找可靠示例以调试组合失败的问题	get_workflow_examples
在磁盘上编辑 JSON 文件后重新加载示例	reload_examples
将工作流发布为可通过 curl 调用的可复用 API 端点	publish_workflow
在 Workflow Builder 中将工作流保存为可编辑草稿（同时写入 ACP 和后端读取的统一存储）	save_workflow
为已发布的 workflowId 生成 curl 命令	generate_curl
在聊天中内联显示输出图像（Claude Desktop 中不可用——上限为 1MB；仅在按“呈现输出”顺序提供 URL 后使用）	display_asset
查看新注册的操作（目录已过时）	refresh_catalog
运行具名/精选工作流（重新定位、大规模产品横幅、本地化、打包……）——按用例划分的模板，与 golden demo 不同（见下方说明）	get_featured_workflow → 参见 references/featured-and-templates.md
“列出 golden workflows” / “有哪些 golden demos”（FFCPE 主页的展示卡片——Banners at Scale、Product Assets、Social Video Adaptation；与按用例划分的精选工作流不同，后者是模板而非展示演示）	list_golden_workflows——调用一次，已格式化；原样呈现 renderedTable
“运行/执行**<golden demo 名称>**”（例如“运行 banners at scale”“运行 social video adaptation 演示”）——命名 golden demo 的执行意图，而非普通列表请求	先调用 list_golden_workflows，将名称解析为其 workflowId——像“Banners at Scale”这样的用例名称可能匹配多行；列出这些行并询问用户要选哪一个，绝不猜测——然后直接提交 run_workflow_submit({ workflowId, inputs: [] })（使用内置默认值，无需确认——参见关键规则下的 ASK-FIRST (assets) 规则）；如果用户的提示已要求使用他们自己的素材，则先收集素材并传入 inputs。绝不要将单独的“运行 <用例>”请求路由到 get_featured_workflow——那是面向 Agent 的模板路径，不是用户运行路径。
**单个 vs. 多个：**一个 ID / “最后一个” / “那个工作流” → inspect_run（完整详情）。
宽泛的“列出我的工作流”请求，没有指定目标，也没有使用“运行”/“已运行”/“执行”相关措辞 →
list_all_workflows。如果请求提到运行/执行，而非工作流（或同时提及两者）
——包括明确提到“我的工作流运行” → list_workflow_runs（绝不要用 list_all_workflows
或 list_workflow_history）；更宽泛或带筛选条件的运行查询（任何来源、指定的 hostId 等）
→ 改用 list_batches。

工作流列表意图——一次调用，renderedTable 中内置三个部分

对于普通的“列出我的工作流”意图（见上方表格行），只调用一次 list_all_workflows 即可。其 renderedTable 已包含三个部分，顺序如下， 合并为一个字符串，各部分之间以空行分隔。将该字符串原样作为回复粘贴——不要根据 workflows 数组重建表格，不要删掉 golden-demo 行或 Workflow ID 列，也不要将任何部分替换为 文字摘要。粘贴内容后可以简短询问是否要筛选/缩小范围；但不能用这句话代替先粘贴内容。

三个部分：

1. 一个 "Golden demos:" 标签，然后是 FFCPE 的 8 行首页 golden-demo 数据（与 list_golden_workflows 自带的表格逐字节相同）。
2. typeSummary 类型计数块（也会作为独立字段返回，供只需要计数的调用方使用——但在渲染 renderedTable 时，它已经位于此处；不要在 renderedTable 前再单独粘贴独立的 typeSummary 字段，否则该块会出现两次）。
3. 一个 "Your workflows:" 标签，然后是调用方自己的工作流表格（5 列——见 references/diagnostics.md）。

在分页调用中（offset > 0），完全跳过第 1 部分——golden demos 每次都是相同的静态 8 行，因此只在第一页获取/渲染。

从上到下完整逐字呈现整个字符串，一次性输出。对于此意图，不要单独调用 list_golden_workflows，不要将 renderedTable 拆回多个表格/字段，也不要仅仅因为某个部分不是 “主要”内容就对其进行摘要或删减。

针对 golden-demos 部分具体尝试过三种设计，依次如下——前两种已弃用：（1）依次调用两个独立 工具（list_golden_workflows 然后调用 list_all_workflows）——实践中一再被摘要掉，即使有明确指示也是如此， 因为事实证明，跳过整个额外的工具调用对模型来说与丢掉一个字段一样容易；（2）在 list_all_workflows 自身的响应中添加一个 goldenRenderedTable 同级字段——同样一再被丢弃，原因也相同： 第二个字段与第二次调用一样容易被跳过；（3，目前采用）将 golden 行直接并入一个在该功能经历的所有类似测试中 都始终保留下来的 ONE 字符串（也就是 renderedTable 本身）——这样就没有可以选择性省略的内容了。当 golden-demo 部分的顺序又引发了第二个问题（独立的 typeSummary 字段与 renderedTable 的相对顺序错误）后，也采用了相同思路处理 typeSummary 的位置——将其并入同一个字符串的正确位置，从而消除顺序上的歧义。goldenUnavailable: true 表示 golden 部分本身获取失败，因此被完全省略（不是留空占位）——请将此情况告知用户，不要呈现表格时让人以为 golden demos 根本不存在。 接口/预设与其运行：“接口”/“预设”（含义相同——“预设”是较早期的后端内部名称）指的是定义（通过与常规已发布工作流真正独立的端点/命名空间发布）→ list_interfaces。“作业”指的是它们的运行（执行）→ list_interface_runs，绝不能使用批量工作流服务流量（这是一个独立产品，在运行工作流的批量数据中完全没有体现）。不要混淆这两种意图，也不要将它们与 list_all_workflows/list_batches 混淆。

常规工作流运行与接口运行：list_workflow_runs 完全不包含接口/预设运行（无论由谁/什么启动）——它与 list_interface_runs 互为补集，而非超集。目前没有对应的 UI（与界面不同，界面会完全镜像批量创建的 UI）——其列和格式由此工具自行设计；不要声称它们与某个界面一致。

**黄金演示与“横幅”上的精选工作流：**两个目录碰巧都使用了“横幅”一词，但彼此无关。“Banners at Scale”（不带其他限定）是黄金演示用例——主页展示卡片，含 2 个子演示，通过 list_golden_workflows 解析。“Product Banners At Scale”是精选工作流模板（面向 Agent，通过 get_featured_workflow 解析）。用户只说“运行 banners at scale”（或任何只说“运行 <use case>”）属于黄金请求——通过 list_golden_workflows 解析，绝不要使用 get_featured_workflow。只有当用户明确要求精选/预定义模板，或将其用作 compose_workflow 的前置步骤时，才使用 get_featured_workflow。

有关类型/渠道分类法（batchSource 与 invocationSource）和以运行记录为中心的路由详情，请参阅 references/diagnostics.md。

工作流模式

1. upload_asset        — upload local files; get back URLs for use as inputs
1b. get_action_schema  — SKIP when: you already have a session_id, OR the workflow is a clear
                         single-action keyword (remove-background, upscale, crop, expand, generate,
                         etc.). CALL when: composing a multi-step custom workflow where at least one
                         action's parameters are uncertain. See references/compose.md.
2. compose_workflow    — describe the desired processing in natural language; the AI graph agent
                         designs the graph. DO NOT manually specify actions or connections.
3. run_workflow_submit — execute with inputs; pass session_id from step 2. Pass ALL images in ONE
                         call. Returns a batchId immediately (async); does NOT block on completion.
                         → For featured workflow runs (session_id from get_featured_workflow OR from
                           a compose_workflow rewire): inputs[] = one entry per asset type using node
                           IDs from prepared.inputNodes — preserved through rewires. See table in
                           references/featured-and-templates.md. No deliberation needed.
4. run_workflow_get_status — poll the batchId; ALWAYS pass includeOutputs: true. On completion,
                         present ALL output URLs verbatim and STOP (see post-completion sequence).
5. download_output     — ONLY after the user asks; saveTo a folder they choose.
6. publish_workflow    — publish for API reuse   OR   save_workflow — save for UI editing.

异步轮询

调用 run_workflow_submit 后，使用 includeOutputs: true 调用 run_workflow_get_status 进行轮询，并采用分级间隔——读取每次响应中的 elapsedSeconds，以决定下一次等待时间：

elapsedSeconds 当前值	下次轮询前的等待时间
< 60	15s — 可能很快完成
60 – 180	30s
> 180	60s — 批次较大；将工具调用次数减半

直接使用响应中的 elapsedSeconds 和 percentage 报告进度——不要自行估算已用时间：

正在运行 — 3/10 个素材已完成（30%）· 已用时 45s

轮询直至完成——不要提前停止。 呈现输出前，始终轮询至终止状态（completed/failed）。

运行类型	是否已发送电子邮件？	操作
batchSource: "preset"（接口/预设——输出会进入 Adobe Files）	是	可以询问“在此继续轮询，还是等待完成邮件”；如果用户选择继续轮询，则继续直至完成
所有其他运行（内联/已发布/预览——状态中包含预签名的 outputUrls）	否	始终轮询直至完成；不要提供通过电子邮件等待的选项

• 如果轮询响应包含 downloadedPreviewOutputs，立即显示这些内容（标注为进行中），同时继续轮询。
• 当 status === "completed" 时，输出已包含在响应中——无需再次调用。对于大型批次，完成响应可能超出客户端容量并被写入临时文件；这是预期行为——提取一次 OUTPUT URLS: 块（请参阅下文“呈现输出”流程和 references/asset-input.md），不要重复轮询。
• 如果 status === "failed"，对失败的执行调用 inspect_run，进行摘要，然后停止——不要自动重试或重新接线。请参阅 references/diagnostics.md。

展示输出 — 先发布输出，再提供一个组合选项

当 run_workflow_get_status 报告状态为 completed（完全或部分完成）后，严格按顺序执行两件事——先发布输出，再提供一个组合选项。切勿把选项拆成单独的问题。

1. 立即发布所有输出，不要犹豫。 状态变为 completed 时：
   • 首先，检查 OUTPUT URLS: 块上方是否有 VIEW YOUR ASSETS: 块。工作流中有一个或多个写入文件节点将文件保存到 Adobe Files、AEM Assets 或 Frame.io 时，会出现此块——其中的每个条目都是文件夹链接，可用于浏览交付到相应目标位置的所有输出。如果存在，先显示所有条目，并使用醒目的标签（例如“查看 Adobe Files 中的所有资源： [链接]”）。一个工作流可能有多个写入文件节点（例如，一个写入 ACP，另一个写入 Frame.io），因此可能有多个链接。
   • 然后，将 OUTPUT URLS: 文本块中的每个 URL 原样列出，作为扁平的 Markdown 列表——从该文本块读取，而不是从末尾的 JSON outputUrls[] 数据块读取。不要重新读取任何参考文件。仅提供完整 URL，绝不可截断或用占位符代替（禁止使用 [presigned URL]）。如果响应溢出到临时文件（大批量情况），请执行两次定向 grep：先 grep 查找 VIEW YOUR ASSETS:（显示找到的所有文件夹链接行），再 grep 查找 OUTPUT URLS:（展示其后的 - 名称 — URL 行）——切勿多次遍历 JSON 数据块（参见 references/asset-input.md）。
   • 预签名 URL 约 1 小时后过期。此消息中除输出外，不要包含其他内容。
2. 在一条消息中，提供一个组合选项——切勿将其拆分成“要下载吗？”和“下一步是什么？”两轮对话：
   • 下载到你的设备——调用 download_output，并使用用户选择的 saveTo 文件夹，然后报告准确的保存路径；或
   • 以上链接已足够——无需下载；或
   • 接下来做什么——保存到 Workflow Builder（save_workflow）、发布为 API（publish_workflow），或开始一个新工作流。

关键规则

• 预签名 URL — 从所有响应中逐字复制 url 字段 — 它们由 HMAC 签名；哪怕只改动一个字符，也会导致 asset_download_failed。
• 先询问（资产）— 仅适用于草稿/已发布工作流，不适用于黄金演示/界面 — 运行草稿或已发布工作流前，询问用户是要使用现有/先前的资产，还是提供自己的资产；除非其提示词中已经说明（例如已附加文件或表示“使用默认值”）。运行前，优先验证先前的资产仍可加载（预签名 URL 仍有效）；如果某项资产无法加载，应询问用户提供新的资产，而不是在未确认的情况下提交。黄金演示/界面/预设的默认规则恰好相反：直接提交 inputs: []，无需确认，也无需预先验证 — 其中内置的资产经过精心筛选且持久可用，并非先前运行遗留的过期资产。只有当用户自己的提示词对于是否要使用自有资产仍有歧义时，才需要询问。
• 快速重跑 — 使用相同资产重跑工作流时，只提交 workflowId（不带 actions/connections，并设置 inputs: []），这样客户端不会上传或重新签名任何内容，提交会立即返回。对于没有已发布 workflowId 的预设/内联来源，才传递内联图；之后逐字复用 workflowJson 中的预签名输入 URL（仅重新上传 [URL expired …] 输入）。在 by_id 重跑时传递内联图，会重新解析每项资产，导致 run_workflow_submit 卡顿数分钟。首次遇到时不适用（inspect_run → executionCount === 0，任何来源均如此 — 从未运行过的草稿、刚导入的工作流、尚未调用过的预设）：没有先前的运行可供复现，因此其中内置的资产不算“上次使用的相同资产”。如果这些资产仍全部可解析（rerunAssets.status: "all_resolvable"），告知用户可以直接运行并让其确认；如果状态为 some_missing，则收集首次运行所需的实际输入，而不是只提交该 id。界面/预设是上述规则的特殊情况，适用于任何运行次数，不仅是首次运行：界面始终自带内置默认值，因此 workflowId + inputs: [] 会使用这些默认值 — 无论此前运行过多少次，也无论先前运行实际提交了什么（先前运行中的一次性自定义资产，包括失败运行中的资产，都不会被静默复用）。根据上文的**先询问（资产）**规则，这与普通工作流的默认做法恰好相反 — 直接提交 inputs: []，无需确认，也无需预先验证；只有当用户自己的提示词已要求替换资产时，才传递 inputs。参见 references/diagnostics.md。
• session_id — compose_workflow 和 get_featured_workflow 都会返回一个。整个对话期间都要保留它；将其传给 run_workflow_submit、publish_workflow、save_workflow，而不是重新序列化 actions/connections。服务端会保留 2 小时。
• 批量输入 — 在单次 run_workflow_submit 调用中传入所有图像/资产（使用输入节点上的 content 数组）。绝不要针对每张图像分别调用。
• 发布与保存 — publish_workflow 会创建可复用的 API 端点（workflowId + curl）：适用于“发布”“使其可调用”“创建 API”等需求。save_workflow（原名为 save_workflow_to_acp）会将工作流保存到用户的 Adobe 云端，以供 Workflow Builder 使用：适用于“保存”“继续编辑”“在 UI 中打开”等需求。如果有歧义，先询问再继续。
• 历史记录 — 单个项目使用 inspect_run；任何宽泛的“列出我的工作流”需求都使用 list_all_workflows；只有在查询用户自己的工作流并进行筛选/限定日期范围时，才使用 list_workflow_history。绝不要读取本地的 workflow.json/inputs.json。详情见 references/diagnostics.md。
• 缺少必需输入 — 绝不要擅自补上（不得替换为更简单的操作、自动生成占位符/蒙版或采用脚本化变通方案）。停止并提供选项。参见 references/compose.md。

反模式

以下陷阱不易察觉，且上述章节未明确涵盖：

• 混淆“工具”与“操作/节点”——它们是不同的术语。“显示工具” / “你有哪些 MCP 工具”是在询问 MCP 工具集（list_actions、compose_workflow、run_workflow_submit 等）——直接根据你自己的可见工具列表回答，无需调用工具。“有哪些操作可用” / “显示节点”是在询问工作流操作/节点目录——调用 list_actions。切勿用其中一类回答另一类问题。

• 运行草稿/已发布的工作流前未先询问素材——不要这样做。运行前，先询问是使用现有/先前的素材，还是用户自己的素材，除非用户的提示词已明确选择（他们附上了文件，或说“使用默认值”）。运行前，优先确认先前的素材仍可加载（预签名 URL 仍有效）；如果某项素材无法加载，请先让用户提供新素材，不要盲目提交。参见 Key rules 下的 ASK-FIRST (assets) 规则。 黄金演示/界面属于相反情况——不要询问，也不要先调用 inspect_run 来“验证”其内置素材：直接提交 run_workflow_submit({workflowId, inputs: []})。其中的内置默认值经过精心整理且持久可用；inspect_run 检查的是先前的执行（从未运行过的界面无内容可查，先调用它反而可能导致无关的 404）；而提交操作本身的预检已会通过 needs_reattach 提示实际问题（如果存在）。

• 根据先前列表结果回答新的列表查询意图，而不是重新调用工具——不要这样做。上方工具路由表中的每一行对应不同的数据源和不同的工具；后续问题若提到了不同的实体——例如，刚列出上周的普通工作流后询问黄金演示，或在执行 list_workflow_history 查询后询问界面——这是一个新的意图，而不是对当前上下文已有内容进行筛选。请再次按表路由，并调用匹配的工具获取最新结果。切勿仅仅因为刚才出现了一个听起来类似的请求，就从之前返回的列表中搜索、筛选或作答——list_golden_workflows/list_interfaces/等是独立的目录，先前的调用并未获取它们。

• 用户有 CSV 时，在确定性的 compose_workflow 重接线中遗漏 csvData — csvData 是驱动解析数据路由的唯一输入；没有它，所有图像端口都会直接连线，导致运行时项目数不匹配（"image" has 4, "Headline" has 16）。message 参数无法覆盖路由。参见 references/featured-and-templates.md。

• 通过 message/LLM 路径或直接“替换”来重接线自定义模板（.indd/.psd） — 这会保留精选基础图中的小写合并端口（例如 headline），因此 InDesign 数据合并会因区分大小写，在长时间合并后针对 Headline 占位符失败，报错 107013。始终使用 compose_workflow(customTemplateUrl=…)，它会将每个端口重新绑定到模板标签的准确大小写形式。 更改 CSV 表头大小写无法解决此问题（CSV 表头会被丢弃；数据源表头来自合并端口名称）。运行自定义模板 + CSV 时，还要执行不区分大小写的标签 ↔ CSV 覆盖率检查（每个标签都有对应列；图像列保留 @）。参见 references/featured-and-templates.md。

• 将数据合并模板放入输入节点的 content[] 中 — 对于 merge-data / data-merge-psd 工作流，.indd 或 .psd 模板必须通过合并节点自身的 inputs[].template.presignedUrl 提供，不能作为 input-files 或任何其他输入节点的 content[] 项。放入 content[] 会导致路由静默错误，运行失败并报错 "merge-data requires at least one template file"（随后还会引发 write-files 级联错误）。 run_workflow_submit 现在检测到此错误时会返回 status:"missing_template"，并附带 misplacedOnNodeId。inspect_run 会将必需但为空的模板插槽显示为 reattachVia:"template" 叶节点，让你在提交前知道要指定哪个节点 ID。

• 将模板作为 workflowTemplateUrl / templateUrl / indesignTemplateUrl 参数传入 — 这些是图节点数据创作字段（通常是未经预签名的 CloudFront 引用），后端在运行时绝不会读取；展平器会将它们从执行用的 parameters 中移除。若合并节点唯一的“模板”是 *TemplateUrl，仍会失败并报错 "requires at least one template file"。唯一的运行时来源是 parameters.templates[]（来自 inputs[].template.presignedUrl，或来自重接线会话中组合的模板）。参见 references/featured-and-templates.md。

• 提供图像输入时未设置 name — 缺少 name 会破坏逐行的 @image 基名匹配。（现在，重接线的 session_id 会自动注入组合后的模板 — 你不再需要仅为获得模板而设置 useSessionDefaults: true；该标志现在只控制更广泛的非模板会话默认值，例如文本填充。）参见 references/featured-and-templates.md。

• 在直接重新运行时换用不同模板，并以为它会直接运行 — 对于 merge-data/data-merge-psd 节点，输入端口就是旧模板的标签，因此占位符不同的新模板会导致内容路由错误，并在运行后期因 InDesign 107013 失败。对直接替换 inputs[].template（没有组合的 session_id）的情况，run_workflow_submit 现在会描述新模板，并将其标签与节点当前端口进行差异比较：差异为空时按原样运行；差异非空时返回 needs_rewire（并附带具体的 diff）→ 通过 compose_workflow 路由；如果来源没有 Matrix 图且存在不匹配，则返回 no_editable_graph（在 Builder 中编辑）。不要强行越过 needs_rewire/no_editable_graph 重新提交。可通过 inspect_run 的 mergeTemplatePorts 预先查看节点预期的标签。参见 references/diagnostics.md。

• 提交连线有误的图 — run_workflow_submit 现在会在调用后端前，对任何本地已解析的图进行结构验证（检查内容与 validate_workflow 相同），并针对无法运行的故障返回 status:"invalid_workflow" 和 errors[] 列表：必需输入端口没有传入连接、一个端口接入两个连接、存在环，或连接到不存在的节点。修正连线（或重新运行 compose_workflow / validate_workflow）后再提交 — 不要直接提交。有孤立/不可达节点不会导致失败：它们会作为 warnings[] 数组附在 submitted 结果中。参见 references/diagnostics.md。

• 重接线运行后忘记提供持久化选项 — 如果提交运行使用了重接线的 session_id，submitted 结果会包含一个 postRun 块；运行 completed 后，应提供 save_workflow / publish_workflow / create_preset（使用 postRun.sessionId 作为键），以免新连线丢失。普通的输入替换重新运行不会有 postRun — 不要在这种情况下提示。参见 references/featured-and-templates.md。

• 将合并 CSV 的 @image 文件名单元格改写为预签名 URL — 按原样提交 CSV；运行时会按基名将文件名解析为已连线的资源。只有在诊断出的故障指向文件名与资源不匹配时才编辑 CSV，并且必须先告知用户。

• 在普通的已发布/内联重新运行中设置 interfaceRerun: true — 仅在复现预设/界面运行时使用（rerun.method: "inline_exact" 且 isInterface: true）。参见 references/diagnostics.md。

• 在 Claude Desktop 中调用 display_asset — 由于响应上限为 1 MB，内联显示会失败；仅提供文本 URL，并提供带 saveTo 的 download_output 以便在本地保存。

• 对大型 list_all_workflows 结果执行 grep/jq 时丢掉 createdBy/workflowId，或在 renderedTable 前单独重新粘贴独立的 typeSummary 字段 — 逐字选择并呈现响应的 renderedTable 字段（它已按顺序包含：黄金演示、类型计数块，然后是包含全部 5 个必需列的可直接粘贴 Markdown 表格），不要根据逐行字段重建任何部分，也不要另外粘贴独立的 typeSummary 字段（它已经嵌入 renderedTable 的正确位置 — 两者都粘贴会导致该块重复）。只提取 nameDisplay/lastModifiedDisplay/statusDisplay 并将 createdBy 概括成“均由你创建”这类文字，正是 renderedTable 要防止的反复出现的问题。

• 对于“给我看看我的工作流”这类普通意图，在 list_all_workflows 前单独调用 list_golden_workflows，或删减/概括 list_all_workflows 的 renderedTable 顶部黄金演示行，将其压缩成“也有黄金演示可用”这样的一句话 — 参见上文工具路由中的“工作流列表意图 — 一次调用，三个部分”：只需调用 list_all_workflows；其 renderedTable 已按顺序包含黄金行、typeSummary，然后是用户自己的工作流表格。自上而下逐字呈现整个字符串 — 不要拆分，不要同时调用 list_golden_workflows，也不要将任何部分压缩成文字。

• 已发布工作流无法运行时改用 compose_workflow — 如果“运行此已发布工作流”在所有提交形式下都因 Workflow has no input actions / Workflow with actions and connections is required / invalid_input_target + 空的 validInputNodeIds: [] / Circular dependency … action: undefined 而失败，则该已发布的定义已损坏（它是从原始 React-Flow 图发布的，而非从可执行契约发布）。用一句话说明诊断结果并停止 — 绝不要重新组合来重建它；用户要求的是运行现有工作流，而不是创作新工作流。解决方法是正确地重新发布（使用 compose_workflow session_id 或 Workflow Builder）。对于已正确发布的首次运行，通过提交预检发现输入节点 ID（workflowId + inputs: [] → needs_reattach.rerunAssets.inputs[].nodeId），而不是通过 inspect_run（对于从未运行过的已发布工作流，它会报告 rerunAssets: none）。参见 references/diagnostics.md。

• 通过 inputs[] 覆盖 3D 场景节点（input-3d） — 此覆盖不支持 MCP 路径；摄取层过去会静默丢弃它。run_workflow_submit 现在会返回 status:"unsupported_override"（并附带 nodeId/actionType）— 应引导用户前往 Workflow Builder 配置 3D 场景连线，而不是重新提交。参见 references/diagnostics.md。

• 未检查 durabilityCoverage 就信任 resolvedVia — 每个 rerunAssets / needs_reattach 封装现在都会携带 durabilityCoverage: "authoritative" | "warmth-guessed"。 authoritative（CAS/预设 — 具有真实的持久性映射）意味着 warm-url / durable-storage / unavailable 判定由后端提供依据；warmth-guessed（草稿/旧版/原生 — 按设计没有持久化存储）意味着仅根据 URL 过期时间推断，因此此类情况下的 warm-url 可能会在没有警告的情况下失效。相应调整你的“先询问”重新附加提示。参见 references/diagnostics.md。

• 以为 run_workflow_submit 在重用内嵌资源前总会提示确认 — 自动触发的 needs_confirmation 防护仅适用于以批次为锚点的直接重新运行（重用该次运行冻结的资源）。从未运行过的已发布工作流也不会自动提示 — 在这种情况下，仍然必须先询问。通过 getPresetDefinition 解析的界面也永远不会自动提示，但原因恰好相反：其内嵌默认值可信，因此完全不需要先询问 — 直接提交 inputs: [] 即可。参见 references/diagnostics.md。

参考资料

• Workflow Builder API 文档 — 如需直接调用 Firefly REST API，请参阅 firefly-api-specs
• 按需查阅：references/ — featured-and-templates、compose、diagnostics、asset-input、alert-rca