dsh-finance-data

Readme

# DSH Finance Data

面向 DSH 的金融数据采集插件:纯 JavaScript、零依赖。按需采集 A 股 / 基金 / 指数 / 宏观 / 期货 / 估值 / 财报 / 事件等公开数据,解析后增量留存本地,并提供模型工具。

## 特性

- 报名字/代码即可采集(`贵州茅台` / `CPI` / `黄金` / `801010`),自动解析到对应数据源
- 增量落盘,重复采集 `added=0`;数据随 profile 持久,卸载重装后可续采
- 纯 JS、零 npm 依赖;从 GitHub 安装,无需构建授权

## 安装

安装为 DSH 组合包（bundle），每个会话自动获得 `finance_*` 工具：

```bash
dsh plugin --profile <name> add github:coder-wu/dsh-finance-data
# 组合包层在启动时加载，安装后需重启 dsh：
dsh --profile <name>
```

> 建议锁定 commit：`dsh plugin --profile <name> add github:coder-wu/dsh-finance-data#<sha>`

### 数据落盘

- 数据经 DSH 的 `ctx.fs` 服务写盘，受 **workspace 沙箱**约束：workspace-write 模式下仅允许写入工作区根目录（dsh 启动时的 `process.cwd()`）与系统临时目录（`/tmp`、`os.tmpdir()`）；沙箱外路径会被拒绝（`FS_SANDBOX_DENIED`）。
- 默认数据根目录为 dsh 启动目录，明细在 `./data/<source>/<symbol>.json`，索引在 `status.json` / `catalog.json`。已采集数据随磁盘持久，卸载重装后按日期增量续采。
- 可用环境变量 `FINANCE_DATA_ROOT` 覆盖数据根目录（优先于默认 `.`）。

### 卸载

```bash
dsh plugin --profile <name> remove dsh-finance-data
```

> 卸载只移除配置层与依赖，不清除已采集数据；重新安装后可继续增量续采。

## 使用

模型在对话中自动解析意图并调用工具:

| 你想 | 插件调用 |
|---|---|
| 采集贵州茅台日线 | `finance_collect {target:'stock', symbols:['贵州茅台']}` |
| 看 CPI / PMI | `finance_collect {target:'macro', series:['cpi','pmi']}` |
| 抓黄金期货 | `finance_collect {target:'futures', futures:['gold']}` |
| 看行业估值 | `finance_collect {target:'valuation', scope:'industry'}` |
| 查已采集数据 | `finance_status` |

- `finance_search {query}`:把名字/代码解析为可采集候选
- `finance_collect {target, ...}`:按需采集并落盘;返回 `{ok, results:[{kind, added, asOf}]}`,重复采集 `added=0`
- `finance_status`:按源显示最近采集日期与 catalog

`target` 支持:`stock`(A 股日线)、`fund`(基金净值)、`index`(申万 L1/L2)、`csi`(中证指数)、`futures`(COMEX/LME)、`macro`(LPR/PMI/CPI/M2/PPI)、`valuation`(行业/个股估值)、`shareholders`(股东户数)、`reports`(财报)、`events`(业绩预告/分红/预约披露/FOMC)。

## 数据源

| target | 数据源 |
|---|---|
| `stock` | 新浪 `getKLineData`(名字→代码经东财搜索) |
| `fund` | 东财 `api.fund.eastmoney.com f10/lsjz` |
| `index` | 申万 `swsresearch` 指数日线(L1 31 / L2 134) |
| `csi` | 中证 `csindex index-perf` |
| `futures` | 雅虎 `v8/finance/chart`(COMEX/LME 金银铜) |
| `macro` | 东财 `RPTA_WEB_RATE`(LPR)+ 金十 jin10(PMI/CPI/M2/PPI) |
| `valuation` | 东财 `RPT_VALUEINDUSTRY_DET` / `RPT_VALUEANALYSIS_DET` |
| `shareholders` | 东财 `RPT_HOLDERNUM_DET` |
| `reports` | 东财 `RPT_DMSK_FN_INCOME/BALANCE/CASHFLOW` |
| `events` | 东财 业绩预告/分红/预约披露 + 美联储 FOMC 日历 |

> 雅虎期货对数据中心出口 IP 限流(429),实网环境/代理下可用。
> `EM_TOKEN` 与金十 `x-app-id` 为对应网站公开网页客户端凭据(非私有密钥),可在 `src/em.mjs` / `src/collectors/macro.mjs` 中替换。

## 开发

```bash
npm test            # 离线单元测试(不联网)
npm run test:static # 静态入口 index.js 冒烟测试(不联网)
npm run test:e2e    # 端到端测试(真网络)
npm run build       # 重新生成 index.js / plugin.json / plugin/host.js(产物已提交,改 src/ 后需重建再提交)
```

## License

[MIT](LICENSE)