scenario-workflows

场景工作流

概述

场景工作流是一个已保存的节点图，可将多个模型串联起来并在一次调用中运行；用户说“应用”时，指的是状态为 ready 的工作流。workflow_run 会返回一个任务，其跟踪方式与其他生成任务相同。

默认仅列出 workflows_list、workflow_get 和 workflow_run；批准和拒绝操作通过 scenario_tools_search 及其执行器通道运行。连接和核心循环请参阅 scenario 技能。创建、编辑和发布节点图请参阅 scenario-workflow-authoring 技能。如果这里提到的某个关联技能不在你可用的技能中，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具架构继续操作，并标明这一缺失。

快速参考

步骤	调用	说明
1. 列出	workflows_list status="ready"	始终限制 limit
2. 查看契约	列出 inputs[]，获取 workflow.inputs_definition	name 是运行键
3. 估价并验证	使用 dry_run=true 调用 workflow_run	返回费用，不创建任务
4. 运行	使用 inputs 调用 workflow_run	返回一个任务
5. 等待	jobs_wait	使用 pending_job_ids 再次调用

ID 以 wflow_ 为前缀；请从 workflows_list 或 search 中复制，切勿自行构造。要查找指定名称的应用或公开模板，请调用 search，设置 target="workflows"、关键词 query、limit=3 和相应范围；要搜索公开目录，请添加 public=true。工作流支持关键词文本和筛选条件，不支持图像或语义搜索。要查找可用应用，请添加原始筛选条件：filter: 'status = "ready"'（不是 filters.status）。从 workflows 中读取搜索结果，然后对选定的 ID 调用 workflow_get，并从 workflow.inputs_definition 中读取契约：搜索摘要不包含运行输入或可编辑节点图。搜索使用 offset，而不是 page_token；如果空页中有 _hint，请遵循提示，不要重复相同的搜索。

限制每次列表调用的数量

每条记录都包含编译后的 flow 和完整的 editorInfo 节点图，而工具没有精简选项：在实时记录中，这两个字段占了 3/4 的字节数，记录长度约为 1,900 到 22,000 个字符；即使草稿的 flow: []，仍会包含 editorInfo。将 limit 限制为 3 或更少，仅读取 id、name、hasFlow 和 inputs；翻页时，将 page_token 设置为上一条回复的 nextPaginationToken，最后一页则不设置。创作时，工具架构标明的上限为 200，但 API 会对任何超过 100 的值返回 400 错误，并注明 pageSize 和范围 [1; 100]，因此不要传入架构所列的最大值。

只有 draft 和 ready 会在服务器端筛选；其他状态会在客户端逐页筛选（标记为 _workflowListStatusFilter）；这种情况下，即使当前页为空，只要存在 nextPaginationToken，就应继续翻页。

输入约定

workflow_run 的 inputs 对象以记录中原样提供的 inputs[].name 为键。每个名称都是其对应节点的 ID，因此名称可能是按位置命名的（text2、text3），既不连续，也不按顺序排列。

• label 和 description 表达的是用户意图，而不是键名。
• 切勿从 editorInfo.nodes[].data.name 提取键名；节点名称可能已过时。
• required 是一个对象：应检查 required.always === true；如果只检查真值，{"always": false} 也会被视为必填。
• 输入有类型之分：string、file、file_array、string_array 等。file 接收资源 ID（需先上传）。类型必须匹配：API 会静默丢弃标量与数组之间类型不匹配的值，但仍会收费；workflow_run 会将简单标量封装为数组，但仅限简单类型。
• inputs[] 并非完整约定：字符串输入会继承其对应节点的长度上限（模型自身的提示词上限，观测到最低为 4000 个字符）。记录中不会列出此上限，而且只会在运行时出现错误 400，错误会指出上限，但不会指出输入键。dry run 会以零成本执行同一个验证器：长文本应通过 dry_run=true 测试并缩短至符合限制，而不是原样重试；如果有多个字符串输入，则可通过 dry run 二分定位出问题的输入。
• workflow_get 会将 inputs_definition/editor_info 包装在 workflow 中；workflows_list 会将 inputs/editorInfo 包装在 workflows 中。

示例：运行已保存的应用

1. 使用 workflows_list，设置 status="ready"、limit=3，并提供 team_id 和 project_id。读取每条记录中的 id、name 和 inputs；忽略 flow 和 editorInfo。
2. 对于 inputs[] 条目 {"name": "text1", "required": {"always": false}}，使用 {"text1": "..."} 运行。
3. 调用 workflow_run，提供 workflow_id、dry_run=true 和完整的 inputs 对象。回复会包含 creativeUnitsCost、creativeUnitsDiscount 和一个空的 job；应先向用户说明费用。此操作也会运行真正的验证器。
4. 不带 dry_run 重复调用，然后对返回的 job 使用 jobs_wait；job 运行期间，需使用 pending_job_ids 重新调用。
5. 对每个输出资源分别调用一次 asset_display，每次提供一个 ID。

常见错误

• 根据标签或节点图猜测输入键，而不是读取 inputs[]。
• 跳过 dry run：三个 ready 工作流中有两个未通过验证，且错误中给出了正确的输入名称；应报告该错误，而不是负载。
• 从父 job 读取费用或归因信息：已完成的工作流 job 的 cuCost: 0，并且只会列出 assetIds，不提供逐模型归因。每个节点都会作为独立的子 job 运行并产生实际的 cuCost（这些费用总和等于 dry-run 报价，但在 forEach 循环中，dry run 只计算一次迭代）；对工作流 job 使用 job_get verbose=true，会返回 metadata.flow，其中将每个节点映射到其子 job 的 jobId、modelId 和输出资源 ID。
• 将批次发送到 file_array 输入，并期待每个项目各自生成一个输出：应用是否循环取决于其节点图，而不是输入。检查 editorInfo 中模型节点前是否有 forEach 节点（编译后的 flow 中为 for-each；workflows_list 记录会同时包含两者，workflow_get 也会提供）；如果没有，应用会根据所有项目生成一次结果，因此应对每个项目分别调用 workflow_run（各自执行 dry run 并创建 job）。循环应用的 dry run 只计算一次迭代，因此应将报价乘以项目数量。
• 运行草稿：即使 inputs 看起来完整，flow: [] 且 hasFlow: false 也表示草稿。发布方式：参见 scenario-workflow-authoring。
• 调用 workflow_approve 或 workflow_reject 时未提供 workflow_id、workflow_job_id 和 node_id 这三项：审批门槛针对单个节点；暂停的运行不会自行完成。使用 jobs_list 查找运行，再通过 job_get verbose=true 读取（简要回复会省略 metadata）：metadata.flow 列出每个节点的状态；待审批节点的 ID 是 node_id，job 的 ID 是 workflow_job_id，其 workflowId 即 workflow_id。拒绝会取消此次运行。