dsh-tool-ths

Readme

# dsh-tool-ths — Tonghuashun (同花顺 / iFinD) connector for DeepSeek Harness

A Cordis plugin that connects DeepSeek Harness agents to Tonghuashun market
data through two channels:

- **`public`** (default, no account): the 10jqka public quote API
  (`d.10jqka.com.cn`) — realtime quotes and daily/weekly/monthly K-lines.
- **`ifind`** (official): the iFinD HTTP API (`quantapi.51ifind.com`) —
  realtime quotes with valuation metrics, history with adjustment, fundamental
  data, trading calendars, announcements, and code conversion. Requires an
  iFinD `refresh_token`.

## Documentation

| Doc | Contents |
| --- | --- |
| [docs/architecture.md](docs/architecture.md) | Architecture, channel comparison, DSH loading, extension guide |
| [docs/tool-reference.md](docs/tool-reference.md) | Full reference for config and all 7 tools |
| [docs/protocol.md](docs/protocol.md) | Wire protocol details, field formats, error codes |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Troubleshooting guide |

## Tools

| Tool | Channel | Purpose |
| --- | --- | --- |
| `ths_status` | both | connection status, token expiry, last error, connectivity probe |
| `ths_quote` | both | realtime quote snapshot (custom indicators on ifind) |
| `ths_kline` | both | history K-line (D/W/M on public; D/W/M/Q/S/Y + adjust on ifind) |
| `ths_basic` | ifind | fundamental indicators (`ths_roe_stock:20241231`) |
| `ths_trade_dates` | ifind | exchange trading calendar |
| `ths_announcement` | ifind | announcement search (with PDF links) |
| `ths_code` | ifind | code/name → THS code conversion |

## Install

Bundle install (needs pnpm):

```bash
dsh plugin --profile web add github:Xiaobai01/dsh-tool-ths   # from GitHub
# restart dsh web
```

Or from a local checkout (needs pnpm):

```bash
dsh plugin --profile web add .
```

Manual install (no pnpm) — copy the package to the profile and insert the
entry in `~/.dsh/profiles/web/cordis.patch.yml`:

```yaml
- insert:
    - id: tool-ths
      name: ./plugins/dsh-tool-ths/index.js
      config:
        channel: public
        refreshToken: ''
        baseUrl: https://quantapi.51ifind.com/api/v1
        timeoutMs: 30000
        retries: 2
        maxCodes: 20
        maxRows: 120
```

The profile patch layer is hot-reloaded by the running GUI (HMR); otherwise
restart `dsh --profile web`.

Security codes: `600519`, `600519.SH`, `sh600519`, `300750`, `830799` (BSE),
`399001` (SZ index). Bare codes infer the market: `6/5/9` → SH, `0/1/2/3` → SZ,
`4/8` → BJ. SH indexes are not available on the public channel.

## Development

```bash
node scripts/smoke.mjs 600519                 # channel smoke test (public)
IFIND_REFRESH_TOKEN=xxx node scripts/smoke.mjs 600519
node scripts/harness.mjs 600519               # apply() with stub registries, calls every tool
```

## Compatibility

| Item | Requirement |
| --- | --- |
| DeepSeek Harness | `0.1.2-rc.1` ~ `0.1.5-rc.1` (verified on 0.1.5-rc.1 and 0.1.2-rc.1) |
| Node.js | `>= 22.19.0` |
| Host services | `tools`, `systemPrompt`, `settings` (all shipped by `dsh-base`) |

## Data source & disclaimer

- The `public` channel uses Tonghuashun's **public web quote endpoint**
  (`d.10jqka.com.cn`) — not an officially supported API. It is intended for
  **personal research only**; endpoint shapes may change without notice.
- The `ifind` channel uses **your own iFinD account**; follow iFinD's terms.
- Market and financial data **belongs to the data providers**. This plugin is a
  client only — it ships **no data** and must not be used to redistribute or
  resell data.
- Outputs are **data and tool results, not investment advice**.

## License

[Apache License 2.0](LICENSE) — free for commercial use, modification and
redistribution; keep the copyright/license notices, state your changes, and
retain the [NOTICE](NOTICE) file. See [CONTRIBUTING.md](CONTRIBUTING.md).