DeepSeek Harness dsh workflow: canvas to YAML

A canvas makes a DSH plugin workflow easy to discuss, but the exported YAML is what a team can actually review, version and regenerate. The canvas, the YAML and the generated code are three representations with different jobs, and most workflow accidents begin when one of them pretends to be the source of truth. Treating YAML as the contract keeps the other two honest.

The canvas is a draft, not the dsh plugin workflow

The canvas answers how people think about a flow, not how a machine reproduces it.

Dragging nodes and connecting ports is the most direct way to arrange a workflow, because branches, dependencies and failure handling stay visible while the team argues. What the canvas saves is interface state, including node positions, zoom and collapsed panels, and that state is a poor long-term contract. Once the canvas is treated as the only artifact, changes become invisible, rollback becomes impossible and a new maintainer has to reconstruct intent from a picture. Validation before export catches some of this, since a referenced skill or tool may have been renamed while the connection still points at the old port.

The canvas also cannot promise that the flow will execute. It shows structure, while the nodes may reference tools that no longer exist or ports that were renamed in the plugin. Exporting to YAML is what turns the discussion into a file that can be compared across versions. A team rule that every change ends with an export is cheaper than later archaeology.

YAML is the dsh plugin workflow contract

YAML is not a backup of the canvas; it is the text that canvas, code and review all agree on.

A usable workflow file describes which nodes exist, how they connect and what parameters each one needs. Node identifiers should stay stable, port names should be readable and parameters should reference configuration rather than hard-code secrets. When those rules hold, both a person and a generator can read the file without guessing.

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

In this sample, nodes describe actions, needs and edges describe order and branching, and the version field tells later tools how to interpret the whole file. Most DSH plugins that export a workflow use a restrained representation for this reason, because a stable middle layer survives changes of runtime better than a direct dump of UI state. Renaming a field is therefore a contract change rather than a cosmetic edit, and the generator and review script must move together. Execution details such as retry policy belong in node parameters where possible, while their implementation belongs in code.

Generated code is execution, not a dsh plugin design

A generator translates structure into code; it does not decide what the business means.

Turning YAML into Python or workflow.mjs is a deterministic translation: nodes become calls, connections become control flow and parameters become arguments. When the mapping rules are stable, the same YAML produces the same code, and any difference can be explained by a change in the graph. That property is what makes generated output reviewable instead of magical.

Error handling is where generated code usually needs the most attention, because one retry line in YAML can become a nest of exception handling in the target language. Branch conditions have the same problem, since a single drawn edge may expand into several runtime checks. Whether generated files are committed depends on the team, but either choice requires an explicit statement that YAML is the source of truth. The generator also knows nothing about duplicate charges or partial writes, so those judgments stay with the person who wrote the flow.

Hand-written YAML for a DeepSeek Harness plugin workflow

Hand-writing works for small flows and batch generation, provided the schema and version are respected.

Some teams never open the canvas and instead produce files from scripts or migrate an older system. A DeepSeek Harness plugin workflow that starts as text is not inferior, but it demands clear knowledge of supported fields and version rules. Starting with one node and one connection is safer than writing fifty lines before the first import, because errors are easier to localize.

1. Confirm the YAML version and fields supported by the installed plugin before copying older examples.
2. Write one node, one connection and one output, then import to confirm the structure is recognized.
3. Add parameters and constraints one node at a time, keeping each diff readable.
4. Keep comments in the file that explain each node's purpose and owner.
5. Import and re-export once, then compare the two YAML files for equivalence.

Import errors usually name a line and a field, so reading the message fully is faster than guessing at indentation. Common causes include a wrong nesting level, a misspelled port and a reference to a node that does not exist. Format drift is the quieter cost, since different editors produce different indentation and field order, and a formatter or validation script in the repository removes that noise before review.

Version control makes a dsh plugin workflow debuggable

A flow that can be diffed is the only kind that can be rolled back with confidence.

Review should focus on structure rather than line counts: nodes added or removed, connections changed and parameters adjusted. Formatting-only changes should be handled by a formatter so they do not hide the real edit. Small commits that touch one node or one connection are easier to reason about than a single commit containing several unrelated changes.

Compatibility deserves advance planning, because a plugin upgrade can change what a field means and an old file may no longer import. Keeping the previous YAML and its generated code gives a way back, and migration belongs on a branch rather than on the main line. An explicit schema version lets the importer and generator choose the right rule set instead of guessing. The DSH Plugin Hub entry is the place to check which version a listing expects, and the division of labor stays simple: the canvas is for discussion, YAML is for review and code is for execution.

Sources: dsh-workflow-designer plugin entry, your first plugin, plugins and lifecycle.