dsh-graph-monitor

一个 DSH (DeepSeek Harness) 插件：使用 LangGraph 风格的 GRAPH 工作流（节点 + 边 + 条件路由 + 并行分支 + 结构化 State），执行时每个环节实时点亮。拓扑动画风格参考 Waku-agent 的 dashboard（http://localhost:7777/#graph）。

• GRAPH 可视化：分层拓扑图（START → 节点 → END，每个深度一列），SVG 渲染，与引擎实际执行的拓扑完全一致（防漂移：图 就是 workflow）。
• 实时动画（Waku 风格 hot/live 闪烁）：当前节点紫色脉动、完成节点绿色、失败节点红色、行进边琥珀色高亮。
• 自定义 workflows：设置 → Graph Monitor，JSON 编辑器（节点 / 边 / 条件路由 / fn 处理器），校验后保存并持久化到 ~/.dsh/graph-monitor/workflows/*.json，保存/删除后列表实时刷新。
• 点击节点看详情：状态 / 耗时 / 输入 / 输出 / 错误。
• 对话集成：
  • /workflow（不带参数）列出现有工作流；
  • /workflow <workflow-id> <输入…> 直接在对话中运行并实时可视化 node/edge；
  • 模型工具 graph_monitor_run —— 用自然语言（如「跑一下售后工作流」）触发运行。
• 运行历史：每次运行可回看，含最终输出。
• 健壮轮询：单调游标 + 截断安全事件日志（超过 2000 条后增量推送依然正确）。

说明：节点执行支持两种后端 —— nodeExecutor: simulated（默认，固定延迟 + 模板输出，不真正调用模型/工具）与 nodeExecutor: real（fn / tool / agent / llm 节点绑定 DSH 真实能力，能力缺失自动回退模拟）。详见下方「执行后端」。

---

目录结构

dsh-graph-monitor/
├── lib/index.js          # 宿主半面：GRAPH 引擎 + HTTP API（/graph-monitor/*）
├── lib/chat.js           # 对话集成：/workflow 命令 + graph_monitor_run 工具 + 系统提示
├── lib/client.js         # 客户端半面：监视器页签 + 聊天内嵌卡片 + 设置编辑器
├── test/engine.test.mjs  # 引擎单测（可独立运行，stub Cordis ctx）
├── package.json
├── cordis.patch.yml      # bundle 补丁（nodeDelayMs / llmDelayMs / keepRuns）
├── LICENSE               # MIT
└── README.md

---

依赖

• DeepSeek Harness 运行时：@deepseek-ai/* 服务（sessions / webServer / tools / commands / systemPrompt 等），以 peerDependencies 声明。
• Node.js ≥ 18（ESM）。

---

安装

插件运行在 DSH 的 loopback web server 上，客户端通过普通 fetch() 访问同源 API。二选一：

方式一：desktop profile 手动布放

$dst = "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\graph-monitor"
New-Item -ItemType Directory -Path "$dst\lib" -Force | Out-Null
Copy-Item "package.json" "$dst\"
Copy-Item "README.md" "$dst\"
Copy-Item "cordis.patch.yml" "$dst\"
Copy-Item "lib\index.js" "$dst\lib\"
Copy-Item "lib\chat.js" "$dst\lib\"
Copy-Item "lib\client.js" "$dst\lib\"

然后在 ~\.dsh\profiles\desktop\cordis.patch.yml 的 insert: 列表追加：

    - id: graph-monitor
      name: 'graph-monitor'
      config:
        nodeDelayMs: 750
        llmDelayMs: 950
        keepRuns: 20
        nodeExecutor: real   # "simulated"（默认固定延迟）| "real"（绑定 DSH 真实能力，缺失回退模拟）

方式二：bundle 引用

在 profile 的 package.json 里把 graph-monitor 加入 dsh.profile.bundles（依赖其已存在于共享层 ~\.dsh\profiles\node_modules）：

"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "graph-monitor"] } }

安装完成后必须重启 DSH Desktop，旧会话的工具面在会话创建时固化，需新建会话才生效。

---

使用手册

1. 对话命令 /workflow

在聊天输入框直接输入：

输入	效果
/workflow	列出所有可用工作流（id + 名称 + 描述 + 节点/边数）
/workflow <id> <输入…>	运行指定工作流，结果以实时卡片形式显示在聊天流中
自然语言	模型根据系统提示自动调用 graph_monitor_run 工具

示例：

/workflow
/workflow text-pipeline hello world

2. Graph Monitor 页签

任意会话右侧切到 Graph Monitor 页签：

1. 下拉框选择 workflow；
2. 输入框填写运行输入，点「运行」；
3. 节点逐个点亮（运行中紫、完成绿、失败红，行进边琥珀高亮）；
4. 点击任意节点查看执行详情；
5. 拖动平移画布，Ctrl + 滚轮 缩放；
6. 「运行历史」回看任意一次运行。

3. 设置编辑器

设置 → Graph Monitor：

1. 「新建 workflow」或「编辑」；
2. 编辑 JSON（节点 / 边 / 条件路由 / fn 处理器）；
3. 「校验」确认合法；
4. 「保存」后立即生效并持久化到 ~/.dsh/graph-monitor/workflows/。

---

GRAPH 词汇表

节点类型（kind）

kind	说明
llm	LLM 推理步骤（模拟延迟）
agent	Agent 循环（规划 + 执行）
tool	工具调用（real 模式下 tool 名 + arguments 调用真实工具）
fn	命名处理器函数（目录白名单，绝不 eval）；real 模式可改用内联 JS code
echo	透传
sleep	暂停（用于动画节奏）
parallel	并行扇出到多个下游分支
merge	汇合并行分支后继续
gate	条件放行/拦截：谓词为真透传到 pass，否则走 fail（无 fail 则 run 以 blocked 结束）
switch	多选一分支：按 cases 顺序第一个命中走对应 to，default 兜底（恰好一条）
subgraph	组合子工作流：把已固化套路封装成可复用新原语（graph 嵌套执行）
loop	迭代子图：while 谓词为真时反复执行，maxIterations 硬上限
retry	失败重试子图：内嵌输出以 ERROR 开头即重试，至多 maxAttempts 次
timeout	时间预算子图：ms 预算内完成透传，超时输出 ERROR: timeout...

fn 处理器目录

基础文本：uppercase · lowercase · reverse · wordCount · charCount · trim · slugify · titleCase

客服话术（售前/售后 canned answers）：productAnswer · returnAnswer · warrantyAnswer · repairAnswer · orderAnswer · logisticsAnswer · handoff

天气（高德 Web 服务 API）：weatherCity（解析城市）· amapWeather（实时 + 预报；需配置 AMAP_KEY 环境变量或 ~/.dsh/graph-monitor/amap-key.txt）

在 real 模式下，fn 节点还可改用内联 JS code 字段（优先于 handler 目录）。

条件路由（router）

router	判定
always / otherwise	恒真 / 默认兜底
nonEmpty	输出非空
containsYes / containsNo	输出含 yes/是/true · no/否/false
isShort / isLong	输出 ≤ 40 字符 · > 40 字符
mentionsCode	输出提及 code/代码
human / presales / aftersales	客服意图：人工 / 售前咨询 / 售后问题
returnRequest / warranty / repair / order / logistics	客服细分：退货退款 / 质保保修 / 维修故障 / 下单支付 / 物流
isError	输出以 ERROR 开头（用于失败分支）

内联谓词（source: "code"）

除命名目录 router 外，gate / switch / loop 的谓词（condition / when / while）还支持内联 JavaScript。内联代码经 DSH codeRuntime 执行（绝不 eval），运行时可用 graph.input() 取上游输入、graph.stateGet(key) 读结构化 State，返回值转为布尔；异常 / 空 / 无 codeRuntime 一律按「拦截 / 不命中」处理，不升级为运行失败。

{ "kind": "gate", "condition": { "source": "code", "code": "return (await graph.input()).includes('approved')" } }

workflow JSON 形状

{
  "id": "my-workflow",
  "name": "My workflow",
  "description": "描述",
  "entry": "start-node",
  "nodes": [{ "id": "start-node", "kind": "llm", "label": "开始", "description": "第一步" }],
  "edges": [
    { "src": "START", "dst": "start-node", "label": "start" },
    { "src": "start-node", "dst": "END", "label": "done" }
  ]
}

条件边示例：{ "src": "a", "dst": "b", "conditional": true, "router": "containsYes", "label": "简单" }

---

内置 workflows

workflow id	说明
research-triage	分类请求：简单走小模型快路径，复杂走完整 agent 循环 + 工具
text-pipeline	确定性数据管道：normalize → transform → measure → 长短分流
customer-agent	客服：理解 →（已知→直接回答 | 未知→搜索工具→升级）→ 关闭
parallel-demo	并行分支：fanout → sentiment/entities 并行 → merge → summarize（演示 parallel/merge 与 reads/writesTo 结构化 State）

（可通过设置编辑器自行扩展现有或新建 workflow。）

---

控制流原语（可进化工作流引擎）

插件已从「固定 DAG 可视化」演进为可进化工作流引擎：除线性 llm / agent / tool / fn 节点外，新增六类控制流原语，用 graph 字段嵌套子工作流（子图节点会各自点亮、各自产生事件）：

原语	关键字段	语义
gate	condition / pass / fail	谓词真 → 透传到 pass；假 → 走 fail，无 fail 则 run 以 status:"blocked" 结束（非失败、非继续）
switch	cases[].when/to / default	按 cases 顺序取第一个命中的 to，default 必填保证「恰好一条」
subgraph	graph	组合子图，把已固化套路封装成可复用新原语
loop	while / maxIterations / graph	每轮以子图最终 state 为输入迭代，while 为假退出
retry	maxAttempts / graph	子图输出以 ERROR 开头即重跑，成功即透传
timeout	ms / graph	预算内完成透传，超时输出 ERROR: timeout after {ms}ms

{
  "id": "lp1",
  "kind": "loop",
  "label": "直到收敛",
  "while": { "source": "code", "code": "return (await graph.input()) !== 'done'" },
  "maxIterations": 10,
  "graph": {
    "entry": "step",
    "nodes": [{ "id": "step", "kind": "fn", "code": "return 'done';" }],
    "edges": [{ "src": "START", "dst": "step" }, { "src": "step", "dst": "END" }]
  }
}

模型驱动的编排（mutation ops）

llm / agent 节点可设 emitOps: true，让模型直接决定编排——通过结构化输出产出图编辑指令 ops 数组，引擎先整体校验、后原子应用，并以 graph/mutate 事件反馈结果（含失败原因）：

{ "ops": [
  { "op": "addNode",  "node": { "id": "x", "kind": "fn", "code": "return 'hi';" } },
  { "op": "addEdge",  "edge": { "src": "a", "dst": "x" } },
  { "op": "rewire",   "edge": { "src": "a", "dst": "x" } },
  { "op": "setEntry", "nodeId": "x" },
  { "op": "skip",     "nodeId": "y" }
] }

完整契约（每个原语的输入 / 输出 / 事件 / 边界情形，以及 ops 载荷 schema 与校验不变量）见 docs/primitive-contract.md。

---

执行后端（nodeExecutor）

nodeExecutor 配置键控制节点执行后端：

值	行为
simulated（默认）	固定延迟 + 模板输出，纯可视化演示，不调用任何真实能力
real	fn / tool / agent / llm 节点绑定 DSH 真实能力；能力缺失或执行出错时自动回退到模拟，不会中断运行

real 模式下的节点映射：

• fn —— 可写内联 JS code 字段，通过 codeRuntime.run 执行；运行时可用 input() 取上游输入、stateGet(key) / stateSet(key, value) 读写结构化 State。无 code 时回退到目录 handler。
• tool —— 写 tool（工具名）+ arguments（对象），调用 tools.execute()。
• agent —— 运行 execContext 携带父 Agent 时经 subagents.start() 委派给子代理。
• llm —— 经 llm.stream() 调用模型流式推理。

提示：fn/tool 的真实路径无需运行 execContext，从设置页「运行」即可触发；llm/agent 的真实路径依赖 execContext（通常经对话 /workflow 指令或 graph_monitor_run 工具触发）。

---

配置项

配置键	默认值	说明
nodeDelayMs	750	普通节点模拟执行延迟（动画节奏）
llmDelayMs	950	llm / agent / tool 节点模拟延迟
keepRuns	20	保留的已完成运行记录数（LRU 淘汰）
nodeExecutor	simulated	执行后端：simulated（模拟）| real（绑定 DSH 真实能力，缺失回退模拟）

---

HTTP API

插件在 DSH 的 loopback web server 上注册以下接口（与 web app / 桌面壳同源）：

方法	路径	说明
GET	/graph-monitor/workflows	workflow 列表 + 编辑器目录
PUT	/graph-monitor/workflows	校验并持久化 workflow
POST	/graph-monitor/validate	只校验不保存
POST	/graph-monitor/workflows/:id/run	启动运行（{input, sessionId}）
GET	/graph-monitor/state?cursor=N	增量实时事件日志（游标轮询）
GET	/graph-monitor/runs/:runId	完整运行记录（含每个节点详情）
DELETE	/graph-monitor/workflows/:id	删除自定义 workflow

---

测试

引擎单测用 stub Cordis ctx，不依赖真实 DSH 服务，但需要 @deepseek-ai/* 依赖可解析（通常在 DSH 的共享层 ~/.dsh/profiles/node_modules 内运行）：

# 在 DSH 共享层 node_modules 内运行（以便解析 @deepseek-ai 依赖）
node "$env:USERPROFILE\.dsh\profiles\node_modules\graph-monitor\test\engine.test.mjs"

覆盖：内置 workflow 种子、HTTP 列表 / 运行 / 状态游标、自定义 workflow 保存/校验/删除、fn 处理器、持久化、会话事件。

---

已知限制

• nodeExecutor: real 依赖 DSH 真实能力（codeRuntime / tools / subagents / llm），对应能力缺失或执行出错时该节点回退到模拟。
• llm / agent 的真实路径依赖运行 execContext（经对话 /workflow 指令或 graph_monitor_run 工具触发）；从设置页「运行」的无 execContext 运行只会走 fn(code)/tool 的真实路径，llm/agent 回退模拟。
• fn 的内联 code 仅在 real 模式执行；simulated 模式走 handler 目录（code 被忽略）。
• 插件改动需重启 DSH Desktop；旧会话的工具面在会话创建时固化。
• 运行记录与事件日志在内存中（LRU 上限 keepRuns / 2000 条事件），重启即清空。

---

License

MIT