Cifang Fund Data

SKILL.md

---
name: cifang-fund-data
description: 获取A股场内基金（ETF、LOF）的历史行情、实时行情和收益率排行数据。使用次方量化API（需要API Key）获取基金列表、历史行情、实时行情和场内基金排行数据。当用户需要获取中国场内基金数据、分析ETF/LOF表现、查询基金历史价格、实时行情或进行金融数据分析时，请使用此技能。
homepage: https://www.cifangquant.com/tool/data-api
required_env_vars:
  - CIFANG_API_KEY
---

# A股场内基金数据获取技能

本技能帮助用户通过次方量化API获取中国A股场内基金（ETF、LOF）的历史行情、实时行情和收益率排行数据。该API需要有效的API Key进行认证。

## 快速开始

1. **获取API Key**：访问[次方量化平台](https://www.cifangquant.com/tool/data-api)获取API Key
2. **优先安全注入**：优先通过 `--api-key` 参数或短期环境变量注入，避免写入长期共享配置
3. **设置环境变量（可选）**：将API Key设置为环境变量 `CIFANG_API_KEY`
4. **使用技能**：请求基金数据时，技能会自动使用API Key

## 安全检查清单

在启用真实 API 前，建议逐项确认：

1. **密钥意愿确认**：本技能运行依赖 `CIFANG_API_KEY`，请先确认你愿意提供该密钥。
2. **来源验证**：优先确认发行者身份、源码仓库和第三方评价；如信息不足，先在受控环境试运行。
3. **网络与隐私确认**：技能会将 `x-api-key` 随请求发送至 `https://www.cifangquant.com`，请确认你接受相关隐私与使用条款。
4. **自动触发策略**：若不希望代理自动执行，请在安装或代理策略中禁用/限制该技能自动触发。

## API 端点

### 基础信息
- **基础URL**: `https://www.cifangquant.com/api`
- **认证**: 请求头 `x-api-key: YOUR_API_KEY`
- **响应格式**: 统一JSON格式 `{"code": 0, "message": "ok", "data": ...}`

### 可用接口
1. **基金列表**：`GET /api/fund/list`
   - 参数：`key_word` (可选，基金代码或名称)
   - 返回：基金基础信息列表

2. **历史行情**：`GET /api/fund/hist_em`
   - 参数：
     - `symbol`: 基金代码，多个以逗号分隔（最多50个）
     - `start_date`: 开始日期 `YYYY-MM-DD`
     - `end_date`: 结束日期 `YYYY-MM-DD`
     - `adjust`: 复权类型 `none`(不复权)/`qfq`(前复权)/`hfq`(后复权)，默认`none`

3. **实时行情**：`GET /api/fund/spot`
   - 参数：
     - `symbol`: 基金代码；支持多个代码用英文逗号 `,` 分隔，不传则返回全量实时行情
   - 返回：基金实时行情快照，数据延迟通常不超过2分钟
   - 字段：`code`(基金代码), `name`(基金名称), `price`(最新价), `change`(涨跌幅%), `change_amount`(涨跌额), `volume`(成交量), `amount`(成交额), `open`(开盘价), `high`(最高价), `low`(最低价), `close_yesterday`(昨收价), `fund_type`(基金类型), `trade_date`(交易日期), `data_time`(行情时间)

4. **场内基金排行**：`GET /api/fund/exchange_rank`
   - 参数：
     - `sort_by`: 排序字段：`zzf`(近1周)、`1yzf`(近1月)、`3yzf`(近3月)、`6yzf`(近6月)、`1nzf`(近1年)、`2nzf`(近2年)、`3nzf`(近3年)、`jnzf`(今年来)、`lnzf`(成立以来)，默认`1yzf`
     - `sort_order`: 排序方向：`desc`(降序)或`asc`(升序)，默认`desc`
     - `limit`: 返回数量上限，默认30000
   - 返回：场内基金收益率排行榜
   - 字段：`rank`(排名), `fund_code`(基金代码), `fund_name`(基金名称), `fund_type`(基金类型), `date`(净值日期), `unit_nav`(单位净值), `accumulated_nav`(累计净值), `week_1`(近1周收益率), `month_1`(近1月收益率), `month_3`(近3月收益率), `month_6`(近6月收益率), `year_1`(近1年收益率), `year_2`(近2年收益率), `year_3`(近3年收益率), `ytd`(今年来收益率), `since_inception`(成立以来收益率), `inception_date`(成立日期)

## 使用指南

### 1. 获取基金列表
当用户需要查找特定基金或浏览可用基金时，使用基金列表接口。

**示例请求**：
```bash
curl -H "x-api-key: $CIFANG_API_KEY" \
  "https://www.cifangquant.com/api/fund/list?key_word=510300"
```

**响应示例**：
```json
[
  {
    "fund_code": "510300",
    "fund_name": "华泰柏瑞沪深300ETF",
    "fund_type": "指数型-股票",
    "fund_market": "SH",
    "establish_date": "2012-05-04"
  }
]
```

### 2. 获取历史行情
当用户需要基金的历史价格数据时，使用历史行情接口。

**示例请求**：
```bash
curl -H "x-api-key: $CIFANG_API_KEY" \
  "https://www.cifangquant.com/api/fund/hist_em?symbol=510300,510500&start_date=2024-01-01&end_date=2024-12-31&adjust=qfq"
```

**响应格式**：
```json
{
  "510300": [
    ["2024-01-02", 3.45, 3.48, 3.50, 3.44, 1.23, 1000000],
    ["2024-01-03", 3.48, 3.50, 3.52, 3.47, 0.57, 1200000]
  ],
  "510500": [
    ["2024-01-02", 5.67, 5.70, 5.72, 5.65, 0.53, 800000],
    ["2024-01-03", 5.70, 5.68, 5.72, 5.66, -0.35, 750000]
  ]
}
```

**数据字段说明**：
- 索引0: 日期 (YYYY-MM-DD)
- 索引1: 开盘价
- 索引2: 收盘价
- 索引3: 最高价
- 索引4: 最低价
- 索引5: 涨跌幅 (%)
- 索引6: 成交量

### 3. 获取实时行情
当用户需要获取场内基金的实时行情快照时，使用实时行情接口。该接口数据延迟通常不超过2分钟。

**示例请求**：
```bash
curl -H "x-api-key: $CIFANG_API_KEY" \
  "https://www.cifangquant.com/api/fund/spot?symbol=161226,518880"
```

**响应示例**：
```json
{
  "161226": {
    "code": "161226",
    "name": "国投白银LOF",
    "price": 2.73,
    "change": -4.177,
    "change_amount": -0.119,
    "volume": 133505376,
    "amount": 366382936,
    "open": 2.789,
    "high": 2.792,
    "low": 2.716,
    "close_yesterday": 2.849,
    "fund_type": "LOF",
    "trade_date": "2026-04-23T00:00:00Z",
    "data_time": "13:32:33"
  }
}
```

### 4. 获取场内基金排行
当用户需要查看场内基金的收益率排行榜时，使用场内基金排行接口。支持按不同时间区间的收益率排序。

**示例请求**：
```bash
curl -H "x-api-key: $CIFANG_API_KEY" \
  "https://www.cifangquant.com/api/fund/exchange_rank?sort_by=1yzf&sort_order=desc&limit=100"
```

**响应示例**：
```json
[
  {
    "rank": 1,
    "fund_code": "515880",
    "fund_name": "通信ETF国泰",
    "fund_type": "指数型-股票",
    "date": "2026-04-22",
    "unit_nav": 1.4105,
    "accumulated_nav": 4.2315,
    "week_1": 15.52,
    "month_1": 30.87,
    "month_3": 33.43,
    "month_6": 58.25,
    "year_1": 270.6,
    "year_2": 282.98,
    "year_3": 279.1,
    "ytd": 37.28,
    "since_inception": 323.19,
    "inception_date": "2019-08-16"
  }
]
```

## 技能工作流程

### 步骤1：检查API Key
首先检查环境变量 `CIFANG_API_KEY` 是否设置。如果未设置，提示用户：
1. 访问 https://www.cifangquant.com 获取API Key
2. 设置环境变量：`export CIFANG_API_KEY="your-api-key"`

### 步骤2：解析用户请求
根据用户请求确定需要的数据：
- **基金查找**：使用基金列表接口
- **历史数据**：使用历史行情接口
- **实时行情**：使用实时行情接口
- **基金排行**：使用场内基金排行接口
- **多基金比较**：支持多个基金代码

### 步骤3：构建API请求
根据用户需求构建相应的API请求：
- **基金列表**：确定关键词（可选）
- **历史行情**：确定基金代码（支持多个）、日期范围（默认最近一年）、复权类型（默认不复权）
- **实时行情**：确定基金代码（支持多个，不传则返回全量）
- **基金排行**：确定排序字段（默认近1月收益率）、排序方向（默认降序）、返回数量上限（默认30000）

### 步骤4：处理响应
将API响应转换为用户友好的格式：
- 解析JSON响应
- 转换数据格式（数组→对象）
- 添加元数据（基金名称、类型等）
- 计算衍生指标（累计收益率、波动率等）

### 步骤5：输出结果
以结构化JSON格式输出，包含：
- 基金基本信息
- 历史行情数据
- 统计摘要
- 数据质量说明

## 高级功能

### 1. 数据转换
将API返回的数组格式转换为更易读的对象格式：

**原始格式**：
```json
["2024-01-02", 3.45, 3.48, 3.50, 3.44, 1.23, 1000000]
```

**转换后格式**：
```json
{
  "date": "2024-01-02",
  "open": 3.45,
  "close": 3.48,
  "high": 3.50,
  "low": 3.44,
  "change_percent": 1.23,
  "volume": 1000000
}
```

### 2. 统计计算
自动计算基本统计指标：
- 期间收益率
- 年化收益率
- 波动率
- 最大回撤
- 夏普比率（如提供无风险利率）

### 3. 数据验证
- 检查日期范围有效性
- 验证基金代码格式
- 处理API错误响应
- 数据完整性检查

## 错误处理

### 常见错误
1. **401 Unauthorized**：API Key无效或未提供
2. **400 Bad Request**：参数格式错误
3. **404 Not Found**：基金代码不存在
4. **429 Too Many Requests**：请求频率超限

### 错误恢复
- 提示用户检查API Key
- 建议合理的日期范围
- 提供基金代码格式示例
- 建议降低请求频率

## 使用示例

### 示例1：获取单只基金历史数据
**用户请求**："获取沪深300ETF（510300）2023年的历史数据"

**技能操作**：
1. 解析基金代码：510300
2. 设置日期范围：2023-01-01 到 2023-12-31
3. 调用历史行情接口
4. 转换数据格式并输出

### 示例2：查找基金
**用户请求**："查找所有沪深300相关的ETF"

**技能操作**：
1. 使用关键词"沪深300"调用基金列表接口
2. 过滤ETF类型基金
3. 返回匹配的基金列表

### 示例3：多基金比较
**用户请求**："比较510300和510500过去一年的表现"

**技能操作**：
1. 解析多个基金代码：510300,510500
2. 设置日期范围：过去一年
3. 批量获取历史数据
4. 计算比较指标并输出

### 示例4：获取实时行情
**用户请求**："获取国投白银LOF（161226）和黄金ETF（518880）的实时行情"

**技能操作**：
1. 解析基金代码：161226,518880
2. 调用实时行情接口
3. 返回实时行情快照，包含最新价、涨跌幅、成交量等字段

### 示例5：获取基金排行
**用户请求**："获取近1月收益率最高的前10只场内基金"

**技能操作**：
1. 设置排序字段：`1yzf`（近1月收益率）
2. 设置排序方向：`desc`（降序）
3. 设置返回数量：10
4. 调用场内基金排行接口
5. 返回排行榜数据，包含排名、基金代码、收益率等字段

## 注意事项

### 1. API限制
- 需要有效的API Key（VIP会员）
- 历史行情接口最多支持50个基金代码
- 实时行情接口支持全量返回，但数据延迟通常不超过2分钟
- 场内基金排行接口默认返回30000条记录，可通过`limit`参数调整
- 请求频率限制（未在文档中明确）

### 2. 数据质量
- 数据来源：东方财富等公开数据
- 历史行情更新频率：交易日收盘后更新
- 实时行情更新频率：交易日内实时更新，数据延迟通常不超过2分钟
- 复权数据：支持前复权(qfq)和后复权(hfq)

### 3. 使用建议
- 对于长期分析，建议使用前复权数据
- 批量请求时注意代码数量限制
- 合理设置日期范围避免过大数据量

## 扩展支持

### 实时行情
API现已提供实时行情接口，支持获取场内基金的实时行情快照：
- 数据延迟通常不超过2分钟
- 支持单个或多个基金代码查询
- 包含最新价、涨跌幅、成交量等关键字段
- 可全量返回所有基金的实时行情

### 数据导出
支持将数据导出为多种格式：
- JSON（默认）
- CSV（用于Excel）
- Pandas DataFrame（Python分析）

## 脚本工具

技能目录下的 `scripts/` 文件夹包含辅助脚本：
- `fetch_fund_data.py`：封装API调用的Python脚本
- `convert_format.py`：数据格式转换工具
- `calculate_stats.py`：统计指标计算工具

使用这些脚本可以简化数据处理流程。

---

**重要**：使用本技能需要有效的次方量化API Key。请确保已设置环境变量 `CIFANG_API_KEY`。