dsh-workflow-designer

Readme

# dsh-workflow-designer

`dsh-workflow-designer` 是面向 DeepSeek Harness 的提示词优先工作流设计插件。它收集当前 Agent 可见的本地 Skill、原生 Tool 与 MCP Tool，提供必要的可视化编排和约束编辑能力，并导出稳定的 YAML 中间表示。后续可由大模型及对应框架把 YAML 生成 Python、`workflow.mjs` 或其他代码工作流。

![工作流辅助编排界面预览](./img_preview.png)

## 为什么采用提示词优先的工作流

Dify、Langflow 一类强编排工作流适合严格控制固定流程，但会牺牲一部分大模型的语义理解和动态规划能力；完全依赖提示词又很难细致控制复杂分支、工具参数、错误处理和结果约束。

本项目采用折中方式：保留 LLM 通过提示词理解和生成任务的灵活性，同时用可视化节点、显式端口、资源快照、参数 Schema、分支条件和验证规则提供强控制，减少工作流生成阶段的漂移与幻觉。设计器本身不负责执行完整工作流，而是生成可审计、可迁移、适合继续代码生成的规范化描述。

## 当前能力

- 在 Harness 的 `sidebar.footer.action` slot 注册“工作流辅助编排”（Assisted Workflow Orchestration）入口。
- 提供 Prompt、Sub-Agent、Sub-Agent Flow、Skill、Skill Interface、MCP Tool、Native Tool、Group、If/Else、Switch 和 Ask User Question 等节点。
- 仅在用户选择资源时，从当前 Session/Agent scope 查询 `ctx.skills` 与 `ctx.tools`。
- 保存 Skill/Tool locator、digest、Schema snapshot 与 Prompt Card，便于发现资源变化并重新验证。
- 支持 MCP Tool 真实调用测试；调用经过 Harness 的 schema、权限、策略、超时和 Tool pipeline。
- 支持 Skill 静态接口索引，并可选择使用当前 Harness Sub-Agent 对接口文档做受限复核。
- 保存 `dsh.workflow/v1alpha1` YAML，并可导出 Mermaid、Markdown 与代码生成上下文。
- 可把去除画布坐标后的语义 YAML 写入当前 Harness 对话输入框，但不会自动发送。

## DeepSeek Harness 兼容基线

当前开发与类型检查锚定以下不可变 Harness 基线；插件自身采用独立的常规 SemVer：

| 项目 | 值 |
| --- | --- |
| Release | [`dsh-v0.1.1-rc.2`](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2) |
| npm version | `0.1.1-rc.2` |
| Git commit | `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e` |
| Repository | `https://github.com/deepseek-ai/deepseek-harness` |
| Plugin version | `0.2.0` |
| Git tag | `v0.2.0` |

`package.json.deepseekHarness` 是机器可读的基线记录，README 中的 Release、version 和 commit 必须始终与它一致。项目不会自动跟随 Harness 的分支、`latest` 或 `next`。

插件版本不再复用 Harness 版本号，后续按常规 SemVer 独立迭代。正式版本默认发布到 npm `latest`，Git tag 固定为 `v<package version>`。

Harness rc.2 要求 Node.js `^22.19.0 || >=24.0.0`，上游源码使用 `pnpm@11.7.0`。

## 兼容模型与直接依赖

Workflow Designer 业务代码只认识以基线制定的 `WD-BASE-1`。正式 Client bundle 同时携带 `WD-ADAPTER-1`（legacy Client Runtime）和 `WD-ADAPTER-2`（split Client Services），启动时优先按实际能力检测选择；Harness tag/version 只用于档案、诊断与已知错误防护。

逐 tag 的不可变 identity、精确依赖快照、接口差异和验证状态保存在 `patch/`，本报告见 [`docs/harness-interface-contract-audit.md`](./docs/harness-interface-contract-audit.md)。`cordis.patch.yml` 仍只负责 Cordis 插件挂载，不参与 API 兼容。

基线开发和类型检查继续精确固定同一 Release：

- `@deepseek-ai/dsh-client-runtime@0.1.1-rc.2`
- `@deepseek-ai/dsh-client-ui-conversation@0.1.1-rc.2`
- `@deepseek-ai/dsh-client-ui-sidebar@0.1.1-rc.2`
- `@deepseek-ai/dsh-client-ui-slots@0.1.1-rc.2`

这些 DSH 包只位于 `devDependencies`，不会作为正式 peer 强迫宿主安装基线 provider。Harness 拥有并加载自身版本的 Client provider；插件静态注入经 boot graph 验证的共同入口 `dsh-client-ui-sidebar` 与 `dsh-client-ui-conversation`，由它们在各接口族中传递加载正确的 Session、Slots 和 Workspace 能力。

`yaml` 是 Host bundle 的外置运行时依赖。`reactflow` 被打入 Client bundle，因此只属于开发依赖。React 与 React DOM 由 Harness Web 客户端提供，作为 peer dependency 声明。插件不直接 import `@deepseek-ai/cordis`，也不在 Client bundle 中运行时 import DSH provider。

当前机器档案覆盖 `dsh-v0.1.0-rc.7` 至 `dsh-v0.1.3-alpha.1`。其中缺少完整已发布精确 provider 的 tag 只具备源码审计结论，不代表 registry 可安装支持；正式支持状态以兼容档案中的 same-tarball 验证为准。

## 安装与运行

从 npm 安装到 Web profile：

```powershell
cd C:\Users\rone\Documents\deepseek-harness
pnpm dsh plugin --profile web add dsh-workflow-designer@latest
pnpm dsh web
```

本地发包前联调可安装当前工作区：

```powershell
cd C:\Users\rone\Documents\deepseek-harness
pnpm dsh plugin --profile web add D:\WorkSpace\dsh-workflow-designer
pnpm dsh web
```

包通过 `dsh.bundle.patch` 加载 `cordis.patch.yml`，并通过 `dsh.client` 与 `./client` 提供浏览器端插件。正常安装不需要手工传入 `--patch`，也不需要修改 Harness 源码。

## 开发与发包前验证

本地类型检查直接使用 lockfile 安装的精确 rc.2 npm 类型声明，不依赖开发机上的 Harness 绝对路径。发布验证使用 registry 安装得到的精确依赖和提交的 lockfile：

```powershell
npm ci
npm run check
npm test
npm run build
npm run verify:client-bundle
npm run verify:boot-graph
npm pack --dry-run
```

`npm run verify:harness-matrix -- --install` 会只构建和打包一次，计算 tarball SHA-256，并用每个 registry 可复现 tag 的精确依赖档案创建隔离 fixture。所有结果必须引用同一 digest，测试过程不得改写 tarball 的 manifest 或 Client bundle。

若启动时缺少共同 Session/Slots/Conversation 能力或两种 Workspace 导航能力，插件会在注册 UI 前抛出 `UnsupportedHarnessError`，错误只列出缺失能力和非敏感的运行时 identity，不会静默选择错误 adapter。

4 组较大的 Skill 接口黄金样例属于可选外部验收数据。设置 `DSH_SKILL_DEMO_ROOT` 指向包含这些样例的目录后会执行；未设置且默认相邻目录不存在时，相关 3 项测试会明确标记为 skipped，其余仓库内测试仍是强制门禁。

`lib/client.js` 是浏览器 bundle，`lib/index.js` 是 Host bundle。打包清单不得包含 Harness checkout、凭证、缓存、临时文件或本地链接。

## 输出目录

- 工作流源文件：当前 workspace 的 `.dsh/workflows/<name>.workflow.yaml`
- 生成结果：当前 workspace 的 `.dsh/generated/<name>/`
- 示例：`examples/`
- 设计器 Skill：`skills/dsh-design-workflow/`

当前版本不执行完整工作流，也不实现 Parallel/Join/Loop、MCP 配置管理、LLM 自动改图、源 Skill 写入或 Mermaid 反向导入。