简体中文 · English

Workflow One

一句话，把真实 Agent 变成可观察的工作流

Workflow One 是运行在 DeepSeek Harness（dsh） 中的可视化 AI 工作流编排器。只需用自然语言描述需求，AI 会自动规划并创建由真实 dsh agent、脚本、条件分支和 HTTP 节点组成的 DAG；也可在画布中微调后启动流程，实时查看每个节点的输入、输出和产物，失败后从中断处恢复。

为什么需要 Workflow One？

安装

[!NOTE] 需要 Node.js >= 22.15.0（dsh 本体用到 node:zlib 的 zstd API，22.15 起提供），并已安装 DeepSeek Harness：npm i -g @deepseek-ai/dsh。

npm

dsh plugin --profile web add dsh-harness-one
dsh plugin --profile web add dsh-better-sidebar   # DSH UI 侧栏宿主（画布 tab）
dsh web

v0.5.0 起 Workflow One 合并为单包 dsh-harness-one（旧 dsh-ccpg-one 已停更）。老用户在设置面板「Workflow One → 检查更新」一键迁移，或手动：dsh plugin --profile <name> remove dsh-ccpg-one && dsh plugin --profile <name> add dsh-harness-one && dsh plugin --profile <name> add dsh-better-sidebar。

Harness Desktop 用户从托盘打开 Open DSH Terminal，执行 dsh plugin add dsh-harness-one && dsh plugin add dsh-better-sidebar 后重启 Desktop。不要在 Desktop 中运行 setup.sh，Desktop 会自行管理 profile、Node/pnpm 和随机 loopback 端口。详见 Desktop 安装与排障。

界面依赖说明：Workflow One 在 dsh 官方界面中的「工作流」画布由开源项目 DSH-better-sidebar 提供侧栏与标签页宿主，dsh-harness-one 会自动安装并依赖它。未安装或禁用 DSH-better-sidebar 时，官方界面内嵌的「工作流」入口不可用，但独立画布 /wf1/ 仍可访问。

离线包

从 GitHub Releases 下载聚合包，无需仓库源码：

curl -LO https://github.com/chumingjun/dsh-harness-one/releases/download/<tag>/dsh-harness-one-plugins-<tag>.tar.gz
tar -xzf dsh-harness-one-plugins-<tag>.tar.gz && cd dsh-plugins
sh setup.sh --one wf1 4021
sh start.sh wf1                         # http://127.0.0.1:4021/

从源码构建

git clone https://github.com/chumingjun/dsh-harness-one.git
cd dsh-harness-one
npm install
npm --prefix web install
sh dsh-plugins/build-web.sh             # 源码安装必跑，构建产物不入库
sh dsh-plugins/setup.sh --one dev 4021
sh dsh-plugins/start.sh dev

模型和密钥完全由 dsh profile 管理。插件使用 dsh 默认模型栈，也支持在 cordis.patch.yml 或 ~/.dsh/settings.yaml 中追加 provider；本仓库和插件不写死、不存储任何 key。完整安装、配置与开发循环见 dsh-plugins/README.md。

普通 dsh 的 lark-cli 由 setup.sh 或插件自举安装；Desktop 仅在用户明确点击后通过受管 pnpm 安装。

界面与使用方式

Workflow One 嵌在 dsh 官方界面中，推荐从 AI 对话开始创建复杂工作流：左侧用自然语言描述目标和需求，中间画布实时呈现 AI 生成的 DAG。画布主要用于确认结构、微调参数和观察运行，也可以继续手工添加或连接节点。

1. 在 dsh 对话中用自然语言描述要完成的工作流需求，AI 会自行规划流程并创建节点。
2. 需求有变化时，继续在对话中说明，AI 会相应更新工作流。
3. 在画布中确认生成结果，保存后从对话或画布启动运行。
4. 运行期间，对话会以卡片直接展示各节点的进展；也可配置「消息通知」节点，将节点状态实时同步到飞书群聊或私聊。画布节点可查看实际输入与执行详情，右侧「过程 / 成果 / 问题」提供时间线、最终结果和产物。

/workflow-one 技能指令：在对话输入框键入 / 打开技能菜单，选择 workflow-one 注入操作指南，之后用自然语言搭建和驾驭长流程——多节点接力、定时触发、跑几十分钟也不用盯着：

• 「搭一条每天早上汇总三个飞书群消息、提取要点写成日报发回群的工作流」——口述需求即创建：AI 规划多节点接力（抓取 → 分析 → 撰写 → 通知）、配好定时触发，保存后每天自动跑
• 「现在跑到哪了？卡在哪个节点？」——长流程随时问进度：给出各节点状态与产出，异常节点附错误摘要和下一步建议
• 「给竞品监控工作流加一个数据异常时转人工确认的分支」——读图、批量改图、lint 校验一次完成
• 「删掉那个临时拼的爬虫工作流」——确认后删除；有关联运行 / 定时 / webhook 时会拒绝并列出清单

该技能由 orchestrator 安装时种子到 dsh 原生技能根，官方聊天与画布会话共用；画布绑定的会话另有 canvas_* 工具族直接操作当前画布，详见下文「画布 AI 助手」。

查看完整分辨率截图

下图展示同一次运行的协同视图：左侧对话持续跟踪进度，中间选中正在执行的节点并查看配置，右侧按拓扑顺序展示每个节点的运行状态。

可导入模板

examples/workflows/ 提供三套可直接导入的工作流：报修工单整理、紧急度分流和多方并行评审。打开「工作流」列表，点击「导入」并选择 .workflow-one.json 文件即可使用。

画布能力

8 种节点类型：输入 / 智能体 / 脚本（QuickJS 沙箱） / 条件分支 / HTTP 请求 / 输出 / 消息通知 / 注释。

• 可拖拽画布（React Flow）：连线（禁自环/环检测）、缩放、小地图、框选、快捷键（Cmd+S 保存 / Cmd+Z 撤销 / Delete 删除 / Cmd+D 复制 / F 定位错误）
• 智能体节点：提示词 + 工具勾选（read_file / web_fetch / feishu_doc_read / feishu_doc_write）；节点级模型与渠道（GLM anthropic 订阅 / openai 按量、DeepSeek），同图不同节点可组队；工具循环轮数上限；Plan-Execute 三阶段模式（规划→逐步执行→总结，planTrace 全程记录）；技能 = dsh 原生 skill 工具（ctx.skills 目录，节点可勾选定向提示）
• 脚本节点：QuickJS 沙箱执行同步 function main(input, workspace) 返回 JSON。命名参数支持「表达式」（完整变量，仅直接上游）或「JSON 常量」；workspace 仅可 list/read/write/remove 本节点目录（拒绝穿越/反斜杠/符号链接）；超时 100–10000ms；可选 outputSchema 校验（失败即节点失败）；返回值进变量树
• 变量系统：模板编辑器（输入 {{ 或 /变量 搜索字段树）覆盖全部模板位；稳定 ID 引用 {{node["n_http_1"].data.json.customer.name}}、缺省值 | default("x")、{{$trigger}} / {{$upstream}}；改名联动全图替换；旧 {{节点名}} 语法兼容
• 运行与调试：SSE 实时状态（queued/running/success/error/skipped）；就绪即发并发调度；分支容错（单支失败不拖垮其余）；节点重试 / 失败继续 / 超时；运行取消 / 重放 / 导出；试运行（手填假输入、关闭即中断）；节点级运行详情（实际输入、产物、token 用量、trace）
• 多运行并发：同一工作流可同时运行多个实例（节点工作区 / 产物 / 日志 / 取消按 runId 互不干扰）；成果面板顶部运行胶囊条随时切换查看任一运行（LIVE 优先、含来源图标与实时进度），画布节点状态随选中运行联动；定时 / Webhook 触发的运行不抢占当前视图，以 toast + 胶囊提示
• 结果面板：时间线按图拓扑稳定排序（跳过分支也可见）；最终结果取输出节点、失败不被中间结果顶替；过程产物折叠分组；产物流式下载（Range 206 / 统一 MIME / HTML sandbox CSP）与全屏预览（PDF/DOCX/XLS(X)/PPTX 本地渲染）
• 消息通知节点：运行级观察器，可独立放置或在线路中透传；支持仅运行结束、每个业务节点完成两种模式；当前通过飞书消息卡片推送到群聊或私聊，渠道层可继续扩展钉钉和企业微信
• 触发与集成：webhook（token 鉴权）、cron 定时（画布「⋯ → 定时任务」可视化管理：预设 + 自定义表达式、下 3 次触发预览、重叠策略可选跳过/并行、立即运行、停用与编辑）、飞书写回（输出节点可选）
• 持久化：工作流库（命名工作流 CRUD）、运行历史（含 graph 快照）、重启恢复（触发器落盘 + 链式定时等待，含触发/跳过统计）
• 可靠性：保存失败 toast 报错并中止运行；命名工作流运行带 graphFingerprint 指纹校验（409 拒绝跑错版本）

画布 AI 助手

官方 dsh Web UI 的聊天里直接改图（同 session，经 canvas_* 工具落图）：canvas_get_graph / canvas_graph_summary / canvas_graph_patch（批量原子操作，含 script 节点契约）/ canvas_lint_graph / canvas_run_workflow / canvas_run_status。点击对话输入框旁的工作流按钮，在右侧 better-sidebar 打开当前 session 的画布；主区对话持续可见。

workflow_ 工具家族*（按工作流 id/name 操作，不依赖画布绑定，任意官方聊天会话可用；按会话 cwd 定工作区）：

• 查询：workflow_list（清单+各 live 运行数）/ workflow_get（概要省 token 或完整图）/ workflow_runs（live 优先+最近 N，可过滤）/ workflow_run_status（单 run 详情）
• 运行：workflow_run（异步返回 runId）/ workflow_run_cancel（按 runId、工作流或 all 批量）
• 管理：workflow_patch（原子改图+可选改名，正打开的画布实时同步）/ workflow_create / workflow_delete（confirm 门 + live/webhook/定时关联守卫）/ workflow_open（把绑定画布切到指定工作流，SSE 联动）

workflow-one 技能（orchestrator 种子到 dsh 原生技能根，同 feishu-cli 先例）：官方 / 菜单自动列出 workflow-one，选中即注入使用指南，模型按指南调上述工具干活；官方聊天 agent 与画布 agent 共用。

飞书

• 账号登录：官方 dsh Web UI 设置面板「飞书账号」扫码（lark-cli Device Flow，token 由 CLI 自管零落盘）；user token 后台自动续约（refresh 轮换，授权长期有效）
• 凭据：画布 ⚙ 设置弹窗管理多套自建应用凭据（掩码/默认切换/输出节点可选）
• 工作流通知：消息通知节点使用自建应用凭据，以机器人身份向群聊或用户私聊发送运行进度与结果卡片
• 技能：feishu-cli 技能由 larkauth 种子到 dsh 原生技能根 ~/.dsh/skills（官方聊天 agent 与画布 agent 共用）；agent 默认 --as user，失败降级 --as bot

消息通知节点

通知节点不承担业务计算，而是观察整次运行，因此既可以串在连线上透传上游输出，也可以不连线独立放在画布上。两种放置方式的通知行为一致。

1. 在画布右上「设置」中添加飞书自建应用的 App ID / App Secret；这与「飞书账号」扫码登录是两套独立凭据。
2. 添加「消息通知」节点，选择飞书渠道和应用凭据。
3. 选择接收方式：群聊填写 oc_ 开头的 chat_id，机器人必须已加入目标群；私聊填写 ou_ 开头的用户 open_id，应用可用范围必须包含该用户并允许机器人向其发消息。
4. 选择通知模式：仅运行结束会在成功、异常终止或取消时发送结果卡；每个节点完成会在每个业务节点成功或失败后发送紧凑进度卡，并在运行结束后追加结果卡。

进度卡包含节点状态、整体进度、节点耗时和输出摘要；结果卡包含最终状态、成功/失败/取消/跳过节点统计、起止时间、总耗时、最终输出摘要，以及异常或取消原因。摘要会截断并脱敏常见 token、密码和密钥字段。通知发送失败只记录在通知节点的运行元数据中，不会把已完成的业务工作流改成失败。

典型使用场景：

• 定时巡检、日报或数据同步完成后，把最终结果推送到业务群
• 长耗时多节点流程逐步播报进度，让协作群及时看到卡点
• 工作流异常或被取消时立即发送失败节点与原因，便于值班响应
• 将审批准备、工单处理或个人自动化结果私聊给指定负责人，减少群消息干扰

插件形态（dsh-ccpg 系）

安装 / 打包 / 数据位置见 dsh-plugins/README.md。

HTTP API（/wf1/api/*，挂在 dsh webServer）

环境变量

本仓库没有自己的配置文件，模型/渠道完全跟随 dsh profile 的配置（apiKeyEnv 声明 key 变量名），技能目录走 dsh 原生 ~/.dsh/skills / ~/.agents/skills 发现根。插件路径没有自创的环境变量。

架构

双端节点注册表：引擎 NodeKind（调度/超时/重试）+ 前端 registry（图标/表单/徽标），新节点两处注册即得全部能力。agent 节点 = ctx.agents.create 进程内真实 dsh agent（followup → whenIdle → session events 聚合，同官方 headless 驱动）。

已知 dsh 插件开发事实（踩坑记录）

• defineTool 必须带 output: { schema, render }（文本工具 schema {type:'string'}）
• ctx.webServer.register 路由形状 {kind:'exact'|'prefix', path, handler}，重复 path 抛错
• 给 ctx 挂自定义属性需 provide 声明；插件包里 @deepseek-ai/* 依赖需 file: 软链（bootstrap-deps.sh）
• dsh 浏览器端 module-loader 禁跨插件值导入——插件 client bundle 必须自包含
• dsh 官方 UI 远程 403 = PRIVILEGED_METHODS 钉死 loopback（安全设计）；插件自有路由不受影响
• dsh 进程内 fetch 127.0.0.1 自请求 404，需换 LAN IP；官方 UI 首载慢，E2E 等待要放宽

测试

cd dsh-plugins/dsh-ccpg-orchestrator && for t in test/*.test.mjs; do node "$t"; done
node dsh-plugins/dsh-ccpg-canvasui/test/client.test.mjs
node dsh-plugins/dsh-ccpg-document-preview/test/index.test.mjs
cd web && npm test

已知限制

• 飞书写回为追加段落块，不保留富文本格式
• 工作流与运行记录按工作区存入 .workflow-one/workflow-one.sqlite；state、附件与运行产物仍为本地文件

致谢

本项目 90% 以上的开发工作使用 ZCode 完成，感谢 ZCode 提供的开发平台与支持。

反馈

• 🐛 安装失败 / 运行报错：提 Issue
• 💡 功能建议：提 Issue
• 💬 使用提问、工作流配置求助、展示你搭的流程：Discussions