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
/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）

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）

内联谓词（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 字段嵌套子工作流（子图节点会各自点亮、各自产生事件）：

{
  "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](docs/primitive-contract.md)。

---

执行后端（nodeExecutor）

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

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 / 桌面壳同源）：

---

测试

引擎单测用 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](LICENSE)