DAG 工作流编排 LouisHaoL/dsh-homerail-dag

dsh-homerail-dag

DeepSeek Harness（DSH）插件：把 HomeRail 的 DAG 工作流编排引擎移植为 DSH 会话可用的 dag_ 工具集 —— AI 写 YAML 编排文件、后台启动 run、跟进进度；节点可以离线确定性执行、跑宿主命令，或跑在 WSL Docker 容器 里。

English: a DeepSeek Harness plugin that ports HomeRail's DAG orchestration
engine into standalone dag_ tools — the agent authors YAML workflow files, starts background runs, and tracks progress; nodes run deterministically, as host commands, or inside WSL Docker containers.

参考项目 / Reference & Acknowledgements

本项目是 HomeRail（作者 xiaotianfotos）DAG 引擎的移植衍生作品，遵循其 MIT 许可证。HomeRail 是一个把一次性 agent 对话变成可审计、可复用工作流的 TypeScript 运行时，其「DAG 运行时」是本插件的直接来源。

This project is a port/derivative of
HomeRail (by
xiaotianfotos), used under its MIT
license. HomeRail is a TypeScript runtime that turns one-off agent chats
into auditable, reusable workflows; its DAG runtime is the direct source of
this plugin.

具体移植自 HomeRail 的部分（homerail_manager/src/orchestration/）：

| HomeRail 源文件 | 本插件对应 | 说明 |
| dag-engine.ts（606 行纯函数状态机） | src/core/dag-engine.ts | 忠实移植：handoff/failNode/_tryPromote/_skipDependentNodes/loop 唤醒/join 仲裁等全部核心转移语义 |
| graph-validator.ts | src/core/graph-validator.ts | 环检测、悬空引用、网关规则、不可达/死端诊断 |
| yaml-loader.ts | src/core/yaml-loader.ts | YAML 模板解析（node.in:port 路由语法、失败端口推断、loop 源检测） |
| graph.ts（类型） | src/core/types.ts | 图数据模型（裁剪子集） |
| runtime/active-runs.ts（网关求值） | src/runtime/gateway-eval.ts | condition/join/while/foreach 的同步求值语义 |
| homerail_worker/src/agent/deterministic.ts | src/runtime/runners.ts | DeterministicClient 的 HANDOFF port=… content=… 指令解析 |

有意未移植的部分（HomeRail 的服务化/体验层）：Manager/Node/Worker 三服务与 WebSocket 控制面、SQLite 持久化（改为 JSON 文件）、语音面、生成式 UI、 agent harness 适配器（claude-sdk/codex/kimi）、scorecard/eval 评估器、 broker/state/approval/fanout/await_command 网关。本插件把执行面收敛为三种 runner（deterministic / host / docker），调度与状态机语义与 HomeRail 保持一致。

移植差异的完整清单见 DIFF.md。

工具一览

| 工具 | 作用 |
| dag_run | 校验 YAML（文件路径或内联字符串）并在后台启动一个 run，立即返回 run_id（job id）。支持 runtime profile。 |
| dag_status | 查看 run 快照：整体状态、每节点状态（PENDING/READY/RUNNING/COMPLETED/FAILED/CANCELLED/SKIPPED）、事件与 handoff 计数、终态判定。 |
| dag_list | 列出 state 目录下全部 run（active/completed/failed/cancelled）。 |
| dag_events | 读取 run 事件流（可 after_seq 增量、可按节点过滤），用于细粒度跟进。 |
| dag_cancel | 取消一个活动 run（READY/RUNNING→CANCELLED，PENDING→SKIPPED）。 |
| dag_templates | 列出插件自带示例模板（two-node / fanout-join / docker-pipeline / while-loop）。 |

dag_run 是长任务：它通过 DSH 的 jobs 系统后台执行（kind dag），返回 job id 供
job_output(wait: true) 等待或让完成通知唤醒；dag_status 随时可查中间进度。

YAML 格式（HomeRail 兼容子集）

name: my-workflow
workflow_id: my-workflow # 稳定标识 description: "..." image: ubuntu:22.04 # docker 节点的默认镜像 executor: docker # 工作节点默认执行器（deterministic|host|docker）

agents: # deterministic 节点的人格（HANDOFF 指令从 system 提取） drafter: system: | You are the drafting node. HANDOFF port=drafted content=Draft checklist: 1. scope 2. build 3. test

nodes:
draft:
agent: drafter
after: [] # 完成依赖（控制边）
outputs:
drafted:
to: "review.in:draft" # 数据边：review 节点 in:draft 端口

review:
agent: reviewer
after: [draft]
outputs:
approved:
to: "" # 终边：run 成功结束

gather: # 网关节点：join / condition / while / loop(foreach) type: join
after: [a, b]
gateway_config: { mode: all }
outputs:
passed: { to: "review.in:gathered" }

build: # 命令节点（宿主或容器） type: command executor: docker # 缺省时：有 image→docker，否则 host gateway_config: command: echo hello > /workspace/out.txt timeout_ms: 60000 success_port: done failure_port: failed outputs:
done: { to: "" }
failed: { to: "" }

语义要点（与 HomeRail 一致）：

- after 是纯完成依赖（label: after_dep 控制边）；outputs.to 的 node.in:port 是数据路由；to: "" 是终边。
- 端口名 failed/failure/rejected/error/blocked/stale（不区分大小写）自动视为 on_failure 路由；也可显式 condition: on_failure|always。
- 状态机：PENDING → READY → RUNNING → COMPLETED|FAILED|CANCELLED|SKIPPED； loop source 节点在循环存活期保持 RUNNING。
- join（all/any/n_of_m）、condition（routes 表路由）、while（8 种比较符 + max_iterations 有界循环 + exhausted 端口）、loop/foreach（items 数组展开）。
- 失败传播：失败节点的 on_success 下游若无替代路径则递归 SKIPPED。
- 一个 run 的全部节点共享 /runs//workspace/（docker 容器挂载为 /workspace），文件沿 DAG 流动。

执行器（executor）

| executor | 行为 |
| deterministic | 不调模型：从 agent system 提取 HANDOFF port= content= 指令并直接 handoff（HomeRail DeterministicClient 语义）。离线冒烟/模板示例用。 |
| host | 宿主机执行 gateway_config.command：数组形式=直接 spawn（无 shell）；字符串=shell 片段（POSIX 经 sh -lc；Windows 经 wsl sh -lc）。 |
| docker | 经 wsl docker run --rm -v :/workspace（Windows）或 docker run（POSIX）在容器里执行命令；Windows 路径自动经 wslpath 转换。 |

runtime profile（兼容 HomeRail） yaml runtime_profiles: offline-deterministic: agents:
"": { agent_type: deterministic }

dag_run 传 profile: offline-deterministic 即全图确定性执行。

安装 sh
dsh plugin --profile web add dsh-homerail-dag # from npm (once published)
dsh plugin --profile web add link:D:/workspace/dsh/dsh-homerail-dag # local dev

从源码（本仓库）安装需先构建（pnpm install && pnpm build 产出 lib/），
再 dsh plugin --profile add link:。安装后重启 profile （或刷新会话），agent 即获得 dag_ 工具与使用宣告。

配置（cordis.patch.yml）

| 键 | 默认 | 说明 |
| stateDir | .homerail-dag | run 状态根（会话工作区内；绝对路径亦可）。 |
| dockerImage | ubuntu:22.04 | docker 节点缺省镜像。 |
| dockerCommand | 平台自适应 | ["wsl","docker"]（Windows）/ ["docker"]。 |
| wslPathHelper | 平台自适应 | ["wsl","wslpath"]（Windows）/ null。 |
| maxConcurrency | 8 | 并发 RUNNING 工作节点上限。 |
| nodeTimeoutMs | 300000 | host/docker 节点缺省超时。 |
| maxEdgeTraversals | 3 | 反馈边遍历上限（防死循环，HomeRail 默认值）。工作流可在 YAML 里用 limits: { max_edge_traversals: N } 覆盖（插件级配置优先）。注意 while/foreach 循环每轮 body→网关反馈消耗 1 次预算，max_iterations 大于预算时需调高。 |

开发 sh
pnpm install
pnpm build # tsc -> lib/
pnpm test # node --test test/ (core / runtime / plugin 三层)

目录：src/core/（引擎纯函数：types / dag-engine / graph-validator / yaml-loader，移植自 HomeRail）、src/runtime/（executor 调度 + runners： deterministic / host / docker + 文件持久化）、src/tools.ts + src/index.ts （Cordis 插件入口 + dag_* 工具注册）、examples/（4 个示例模板）。

已知限制

- 活动 run 不跨进程恢复（进程内调度；引擎状态落盘 engine-state.json 供检视，重启后历史 run 仍可 dag_status/dag_events 读取）。
- HomeRail 的 broker/state/approval/fanout/await_command 网关未移植。
- docker runner 的镜像拉取时间计入节点超时。

License

MIT。src/core/ 与 src/runtime/gateway-eval.ts、deterministic 指令解析衍生自 HomeRail（MIT）。