akshare-api

# Akshare API 这个 skill 用来处理中文股票数据查询。调用方式是：先对用户问题做最小必要拆解（识别意图、标的、时间范围、指标），再把“保留原意”的查询语句交给本地客户端，由客户端路由意图并请求固定云端服务 `https://akshare.devtool.uk`。 重要原则： - 优先在 skill 层完成查询规范化，不要依赖代码里的硬编码别名表。 - 代码层只负责通用解析和运行时动态 symbol 解析；复杂别名、模糊表述、市场推断应优先由 skill 完成。 文档基准：本 skill 的股票能力范围、symbol 规则与参数优先遵循你提供的 AkShare 股票文档： - https://akshare.akfamily.xyz/_sources/data/stock/stock.md.txt ## When To Use This Skill 在用户提出以下类型的问题时使用本 skill： - A 股大盘、上证指数、深证成指、创业板指、实时行情 - 个股最近 N 天 K 线、日线、周线、月线 - 个股走势、K 线图、行情图 - 涨停、跌停、涨跌停统计 - 个股或市场资金流向、主力资金、北向资金 - 基本面、财务指标、ROE、市盈率、市净率、估值 - 个股综合分析 - 行业板块、概念板块、题材轮动、涨跌幅榜 - 股票推荐、选股 - 港股、美股、ETF、基金、可转债、债券 - 财经新闻、研究报告、机构评级 ## Do Not Use This Skill For - 实盘交易、下单、撤单 - 严格个性化投资建议或收益承诺 - 用户本地持仓管理 说明：代码里存在持仓管理分支，但依赖外部脚本，不适合作为这个 skill 的默认能力暴露给最终用户。 ## How To Execute 在 skill 内部直接运行下面的命令： ```bash python3 main.py --query "<拆解后、保留原意的查询语句>" ``` 默认假设当前工作目录就是本仓库根目录，大模型可以据此推断相对路径执行。 不要要求用户配置 `--service-url`，也不要要求用户部署服务。服务地址已经固定使用线上地址：`https://akshare.devtool.uk`。 ## Question Decomposition Rules 执行前先做一次轻量拆解，把用户问题映射为以下 4 个槽位： - 意图：行情 / K线 / 资金流 / 基本面 / 板块 / 新闻研报 / 综合分析。 - 标的：股票名称、6 位代码、指数、板块名、市场（A股/港股/美股）。 - 时间范围：最近 N 天、日/周/月、今日、实时、指定日期区间。 - 指标：如 ROE、市盈率、涨停家数、主力净流入等。 拆解后处理原则： - 信息齐全：直接执行，不再追问。 - 缺少最小必要信息：只问一个最关键问题，不连环追问。 - 用户表达过于宽泛：给 2-4 个可执行选项，让用户一键确认方向。 轻量改写原则（重要）： - 保留用户原意，不改变分析角度，不擅自替换标的。 - 仅补全结构，不臆造数据。例如把“看看茅台”改写为“贵州茅台最近30天K线”。 - 如果用户已明确“代码/名称 + 指标 + 时间”，优先原样执行。 规范化优先级： 1. 先把自然语言问题规范为“市场 + 标的 + 周期/日期 + 指标”。 2. 若能明确代码，就优先改写为显式代码。 3. 若无法明确代码，但能明确市场与名称，则保留名称并保留市场信息，不要臆造代码。 4. 只有在文档明确支持的格式下，才改写为 ticker/symbol。 可直接套用的拆解模板： - 原问题：`帮我看看市场` 执行前引导：`你想看哪一类：1) 大盘实时行情 2) 今日涨停统计 3) 市场资金流向 4) 半导体板块涨跌？` - 原问题：`分析一下茅台` 改写执行：`分析一下 贵州茅台 600519` - 原问题：`宁德时代怎么样` 改写执行：`宁德时代最近30天K线` ## Query Guidelines - 优先保留用户原始表述，不要过度改写。 - 先拆解再执行，改写只做“最小必要补全”。 - 如果用户已经给出股票名称或代码，优先规范化后执行。 - 如果请求依赖具体股票但用户没给标的，先追问股票名称或代码。 - 如果用户问题同时包含多个任务，拆成顺序执行的子问题，并按“先行情后分析”返回。 - 如果执行过程中存在不确定项（例如：名称映射、指数别名、交易所代码、接口可用性），先调用可用的搜索能力进行确认，再继续执行。优先顺序： 1) 工作区内可用搜索技能/搜索工具（用于查本 skill 约束、代码路由、已支持别名） 2) Web Search（用于查公开别名、指数英文简称、交易所代码规则、Akshare 文档变更） - 搜索后仍不确定时，只追问用户 1 个最关键问题，不要连续追问。 - 对于名称类输入，优先用 AkShare 文档对应的列表/实时接口完成运行时解析，不要在 skill 中维护大量固定映射。 - 如果用户的问题明显属于以下模式，可直接执行： | 类型 | 示例问法 | |------|----------| | 指数 | 上证指数实时行情 | | K线 | 茅台最近30天K线 | | 周期 | 宁德时代周线 | | 涨跌停 | 今日涨停统计 | | 资金流 | 茅台资金流向 | | 基本面 | 贵州茅台ROE | | 综合分析 | 分析一下 600519 | | 板块 | 今日半导体板块涨跌 | | 港美股 | 英伟达美股行情 | | 基金债券 | 可转债行情 | | 新闻研报 | 宁德时代研报 | ## Skill Canonicalization Rules skill 在执行前应优先做这些规范化： - A 股名称查询：尽量改写为“名称 + 6 位代码”。如果无法确认代码，可保留名称并带上市场线索，例如“贵州茅台 A股 最近30天K线”。 - 港股名称查询：保留“港股”语义；代码若已知，优先 5 位数字。 - 美股名称查询：保留“美股”语义；若已知交易代码，优先显式代码。 - 指数查询：优先把自然语言改写为“指数名称 + 市场 + K线/实时/分钟”。如果能确认 ticker，可附带 ticker；若不能确认，不要臆造。 - 新闻/研报/资金流类：保留原问题中的标的和范围词，不要额外扩展分析维度。 ## Symbol And Parameter Rules (AkShare 对齐) 根据 AkShare 股票数据文档，执行前优先做以下规范化，减少查不到数据的情况： - A 股日线/周线/月线：优先使用 6 位代码（如 `600519`）查询。 - A 股带交易所前缀代码（如 `sh600519`、`sz000001`）在进入执行前应归一化为 6 位代码。 - A 股分钟级： - 优先按 `period` in `{1, 5, 15, 30, 60}`。 - `1` 分钟数据通常只覆盖近期交易日，且常见不复权限制。 - 港股代码：统一为 5 位数字（如 `00700`），若用户给 `HK0700` 需自动转换为 `00700`。 - 美股代码：优先用交易代码（如 `AAPL`、`NVDA`）。 - 美股东财代码（如 `105.TTE`）在历史行情场景可直接透传。 - 东财系历史接口常见参数： - `period`: `daily|weekly|monthly` 或分钟周期。 - `adjust`: `""|qfq|hfq`（当接口支持时）。 - 涨跌停、两融、公告等按交易日接口：优先标准化为 `YYYYMMDD`。 如果名称或指数别名在执行前仍不确定，不要猜测，先追问一次最关键问题，或者保留市场线索后交给运行时动态解析。 ## Compatibility Matrix 以下是按 stock 文档整理的推荐路由优先级（命中失败再降级）： - A 股实时：`stock_zh_a_spot_em` -> `stock_sh_a_spot_em`/`stock_sz_a_spot_em`/`stock_bj_a_spot_em` - A 股历史 K：`stock_zh_a_hist` - A 股分钟：`stock_zh_a_hist_min_em` -> `stock_zh_a_minute` - 港股实时：`stock_hk_spot_em` - 港股历史 K：`stock_hk_hist` - 港股分钟：`stock_hk_hist_min_em` - 美股实时：`stock_us_spot_em` - 美股历史 K：`stock_us_hist` - 个股信息：`stock_individual_info_em` - 资金流：`stock_individual_fund_flow`/`stock_fund_flow_individual` - 北向南向：`stock_hsgt_fund_flow_summary_em`、`stock_hsgt_fund_min_em`、`stock_hsgt_hist_em` - 新闻：`stock_news_em`、`stock_news_main_cx` 注意：某些市场指数别名在不同版本 AkShare 的接口支持并不一致。skill 负责尽量把问题改写得更明确；代码层再做动态解析与回退。 ## Data Characteristics 根据 AkShare 文档，回答时应显式提示这些数据特征（如与用户问题相关）： - 东财港股与部分跨市场数据常见延时（例如 15 分钟）。 - 日频历史数据通常在收盘后更新，当日收盘价盘中不完整。 - 分钟级接口存在“最近 N 个交易日”窗口限制。 - 某些接口参数看似可选，但在不同版本中会变；失败时优先做最小改写后重试。 ## Response Rules - 优先直接返回命令输出中的核心结果。 - 如果输出是结构化 JSON，不要把整段原样倾倒给用户；提炼成简洁结论，并保留关键数值。 - 如使用了映射（名称 -> 代码、别名 -> 指数代码），在结果里用一句话说明映射依据。 - 如果查询失败，先返回清晰错误原因，再给出更容易命中的改写方式。 - 如果问题过于模糊，先补一个最小必要追问，不要凭空猜股票代码。 ## Failure Handling 常见失败和处理方式： 1. 股票标的不明确。 处理：追问“请给我股票名称或 6 位代码”。 2. 用户问法过于泛化，例如“帮我看看市场”。 处理：先给出 2-4 个可执行方向供用户确认，不直接猜测。 3. 服务暂时不可用或超时。 处理：明确说明当前数据服务异常，请稍后重试，不要编造行情数据。 4. 用户一次问多个维度（例如“给我茅台K线+资金流+估值”）。 处理：拆成子任务顺序执行，并在回复中按小标题分段。 5. 名称/代码/市场映射不清楚（例如“恒生科技K线”但 symbol 不确定）。 处理：先调用可用搜索技能确认映射（本地搜索优先，必要时 web search）；若仍不确定，再追问用户一次。 ## Recommended Workflow 1. 判断是否属于股票数据查询。 2. 按“意图-标的-时间-指标”做轻量拆解。 3. 在 skill 层优先完成 query canonicalization，尽量减少运行时歧义。 4. 若存在不确定项，先调用可用搜索技能/工具核实关键事实（本地搜索优先，必要时 web search）。 5. 判断是否缺少最小必要信息（最多追问 1 个关键问题）。 6. 生成“保留原意、可执行”的查询语句。 7. 执行 `python3 main.py --query "..."`。 8. 将结果整理成用户能直接消费的中文答案（多子任务分段返回）。 ## Search Escalation Rules - 触发条件：出现别名冲突、symbol 无法唯一确定、市场归属不明、接口报“unknown symbol/no data/no callable api found”。 - 搜索目标：先确认“名称→symbol→市场→接口”链路，再执行查询。 - 输出要求：若使用了搜索能力，在回答中简要说明“依据何种映射”完成查询；不要展示冗长原始搜索结果。 ## Example Invocations ```bash python3 main.py --query "茅台最近30天K线" python3 main.py --query "今日涨停统计" python3 main.py --query "上证指数实时行情" python3 main.py --query "宁德时代资金流向" python3 main.py --query "半导体板块涨跌" ``` ## Notes - 本 skill 面向“查数据、看行情、做基础分析”，不是投顾系统。 - 本 skill 的优势是零本地依赖数据栈，终端只需要能运行 Python 3 标准库客户端。 - 如果用户只是想知道能问什么，可以先执行： ```bash python3 main.py --query "帮助" ```