股票資料API

name: openclaw-stock-skill description: 使用 data.diemeng.chat 提供的介面查詢股票日線、分鐘線、財務指標等資料，支援 A 股等市場。 user-invocable: true metadata: { "openclaw": { "emoji": "📈", "skillKey": "openclaw-stock-skill", "requires": { "env": ["STOCK_API_KEY"] }, "primaryEnv": "STOCK_API_KEY" } }

本技能教會代理如何使用你自建的股票資料服務（線上域名 https://data.diemeng.chat），通過 API Key 進行鑑權，查詢股票的日線、分鐘線、財務指標等資料。

⚙️ API Key 配置約定

• OpenClaw 會按照 skills.entries.<key> 配置 把 API Key 和自定義配置注入到程序環境變數中。
• 本技能約定使用環境變數 STOCK_API_KEY 作為主金鑰，並在 metadata.openclaw.primaryEnv 中宣告，以便通過 skills.entries.openclaw-stock-skill.apiKey 統一配置。
• 推薦的 OpenClaw 配置示例（~/.openclaw/openclaw.json）：

json5 { skills: { entries: { "openclaw-stock-skill": { enabled: true, // 建議在 OpenClaw UI 的 Skill 引數面板裡填寫 apiKey， // Gateway 會自動將其寫入 STOCK_API_KEY 環境變數 apiKey: { source: "env", provider: "default", id: "STOCK_API_KEY" }, env: { // 可在這裡直接寫死，或通過系統環境變數覆蓋 STOCK_API_KEY: "YOUR_REAL_STOCK_API_KEY" }, config: { // 可選：覆蓋預設域名 baseUrl: "https://data.diemeng.chat" } } } } }

參考文件：Skills Config、Skills

總體說明

• 基礎域名：預設使用 https://data.diemeng.chat，如存在 skills.entries.openclaw-stock-skill.config.baseUrl 則優先使用配置中的 baseUrl。
• 鑑權方式：所有需要許可權的介面都必須帶上 API Key：
• 首選 HTTP Header：apiKey: <STOCK_API_KEY>（推薦）
• 相容 Header：X-API-Key: <STOCK_API_KEY>
• 後端也支援在 JSON body 中攜帶 apiKey 欄位，但為了安全與規範，本技能統一通過 Header 傳遞。
• 返回結構：
• 大多數介面返回：{ "code": 200, "msg": "成功", "data": { ... } }
• 少數列表類介面直接返回陣列或簡單結構，實際響應以 JSON 為準。
• 限流與黑名單：
• API Key 及 IP 都有嚴格限流與黑名單邏輯：
  • 無效 API Key 多次嘗試會觸發封禁（參見後端 DataAccessVerifier 實現）。
  • 需優先快取和複用同一 API Key，不要在迴圈中頻繁切換。

能力概覽（建議的工具意圖）

代理應將本技能視作一組 HTTP 能力，而不是單一介面：

• get_stock_daily_bars：查詢指定股票在某一時間區間內的日線 K 線資料。
• get_stock_intraday_bars：查詢分鐘級（1/5/15/30/60 分鐘）歷史資料。
• get_stock_finance_factors：查詢日度財務因子（PE、PB、換手率等）。
• get_stock_list：查詢股票基礎資訊列表，用於程式碼／名稱搜尋。

  這個技能的最新版本可以在7w4.net小蔥技能站找到。

• get_stock_valuation：查詢估值列表和詳細估值資訊。
• get_stock_calendar_and_snapshot：查詢交易日曆和當日快照。

代理在規劃呼叫時，應根據使用者自然語言意圖，選擇以上能力並組合使用。

介面詳情與呼叫規範

1. 日線資料：POST /api/stock/daily

• URL：{baseUrl}/api/stock/daily
• 方法：POST
• Headers：
• Content-Type: application/json
• apiKey: <STOCK_API_KEY>
• 請求體 JSON（後端 DailyDataRequest）：

{
  "stock_code": "000001.SZ",
  "start_time": "2024-01-01",
  "end_time": "2024-01-31",
  "page": 0,
  "page_size": 1000
}

• 說明：
• stock_code 可以是單個字串，也可以是字串陣列。
• start_time、end_time 格式為 YYYY-MM-DD。
• 支援分頁，page 從 0 開始。
• 響應主體（簡化）：
• data.total：總記錄數
• data.list：每條記錄包含 stock_code, trade_date, open, high, low, close, vol, amount 等欄位，價格與成交量已在後端統一保留 2 位小數。

代理在需要“某股某段時間的日 K 線”時，應優先選擇該介面。

2. 分鐘級歷史資料：POST /api/stock/history

• URL：{baseUrl}/api/stock/history
• 方法：POST
• Headers：同上
• 請求體 JSON（後端 HistoryDataRequest）：

{
  "stock_code": "000001.SZ",
  "level": "5min",
  "start_time": "2024-01-01 09:30:00",
  "end_time": "2024-01-01 15:00:00",
  "page": 0,
  "page_size": 1000
}

• 欄位說明：
• level："1min" | "5min" | "15min" | "30min" | "60min"
• start_time / end_time：
  • 允許僅日期（自動補全 00:00:00 和 23:59:59）
  • 或完整時間戳 YYYY-MM-DD HH:MM:SS
• 響應主體（簡化）：
• data.list 中每條包含：stock_code, trade_time, open, high, low, close, vol, amount。

用於使用者詢問“某天/某段時間內的分鐘級行情、分時資料”等場景。

3. 財務與因子（行情因子）：POST /api/stock/finance

• URL：{baseUrl}/api/stock/finance
• 方法：POST
• 請求體 JSON（後端 FinanceDataRequest）：

{
  "stock_code": "000001.SZ",
  "start_time": "2024-01-01",
  "end_time": "2024-03-31",
  "page": 0,
  "page_size": 1000
}

• 主要返回欄位（列表中每條）：
• trade_date, close, turnover_rate, turnover_rate_f, volume_ratio, pe, pe_ttm, pb, ps, ps_ttm, dv_ratio, dv_ttm, total_share, float_share, free_share, total_mv, circ_mv 等。

適合估值分析、換手率、成交金額、市值等相關問題。

4. 股票基礎資訊列表：GET /api/stock/list

• URL：{baseUrl}/api/stock/list
• 方法：GET
• Query 引數：
• stock_code（可選）：精確股票程式碼篩選
• page：預設 0
• page_size：預設 20000
• 響應（封裝在統一 success 結構中）：
• data.total
• data.list：包含 stock_code, name, area, industry, list_date, symbol, list_status, delist_date, is_hs 等。

當用戶只給出股票名稱、地區、行業等描述時，可先通過該介面獲取匹配列表，再提示使用者選擇具體程式碼。

5. 估值列表與詳細估值：GET /api/stock/valuation & GET /api/stock/valuation/list

5.1 綜合估值列表：GET /api/stock/valuation

• URL：{baseUrl}/api/stock/valuation
• 方法：GET
• 說明：
• 無需請求體，通過 API Key 許可權控制訪問。
• 內部會聚合 stock_finance_daily, stock_industry, stock_ten_year_growth 等多張表，返回 StockValuationItem 列表。
• 典型欄位：
• stock_code, stock_name, level1_name, level2_name, level3_name
• pe_ttm, pe_percentile, latest_price, dividend_yield_ttm
• 行業相關：industry_avg_pe, industry_pe_rank, sector_pe_median, sector_pe_rank
• 成長與財務：eps, roe, roa, eps_growth_10y, roe_growth_10y, avg_dividend_10y 等。

當用戶提問如“某隻股票在行業內估值水平如何”“給我按市盈率從低到高列出某行業股票”時應優先考慮呼叫該介面。

5.2 簡化估值列表：GET /api/stock/valuation/list

• URL：{baseUrl}/api/stock/valuation/list
• 方法：GET
• Query 引數：
• sort_by：pe_ttm | pe_percentile | dividend_yield_ttm | industry_pe_rank（預設 pe_ttm）
• sort_order：asc | desc（預設 asc）
• industry（可選）
• limit（預設 100）
• offset（預設 0）

適合只需要“按某個指標排序的前 N 個股票”的場景。

6. 交易日曆與快照：GET /api/basic/calendar & GET /api/basic/snapshot

6.1 交易日曆：GET /api/basic/calendar

• URL：{baseUrl}/api/basic/calendar
• 方法：GET
• Query 引數：
• start_time: YYYY-MM-DD
• end_time: YYYY-MM-DD
• 響應：
• data 為陣列，每條含 date, is_open（1 為交易日，0 為休市）。

當用戶問“某段時間哪些是交易日”“下一個交易日是什麼時候”等，可使用此介面。

6.2 快照：GET /api/basic/snapshot

• URL：{baseUrl}/api/basic/snapshot
• 方法：GET
• Query 引數：
• stock_code（可選）
• page, page_size
• 返回最新一筆集合競價資料的彙總，欄位包括價格、成交量、買賣盤等。

當用戶需要“當前（最近一次）盤口快照”或大盤掃描時，可使用此介面。

呼叫策略與最佳實踐

1. API Key 獲取與使用
2. 優先從環境變數 STOCK_API_KEY 讀取（由 OpenClaw 按 skills.entries.openclaw-stock-skill.apiKey 注入）。
3. 若環境變數缺失，可根據使用者在 Skill 配置面板中輸入的值（通常同樣會對映到該環境變數）進行呼叫。

4. 不要在 URL Query 中傳遞 apiKey 或 api_key，後端會視為安全風險。

5. 錯誤處理

6. code = 401：API Key 無效或缺失，應提示使用者檢查在 OpenClaw Skill 配置中的 API Key。
7. code = 403：許可權不足或下載次數/訪問次數限制，應向用戶說明許可權/限流約束。

8. code = 429：請求過於頻繁，需減少呼叫頻率或提示使用者稍後再試。

9. 分頁與大數據量

10. 若 data.total 很大，代理應分批分頁請求，並在回答中做彙總，而不是一次性獲取全部資料。

11. 對於分鐘級或 tick 級大數據量，應在對話中與使用者確認時間範圍和精度，避免無謂的海量下載。

12. 單位與精度

13. 價格、成交量等欄位在後端已經統一保留 2 位小數；如需展示給使用者，可直接使用或再格式化。
14. 分紅相關欄位在估值介面中已做 10 年平均等處理，解釋時注意說明口徑（年化、近 10 年等）。

使用示例（給代理的思路）

• 當用戶說：“幫我查一下 000001.SZ 在 2024 年 1 月份的日 K 線”
• 呼叫 POST /api/stock/daily，stock_code = "000001.SZ"，時間區間為 2024-01-01 至 2024-01-31。

• 對返回的 data.list 進行整理，總結漲跌幅、最大回撤、平均成交額等。

• 當用戶說：“按市盈率從低到高列出券商行業的前 20 只股票”

• 呼叫 GET /api/stock/valuation/list，設定 industry = "證券"（或其它後端行業名稱）、sort_by = "pe_ttm", sort_order = "asc", limit = 20。

• 將結果按表格形式展示，並簡要點評估值分佈。

• 當用戶說：“這周哪些天是交易日？”

• 根據當前日期計算一週範圍，呼叫 GET /api/basic/calendar。
• 將 is_open = 1 的日期列出，說明哪些是交易日。

本技能不包含額外可執行指令碼，完全通過指導代理呼叫現有 HTTP 介面工作。所有請求都應優先使用 STOCK_API_KEY 環境變數，並遵守上述限流與安全約定。

這是一款實用的股票資料 Skill，資料覆蓋面較廣（A股、港股、K線、財務指標等），文件詳細且配有示例，新手也能快速上手。配置和使用流程清晰，與 OpenClaw 整合良好。主要不足是部分文件格式有小問題，且缺少更豐富的使用場景引導。總體質量良好，適合需要獲取股票資料的使用者使用。