校验一份图定义(零成本)。传 yaml 全文,或已保存的 workflow_id。

检查:YAML 语法、节点类型封闭清单、边引用、条件边与路由字段、入口、 可达性、死环、有环必须设 max_iterations、consumes 引用、异质性提示。 返回 JSON；校验不过时 error 会指出具体字段或图结构问题，并统一附带 YAML path、line、column（整图聚合错误没有唯一坐标时只返回 path）。 按 workflow_id 校验时额外回显 yaml 原文与 file_sha256——修改已有图的 读-改-写闭环:改 yaml 内容后带 file_sha256 作为 expected_sha256 调 atlas_save_workflow。两个参数都传时以 yaml 全文为准。

把校验通过的 YAML 保存为 workflows/.yaml(零成本)。

校验不过不保存。新建要求 id 未被占用;更新必须传 expected_sha256 (上次读到的文件哈希)——文件被改过就拒绝,防静默覆盖。 返回 file_sha256(下次更新用它)与 spec_fingerprint。

运行工作流。同步阻塞到结束。

workflow_id 与 yaml 二选一(都传时以 yaml 为准):

• workflow_id:运行已保存的 workflows/.yaml;

• yaml:运行即时编写的自定义图全文,不落盘、不写 workflows/。 persist_as(可选):真实运行结束后,把 yaml 固化为 workflows/.yaml——新建要求 id 未被占用,更新需 expected_sha256 语义与 atlas_save_workflow 相同;dry_run 不固化。

attachments(可选,E-2A):运行附件 [{name, path}];path 是发起 机器本机绝对路径,启动前整读校验(单件 ≤16MiB/合计 ≤32MiB,名字 全小写且不得撞保留名/节点 id),内容字节克隆进 run 产物库后与原 文件再无关联。下游节点用 consumes 引用 name;投影只含摘要行, 原字节经界面产物工作台查看。响应不含原始路径。

node_overrides 是封闭的本次运行节点参数覆盖；不改 YAML，不接受权限或拓扑字段。 可覆盖:model/fallback/thinking/max_output_tokens/temperature/seed/ timeout_s/retry/prompt(llm)、max_turns/timeout_s/retry/prompt/workdir (coding_agent;research 无 workdir)、prompt(human)。 prompt 是完整替换本次运行的节点职责文本,不是追加; consumes/outputs/图结构永远不可覆盖——要长期生效就用 persist_as 固化 或调用 atlas_save_workflow。 dry_run=True 与真跑使用同一有效规格，只渲染、不花钱； 默认同步阻塞到结束(wait=true);wait=false 见下。dry_run=False 真实调用模型。暂停在 human 节点时返回 paused。 wait(默认 true)同步阻塞到结束;wait=false 通过全部预检与执行身份 断言后立即返回 run_id(status=starting),长任务不再占住会话—— 用 atlas_get_run 轮询、atlas_list_runs 列表。wait=false 与 persist_as 互斥(固化需要等真跑结束)。

列出运行(零成本,P4)。按 run_id 降序稳定分页。

每条含 run_id/graph/status/nodes_done/started;状态为 running/interrupted/paused/done/failed/cancelled(interrupted 由 账本+运行锁动态判定)。starting 只在账本落账前的短暂窗口由 Web 单 run 查询 合成,不出现在本列表。cursor 传上一页返回的 next_cursor 续页。

列出 workflows/ 里的图定义与校验状态(零成本)。

请求取消一个运行(P2,零成本)。

done/failed/cancelled 返回冲突;running 写请求后 controller 在 下一节点边界终止(在途模型调用只能等它返回或超时,不宣称强杀); paused/interrupted 在锁内直接落 run_cancelled 终态。幂等。

查某次运行的动态状态、每节点模型与 token、账本路径(零成本)。

仅恢复动态判定为 interrupted 的运行；paused 必须在 Web 审批。