dsh workflow 怎么从画布落到代码：DeepSeek Harness 的 YAML 导出与版本管理

画布上连好的流程，只有落成一份可评审的 YAML，才算真正属于团队；DeepSeek Harness 的 dsh workflow 导出做的正是这件事。 画布、YAML 与生成代码各管一段，谁越界，哪一层就会变成不可信的副本。

画布负责设计：DSH插件里它只是草稿

画布解决的是人怎么想，不解决机器怎么复现。

在工作流设计器里拖节点、连端口，是最直观的编排方式。画布把分支、依赖和失败处理摆在眼前，讨论成本比读一段提示词低得多。但它保存的是界面状态，节点位置、缩放和折叠方式都会变，很难作为长期契约。

把画布当唯一产物，团队很快会遇到三个问题：改了什么看不出来，出了问题退不回去，换个人接手只能从头理解。这些问题不是画布做得不好，而是它本来就不承担版本管理的职责。指望它同时做设计和记录，最后两边都做不扎实。

画布的另一个边界是执行。它展示的是结构，不保证节点参数真的能跑通。节点引用的 Skill 或 Tool 可能已经改名，连接也可能指向不存在的端口。导出之前先在画布上跑一次校验，能挡掉一部分低级错误。

所以画布适合作为讨论和试排的地方，导出 YAML 之后就应该以文件为准。团队里如果有人继续在画布上改而不导出，差异会悄悄积累，最终没人说得清线上跑的是哪一版。把「改完必须导出」写进协作约定，比事后追查省事得多。

YAML 是契约：DeepSeek Harness 工作流的稳定描述

YAML 不是画布的备份，而是画布、代码与评审共同承认的那份文本。

一份合格的工作流 YAML 至少要表达三件事：有哪些节点、节点之间怎么连、每个节点需要什么参数。节点 id 要稳定，端口名要能读懂，参数尽量用引用而不是硬编码。做到这几点，文件才能被人评审，也才能被工具稳定生成代码。

下面是一段最小但完整的示例，结构比字段数量更重要。它没有覆盖所有字段，但足以说明节点、参数和连接是怎么落到文本里的。读的时候重点看 id、needs 和 edges 三处。

workflow: customer-triage
version: 1
nodes:
  - id: fetch_ticket
    type: tool
    tool: http.get
    with:
      url: "${TICKET_API}/latest"
  - id: classify
    type: skill
    skill: ticket-classifier
    needs: [fetch_ticket]
edges:
  - from: classify.ok
    to: notify_support

这段 YAML 里，nodes 描述动作，needs 与 edges 描述顺序和分支，version 则决定了后续工具如何解释整份文件。字段名看起来琐碎，实际是契约的一部分，随意改名等于单方面毁约。生成器和评审脚本都依赖这些约定，改动必须同步。

YAML 也不该承载执行细节。超时重试这类策略可以写在节点参数里，但具体实现应留给代码层。中间表示越克制，迁移到另一种运行时就越容易，团队也不必为每一种执行器维护一套平行格式。

生成代码的边界：DeepSeek插件只保证结构可执行

生成器负责把结构翻译成代码，不负责替你想清楚业务。

从 YAML 生成 Python 或 workflow.mjs，本质是一次确定性的翻译。节点变成函数调用，连接变成控制流，参数变成实参。只要映射规则稳定，同一份 YAML 每次生成的代码就应该一致，差异也应当能用节点变化解释。

生成代码最容易出问题的地方是错误处理。YAML 里一行「失败后重试」，落到代码里可能是一段复杂的异常捕获，评审时必须逐行看。分支条件同样如此，画布上一条线，在代码里可能对应多个判断。

生成物是否需要入库，取决于团队习惯。入库便于 diff 和回滚，但容易与源 YAML 脱节；不入库则要求每次构建都能重现生成结果。无论选哪种，都要明确唯一事实来源是 YAML，而不是生成出来的文件。

还有一层边界常被忽略：生成器不认识业务语义。它不知道某个节点失败意味着什么，也不知道重试会不会造成重复扣款。这些判断必须由写 YAML 的人负责，生成器只保证结构没写错。

手写 YAML 与导入：dsh plugin 没有画布时怎么办

手写适合小流程和批量生成，但前提是先接受字段规范的约束。

有些团队根本不用画布，流程由脚本批量产出，或者从旧系统迁移过来。这时 YAML 就是第一手输入，导入器负责把它还原成可视结构。手写并不低级，但它要求作者对字段和版本非常清楚。

一个稳妥的做法是从最小流程开始，跑通后再逐步加节点。每加一个节点就导入一次，确认画布能正确识别。不要一次写完几十行再导入，报错时很难定位是哪一段出的问题。

1. 先确认插件当前支持的 YAML 版本与字段，不要照抄旧文档。
2. 写一个节点、一条连接和一个输出，导入确认结构可识别。
3. 补齐参数与约束，每次只增加一个节点。
4. 在文件里保留注释，说明每个节点的用途与负责人。
5. 导入后重新导出一次，对比两份 YAML 是否等价。

导入器报错时，先看它指出的行号，再对照字段规范。常见问题是缩进层级不对、端口名拼错、引用了不存在的节点。把错误信息完整读完，通常比反复猜测快得多。

手写还有一个隐性成本：格式漂移。不同人用不同的缩进和字段顺序，diff 会变得难以阅读。提交前统一格式化，或者在仓库里放一个校验脚本，能显著降低评审负担。

版本管理：让 DeepSeek Harness 的 YAML 像代码一样 diff

能 diff 的流程才有资格谈回滚。

把 YAML 放进 Git 之后，评审的重点应该从行数转向结构。节点增删、连接变化、参数调整，这三类改动决定了行为差异。纯格式变动应该被格式化工具消掉，而不是混进提交里干扰判断。

提交粒度也很关键。一次只改一个节点或一条连接，出问题时容易定位。把多个不相关的改动塞进同一个提交，回滚时就会连带撤掉不想动的部分。提交说明写清楚改了什么、为什么改，比事后补文档有用。

版本兼容要提前考虑。插件升级可能改变字段含义，旧 YAML 未必能直接导入。保留旧版本文件和对应的生成代码，才能在不兼容时快速退回。迁移应该发生在分支上，而不是直接覆盖主线。

如果团队同时维护多套流程，可以给 YAML 加一个显式的 schema 版本号。这样导入器和生成器都能判断该用哪套规则，避免靠猜。代价是每次升级都要多一步迁移，收益是问题能被早点发现。

三者越界之后：DSH插件工作流最常见的契约破坏

大部分工作流事故不是节点写错，而是某一层偷偷成了事实来源。

只保存画布不导出 YAML，等于把设计锁在一个打不开 diff 的文件里。反过来，只改生成代码不回头改 YAML，下一次生成就会把手工修改全部覆盖。两种做法都会让唯一事实来源变得模糊。

还有一种破坏更隐蔽：YAML 与代码同时被改，但没人核对两者的对应关系。表面上测试通过，实际行为已经和设计不一致。定期重新生成并对比差异，是发现这类问题最直接的办法。

把这些边界写进团队约定，比依赖个人记性可靠。画布用来讨论，YAML 用来评审，代码用来执行，三者各归其位，工作流才能在几个月后仍然被理解。需要对照插件说明时，可以从 DSH Plugin Hub 进入条目查看版本信息。

来源：dsh-workflow-designer 插件条目、开发第一个插件、插件与生命周期。