# Sparkles for DeepSeek Harness

Turn [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) into a
finance research assistant for mainland China, Hong Kong, and US markets.

This is the DSH distribution of
[Sparkles](https://github.com/kaiwu/sparkles). Pi users should install the sibling
[@pi-sparkles/pi-sparkles](https://www.npmjs.com/package/@pi-sparkles/pi-sparkles)
package, which reuses the same finance cores but owns separate Pi lifecycle and
terminal presentation.

Requires **DSH 0.2.1-rc.2**, the tested DSH 0.2.1-rc.2 API.
The host and service peers are pinned exactly; other host versions require a separate compatibility review.

Ask about a stock or ETF in everyday language. DSH Sparkles brings current market
data, price history, company filings, fundamentals, and financial calculations
into the conversation.

## What it gives you

- Current quotes and recent price history for supported CN, HK, and US sources.
- Trend, momentum, and volatility analysis with SMA, RSI, and ATR.
- SEC, CNINFO, and HKEXnews filing and disclosure research.
- Fundamental, valuation, portfolio-risk, scenario, event-study, and backtest
  calculations when the required data is available.
- Bounded CN/HK/US transaction-tape packet review, local possible-fill
  simulation, read-only broker evidence review, compound compliance checks,
  non-executable handoffs, and receipt reconciliation.
- Clear source, timestamp, currency, freshness, and data-limit context in answers.
- Responsive SVG OHLCV charts stacked above the floating finance status bar.

DSH automatically looks up current evidence for questions about price, trend,
buying now, or when to sell. You do not need to ask it to "use tools" first.

## Quick start

```sh
npm install -g @deepseek-ai/dsh@0.2.1-rc.2
dsh plugin --profile web add @dsh-sparkles/dsh-sparkles@0.1.17
AGENT_CONTACT="you@example.com" dsh web
```

The bundle patch layer is applied on the next `dsh --profile <name>` boot.
Restart the DSH server after an update; browser refresh alone does not reload
server projections. A chart stays inline until its call is available in the panel.
Uninstall with `dsh plugin --profile <name> remove @dsh-sparkles/dsh-sparkles`.

For most mainland China and Hong Kong quote/history research, and for SEC filing
research, the only setup is a contact address used to identify requests to public
data services:

```sh
AGENT_CONTACT="you@example.com" dsh --profile <name>
```

Then ask naturally:

- `Get a current quote for AAPL.`
- `分析一下科创50ETF的走势`
- `588000 如果现在买，什么时候卖比较好？`
- `分析腾讯 00700.HK 最近半年的趋势、动量和波动`
- `Summarize AAPL's latest SEC fundamentals and cite the evidence.`
- `Compare this portfolio with its benchmark and explain the largest risks.`

## Floating charts

Charts appear above the floating finance status bar, independently of collapsed
tool output. Drag the bar to move the whole group. Hide a card or use its
checkbox under Charts; cards above close the gap against the same floor. The
panel keeps the latest 12 charts, scrolls tall stacks and remembers visibility
separately for each session until reload. Each card is 1.5 times the measured
status-bar width, capped to the screen, with readable axes, pan, zoom and Reset.
Exact text remains in tool output. A result stays inline if its floating panel
is unavailable or its call is outside the retained history.

## Remember picks and schedule checks

Ask Sparkles to remember selected picks in this session. After you accept,
it can save the exact watchlist and schedule a bounded number of reviews at a
chosen interval. Saving alone starts no polling. Reviews run while DSH runs,
without waking a model, and keep source receipts plus interrupted/unknown status.
Choose up to ten picks, 1–30 reviews, intervals of 1 hour–30 days, and an
explicit per-review request budget. Repeated request IDs are idempotent;
changed picks never alter an already scheduled review's pinned snapshot.
CN checks use the explicitly selected Eastmoney source; HK/US are track_partial.
DSH tool policies can deny a source check. Inspect status/history or cancel a
review through conversation; the finance badge shows active or paused reviews.
Saved picks and jobs remain owned by the original session after resume. Bring
picks into a new chat through an explicit snapshot handoff.

## Optional data-service setup

The package loads without provider credentials. Add only the services you want;
you do not need every variable below.

| Variable | What it enables |
| --- | --- |
| `AGENT_CONTACT` | Identified access to supported public services, including Eastmoney, CNINFO, SEC, and HKEXnews. Use one email address everywhere. |
| `TUSHARE_TOKEN` | Optional, rate- and entitlement-limited mainland China stock-identity fallback. It is never required or the first route. Tushare permissions and points apply. |
| `ALPACA_API_KEY_ID`, `ALPACA_API_SECRET_KEY` | Optional Alpaca US prices, bars, news, corporate actions, and assets. Feed permissions apply. |
| `OPENFIGI_API_KEY` | Optional OpenFIGI identity mapping. |
| `TWELVE_DATA_API_KEY` | Optional Twelve Data company profiles. Pass provider `twelve_data` or omit it. |
| `EQUIBLES_API_KEY` | Optional Equibles US company snapshots. Pass provider `equibles`. This is not a Twelve Data fallback. |
| `FRED_API_KEY` | Optional FRED macroeconomic series. |

Example:

```sh
AGENT_CONTACT="you@example.com" \
ALPACA_API_KEY_ID="..." \
ALPACA_API_SECRET_KEY="..." \
dsh --profile <name>
```

Credentials stay in your runtime environment; this package does not write, log,
or persist them. Restart DSH after changing environment configuration because
some adapters initialize at boot.

## Boundaries

Sparkles for DSH is read-only research software: it cannot place, change, or
cancel broker orders. External providers, gateways, SDKs, credentials, and
entitlements remain caller-owned; Sparkles never silently selects or falls back
to another provider. It is not investment, legal, accounting, or tax advice.
See `CONFIGURATION.md` for the complete source and configuration reference.

Version 0.1.17 · T6 · 135 plugin components