宏觀經濟資料查詢 (mx_macro_data)

通過文本輸入查詢宏觀經濟資料，介面返回 JSON 後會自動轉換為 CSV 並生成對應的內容描述 txt 檔案。

金鑰來源與安全說明

• 本技能僅使用一個環境變數：EM_API_KEY。
• EM_API_KEY 由東方財富妙想服務（https://ai.eastmoney.com/mxClaw）簽發，用於其介面鑑權。

  小蔥技能7w4.net持續更新中。

• 在提供金鑰前，請先確認金鑰來源、可用範圍、有效期及是否支援重置/撤銷。
• 禁止在程式碼、提示詞、日誌或輸出檔案中硬編碼/明文暴露金鑰。

⚠️ 核心輸入約束 (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 後，必須執行以下工作流，以確保最終結果的完整性：

階段 A: 任務解析與預期規劃 (Task Parsing & Expectation Planning)

1. 解析原始使用者意圖：從使用者查詢中提取核心要素。
2. 構建預期全集 (Expected Universe)：
   • 地域：通過規劃引擎的內建知識庫、搜尋引擎或 LLM 推理能力，將模糊地域表述解析為具體行政單元。例如："中國各省" → 34 個省級行政區；"華東地區" → 上海、江蘇、浙江、安徽、福建、江西、山東共 7 個省市。
   • 指標：將複合指標拆解為獨立指標。例如："GDP, CPI" → ["GDP", "CPI"]。
   • 頻率：根據查詢語境推斷預期頻率，可能生成多個頻率的資料檔案（yearly、quarterly、monthly等）。

階段 B: 檔案讀取與差異檢測 (File Reading & Gap Detection)

1. 獲取輸出檔案列表：獲取 mx_macro_data 生成的所有 CSV 檔案路徑。
2. 讀取並分析每個檔案：
   • 使用規劃引擎內建的程式碼執行能力（如 Python Sandbox）讀取 CSV。
   • 提取每個檔案中實際覆蓋的 (地區, 指標) 組合及其數量。
3. 執行差異計算：
   • 對每一種頻率的檔案，分別計算 Missing_Pairs_<Frequency> = Expected_Universe - Actual_From_CSV_File。
   • 識別出具體缺失的項（如：年頻資料中缺失“西藏-GDP”）。

階段 C: 決策與迭代呼叫 (Decision & Iterative Invocation)

⚠️ 強制要求：上層規劃引擎必須執行以下補全流程，不得在存在缺失資料時直接交付結果。

1. 判斷是否需要補全：

   • 如果所有頻率的 Missing_Pairs 集合均為空：結束流程，交付現有檔案。
   • 如果存在非空的 Missing_Pairs 集合：必須進入補全流程，不可跳過。

2. 構建補全查詢：

   • 根據 Missing_Pairs_<Frequency> 中的缺失項，結合原始查詢的時間維度，構造新的自然語言查詢。
   • 示例：

     Missing_Pairs_季 = [("西藏", "GDP"), ("寧夏", "GDP")]
     ↓
     補全查詢 = "查詢西藏自治區、寧夏回族自治區的 GDP 季度資料，時間範圍同前次查詢"

3. 再次呼叫 mx_macro_data：

   • 使用新構造的補全查詢，再次呼叫本 Skill 獲取缺失資料。

4. 迭代迴圈：

   • 重複執行 階段 B（差異檢測）→ 階段 C（決策補全），直至滿足以下任一條件：
     • ✅ 所有頻率下的缺失項均已補全
     • ⚠️ 達到最大重試次數5次，此時應向用戶報告未能補全的資料項

階段 D: 最終交付 (Final Delivery)

1. 資料合併（可選）：
   • 如果需要，可將同一頻率下多次查詢的結果（如多個 quarterly.csv 檔案）合併為一個完整的 quarterly.csv。
2. 狀態報告：

   • 規劃引擎應向上遊（如使用者介面）報告最終交付的檔案列表，並可選地報告補全過程（如“系統已自動補全 2 個缺失資料項”）。

功能範圍

基礎查詢能力

• 經濟指標：GDP、CPI、PPI、PMI、失業率、工業增加值等（支援指定國家/地區及具體指標名）。
• 貨幣金融：M1/M2 貨幣供應量、社融規模、國債利率、匯率（支援指定幣種對）。
• 商品價格：黃金、白銀、原油、銅、特定稀土氧化物等（必須指定具體品種）。
• 時間頻率：自動識別相對時間（年、季、月、周、日）並匹配對應頻率資料；若未指定，返回最新資料。

查詢示例對照表

前提條件

1. 註冊東方財富妙想賬號

訪問 https://ai.eastmoney.com/mxClaw 註冊賬號並獲取API_KEY。

2. 配置 Token

# 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 檔案分別執行完整性審計和補全。年頻資料的缺失不能用月頻資料補全，反之亦然。

這個 Skill 整體質量良好，文件說明詳細易懂，功能實現完整。通過自然語言查詢宏觀經濟資料，使用場景覆蓋廣泛，返回結果自動整理為 CSV 格式便於後續分析。輸入約束定義清晰，能有效引導使用者提出有效查詢。主要優點是輸出結構規範、支援多種資料頻率；不足之處是依賴外部 API 穩定性，且無本地快取機制，長期使用需關注 API 服務狀態。總體而言，這是一個專業度高、可用性強的資料查詢工具。