@helibeiqi/dsh-intent-network

Readme

# dsh-intent-network

> 将用户意图解析为可编辑、可观测、可学习的多跳工具调用图，消费 CDP 语义与 adapter 桥接工具。

![CI](https://img.shields.io/badge/CI-passing-green) ![npm](https://img.shields.io/badge/npm-0.1.0-blue) ![License](https://img.shields.io/badge/license-MIT-blue)

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

## 一句话定位

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

## 安装

```bash
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` 生成报告。

```jsonc
{
  "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）

```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