Preface¶

When allowing agents to execute multi-step tasks within DeepSeek Harness (DSH), workflows are often scattered across conversation logs or miscellaneous files: step boundaries are unclear, branch conditions are difficult to verify, and modifying one part requires checking multiple Markdown files. Plain text allows for version control but lacks intuitive topological relationships, while a pure canvas can easily become disconnected from the source files.

DeepSeek Flow (kanghelyu/dsh-deepseek-flow) is a visual, Markdown-first workflow editor designed for the DSH Web UI. It uses WORKFLOW.md and per-step STEP.md files as the single source of truth, providing an editable flowchart within the Harness and bidirectional synchronization with Markdown. The plugin intentionally serves only as an editor, not a workflow runtime; designing, inspecting, and refining processes happens in the Studio, while actual execution remains the responsibility of the current Session’s agent.

What This Is¶

DeepSeek Flow is maintained by kanghelyu, licensed under MIT, with the npm package name deepseek-flow and the current version 0.4.2. The project has approximately 50 stars and 4 forks on GitHub. Official site: deepseekflow.kanghelyu.org.

In one sentence: It converts WORKFLOW.md and step-level STEP.md into an editable flowchart within the Harness; built-in Skills allow the current session to create and maintain workflows via tools, with the canvas synchronized and portable alongside Markdown.

Core Features¶

Summarized below based on verified capabilities from the README and package.json.

Markdown as Source, Canvas as Editor¶

• Main document WORKFLOW.md, with each step in its own directory containing a STEP.md.
• Create, move, connect, reconnect, annotate, and delete nodes and arrows on the canvas.
• Bidirectional synchronization between the canvas and Markdown editor; changes are written back to the workflow files.

Typical directory structure:

my-workflow/
├── WORKFLOW.md
├── 01-input/
│   └── STEP.md
├── 02-research/
│   └── STEP.md
├── 03-quality-check/
│   └── STEP.md
└── 04-output/
    └── STEP.md

Topology Changes and Review Semantics¶

• When a human modifies topology on the canvas: the graph structure is validated, then the current session agent reviews it, and a new version is atomically saved.
• When an agent directly modifies files to drive topology: a deterministic finalize path can be taken to avoid repeated reviews in the same session; the agent should call flow_finalize_canvas, and if it doesn’t, the Studio will detect the absence of canvas edit events and automatically execute an equivalent finalize.

Executable Gate Semantics and Agent Tools¶

The exported contracts include formulas, operands, predicates, and deterministic boolean results, allowing gate logic to be evaluated without running agent steps. The plugin includes agent Skills, with documentation covering each workflow tool and examples of executable IF/ELSE and boolean gates.

Session Isolation, Navigation, and Persistence¶

• Each Harness session maintains an independent workflow with optional shared templates; the toolbar allows deletion of the current workflow or shared templates (requires confirmation, and managed workspaces move to the recycle bin for recovery).
• The sidebar is collapsible and resizable; supports panning, zooming, fit-to-view, and node focus animations; large graph drags are committed upon pointer release, with lightweight revisions polled in the background.
• The interface follows the Harness light/dark theme and WebUI language.
• Logic validation results, AI proposals, and unapplied canvas drafts are persisted to disk; switching documents, sessions, or restarting dsh web does not lose them, and they are only cleared upon explicit discard or successful commit.
• Unchanged documents are not rewritten; background polling can be canceled; sub-agents default to a 10-minute timeout.

Manual and Background AI Assistance¶

You can trigger logic validation, single-document optimization (with review), or full workflow optimization from the interface. Switching documents, views, or sessions does not interrupt accepted background tasks; returning to them resumes document proposals.

Installation and Enabling¶

The plugin is installed from GitHub via DSH’s Web profile. After installation, restart dsh web and select the DeepSeek Flow tab within the session.

dsh plugin --profile web add "github:kanghelyu/dsh-deepseek-flow#main"

Confirm the plugin is mounted:

dsh web --dump-config | grep deepseek-flow

Note: The DSH ecosystem follows the “everything is a plugin” principle; the SkillHub directory page is a community site with no official affiliation with DeepSeek or High-Flyer. Before installation, please review the source code and MIT license yourself; the plugin runs with the same file and network access permissions as the current dsh process.

Typical Usage¶

Your First Workflow¶

1. In the session, ask the agent to build a workflow or import a workflow; the built-in deepseek-flow Skill will guide the use of flow_create or flow_put.
2. Open DeepSeek Flow, and the plugin will scaffold the main document, step documents, and visual layout.
3. Have the session agent modify workflow files, or directly edit Markdown in the Studio by selecting documents.
4. Topology updates driven by the session/files are completed via the finalize path, requiring no further main session review.
5. If adding, removing, modifying, or connecting nodes on the canvas, click Apply changes: validation → agent review → re-validation → atomic save.
6. When execution is needed, return to the session and have the agent run the workflow.

Cross-Session and Active Workflows¶

The Studio toolbar dropdown groups by source: current session, other sessions, and shared templates. When switching to a workflow from another session, it imports a copy of that workspace’s documents into the current session (external custom docRoots are referenced, not copied); switching to shared templates also copies them into the current session’s managed space to avoid polluting the shared originals. Each session persists activeFlowId in sessions/<id>.json, and reopening the Studio automatically selects the last workflow.

Use Cases and Considerations¶

Who is it for?

• Developers who need to design, review, and iterate on multi-step agent workflows within DSH, desiring Markdown that is version-controllable and portable.
• Teams that need to visually verify branches and boolean gate logic without tying the execution engine to the editor.
• Scenarios where agents have built processes through conversation, but unified maintenance via canvas and file bidirectional editing is desired.

Important notes

• This is an editor, not a runtime; execution still occurs in the current session.
• Human changes to canvas topology trigger agent review; file changes should be paired with flow_finalize_canvas or rely on Studio’s automatic finalize.
• Installing the plugin grants it the same file and network access capabilities as dsh; install from a trusted source and review the source code.

Summary¶

DeepSeek Flow binds WORKFLOW.md / STEP.md with an editable flowchart within the Harness: Markdown for portability, canvas for intuitiveness, clear review or finalize paths for topology changes, and comprehensive agent tools and Skills. If you are already using the DSH Web UI to orchestrate multi-step tasks, you can view documentation and examples from the directory page or GitHub, install via the official command, and create your first workflow in a session.

• Directory page: https://www.skillhub.cn/plugins/kanghelyu/dsh-deepseek-flow
• GitHub: https://github.com/kanghelyu/dsh-deepseek-flow