Workflow 参考

Workflow 参考页描述公开可配置面。它面向需要导入 JSON、让主聊天创建生产线，或排查运行状态的用户。

Definition 字段

字段	类型	默认值	说明
`name`	string	必填	Workflow 名称。
`description`	string	`""`	给用户和主脑看的用途说明。
`nodes`	array	必填	节点列表，至少 1 个节点。
`failure_policy`	string	`pause`	节点失败后的运行策略：`pause`、`fail_fast`、`continue`。
`auto_supervise`	boolean	`true`	运行时是否自动开启自主监督，并在收敛后关闭这次运行自己开启的监督。

生命周期字段不放进导入 spec：

字段	说明
`status`	`draft` 或 `published`。草稿不可运行。
`revision`	定义修订号。更新时可配合 `expected_revision` 做并发编辑保护。
`source` / `locked`	扩展包或内置来源可能锁定定义，通常需要复制后编辑。

Node 字段

字段	类型	默认值	说明
`id`	string	必填	节点唯一 ID。模板变量和依赖都会引用它。
`name`	string	必填	UI 展示名。
`profile_id`	string or null	`null`	要应用的 Agent Profile。
`prompt_template`	string	必填	节点启动 prompt，支持 Workflow 模板变量。
`runtime`	string	`auto`	UI 暴露 `auto`、`claude-code`、`codex`、`opencode`、`kimi-code`。
`cwd`	string or null	`null`	节点工作目录。为空时使用会话启动链路的默认目录或 Profile 默认目录。
`model`	string or null	`null`	节点级模型覆盖。为空时使用 Profile 或运行时默认。
`effort`	string or null	`null`	推理强度覆盖。UI 常用 `low`、`medium`、`high`、`xhigh`、`max`。
`permission_mode`	string or null	`null`	节点权限模式。为空时继承本次启动的 worker gear；显式值常用 `bounded` 和 `yolo`。
`skip_permissions`	boolean or null	`null`	是否跳过权限提示。为空时由 `permission_mode` 或启动链路默认值推导。
`isolate`	boolean or null	`null`	是否强制 worktree 隔离；`null` 表示跟随默认策略。
`depends_on`	string[]	`[]`	直接上游节点 ID。后端校验未知依赖、自依赖和环。
`output_schema`	object or null	`null`	handoff JSON schema 子集。为空时使用默认 schema。
`skills`	array	`[]`	节点补充 skills，会与 Profile skills 合并。当前 worker 注入只支持 local skills。
`requires_approval`	boolean	`false`	节点到达后是否等待人工批准再启动。
`reuse_session_of`	string or null	`null`	复用某个上游祖先节点的 worker 会话。目标必须是传递依赖祖先。

模板变量

变量	含义
`{{task}}`	启动 run 时输入的 `task_input`。
`{{upstream.<node_id>.summary}}`	直接上游节点 handoff 的 `summary` 字段。
`{{upstream.<node_id>.json}}`	直接上游节点 handoff 的完整 JSON 字符串。
`{{upstream.<node_id>.<field>}}`	直接上游节点 handoff 的顶层字段。
`{{upstream_summaries}}`	所有直接上游摘要的合并文本。

只有直接依赖的上游会被渲染。非直接依赖变量会保留为原始文本。

Handoff 与 `output_schema`

节点完成时必须输出结构化 handoff。默认 schema 是：

{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "artifacts": {
      "type": "array",
      "items": { "type": "string" }
    },
    "notes": { "type": "string" }
  },
  "required": ["summary"]
}

自定义 output_schema 支持 JSON Schema 子集：

关键字	支持情况
`type`	支持，根必须是 `object`。
`properties`	支持对象属性声明。
`required`	支持必填字段校验。
`items`	支持数组元素声明。
`enum`	支持枚举值。
`additionalProperties`	可作为注释使用，不要依赖它严格拦截额外字段。

如果 worker 汇报不符合 schema，Workflow 会要求节点修正 handoff；重复失败后节点会进入阻塞或失败路径。

失败策略

策略	行为
`pause`	默认。节点失败时暂停整条运行，等待你重试、跳过或取消。
`fail_fast`	节点失败后取消未启动节点，并让 run 进入失败。
`continue`	独立分支继续运行；最终如果存在失败节点，run 会以失败收敛。

运行状态

Run 状态：

状态	含义
`pending`	已创建，等待推进。
`running`	正在推进节点。
`paused`	已暂停，需要人工干预。
`succeeded`	所有节点成功。
`failed`	运行失败收敛。
`canceled`	人工取消。

Node 状态：

状态	含义
`pending`	等待依赖。
`ready`	依赖已满足，等待启动。
`waiting_approval`	已到达人工批准门。
`launching`	正在启动 worker。
`running`	worker 正在执行。
`blocked`	worker 主动阻塞或 handoff 修正失败。
`succeeded`	节点完成并产生有效 handoff。
`failed`	节点失败。
`canceled`	节点被取消。

运行控制动作

动作	用途
`list_definitions`	列出可运行 Workflow 定义。
`list_runs`	列出运行历史或活跃 run。
`inspect`	查看某个 run 的节点状态。
`start`	用 `definition_id` 和 `task_input` 启动 run。
`pause` / `resume`	暂停或恢复活跃 run。
`cancel`	取消活跃 run。
`approve_node`	放行 `waiting_approval` 节点。
`retry_node`	重试失败或取消的节点。
`skip_node`	跳过节点；可附 note 作为 handoff 摘要。
`stop_sessions`	run 终态后优雅退出这次运行创建的 worker 会话。

manage_workflow 只管理定义：list、read、create、update、publish、delete。启动和干预运行使用 pipeline_control。

限制

限制	默认值	说明
节点数上限	`200`	可由管理员通过 `JARVIS_PIPELINE_MAX_NODES` 调整。超过 64 节点会给出非阻断提示。
并发启动上限	`10`	可由管理员通过 `JARVIS_PIPELINE_MAX_PARALLEL` 调整。
`task_input` 长度	`20000` 字符	REST 启动 run 的输入限制。