# dsh-deepseek-flow

> 为 DeepSeek Harness 提供 Markdown 优先的可视化工作流编辑器，画布与文档双向同步，并支持可计算的布尔逻辑门判定。

## Metadata

- Author: [@kanghelyu](https://github.com/kanghelyu)
- Repo: <https://github.com/kanghelyu/dsh-deepseek-flow.git>
- GitHub: [kanghelyu/dsh-deepseek-flow](https://github.com/kanghelyu/dsh-deepseek-flow)
- Stars: 49
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://deepseekflow.kanghelyu.org/>
- Topics: `ai-workflow`, `dark-mode`, `deepseek-harness`, `developer-tools`, `dsh-plugin`, `flow-editor`, `markdown`, `visual-workflow`, `visualization`, `workflow`, `workflow-builder`, `workflow-management`
- Forks: 4
- Open Issues: 1
- Last push: 2026-08-19T15:49:27.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
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 | 0.1.0-rc.6 | peerDependencies 与 devDependencies 中各 `dsh-*` 包均为 `^0.1.0-rc.6` |
| `@deepseek-ai/dsh-typert-protocol` | ^0.1.0-rc.6 | 运行时依赖，用于 Remote 服务 |
| `@deepseek-ai/dsh-tools` | ^0.1.0-rc.6 | peer 依赖，注册 Agent 工具 |
| 平台 | 跨平台 | 插件本身不绑定 OS；DSH Web profile 在 macOS/Windows/Linux 均可运行 |
| 原生模块 | 无 | 未声明原生依赖，仅使用 Node 内置 `node:fs/promises`、`node:os`、`node:crypto` 等 |

## 安装方式
```bash
dsh plugin --profile web add github:kanghelyu/dsh-deepseek-flow
```

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

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `dataDir` | 字符串 | 插件数据目录，存放工作流文件、UI 状态、Assist 结果与回收区 | 未设置时取 `$DSH_HOME/deepseek-flow`，未设置 `DSH_HOME` 则取 `~/.dsh/deepseek-flow` |
| `assistantProvider` | 字符串 | AI 助手使用的模型供应商标识；为空时跟随 Session | 未设置（跟随 Session） |
| `assistantModel` | 字符串 | AI 助手使用的模型；为空时跟随 Session | 未设置（跟随 Session） |
| `assistantTimeoutMs` | 数字（毫秒） | 助手子代理超时，合法范围 10000–600000；超过 600000 会被截断 | 600000（10 分钟） |
| `assistResultTtlMs` | 数字（毫秒） | AI 助手结果保留时长；不设置则永久保留直到用户显式丢弃 | 未设置（永久保留） |

## 常见问题

**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 功能边界章节

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-deepseek-flow](https://deepseek-plugin.org/plugins/kanghelyu/dsh-deepseek-flow)
Wiki generated by AI (model: `MiniMax-M3`)