stock-price-query

# Stock Price Query Skill 实时股票行情与大盘指数查询技能，覆盖 **A 股（沪深两市）**、**港股**、**美股**三大市场。支持**单只查询**和**批量查询**（一次查询多只股票对比），轻量无依赖，无需 API Key，适合聊天场景下的快速股价查询——秒级获取当前价格、涨跌幅、开高低收、成交量等行情数据。 Real-time stock quote and market index tool covering A-shares, Hong Kong, and US stocks. Supports batch queries for comparing multiple stocks in one call. Quick chat-friendly price checks with zero dependencies and no API key needed. ## Overview 实时股票价格查询技能，支持查询 A 股（沪深两市）、港股和美股的实时行情数据。通过调用免费公开的行情 API 获取数据，返回结构化的股票信息。 ## When to Use 当用户的请求涉及以下场景时触发此技能： - 查询股价："茅台多少钱"、"查一下宁德时代" - 了解涨跌："腾讯今天涨了吗"、"00700 行情" - 股票代码查询："600519"、"NVDA price" - 多只对比："比亚迪和英伟达的股价"、"帮我看下茅台、腾讯和苹果" - 批量查询："查一下这几只：600519, 00700, AAPL" - 大盘指数："上证指数多少"、"大盘怎么样"、"恒指行情" - 关键词触发："查股票"、"股票行情"、"stock price" ## How to Use ### 查询流程 1. **解析用户输入**：从用户消息中提取股票代码。如果用户提供的是中文名称，需先根据下方映射表将名称转换为股票代码（脚本仅接受股票代码作为输入）。 2. **识别市场**：根据股票代码格式自动识别所属市场： - A 股沪市：以 `sh` 开头或 6 位数字以 6 开头（如 `sh600519`、`600519`） - A 股深市：以 `sz` 开头或 6 位数字以 0/3 开头（如 `sz000001`、`300750`） - 港股：以 `hk` 开头或纯数字 5 位及以下（如 `hk00700`、`00700`），港股指数为纯字母代码（如 `HSI`、`HSCEI`） - 美股：纯英文字母代码（如 `AAPL`、`TSLA`、`GOOGL`），美股指数以 `.` 开头（如 `.IXIC`、`.DJI`、`.INX`） 3. **执行查询脚本**：运行 `scripts/stock_query.py` 获取实时数据。 4. **格式化输出**：将结果以清晰友好的格式展示给用户。 ### 脚本调用方式 **单只查询：** ```bash python3 {{SKILL_DIR}}/scripts/stock_query.py <stock_code> [market] ``` **批量查询（推荐用于多只对比）：** ```bash python3 {{SKILL_DIR}}/scripts/stock_query.py <code1,code2,code3> ``` **参数说明：** - `stock_code`（必需）：股票代码，如 `600519`、`AAPL`、`00700`。批量查询时用逗号分隔，最多 20 只。 - `market`（可选）：市场标识，可选值为 `sh`（沪市）、`sz`（深市）、`hk`（港股）、`us`（美股）。不提供时脚本会自动识别。批量查询时不需要此参数（自动识别各只股票的市场）。 **单只查询输出格式**：JSON 对象（`pe_ratio` 和 `market_cap` 在数据源可用时返回）： ```json { "code": "600519", "name": "贵州茅台", "market": "sh", "current_price": 1688.00, "change": 12.50, "change_percent": 0.75, "open": 1680.00, "high": 1695.00, "low": 1675.00, "prev_close": 1675.50, "volume": 2345678, "amount": 3956789012.50, "time": "2026-02-24 15:00:00", "pe_ratio": 28.35, "market_cap": 2120000000000.00, "status": "success" } ``` **批量查询输出格式**：JSON 数组，每只股票一个对象： ```json [ { "code": "600519", "name": "贵州茅台", "market": "sh", "current_price": 1688.00, "change": 12.50, "change_percent": 0.75, "status": "success", ... }, { "code": "00700", "name": "腾讯控股", "market": "hk", "current_price": 420.60, "change": 5.20, "change_percent": 1.25, "status": "success", ... }, { "code": "AAPL", "name": "APPLE", "market": "us", "current_price": 178.50, "change": -1.30, "change_percent": -0.72, "status": "success", ... } ] ``` ### 常见股票名称与代码映射（供 agent 参考） 脚本仅接受股票代码作为输入，不支持中文名称。当用户提供股票名称时，agent 应先根据下表将名称转换为对应代码后再调用脚本： **大盘指数：** | 名称 | 代码 | 市场 | |------|------|------| | 上证指数/大盘 | 000001 | sh | | 深证成指 | 399001 | sz | | 创业板指 | 399006 | sz | | 恒生指数/恒指 | HSI | hk | | 国企指数/H股指数 | HSCEI | hk | | 纳斯达克/纳指 | .IXIC | us | | 道琼斯/道指 | .DJI | us | | 标普500 | .INX | us | **热门个股：** | 名称 | 代码 | 市场 | |------|------|------| | 贵州茅台 | 600519 | sh | | 中国平安 | 601318 | sh | | 招商银行 | 600036 | sh | | 工商银行 | 601398 | sh | | 中国石油 | 601857 | sh | | 比亚迪 | 002594 | sz | | 宁德时代 | 300750 | sz | | 五粮液 | 000858 | sz | | 美的集团 | 000333 | sz | | 腾讯控股 | 00700 | hk | | 阿里巴巴 | 09988 | hk | | 美团 | 03690 | hk | | 小米集团 | 01810 | hk | | 京东 | 09618 | hk | | 苹果/Apple | AAPL | us | | 特斯拉/Tesla | TSLA | us | | 英伟达/NVIDIA | NVDA | us | | 微软/Microsoft | MSFT | us | | 谷歌/Google | GOOGL | us | | 亚马逊/Amazon | AMZN | us | | Meta/Facebook | META | us | 对于不在映射表中的股票名称，提示用户提供准确的股票代码。 ### 输出格式要求 **单只查询**：查询成功后，以如下紧凑格式展示结果（不要使用表格，避免消息过长导致飞书分页）： ``` 📈 **{股票名称}**（{股票代码}.{市场}） 💰 当前价格：{current_price} 元/港元/美元 | 📊 涨跌幅：{change} ({change_percent}%) ↑/↓ 📅 行情时间：{time} 📊 今开 {open} | 最高 {high} | 最低 {low} | 昨收 {prev_close} 📦 成交量：{volume} | 成交额：{amount} 📐 市盈率：{pe_ratio} | 总市值：{market_cap}（如有） ``` **批量查询**：多只股票依次展示，每只之间空一行： ``` 📈 **贵州茅台**（600519.SH） 💰 1688.00 元 | 🟢 +12.50 (+0.75%) ↑ 📈 **腾讯控股**（00700.HK） 💰 420.60 港元 | 🟢 +5.20 (+1.25%) ↑ 📈 **APPLE**（AAPL.US） 💰 178.50 美元 | 🔴 -1.30 (-0.72%) ↓ ``` 涨跌幅为正时使用 🟢 和 ↑，为负时使用 🔴 和 ↓。成交额如果超过 1 亿，用"亿"为单位显示（保留两位小数）；超过 1 万不足 1 亿，用"万"为单位显示。 ## Edge Cases - **输入安全校验**：脚本在执行前会严格校验所有输入参数。`stock_code` 仅允许字母、数字和前导点号（正则 `^\.?[A-Za-z0-9]{1,10}$`，前导点号用于支持美股指数代码如 `.IXIC`、`.DJI`、`.INX`），`market` 仅允许白名单值（`sh`/`sz`/`hk`/`us`）。任何包含特殊字符、shell 元字符或超长输入都会被拒绝，防止命令注入。 - **批量查询数量限制**：一次最多查询 20 只股票，超出时返回错误提示。 - **批量查询部分失败**：批量查询中如果部分股票代码无效，有效的股票仍正常返回结果，无效的会在对应位置返回错误信息。agent 应正常展示成功的结果，对失败的提示用户。 - **股票代码无效**：返回 "无法识别该股票代码，请确认后重试。支持 A 股（6 位数字）、港股（5 位数字）、美股（英文字母）。" - **网络请求失败**：返回 "网络请求失败，请稍后重试。" - **非交易时段**：正常返回最近的收盘数据，并提示 "当前为非交易时段，显示的是最近一次的收盘数据。" - **股票名称模糊**：脚本不支持名称输入。如果用户提供的名称无法在映射表中匹配，agent 应提示用户提供准确的股票代码。 - **API 限流**：如遇到限流，等待 1 秒后重试一次，仍失败则提示用户稍后再试。