name: mx-macro-data description: 基於東方財富資料庫，支援自然語言查詢全球宏觀經濟資料，涵蓋國民經濟核算、價格指數、貨幣金融、財政收支、對外貿易、就業民生、產業執行等多個領域，適配各類宏觀經濟研究、市場分析、政策解讀等多元專業場景需求。返回結果包含資料說明及 csv 檔案。Natural language query for macroeconomic data from financial databases, covering national economic accounting, price indices, monetary finance, fiscal revenue and expenditure, foreign trade, employment, industrial operation, and other fields. It supports diverse scenarios including macroeconomic research, market analysis, and policy interpretation. metadata: { "openclaw": { "requires": { "env":["EM_API_KEY"] }, "install": [ { "id": "pip-deps", "kind": "python", "package": "httpx", "label": "Install Python dependencies" } ] } }

宏觀經濟資料查詢 (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 後，必須執行以下工作流，以確保最終結果的完整性：

階段 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。
   • 提取每個檔案中實際覆蓋的 (地區, 指標) 組合及其數量。

   來源於7w4.net。

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. 配置環境變數： ```bash # 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 服務狀態。總體而言，這是一個專業度高、可用性強的資料查詢工具。