# DolphinPI

<p align="center">
  <strong>🐬 基于 <a href="https://pi.dev">pi-coding-agent</a> 的 DolphinDB 智能编程助手</strong>
</p>

<p align="center">
  RAG 文档检索 · WebSocket 脚本执行 · 自动错误修复
</p>

---

## 概述

DolphinPI 是一个 pi-coding-agent 扩展包，专为 **DolphinDB** 开发者设计。它集成了两大能力：

| 能力 | 实现 | 说明 |
|------|------|------|
| **RAG 文档检索** | DolphinMind 知识库 | 编写脚本前自动查询官方 API 文档、函数签名和用法示例 |
| **脚本执行验证** | dolphindb WebSocket | 写完脚本直接在服务器上运行验证，即时反馈结果 |

LLM 在生成每行 DolphinDB 代码前都会先检索官方文档，不会凭记忆编造不存在的 API。

## 快速开始

### 1. 安装

```bash
npm install -g dolphinpi
```

一条命令完成安装。`pi` 和 `dolphindb` SDK 自动安装。

### 2. 启动

```bash
dolphinpi
```

### 3. 配置

首次启动后需要配置两项，在 pi 交互界面中运行 `/ddb:config` 完成：

**① DolphinDB 服务器连接** — 输入 DolphinDB 服务器的 Host / Port / User / Password。

**② DolphinMind 账户登录** — 在配置流程末尾选择登录，使用 [dolphindb.cn/think](https://dolphindb.cn/think) 注册的账户（手机号 + 密码）。登录后自动获取 Token，后续 RAG 检索无需重复操作。

> 💡 也可以用环境变量一次性配完，见 [环境变量](#环境变量)。

### 4. 验证

```
/ddb:doctor
```

一键检查：DDB WebSocket 连接 → DolphinMind API 状态。

### 5. 开始编程

```
用户: 帮我写一个 DolphinDB 因子回测脚本

LLM 自动流程:
  dolphindb_search("因子回测最佳实践")
       ↓
  基于文档生成脚本
       ↓
  dolphindb_execute(script)
       ↓
  ✅ 执行成功 / ❌ 报错 → dolphindb_search(错误信息) → 修复 → 重新执行
```

## 其他安装方式

```bash
# curl 一键安装
curl -fsSL https://dolphindb.cn/install-dolphinpi.sh | sh

# 开发者本地安装
git clone ... && cd DolphinPI && npm install -g .
```

## 命令

| 命令 | 功能 |
|------|------|
| `/ddb:config` | 交互式配置 DolphinDB 连接 + DolphinMind 登录 |
| `/ddb:doctor` | 诊断：配置、DDB 连接、DolphinMind API 状态 |

### `/ddb:config` 交互流程

**首次配置**，依次输入：
1. DolphinDB 连接 — Host / Port / User / Password
2. 保存位置 — 项目级 (`<cwd>/.dolphinpi/config.json`) 或全局级 (`~/.dolphinpi/config.json`)
3. DolphinMind 登录 — [dolphindb.cn/think](https://dolphindb.cn/think) 账户（手机号 + 密码）→ 自动获取 JWT Token

**已有配置**时显示菜单：Modify DDB | Login Mind | View JSON | Test DDB | Cancel

## LLM 工具

| 工具 | 触发场景 | 功能 |
|------|---------|------|
| `dolphindb_search` | 写代码前 / 报错后 / 询问 API | 从 DolphinDB 官方知识库检索文档，返回 Markdown |
| `dolphindb_execute` | 写完脚本需要验证 | WebSocket 在服务器上执行脚本，返回结果 |

## 架构

```
┌─────────────────────────────────────────────────────────┐
│                      DolphinPI                          │
│                                                         │
│  ┌──────────────────┐  ┌─────────────────────────────┐ │
│  │ dolphindb_search │  │      dolphindb_execute      │ │
│  │                  │  │                             │ │
│  │ HTTP multipart   │  │    WebSocket (dolphindb)    │ │
│  │       ↓          │  │             ↓               │ │
│  │ DolphinMind API  │  │    DolphinDB Server         │ │
│  │ :8007            │  │    ws://host:port           │ │
│  └──────────────────┘  └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```

**设计决策：**
- RAG 逻辑全部在服务端（DolphinMind）— DolphinPI 只做 HTTP 调用和格式化
- JavaScript 原生连接 — 使用 `dolphindb` npm 包（WebSocket），无 Python 依赖
- 只收集文档，不生成答案 — SSE 流中忽略 LLM 生成的 content，只保留 source 文档片段，最终答案由 pi 的 LLM 生成

## 配置

### 配置文件

优先级：**项目级 > 全局级 > 默认值**

```
<cwd>/.dolphinpi/config.json    # 项目级
~/.dolphinpi/config.json        # 全局级
```

```json
{
  "host": "127.0.0.1",
  "port": 8848,
  "username": "admin",
  "password": "123456",
  "dolphinmindToken": "eyJ...",
  "dolphinmindBaseUrl": "https://dolphindb.cn:8007"
}
```

### 环境变量

设置后首次启动自动写入配置文件，跳过 `/ddb:config` 交互：

| 变量 | 用途 |
|------|------|
| `DOLPHINPI_DDB_HOST` | DolphinDB 主机 |
| `DOLPHINPI_DDB_PORT` | DolphinDB 端口 |
| `DOLPHINPI_DDB_USER` | DolphinDB 用户名 |
| `DOLPHINPI_DDB_PASS` | DolphinDB 密码 |
| `DOLPHINPI_DOLPHINMIND_TOKEN` | DolphinMind JWT Token（跳过登录） |
| `DOLPHINPI_TLS_INSECURE` | 设为 `0` 要求有效证书（默认自动允许自签证书） |

```bash
export DOLPHINPI_DDB_HOST=10.0.0.1
export DOLPHINPI_DDB_PORT=8920
export DOLPHINPI_DDB_USER=admin
export DOLPHINPI_DDB_PASS=123456
export DOLPHINPI_DOLPHINMIND_TOKEN=eyJ...

dolphinpi   # 直接启动，无需 /ddb:config
```

## 项目结构

```
DolphinPI/
├── bin/
│   └── dolphinpi.js                 # CLI 启动器 — TLS + env config + pi 启动
├── install.sh                       # curl 一键安装脚本
├── package.json
├── extensions/dolphinpi/
│   ├── index.ts                     # 主扩展 — 注册工具/命令/事件处理
│   ├── config.ts                    # 配置管理 — 加载/保存/解析 + TLS 处理
│   ├── ddb.ts                       # DolphinDB 连接池 — WebSocket 单例
│   └── dolphinmind.ts               # DolphinMind HTTP 客户端 — 登录 + 检索
└── skills/dolphinpi/
    └── SKILL.md                     # LLM 行为引导 — 何时检索、如何执行
```

### 各模块职责

| 文件 | 行数 | 职责 |
|------|------|------|
| `index.ts` | ~560 | 注册 2 工具 + 2 命令 + 3 事件处理 |
| `config.ts` | ~210 | DolphinDB 连接 + DolphinMind API 配置，TLS 兼容 |
| `ddb.ts` | ~70 | DolphinDB WebSocket 连接池 |
| `dolphinmind.ts` | ~400 | DolphinMind 登录 + SSE 流解析 + 文档片段收集 |
| `SKILL.md` | ~90 | LLM 行为指令 |
| `dolphinpi.js` | ~90 | CLI 启动器 |

## 依赖

| 包 | 版本 | 用途 |
|----|------|------|
| `@earendil-works/pi-coding-agent` | >=0.74 | pi 运行时 + 交互终端 |
| `typebox` | (pi 内置) | 工具参数 Schema |
| `dolphindb` | ^3.1.48 | DolphinDB WebSocket 客户端 |

## License

MIT