意图调用图 helibeiqi/dsh-intent-network

dsh-intent-network

把用户意图解析成一张多跳工具调用图，可编辑、可观测、可学习；消费 CDP 语义，桥接 adapter 工具。

[!] Developer Preview：DSH 插件生态还在演进，API 可能随 DSH 版本调整。建议锁定 DSH 兼容版本（见下方版本区间）。

一句话定位

把「用户一句话需求」变成一张工具调用图，可编辑、可审计、能自我改进 —— 节点是 DSH 已注册工具（含经 dsh-cordis-universal-adapter 桥接进来的 mcp:: 工具），边是条件分支 / 依赖 / 回退，语义来自 dsh-cdp-metadata 的 CDP 元数据。

安装

dsh plugin --profile web add github:helibeiqi/dsh-intent-network
dsh plugin --profile web add dsh-intent-network
dsh plugin --profile web add "file:./dsh-intent-network"

协同关系（与已有两插件正交，不打架）

本插件是 Host 组合层，与以下插件协同，互不侵入：

| 插件 | 职责 | 与 intent-network 的关系 |
| dsh-cdp-metadata | 提供 CDP 语义（downstream_hints / semantic_tags / boundaries） | intent-network 消费其 ctx.cdpRegistry（optional 降级） |
| dsh-cordis-universal-adapter | 桥接外部 MCP 工具为 mcp:: | intent-network 通过 ctx.tools.schemas() 读取这些桥接工具 |
| dsh-intent-network | 意图图编排 / 执行 / 可观测 / 学习 | 不定义 CDP、不桥接 MCP，仅消费前两者 |

三者可同时安装，互不覆盖配置。

DSH 版本区间

- 需要 DSH 运行时支持 Cordis 插件机制与 ctx.tools / ctx.cdpRegistry 注入。
- 兼容 @deepseek-ai/cordis >= 0.1.0、@deepseek-ai/dsh-tools >= 0.1.0。
- @deepseek-ai/cdp-metadata 为可选依赖（peerDependenciesMeta.optional）。

配置字段

插件 config（写于 ~/.workbuddy/mcp.json 的插件配置项或宿主注入）：

| 字段 | 子项 | 说明 | 默认 |
| sources | intentsDir | 意图图目录 | ./intents |
| planner | enabled | 是否启用规划器 | false（零 LLM 开销） |
| planner | strategy | llm / rule / hybrid | hybrid |
| planner | fallbackToLLM | rule 命中不足时升级 LLM | true |
| executor | maxParallel | 并行节点上限 | 4 |
| executor | maxLoops | 循环上限防失控 | 3 |
| executor | abortable | 支持 AbortSignal 取消 | true |
| observability | enabled | 是否落盘 trace | true |
| observability | logPath | trace 落盘路径 | ./.intent-traces |
| observability | format | markdown / json | markdown |
| learning | enabled | M1 关闭，仅收集 | false |

注意：本插件 不 使用 servers / pluginDirs / export / router / naming / schema 字段。

端到端示例

用 intents/analyze_and_report.intent.json 串起： dsh-quant-data-mcp（历史数据）→ 外部因果推断 MCP（因果归因）→ dsh-excel-kit（可视化）→ docx 生成报告。

{
"id": "analyze_and_report@v1",
"intent": "分析标的下跌原因并生成中文报告",
"nodes": [
{ "id": "fetch", "tool": "mcp::quant:get_history", "cdp_tags": ["historical_pattern"] },
{ "id": "attribute", "tool": "mcp::causal:infer", "cdp_tags": ["causal_estimate"],
"guard": "boundaries.can 含因果推断" }, { "id": "visualize", "tool": "dsh:excel-kit", "cdp_tags": ["quantitative_metric"],
"depends_on": ["fetch"] },
{ "id": "report", "tool": "docx_gen", "cdp_tags": ["reportable"],
"depends_on": ["attribute", "visualize"] }
],
"edges": [
{ "from": "fetch", "to": "attribute", "when": "data 含干预变量" },json { "from": "fetch", "to": "visualize", "when": "默认" }, { "from": "attribute", "to": "report", "when": "tag=causal_estimate" }, { "from": "attribute", "to": "__human_review__", "when": "tag=limitations 或 archetype=advisor" } ],
"fallbacks": {
"attribute->visualize": "使用 dsh-excel-kit 做相关性分析替代因果推断" } }

回退路径：当 attribute（因果推断）失败，或没有干预变量时，按 fallbacks 退到相关性分析（visualize），不中断整图。

人工门：当 attribute 节点 CDP archetype=advisor 或 side_effects=irreversible 时，执行到该节点会暂停并返回 ConfirmationRequired，待用户确认后才继续 —— 绝不放行不可逆操作。

IntentTrace 示例（markdown） markdown

IntentTrace: analyze_and_report@v1

- 状态: success
- 总耗时: 412 ms
- 执行路径: fetch → visualize → attribute → report

| 节点 | 工具 | CDP tags | 决策原因 | 耗时(ms) | 状态 | 回退 |
| fetch | mcp::quant:get_history | historical_pattern | 节点执行成功 | 120 | done | - |
| visualize | dsh:excel-kit | quantitative_metric | 节点执行成功 | 88 | done | - |
| attribute | mcp::causal:infer | causal_estimate | 节点执行成功 | 156 | done | - |
| report | docx_gen | reportable | 节点执行成功 | 48 | done | - |

已知限制

- M1 不含学习算法：learning.ts 仅暴露 collectTrace() 与空 suggestOptimizations() 桩，模式挖掘在 M2 实现。
- planner LLM 模式依赖 ctx.llm 实际签名：若宿主未提供 ctx.llm，即使 strategy=llm 也会降级为 rule（hybrid 下 fallbackToLLM 同理）。
- 本插件 不实现沙箱，工具副作用由宿主环境与工具自身负责。
- 节点执行参数当前为空（{}）；参数化输入计划在后续版本补充（见 docs/DESIGN.md）。

开发 bash
npm install
npm run typecheck # tsc --noEmit
npm run lint
npm run test
npm run build

License

MIT