knowledge: 同步 FinMind-Doc 8 月新增/更新的 dataset，並修正三個 snapshot endpoint - #22
Merged
Conversation
上次 catalog 同步（#19）停在 2026-08-01，之後 FinMind-Doc 又有異動；同時對照 FinMind 主 repo 的 /finmind skill，發現 catalog 有兩處會讓 AI 直接答錯的內容。 knowledge/datasets.md： 新增 dataset（FinMind-Doc 2026-08-09） - TaiwanStockMarginMaintenance（個股融資維持率，Sponsor）：Required `start_date`、 Optional `data_id`/`end_date`（不帶 data_id 可取該日全市場）；欄位 date / stock_id / margin_balance / margin_cost / margin_ratio / margin_maintenance。 一併記下 Doc 的兩個重點：資料區間 2001-01-05 起（上櫃 2007-01-04 起），以及 「本資料集為估算指標、與其他服務數字不會一致」——這點客戶最容易誤解。 既有 dataset 的新增能力 - TaiwanStockKBar：補上加權指數分 K（`data_id="TAIEX"`，2005-01-03 ~ now、每日 271 筆 09:00~13:30、volume 固定 0），並補個股區間 2019-01-01 起與 volume 單位 依市場別而異（上市櫃「張」、興櫃「股」）。 - taiwan_options_snapshot：補契約系列對照 TXO 月選 / TX1~TX5（週三到期）/ TXU TXV TXX TXY TXZ（週五到期，2026-08-09 增開），以及「無成交時回傳最後成交 價量、要看 date 欄位」的判讀方式。 修正：三個 snapshot 的 endpoint 寫錯 - taiwan_stock_tick_snapshot / taiwan_futures_snapshot / taiwan_options_snapshot 原本都標 `/api/v4/data` + `dataset=...`，但這三個是 dedicated endpoint，並不在 `/api/v4/data` 的 dataset enum 內，照 catalog 打會被 422 拒。改為 `/api/v4/<name>`（dedicated），對齊 TaiwanStockTradingDailyReportSecIdAgg 既有 寫法，並補 data_id 可多帶 / 留空取全部。 修正：storage_objects 整日下載的「無歷史回補」是錯的 - KBar / FuturesTick / OptionTick 三處刪掉「逐交易日提供、無歷史回補」，改成 「歷史整日檔案皆可下載」並標最早日（PriceTick 2018-12-07、KBar 2019-01-02、 FuturesTick 與 OptionTick 2011-01-03）。此為 FinMind #444 已修正的內容， catalog 尚未跟上；這句話曾誤導客戶以為整日批次下載拿不到歷史。 其他 - 檔頭 dataset 總數 100 → 106。 驗證 - 對 live API 實打確認：TaiwanStockMarginMaintenance 2330 回傳欄位與文件一致； TaiwanStockKBar data_id=TAIEX 於 2026-08-19 與 2005-01-03 各回 271 筆、volume=0； taiwan_options_snapshot?data_id=TXO 回 2050 筆，而 /api/v4/data?dataset= taiwan_options_snapshot 回 422 enum 錯誤（佐證 endpoint 修正）。 - scripts/check_doc_sync.py 對 FinMind-Doc origin/master：OK, in sync。 - pytest 32 passed、smoke.py OK、build_instructions 7987/8000 chars。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
上次 catalog 同步（#19）停在 2026-08-01，之後 FinMind-Doc 又有異動。這次順帶把 FinMind 主 repo 的
/finmindskill 一起對照，發現 catalog 有兩處會讓 AI 直接回答錯誤的內容。只改
knowledge/datasets.md（list_datasets工具與 Custom GPT knowledge bundle 的 SSOT）。新增 dataset
TaiwanStockMarginMaintenance（個股融資維持率）Required
start_date、Optionaldata_id/end_date（不帶data_id可取該日全市場）；欄位date/stock_id/margin_balance/margin_cost/margin_ratio/margin_maintenance。一併記下 Doc 的兩個重點：資料區間 2001-01-05 起（上櫃 2007-01-04 起），以及「本資料集為估算指標、與其他服務數字不會一致」——這點客戶最容易誤解，寫進 catalog 讓 AI 主動說明。
既有 dataset 的新增能力
TaiwanStockKBar：補上加權指數分 K（data_id="TAIEX"，2005-01-03 ~ now、每個交易日 271 筆涵蓋 09:00~13:30、volume固定 0）。順帶補個股區間 2019-01-01 起，以及volume單位依市場別而異（上市櫃「張」、興櫃「股」）。taiwan_options_snapshot：補契約系列對照 ——TXO月選 /TX1~TX5（週三到期）/TXUTXVTXXTXYTXZ（週五到期，2026-08-09 增開），以及「無成交時回傳最後成交價量、要以date欄位判讀」。🐛 修正：三個 snapshot 的 endpoint 寫錯
taiwan_stock_tick_snapshot/taiwan_futures_snapshot/taiwan_options_snapshot原本都標/api/v4/data+dataset=...，但這三個是 dedicated endpoint，並不在/api/v4/data的 dataset enum 內 —— 照 catalog 打會被 422 拒。改為/api/v4/<name>（dedicated），對齊TaiwanStockTradingDailyReportSecIdAgg既有寫法，並補data_id可多帶 / 留空取全部。🐛 修正：storage_objects「無歷史回補」是錯的
KBar / FuturesTick / OptionTick 三處刪掉「逐交易日提供、無歷史回補」，改成「歷史整日檔案皆可下載」並標最早日（PriceTick 2018-12-07、KBar 2019-01-02、FuturesTick 與 OptionTick 2011-01-03）。此為 FinMind #444 已修正的內容，catalog 尚未跟上；這句話曾誤導客戶以為整日批次下載拿不到歷史。
檔頭 dataset 總數 100 → 106。
驗證
對 live API 實打確認：
TaiwanStockMarginMaintenancedata_id=2330回傳欄位與文件一致TaiwanStockKBardata_id=TAIEX於 2026-08-19 與 2005-01-03 各回 271 筆、volume=0taiwan_options_snapshot?data_id=TXO回 2050 筆；而/api/v4/data?dataset=taiwan_options_snapshot回 422 enum 錯誤（佐證 endpoint 修正）本機：
scripts/check_doc_sync.py --doc <FinMind-Doc origin/master>→ OK, in syncpytest32 passed、smoke.pyOK、build_instructions.py7987/8000 chars刻意不納入
live
/api/v4/dataenum 有兩個 FinMind-Doc 完全沒有文件的 dataset：ExchangeRate、TaiwanFutOptInstitutionalInvestors。兩者皆已棄用（已確認），只是還留在 API enum 裡沒清掉，因此不進 catalog。日後再做三方清單比對（live enum / SDKclass Dataset/ catalog）時，這兩個出現在差異裡屬預期，不必再追。Merge 後若要讓使用者端的
list_datasets拿到新 catalog，需另下新 tag 觸發 PyPI 發版；Custom GPT 則要重跑build_instructions.py重貼 instructions / knowledge bundle。🤖 Generated with Claude Code