一句话定位

DeepSeek Flow 是 DeepSeek Harness Web 端的可视化工作流编辑器，把一份 WORKFLOW.md 与每步独立的 STEP.md 文件变成可编辑的流程图，画布与 Markdown 双向同步。插件只做编辑、保存与确定性布尔门求值，不运行 Agent 步骤，真实执行仍在当前 Session 内完成。

核心能力

• 把 WORKFLOW.md 总控文档和每步的 STEP.md 工作区渲染成可编辑的可视化流程图
• 在画布与 Markdown 之间双向同步，新增、移动、连接、删除节点或箭头都会写回工作流文件
• 提供八类逻辑门（IF/ELSE、AND、OR、NOT、NAND、NOR、XOR、XNOR）与确定性布尔求值，结果不依赖运行 Agent
• 通过 flow_create / flow_put / flow_list / flow_read / flow_evaluate / flow_finalize_canvas / flow_delete 等 Agent 工具创建、导入、读取、删除工作流
• 按 Session 隔离工作流，跨 Session 切换会复制为当前 Session 的独立副本；支持共享模板
• 手动触发逻辑校验、单文档 AI 优化与整工作流 AI 优化，结果和未应用草稿落盘保存，切视图或重启不丢

技术实现

• 语言: JavaScript（ES Module，TypeScript 风格），客户端使用 React 18 + 原生 SVG 画布
• 关键依赖: @deepseek-ai/dsh-typert-protocol、@deepseek-ai/dsh-tools（peer）、zod；开发态依赖 @deepseek-ai/cordis 与若干 @deepseek-ai/dsh-* 内部包
• 架构模式: Host/Client 分离；Host 在 apply(ctx, config) 中注册 Remote 服务 dflow/* 与 Cordis 工具，Client 注入 conversation.view slot 渲染编辑器；包内附带 SKILL.md，运行时响应式注册 Skill
• 入口文件: Host 入口 lib/index.js，Client 入口 src/client/entry.js（构建后产物为 lib/client.js），调度入口 cordis.patch.yml

适用场景

当用户希望把多步骤任务（例如「找论文 → 读论文 → 出综述 → 名词解释」）以可视化流程图的方式整理出来，并在 Harness Session 内由 Agent 按节点逐步执行时使用本插件。它也适合需要把已有 Markdown 工作流结构化、加入分支条件或有限重试、并由 Agent 在画布和文档之间双向维护的场景。

前置依赖与兼容性

安装方式

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

配置项

本插件通过 cordis.patch.yml 暴露的注入配置包含以下字段；说明列写人话：

常见问题

Q: 这个插件是工作流运行器吗？

A: 不是。DeepSeek Flow 只负责编辑、保存与确定性布尔门求值；Agent 步骤与完整工作流的真实执行仍在当前 Harness Session 内由 Agent 完成。

Q: 安装后看不到 DeepSeek Flow 标签怎么办？

A: 先用 dsh web --dump-config | grep deepseek-flow 确认插件已挂载。若已经挂载但下拉为空，需要完全停止再重启 dsh web（仅刷新浏览器不够，因为 Typert 路由表在进程启动时快照）。

Q: AI 整工作流优化写不进去是什么原因？

A: 通常是 Agent 工作期间原文发生了变化，或 Agent 没有返回全部必需文档。优化器会基于原始 revision 比对，发现原文变化就拒绝覆盖；请让 Agent 基于最新文件重新生成。

Q: 删除的工作流能找回吗？

A: 可以。插件托管的工作区会被移到 ~/.dsh/deepseek-flow/trash/<日期>/ 目录，把整个工作区目录复制回 workspaces/ 即可恢复文档；flow 定义本身可用导出的 JSON 通过 flow_put 重新导入。

Q: 条件框为什么必须用 truthy/falsy/nonEmpty 而不能写自然语言？

A: 逻辑门只做确定性布尔运算，不理解语义。要做语义判断，应在条件框上游加一个 Agent 步骤，让它输出 JSON 布尔值 true 或 false，再连到 predicate: "truthy" 的条件框。

Q: 什么是有限反馈边？什么时候用它？

A: 反馈边是带 maxIterations（1–1000 的正整数）和非空 exitCondition 的回退箭头，用来表达有限重试；它不参与单次布尔门求值，也不会自动执行步骤。普通执行箭头必须无环，要做重试只能画反馈边。

Q: 直接编辑文件后 Studio 一直显示「应用修改」怎么办？

A: 等几秒让 Studio 通过文件来源兜底机制自动按下隐藏定稿动作，或让 Agent 调用 flow_finalize_canvas（传入工作流 id 与当前 revision）显式触发确定性定稿，跳过主 Session 重复审核。

上手难度

入门 — 安装后让 Agent 用自然语言说「构建工作流」即可生成第一份流程图；普通用户无需阅读 README 也能上手，进阶配置（有限反馈边、跨 Session 切换、AI 优化）才需要查阅文档。

已知问题与限制

• 修改 Host 代码或新增 Remote 方法后必须完全重启 dsh web，仅刷新浏览器或硬刷新都不能让新的 /api/dflow/* 接口生效（CHANGELOG.md:5-45、README.md:230）
• 0.3.21 曾出现 @deepseek-ai/dsh-tools 重复副本导致所有 DSH 工具调用失败的严重问题；当前版本通过将其移入 peerDependencies 并在运行时桥接 TOOL_RUNTIME_SCHEDULER 修复（CHANGELOG.md:78-82、lib/index.js:967-978）
• 旧 harness-flow 数据目录中的无主 flows 会在首次启动时自动迁移为共享模板（排除 starter-flow 示例）；迁移是一次性的，不会回写（lib/index.js:1054-1073）
• applyChanges（应用修改）只接受显式有限反馈边的回环，普通执行箭头有环会被校验拒绝；IF/ELSE 出线必须各只有一条，NOT 只允许一条（lib/flow-validation.js:78-85、lib/graph-analysis.js:76-96）
• flow_finalize_canvas 排队后 30 分钟内未被 Studio 消费即过期，需要重新调用（lib/index.js:44、lib/index.js:914-923）
• 插件不做工作流执行、API Key / 凭据管理、定时任务、Webhook 与执行历史；这是产品边界，详见 README.zh-CN.md 功能边界章节

DeepSeek Flow

See the workflow. Keep Markdown portable. Review only real canvas edits.

A visual, Markdown-first workflow editor built for the DeepSeek Harness Web UI.

🌐 Official website — deepseekflow.kanghelyu.org

English · 简体中文

DeepSeek Flow turns a WORKFLOW.md and its step-level STEP.md files into an editable diagram inside DeepSeek Harness. The bundled Skill lets the current Session create and maintain workflows through tools, while the diagram and Markdown remain synchronized and portable.

It is intentionally an editor—not a workflow runtime. DeepSeek Flow helps you design, inspect, and improve a workflow; execution remains in the current Session.

What it gives you

• Markdown as the source of truth — one master WORKFLOW.md, plus one STEP.md workspace for each step.
• A real visual editor — create, move, connect, reconnect, label, and delete nodes and arrows.
• Two-way synchronization — edits made on the canvas and in the Markdown editor are written back to the workflow files.
• Source-aware topology transactions — human canvas edits receive a full current-Session review; topology produced by direct Session file edits can use an invisible deterministic finalize path instead of being sent back to the same Session.
• Executable gate semantics — the exported contract includes formulas, operands, predicates, and deterministic Boolean results without running Agent steps.
• Per-session isolation — each Harness session keeps its own workflows, with optional shared templates; the canvas toolbar can delete the current workflow or shared template behind a guarded confirm (managed workspaces move to a trash area and can be recovered).
• Comfortable large-flow navigation — collapsible and resizable side panels, pan and zoom, fit-to-view, animated node focus, and independent scrolling regions; node drags commit once on pointer release and background sync polls lightweight revisions, so large graphs stay smooth.
• Native theme support — the interface follows Harness light and dark themes and the active WebUI language.
• Manual AI assistance — run logic validation, optimize one document with review, or optimize the complete workflow.
• Background AI jobs — switching documents, views, or sessions does not interrupt accepted jobs; document proposals are restored when you return.
• Persistent results and drafts — logic-validation findings, AI proposals, and unapplied canvas drafts are persisted to disk: view switches, session switches, and dsh web restarts lose nothing; they are cleared only by an explicit discard or a successful commit. Markdown edits inside the 650 ms autosave window are flushed immediately when you leave the view.
• I/O and memory safeguards — unchanged documents are never rewritten (autosaves no longer grind the SSD), assist history and drafts live in separate files, result polling uses single-key queries with failure and duration caps, every background poll is cancellable with no leaks, and subagents get a 10-minute default timeout.
• A bundled Agent Skill — installs with the plugin, documents every workflow tool, and includes executable IF/ELSE and Boolean-gate examples.

Quick start

Install from GitHub into the Web profile:

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

Restart dsh web, open a session, and select the DeepSeek Flow tab.

To confirm that the plugin is mounted:

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

Your first workflow

1. In a Session, ask the Agent to build a workflow or import a workflow. The bundled deepseek-flow Skill guides it to flow_create or flow_put.
2. Open DeepSeek Flow. The plugin scaffolds a master document, step documents, and their visual layout.
3. Ask the Session Agent to change the workflow files, or select a document and edit its Markdown directly.
4. Direct Session/file-driven topology updates are finalized without another main-Session review. The Agent should call flow_finalize_canvas; if it forgets, Studio falls back to detecting that no canvas edit event occurred and presses the same invisible finalize action automatically.
5. When you add, remove, rename, or connect boxes on the canvas, click Apply changes. DeepSeek Flow validates the graph, asks the current Session Agent to review it, validates again, and atomically saves a new revision.
6. Return to the Session when you want the Agent to execute the workflow.

A typical workflow directory looks like this:

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

Agent tools

The Skill is registered reactively when the Harness skills service becomes available. Its SKILL.md contains real Markdown after frontmatter, so filesystem and runtime providers never return an empty instruction body.

Active workflow & cross-session switching

The Studio toolbar's workflow dropdown lists every historical workflow, grouped by origin: current session first, other sessions next, shared templates last. Switching to another session's workflow imports an independent copy of its document workspace into the current session — external custom docRoots are referenced, never copied. Shared templates are also copied into the current session's own managed workspace on switch, so edits never pollute the shared original.

Each session persists an activeFlowId (the workflow last used in Studio) inside sessions/<id>.json. Reopening Studio auto-selects it, and because both the pointer and the history listing (dflow/allFlows) are read straight from disk, the dropdown stays fully populated after a dsh web restart or a machine reboot. A brand-new session starts with an empty canvas and a hint to pick a past workflow from the dropdown, import JSON, or ask the agent to create one.

When the user switches workflows mid-conversation, the next flow_list/flow_read returns an activeFlowNotice instructing the agent to run the switched workflow instead of any earlier instruction. The notice fires exactly once; if the active workflow did not change, nothing is said and the conversation continues uninterrupted.

flow_create accepts an optional language parameter ("en" or "zh"). The Agent should pass the user's current language so default names (New Flow / 新工作流), default step labels, and default node labels are generated in the right language. The user can still override the name explicitly.

Logic gates

Condition boxes support eight gate types: IF/ELSE, AND, OR, NOT, NAND, NOR, XOR, and XNOR. Gate metadata controls connection labels, outgoing limits, and the Boolean contract exported to the current Session.

Duplicate targets, duplicate Yes/No branches, excess IF/ELSE or NOT arrows, invalid aggregate input arity, unmarked cycles, and unknown box kinds are rejected with actionable validation messages. A retry loop is allowed only as an explicit feedback edge with a finite maxIterations and a non-empty exitCondition; feedback edges do not participate in one-pass Boolean evaluation or automatic Agent execution. Legacy true/false branches are normalized to IF/ELSE.

The flow_evaluate tool can deterministically evaluate gate state and activated targets from upstream step results. It does not run Agent steps or perform workflow side effects.

Gate predicates are deliberately small and deterministic: truthy, falsy, and nonEmpty. Do not put a natural-language rule such as "the user confirmed" in predicate. Add an upstream Agent step that outputs JSON Boolean true or false, then connect it to a condition with predicate: "truthy".

{
  "id": "confirmed",
  "kind": "condition",
  "data": { "label": "Confirmed?", "gateType": "ifElse", "predicate": "truthy" }
}

Reviewed topology transactions

Adding or deleting boxes, gates, arrows, inputs, or outputs in Studio creates a local topology draft. Persisting that user-authored draft is an explicit transaction:

Local validation → current Session Agent review → second validation → atomic revision save

• The reviewer is the live current Session Agent, not a detached background session.
• Markdown is immutable review context: topology review cannot silently rewrite document content.
• Stale or incomplete revisions are rejected so concurrent writers cannot lose state.
• Moving a box changes layout only and auto-saves without opening a topology transaction.
• While a topology draft is pending, logic validation and whole-workflow optimization stay disabled; single-document editing and optimization remain available.
• Deleted managed workflows and generated step directories move to trash; external custom document roots are never moved automatically.

Direct Session file edits use a separate trusted path:

Session edits files → optional flow_finalize_canvas signal → deterministic validation → atomic save

The finalize control exists in Studio but is hidden and cannot be clicked through the normal UI. Studio records every user topology edit handler. If a topology difference appears without any such canvas event, it is treated as external/file-driven and the hidden action is pressed automatically. If deterministic validation fails, the draft is preserved and the normal Apply changes path remains available. This fallback means correctness does not depend solely on the Agent remembering the tool call.

AI document assistant

Every AI action is started manually. DeepSeek Flow never runs validation or optimization behind your back.

For whole-workflow optimization, commit or back up important Markdown files first. If a document changes while an optimization is running, DeepSeek Flow refuses to overwrite the newer content.

The assistant uses an isolated Agent job and does not run the workflow. Model and reasoning-effort controls are available in the assistant menu.

Topology review is the exception: it deliberately uses the live current Session Agent because that Session owns the workflow context. Document validation and optimization continue to use isolated one-shot Agent jobs.

Design boundaries

DeepSeek Flow deliberately does not provide:

• a workflow execution button or runtime;
• API-key, provider, or credential management;
• triggers, schedules, webhooks, or execution history;
• a replacement for normal Session interaction.

That boundary keeps the plugin focused: edit and validate in DeepSeek Flow, execute in the Session.

Local development

Clone the repository and link it into your Web profile:

git clone https://github.com/kanghelyu/dsh-deepseek-flow.git
cd dsh-deepseek-flow
dsh plugin --profile web add "link:$PWD"

Useful checks:

npm test
npm run build
npm run smoke

If an older local Harness installation is missing linked dependencies, stop dsh web before running:

bash scripts/ensure-deps.sh

After changing client code, rebuild and hard-refresh the browser. Host changes require restarting dsh web.

deepseek-flow/
├── lib/                 Host code, topology transactions, gate semantics, and client bundle
├── src/client/          WebUI client source
├── skills/              Bundled DeepSeek Flow Agent Skill
├── scripts/             Build, dependency, screenshot, and smoke checks
├── test/                Contract and regression tests
├── examples/            Example Markdown workflow
└── docs/images/         README screenshots

Quality safeguards include automated contract and behavior tests covering graph conversion, bounded feedback loops, revision locking, document lifecycle, topology review, hidden finalization, Boolean semantics, connection validation, Agent jobs, JSON tool-argument normalization, and the generated client bundle. See Code quality notes and QA report for more detail.

Troubleshooting

• The tab does not appear: verify the plugin with dsh web --dump-config, then restart the Web profile.
• The UI looks stale: rebuild with npm run build, restart when Host code changed, and hard-refresh the browser.
• New /api/dflow/* endpoints return 404 and the history dropdown stays empty: the Typert route table is snapshotted when the dsh web process starts. After a Host upgrade that adds remote methods (e.g. allFlows, activate), you must fully restart the Web profile — kill the process and start it again, not just a browser hard-refresh. Verify with curl -X POST http://127.0.0.1:3080/api/dflow/allFlows -H 'Content-Type: application/json' -d '{"args":{}}' (expect 200).
• AI actions report no provider: select a working model in the Session or in the assistant menu.
• Whole-workflow optimization is rejected: one or more documents changed while the Agent was working, or the Agent did not return every required document. Retry from the latest files.
• Apply changes is rejected: for a retry, add a feedback edge with a finite maxIterations and non-empty exitCondition; otherwise fix the reported ordinary cycle, missing input, branch limit, or stale revision, then submit the complete topology again.
• Apply changes appears after a Session file edit: wait briefly for Studio's file-origin fallback, or ask the Agent to call flow_finalize_canvas with the workflow id and current revision.
• The Skill tool returns an empty body: update the plugin and restart dsh web; current releases bundle a valid skills/deepseek-flow/SKILL.md and register it after the skills service is ready.
• Recovering a deleted workflow: managed workspaces are kept under deepseek-flow/trash/<date>/; copy the directory back into workspaces/ to restore the documents, then re-import the flow JSON with flow_put.

Uninstall

dsh plugin --profile web remove deepseek-flow

License

MIT. Community project; not affiliated with DeepSeek.