Skip to content

SKILL.md

Latest commit

 

History

History
151 lines (114 loc) · 5.34 KB

SKILL.md

File metadata and controls

151 lines (114 loc) · 5.34 KB
name akshare-doc-query
description 指导开发者使用 AKShare API 进行开发。当用户需要用 akshare 获取数据、编写调用代码、排查 API 问题、选择合适接口时触发。提供接口选型、参数说明、代码生成、API 陷阱提醒和调试指导。也支持更新本地文档库。
user-invocable true

AKShare API 开发指导

帮开发者选对接口、写对代码、避开陷阱。

触发条件

  • 用户说 "akshare"、"akshare-doc-query"、"/akshare-doc-query"
  • 用户想用 akshare 获取某类数据（行情、财务、资金流、宏观等）
  • 用户需要编写 akshare API 调用代码
  • 用户遇到 akshare API 调用问题（空数据、报错、字段对不上等）
  • 用户要求更新 akshare 文档

操作步骤

1. 理解开发需求

先搞清楚用户要做什么：

  • 获取什么数据？（A股行情、期货、基金、宏观、外汇...）
  • 用在什么场景？（研究分析、数据管道、策略回测...）
  • 数据频率要求？（实时、日线、分钟线...）

2. 选接口

读取 docs/local_index.md，根据需求匹配接口：

  • 优先精确匹配接口名
  • 其次按标题和描述模糊匹配
  • 如果匹配到多个，说明每个接口的适用场景，帮用户选择
  • 如果需求复杂，可能需要组合多个接口

接口推荐思路（不是硬性规则，具体以文档为准）：

需求 常用接口
A 股历史行情 stock_zh_a_hist、stock_zh_a_daily
A 股实时行情 stock_zh_a_spot_em、stock_sh_a_spot_em
指数数据 index_zh_a_hist、stock_board_industry_name_em
期货行情 futures_main_sina、futures_zh_daily_sina
基金净值 fund_open_fund_info_em、fund_etf_fund_daily_em
宏观数据 macro_china_gdp、macro_china_cpi、macro_china_ppi
债券/可转债 bond_zh_cov_info、bond_china_yield_start
外汇 currency_binance_spot、fx_spot_quote

3. 给出接口文档

读取匹配到的接口文档文件（路径来自 local_index.md），整理为：

  • 接口说明：这个接口做什么、返回什么
  • 必填参数：哪些参数必须传
  • 关键可选参数：常用的可选参数
  • 输出字段：返回哪些列
  • 数据源说明：来自哪个网站（东财、新浪、腾讯等）

4. 生成调用代码

根据用户的技术栈，给出可直接运行的代码片段。

Python 示例模板：

import akshare as ak

# A 股历史行情
df = ak.stock_zh_a_hist(symbol="000001", period="daily",
                         start_date="20240101", end_date="20241231", adjust="qfq")
print(df.shape)
print(df.head())

5. 提醒 API 陷阱

在给出代码时，必须针对该接口提醒相关陷阱（完整列表见 docs/akshare_api_pitfalls.md）：

  • 数据源后缀含义：_em（东方财富）、_sina（新浪）、_tx（腾讯）、_xq（雪球），同一类数据不同后缀的接口返回格式和字段可能不同
  • 日期格式：大部分接口使用 YYYYMMDD，少数使用 YYYY-MM-DD，需查看具体接口文档
  • 实时数据注意：非交易时间调用实时行情接口可能返回上一交易日数据
  • 频率限制：akshare 依赖数据源网站，没有官方频率限制文档，建议请求间加 time.sleep() 延时
  • 返回类型：几乎所有接口返回 pandas.DataFrame
  • 字段名不跨接口一致：同一概念在不同接口中字段名可能不同，必须查阅该接口文档确认

6. 帮助调试

当用户遇到 API 调用问题时，按以下顺序排查：

  1. 空结果 → 检查股票代码格式、日期是否为交易日、参数是否拼写正确
  2. 报错 → 区分是网络问题（数据源网站不可达）还是参数问题
  3. 数据不完整 → 检查数据源网站是否有该时段数据
  4. 频率限制 → 加入延时控制

调试命令：

import akshare as ak

# 确认版本
print(ak.__version__)

# 冒烟测试：拉取实时行情确认环境正常
df = ak.stock_zh_a_spot_em()
print(df.shape)

# 确认接口返回的列名（排查字段名问题）
print(df.columns.tolist())
print(df.dtypes)

更新文档

当用户要求更新 akshare 文档时：

执行 bash scripts/update_docs.sh

  • 自动：下载最新索引 → 爬取新增/变更文档 → 生成本地索引
  • 加 --repo-path 指定仓库路径
  • 加 --force 强制重新下载全部
  • 加 --dry-run 仅查看计划

接口分类速查

分类 涵盖内容
stock A股/港股/美股行情、财务、资金流、板块、龙虎榜
futures 期货合约、行情、持仓、主力合约
bond 可转债、国债收益率、回购
option 期权合约、行情
fund 公募/私募基金列表、净值、持仓
index 指数行情、成分、权重
macro GDP、CPI、PPI、利率、社融
fx 外汇行情
currency 货币数据
spot 现货行情（黄金等）
interest_rate Shibor、LPR 等利率数据
dc 加密货币行情
bank 银行理财、存款利率
energy 能源数据
hf 高频数据
nlp 新闻、公告 NLP
qdii QDII 基金数据
others 另类数据
tool 工具函数

前置条件

pip install akshare

akshare 不需要注册或 token，安装即可使用。