dsn-finance

Readme

# DSH Finance

> 让 DeepSeek Harness 从“查一条行情”走向“看懂市场、管理组合、组织研究”。

[English README](./README.en.md) · [MIT License](./package.json)

DSN Finance 是一个面向 DeepSeek Harness 的金融插件：它把 A 股、港股、美股、基金、宏观数据和财经新闻接入模型，同时提供一个可停靠的本地金融面板。行情通过公开 HTTP 接口直连，持仓和自选股保存在本地 JSON 中，适合个人研究、组合复盘和多智能体协作。

<img width="1331" height="804" alt="DSN Finance panel" src="https://github.com/user-attachments/assets/3fa063b1-22ef-404b-8fb9-1d230b7e66c0" />

## 你可以用它做什么

- **跨市场看行情**：A 股、港股、美股和公募基金的报价、K 线、列表与代码解析。
- **从数据到判断**：本地计算 MA、MACD、RSI、KDJ；查询财务指标、市场指数和行业板块。
- **跟踪市场叙事**：读取中国 CPI/PPI/PMI/GDP/M2、市场电报、个股新闻，并通过 DuckDuckGo 免费搜索网页。
- **管理自己的组合**：维护持仓和自选股，计算市值、盈亏、资产类型/市场分布，以及 top1、top3 和 HHI 集中度。
- **用研究团队拆解问题**：内置行情、基本面、宏观、基金、消息和风险管理 playbook，可交给 DSH subagent 并行研究后汇总。

## 核心体验

### 一个面板，十个视角

从侧边栏打开 **📈 金融面板**，可在以下标签页之间切换：

| 标签页 | 内容 |
| --- | --- |
| 行情 | 指数、自选股走势、迷你 K 线和实时刷新 |
| 市场 | 领涨/领跌行业板块，快速定位当日风险 |
| 持仓 | 持仓盈亏、组合市值、股票/基金配置和集中度 |
| 基金 | 开放式基金排行、净值和加入自选 |
| K线 | 本地历史库日 K 线，财报/分红/自定义事件标记 |
| 宏观 | CPI、PPI、PMI、GDP、货币供应量及趋势 |
| 快讯 | 全球财经电报，以及按持仓/自选筛选的个股新闻 |
| 数据源 | 按 capability 选择 provider，选择顺序即调用优先级 |
| 技能 | 本地 playbook 与盈米金融场景 skill 的启停管理 |
| 接口 | 数据源健康状态与当前 provider、MCP 外部源开关 |

持仓截图也可以交给 Agent 识别，再通过 `import_holdings` 批量写入本地文件；面板会自动刷新。点击持仓或自选中的股票/基金即可打开完整 AI 解读，首次主动点击后才生成，报告会缓存到本地并支持重新生成。插件只修改本地持仓数据，不执行真实交易。

### 面板与对话双向通道

面板与模型之间是双向实时的：

- **面板 → 对话**：点击持仓/自选触发解读时，面板把任务注入当前 Harness 会话。
- **对话 → 面板**：工具对持仓、自选、解读缓存、数据源策略、技能开关的修改，经服务端事件总线（`GET api/events`，SSE）即时推送到面板，无需等待轮询；模型还可以调用 `panel_navigate` 把面板切到指定标签页、聚焦某只股票的 K 线，或直接打开 AI 解读。
- 60 秒轮询保留为兜底；SSE 断线时 EventSource 自动重连。

### What-if 再平衡模拟

`simulate_rebalance` 基于本地持仓做**纯模拟**推演，不修改持仓文件、不下单：

- **trades 模式**：给定买卖列表（先卖后买、现金约束、超卖自动截断）；
- **targets 模式**：给定目标权重（占「持仓市值 + 可用现金」的百分比），自动折算为交易；
- 输出前后对比：总市值、现金、权重、top1/top3、HHI、分币种敞口，以及全部警告与口径说明（按最新价成交、不计滑点费用、跨币种未折算汇率等）。

### 面向模型的金融工具

| 领域 | 工具 | 能力 |
| --- | --- | --- |
| A 股 | `get_realtime_quote` · `get_stock_kline` · `search_stock` · `get_stock_list` | 行情、日/周/月 K 线、列表搜索 |
| A 股 | `get_market_overview` · `get_financial_indicators` · `get_sector_board` | 指数、财务指标、行业板块 |
| 港股 | `get_hk_quote` · `get_hk_kline` · `get_hk_list` | 港股报价、K 线和列表样本 |
| 美股 | `get_us_quote` · `get_us_kline` | Yahoo 优先、东财兜底的报价与 K 线 |
| 基金 | `get_fund_quote` · `get_fund_kline` · `get_fund_rank` | 净值、历史走势和分类排行 |
| 通用 | `search_symbol` · `get_stock_info` | 跨市场代码解析、个股档案与市值 |
| 研究 | `calculate_technical_indicators` · `get_macro_china` | MA/MACD/RSI/KDJ 与中国宏观序列 |
| 新闻 | `get_market_news` · `get_stock_news` · `web_search` | 市场快讯、个股新闻、免费网页搜索 |
| 组合 | `get_portfolio` · `analyze_portfolio` · `upsert_holding` · `import_holdings` · `remove_holding` · `save_position_analysis` | 持仓 CRUD、批量导入、盈亏、风险分析和解读缓存 |
| 模拟 | `simulate_rebalance` | What-if 再平衡推演（交易列表或目标权重），前后权重/HHI/分币种对比 |
| 面板 | `panel_navigate` | 对话中把金融面板切到指定标签页、聚焦代码或打开 AI 解读 |
| 自选 | `add_watchlist` · `remove_watchlist` · `get_portfolio_file` | 自选股/基金和本地文件管理 |
| 运维 | `probe_finance_sources` | 串行探测端点并生成 provider 降级顺序 |

## 快速开始

### 1. 安装并构建

需要 Node.js `>=20`：

```bash
cd dsn-finance-lab
npm install
npm run build
```

### 2. 先探测公开数据源

东财、腾讯、Yahoo 和 DuckDuckGo 都是公开源，可能受到网络波动、风控或限流影响。首次运行建议先探测，插件启动时会读取报告并优先使用健康的 provider：

```bash
npm run probe

# 指定输出和请求间隔
npx tsx scripts/probe_sources.ts \
  --out data/probe-report.json \
  --gap-sec 3

# 只探测某个 capability.provider
npx tsx scripts/probe_sources.ts --only kline.em_kline
```

报告默认写入 `data/probe-report.json`。全部公开源不可用时，行情工具会返回不可用信息；本地持仓 CRUD 仍然可以使用。

### 3. 接入 DeepSeek Harness

将当前项目目录注册到 `web` profile：

```bash
npx @deepseek-ai/dsh plugin \
  --profile web add /absolute/path/to/dsn-finance-lab
npx @deepseek-ai/dsh web --profile web
```

本地开发也可以直接运行：

```bash
bash scripts/dev_web.sh
```

如果需要使用开发期的绝对路径 overlay：

```bash
npx @deepseek-ai/dsh web --patch ./cordis.dev.yml
```

注册插件后，从 Harness 左下角的 **📈 金融面板** 打开 UI；模型工具会自动出现在工具列表中。

## 配置与数据

默认配置位于 `cordis.patch.yml`：

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `cacheTtlSec` | `300` | provider 缓存时间 |
| `requestGapMs` | `3000` | 相邻公开请求的间隔 |
| `httpTimeoutMs` | `30000` | 单次请求超时 |
| `probeReportPath` | `data/probe-report.json` | provider 探测报告 |
| `portfolioPath` | `data/portfolio.json` | 本地持仓/自选文件 |
| `mcpSources` | 预置 妙想 / 盈米 | 外部 MCP 数据源列表（见「多来源数据」） |
| `panelOpen` | 未设置 | 是否打开金融面板 |
| `panelDocked` | 未设置 | 是否默认停靠为侧栏页 |

相对路径均以插件包目录为基准。`data/probe-report.json` 和 `data/portfolio.json` 属于本地运行数据，不会被提交。

## 可用性测试

项目提供覆盖 A 股、港股、美股、跨市场解析和网页搜索的串行测试集：

```bash
npm run test:avail

# 只测试某个分组
npm run test:avail -- --group us
# 可选分组：ashare、hk、us、tools、search
```

## 数据源与边界

- 运行时不依赖 Python `akshare`；接口形状参考 [AkShare](https://github.com/akfamily/akshare) 源码，并在 `src/data/providers.ts` 中保留来源注释。
- A 股、港股、基金、宏观和新闻主要使用东方财富，部分行情使用腾讯；美股优先使用 Yahoo Finance，并以东方财富兜底；网页搜索使用 DuckDuckGo。
- provider 会按 capability 独立降级。公开源并不承诺稳定性或完整覆盖，返回结果应结合时间、市场状态和来源健康度解读。
- 本项目用于研究和组合记录，不构成投资建议；不连接券商，也不执行下单。

## 多来源数据（MCP）

除公开免费源外，可通过 `mcpSources` 接入需要凭证的外部数据源，其工具会被桥接进模型工具集，并显示在金融面板「接口」标签页。支持三类：

| kind | 说明 | 桥接后的工具名 |
| --- | --- | --- |
| `mcp-http` | Streamable HTTP MCP Server | `mcp__<name>__*` |
| `mcp-stdio` | 子进程 stdio MCP Server | `mcp__<name>__*` |
| `cli` | 遵循 `<command> mcp list/schema/call` 约定的 CLI | `<name>_list` / `_schema` / `_call` |

默认预置两个（需自备 token）：

- **妙想数据**（`mx`，`mcp-http`，东方财富）：A股/港股/美股/基金/债券/指数板块/宏观/新闻/公告的自然语言查询。
- **盈米**（`yingmi`，`cli`）：基金详情、风险与资产配置等能力，依赖全局安装的 `yingmi-skill-cli`。

Token 解析优先级：环境变量（`apiKeyEnv`，如 `EM_API_KEY`）→ 本地 `data/mcp-secrets.json`（不提交，见 `data/mcp-secrets.example.json`）→ 配置内联 `apiKey`。也可在面板「接口」页点 🔑 直接填写 token：写入 `data/mcp-secrets.json` 并**即时热重载**（断开旧连接、重新桥接工具，无需重启）。

## 数据源选择（多来源策略）

面板「数据源」页可按 capability 选择使用哪些 provider（`quote`/`kline`/`hk_*`/`us_*`/`web_search` 等常有多个来源共存）：多选、点击顺序即调用优先级，绿点=探测可用。选择保存到本地 `data/provider-policy.json` 并即时生效（用户选择优先于探测顺序）。妙想/盈米作为整体数据源在「接口」页开关。

## 本地历史库与 K 线事件

面板「K线」页可把日 K 线与事件落地到本地库并追加更新（`data/history/<code>.json`）：

- `sync_history`（工具）/ `POST api/history/sync`：抓取日 K 线（A股/港股/美股/基金）并按日期去重合并，股票同时把财报日期存为事件。
- `add_market_event` / `get_history` / `list_history`：追加分红/公告等自定义事件、读取、列出。
- K 线图上以虚线标注事件（财报=蓝、分红=绿），下方列出事件时间。

## 技能管理

面板「技能」页统一管理技能（类似工具）：本插件 playbook 技能可启用/停用（进入系统提示）；盈米的 11 个金融场景 skill（标准 SKILL.md）可勾选可见范围，写入 `remote-skill scope`。选择保存到 `data/skills-policy.json`。

## 项目结构

```text
src/                  插件服务、provider、模型工具和金融面板
src/panel-bus.ts      面板 ↔ 对话双向通道的事件总线（SSE 推送）
src/rebalance.ts      What-if 再平衡模拟引擎（纯函数，不改持仓）
src/mcp/              外部 MCP 数据源桥接（妙想 HTTP / 盈米 CLI）+ token 热重载
src/history/          本地历史库（K线/财报/分红）与同步
skills/               财务分析、组合、策略、风控与研究团队 playbook
scripts/              provider 探测、可用性测试和本地 Web 启动脚本
cordis.patch.yml      Harness 插件注册与默认配置
```