# 工作流图 Schema v1.0（冻结）

> 阶段 0 交付。实现源：`packages/harness/deerflow/workflows/schemas.py`  
> 样例：`packages/harness/deerflow/workflows/samples/`  
> ADR：[`adr/0001-workflow-studio-runtime.md`](adr/0001-workflow-studio-runtime.md)

## 原则

- Coze 画布 DTO **进入 Gateway 后**转换成此内部结构；运行时不依赖 Coze 私有字段。
- Wire JSON 使用 **camelCase**；Python 模型使用 snake_case（`populate_by_name=True`）。
- `schemaVersion` 固定为 `"1.0"`；破坏性变更必须升版本并双写迁移说明。

## 顶层 `WorkflowGraph`

| 字段 | 类型 | 说明 |
|------|------|------|
| `schemaVersion` | `"1.0"` | 协议版本 |
| `id` | string | 工作流逻辑 id（定义侧稳定标识） |
| `name` / `description` | string | 展示用 |
| `inputSchema` / `outputSchema` | JSON Schema object | 开始/输出校验 |
| `nodes` | `WorkflowNode[]` | 节点列表，`id` 唯一 |
| `edges` | `WorkflowEdge[]` | 边列表，`id` 唯一；`source`/`target` 必须引用已有节点 |
| `settings` | object | 见下 |

### `settings`

| 字段 | 默认 | 说明 |
|------|------|------|
| `runTimeoutSeconds` | 1800 | 整 run 超时 |
| `nodeTimeoutSeconds` | 300 | 单节点默认超时 |
| `maxSteps` | 200 | 最大节点步数 |
| `maxLoopIterations` | 5 | 全局循环上限 |
| `maxParallelism` | 4 | 同层并行度 |

发布时仍受系统级配额覆盖（阶段 6）。

## 节点类型（封闭集合）

`start` · `output` · `agent` · `skill` · `http` · `sql_read` · `code` · `transform` · `condition` · `merge` · `human_input` · `subworkflow` · `loop`

每类最小样例见 `workflows/samples/nodes/<type>.json`。

## `NodeResult`（统一节点结果）

```json
{
  "data": {},
  "messages": [],
  "artifacts": [
    {
      "artifactId": "artifact_01",
      "name": "专题报告.md",
      "mimeType": "text/markdown",
      "path": "/mnt/data/专题报告.md"
    }
  ],
  "metadata": {},
  "warnings": []
}
```

大文本 / 二进制 / 超大查询结果写入 artifact，事件与 `output_json` 只传引用与有界预览。

## 运行状态

`queued` → `running` → `awaiting_input` | `completed` | `failed` | `cancel_requested` → `cancelled`

终态：`completed` / `failed` / `cancelled`。

## 安全表达式（约定，求值器阶段 2+）

允许只读引用：

- `{{ inputs.<field> }}`
- `{{ nodes.<nodeId>.data... }}`
- `{{ run.id }}`

禁止：`eval`、任意属性反射、字符串拼接构造 SQL/HTTP。条件节点运算符白名单：相等、包含、数值比较、空值、布尔组合。

## `graph_hash`

对规范化 camelCase JSON（`model_dump_json(by_alias=True, exclude_none=True)`）做 SHA-256。发布版本写入 `workflow_versions.graph_hash`；编译缓存可按 hash 做有界缓存，缓存对象不得含用户密钥。

## 样例图

| 文件 | 用途 |
|------|------|
| `samples/report_generation.json` | 专题报告端到端验收基线 |
| `samples/start_output.json` | 最小 start→output（运行骨架） |
| `samples/nodes/*.json` | 各节点最小 config |
| `samples/event_envelope_example.json` | SSE envelope 契约样例 |

加载：`from deerflow.workflows.samples import load_sample_graph`。