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 含干预变量" },
    { "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 做相关性分析替代因果推断"
  }
}

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

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

IntentTrace 示例（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）。

开发

npm install
npm run typecheck   # tsc --noEmit
npm run lint
npm run test
npm run build

License

MIT