工作流编排 zaalipro/dsh-workflows

@zaalipro/dsh-workflows

@zaalipro/dsh-workflows@0.1.0-rc.5 是一个可安装的 DeepSeek Harness bundle，提供已保存的 JavaScript workflow、受监督的后台运行、保留记录检查、斜杠命令和 Web 仪表盘。它面向官方 DeepSeek Harness 0.1.2-rc.1，并附带一个由本包拥有、采用 MIT 许可的 compatibility evaluator，以提供 replay-safe background execution；它不包含任何 Grok CLI 代码、账户、配额、二进制文件、协议或运行时依赖，也不包含 Rhai 解析器或求值器。

兼容性

已验证的 Host 是官方 DeepSeek Harness 0.1.2-rc.1。Plugin 0.1.0-rc.5 针对该精确版本编译并完成 smoke test，其直接 Harness peer dependency 也精确锁定在该版本。原版 0.1.0-rc.8 仍不受支持；更高 Harness 版本需要新的已验证 plugin release。

本包要求 Node ^22.19.0 || >=24.0.0，使用 pnpm@11.7.0，并按 MIT license 发布。原生锁依赖的归属信息见 NOTICE.md。

安装

先确保 service user 的 PATH 中有 pnpm。像其他 profile plugin 一样安装固定 release tag；它增加一个依赖和一个名为 @zaalipro/dsh-workflows 的 bundle 层，无需手动 profile patch 或 install-time build。

dsh plugin --profile web add github:zaalipro/dsh-workflows#v0.1.0-rc.5
dsh plugin --profile headless add github:zaalipro/dsh-workflows#v0.1.0-rc.5

也可以把 exact tested tarball 复制到 durable path（不要使用 /tmp）后安装：

dsh plugin --profile web add /absolute/path/zaalipro-dsh-workflows-0.1.0-rc.5.tgz
dsh plugin --profile headless add /absolute/path/zaalipro-dsh-workflows-0.1.0-rc.5.tgz

0.1.0-rc.5 在 npm 公开发布后，可以使用等价的 registry install：

dsh plugin --profile web add @zaalipro/dsh-workflows@0.1.0-rc.5
dsh plugin --profile headless add @zaalipro/dsh-workflows@0.1.0-rc.5

Web 会加载 Host 产品和浏览器 Client；headless 只加载 Host 产品，绝不求值浏览器代码。Plugin 不修改 stock ctx.workflowEngine。Supervisor 私下使用本包拥有的 compatibility evaluator，其产物为 lib/compat-engine/index.js 与 worker.cjs。

移除

同时移除依赖和 bundle 条目，然后重启 profile：

dsh plugin --profile web remove @zaalipro/dsh-workflows
dsh plugin --profile headless remove @zaalipro/dsh-workflows

移除后，未修改的官方 profile 可以启动；该命令不会就地改写官方 profile 文件。

已保存定义与创作

定义和运行是不同资源。定义是扁平的 UTF-8 <name>.workflow.json 文件，按以下顺序选择第一个胜出的根：已配置的 bundled 根、最近 Git 项目根的 .dsh/workflows 目录（没有 Git 根时使用 Session cwd），最后是 $DSH_HOME/workflows。根不存在是合法情况；已观察到的匹配文件若不安全、格式错误、过大、为链接或存在其他无效情况，整个观察会失败，而不是从目录中静默消失。

每个文件只包含作为数据的 metadata 和一个纯 JavaScript body：

{
"meta": {
"name": "review-changes",
"description": "Review a change and verify the findings",
"whenToUse": "Before merge",
"phases": [
{ "title": "Review" },
{ "title": "Verify" }
]
},
"script": "phase(\"Review\");\nconst review = await agent(\"Review the requested change. Return evidence.\", { label: \"reviewer\", phase: \"Review\" });\nif (review === null) complete({ ok: false, reason: \"review failed\" });\nphase(\"Verify\");\nconst verified = await agent(Verify this review against the workspace:\\n${review}, { label: \"verifier\", phase: \"Verify\" });\ncomplete({ ok: verified !== null, review, verified });"
}

名称采用小写 kebab-case，以字母开头，不超过 64 个 UTF-16 code unit，与文件名 stem 一致，并避开命令保留名和 Windows 设备名。运行 /create-workflow [detail] 可调用已安装的创作 skill；它会收集意图与 fan-out，用 JSON data 保存 metadata 并编写 JavaScript，使用 canned agent result 验证一个有代表性的 args-selected path，而且只在 smoke check 成功后保存。Inline tool call 默认使用 save_scope: "project"，也可用 save_scope: "user" 保存到 $DSH_HOME/workflows；user scope 不要求 Session cwd。完整 hook 与 quota 参考见已安装的创作 skill。

Structured agent() schema 可以在 array 节点上使用包含端点的 minItems 与 maxItems bound。每个 bound 必须是非负 safe integer（不能是 -0），minItems 不得超过 maxItems，且两个 keyword 都不能与 oneOf 并列。Evaluator 会在 child 启动前检查 declaration，并再次检查返回值；stock-RC2 adaptation 只会从 provider-facing schema 副本中移除这两个 keyword。

启动与操作

使用 /workflow <name> [<json-args>] 或生成的 /<name> [<json-args>] alias 启动已保存定义。普通命令会保留冲突的裸名称；workflow 会取得第一个可用的重复前缀 alias，例如 /workflow-review-changes，而 /workflow review-changes 始终可用。启动会立即返回 Started workflow "<display-name>" in the background. Open /workflows to watch it.；同一 metadata name 的后续运行使用 review-changes-2 等 display handle，不暴露内部 id。

在 Web 中，裸 /workflow 打开已保存定义选择器；严格的裸 /workflows 是仅由浏览器处理的 slash action，它打开 dashboard，不产生 Host command lifecycle，也不会唤醒模型。参数和附件会在本地被拒绝并保留在 composer 中。在 headless 中，裸 /workflow 输出 usage；由于不存在 dashboard surface，/workflows 不注册为 Host command。仪表盘列出已保存 definition（可 Start），以及 live 与 retained run、phase、agent spend、member outcome、log、terminal result 和分块 scratch artifact。Pause、Resume、Stop 与符合条件的 Save action 都检查 revision；键盘操作和窄屏 drill-down 同样可用。

符合条件的 terminal run 最多尝试一次 owner-visible completion notice。它优先使用有界的 scratch/report.md，否则使用有界 result preview，并以 Open /workflows to inspect the run. 结尾。Notice 会直接追加到 durable Session surface，因此无需唤醒模型或进入 Agent inbox 即可显示。Notice delivery 是 at most once：进程故障可能导致 notice 缺失，但不会重试已 claimed、delivered 或 abandoned 的 notice。

Replay、恢复与安全

Pause 和 Resume 仅限同一进程（same-process only）。attempt result settle 且 disposal 排空已接纳的 child 与 scratch work 后，package evaluator 的 quiescent checkpoint 是唯一 replay authority。匹配且已提交的 journal call 会 replay，不再次消耗 agent，也不重复其已提交 effect；observer event 不是 authority。若外部 effect 的结果尚未提交，它可能再次执行，因此 effectful prompt 与 verification step 必须保持幂等。

await_user() 会继续同一个已确认 attempt 并提交该 gate；pause() 不提交，在 replay 后条件仍成立时会重新触发。budget-limited run 不能通过人工 control 恢复：model tool 必须使用内部 resume token，并提供比旧 total 更大且不超过 1,024 的绝对 agent_budget。

进程退出会把每个 retained active row 转换为不可恢复的 Interrupted，取消界面上仍在运行的 member，并且只恢复 inspection data。系统不会跨进程重建 Agent、args、script authority、journal、checkpoint、gate、child reference 或 effect claim；Interrupted run 不能 Resume 或 Save。

version-2 store 位于 $DSH_HOME/workflow-runs。一个永久 .workflow-storage.lock anchor 在 Host 生命周期内持有 native advisory lease；第二个协作进程会收到 workflow storage root is already owned by another live process。descriptor-rooted identity、owner、mode、type 和 link 检查都会 fail closed。该 lease 只协调同一用户下相互协作的 Host；它不能防御以同一 OS 用户运行、忽略 lease 或替换 anchor 的恶意进程。

Workflow script 与现有 model shell access 具有相同的 trust premise。worker 和 node:vm 用于塑造可用 API 并隔离 host event loop，但不是 hostile-code security sandbox。

限制

- Workflow body 是支持 top-level await 的纯 JavaScript；不存在 Rhai language path。
- Workflow script 不提供嵌套 workflow() hook。
- 不提供 cross-process execution resume 或 exactly-once external effect。
- 本包不会以任何形式联系或复用 Grok CLI。
- Validate-only 会编译完整 script，但只执行一个使用 canned output 的 args-selected path；它不覆盖所有 branch、live tool 或所有可能的 agent response。

文档

- 用户指南 — 创建、验证、启动、检查、控制 workflow 并排查故障。
- 架构 — Host/Client composition、lifecycle authority、storage、Remote paging 和 package build。
- 测试与发布验收 — 自动化证据与最终人工 Web checklist。
- 已安装的创作 skill — JavaScript global、schema、budget、scratch 和安全创作模式。
- License 与原生依赖 notice。
- 官方 Harness 0.1.2-rc.1 提供 Host、Agent、Session、provider 与 Client service。Plugin compatibility evaluator 私下拥有 deferred-start、journal、gate、scratch 与 checkpoint protocol。