scenario-workflow-authoring

场景工作流编写

概述

工作流有两种表示形式：editor_info（可编辑的节点图：nodes、edges、inputKeys）和 flow（编译后的可运行形式）。通过 MCP 编写工作流，意味着要写入整个 editor_info 文档：没有单节点编辑工具；每次更改都要通过 workflow_create 或 workflow_update 读取、修改并写入完整图。切勿手动编写 flow：workflow_publish 会将 editor_info 编译为 flow，并将状态切换为 ready。编辑已就绪工作流的 editor_info 后，旧的 flow 会继续运行，直到再次发布。

编写任何图之前，请先阅读 references/editor-info.md：其中介绍了节点类型词汇、节点选择原则（何时可以合理使用 llm 节点）、边的方向规则、各节点的数据契约，以及经过验证的最小示例。创建、更新、发布、复制和删除功能位于工具目录中（scenario_tools_search 及对应的执行器，参见 scenario 技能）。workflows_list、workflow_get 和 workflow_run 是直接工具：作用范围和 dry_run 必须放在顶层参数中，不能放在执行器封装中。运行和定价：参见 scenario-workflows 技能。如果此处提到的同伴技能不在可用技能中，请提示用户安装（npx skills add scenario-labs/skills --skill <name>）；在无人值守的情况下，请根据工具架构继续操作，并注明缺少该技能。

快速参考

步骤	调用	说明
1. 研究图	对可用工作流调用 workflow_get	复制结构，不要复制 ID
2. 模型契约	model_schema_get	处理名称和必填输入
3. 编写	editor_info + inputs_definition	按照参考文件
4. 创建	workflow_create	非原子操作，见下文
5. 发布	workflow_publish	编译 flow；必须有一个输出 pin
6. 验证	使用 dry_run=true 调用 workflow_run	定价并运行实际验证器

workflow_create 在底层分为两次调用：创建失败时，仍可能已创建一个草稿，且其 ID 会显示在错误信息中。请使用该 ID 调用 workflow_update 恢复；重新创建会产生重复项。步骤 1 可通过 workflow_get 获取数据：它会返回你持有其 ID 的任意工作流的完整图，包括公开工作流（ID 或用户提供的应用 URL，或你自己的团队通过 workflows_list 获取的工作流）。要查找公开模板，请使用 search，并设置 target="workflows"、public=true、关键词 query、limit=3 以及你的作用范围；例如，query="image" 并使用原始 filter: 'status = "ready"'。从 workflows 中读取 ID，然后通过 workflow_get 获取所选图；搜索结果只是摘要，不是图文档。工作流搜索仅支持关键词文本和筛选条件，因此请省略图像和语义选项。浏览已保存的工作流请使用 workflows_list。 scripts/fetch_workflow_examples.py 会批量导出精选工作流的精简图，供维护者使用（设置说明见文件头部）。

示例：文生图应用

1. 使用 capability: "txt2img" 调用 recommend，并将用户的需求描述作为 prompt，遵循 scenario 技能的 next_step 规则，然后调用 model_schema_get：其输入名称会成为模型节点的句柄名称，required 标记表示必须连接的输入。用户指定模型时改用 search。
2. 编写 editor_info：设置 text1 的 data.isInput: true，设置 model1 的 type: "model"、data.modelId 和 data.isOutput: true，添加一条从 model1 输入端到 text1 输出端的边（边的 source 指下游节点，参见参考文档），并设置 inputKeys: ["text1"]。
3. 调用 workflow_create，传入 name、editor_info 和 inputs_definition，将 text1 定义为字符串输入。已发布的输入键就是节点 ID，因此运行输入会使用 text1 这样的名称。
4. 调用 workflow_publish，然后使用 dry_run=true 调用 workflow_run 进行验证和估价。如果验证失败，修复图并重新发布。

每个输入项都需要一个输出时，必须使用循环

将多项素材输入直接连接到生成模型的参考字段，会让模型根据所有输入项同时进行一次生成：例如，输入十张产品照片，得到的是一张融合了它们的图片，而不是十张编辑结果。字段名称和基数因模型而异，因此请通过 model_schema_get 查看（array: true 表示列表），并阅读字段说明：有些实用工具接受列表，并为每个输入项返回一个输出，无需循环。每个输入项都需要单独结果时，请将模型放在针对该列表的 forEach 中，并从 forEachEnd 读取输出（连接方式参见参考文档的 forEach 部分）；只有当这些输入项要作为单个输出的联合参考时，才保留直接连接。在循环内部，当前输入项会作为仅含一项的列表传入数组字段。forEach 会为每个输入项运行一个计费的模型任务，但试运行只按一次迭代估价，不受列表长度影响（实测：一项或两项的报价相同，两项的实际费用是报价的两倍），因此向用户报价前，应将报价乘以输入项数量。

从其他节点工具迁移图

从 Weavy、ComfyUI 或其他节点编辑器导出的流水线无法直接导入：只有 Scenario 自身导出的文件支持往返导入。迁移时需要逐个翻译节点，然后按上述步骤创建、发布并试运行。映射表、成员解析方式以及用户会收到的报告见 references/foreign-graph-import.md；在处理此类导出文件前请先阅读，因为其中的第一条规则要求先在本地将文件整理成表格，而不是粘贴到对话中。

常见错误

• 将界面调色板中的名称当作节点类型：持久化类型使用参考文档中的 camelCase 词汇表，且每个生成器都是 type: "model"。
• 按生产者到消费者的方向连接边：持久化边的指向正好相反。
• 认为更新 editor_info 后，无需重新发布即可更改正在运行的应用。
• workflow_create 失败后，使用第二次创建操作重试，而不是对错误中提供的 id 执行 workflow_update。
• 将一批资源接入一个模型输入，并期望每项资源各自生成一个输出：这会对所有资源进行一次生成；请使用 forEach 循环。
• 发布时没有输出引脚，或在文本节点或资源节点上设置 data.isOutput：发布会失败，并提示 compiled to an empty flow。输出引脚应添加到生成交付内容的 model、llm 或 forEachEnd 节点上。输入引脚是可选的：内置提示词的图可以在没有输入的情况下发布和运行。
• 在构建器或模型前设置文本节点的门控：分支只会跳过连接到其句柄的节点，因此消费者会一直处于待处理状态，作业也永远无法完成。请对实际执行工作的节点设置门控，或根据参考文档的 ifElse 部分，使用 CEL 三元表达式处理条件提示词文本。
• 使用双引号括起 CEL 字面量：它们可以求值，但会破坏画布编辑器；只能使用单引号。
• 向 workflow_copy 传入 workflow_id：get、update、publish、run 和 delete 都使用 workflow_id，但 copy 使用 source_workflow_id；复制操作会原样继承所有内容，且需要单独发布。