大宗商品数据智能查询

技能文档

---
name: mysteel-datasearch
title: 大宗商品数据智能查询
category: 金融投资
description: 查询大宗商品期现货价格、宏观经济指标、产业链供需、进出口库存与多市场金融数据，支持自然语言查询、历史趋势、区域与企业价格对比及结算确认单生成。当用户询问期货现货价格、历史行情、宏观数据或产业链数据时触发。触发词：大宗商品价格、期货查询、现货价格、螺纹钢价格。
---

# 大宗商品数据智能查询

大宗商品与宏观经济数据综合查询技能，基于专业数据平台提供价格数据服务。

## 未配置密钥时的引导回复

当用户查询价格数据但尚未配置密钥时，请按以下引导回复用户：

看起来还没有配置 API 密钥。要使用数据查询，需要先获取一个 API Key。

**获取方式：** 浏览器打开 [数据服务开放平台](https://data.mysteel.com/skills/index.html)，在「API Key」一栏点击「生成」或「复制」即可获取。

请问您是否已有 API Key？如果有，请直接告诉我，我会自动保存并立即为您查询。

### 用户提供密钥后的处理流程

1. 调用 `python scripts/search.py --api-key "<密钥>" "<查询文本>"` 保存密钥并执行查询
2. 保存成功后告知用户密钥已保存，后续可直接使用

## 密钥配置

脚本支持多级 API Key 获取方式（按优先级）：

1. **环境变量**（优先级最高）：设置环境变量 `mysteel_skill_auth_key`
   - 变量名：`mysteel_skill_auth_key`
   - 变量值：您的 API 密钥

2. **配置文件**（次优）：在 `references/api_key.md` 文件第一行写入 API 密钥

3. **对话输入**（兜底）：在对话中直接提供 API 密钥
   - 脚本通过 `--api-key` 参数接收用户在对话中提供的密钥
   - **自动保存**：当通过对话输入 API 密钥时，脚本会自动将其保存到 `references/api_key.md` 文件中，供后续使用

如果以上方式都无法获取到 API 密钥，脚本会提示用户进行配置。

## 技能工作流

### 步骤1：确认密钥可用

按「密钥配置」的优先级获取 API Key；均不可用时按引导话术向用户索取，不得猜测或编造密钥。

### 步骤2：执行查询

```bash
python scripts/search.py "<查询文本>"
```

通过对话提供密钥时：

```bash
python scripts/search.py "<查询文本>" --api-key "<用户提供的API密钥>"
```

### 步骤3：读取结果并回复

推荐使用 CSV 输出模式，并**根据需要使用过滤参数减少数据量**：

```bash
# 查询最新10条价格（最常用）
python scripts/search.py "螺纹钢最新价格" --csv --limit 10

# 查询最近30天价格
python scripts/search.py "铜期货价格" --csv --days 30

# 查询特定日期范围
python scripts/search.py "热卷价格" --csv --start-date 2024-01-01 --end-date 2024-03-31
```

读取 CSV 时不要一次性读入整个文件，按需分段查看：

```bash
# 查看文件元数据（了解数据概况）
head -10 output/螺纹钢.csv

# 仅读取前N行数据
head -20 output/螺纹钢.csv | tail -n +10

# 按日期过滤
grep -E "^2024-01" output/螺纹钢.csv

# 查看文件统计信息
wc -l output/螺纹钢.csv
```

### 步骤4：按规范回复

回复中需要详细标明数据所引用的指标（indexName）。

## CSV 文件格式

CSV 文件包含元数据头注释，格式如下：

```
# index_name: 螺纹钢_上海_HRB400E
# unit: 元/吨
# total_rows: 365
# date_range: 2023-01-15 ~ 2024-01-15
# generated: 2024-01-15 10:30:00
#
date,price,unit,change,change_pct
2024-01-15,3800,元/吨,+20.00,+0.53%
2024-01-14,3780,元/吨,-10.00,-0.26%
```

## 完整参数列表

- `--csv`：保存结果为 CSV 文件到 output 目录
- `--output-dir`：指定 CSV 输出目录（默认：技能目录/output）
- `--limit N`：限制每个文件最多 N 行数据
- `--days N`：仅查询最近 N 天的数据
- `--start-date YYYY-MM-DD`：起始日期过滤
- `--end-date YYYY-MM-DD`：结束日期过滤
- `--max-files N`：限制 output 目录最多保留 N 个 CSV 文件（默认：100），超过时删除最旧的文件
- `--api-key <API_KEY>`：直接提供 API 密钥（会自动保存到 `references/api_key.md` 文件）

## 查询能力

### 1. 价格数据查询
- **期货价格**：最新收盘价、结算价、涨跌幅
- **现货价格**：实时报价、区域价格、企业报价
- **历史数据**：趋势分析、周期对比

### 2. 宏观经济数据
- 全球宏观经济主要指标
- 分国别/地区数据查询
- GDP、CPI、PMI 等指标

### 3. 产业链数据
- 上游原材料价格
- 下游产品价格
- 供需平衡数据
- 进出口数据
- 库存数据

### 4. 金融市场数据
- 期权价格与隐含波动率
- 股票行情
- 债券收益率
- 外汇汇率

### 5. 智能分析
- 类目识别与指标识别
- 多维度数据对比
- 口径标准化
- 差值计算

### 6. 结算凭证
- 支持贸易双方成交数量输入

## 接口参考

详细接口文档参见 [api_reference.md](references/api_reference.md)。接口返回 JSON 格式数据，主要包含价格数据（数值、单位、涨跌幅、时间戳）、图表数据（支持历史趋势）与对比数据（多维度价格对比）。

## 最佳实践

1. **查询表达**：使用自然语言描述查询需求，接口支持智能语义解析
2. **数据对比**：可同时查询多个品种或区域进行对比分析
3. **历史溯源**：支持基于时间范围的查询，获取历史趋势

使用说明

# 大宗商品数据智能查询

用自然语言查询大宗商品期现货价格、宏观经济指标、产业链供需与多市场金融数据，结果可落盘为 CSV 便于分析。

## 使用

```bash
# 首次使用配置密钥（获取入口见 SKILL.md）
export mysteel_skill_auth_key=<你的API密钥>

python scripts/search.py "螺纹钢最新价格" --csv --limit 10
```

也可以直接对助手说「查一下最近30天铜期货价格」。

## 工作原理

脚本把自然语言查询发送给数据服务接口，由服务端完成类目与指标识别、口径标准化，返回价格、涨跌幅与时间序列；`--csv` 模式将结果连同元数据头写入 output 目录，`--limit/--days/--start-date/--end-date` 控制数据量。支持期货、现货、宏观、产业链、期权股票债券外汇等多类数据与结算凭证生成。

## 目录结构

- `SKILL.md`：密钥配置、工作流与查询能力说明
- `scripts/search.py`：查询脚本
- `references/api_reference.md`：接口参考
- `references/api_key.md`：本地密钥存放（对话输入时自动写入）

## 依赖

- `python3`（仅标准库）
- 需联网访问数据服务（按量计费，需密钥）

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。