宏观经济数据查询 (mx_macro_data)

通过文本输入查询宏观经济数据，接口返回 JSON 后会自动转换为CSV并生成对应的内容描述 txt文件。

密钥来源与安全说明

• 本技能仅使用一个环境变量：EM_API_KEY。
• EM_API_KEY由东方财富妙想服务（https://ai.eastmoney.com/mxClaw）签发，用于其接口鉴权。
• 在提供密钥前，请先确认密钥来源、可用范围、有效期及是否支持重置/撤销。
• 禁止在代码、提示词、日志或输出文件中硬编码/明文暴露密钥。

⚠️ 核心输入约束 (Critical Input Constraints)

• 时间维度：支持相对时间表述（如“今年”、“过去三年”、“上月”）。
• 地域维度：支持宏观地区表述（如“中国”、“美国”、“欧元区”、“华东地区”、“中国各省”），无需拆解为具体省市列表。

1. 禁止模糊商品类别 (No Ambiguous Commodities)

• 禁止输入大类统称（如“稀土金属”、“有色金属”、“农产品”、“能源”、“科技股”）。
• 要求：必须解包为具体的交易品种名称或代码。
  • ❌ 错误："查询稀土价格走势"
  • ✅ 正确："查询氧化镨钕、氧化镝、氧化铽的价格走势"

2. 禁止宏观泛指指标 (No Macro Generalizations without Metrics)

• 禁止输入：宽泛的经济概念而无具体指标（如“中国经济”、“美国制造业状况”、“全球通胀情况”）。
• 要求：必须指定具体的指标名称（如 GDP、CPI、PMI、失业率、工业增加值等）。
  • ❌ 错误："查询中国经济数据"
  • ✅ 正确："查询中国 GDP 同比增速、中国 CPI 同比"
  • ✅ 正确："查询美国制造业 PMI"(地域允许宏观，但指标必须具体)

3. 时间与地域的灵活性 (Flexible Time & Region)

• 时间无需绝对日期。
  • ✅ 允许："查询中国过去五年的M2增速"、"查询上个月美国的非农数据"、"查询黄金今日价格"。
  • ✅ 允许（缺省）："查询德国失业率"。
• 地域：无需拆解为子集列表。
  • ✅ 允许："查询华东地区GDP"、"查询中国各省GDP"。
  • ⚠️ 注意：若涉及“主要新兴市场”、“Top 5 国家”等动态排名指代，仍建议上层模型解包为具体国家列表（如"查询中国、印度、巴西的M2"），以确保数据源一致性。

🔄 输出接口与上层规划协议 (Output Interface & Orchestration Protocol)

本 Skill 仅负责执行单次查询并生成文件。为实现数据完整性保障，上层规划引擎必须根据以下协议，对本 Skill 的输出进行后续处理。

1. 输出文件结构 (Output File Structure)

执行mx_macro_data后，Skill 将在指定目录下生成一个或多个 CSV 文件，以及一个描述文件。

• CSV 文件：mx_macro_data_<查询ID>_<频率>.csv
  • 示例：mx_macro_data_4591GG28_yearly.csv、mx_macro_data_4591GG28_quarterly.csv、mx_macro_data_4591GG28_monthly.csv
  • 注意：文件数量和频率取决于查询指标的可用性（yearly、quarterly、monthly、weekly、daily）。
• 描述文件：mx_macro_data_<查询ID>_description.txt
  • 包含数据来源、时间范围、指标说明等基础信息。

2. 上层规划引擎必须执行的“完整性复核”逻辑 (Mandatory Verification Logic for Orchestrator)

上层规划引擎在调用mx_macro_data后，必须Execute the following workflow to ensure the completeness of the final results:

Phase A: Task Parsing & Expectation Planning

1. Parse the original user intent: Extract the core elements from the user query.
2. Build the Expected Universe:
   • Region: Use the planning engine's built-in knowledge base, search engine, or LLM reasoning capabilities to parse vague regional descriptions into specific administrative units. For example: "Provinces of China" → 34 provincial-level administrative regions; "East China region" → the 7 provinces/municipalities of Shanghai, Jiangsu, Zhejiang, Anhui, Fujian, Jiangxi, Shandong.
   • Indicators: Decompose compound indicators into independent indicators. For example: "GDP, CPI" → ["GDP", "CPI"].
   • Frequency: Infer the expected frequency based on the query context, potentially generating data files for multiple frequencies (yearly, quarterly, monthly, etc.).

Phase B: File Reading & Gap Detection

1. Obtain the output file list: Retrieve all CSV file paths generated bymx_macro_data.
2. Read and analyze each file:
   • Use the planning engine's built-in code execution capabilities (e.g., Python Sandbox) to read the CSV.
   • Extract the actual covered(region, indicator)combinations and their counts from each file.
3. Perform difference calculation:
   • Foreach frequency's file, calculate separatelyMissing_Pairs_<Frequency> = Expected_Universe - Actual_From_CSV_File.
   • Identify the specific missing items (e.g., "Tibet-GDP" is missing in the annual frequency data).

Phase C: Decision & Iterative Invocation

⚠️Mandatory requirement: The upper-level planning enginemustexecute the following completion process and must not deliver results directly when missing data exists.

1. Determine whether completion is needed:

   • If theMissing_Pairssets for all frequencies are empty:End the processand deliver the existing files.
   • If there exist non-emptyMissing_Pairssets:Must enter the completion processand cannot skip it.

2. Construct Completion Queries:

   • Based on the missing items inMissing_Pairs_<Frequency>, construct new natural language queries by incorporating the temporal dimension of the original query.
   • Example:

     Missing_Pairs_季 = [("西藏", "GDP"), ("宁夏", "GDP")]
     ↓
     补全查询 = "查询西藏自治区、宁夏回族自治区的 GDP 季度数据，时间范围同前次查询"
     

3. Re-invokemx_macro_data:

   • Use the newly constructed completion queries to re-invoke this Skill to retrieve the missing data.

4. Iterative Loop:

   • Repeat the execution ofPhase B (Difference Detection) → Phase C (Decision Completion)until any of the following conditions is met:
     • ✅ All missing items across all frequencies have been completed.
     • ⚠️ The maximum number of retries (5) is reached, at which point the data items that could not be completed should be reported to the user.

Phase D: Final Delivery

1. Data Merging (Optional):
   • If necessary, results from multiple queries at the same frequency (e.g., multiplequarterly.csvfiles) can be merged into a single completequarterly.csvfile.
2. Status Report:
   • The planning engine should report the final delivered file list to upstream components (such as the user interface) and optionally report the completion process (e.g., "The system has automatically filled 2 missing data items").

Functional Scope

Basic Query Capabilities

• Economic Indicators: GDP, CPI, PPI, PMI, Unemployment Rate, Industrial Added Value, etc. (Supports specifying country/region and specific indicator names).
• Monetary & Finance: M1/M2 Money Supply, Total Social Financing, Government Bond Rates, Exchange Rates (Supports specifying currency pairs).
• Commodity Prices: Gold, Silver, Crude Oil, Copper, Specific Rare Earth Oxides, etc. (Mustspecify the specific variety).
• Time Frequency: Automatically recognize relative time periods (year, quarter, month, week, day) and match corresponding frequency data; if not specified, return the latest data.

Query Example Comparison Table

前提条件

1. 注册东方财富妙想账号

访问https://ai.eastmoney.com/mxClaw注册账号并获取API_KEY。

2. 配置令牌

# macOS 添加到 ~/.zshrc，Linux 添加到 ~/.bashrc
export EM_API_KEY="your_api_key_here"

然后根据系统执行对应的命令：

macOS：

source ~/.zshrc

Linux：

source ~/.bashrc

3. 安装依赖

pip3 install httpx --user

快速开始

1. 命令行调用

在项目根目录或配置的工作目录下执行：

python3 {baseDir}/scripts/get_data.py --query 中国GDP

参数说明：

### 2. 代码调用

```python
import asyncio
from pathlib import Path
from scripts.get_data import query_mx_macro_data

async def main():
    result = await query_mx_macro_data(
        query="中国近五年GDP",
        output_dir=Path("workspace/mx_macro_data"),
    )
    if "error" in result:
        print(result["error"])
    else:
        print(f"CSV: {r['csv_paths']}")
        print(f"描述: {r['description_path']}")
        print(f"行数: {r['row_counts']}")

asyncio.run(main())

输出示例：

CSV: /path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_yearly.csv
CSV: /path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_quarterly.csv
CSV: /path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_monthly.csv
描述:/path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_description.txt
行数: 年: 10行, 季: 20行, 月: 40行

输出文件说明

环境变量

常见问题

用户常见问题

Q: 提示"请设置 EM_API_KEY 环境变量"怎么办？

A: 按以下步骤配置 API 密钥：

1. 访问东方财富宏观查数工具注册并获取API_KEY。
2. 配置环境变量：

   # macOS/Linux
   export EM_API_KEY="your_api_key_here"
   
   # Windows PowerShell
   $env:EM_API_KEY="your_api_key_here"
   

Q: 如何指定输出目录？

A: 通过设置MX_MACRO_DATA_OUTPUT_DIR环境变量：

export MX_MACRO_DATA_OUTPUT_DIR="/path/to/output"
python3 scripts/get_data.py --query "查询内容"

开发者常见问题（规划引擎集成）

Q: 为什么需要上层规划引擎做复核？

A: 本 Skill 专注于单一查询能力，不负责数据完整性校验。完整性验证（如"中国各省"是否真的覆盖全部省份）属于业务逻辑范畴，更适合由具备上下文理解和决策能力的规划引擎来处理。

Q: 如何判断何时进行复核？

A: 当原始用户意图包含以下特征时，应自动触发复核流程：

• 集合性词汇：如"各省"、"各地区"、"华东地区"等
• 多指标查询：如"GDP 和 CPI"、"主要经济指标"等

Q: 如何处理不同频率的数据？A:必须对每种频率的 CSV 文件分别Conduct integrity audit and completion. Missing annual frequency data cannot be supplemented with monthly frequency data, and vice versa.