調研目標
為 OpenClaw 的 /sdd（港股盡調）、/finance（財務分析）、/reip（投資建議書）等斜槓指令，接入結構化金融數據 API，取代目前手動收集數據的流程。
備選 API
港股數據
| API | 數據類型 | 成本 | 備註 |
|---|---|---|---|
| HKEX 官方 | 公告、年報 PDF | 免費 | 需要 PyMuPDF 提取 |
| AASTOCKS | 即時報價、財報 | 免費 (非官方) | 無官方 API |
| Bloomberg API | 全市場數據 | 極貴 | 機構用 |
| Morningstar | 結構化財報 | 付費 | 已有在用 |
美股數據
| API | 數據類型 | 成本 |
|---|---|---|
| Yahoo Finance | 報價、財報、歷史 | 免費 (非官方) |
| Alpha Vantage | 報價、技術指標 | 免費 25次/天 |
| Polygon.io | 全市場即時數據 | 付費 |
| Financial Modeling Prep | 財報、估值 | 免費層可用 |
宏觀/行業
| API | 數據類型 | 成本 |
|---|---|---|
| FRED (美聯儲) | 利率、GDP、就業 | 免費 |
| World Bank | 全球經濟指標 | 免費 |
| Wind (萬得) | 中國宏觀/行業 | 付費 |
整合策略
OpenClaw (/sdd 0515.HK)
→ Step 1: Yahoo Finance / Morningstar → 財務數據
→ Step 2: HKEX 官方 → 股權結構 PDF
→ Step 3: AASTOCKS scrape → 最新公告
→ Step 4: FRED / World Bank → 宏觀背景
→ 匯總 → 生成調研報告
優先級
| 優先 | API | 用途 |
|---|---|---|
| 🔴 立即 | Yahoo Finance | 美股 + 港股基礎數據 |
| 🔴 立即 | Alpha Vantage | 備援 + 技術指標 |
| 🟡 下週 | FRED | 宏觀經濟背景 |
| 🟡 下週 | Financial Modeling Prep | 結構化財報 |
接入層的技術要點與取捨
把多個來源接進同一個 Agent，難點通常不在呼叫 API，而在於讓回來的資料可比較、可追溯、可重試。以下幾個環節建議先想清楚再動工。
授權與合規：官方 API 有明確條款與配額，非官方來源（例如網頁抓取）則有欄位隨時變動、被限流或封鎖的風險。取捨上，能取得授權的就優先用官方接口，抓取只作為補充，並且要設定合理的請求頻率、自訂 User-Agent、失敗退避重試，避免對來源造成壓力。
快取策略：不同資料的更新頻率差異極大。報價屬於秒級，快取時間要短；財報與年報是季度或年度更新，快取時間可以長；宏觀指標多是月度或季度發布。分層設定 TTL（存活時間），既能省配額，也能讓重複查詢保持穩定。關鍵是快取要有來源與時間戳，否則報告裡出現舊數字卻無從察覺。
欄位正規化：不同來源對同一科目的命名與口徑不一致，例如「營業收入」與「Revenue」、合併與母公司口徑、千元與百萬元單位。建議在接入層與業務層之間放一層映射，把外部欄位統一成內部標準名稱，業務邏輯只依賴內部標準，來源更換時不必改動下游。
時間、幣種與交易日曆：跨市場資料涉及時區、交易日曆與貨幣換算。港股與美股休市日不同，報價時間點要標明時區；不同市場的幣種要先換算成報告基準貨幣再比較。歷史價格還要考慮除權除息與拆股的復權處理，否則長期走勢會失真。
PDF 提取：年報與公告是 PDF，抽取難點在表格跨頁、欄位換行與掃描件。可先用 PyMuPDF 取文字層，遇到掃描件再考慮 OCR；抽出的數字要保留頁碼與表格標題，日後核對才有依據。
資料品質與一致性檢查
多來源匯總最大的風險是「看起來對，其實口徑不同」。以下檢查建議做成自動化步驟，而不是靠人工抽查。
| 檢查項 | 做法 | 目的 |
|---|---|---|
| 交叉驗證 | 同一指標取兩個來源比對 | 發現單一來源錯誤 |
| 單位一致 | 明確標示千元或百萬元 | 避免數量級錯誤 |
| 期間對齊 | 確認財年是日曆年或自訂財年 | 避免期間錯配 |
| 復權處理 | 歷史價格做除權息調整 | 保證走勢可比 |
| 缺值標記 | 缺值明確標示而非填零 | 避免把缺失當事實 |
| 來源留痕 | 每筆數據附來源與抓取時間 | 支援事後追溯 |
交叉驗證的容差要設定合理：不同來源的統計口徑可能天生有差異，硬性要求完全相等會產生大量誤報。建議設定一個容差範圍，超出範圍才告警，並人工確認差異原因。
整合進 Agent 框架的做法
金融數據要能被 Agent 穩定使用，取決於工具介面設計，而非模型本身。
單一職責的工具：每個工具只做一件事，例如「取報價」、「取財報」、「取宏觀序列」分開，不要做一個萬能查詢工具。職責清晰的好處是模型容易選擇正確工具，除錯時也能快速定位。
明確的輸入輸出結構：工具參數要限制類型與取值範圍（例如市場代碼格式、日期格式、期間長度），回傳要固定欄位並包含來源與時間戳。回傳格式穩定，下游的報告生成才不會因為欄位缺失而崩潰。
錯誤可回復：限流、逾時、欄位缺失都要回傳可行的替代建議，例如提示「改用備援來源」或「縮短查詢期間」，讓 Agent 有機會自行調整，而不是直接中斷整條流程。
常見錯誤
- 把多個來源硬編碼在業務邏輯裡，日後換源要改多處。
- 沒有快取，重複查詢打爆配額。
- 把抓取到的數字直接寫進報告，沒有交叉驗證與來源留痕。
- 忽略單位與口徑差異，導致數量級或期間錯誤。
- 工具回傳格式不穩定，Agent 被迫猜測欄位含義。
- 沒有處理休市與停牌情形，報價查詢回傳空值卻當成零。
- 把密鑰寫進配置文件或日誌，造成洩露風險。
驗證方式與實作檢查清單
驗證方式
先建立一組已知答案的測試案例，例如指定公司的某年度營收與指定日期的收盤價，用這些案例驗證每個來源的準確度與欄位正確性。再測異常路徑：斷網、限流、逾時、欄位缺失、休市日，確認系統會回報可理解的錯誤而不是靜默失敗。快取要驗證命中與過期兩種情形，確保不會回傳過期數據。最後做端到端測試，用真實斜槓指令走一遍流程，確認從數據到報告的鏈路完整。
實作檢查清單
- 每個來源都確認了授權條款與配額限制。
- 已實作分層快取，並在快取中保留來源與時間戳。
- 已建立欄位映射層，業務邏輯只依賴內部標準名稱。
- 已處理時區、交易日曆與貨幣換算。
- 已對歷史價格做復權處理。
- 已設定交叉驗證與容差告警。
- 每筆數據都可追溯到來源與抓取時間。
- 已測試限流、逾時、缺值與休市等異常路徑。
- 密鑰以環境變數或受保護的儲存方式管理，未寫入配置文件或日誌。
- 已用真實指令完成一次端到端驗證。