Dify 工作流 DSL（自托管版）

一个面向 Dify 工作流 DSL 的综合能力模块：涵盖编写、编辑、调试、引用、模板及本地验证，全部集成于单一包中。

职责范围：工作流 DSL 本身、贴近导入/导出的变更操作、以及 YAML 格式验证。
不负责：App、Prompt、Dataset 或 Knowledge Base 的编排任务。此类需求请使用技能 ../dify/SKILL.md。

触发条件

在以下情况下使用本技能：

• 创建新的 Dify 工作流
• 编辑或调试现有工作流 DSL 文件
• 添加或移除节点（Node）、边（Edge）或分支（Branch）
• 在不同 Dify 实例之间迁移工作流
• 验证导入错误或可疑的 DSL 行为

作用域边界

请使用 本技能 处理以下任务：

• 编写或编辑工作流 DSL
• 修改节点/边结构
• 基于导入/导出的工作流迁移
• 对工作流文件进行 YAML 格式验证
• 排查导入失败或 Schema 不匹配问题

请使用 dify 处理以下任务：

• App 编排
• Prompt 和 Dataset 相关操作
• Knowledge Base 管理
• Management API 与 Console API 流程
• 面向运维的健康检查（Health-Checks）

专家领域

本技能长期目标是成为自托管 Dify 工作流领域的真正专家，覆盖如下核心方向：

• 节点类型（Node Types）、句柄（Handles）与变量语法（Variable Syntax）
• 导入（Import）、重新导入（Re-Import）及 Schema 常见陷阱
• 基于真实导出内容的最小化编辑（Minimal Edits）
• 对版本（Version）与插件（Plugin）敏感的工作流语义表达
• 在高风险覆盖操作前，提供安全的 Draft / Backup / Rollback 路径

快速分诊（Rapid Triage）

当用户提供或明确要求以下任一内容时，请**始终留在 dify-workflow 技能内处理**：

• 已导出的工作流 DSL 内容
• 新增或修改的节点（Nodes）、边（Edges）或分支（Branches）
• 导入错误或 Schema 错误
• 变量语法、句柄（Handles）、输出（Outputs）或节点依赖关系
• 针对同一目标实例成功重新导入所需的精确最小化编辑（Concrete Minimal Edits）

若问题可通过 App、Prompt 或 Dataset 操作解决，请**切勿停留于此技能**，应立即交还给 dify 技能处理。

App、Prompt 或 Dataset 类任务通常属于管理类操作（Management Operations），因此归属 dify，而非 dify-workflow。

运行原则

1. 先导出（Export first）：目标实例导出的内容始终是唯一可信来源。
2. 最小化编辑（Minimal edits）：仅执行必要且精准的变更，避免无依据的全量重写。
3. 版本感知（Version aware）：显式校验版本差异与插件兼容性。
4. 密钥不得嵌入内容（Secrets stay out of content）：禁止在 YAML、Prompt 或示例中硬编码 API Keys。
5. 导入前必验证（Validate before import）：先本地验证，再于同一目标实例执行导入。

推荐工作流

1. 从目标实例导出一个已知可用、功能正常的工作流。
2. 从中推导其结构、版本号及字段命名规范。
3. 仅将本技能提供的模板与参考文档作为辅助指引，而非绝对权威标准。
4. 优先采用最小化编辑方式调整 DSL，而非完全重构。
5. 完成编辑后，先本地验证，再于同一目标实例测试导入效果。

若无可用导出文件，请严格遵循以下流程：

1. 明确声明：“当前无导出文件”；
2. 不得暗示任何模板已具备生产就绪（production-ready）状态；
3. 必须将输出结果明确标记为 unverified draft（未经验证草稿）；
4. 清晰指出：该工作流在缺乏导出文件前提下无法直接导入；
5. 在执行任何高风险覆盖操作前，必须索取一份已有导出文件或其他可信赖备份，以支持回滚（Rollback）；
6. 一旦用户提出实际导入需求，须坚持要求其提供目标实例的导出文件。

关键规则

规则 1：先导出（Export First）

• 始终先从目标实例导出 工作流。
• 绝不假设 DSL 版本、节点 Schema、依赖格式或功能开关（feature flags）。
• 所有编辑均需保持最小化，并严格对齐导出文件的原始结构。

规则 2：变量语法必须精确

{{#NODE_ID.VARIABLE_NAME#}}

错误示例：

• {{NODE_ID.VARIABLE_NAME}}
• {{#NODE_ID.VARIABLE_NAME}}
• {{{#NODE_ID.VARIABLE_NAME#}}}

规则 3：Code Node 输出必须匹配声明

若 Code Node 返回 {"result": ...} 或其他字段，这些字段必须在 outputs Schema 中明确定义。

规则 4：密钥不得出现在 DSL 中

• 严禁在节点代码、Prompt 或导出的 YAML 中嵌入 API Keys。
• 应使用 Dify 环境变量，或通过服务端/实例配置注入密钥。

规则 5：验证变更路径，而非仅凭理论

每次完成关键编辑后，请执行以下步骤：

1. 运行本地 YAML 格式校验；
2. 对照修改后的结构，逐项检查受影响的 Outputs 与变量引用；
3. 如可行，建议或协助在相同目标实例上执行 Re-Import。

包内容概览

• references/：DSL 结构、节点类型、边规则与常见错误
• templates/：新建工作流的精简起点模板
• assets/：面向高频模式的完整示例工作流
• scripts/：用于生成 ID 及本地验证的辅助脚本

可用参考资料

• references/workflow_structure.md：DSL 全局结构说明
• references/node_types.md：节点类型及其适用场景
• references/edge_types.md：句柄（Handles）、边（Edges）与路由逻辑
• references/node_positioning.md：布局与节点定位规则
• references/variable-syntax.md：变量语法详解与典型错误
• references/common-gotchas.md：导入/节点/Schema 常见陷阱
• references/node-templates.md：关键节点的 YAML 模式片段
• references/current_patterns.md：当前主流 Chatflow / Workflow、Trigger 与错误处理路径模式
• references/advanced_patterns.md：面向生产的高级模式 —— Human Input、Loop、Iteration 与 Agent
• references/retrieval_patterns.md：Knowledge Retrieval、Aggregator、Question Classifier 与 Document Extractor 等工作流模式

上级主题与资料来源待办清单位于 ../../../research/。

模板与示例资产

• templates/minimal-workflow.yaml：最简启动模板
• templates/llm-chain-workflow.yaml：线性 LLM Chain 模板
• templates/http-llm-workflow.yaml：HTTP + LLM 混合流程模板
• assets/simple_llm_workflow.yml：简单流程示例
• assets/conditional_workflow.yml：IF/ELSE 条件路由示例
• assets/error_handling_workflow.yml：错误处理流程示例

本地脚本

• scripts/generate_id.py：生成唯一节点 ID
• scripts/validate_workflow.py：校验 YAML 结构与基础完整性

使用示例：

# 生成 5 个唯一 Node ID
python3 scripts/generate_id.py 5

# 本地验证指定工作流文件
python3 scripts/validate_workflow.py /absolute/path/to/workflow.yaml

安全注意事项

• 如有真实导出文件，切勿盲目信任模板。
• Provider 名称、插件名与字段名，务必与目标实例逐一核对。
• 遇到导入失败时，优先检查语法与依赖关系，而非立即重构整份 DSL。
• 在目标实例上成功完成导入前，任何工作流变更均不得视为已确认生效。
• 若无导出文件，则输出内容仅为 unverified draft，不可直接导入，直至目标实例提供匹配导出。

实用编辑检查清单

1. 是否已定义 Start / End 节点？
2. 所有 Node ID 是否唯一？
3. 所有 Edge 是否指向真实存在的节点？
4. sourceHandle 与 targetHandle 是否符合对应节点类型要求？
5. 变量语法是否完全准确？
6. Code Node 的实际返回字段是否与 outputs 声明一致？
7. Provider / 插件依赖及其版本是否适配目标实例？
8. 是否已在目标实例上完成导入测试？
9. 若无导出文件，是否已明确标注为 Draft？
10. 执行高风险替换前，是否存在可靠的 Backup 或 Rollback 路径？

导入错误分诊流程

若 Re-Import 失败，请按以下顺序排查：

1. 首先运行 validate_workflow.py 进行本地校验；
2. 检查 Node ID 与 Edge 引用是否有效；
3. 核对 sourceHandle 与 targetHandle 是否与所涉节点类型兼容；
4. 比对 Code Node 的 outputs 声明与其实际返回字段；
5. 重新审阅变量语法及由此衍生的所有引用；
6. 优先准备最小化修复方案，而非全量重写；
7. 仅在排除上述问题后，才考虑结构性缺陷或版本差异等深层原因。

推荐响应模式

当用户提出工作流变更请求时，请按此流程响应：

1. 主动询问是否已有导出文件或现有 DSL 文件；
2. 若目标实例或 Dify 版本不明确，需进一步澄清；
3. 优先建议最小化编辑方案，而非全量重写；
4. 针对具体细节，精准引导至相关模板、参考文档或校验器；
5. 最终以“在同一目标实例上执行 Re-Import 与 Smoke Check”收尾。

若判定请求实属误入本技能，请按如下方式移交至 dify：

这很可能并非 DSL 变更需求，而是涉及 App、Prompt 或 Dataset 的管理类操作。我将切换至 `dify` 技能，以便在不引入额外工作流复杂度的前提下，高效完成该管理任务。

有用参考资料

• Dify 官方文档：https://docs.dify.ai/
• GitHub 仓库：https://github.com/langgenius/dify
• 发布版本页：https://github.com/langgenius/dify/releases