stock-query

# 全球股票/ETF/基金/指数 实时价格查询

## 前置依赖

运行本 skill 需要以下命令行工具：

| 工具 | 用途 |
|------|------|
| `curl` | 调用股票行情 API |
| `iconv` | 将 API 响应从 GBK 转码为 UTF-8 |

## 支持的市场与标的

| 市场     | 代码格式                  | API 前缀     | 数据源       | 备用数据源   |
|---------|--------------------------|-------------|-------------|-------------|
| 沪市股票  | 6 开头 6 位数字           | `sh`        | 腾讯财经     | 新浪财经     |
| 深市股票  | 0 或 3 开头 6 位数字      | `sz`        | 腾讯财经     | 新浪财经     |
| 沪市 ETF | 5 开头 6 位数字           | `sh`        | 腾讯财经     | 新浪财经     |
| 深市 ETF | 1 开头 6 位数字           | `sz`        | 腾讯财经     | 新浪财经     |
| 沪市指数  | 000 开头 6 位数字         | `sh`        | 腾讯财经     | 新浪财经     |
| 深市指数  | 399 开头 6 位数字         | `sz`        | 腾讯财经     | 新浪财经     |
| 场外基金  | 排除法（见 Step 2）       | —           | 天天基金     | 东方财富     |
| 港股     | 5 位数字（如 00700）      | `hk`        | 腾讯财经     | —           |
| 美股     | 英文 ticker（如 AAPL）    | `us`        | 腾讯财经     | —           |
| 美股指数  | .DJI / .IXIC / .SPX     | `us`        | 腾讯财经     | —           |

## 工作流程

### Step 0: Meta 命令路由

在解析标的代码前，先检查用户输入是否为 meta 命令：

**version 命令**：输入为 `version`、`-v`、`--version`（大小写不敏感）
→ 直接输出版本信息，**不执行后续步骤**：

```
stock-query v2.0.4
```

**help 命令**：输入为 `help`、`-h`、`--help`（大小写不敏感）
→ 直接输出用法说明，**不执行后续步骤**：

```
stock-query v2.0.4 — 全球股票/ETF/基金/指数实时行情查询

用法：
  /stock-query <代码> [代码2 ...]   查询一个或多个标的
  /stock-query version              显示版本号
  /stock-query help                 显示本帮助

支持的市场：
  A股（沪/深）  6位数字，如 601991 000001
  港股          5位数字，如 00700 09988
  美股          英文ticker，如 AAPL TSLA NVDA
  美股指数      .DJI  .IXIC  .SPX
  ETF           6位数字，如 510300 159915
  场外基金      6位数字，如 014978

常用示例：
  /stock-query AAPL
  /stock-query 00700 09988
  /stock-query AAPL 00700 601991 510300
```

---

### Step 1: 解析用户输入

从用户消息中提取标的代码。支持以下输入形式：

- **6 位纯数字** → A 股（股票/ETF/指数/基金）
- **5 位纯数字** → 港股（如 00700、09988）
- **英文字母或英文+数字** → 美股 ticker（如 AAPL、TSLA、BIDU）
- **中文/英文名称** → 尝试匹配常见标的（见下表）

常见标的速查：

**A 股：**
- 黄金ETF → 518880（沪市）
- 红利低波ETF → 512890（沪市）
- 沪深300ETF → 510300（沪市）
- 卫星ETF → 563230（沪市）
- 创业板ETF → 159915（深市）
- 中证500ETF → 510500（沪市）
- 上证指数 → 000001（沪市指数）
- 深证成指 → 399001（深市指数）
- 创业板指 → 399006（深市指数）
- 沪深300 → 000300（沪市指数）
- 上证50 → 000016（沪市指数）
- 中证500 → 000905（沪市指数）
- 中证1000 → 000852（沪市指数）

**港股：**
- 腾讯 → 00700
- 阿里巴巴 → 09988
- 美团 → 03690
- 小米 → 01810
- 比亚迪（港股）→ 01211
- 恒生指数 → HSI（腾讯 API 前缀 `hkHSI`）

**美股：**
- 苹果 → AAPL
- 谷歌 → GOOG
- 特斯拉 → TSLA
- 英伟达 → NVDA
- 微软 → MSFT
- 亚马逊 → AMZN
- 百度 → BIDU
- 阿里巴巴（美股）→ BABA
- 哔哩哔哩 → BILI
- 拼多多 → PDD
- 道琼斯指数 → .DJI
- 纳斯达克指数 → .IXIC
- 标普500指数 → .SPX

如果无法确定代码，向用户确认。

### Step 2: 识别标的市场

```
第一步：判断输入类型

if input 是 5 位纯数字:
    market = 'hk'           # 港股
    type = 'hk_stock'
elif input 以 . 开头 (如 .DJI):
    market = 'us'           # 美股指数
    type = 'us_index'
elif input 包含英文字母:
    market = 'us'           # 美股
    type = 'us_stock'
elif input 是 6 位纯数字:
    # A 股市场识别（原有逻辑）
    if code.startsWith('000') and len==6:
        market = 'sh'       # 沪市指数（注意与深市股票歧义）
        type = 'index_or_stock'
    elif code.startsWith('399'):
        market = 'sz'       # 深市指数
        type = 'index'
    elif code.startsWith('6'):
        market = 'sh'       # 沪市股票
        type = 'stock'
    elif code.startsWith('0') or code.startsWith('3'):
        market = 'sz'       # 深市股票（可能是场外基金，需二次确认）
        type = 'stock_or_fund'
    elif code.startsWith('5'):
        market = 'sh'       # 沪市 ETF
        type = 'etf'
    elif code.startsWith('1'):
        market = 'sz'       # 深市 ETF
        type = 'etf'
    else:
        type = 'fund'       # 场外基金（2/4/7/8/9 开头）

第二步：A 股歧义处理

对 type='index_or_stock' 的 000 开头代码：
1. 用户提到"指数""大盘""上证" → sh 前缀（指数）
2. 用户提到股票名称或"股票" → sz 前缀（深市股票）
3. 无法判断：先查 sh{code}，名称含"指数"则确认为指数；否则查 sz{code}
4. 典型歧义：000001 → sh000001 上证指数，sz000001 平安银行

对 type='stock_or_fund' 的代码做二次确认：
1. 用腾讯接口查询 sz{code}
2. 若返回空/无效，判定为场外基金
3. 若返回数据，确认为深市股票

第三步：防碰撞校验
查询返回后校验名称与用户预期一致。不符时尝试另一市场前缀。
```

### Step 3: 查询股票/ETF/指数 实时行情

#### 3a. 腾讯财经（首选，支持全球市场）

腾讯财经 API 统一支持 A 股、港股、美股查询。

```bash
# A 股
curl -s "https://qt.gtimg.cn/q=sh601991,sz000001" | iconv -f GBK -t UTF-8

# 港股
curl -s "https://qt.gtimg.cn/q=hk00700,hk09988" | iconv -f GBK -t UTF-8

# 美股
curl -s "https://qt.gtimg.cn/q=usAAPL,usTSLA" | iconv -f GBK -t UTF-8

# 美股指数
curl -s "https://qt.gtimg.cn/q=us.DJI,us.IXIC,us.SPX" | iconv -f GBK -t UTF-8

# 混合查询（可跨市场批量）
curl -s "https://qt.gtimg.cn/q=sh601991,hk00700,usAAPL" | iconv -f GBK -t UTF-8
```

**重要：腾讯接口返回 GBK 编码，必须通过 `iconv -f GBK -t UTF-8` 转码。**

API 前缀规则：

| 市场     | 前缀格式              | 示例                      |
|---------|----------------------|--------------------------|
| 沪市     | `sh` + 6位代码       | `sh601991`               |
| 深市     | `sz` + 6位代码       | `sz000001`               |
| 港股     | `hk` + 5位代码       | `hk00700`                |
| 美股     | `us` + ticker        | `usAAPL`、`usBIDU`       |
| 美股指数  | `us` + .代码         | `us.DJI`、`us.IXIC`     |

响应格式为 `~` 分隔的文本，各市场字段结构一致：

| 索引 | 含义                                        |
|-----|---------------------------------------------|
| [0] | 市场标识（1=A股, 100=港股, 200=美股）          |
| [1] | 名称（中文）                                  |
| [2] | 代码                                         |
| [3] | 最新价                                       |
| [4] | 昨收                                         |
| [5] | 今开                                         |
| [6] | 成交量                                       |
| [30]| 日期时间                                      |
| [31]| 涨跌额（已算好）                               |
| [32]| 涨跌幅 %（已算好，直接使用）                    |
| [33]| 最高                                         |
| [34]| 最低                                         |

注意事项：
- 日期时间格式因市场不同：A 股为 `YYYYMMDDHHMMSS`，港股为 `YYYY/MM/DD HH:MM:SS`，美股为 `YYYY-MM-DD HH:MM:SS`
- 涨跌额和涨跌幅由接口直接返回，无需手动计算
- [0] 字段可用于区分市场：1=A股, 51=深市个股, 100=港股, 200=美股

**频率限制：** 腾讯接口为公共 API，过度调用会被封禁 IP。健康使用频率：
- 单次请求最多 **100 个代码**
- 请求间隔不低于 **100ms**（即每秒最多 10 次请求）
- 批量查询时优先合并为单次请求，避免逐个查询

#### 3b. 新浪财经（A 股备用）

仅用于 A 股。当腾讯接口超时或返回空时回退：

```bash
curl -s "https://hq.sinajs.cn/list={market}{code}" \
  -H "Referer: https://finance.sina.com.cn" \
  | iconv -f GBK -t UTF-8
```

新浪字段索引（引号内逗号分隔，0-based）：
- [0] 名称, [1] 今开, [2] 昨收, [3] 最新价, [4] 最高, [5] 最低
- [8] 成交量, [9] 成交额, [30] 日期, [31] 时间

新浪涨跌额 = [3] - [2]，涨跌幅 = ([3] - [2]) / [2] × 100%

### Step 4: 查询场外基金净值

对 type 为 fund 的标的（仅 A 股场外基金），按优先级使用：

**4a. 实时估值（交易日盘中，优先使用）：**
```bash
curl -s "http://fundgz.1234567.com.cn/js/{code}.js"
```
> **安全说明**：该接口为 HTTP（无 TLS），请求中仅含基金代码，不涉及用户敏感信息。

响应字段：
- `fundcode`: 基金代码
- `name`: 基金名称
- `jzrq`: 最新净值日期
- `dwjz`: 上一交易日单位净值
- `gsz`: 实时估算净值
- `gszzl`: 估算涨跌幅(%)
- `gztime`: 估值时间

**4b. 备用：最新确认净值**
```bash
curl -s "https://api.fund.eastmoney.com/f10/lsjz?fundCode={code}&pageIndex=1&pageSize=1" \
  -H "Referer: https://fund.eastmoney.com"
```

若 4a 返回 `jsonpgz()` 空值，则使用 4b。

**QDII 基金特殊处理：**
基金名称含"QDII""纳斯达克""标普""海外""美国""全球"，且净值日期落后 >2 天，属正常——QDII 基金净值公布有 T+2 至 T+7 的系统性延迟。附加提示：`⏳ QDII基金，净值公布有 T+2~T+7 延迟`

### Step 5: 格式化输出

以 Markdown 表格输出：

```
| 代码    | 名称           | 市场  | 最新价    | 涨跌幅          | 最高      | 最低      | 币种 | 更新时间            |
|---------|---------------|-------|----------|----------------|----------|----------|------|-------------------|
| 000001  | 上证指数       | A股   | 3874.39  | 🔴 +1.60%      | 3881.20  | 3850.10  | CNY  | 2026-03-24 15:00  |
| 601991  | 大唐发电       | A股   | 4.21     | 🔴 +4.47%      | 4.25     | 4.06     | CNY  | 2026-03-24 15:00  |
| 00700   | 腾讯控股       | 港股  | 511.000  | 🔴 +2.53%      | 515.000  | 498.000  | HKD  | 2026-03-24 16:00  |
| AAPL    | 苹果          | 美股  | 251.49   | 🟩 +1.41%      | 254.60   | 250.28   | USD  | 2026-03-23 16:00  |
| .DJI    | 道琼斯        | 美股  | 46208.47 | 🟩 +1.38%      | 46350.12 | 45980.33 | USD  | 2026-03-23 17:11  |
| 014978  | 华安纳指100C  | 基金  | 6.8897   | 🟢 -1.43%（估） | —        | —        | CNY  | 2026-03-24 15:00  |
```

涨跌标识规则：
- **A 股/港股（红涨绿跌）**：上涨 🔴 `+X.XX%`，下跌 🟢 `-X.XX%`
- **美股（绿涨红跌）**：上涨 🟩 `+X.XX%`，下跌 🟥 `-X.XX%`
- **平盘**：⚪ `0.00%`（所有市场通用）

如果输出环境支持 HTML 或富文本，使用颜色标签增强显示：
- A 股/港股上涨：`<span style="color:#e54d42">🔴 +1.41%</span>`
- A 股/港股下跌：`<span style="color:#39b54a">🟢 -0.29%</span>`
- 美股上涨：`<span style="color:#39b54a">🟩 +1.41%</span>`
- 美股下跌：`<span style="color:#e54d42">🟥 -0.29%</span>`

其他输出规则：
- 涨跌幅为正数前面加 `+`，为负数自带 `-`
- 价格保留与原始数据相同的小数位数
- 场外基金盘中显示估算净值，在涨跌幅后标注 `（估）`
- 非交易时段在表格下方注明：`⏸ 非交易时段，显示上一交易日收盘数据`
- QDII 基金在表格下方注明：`⏳ QDII基金，净值公布有 T+2~T+7 延迟`
- 美股数据在非美股交易时段显示的是上一交易日收盘价

### Step 6: 持仓市值计算（可选）

如果用户同时提供了持仓份额/股数，额外输出市值表：

```
| 代码   | 名称      | 持仓   | 成本价  | 最新价  | 市值       | 浮盈/亏         | 盈亏比          |
|--------|----------|--------|--------|--------|-----------|----------------|----------------|
| 600519 | 贵州茅台  | 100股  | 1680.0 | 1725.0 | 172,500   | 🔴 +4,500      | 🔴 +2.68%     |
| AAPL   | 苹果     | 50股   | 220.0  | 251.49 | 12,574.50 | 🟩 +1,574.50   | 🟩 +14.31%    |
```

汇总行：
```
📊 持仓合计：市值 185,074.50 | 总成本 179,000 | 浮盈 +6,074.50（+3.39%）
```

注意：跨市场持仓汇总时，需提示用户各币种的市值分开统计，或按实时汇率折算。

## 数据源降级策略

- A 股（股票/ETF/指数）：腾讯财经（首选）→ 新浪财经（备用）→ 报错
- 港股/美股：腾讯财经（唯一数据源）→ 报错
- 场外基金：天天基金估值（首选）→ 东方财富净值（备用）→ 报错

## 错误处理

| 场景              | 处理方式                                                     |
|------------------|--------------------------------------------------------------|
| 代码无法识别       | 提示 "未找到标的 {code}，请确认代码是否正确"                      |
| 腾讯接口超时/空值  | A 股自动回退新浪；港股/美股提示 "数据源暂时不可用"                 |
| 新浪接口也失败     | 重试 1 次，仍失败则提示 "数据源暂时不可用，请稍后重试"              |
| 场外基金无估值数据  | 回退到确认净值接口，标注 `（净值，非估值）`                        |
| 市场前缀碰撞       | 校验返回名称与用户预期是否一致，不一致时尝试另一市场前缀             |
| 中文乱码          | 检查是否遗漏 iconv 转码步骤（腾讯和新浪接口均为 GBK 编码）         |

## 安全与隐私说明

- **场外基金估值接口（fundgz.1234567.com.cn）**：当前仅提供 HTTP（无 TLS）。请求中仅发送基金代码，不涉及用户身份或敏感数据。
- **portfolio_file 配置**：`skill.yaml` 中为可选配置项。**本 skill 附带的脚本不会自动读取该路径**；若配置此项，agent 可能在用户指令下读取该文件。⚠️ 本 skill 同时具有 shell 和 network 权限，理论上读取的文件内容可被纳入网络请求（如查询持仓数据时）。**请勿将此项指向包含账户凭证、API 密钥或其他敏感信息的文件。**

## 交易时间参考

| 市场       | 交易时段（当地时间）                    | 时区       |
|-----------|---------------------------------------|-----------|
| A 股/ETF   | 工作日 09:30-11:30, 13:00-15:00       | UTC+8     |
| 场外基金估值 | 工作日 09:30-15:00                    | UTC+8     |
| 港股       | 工作日 09:30-12:00, 13:00-16:00       | UTC+8     |
| 美股       | 工作日 09:30-16:00（夏令时 21:30-04:00 北京） | UTC-4/-5 |
| QDII 基金  | 净值 T+2 至 T+7 公布                  | —         |