dsh-finance-db

Readme

# dsh-finance-db

**Read-only market data for DeepSeek Harness. Ask about a stock, and let DSH call the data tools directly.**

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

`dsh-finance-db` brings practical finance data tools into [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): live quotes, historical prices, basic fundamentals, news, stock search, and market health checks.

It is designed for analysis workflows—not trading. The plugin never places orders, moves money, stores broker credentials, or mutates a portfolio.

## See it in action

Ask naturally:

```text
Get the current quote for 600519. Use finance_quote only and do not browse the web.
```

The model calls the host-side tool and receives structured data from the original upstream provider:

![Example: DSH calling finance_quote for 600519](assest/case.png)

## Why this plugin?

- **Native DSH tools** — the model can call finance functions instead of parsing pages or scraping rendered HTML.
- **Direct upstream APIs** — A-share and Hong Kong data use EastMoney endpoints; US market data uses Yahoo Finance chart endpoints.
- **Read-only by design** — no broker integration, trading action, credential storage, or account access.
- **Structured results** — quotes, OHLCV rows, fundamentals, news items, and health status are returned as JSON.
- **Small and composable** — in-memory caching, provider errors, and no required database service for the first release.
- **Bilingual documentation** — this page is the default English entry point; see [简体中文](README.zh-CN.md).

## Available tools

| Tool | What it does | Current coverage |
| --- | --- | --- |
| `finance_quote` | Current price, change, volume, PE, and timestamp | A-share, HK, US |
| `finance_ohlcv` | Historical open/high/low/close/volume data | A-share, HK, US |
| `finance_fundamentals` | Quote-linked valuation fields and provider metadata | A-share, HK, US |
| `finance_news` | Recent finance headlines from NewsNow | NewsNow feeds |
| `finance_search_stocks` | Find a ticker by code or name | A-share, HK, US |
| `finance_market_overview` | Major indices and daily changes | EastMoney indices |
| `finance_health` | Check provider availability | EastMoney, Yahoo Finance, NewsNow |
| `finance_sentiment` | Sentiment entry point | Requires a mounted local/agent provider |

The tool names are intentionally explicit, so prompts can be precise when needed:

```text
Call finance_ohlcv for AAPL over 1 year and summarize the price range.
Call finance_news for 600519 and list the five newest headlines.
Run finance_health before using market data.
```

## More use cases

### 1. Quote lookup

```text
What is the latest quote for 600519? Include the market, provider timestamp, price, change, and volume.
```

### 2. Historical context

```text
Get 1-year OHLCV data for AAPL and summarize the highest close, lowest close, and recent direction.
```

### 3. Stock discovery

```text
Search for Hong Kong-listed companies matching "Tencent" and return the ticker and company name.
```

### 4. News-assisted research

```text
Fetch the latest finance news for 600519. Separate headlines from the data returned by finance_quote.
```

### 5. Provider diagnosis

```text
Run finance_health. If a provider is unavailable, explain which data tools may be affected.
```

## Install in DSH

### From npm

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

### From a local checkout

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

If DSH is already running, restart the web process after reinstalling the local plugin so it reloads the compiled `lib/` files.

## Providers and configuration

The plugin calls the original upstream providers directly. It does not call a DeepEar/Vercel proxy.

| Capability | Provider | Configuration |
| --- | --- | --- |
| A-share / HK quote and history | EastMoney | No key required |
| US quote and history | Yahoo Finance chart endpoint | No key required |
| Headlines | NewsNow | No key required |
| Optional web search | Jina Search | Set `JINA_API_KEY` |

Requests are cached in memory for short, capability-specific TTLs. A cache hit does not make a fresh upstream request; use `finance_health` when diagnosing connectivity.

## Development

```sh
npm install
npm run verify       # build, tests, and package dry-run
npm run dev          # watch TypeScript output
```

The plugin is host-side and mounts through `cordis.patch.yml`; it does not require a browser bundle or UI injection.

## Scope and roadmap

This first release focuses on dependable read-only market-data plumbing. The source project also contains local workflows for sentiment, Kronos prediction, signal tracking, logic-chain visualization, reporting, and local search. Those workflows are not remote APIs, so they remain provider-mounted or agent-side extensions rather than pretending to be available through this package.

That boundary keeps failures explicit: a missing provider returns a clear provider error instead of fabricated data.

## Disclaimer

This plugin provides data for research and automation workflows. It is not investment, tax, accounting, or legal advice. Upstream coverage, freshness, rate limits, and availability can change.

## License

MIT. See [LICENSE](LICENSE).