前言¶
在 DeepSeek Harness（DSH）里，单次 subagent 委托已经够用；任务一旦拉长、参与者变多，常见问题是：同一条对话里上下文互相渗透，下游发现上游交付不足时往往自行补洞，节点重试或恢复后先前的决策与踩坑记录也随之消失。dsh-agent-graph 把多步任务写成带依赖的 YAML 图，由引擎在会话内通过 /graph 命令调度；每个节点是一次独立的 DSH 子智能体激活，节点之间用结构化 handoff 交接，不足时可向直接上游发起有边界的返工请求，并把进度与决策写入分层全局账本（ledger）。下面介绍它是什么、能做什么，以及如何安装与跑通示例。
这是什么¶
dsh-agent-graph 是社区维护者 wrc093 发布的 DSH 工作流类插件，npm 包名同为 dsh-agent-graph，当前资料中的版本为 0.2.1，许可证 MIT，运行环境要求 Node.js >= 22。一句话定位：在 DSH 会话内对「有范围划分的智能体节点」做图编排——结构化 handoff、有边界的返工（rework）、分层全局 ledger。
插件在 SkillHub 目录 与 GitHub 仓库 均可查阅；目录站点为社区生态索引，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
资料中归纳的能力如下，均对应 README 中的机制说明，而非仅靠提示词约束。
任务分解与校验
用 YAML 描述节点及 needs 依赖边；运行前引擎校验环、未知引用、重复 id 等问题。
节点执行
每个节点激活时执行一次 ctx.subagents.start('spawn', …)，携带范围提示、上游 handoff、ledger 指针和结构化输出 schema。节点之间不共享对话；一次激活只能看到本节点 prompt、直接上游交付和 ledger。
节点间交付
handoff 有固定结构（summary / artifacts / openIssues），注入到每个直接下游的激活上下文。
上游不足时的返工
下游可向直接上游发起有边界的 rework 请求，附带证据与验收标准；上游可提供、拒绝，或按协议逐跳转发。
共享记忆
每次运行对应一份 ledger（README → index → 各节点章节 → 细节），节点读写、引擎确定性再生成；人类或其它智能体均可阅读。
失败与恢复
失败即停（fail-fast）；可用 /graph resume 重试失败或中断的节点。
可观测性
/graph status 与磁盘上的 ledger；激活、handoff、rework 轨迹与索引均落盘。
Web 编排（V2）
安装 Web profile 后，会话标题栏会出现 编排 标签页，提供拖拽 DAG 画布、节点检查器、依赖编辑与图校验（资料中标注为 Visual DAG editor V2）。
与 DSH 内置能力的对比（README 表格摘要）：需要显式依赖、多于两三个参与者、且「谁决定了什么」必须在节点重建后仍可追溯时，更适合用图编排；一两次简单委托仍可用内置 subagent。
安装与启用¶
在 DSH Web profile 下添加插件，安装命令以 README 原文为准：
dsh plugin --profile web add dsh-agent-graph
安装前请自行查看仓库源码与 MIT 许可证；插件以当前 dsh 进程权限运行，与任何 DSH 插件一样，应确认其行为符合你的安全与合规要求。
典型用法¶
图文档与命令入口¶
图在 DSH 会话内通过人类命令 /graph 驱动，而不是作为面向模型的 tool。节点本身是普通子智能体，可使用宿主授予的工具。
仓库自带五节点示例 examples/feature-delivery.yaml，以及无需模型的脚本化 dry run（examples/fake-script.json）。在克隆或下载后的仓库根目录可本地演示：
npm install
npm run demo
真实运行会对同一图启动 live 子智能体，示例输出形态如下（路径以实际 workspace 为准）：
/graph run examples/feature-delivery.yaml
Started run feature-delivery-20260918-024342 (graph "feature-delivery", 5 nodes, concurrency 2).
Ledger: /path/to/workspace/.agent-graph/runs/feature-delivery-20260918-024342
Track with /graph status; nodes are DSH subagents, so this may take a while.
查看运行状态与节点账本¶
/graph status
Run feature-delivery-20260918-024342 — feature-delivery · status completed
activations 7/24 · started 2026-09-17T18:43:42.782Z · finished 2026-09-17T18:43:42.807Z
node state try handoff
implement ok 2 nodes/implement/handoff/v1.md
research ok 1 nodes/research/handoff/v1.md
spec ok 1 nodes/spec/handoff/v2.md
test-plan self_handled 2 nodes/test-plan/handoff/v1.md
tests ok 1 nodes/tests/handoff/v1.md
/graph show test-plan # prints that node's ledger section
示例 dry run 还演示两种 rework 结果：implement 向 spec 索要缺失细节并得到补充（provided）；test-plan 向 implement 请求接口边界遭拒（超出范围）后自行处理（declined → self_handled），交换记录在 requests/ 下。
校验图文件可用仓库脚本（与 demo 同源 CLI）：
npm run validate
适用场景与注意¶
更适合
任务具备真实依赖结构（如调研 → 规格 → 实现 → 测试计划 → 测试），参与者较多，且需要在 retry、resume 或 follow-up 之后保留决策与 handoff 版本。
不必强上
仅一两步委托、无复杂依赖时，内置 subagent 路径更短；与内置 workflow（模型编写的 JS 编排脚本）或 ralph（不可变 goal 迭代）解决的是相邻问题，可按 README 对比表组合选用。
使用注意
- 图执行可能耗时较长，因节点均为 DSH 子智能体。
- 首次节点失败会终止整次 run，需用 /graph resume 恢复。
- Web 编排能力依赖 --profile web 安装；CLI 亦提供 dsh-agent-graph 二进制（见 package.json bin 字段）。
- 数据落盘位置以运行时的 workspace 下 .agent-graph/runs/ 为准；具体限制与故障排查见仓库 README 对应章节。
结尾¶
dsh-agent-graph 用声明式依赖图固定节点边界，用 handoff 与 bounded rework 规范上下游协作，用分层 ledger 保留跨激活的记忆，适合在 DSH 里把「交付一个功能」这类长链路拆成可追踪的多智能体工作流。
- 目录页：https://www.skillhub.cn/plugins/wrc093/dsh-agent-graph
- GitHub：https://github.com/wrc093/dsh-agent-graph
- 中文 README 链接（仓库内）：
README.zh-CN.md
