dsh-dcs-engine

Readme

# dsh-dcs-engine (DCS)

> Dynamic Capability Synthesis Engine — 在运行时把零散基础工具**合成**为可命名、注册、复用、持久化的 DSH Capability。

[![CI](https://img.shields.io/badge/CI-passing-green)](https://github.com/helibeiqi/dsh-dcs-engine/actions)
[![npm](https://img.shields.io/badge/npm-dsh--dcs--engine-blue)](https://www.npmjs.com/package/dsh-dcs-engine)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

---

## 定位

`dsh-dcs-engine`（DCS）是 DSH 协议栈的 **Host 组合层**，同时是五件套的 **消费方与演示载体（credit engine）**：

- **CDP**（`ctx.cdpRegistry`）— 消费语义（cognitive_style / semantic_tags / boundaries）做候选打分，不定义元数据
- **意图网络**（`ctx.intentNetwork`）— 复用其 `plan()`，否则内置 rule 拓扑规划，不替代编排
- **CSP**（`ctx.cspStore`）— 仅写入 `decision_trace`，不描述思考
- **ASP**（`ctx.aspGuard`）— 注册前强制过审 side_effects，不自行审查
- **universal-adapter** — 仅消费其桥接进 `ctx.tools` 的 `mcp::*` 工具，不桥接

> DCS **正交协同**，不替代任何一件——它把既有的五件套"真正用起来"，并证明这套协议栈"被用起来"后能产生什么。

## 版本区间与警告

- **DSH 版本区间**：`@deepseek-ai/cordis >= 0.1.0`、`@deepseek-ai/dsh-tools >= 0.1.0`
- ⚠️ **Developer Preview**：M2 阶段 `materializer` 已可生成完整可部署的 `dsh-cap-<id>` 插件骨架（含 package.json / tsconfig.json / cordis.patch.yml / .cdp.json / capability.json / README.md / src/index.ts）；合成策略默认 `rule`（零 LLM）。
  接口在 0.1.x 内可能变动，生产用途请等待 1.0 稳定版。

## 安装

```bash
# 从 GitHub 安装
dsh plugin --profile web add github:helibeiqi/dsh-dcs-engine

# 从 DSH 插件 registry 安装
dsh plugin --profile web add dsh-dcs-engine

# 本地路径安装
dsh plugin --profile web add "file:./dsh-dcs-engine"
```

## 配置字段

| 字段 | 说明 | 默认 |
|------|------|------|
| `sources` | 基础件来源，`capabilitiesDir` 产物/示例目录 | `{ capabilitiesDir: "./capabilities" }` |
| `synthesizer` | 合成策略 `strategy`(rule/llm/hybrid)、`fallbackToLLM`、`maxCandidates` | `{ strategy: "rule", fallbackToLLM: true, maxCandidates: 20 }` |
| `registry` | `deduplicate`(语义哈希去重)、`autoRegisterTools`(defineTool 包装) | `{ deduplicate: true, autoRegisterTools: true }` |
| `materializer` | `enabled`(M2 完整插件骨架)、`format`(当前仅 `plugin-skeleton`) | `{ enabled: false, format: "plugin-skeleton" }` |
| `safety` | `requireAsp`(无 ASP 拒绝)、`blockOnFail`(不通过拒绝注册) | `{ requireAsp: true, blockOnFail: true }` |

> ⚠️ 配置**仅**识别上述五个字段。禁止 `servers` / `pluginDirs` / `export` / `router` / `naming` / `schema` 等。

## 端到端示例

**意图**：「分析 AAPL 下跌原因并生成中文报告」

1. DCS 取基础件池：`dsh-quant-data-mcp::quote` + 外部因果推断 `mcp::causal_inference` + `docx_gen::create`
2. 内置 rule 规划 `input → transform → output` 拓扑，生成 `stock_causal_report` CapabilitySpec
3. 过 `ctx.aspGuard`（`side_effects: ["write-file"]` → `verdict: pass`）
4. 注册为 `capabilityRegistry` 并以 `defineTool` 暴露
5. 调用：

```ts
const registry = ctx.get('capabilityRegistry');
const spec = await registry.synthesizeAndRegister('分析 AAPL 下跌原因并生成中文报告');
const report = await registry.invoke(spec.id, { symbol: 'AAPL' });
```

**导出骨架**（`--persist` 触发 materializer）：

```bash
npx tsx scripts/dcs-synthesize.ts --intent "分析 AAPL 下跌原因并生成中文报告" --persist
# → capabilities/stock_causal_report.capability.json
```

## 安全说明

- 合成产物注册前**必须**过 `ctx.aspGuard`；`verdict=fail` 且 `safety.blockOnFail` 时抛 `SynthesisRejectedError`。
- 无 ASP 且 `safety.requireAsp=true` 时拒绝注册（安全优先，`asp_verdict: unknown`）。
- `side_effects` 在 `cdp` 与 `safety` 两处对齐，供审查留痕。
- 所有文件 IO 经路径白名单（仅 `capabilitiesDir` / `outDir`）。

## 已知局限

- 合成策略默认 `rule`（零 LLM 开销）；`hybrid` / `llm` 依赖 `ctx.llm` 签名（best-effort，不强制）。
- `materializer` 生成的 `src/index.ts` 使用通用输入映射（`{ ...userInput, ...predecessorOutputs }`），需人工 refine 各步工具的精确参数 schema 与 guard 接线。
- 无 CDP 时退化为关键词匹配，语义精度有限。
- 无 ASP 时 `safety.asp_verdict = "unknown"`，`requireAsp: true` 下会拒绝注册。

## License

[MIT](./LICENSE)