@kiwifruit/dsh-scientific-computing

Readme

# DSH-Scientific-Computing

NumPy / SciPy 数学计算工具，以 DSH（DeepSeek Harness）Cordis 插件形式集成到 AI Agent 的工具调用链。

模型可通过 `math_compute` 工具随时发起任意 NumPy / SciPy 运算，返回结构化 JSON 结果。

---

## 目录结构

```
DSH-Scientific-Computing/
├── src/
│   └── index.js              # DSH Cordis 插件（ESM，name/Config/apply）
├── scripts/
│   ├── math_compute_tool.py  # Python 计算引擎（stdin JSON → stdout JSON，安全重构版）
│   ├── run_tests.py          # 30 用例回归测试（含注入防御）
│   └── verify_plugin.py      # 五层验证脚本
├── docs/
│   ├── 集成指南.md            # 权威操作指导（唯一真相源）
│   └── 坑与经验沉淀.md         # 踩坑记录
├── cordis.patch.yml          # 发布版 bundle patch（npm 包名）
├── package.json              # npm 包清单
├── LICENSE                   # GPL-3.0
├── README.md                 # 本文档
└── AGENTS.md / CLAUDE.md     # 项目规范
```

---

## 安装

### 方式一：npm（推荐）

```bash
dsh plugin --profile web add @kiwifruit/dsh-scientific-computing
```

### 方式二：源码直装

```bash
dsh plugin --profile web add file:/你的路径/DSH-Scientific-Computing
```

### 前置条件

- Python 3.8+，已安装 `numpy` 和 `scipy`
- DSH（`dsh` CLI 可用）
- Node.js ≥ 18

```bash
pip install numpy scipy
```

---

## 快速验证

### 1. Python 引擎独立测试

```bash
echo '{"operation":"sum","args":[[1,2],[3,4]],"module":"numpy"}' \
  | python scripts/math_compute_tool.py

# → {"success": true, "result": {"type": "array", "value": 10}}
```

### 2. 全量回归测试

```bash
python scripts/run_tests.py
# PASS: 30/30 all passed
```

> 覆盖数组聚合、线性代数（含 `solve`/`lstsq`）、FFT、优化（lambda）、布尔参数、`keepdims`、注入防御、非法类型。

### 3. 插件合规验证

```bash
python scripts/verify_plugin.py
```

---

## 支持的运算

| 类别 | 操作 | module |
|------|------|--------|
| 数组聚合 | `sum`, `mean`, `std`, `var`, `min`, `max`, `argmin`, `argmax`, `cumsum`, `prod`, `trace` | `numpy` |
| 线性代数 | `inv`, `det`, `eig`, `eigvals`, `svd`, `qr`, `norm`, `pinv`, `solve` | `numpy.linalg` |
| 信号处理 | `fft`, `ifft`, `rfft`, `irfft`, `fft2`, `ifft2`, `fftfreq` | `numpy.fft` |
| 矩阵乘法 | `dot`, `matmul` | `numpy` |
| 优化 | `minimize`, `linprog`, `least_squares`, `root` | `scipy.optimize` |
| 其他 | `norm` | `scipy.linalg` |

### Lambda 函数传参

优化类操作需要传 lambda，须用**字符串**形式：

```json
{
  "operation": "minimize",
  "module": "scipy.optimize",
  "kwargs": {
    "fun": "lambda x: x[0]**2 + x[1]**2",
    "x0": [1, 0]
  }
}
```

---

## 配置

通过 `cordis.patch.yml` 或 `config` 参数配置：

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `pythonPath` | `'python'` | Python 解释器路径（系统 PATH 或绝对路径） |
| `enginePath` | 自动解析 | Python 引擎脚本路径；缺省从插件 install 位置自动解析 |

### 覆盖 enginePath

如需使用自定义 Python 脚本：

```yaml
- insert:
    - id: scientific-computing
      name: '@kiwifruit/dsh-scientific-computing'
      config:
        pythonPath: 'python'
        enginePath: 'C:/custom/maths/math_compute_tool.py'
```

---

## 输出格式

### 成功

```json
{
  "success": true,
  "result": {
    "type": "array" | "scalar" | "result" | "other",
    "value": [...]
  }
}
```

### 失败

```json
{
  "success": false,
  "error": "Import error: No module named 'numpy'"
}
```

---

## 通信协议

```
插件 (JS)                    Python 引擎
   │                          │
   │── JSON stdin ──────────→│  module, operation, args, kwargs
   │←── JSON stdout ─────────│  success, result
   │                          │
```

---

## 验证清单

| # | 检查项 | 命令 |
|---|--------|------|
| 1 | 插件已安装 | `dsh plugin --profile web list` |
| 2 | 模块形状合法 | `node -e "import('./src/index.js').then(m=>console.log(m.name))"` |
| 3 | 引擎直连正常 | `echo '{"operation":"sum","args":[[1,2]]}' \| python scripts/math_compute_tool.py` |
| 4 | 完整测试通过 | `python scripts/run_tests.py` |
| 5 | 合规验证通过 | `python scripts/verify_plugin.py` |

---

## 发布到 npm

```bash
npm publish --access public
```

---

*最后更新：2026-08-26*