dsh-intent-network：构建可观测的多跳工具调用意图图

在 DSH 插件生态中，开发者常面临将松散的工具调用串联为复杂工作流的挑战。dsh-intent-network 旨在解决这一问题，它将用户的自然语言意图解析为可编辑、可观测、可学习的多跳工具调用图。

是什么¶

该插件由 helibeiqi 维护，属于工作流类别。其核心职责是将用户意图转化为结构化的执行计划。它消费 CDP（Context Description Protocol）语义，并通过 dsh-cordis-universal-adapter 桥接进来的 mcp::* 工具，构建具备条件分支、依赖关系和回退机制的执行图。

作为 Host 组合层，它与 dsh-cdp-metadata（提供 CDP 语义）和 dsh-cordis-universal-adapter（桥接 MCP 工具）协同工作，三者可同时安装，互不覆盖配置。

核心功能¶

该插件提供以下能力：

意图解析与图化：将用户意图解析为工具调用图。
语义消费：消费 CDP 元数据（如 cdp_tags、boundaries）指导执行。
工具桥接：通过 dsh-cordis-universal-adapter 读取并执行桥接后的 MCP 工具。
流程编排：支持条件分支、节点依赖、回退路径。
规划与执行：
- 规划器策略支持 llm、rule、hybrid。
- 执行器支持并发控制（maxParallel）与循环限制（maxLoops）。
可观测性：支持 Trace 落盘，记录执行路径与决策原因。
学习模式：支持收集 Trace 数据（M1 版本仅收集，不包含算法）。

安装¶

使用以下命令安装插件：

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

配置与启用¶

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

在配置文件中设置以下字段：

sources：指定意图图目录，默认为 ./intents。
planner：
- enabled：是否启用规划器，默认 false 以节省开销。
- strategy：规划策略，支持 llm、rule、hybrid，默认 hybrid。
- fallbackToLLM：规则不足时升级为 LLM，默认 true。
executor：
- maxParallel：限制并行节点上限，默认 4。
- maxLoops：限制循环上限，防止失控，默认 3。
observability：
- enabled：是否落盘 Trace，默认 true。
- logPath：Trace 落盘路径，默认 ./.intent-traces。
learning：
- enabled：M1 模式下默认关闭，仅收集 Trace。

典型用法¶

在 intents 目录下定义意图图文件，例如 analyze_and_report.intent.json。以下示例展示了如何串联数据获取、因果推断、可视化和报告生成，并定义了回退路径：

{
  "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 含干预变量" },
    { "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 节点（相关性分析），不中断整图执行。

注意事项¶

API 演进：DSH 插件生态仍在演进，API 可能随 DSH 版本调整，建议锁定兼容版本。
依赖环境：必须确保 DSH 运行时支持 Cordis 插件机制与相关 Context 注入。
M1 限制：M1 版本不包含学习算法，仅暴露 collectTrace 与空的 suggestOptimizations，模式挖掘在后续版本实现。
LLM 降级：Planner 的 LLM 模式依赖 ctx.llm。若宿主未提供 ctx.llm，策略会降级为 rule。
安全边界：插件不实现沙箱，工具的副作用由宿主环境与工具自身负责。
参数限制：当前节点执行参数为空 {}，参数化输入计划在后续版本补充。

总结¶

dsh-intent-network 提供了一种将意图转化为结构化执行图的机制，通过配置意图文件和回退策略，开发者可以构建稳定且可观测的工作流。对于需要处理复杂工具链调用的场景，该插件提供了清晰的编排视图。