一句话定位

在 DeepSeek Harness（DSH）原有 workflow 工具之上，加一层可命名、可保存、可暂停、可重跑、可审计的可复用 Workflow 引擎，把多 Agent 协作从一次性技巧变成可维护的工程资产。

核心能力

• 运行已命名、已保存的多 Agent 工作流（项目级或个人级目录），或在对话中调用 /workflow <name>
• 从自然语言需求"侦察-生成-运行"自动编排一个可复用的内联 workflow（scout-then-author）
• 按快照重跑、按 effect cache 续跑、暂停/恢复/停止运行，并保留不可变胶囊用于事后追溯
• 提供 parallel-investigation 和 scoped-review（含 /workflow review 命令，自动捕获 Git diff）两个内置流程
• 暴露三个 DSH 工具：workflow_list（发现）、run_workflow（执行/生成/内联）、workflow_manage（生命周期管理）
• 用 QuickJS WebAssembly 隔离堆运行生成型脚本，仅通过 JSON 能力桥调用宿主，静态拒绝 import/process/文件/网络/计时器

技术实现

• 语言: TypeScript（构建到 ESM lib/*.js）
• 关键依赖: quickjs-emscripten（受限脚本沙箱）、@deepseek-ai/cordis（插件注入）、@deepseek-ai/schemastery（配置 schema）
• 架构模式: Cordis bundle patch — cordis.patch.yml 声明 dsh-external-workflow 节点；index.ts 导出 name + inject: ['subagents','tools'] + apply(ctx, config)；运行时注册一条 /workflow 命令、三个 DSH 工具、System Prompt 段落，并通过 ctx.plugin(DynamicWorkflowService) 装载 service/engine/catalog/runtime/store 子模块
• 入口文件: src/index.ts（已编译为 lib/index.js）

适用场景

适合需要把多 Agent 协作流程沉淀下来反复使用的团队：在仓库里保存代码评审、并行调查、竞品对比等固定流程，避免每次重新提示"如何拆任务、如何并发、如何验证"。也适合需要把工作流跑成长任务或后台任务的开发者——插件默认返回 { runId, status, jobId }，由 DSH 后台 jobs 托管，不会占用当前对话。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:icetomoyo/dsh_workflow

配置项

完整字段与"部署适配器"（registerIsolationAdapter / registerVerificationAdapter / registerDispatchAdapter）的注册方式见 docs/CONFIGURATION.md。

常见问题

Q: 这个插件会接管 DSH 自带的 workflow 工具吗？

A: 不会。两个并存：DSH 自带工具仍负责"这一次把若干工作并行跑完"，本插件负责"把这种过程命名、持久、复用、治理"。它以 Cordis bundle patch 形式注入而非替换核心。

Q: 安装后默认能跑吗？需要额外配置吗？

A: 可以。开箱即用——配置 schema 提供全部默认值，常见调整项是 approvalMode、maxAgents、maxConcurrency、fast/balanced/deep 三层模型路由，或在 readOnlyAllowedTools 里追加要保留的只读工具。

Q: 内置的代码评审流程怎么用？

A: 在会话中输入 /workflow review。插件会调用 git diff 捕获当前变更（默认对比 main/master/develop，都失败则对比未提交内容），并启动 scoped-review 流程。参数：--risk low|medium|high（路由风险）、--requirement "..."（评审约束）、--test-evidence "..."（已有测试证据）、--wait（同步等待）、-- 后追加评审焦点。

Q: 生成的脚本安全吗？能访问我的文件吗？

A: 默认不能。生成型脚本运行在 QuickJS WebAssembly 独立堆中，只通过 JSON 能力桥调用宿主；静态策略拒绝 import/require/process/文件/Shell/网络/计时器/非确定性 API。同步时长、墙钟、内存、栈都有上限。但 trusted-local 形态继承宿主 Node 权限，每次执行都需显式确认——不要把不可信第三方源码标为 trusted-local。

Q: 如何暂停、恢复、重跑一个运行？

A: 用 /workflow 命令：pause|resume|stop 控制当前活动 run；rerun 用当前保存版本重跑，resume-run 用不可变胶囊快照续跑（命中 effect cache 的任务会跳过）。模型侧用 workflow_manage 工具的对应 action。

Q: 持久化数据存在哪里？怎么清理？

A: 运行产物默认在项目根的 .dsh/workflow-runs/<run-id>/（含 run.json、events.jsonl、workflow.workflow.json、results/、artifacts/）。命名 workflow 在 .dsh/workflows/（项目）或 $DSH_HOME/workflows/（个人）。可用 /workflow prune 按数量或时间窗预览/删除；超过 maxRetainedRuns 时终态 run 也会自动清理。

Q: 卸载插件会留下数据吗？

A: 命令与工具会停止注册，但已经写入项目的目录仍保留。重新安装插件可以继续访问历史 run；想彻底清空请删除 .dsh/workflow-runs/ 与 .dsh/workflows/ 目录。

Q: 我能写自己的 workflow 让其他人复用吗？

A: 可以。把 .workflow.json（含 manifest + source + intent + requires + provenance）放进项目 .dsh/workflows/ 或个人目录；文件名不匹配 manifest.name、未知字段、版本不兼容、符号链接逃逸、超大文件都会被预检拒绝。生成型内联 workflow 可通过 /workflow create <需求> 让插件自动产出。

上手难度

进阶 — 需要理解 DSH 子 Agent、内置工具命名、模型路由等概念，但所有配置有默认值，按 README.md 跑一次 /workflow list 与 /workflow parallel-investigation 即可看到效果。

已知问题与限制

• trusted-local 形态的 .ts 文件依赖 Node 22 原生 erasable-syntax TypeScript 与 Node 模块缓存，修改后需重启 DSH；若需要 enum、装饰器等 transform-only 语法或热重载，请发布为 .mjs/.js。
• 嵌套 workflow 仅支持一层；尝试两层会被 WorkflowControlError 立即拒绝。
• /workflow create <request> 与自由文本请求不接受 --wait——它们的执行归当前 Agent 接管，必须等当前 turn 结束。
• DSH 当前子 Agent seam 不原生支持 existing-agent target、per-agent effort、通用 worktree；相关请求需要部署注册 registerDispatchAdapter/registerIsolationAdapter，未注册时显式失败。
• 内置验证覆盖"已执行的读工具证据 / Git 工作区变更 / 每个 required path 的前后指纹 / final-text 后置条件"；非 Git 工作区或外部权威证据由 registerVerificationAdapter 补充。
• 只有生成型 capsule 的 run 才能保存不可变脚本快照用于按 run id 重跑；纯函数 trusted-package/trusted-local 的 run 不能从 run id 再保存。
• dsh.workflow v1 capsule 与 KodaX capsule 不做 wire 兼容；外部 KodaX capsule 不会被误执行。
• DSH Web 左侧工作区在"手动排序"且当前 workspace 会话超过 5 条时会折叠其余会话；新 workflow 会话已归属对应工作区，可点击"展开其余 N 个会话"或切换到"最近更新"排序。

DSH Workflow

把 DeepSeek Harness 的一次性多 Agent 调度，升级为可生成、可保存、可治理、可观察、可恢复的 Workflow 层。

中文 · English · 快速开始 · DSH 价值 · 能力 · 对标矩阵

@dsh-external/workflow 是一个官方 bundle 形态、零核心 patch 的 DSH 插件。它完整参考 KodaX 的 workflow 设计能力，并针对 DSH 的 Cordis、ctx.subagents、Session、后台 jobs、审批、命令和工具机制做独立实现。

它不替换 DSH 已有的前台 workflow 工具。原生工具适合“这一次把若干工作并行跑完”；本插件负责更高一层的流程产品能力：命名、发现、生成、复用、暂停/恢复、重跑/续跑、持久证据、成本记录和治理。

它为 DSH 带来什么

DSH 已经有很强的 Harness 基础设施：模型路由、子 Agent provider、工具权限、审批、Session 日志、后台 jobs 与 UI 事件。但仅有这些“执行原语”，团队仍需在每次会话里重新描述如何拆解、并发、验证和汇总。

对 DSH 项目本身，这个插件的价值是把已有 Harness 能力串成完整闭环：

flowchart LR
  A["DSH providers / models"] --> W["DSH Workflow"]
  B["tool filters / approval"] --> W
  C["Session / jobs / commands"] --> W
  W --> D["reusable capsules"]
  W --> E["durable run graph"]
  W --> F["resume / governance / evidence"]

因此，DSH 不只会“调用 Agent”，还可以承载长期维护的 Agent 工作流库。

快速开始

要求：Node.js >=22.19，以及与 compatibility.json 一致的 DSH 快照。

# 构建产物已提交，git 源安装不需要在用户侧编译
dsh plugin --profile web add "github:dsh-external/dsh_workflow#main"

# 验证 bundle 已进入 profile 合成树
dsh --profile web --dump-config

预期配置中出现：

- id: dsh-external-workflow
  name: '@dsh-external/workflow'

重启对应 DSH profile 后，在会话中输入：

/workflow list
/workflow parallel-investigation {"question":"为什么这个测试会间歇失败？"}
/workflow create 为这个仓库设计一个并行安全评审流程
/workflow review --risk high --requirement "不得破坏公开 API" --test-evidence "pnpm test 通过" --wait
/workflow runs

/workflow create <request> 和未知名称的 /workflow <自然语言请求> 会像 KodaX 一样立即结束命令处理，并把显式 workflow 意图交给当前主 Agent。用户原始 query 以真正的 user message 进入 Session，所以会在对话中显示、参与 DSH 会话标题生成并可在左侧工作区中按标题识别；内部 authoring contract 则作为独立的折叠 plugin context 交给模型，不会污染标题或用户气泡。主 Agent 先用自身工具调查真实 workspace，再以 source + manifest 调用 run_workflow 生成和启动流程；长时间 scout/authoring 不会把斜杠命令卡在 command/run。这条命令只为对应消息中的第一次通过预启动冒烟校验的 inline workflow 提供一次性显式授权；如果脚本或子任务字段无效（例如 modelHint 不是 fast | balanced | deep），插件会在启动任何真实子 Agent 前返回精确错误，并保留本 turn 的一次性授权供主 Agent 修正后重试。内部 relay、后续直接用户消息或重复的有效调用都不能复用授权；工具产生的 scouting context 不会误撤销它。approvalMode: always 和 trusted-local workflow 的审批仍然保留。由于 authoring 由当前 Agent turn 接管，create/free-text 形式不接受 --wait；需要同步等待时请对命名 workflow、rerun、review 使用 --wait，或在工具调用中使用 wait: true。

DSH Web 的左侧工作区在“手动排序”且会话数超过 5 条时会折叠其余会话；新 workflow 会话已归属对应工作区，必要时点击“展开其余 N 个会话”，或将视图排序切换为“最近更新”让活动会话自动前置。

workflow 启动和 run_workflow 默认立即返回 { runId, status, jobId? }，不会让一个长流程占住当前 turn；支持等待的子命令显式传入 --wait（工具参数为 wait: true）才等待终态。/workflow show 默认显示最新 run，/workflow stop 默认停止当前活动 run。

模型也可以调用三个工具：

• workflow_list：发现 built-in、pattern、项目和个人 workflow；无效条目会报告但不会执行。
• run_workflow：运行命名 workflow、从自然语言 scout-then-author，或执行受限 inline workflow。
• workflow_manage：查看、暂停、恢复、停止、重跑、续跑、保存、改名、修订、删除和清理。

能力

与 KodaX workflow 对标的执行模型

• 版本化 dsh.workflow v1 capsule：manifest、source、intent、inputs、requires、provenance。
• 统一 async function run(wf, args) 模型。
• 完整 WorkflowApi：phase、spawnAgent、runAgent、wait、snapshot/output、send/stop、parallel、pipeline、synthesize、单层嵌套 workflow、artifact、log、budget。
• runAgent 对普通子任务失败返回 null，让 workflow 能按策略降级；显式 handle 的 wait 仍保留完整失败结果。要求 object JSON Schema 的任务在原生 structured capture 缺失时只做一次同路由、无工具修复，仍不合规则明确失败。
• Agent 元数据：phase、scope、constraints、read-only、provider/subagent type、fast/balanced/deep 路由、显式 model、isolation、token、evidence、verification、output schema、terse result。
• 两个 built-in：可按 rubric/agent/concurrency 参数化的 parallel-investigation，以及完整 packet/schema/read-contract/双 primary/逐 finding verifier/audit artifact 的 scoped-review。公共 writeReviewPackets() 从调用方已经捕获的 diff、约束和测试证据生成工作区内 content-addressed、不可覆写的分区文件；/workflow review 可直接捕获当前 Git 范围并启动该流程，不依赖 DSH 核心额外提供 /review patch。
• 稳定的 ProcessSnapshot、WorkflowOutcome 与 AgentResult 投影：包含 item/count/progress、失败与未验证结果、structured output、验证证据、路由、usage、artifact 和缓存重放来源。
• 六个标准 pattern：classify-and-act、fan-out-and-synthesize、adversarial-verification、generate-and-filter、tournament、loop-until-done。

完整逐项验收见 KodaX 对标矩阵。本项目只参考行为与能力，不复制 KodaX 的受限许可源码。

发现与复用

搜索顺序是 deterministic 的：

1. 插件内置 workflow 与 pattern（不可被磁盘文件遮蔽）；
2. 项目目录 .dsh/workflows；
3. 个人目录 $DSH_HOME/workflows。

项目同名条目覆盖个人条目；同一目录中 .workflow.json 优先于 .ts/.mjs/.js。符号链接、路径逃逸、超大文件、未知 capsule 字段、版本不兼容和 manifest/文件名不一致都会在执行前失败。

受限 capsule 示例见 examples/review.workflow.json。可信本地模块适用于人工维护的高权限流程，但每次执行都需要显式确认。

生命周期、持久化与续跑

每个 run 都有 running → paused/completed/failed/denied/stopped 状态和稳定 id。默认在项目中写入：

.dsh/workflow-runs/<run-id>/
├── run.json                    # 状态、结果摘要、成本
├── events.jsonl                # append-only 事件图
├── workflow.workflow.json      # 不可变执行快照（生成型 workflow）
├── results/                    # 只保存已完成且验证通过的确定性 effect cache
└── artifacts/                  # workflow 命名证据

• 按 run id 重跑：使用该 run 的不可变 capsule snapshot。
• 按 saved name 重跑：使用当前保存版本。
• resume-run：相同调用序号 + 相同 task input 命中缓存，其余任务继续执行。
• 终态 run 自动按 maxRetainedRuns 清理；也可 preview/执行 prune。
• 同时记录原生 tool-workflow/* Session 事件，复用 DSH 已有 UI/可观察性。动态 workflow 的 run-start 使用 Session 生命周期：启动它的 tool step 或 Agent turn 结束时，后台流程仍保持 running，直到真实 run-end 决定完成、失败或取消，不再被 UI 误标为“已中断”。

常用命令

/workflow help
/workflow list
/workflow create <request>
/workflow review [base | sha <hash>] [--lean] [--risk low|medium|high] [--requirement "..."] [--test-evidence "..."] [--wait] [-- <focus>]
/workflow <name> [JSON args]
/workflow runs [--all|--limit N]
/workflow show [--full] [runId]
/workflow pause|resume|stop [runId]
/workflow rerun|resume-run <runId|savedName> [JSON args] [--wait]
/workflow save <runId> <name> [project|personal]
/workflow rename-run <runId> <display name>
/workflow rename-saved <from> <to> [project|personal]
/workflow revise <savedName> <change>
/workflow delete-run <runId> [--force]
/workflow delete-saved <name> [project|personal]
/workflow prune [--dry-run] [--keep N] [--older-than 7d|24h]

斜杠命令通过 ctx.userQuestions 做一次性人类确认；模型工具使用 DSH 当前 turn 的 ctx.approval。后台运行会尽可能注册到 ctx.jobs，并始终保留插件自己的 durable run id。三条路径共享同一个引擎、run store 和安全策略。

配置

常见配置如下；完整字段和治理建议见 配置参考。

- id: dsh-external-workflow
  name: '@dsh-external/workflow'
  config:
    approvalMode: generated-and-local  # never | generated-and-local | always
    maxAgents: 64
    maxConcurrency: 8
    maxRetainedRuns: 500
    fastProvider: spawn              # ctx.subagents transport
    fastModelProvider: deepseek-official
    fastMaxTokens: 4096
    balancedProvider: spawn          # ctx.subagents transport
    balancedModelProvider: deepseek-official
    balancedMaxTokens: 8192
    deepProvider: spawn              # ctx.subagents transport
    deepModelProvider: deepseek-official
    deepMaxTokens: 16384
    readOnlyAllowedTools:       # 与当前父 Agent 可见工具动态求交集
      - read
      - read_image
      - glob
      - grep
      - lsp
      - skill
      - web_search

availableTools、availableMcp、availableSkills 是部署能力清单，供 capsule preflight 使用。workflow 声明的 requirement 不在清单中时会失败，不会偷偷降级。

安全与能力边界

• 生成型脚本只能通过冻结的 WorkflowApi 发起 effect；脚本结果、参数和 RPC 值必须可 JSON 序列化。
• 生成脚本运行在 QuickJS WebAssembly 独立堆中；宿主只暴露 JSON capability RPC。静态 policy 还会拒绝 import/require、process、文件、shell、网络、timer 与非确定性 API。
• 同步执行、总墙钟、WASM 内存与栈都有上限；主函数返回或墙钟超时时会关闭 RPC、abort run，并等待所有已接收的宿主 RPC 与已发布 child 静默退出。可信本地模块仍具有宿主权限。
• readOnly: true 使用“当前父 Agent 可见工具 ∩ 可信只读 allow-list”，未来新增写工具默认不可见；provider 不支持 toolFilter 时直接失败。
• token budget 在子 Agent 发布前预留，本地 Agent 有 usage 时按 Session 实际值核算。
• read-path、成功 mutation tool + Git workspace 指纹变化、每个 required changed path 的前后内容指纹、final-text 与 bounded same-actor repair 已内建；部署可以用带稳定 cacheIdentity 的 registerVerificationAdapter() 叠加非 Git 或更强的 workspace 证据。worktree 通过 registerIsolationAdapter() 接入，未注册时明确失败。
• catalog 保存/替换/改名/删除使用规范化根目录、逐段 junction/symlink 拒绝与原子独占发布；并发同名保存不会互相覆盖。
• DSH one-shot seam 没有原生 existing-agent target / effort 控制；部署可在首次运行前注册 registerDispatchAdapter() 完整承接这两个字段，否则 fail loud。

更多细节见 安全模型和架构说明。

开发与验证

仓库旁需有兼容 DSH checkout，默认路径为 ../test-icetomoyo，也可设置 DSH_SNAPSHOT_DIR。

pnpm install
pnpm check           # 快照 pin + 真实 DSH 投影 + 179 tests + typecheck + build
pnpm test:coverage   # 语句/分支/函数/行全局阈值均为 80%
pnpm pack

兼容基线、commit 和验证时间记录在 compatibility.json。发布前必须重新 fetch DSH 默认分支并更新此文件。

已知限制

• trusted-local .ts 使用 Node 22 原生 erasable-syntax TypeScript，并遵循 Node module cache（修改后重启 DSH）；需要 enum 等 transform-only 语法或热重载时请发布为 .mjs/.js。
• 当前 DSH 通用 subagent seam 不直接支持 existing-agent target、per-agent effort 和 worktree；相应请求需要部署注册 dispatch/isolation adapter，未注册时 fail loud。
• 内建 verification 能证明实际 read/mutation tool evidence、Git workspace 变化、每个 required path 的任务前后指纹与文本后置条件；非 Git 工作区或需要外部权威证据的策略由 verification adapter 补充。
• 仅生成型 capsule run 能保存不可变 script snapshot；纯函数 trusted-package/local run 不能从 run id 再保存。
• capsule v1 与 KodaX capsule 不做 wire compatibility；外部 capsule 不会被误执行。
• capability-generated 源码与宿主对象隔离；但 trusted-local workflow 会以 Node 宿主权限执行，不要把不可信第三方源码标为 trusted-local。

致谢

• DeepSeek Harness 提供 Harness、插件和子 Agent 能力面。
• KodaX 提供 workflow 产品设计的行为参考；本插件为独立实现。
• dsh-external 社区插件为 bundle 安装、验证、安全边界和文档结构提供了实践参考。

License

MIT，见 LICENSE。