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 提供了一種將意圖轉化爲結構化執行圖的機制，通過配置意圖文件和回退策略，開發者可以構建穩定且可觀測的工作流。對於需要處理複雜工具鏈調用的場景，該插件提供了清晰的編排視圖。