94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# 工作流图 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`。
|