網路上的訓練資訊，多半是一篇篇獨立的文章：一個課表寫一篇，一個動作寫一篇，彼此的關係靠讀者自己腦補，來源也經常沒有交代。Barlore 改用「資料」而不是「文章」整理這些內容：每一筆都有固定欄位、彼此用 ID 關聯，並且能用腳本檢查是否自相矛盾。
目前的規模是 688 個動作、53 個課表、6 個訓練系統（健力、健美、舉重、徒手、強人、CrossFit），加上訓練原則與營養恢復的文件。程式碼與內容在 GitHub，也有網站可以瀏覽。
這篇寫的是資料怎麼設計、怎麼驗證，以及怎麼提供給 AI 使用。
1. 資料模型：動作是中立的 #
最核心的設計決定，是把三件事拆開：
| 層 | 回答的問題 | 位置 |
|---|---|---|
| 動作 | 這個動作本身是什麼 | exercises/ |
| 課表 | 這個課表怎麼使用它 | programs/ |
| 訓練系統 | 為什麼這個系統重視它 | systems/ |
背後的想法是：後蹲不是「健力的動作」，它是一個健力、健美、CrossFit 都會用、但用法各不相同的動作。如果把後蹲寫進健力的文章裡，其他系統就得重複寫一遍，兩邊也容易不一致。
所以動作條目只描述動作本身（肌群、技術要點、受傷風險、變化式），課表條目再用 exercises[] 欄位描述「這個課表怎麼用這個動作」，包括技術、強度與每週的處方。規格文件裡也註記了一次架構調整：原本在系統底下的 lenses 層已經移除，這類內容改放在課表條目內。
三種關聯要分清楚 #
動作之間的關聯有三種，在規格文件裡刻意分開定義：
variations：同一個動作換一種做法（前蹲與後蹲）progressions：通往這個動作的較簡單版本（箱上蹲到後蹲）alternatives：不同的動作，但訓練目的相似（腿推機對後蹲）
這些關聯欄位存的都是條目的 id，不是檔案路徑或顯示名稱。
2. 資料紀律：沒有來源就留空 #
這個專案最重視的原則，寫在 WORKFLOW.md 的開頭：先有來源，再寫內容。
沒有來源的欄位就維持空白。空白是誠實的，捏造的數字是會污染資料的。
具體的規則：
- 肌電圖、關節活動度這類量化欄位，只有在有來源時才填
- 每個來源都必須標註證據等級，從強到弱依序是：
meta_analysis>rct>expert_consensus>practitioner>anecdotal - 不同類型的條目有最低的可信度要求，例如肌電圖欄位至少要是
rct，營養類內容要是meta_analysis，課表則以作者自己的著作為依據
所以現在的資料也反映了這個原則：688 個動作裡，只有 93 筆是完整條目，595 筆是基本條目。完整條目中，有肌電圖資料的是 59 筆，關節活動度與力量曲線各 93 筆（以上是覆蓋率腳本在 2026-08-10 產出的數字）。基本條目只有規格裡的必填欄位，沒有量化資料。
3. 用腳本維持一致性 #
資料量到了幾百筆之後，靠人眼檢查不可行。scripts/build_index.py 同時做兩件事：
- 建立索引：產生
exercises.json、programs.json、肌群索引、「哪些課表用了哪些動作」的反向索引等，網站與 MCP Server 都使用這些索引 - 驗證規格：加上
--check時，依照SCHEMA.md檢查每一筆資料
驗證的規則包括：
- 必填欄位是否齊全
- 所有
*_ref與關聯欄位指到的id是否真的存在，指不到就失敗 - 肌群 ID 是否在
muscles.yaml的 63 個定義裡 - 關聯是否對稱（只是警告，不會失敗）
關聯只要求單向宣告，由驗證器檢查雙向是否一致，規格文件也明說不要手動寫兩邊。目前驗證結果是通過，另有 12 筆對稱性警告。
其他輔助腳本還有：覆蓋率報表（coverage.py，列出哪些動作還是基本條目）、stub_audit.py（找出「已經被課表引用、但資料還很薄」的動作），以及從課表資料產生決策矩陣的腳本。目前有 105 個動作被課表引用，這個關係可以用來判斷該先補哪些條目。
批次補資料的流程 #
肌電圖這類資料量大，文件記載的流程是用 Gemini Deep Research 做批次研究：先產生研究 prompt，把完整輸出存成 deep research/{id}.md 作為稽核紀錄，再從中抽出 YAML 補進對應的基本條目，最後跑一次 build_index.py 驗證。這些資料有一部分是 AI 輔助產生的，所以保留稽核紀錄、並且仍然要求每個欄位附上來源，是這個流程裡不能省的步驟。
4. 提供給人與 AI 使用 #
網站 #
用 VitePress 建置，部署在 GitHub Pages，由 GitHub Actions 負責：推送到 main 後，先執行 prebuild.sh 把各目錄的 Markdown 複製進 VitePress 的來源目錄，再建置並部署。腳本註解說明，用複製而不是符號連結，是為了讓 CI 不依賴本機的檔案系統結構。
MCP Server #
為了讓 AI 工具（Claude Code、Cursor 等）能直接查詢，專案裡有一個 MCP Server，提供 7 個工具：
| 工具 | 用途 |
|---|---|
search_exercises |
依名稱、動作模式、器材、肌群搜尋動作 |
get_exercise |
取得單一動作的完整資料 |
search_by_muscle |
找出訓練某肌群的動作 |
list_programs |
依系統或程度瀏覽課表 |
get_program |
取得單一課表的完整資料 |
get_training_concept |
查訓練原則（週期化、SRA 曲線、RPE 等） |
list_muscles |
所有肌群 ID 與對應的動作數量 |
它提供兩種使用方式：本機以 stdio 執行，或使用已部署在 Cloudflare Workers 的版本（streamable HTTP），後者只要在 AI 工具的設定裡填一個網址，不用自己架設。設定方式寫在倉庫的 README。
給 LLM 的入口 #
倉庫根目錄放了 llms.txt，用簡短的文字說明這個知識庫的內容與使用方式，作為給 AI 讀取的入口。
另外有一個「訓練計畫產生器」prompt（prompts/plan_generator.md）：使用者填寫自己的目標、經驗、器材與時間，整份貼進任何一個 AI 聊天機器人，就能得到依照 Barlore 內課表產生的個人化計畫。這份 prompt 有幾個設計：
- 規則明確要求只能使用 Barlore 裡既有的課表與動作，不能自行發明，並且要引用條目的 ID
- 如果 AI 沒有讀檔能力，只能依據內嵌的決策矩陣，且輸出必須以一行聲明開頭，說明這份計畫沒有讀取原始檔案，細節可能與知識庫不同
- 新手對不確定的欄位可以填
not_sure，讓 AI 協助判斷，而不是要求使用者先懂專有名詞
5. 限制 #
- 覆蓋不均。 如上所述，大部分動作還是基本條目，量化資料只集中在部分動作。
- AI 輔助的部分仍需人工審查。 批次補進來的資料有稽核紀錄，但不代表每一筆都經過同儕審查。
- 這是知識整理，不是醫療建議。 它不能取代教練或醫療專業人員，尤其是有傷病的人。
- 對稱性警告還沒清完。 12 筆關聯警告目前保留。
- README 的數字沒有自動同步，倉庫首頁寫的筆數落後於實際內容（以驗證腳本的輸出為準）。
小結 #
同一份結構化資料，現在同時支撐了網站、MCP 工具和 AI prompt，而不需要為每一種用途各寫一份。這也是把內容當資料、而不是當文章來維護的好處：欄位與關聯固定之後，檢查可以交給腳本，使用方式也可以隨需求增加。