# dsh-finance-db

**为 DeepSeek Harness 提供只读金融市场数据。让 DSH 直接调用工具查询行情。**

[English](README.md) · [简体中文](README.zh-CN.md)

`dsh-finance-db` 将实时报价、历史价格、基础估值、新闻、股票搜索和数据源健康检查接入 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。

它面向研究和分析流程，而不是交易执行：插件不会下单、转移资金、保存券商凭证，也不会修改投资组合。

## 实际效果

可以直接这样提问：

```text
请查询 600519 的当前行情，只使用 finance_quote，不要改用网页搜索。
```

模型会调用宿主侧工具，并从原始上游数据源获得结构化结果：

![示例：DSH 调用 finance_quote 查询 600519](assest/case.png)

## 核心特点

- **原生 DSH 工具**：模型直接调用金融函数，不需要解析网页或抓取页面内容。
- **直连原始 API**：A 股和港股使用 EastMoney 接口，美股使用 Yahoo Finance chart 接口。
- **只读安全边界**：没有券商接入、交易能力、凭证保存或账户访问。
- **结构化返回**：行情、OHLCV、基础面、新闻和健康状态均返回 JSON。
- **轻量可组合**：内存缓存、清晰的 provider 错误，不要求先部署数据库服务。
- **中英文文档**：当前页面为中文版本，返回 [English](README.md)。

## 可用工具

| 工具 | 用途 | 当前覆盖 |
| --- | --- | --- |
| `finance_quote` | 当前价格、涨跌、成交量、市盈率和时间戳 | A 股、港股、美股 |
| `finance_ohlcv` | 历史开高低收和成交量 | A 股、港股、美股 |
| `finance_fundamentals` | 与行情关联的估值字段和数据源信息 | A 股、港股、美股 |
| `finance_news` | 获取近期金融新闻标题 | NewsNow feed |
| `finance_search_stocks` | 按代码或名称搜索股票 | A 股、港股、美股 |
| `finance_market_overview` | 主要指数及当日变化 | EastMoney 指数 |
| `finance_health` | 检查数据源是否可用 | EastMoney、Yahoo Finance、NewsNow |
| `finance_sentiment` | 情绪分析入口 | 需要挂载本地或 agent provider |

## 更多使用案例

### 1. 查询行情

```text
查询 600519 最新行情，包含市场、数据时间、价格、涨跌额和成交量。
```

### 2. 查看历史走势

```text
获取 AAPL 过去一年的 OHLCV 数据，并总结最高收盘价、最低收盘价和近期方向。
```

### 3. 搜索股票

```text
搜索名称包含 Tencent 的港股公司，返回股票代码、名称和市场。
```

### 4. 结合新闻研究

```text
获取 600519 最新金融新闻，并将新闻标题与 finance_quote 返回的行情分开整理。
```

### 5. 排查数据源

```text
先运行 finance_health。如果某个数据源不可用，说明哪些工具可能受到影响。
```

## 在 DSH 中安装

### 从 npm 安装

```sh
npx @deepseek-ai/dsh plugin --profile web add dsh-finance-db
npx @deepseek-ai/dsh web
```

### 从本地源码安装

```sh
git clone https://github.com/zhiyaoli0221/dsh-finance-db.git
cd dsh-finance-db
npm install
npm run verify
npx @deepseek-ai/dsh plugin --profile web add "$PWD"
npx @deepseek-ai/dsh web
```

如果 DSH Web 已经在运行，重新安装本地插件后请重启 Web 进程，使其重新加载编译后的 `lib/` 文件。

## 数据源与配置

插件直接调用原始上游数据源，不调用 DeepEar/Vercel 代理。

| 能力 | 数据源 | 配置 |
| --- | --- | --- |
| A 股 / 港股行情和历史数据 | EastMoney | 不需要 key |
| 美股行情和历史数据 | Yahoo Finance chart endpoint | 不需要 key |
| 新闻标题 | NewsNow | 不需要 key |
| 可选网页搜索 | Jina Search | 设置 `JINA_API_KEY` |

请求会按能力使用短时内存缓存。命中缓存时不会重新请求上游；排查连接问题时可以先调用 `finance_health`。

## 开发

```sh
npm install
npm run verify       # 构建、测试和 npm 打包检查
npm run dev          # 监听 TypeScript 输出
```

插件运行在宿主侧，通过 `cordis.patch.yml` 挂载，不需要浏览器 bundle 或 UI 注入。

## 范围与后续扩展

第一版聚焦稳定的只读市场数据。源项目中的本地情绪分析、Kronos 预测、信号跟踪、逻辑链可视化、报告生成和本地搜索，并不是远程 API，因此在本插件中保留为可挂载或 agent-side 的扩展，而不是伪装成当前可用的在线能力。

这样可以让故障边界保持清晰：缺少 provider 时返回明确错误，不生成虚假数据。

## 免责声明

本插件提供研究和自动化流程所需的数据，不构成投资、税务、会计或法律建议。上游数据的覆盖范围、时效性、限流策略和可用性可能发生变化。

## License

MIT，详见 [LICENSE](LICENSE)。