流程画布 kanghelyu/dsh-deepseek-flow

DeepSeek Flow

看清工作流。让 Markdown 保持可移植。只审查真正的画布改动。

为 DeepSeek Harness Web UI 打造的可视化、Markdown 优先的工作流编辑器。

🌐 官方网站 — deepseekflow.kanghelyu.org

English · 简体中文

DeepSeek Flow 把 WORKFLOW.md 和它每一步的 STEP.md 文件变成 DeepSeek Harness 里可编辑的图。内置技能让当前会话通过工具创建和维护工作流，同时图与 Markdown 保持同步、保持可移植。

它有意做成编辑器，而不是工作流运行时。DeepSeek Flow 帮你设计、检查、改进工作流；执行仍然留在当前会话里。

它能给你什么

- Markdown 是唯一事实来源 — 一份主 WORKFLOW.md，加上每一步一个 STEP.md 工作区。
- 真正的可视化编辑器 — 创建、移动、连接、重连、加标签、删除节点和箭头。
- 双向同步 — 画布上的改动和 Markdown 编辑器里的改动都会写回工作流文件。
- 感知来源的拓扑事务 — 人工在画布上的改动会收到完整的当前会话审查；直接编辑会话文件产生的拓扑，可以走一条不可见的确定性收尾路径，而不必送回同一个会话。
- 可执行的闸门语义 — 导出的契约包含公式、操作数、谓词和确定性布尔结果，且不运行智能体步骤。
- 按会话隔离 — 每个 Harness 会话保留自己的工作流，可选共享模板；画布工具栏能删除当前工作流或共享模板，删除前有受保护的确认（受管工作区会移入回收区，可以恢复）。
- 舒适的大流量导航 —— 侧边面板可折叠、可调整大小，支持平移与缩放、适应视图、节点聚焦动画，以及独立滚动区域；节点拖拽在指针释放时一次性提交，后台同步轮询轻量修订号，因此大图也能保持流畅。
- 原生主题支持 —— 界面跟随 Harness 的浅色与深色主题，以及当前 WebUI 语言。
- 手动 AI 辅助 —— 运行逻辑校验、带审阅地优化单个文档，或优化整个工作流。
- 后台 AI 任务 —— 切换文档、视图或会话都不会中断已接受的任务；返回时文档提案会恢复。
- 结果与草稿持久化 —— 逻辑校验发现、AI 提案和未应用的画布草稿都会写入磁盘：切换视图、切换会话、重启 dsh web 都不会丢失；只有显式丢弃或成功提交才会清除。离开视图时，650 ms 自动保存窗口内的 Markdown 编辑会立即刷盘。
- I/O 与内存防护 —— 未改动的文档绝不重写（自动保存不再磨损 SSD），辅助历史与草稿分文件存放，结果轮询使用单键查询并限制失败次数与耗时，每次后台轮询都可取消且无泄漏，子代理默认超时 10 分钟。
- 内置 Agent Skill —— 随插件一起安装，记录每个工作流工具，并包含可执行的 IF/ELSE 与布尔门示例。

快速开始

从 GitHub 安装到 Web 配置档：

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

重启 dsh web，打开会话，选择 DeepSeek Flow 标签页。

确认插件已挂载：

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

你的第一个工作流

1. 在会话中，让智能体构建工作流或导入工作流。内置的 deepseek-flow 技能会引导它调用 flow_create 或 flow_put。
2. 打开 DeepSeek Flow。插件会搭建主文档、步骤文档及其可视化布局。
3. 让会话智能体修改工作流文件，或选中某个文档直接编辑其 Markdown。
4. 由会话或文件驱动的拓扑更新会直接定稿，无需再经主会话审阅。智能体应调用 flow_finalize_canvas；如果它忘了，Studio 会退而检测「未发生画布编辑事件」，并自动按下同一个隐形定稿操作。
5. 当你在画布上添加、删除、重命名或连接方框后，点击 Apply changes。DeepSeek Flow 会校验图，请当前会话智能体审阅，再次校验，然后原子化保存新修订。
6. 想让智能体执行工作流时，回到会话即可。

典型的工作流目录如下：

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

智能体工具

| 工具 | 用途 |
| flow_create | 创建带文档的线性或分支工作流，并保存到当前会话。 |
| flow_list / flow_read | 发现工作流，读取主文档、步骤文档、修订版本、图和逻辑契约。两者还会返回会话的 activeFlowId，以及用户在 Studio 中切换活动工作流后的一次性 activeFlowNotice —— 智能体随后应运行切换后的工作流，忽略此前关于其他工作流的指令；没有通知时，对话保持连贯。 |
| flow_put | 导入或原子更新完整的工作流定义。调用成功即已持久化。 |
| flow_evaluate | 根据上游值评估布尔门，不运行智能体步骤。 |
| flow_finalize_canvas | 直接编辑文件后，排队执行 Studio 隐式的确定性收尾动作，跳过多余的主会话审查。 |
| flow_delete | 删除会话工作流或共享模板；受管理工作区会被移入回收站。 |

Harness 的 skills 服务可用时，技能会以响应式方式注册。它的 SKILL.md 在 frontmatter 之后包含真正的 Markdown，因此文件系统服务商和运行时服务商永远不会返回空的指令正文。

活动工作流与跨会话切换

Studio 工具栏的工作流下拉菜单列出所有历史工作流，按来源分组：当前会话在前，其他会话其次，共享模板最后。切换到其他会话的工作流时，会把它的文档工作区副本独立导入当前会话 —— 外部自定义 docRoot 只引用，绝不复制。共享模板在切换时也会复制到当前会话自己的受管理工作区，因此编辑永远不会污染共享原件。

每个会话都在 sessions/<id>.json 中持久化一个 activeFlowId（Studio 中最后使用的工作流）。重新打开 Studio 会自动选中它，而且由于指针和历史列表（dflow/allFlows）都直接从磁盘读取，dsh web 重启或机器重启后，下拉菜单依然完整。全新会话从空画布开始，并提示你从下拉菜单选择过往工作流、导入 JSON，或让智能体创建一个。

用户在对话中途切换工作流时，下一次 flow_list/flow_read 会返回 activeFlowNotice，指示智能体运行切换后的工作流，而不是此前的任何指令。该通知只触发一次；如果活动工作流没有变化，则什么都不说，对话继续不受打断。

flow_create 接受可选的 language 参数（"en" 或 "zh"）。智能体应传入用户当前的语言，这样默认名称（New Flow / 新工作流）、默认步骤标签和默认节点标签就会以正确的语言生成。用户仍可显式覆盖名称。

逻辑门条件框支持八种门类型：IF/ELSE、AND、OR、NOT、NAND、NOR、XOR 和 XNOR。门元数据控制连接标签、出边数量上限，以及导出到当前会话的布尔契约。

| 门 | 连接行为 | 布尔结果 |
| IF / ELSE | 最多一条 Yes 分支和一条 No 分支。 | 只选中与条件结果匹配的那条分支。 |
| AND / NAND | 多个不同目标；标签自动生成。 | 对所有已知操作数求值，NAND 对 AND 取反。 |
| OR / NOR | 多个不同目标；标签自动生成。 | 对所有已知操作数求值，NOR 对 OR 取反。 |
| XOR / XNOR | 多个不同目标；标签自动生成。 | 计算奇偶性，XNOR 对 XOR 取反。 |
| NOT | 恰好一条自动加标签的出边箭头。 | 对唯一输入取反。 |

重复目标、重复的 Yes/No 分支、多余的 IF/ELSE 或 NOT 箭头、非法的聚合输入元数、未标记的环、未知的框类型，都会被拒绝，并给出可操作的校验信息。重试循环只允许作为显式反馈边存在，且必须有有限的 maxIterations 和非空的 exitCondition；反馈边不参与单趟布尔求值，也不参与自动智能体执行。旧式的 true/false 分支会归一化为 IF/ELSE。

flow_evaluate 工具可以根据上游步骤结果，确定性地求值门状态和已激活目标。它不运行智能体步骤，也不产生工作流副作用。

门谓词刻意做得小而确定：truthy、falsy 和 nonEmpty。不要把 "the user confirmed" 这类自然语言规则放进 predicate。应添加一个上游智能体步骤，输出 JSON 布尔值 true 或 false，再用 predicate: "truthy" 把它连到条件上。
json
{
"id": "confirmed",
"kind": "condition",
"data": { "label": "Confirmed?", "gateType": "ifElse", "predicate": "truthy" }
}

受审的拓扑事务

在 Studio 中添加或删除框、门、箭头、输入或输出，会创建一个本地拓扑草稿。持久化这份用户编写的草稿是一个显式事务： text 本地校验 → 当前会话智能体审查 → 二次校验 → 原子化修订保存

- 审查者是当前活跃的会话智能体，不是分离的后台会话。
- Markdown 是不可变的审查上下文：拓扑审查不能悄悄改写文档内容。
- 过期或不完整的修订会被拒绝，避免并发写入者丢失状态。
- 移动框只改变布局，会自动保存，不会开启拓扑事务。
- 拓扑草稿待处理期间，逻辑校验和整工作流优化保持禁用；单文档编辑和优化仍可用。
- 删除的受管工作流和生成的步骤目录会移入回收站；外部自定义文档根目录永远不会被自动移动。

直接编辑会话文件走另一条受信路径： text 会话编辑文件 → 可选的 flow_finalize_canvas 信号 → 确定性校验 → 原子保存

finalize 控件存在于 Studio 中，但被隐藏，无法通过正常 UI 点击。Studio 会记录每一次用户拓扑编辑处理。如果出现拓扑差异，却没有任何此类画布事件，就视为外部或文件驱动，自动按下隐藏操作。如果确定性校验失败，草稿会保留，正常的 Apply changes 路径仍然可用。这条兜底路径意味着正确性不只依赖智能体是否记得调用工具。

AI 文档助手

每个 AI 操作都手动启动。DeepSeek Flow 绝不会在背后运行校验或优化。

| 操作 | 范围 | 文件变更前会发生什么 |
| Logic validation | 所有工作流文档和箭头关系 | 智能体返回可点击的错误和警告；不修改任何文件。 |
| Optimize current document | 仅选中的 WORKFLOW.md 或 STEP.md | 预览中显示完整提案。你必须 Accept 或 Reject。 |
| Optimize entire workflow | WORKFLOW.md 和每个 STEP.md | 先显示警告。确认后，智能体直接重写并保存整套文档。没有逐文档审核，也没有内置撤销。 |

整工作流优化前，请先提交或备份重要的 Markdown 文件。如果优化运行期间文档发生变更，DeepSeek Flow 会拒绝覆盖更新的内容。

助手使用隔离的智能体任务，不运行工作流。助手菜单中提供模型和推理强度控制。

拓扑审查是例外：它有意使用当前活跃的会话智能体，因为该会话拥有工作流上下文。文档校验和优化仍然使用隔离的一次性智能体任务。

设计边界

DeepSeek Flow 有意不提供：

- 工作流执行按钮或运行时；
- API key、服务商或凭据管理；
- 触发器、调度、webhook 或执行历史；
- 对正常会话交互的替代。

这条边界让插件保持专注：在 DeepSeek Flow 中编辑和校验，在会话中执行。

本地开发

克隆仓库并链接到你的 Web 配置档： bash
git clone https://github.com/kanghelyu/dsh-deepseek-flow.git
cd dsh-deepseek-flow
dsh plugin --profile web add "link:$PWD"

常用检查： bash
npm test
npm run build
npm run smoke

如果较旧的本地 Harness 安装缺少链接依赖，先停止 dsh web，再运行： bash bash scripts/ensure-deps.sh

修改客户端代码后，重新构建并硬刷新浏览器。宿主端变更需要重启 dsh web。

Repository layout
text
deepseek-flow/
├── lib/ Host code, topology transactions, gate semantics, and client bundle
├── src/client/ WebUI 客户端源码 ├── skills/ 内置的 DeepSeek Flow Agent 技能 ├── scripts/ 构建、依赖、截图与冒烟检查 ├── test/ 契约测试与回归测试 ├── examples/ 示例 Markdown 工作流 └── docs/images/ README 截图

质量保障包括自动化契约测试与行为测试，覆盖图转换、有界反馈循环、修订锁定、文档生命周期、拓扑审查、隐藏收尾、布尔语义、连接校验、Agent 作业、JSON 工具参数归一化，以及生成的客户端 bundle。更多细节见 代码质量说明 与 QA 报告。

故障排查

- 标签页没有出现： 用 dsh web --dump-config 验证插件，然后重启 Web 配置档。
- 界面看起来是旧的： 用 npm run build 重新构建；Host 代码有改动时重启；再强制刷新浏览器。
- 新的 /api/dflow/* 端点返回 404，历史下拉框一直是空的： Typert 路由表在 dsh web 进程启动时就已快照。Host 升级新增了远程方法（例如 allFlows、activate）之后，你必须完整重启 Web 配置档 —— 杀掉进程再重新启动，光强制刷新浏览器不够。用 curl -X POST http://127.0.0.1:3080/api/dflow/allFlows -H 'Content-Type: application/json' -d '{"args":{}}' 验证（预期返回 200）。
- AI 操作提示没有服务商： 在会话里或助手菜单里选一个可用的模型。
- 整工作流优化被拒绝： Agent 工作期间有一个或多个文档发生了变化，或者 Agent 没有返回全部必需文档。从最新文件重试。
- 应用更改被拒绝： 如果要重试，加一条反馈边，设置有限的 maxIterations 和非空 exitCondition；否则先修复报告出来的普通环、缺失输入、分支上限或过期修订，再重新提交完整拓扑。
- 会话文件编辑之后才出现「应用更改」： 稍等片刻，让 Studio 的文件来源回退生效，或者让 Agent 用工作流 id 和当前修订调用 flow_finalize_canvas。
- 技能工具返回空 body： 更新插件并重启 dsh web；当前版本内置了有效的 skills/deepseek-flow/SKILL.md，并在 skills 服务就绪后注册它。
- 恢复被删除的工作流： 托管工作区保存在 deepseek-flow/trash/<date>/ 下；把目录复制回 workspaces/ 即可恢复文档，然后用 flow_put 重新导入 flow JSON。

卸载 bash
dsh plugin --profile web remove deepseek-flow

许可证

MIT。社区项目，与 DeepSeek 无隶属关系。