# Local Datasource

一个**本地运行的 MCP（Model Context Protocol）数据服务器**。它让任何支持 MCP 的 Agent（Claude Code、Codex、Cursor、OpenCode 等）都能直接查询金融市场、宏观经济和学术论文数据，而无需第三方账号、不消耗云额度、不经过外部中继。

---

## 一句话介绍

`local-datasource` 把 `akshare`、`yfinance`、`wbgapi`、`arxiv` 等免费公开接口封装成 16 个标准 MCP tool，覆盖 A股/港股/美股/ETF/期货/指数/期权行情、债券与可转债、全球利率与波动率（美债收益率/美联储利率/美元指数/VIX）、汇率、商品现货、带生效区间的交易规则参数表、多序列对齐合并、世界银行宏观指标与 arXiv 论文，Agent 只需要像调用本地函数一样请求数据，即可获得结构化 CSV 输出。

---

## 为什么需要这个项目

在日常投研、尽调、学术检索或自动化报告生成中，Agent 经常需要实时数据：

- 查一只股票过去一年的走势
- 对比黄金、美股、A股等多资产表现
- 拉取某个国家的 GDP/CPI 数据
- 检索某个领域的 arXiv 论文

这些需求本身并不复杂，但常见方案要么需要登录某个平台并消耗额度，要么把查询请求发到云端。`local-datasource` 希望提供一种**透明、可控、低成本**的替代方案：

- **数据请求不出本机**：适合对合规、隐私敏感的场景。
- **无需账号和额度**：基于公开接口，安装完就能用。
- **标准 MCP 协议**：不绑定任何特定 Agent，可被多家产品复用。
- **源码可见、可扩展**：增加新数据源或调整输出格式都很直接。

---

## 核心特点

- ✅ **A股 / 港股 / 美股**：日线行情，支持前复权/后复权。
- ✅ **美股 / 美股 ETF / 全球资产**：默认 `akshare` 美股接口，可回退 `yfinance`（A股场内 ETF 见 `query_etf`）。
- ✅ **世界银行宏观指标**：GDP、CPI、人口等。
- ✅ **arXiv 论文搜索**：标题、作者、摘要、PDF 链接结构化输出。
- ✅ **中国境内债券**：国债收益率曲线、信用债发行信息（按代码或发行人查）、交易所行情。
- ✅ **可转债**：一览含溢价率、强赎/回售条款、历史K线、发行人正股财务报表。
- ✅ **国内期货**：单合约（全历史）/主连日线与分钟、品种挂牌合约清单。
- ✅ **国内指数**：沪深指数（2014 起）与中证系列日线，沪深指数分钟。
- ✅ **A股场内 ETF**：日线（2012 起全历史）与分钟。
- ✅ **期权**：ETF 期权与股指期权（IO/HO/MO）的到期月份、合约清单、单合约日线。
- ✅ **A股个股分钟**：`query_stock(period=min)`，与日线同一入口。
- ✅ **全球利率与波动率**：美债收益率曲线、美联储 EFFR、美元指数（东财失败回退 Yahoo）、VIX（CBOE 直连）。
- ✅ **汇率**：央行官方中间价、中行牌价、离岸 USDCNH、主要货币对交叉盘。
- ✅ **商品现货**：上金所贵金属日线、生意社大宗现货（含主力合约价与基差）。
- ✅ **对齐合并**：多份本库产出的 CSV 按日期合并成宽表（支持周/月重采样），纯本地计算。
- ✅ **交易规则参数表**：印花税/过户费/涨跌幅/保证金/T+1 等参数按 `as_of` 取当日生效值（含生效区间、来源与四档置信度标注）；商品期货参数不入表、返回查交易所当日结算参数的引导。
- ✅ **金融输入归一化**：股票/债券的名称、简称、全称、发行人 → 统一代码（`resolve_stock_code` + `bond_issue`）。
- ✅ **统一 CSV 输出**：每个 tool 都把结果写到 `file_path`，并返回前 5 行预览。
- ✅ **零 API Key**：所有默认数据源均免费使用。
- ✅ **跨 Agent 复用**：标准 MCP Server，配置一条 `command` 即可接入。

---

## 适用人群

- 需要在 Agent 工作流里频繁查数据的投研、分析师、开发者。
- 不希望把查询请求发送到云端的本地优先用户。
- 想学习/定制 MCP 数据服务器实现的开发者。

---

## 快速开始

要求：Python >= 3.10。

```bash
# 1. 克隆并安装
git clone https://github.com/jarvislee90s-dot/local-datasource.git
cd local-datasource
pip install -e .

# 2. 启动 MCP 服务
local-datasource

# 3. 在 Agent 的 MCP 配置中添加
{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}
```

---

## 覆盖范围

| 数据类型 | 工具 | 底层接口 | 是否需 API Key |
|---|---|---|---|
| A股（日线含换手率/流通股本/成交额，分钟）/ 港股 / 美股 历史行情 | `query_stock` | `akshare` | 否 |
| 美股 / 美股 ETF / 全球资产 | `query_yfinance` | `akshare`（默认）/ `yfinance`（备选） | 否 |
| 世界银行宏观指标 | `query_worldbank` | `wbgapi` | 否 |
| arXiv 学术论文 | `query_arxiv` | `arxiv` | 否 |
| 中国境内债券（国债收益率曲线/信用债发行信息/交易所行情） | `query_bond` | `akshare` | 否 |
| 可转债（一览/条款/历史K线/发行人财务） | `query_convertible_bond` | `akshare` | 否 |
| 股票名称（简称/全称）→ 代码候选 | `resolve_stock_code` | 新浪 suggest API / `akshare` | 否 |
| 国内期货（单合约/主连行情、合约清单） | `query_futures` | `akshare`（新浪/交易所官方） | 否 |
| 国内指数（沪深/中证系列，日线/分钟） | `query_index` | `akshare`（新浪/腾讯/中证官网） | 否 |
| A股场内 ETF（日线/分钟） | `query_etf` | `akshare`（新浪/腾讯） | 否 |
| 期权（ETF期权/股指期权：月份/清单/日线） | `query_options` | `akshare`（新浪/上交所/CFFEX） | 否 |
| 美债收益率/美联储 EFFR/美元指数/VIX（全球利率与波动率） | `query_global_rates` | 东财数据中心 / 新浪 / 纽约联储 / CBOE / yfinance（回退） | 否 |
| 汇率（官方中间价/中行牌价/离岸 USDCNH/主要货币对） | `query_fx` | 外汇局 / 新浪 / yfinance | 否 |
| 商品现货（上金所贵金属/生意社大宗含基差） | `query_spot` | `akshare`（上金所/生意社 100ppi） | 否 |
| 多序列对齐合并（宽表/重采样，纯本地） | `align_series` | 本地 `pandas` 计算（不联网） | 否 |
| 交易规则参数（税费/涨跌幅/保证金/T+1 等，按生效区间） | `query_trading_rules` | 包内静态表（附录 B 调研） | 否 |

---

## 金融输入归一化

用户给金融标的时可能贴代码、简称、全称或发行人名。本服务支持先把输入归一化为统一代码再查询：

- **股票**：公司简称/全称 → `resolve_stock_code` → 代码候选 → `query_stock`（新浪 suggest API 支持全称反查）
- **标债**：发行人名 → `query_bond(kind=issue_info, bond_issue=...)` → 最新一只债代码 → 继续查基本信息/财务
- **可转债**：正股简称 → `query_convertible_bond(kind=overview, keyword=...)` → 该公司转债
- **发行人财务**：任意债代码/发行人名 → 先归一化到代码 → `query_convertible_bond(kind=issuer_finance, ...)`
- **期货**：直接给合约/主连代码（`IM2612`/`IM0`/`IM主连` 自动归一）；查挂牌合约用 `query_futures(kind=contracts, symbol=品种如IM)`（合约清单走交易所官方挂牌表，DCE/GFEX 品种忽略 `trade_date`，返回当前挂牌）
- **指数**：`000852`/`sh000300` 自动补交易所前缀走新浪；中证系列 `930xxx/950xxx` 自动走中证官网源（慢约 10 秒，无分钟）
- **ETF**：`510300` 按首位自动补 `sh`/`sz` 前缀
- **期权**：先 `query_options(kind=months/contracts, underlying=...)` 拿到期月份/合约代码，再 `kind=hist` 查日线；合约代码宽容格式（`IO2706-P-5600` 与 `io2706p5600` 等价）

城投/非上市发行人无上市股票，`resolve_stock_code` 返回空候选；其债券的 `issuer_finance` 返回引导性提示（免费层无财务，建议查 Wind/企业预警通）。

---

## 架构

```
Agent（Claude Code / Codex / Cursor / OpenCode 等）
        ↓ MCP stdio
local-datasource（本仓库）
        ↓ 直接调用
akshare / yfinance / wbgapi / arxiv / requests（HTTP 直连）
        ↓ 原始数据源
新浪 / 腾讯 / 东财数据中心 / 交易所官网 / 中证指数 / 同花顺 / 外汇局 / 上金所 / 生意社 / 纽约联储 / CBOE / Yahoo Finance / World Bank / arxiv.org
```

---

## 文件结构

```
.
├── SKILL.md                        # Agent 执行手册
├── README.md                       # 项目介绍（本文档）
├── CHANGELOG.md                    # 里程碑变更记录
├── pyproject.toml                  # Python 包配置与依赖
├── config.yaml                     # 可选配置文件
├── src/local_datasource/           # MCP server 源码
│   ├── server.py                   # 服务入口：注册 tools、处理调用
│   ├── cli.py                      # download 批量下载子命令（唯一写缓存的入口）
│   ├── cache.py                    # 下载缓存纯函数：key/路径/manifest/新鲜度
│   ├── config.py                   # 加载 config.yaml / 环境变量
│   ├── formatters.py               # 统一 CSV 输出与预览
│   ├── assets/
│   │   └── trading_rules.yaml      # 交易规则参数静态表（附录 B 调研，随包分发）
│   └── providers/                  # 各数据源适配器
│       ├── common.py               # 共享工具：日期过滤、分钟深度守卫、腾讯分钟路径
│       ├── stock.py                # A/HK/US 股票（日线/A股分钟）+ resolve_stock_code 名称反查
│       ├── yahoo.py                # 美股/全球资产
│       ├── worldbank.py            # 世界银行
│       ├── arxiv.py                # arXiv 论文
│       ├── bond.py                 # 中国境内债券（国债收益率/信用债发行/交易所行情）
│       ├── convertible_bond.py     # 可转债（一览/条款/历史K线/发行人财务）
│       ├── futures.py              # 国内期货（行情/合约清单）
│       ├── index.py                # 国内指数（沪深/中证系列）
│       ├── etf.py                  # A股场内 ETF
│       ├── options.py              # 期权（ETF/股指：月份/清单/日线）
│       ├── global_rates.py         # 全球利率（美债收益率/美联储 EFFR/美元指数/VIX）
│       ├── fx.py                   # 外汇（中间价/中行牌价/离岸 USDCNH/交叉盘）
│       ├── spot.py                 # 现货（上金所贵金属/生意社大宗含基差）
│       ├── align.py                # 多序列对齐合并（宽表/重采样，纯本地）
│       └── rules.py                # 交易规则参数表（按 as_of 取生效值，纯本地）
└── demos/                          # 示例脚本
    └── mcp_query_demo.py           # 多资产查询 + 归一化走势图
```

---

## 依赖

- Python >= 3.10
- `mcp`：MCP 服务器框架
- `akshare`：A股/港股/美股/ETF/债券/可转债 行情
- `yfinance`：Yahoo Finance 备选接口
- `wbgapi`：世界银行数据
- `arxiv`：arXiv 论文搜索
- `pandas`：数据处理
- `pyyaml`：配置文件解析
- `requests`：新浪 suggest API（股票名称反查）

可选：
- `matplotlib`：运行 `demos/mcp_query_demo.py` 绘图

---

## 安装

```bash
pip install -e .
```

安装完成后，`local-datasource` 命令会被加入 PATH。

---

## 启动 MCP 服务

```bash
local-datasource
```

服务通过标准输入输出（stdio）与 Agent 通信。可以用以下命令快速验证是否启动成功：

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | local-datasource
```

若返回初始化结果，说明服务正常。

---

## 批量下载（download 命令）

除了作为 MCP 服务被 Agent 调用，本库还提供一个**批量下载子命令**，把常用数据在本地预取成 CSV 缓存，供回测、研究复用：

```bash
local-datasource download --config FILE [--data-dir DIR] [--force]
```

- `--config`（必填）：清单 YAML 路径
- `--data-dir`：缓存根目录；优先级 **CLI `--data-dir` > 清单顶层 `data_dir` > `config.yaml` 的 `cache.data_dir`**
- `--force`：忽略"当天已拉取"的新鲜度判断，强制重新下载

清单 YAML 格式（`assets` 列表，每条 `{tool, args, start_date?, end_date?}`）：

```yaml
# batch.yaml
data_dir: ./datasource-cache   # 顶层可选；CLI --data-dir 优先
assets:
  - tool: query_global_rates
    args: {kind: us_treasury, tenure: all}
  - tool: query_stock
    args: {ticker: "600519", market: a, adjust: qfq, period: daily}
    start_date: "2025-01-01"   # 可选：合并进 args；与 args 内同名值同时存在时,这里优先
    end_date: "2025-12-31"
  - tool: query_fx
    args: {kind: mid, currency: usd,eur}
```

支持的 `tool` 白名单为 13 个查询工具（`query_stock`/`query_yfinance`/`query_worldbank`/`query_arxiv`/`query_bond`/`query_convertible_bond`/`query_futures`/`query_index`/`query_etf`/`query_options`/`query_global_rates`/`query_fx`/`query_spot`）。`resolve_stock_code`（名称反查）、`align_series`（本地对齐）、`query_trading_rules`（M4 静态规则表）**不支持**出现在清单中——它们不产出待缓存的行情序列。未知 tool 名、缺 `args` 会在启动时一次性报错并列出合法 tool 名，校验全部通过后才开始下载。

每条目输出一行状态：

- `SKIP <tool>/<key>`：当天已拉取过（manifest 的 `last_fetched` 为今天）且未 `--force`，直接复用缓存
- `FETCH <tool>/<key> <rows> rows`：调用 provider 下载并写入缓存
- `FAIL <tool>/<key> <error>`：该条目失败；**单条失败不中断整批**，全部条目跑完后只要存在失败，退出码为 `1`（全部成功 `0`，清单/用法错误 `2`）

缓存目录布局：每条目落在 `<data_dir>/<tool>/<key>.csv`，旁边有同名的 `<key>.manifest.json` 元信息（含 args、行数、首末日期、`last_fetched`）。`key` 由工具名与参数生成，可读且末尾带 8 位哈希，例如：

```
datasource-cache/
└── query_global_rates/
    ├── query_global_rates-kind-us_treasury-tenure-all-1a2b3c4d.csv
    └── query_global_rates-kind-us_treasury-tenure-all-1a2b3c4d.manifest.json
```

> **架构说明**：MCP 查询路径**不做任何缓存**，永远直连数据源；`download` 是唯一写缓存的入口。缓存仅供用户显式预取/复用，不会让 Agent 拿到过期数据。

---

## Agent 配置示例

任何支持 MCP 的 Agent 都可以通过 `command` 方式调用本服务。

### Claude Code

`claude_mcp_settings.json`：

```json
{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}
```

### Codex

`.codex/config.json`：

```json
{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}
```

### Cursor / Windsurf / OpenCode

在对应 MCP 配置中添加：

```json
{
  "mcpServers": {
    "local-datasource": {
      "command": "local-datasource"
    }
  }
}
```

---

## 调用数据案例

### 查询 A 股：贵州茅台

```json
{
  "ticker": "600519",
  "market": "a",
  "start_date": "2025-06-01",
  "end_date": "2026-06-24",
  "file_path": "/tmp/moutai.csv"
}
```

Tool：`query_stock`

### 查询港股：腾讯

```json
{
  "ticker": "00700",
  "market": "hk",
  "start_date": "2025-06-01",
  "end_date": "2026-06-24",
  "file_path": "/tmp/tencent.csv"
}
```

Tool：`query_stock`

### 查询美股/ETF：黄金 GLD

```json
{
  "ticker": "GLD",
  "period": "1y",
  "file_path": "/tmp/gld.csv"
}
```

Tool：`query_yfinance`

默认使用 `akshare` 的美股日线接口；若需要 Yahoo Finance 数据，添加 `"use_yfinance": true`：

```json
{
  "ticker": "AAPL",
  "period": "1y",
  "use_yfinance": true,
  "file_path": "/tmp/aapl_yahoo.csv"
}
```

### 查询世界银行：中国 GDP 现价

```json
{
  "indicator": "NY.GDP.MKTP.CD",
  "country": "CHN",
  "start_year": 2020,
  "end_year": 2023,
  "file_path": "/tmp/china_gdp.csv"
}
```

Tool：`query_worldbank`

### 搜索 arXiv 论文

```json
{
  "query": "large language model retrieval augmented generation",
  "max_results": 10,
  "sort_by": "relevance",
  "file_path": "/tmp/llm_rag.csv"
}
```

Tool：`query_arxiv`

### 查询国债收益率曲线

```json
{
  "kind": "yield_curve",
  "start_date": "2025-01-01",
  "end_date": "2025-06-30",
  "file_path": "/tmp/bond_yield.csv"
}
```

Tool：`query_bond`（kind=`yield_curve`）

### 查询信用债发行信息

```json
{
  "kind": "issue_info",
  "bond_code": "2180495.IB",
  "file_path": "/tmp/bond_issue.csv"
}
```

Tool：`query_bond`（kind=`issue_info`，`bond_code` 精确匹配单只，支持 `2180495.IB` / `2180495` 格式，避免子串误命中）

### 按发行人查最新一只债

```json
{
  "kind": "issue_info",
  "bond_issue": "成都东方广益",
  "file_path": "/tmp/bond_by_issuer.csv"
}
```

Tool：`query_bond`（kind=`issue_info`，`bond_issue` 按发行人查，返回发行日期最新的一只债代码；与 `bond_code` 互斥）

### 查询可转债一览

```json
{
  "kind": "overview",
  "file_path": "/tmp/cb_overview.csv"
}
```

Tool：`query_convertible_bond`（kind=`overview`，返回全市场转债含转股溢价率/评级/规模，可选 `keyword` 按简称过滤）

### 查询发行人财务报表

```json
{
  "kind": "issuer_finance",
  "stock_code": "sh603938",
  "report_type": "资产负债表",
  "file_path": "/tmp/issuer_finance.csv"
}
```

Tool：`query_convertible_bond`（kind=`issuer_finance`，`bond_code`/`stock_code` 二选一；城投/非上市发行人返回引导性提示而非报错）

### 股票名称反查代码

```json
{
  "keyword": "贵州茅台酒股份有限公司",
  "file_path": "/tmp/resolve_stock.csv"
}
```

Tool：`resolve_stock_code`（首选新浪 suggest API，简称精确命中、全称从关联字段提取代码；城投/非上市发行人返回空候选；多候选时择一再调 `query_stock`）

### 查询期货：IM 主连日线

```json
{
  "symbol": "IM0",
  "period": "daily",
  "start_date": "2026-06-01",
  "end_date": "2026-08-28",
  "file_path": "/tmp/im_main.csv"
}
```

Tool：`query_futures`（单合约改 `symbol: IM2612` 得全历史；分钟加 `period: min`，深度约 4 个交易日，超覆盖报错并给补数指引）

### 查询指数：中证1000 日线

```json
{
  "symbol": "000852",
  "period": "daily",
  "start_date": "2014-10-17",
  "end_date": "2026-08-28",
  "file_path": "/tmp/csi1000.csv"
}
```

Tool：`query_index`（中证系列 `930xxx` 走中证官网源，慢约 10 秒、无分钟数据）

### 查询 ETF：沪深300ETF 分钟

```json
{
  "symbol": "510300",
  "period": "min",
  "freq": "1",
  "start_date": "2026-08-25",
  "end_date": "2026-08-27",
  "file_path": "/tmp/etf_min.csv"
}
```

Tool：`query_etf`（日线去 `period/freq` 加日期区间；日线源无复权）

### 查询期权：IO 到期月份 → 单合约日线

```json
{
  "kind": "months",
  "underlying": "IO",
  "file_path": "/tmp/io_months.csv"
}
```

Tool：`query_options`（合约清单 `kind: contracts`；日线 `kind: hist, symbol: "IO2706-P-5600"`）

### 查询美债收益率

```json
{
  "kind": "us_treasury",
  "tenure": "all",
  "file_path": "/tmp/us_treasury.csv"
}
```

Tool：`query_global_rates`（kind=`us_treasury`，`tenure: all` 返回 2/5/10/30 年及 10Y-2Y 利差，1990 年起；短端期限如 `3m` 仅近 1000 交易日；kind=`fed_rate`/`dxy`/`vix` 分别查美联储 EFFR、美元指数（东财失败自动回退 Yahoo）、VIX（CBOE 直连，1990 起））

### 查询汇率中间价

```json
{
  "kind": "mid",
  "currency": "usd,eur",
  "file_path": "/tmp/fx_mid.csv"
}
```

Tool：`query_fx`（kind=`mid` 外汇局官方中间价，1994 年起，单位为 100 外币 = X 人民币；kind=`bochina` 中行牌价需 `symbol` 如"美元"且起止日期必填；kind=`usdcnh`/`cross` 走 Yahoo，不可达时明确报错）

### 查询现货黄金：上金所 Au99.99

```json
{
  "kind": "sge",
  "symbol": "Au99.99",
  "file_path": "/tmp/au9999.csv"
}
```

Tool：`query_spot`（kind=`sge` 上金所贵金属日线，2016-12 起约 10 年深度；kind=`sy` 生意社大宗现货含主力合约价与基差，需 `symbols: ["CU","RB"]` 且起止日期必填、单次区间最长 1 年）

### 对齐合并多份行情 CSV 为宽表

```json
{
  "file_paths": ["/tmp/moutai.csv", "/tmp/gld.csv"],
  "columns": ["close", "close"],
  "names": ["moutai", "gld"],
  "align": "outer",
  "fill": "ffill",
  "file_path": "/tmp/merged.csv"
}
```

Tool：`align_series`（纯本地合并不联网；`columns`/`names` 与 `file_paths` 一一对应，缺省各取 `close`、列名用文件名；`resample: "week"/"month"` 重采样时每期取最后一个实际交易日）

### 查询交易规则参数：A 股某历史日期的印花税

```json
{
  "market": "a",
  "as_of": "2021-06-01",
  "file_path": "/tmp/rules_a.csv"
}
```

Tool：`query_trading_rules`（纯本地读包内静态表；不传 `as_of` 取现行值；`market: "commodity_futures"` 返回查交易所当日结算参数的引导性提示而非报错；输出含生效区间/来源/置信度等 12 个字段，可选 `parameter: "印花税"` 子串过滤）

---

参考 `demos/mcp_query_demo.py`：它通过 MCP 调用多个工具，读取生成的 CSV，计算归一化价格，并绘制对比图。

```bash
python demos/mcp_query_demo.py
```

输出：
- `demos/outputs/*.csv`：各资产原始行情
- `demos/outputs/normalized_returns.png`：归一化走势图
- `demos/outputs/summary.csv`：汇总表

---

## 配置

项目根目录的 `config.yaml`：

```yaml
providers:
  yahoo:
    # 默认使用 akshare。设为 true 则默认使用 yfinance。
    use_yfinance: false
cache:
  # download 批量下载的缓存根目录（默认 ./datasource-cache）。
  # 仅 download CLI 使用；MCP 查询不读写缓存。
  data_dir: ./datasource-cache
```

`cache.data_dir` 只影响 `local-datasource download`（见上文"批量下载"）；清单顶层 `data_dir` 与 CLI `--data-dir` 都比它优先。

也可通过环境变量指定配置文件：

```bash
LOCAL_DATASOURCE_CONFIG=/path/to/config.yaml local-datasource
```

---

## 扩展新数据源

`src/local_datasource/providers/` 下的每个文件都是一个独立适配器，新增数据源的步骤：

1. 在 `providers/` 新增一个 Python 文件，实现 `query_xxx(...)` 函数，返回 `tuple[str, str]`（文件路径 + 预览文本）。
2. 在 `server.py` 新增一个 `@mcp.tool(structured_output=False)` 薄工具函数：参数注解（`Annotated`/`Literal`/`Field`）即客户端可见 schema，docstring 即工具描述；函数体一行转发 `_safe_summary`。
3. 在 `_summary_for()` 中增加对应路由分支。
4. 更新 `SKILL.md` 和 `README.md` 的 tool 说明。

---

## 测试

测试随仓库分发（`tests/` 目录）。离线单测不连网；联网冒烟默认开启，设 `SKIP_INTEGRATION=1` 跳过：

```bash
python -m pytest tests/ -v              # 全量(含联网冒烟)
SKIP_INTEGRATION=1 python -m pytest tests/ -q   # 仅离线
```

包含配置加载、格式化、缓存与 CLI、15 个 provider 的测试、MCP server 工具注册（16 个 tool）。

---

## 网络环境已知风险

以下为在本机实测（2026-09）确认的数据源网络情况，也是本轮海外数据源选型的依据（CBOE、纽约联储直连可达）：

- **东财非 A 股端点部分网络被拒**：东财的全球指数/期货 K 线等非 A 股端点在部分网络环境下不可达（A 股相关端点不受影响）。美元指数已内置 Yahoo 自动回退。
- **金十美联储决议源 2025-09 起停更**：美联储利率已改用纽约联储官方 EFFR API（免 key 直连）。
- **FRED / treasury.gov / stooq 在本机实测不可用**：美债收益率走东财全表（1990 起，短端走新浪），VIX 走 CBOE 官方 CSV 直连，不依赖上述源。

---

## 注意事项

- **分钟数据深度有限**（免费源天花板）：期货分钟约 4 个交易日，腾讯源（个股/指数/ETF）约 8 个交易日。请求区间超出覆盖时会**明确报错并提示从 Wind/终端导出 Excel 补数**，不会静默返回残缺数据。
- **慢源与已知限制**：中证系列指数日线走中证官网（约 10 秒，无分钟）；ETF 日线无复权（原始价）；期权仅日线。期货主连日线为全历史：自品种上市日（或 2005-01-04，取较早）至今，共 83 个主连品种（IF0 特例仅自 2017-01-17 起）。
- **`query_bond(kind=issue_info)` 走中国货币网直连**（akshare 未适配其改版）：站点按 IP 限窗口内请求数，单次查询约 75 秒（30 个债券类型节流遍历）；触发限流（HTTP 421）时自动退避 4 分钟重试一次，仍限流则如实报错。同一发行人的重复查询建议走 `download` 缓存。
- `yfinance` 容易被 Yahoo Finance 限流，因此默认优先使用 `akshare`。
- `akshare` 的接口可能随时间变化，建议定期更新到较新版本。
- World Bank 和 arXiv 通常稳定且无需 API key。

---

## 与 kimi-datasource 的异同

| 维度 | local-datasource | kimi-datasource |
|---|---|---|
| 运行位置 | 本机 | Kimi Code 云端 |
| 登录/账号 | 不需要 | 需要 Kimi Code 账号 |
| 费用 | 免费（受公开接口限额影响） | 消耗 Kimi Code 额度 |
| 数据源 | A/HK/US 股票、境内债券/可转债、期货、指数、A股 ETF、期权、美股/全球资产、全球利率与波动率（美债/EFFR/美元指数/VIX）、汇率、商品现货（贵金属/大宗含基差）、交易规则参数表、多序列对齐合并、World Bank、arXiv | 更多，包括天眼查、Google Scholar、元典法律等 |
| 数据链路 | Agent → 本地 Server → 公开接口 | Agent → Kimi 云服务 → 后端数据源 |
| 可定制性 | 源码本地可见，可修改/扩展 | 黑盒，只能使用官方暴露的 tool |
| 跨 Agent 复用 | 标准 MCP Server，可被多家 Agent 复用 | 仅限 Kimi Code 内部 |

本项目的设计思路是：把常见的免费/公开数据查询能力做成一个本地、透明、可扩展的 MCP 服务。它并不复制 kimi-datasource 的具体实现（其接口实现并不公开），而是基于公开库重新组合出一套可用的本地替代方案。