FHL Bible MCP Server

# 次經與使徒教父書卷名稱支援修正 ## 📅 日期 2025年1月4日 ## 🐛 問題描述 用戶在測試時發現以下查詢指令無法正常工作： 1. **「請給我瑪加伯上第 1 章的完整內容」** 2. **「查詢便西拉智訓第 3 章」** ### 根本原因 工具的書卷名稱映射 (`APOCRYPHA_BOOKS`) 中只包含了簡短的中文縮寫（如「加上」、「德」）和英文縮寫（如「1Mac」、「Sir」），但沒有包含完整的中文書卷名稱（如「瑪加伯上」、「便西拉智訓」）。 這導致當用戶使用完整書卷名稱查詢時，系統無法識別書卷，查詢失敗。 ## ✅ 修正內容 ### 1. 次經工具 (`src/fhl_bible_mcp/tools/apocrypha.py`) **新增支援的書卷名稱**： ```python # 新增中文全名 "多俾亞傳": {"id": 101, ...}, "友弟德傳": {"id": 102, ...}, "瑪加伯上": {"id": 103, ...}, # ✅ 修正 "瑪加伯下": {"id": 104, ...}, "智慧篇": {"id": 105, ...}, "德訓篇": {"id": 106, ...}, "便西拉智訓": {"id": 106, ...}, # ✅ 修正（別名） "巴錄書": {"id": 107, ...}, # ... 等 # 新增英文全名 "Tobit": {"id": 101, ...}, "Judith": {"id": 102, ...}, "1 Maccabees": {"id": 103, ...}, "2 Maccabees": {"id": 104, ...}, "Wisdom": {"id": 105, ...}, "Sirach": {"id": 106, ...}, "Baruch": {"id": 107, ...}, ``` **更新工具描述**： - 明確說明支援「中文縮寫」、「中文全名」、「英文縮寫」、「英文全名」 - 在描述中特別提到「德訓篇(便西拉智訓)」 **統計**： - **次經書卷數**: 9 本（Book ID 101-109） - **支援的名稱/縮寫**: 34 個 - **測試結果**: ✅ 全部通過 ### 2. 使徒教父工具 (`src/fhl_bible_mcp/tools/apostolic_fathers.py`) **新增支援的書卷名稱**： ```python # 新增中文全名 "革利免前書": {"id": 201, ...}, "革利免後書": {"id": 202, ...}, "伊格那丟書信": {"id": 203, ...}, "坡旅甲書信": {"id": 204, ...}, "黑馬牧人書": {"id": 205, ...}, "巴拿巴書": {"id": 206, ...}, "十二使徒遺訓": {"id": 207, ...}, "帕皮亞殘篇": {"id": 216, ...}, # 新增英文全名 "1 Clement": {"id": 201, ...}, "2 Clement": {"id": 202, ...}, "Ignatius": {"id": 203, ...}, "Polycarp": {"id": 204, ...}, "Shepherd of Hermas": {"id": 205, ...}, "Barnabas": {"id": 206, ...}, "Didache": {"id": 207, ...}, "Papias Fragments": {"id": 216, ...}, ``` **統計**： - **使徒教父書卷數**: 8 本（Book ID 201-207, 216） - **支援的名稱/縮寫**: 32 個 - **測試結果**: ✅ 全部通過 ### 3. 文檔更新 #### `README.md` - 更新工具說明，強調支援完整書卷名稱 - 範例：「查詢次經經文（舊約次經 101-115）支援完整書卷名如「瑪加伯上」、「便西拉智訓」」 #### `docs/4_manuals/API.md` - 修正次經書卷列表（之前的 ID 和名稱對應錯誤） - 新增「支援的縮寫/全名」欄位 - 明確標示「便西拉智訓」為「德訓篇」的別名 ## 🧪 測試驗證 建立測試腳本驗證所有修改： ```python # 次經測試案例 test_cases = [ "瑪加伯上", # ✅ Book 103 "便西拉智訓", # ✅ Book 106 "加上", # ✅ Book 103 "德", # ✅ Book 106 "1Mac", # ✅ Book 103 "Sir", # ✅ Book 106 "Sirach", # ✅ Book 106 "德訓篇", # ✅ Book 106 ] # 使徒教父測試案例 test_cases = [ "革利免前書", # ✅ Book 201 "十二使徒遺訓", # ✅ Book 207 "革", # ✅ Book 201 "訓", # ✅ Book 207 "1Clem", # ✅ Book 201 "Did", # ✅ Book 207 "Didache", # ✅ Book 207 "黑馬牧人書", # ✅ Book 205 ] ``` **測試結果**: ✅ 所有測試用例通過 ## 📊 修正前後對比 | 項目 | 修正前 | 修正後 | |------|--------|--------| | 次經書卷名稱數 | 18 個（僅縮寫） | 34 個（縮寫+全名） | | 使徒教父書卷名稱數 | 16 個（僅縮寫） | 32 個（縮寫+全名） | | 支援「瑪加伯上」 | ❌ | ✅ | | 支援「便西拉智訓」 | ❌ | ✅ | | 支援「十二使徒遺訓」 | ❌ | ✅ | ## 💡 使用範例 修正後，以下所有查詢方式都能正常工作： ### 次經查詢 ``` # 使用完整中文名稱（新增支援） 請給我瑪加伯上第 1 章的完整內容 查詢便西拉智訓第 3 章 # 使用中文縮寫（原本就支援） 查詢加上 1:1 查詢德 3:1-10 # 使用英文名稱（新增完整支援） Get me 1 Maccabees chapter 1 Query Sirach 3:1-10 ``` ### 使徒教父查詢 ``` # 使用完整中文名稱（新增支援） 查詢革利免前書第 1 章 請給我十二使徒遺訓的內容 # 使用中文縮寫（原本就支援） 查詢革 1:1 查詢訓 1:1 # 使用英文名稱（新增完整支援） Get me 1 Clement chapter 1 Query Didache 1:1 ``` ## 🎯 受益點 1. **更直觀**: 用戶可以使用自然語言中常見的完整書卷名稱 2. **更友善**: 不需要記憶特殊縮寫（如「加上」、「德」等） 3. **更全面**: 支援中文、英文、縮寫、全名等多種格式 4. **向後兼容**: 原有的縮寫方式仍然完全可用 ## 📝 後續建議 1. **單元測試**: 為新增的書卷名稱添加單元測試 2. **文檔完善**: 在 EXAMPLES.md 中添加使用完整書卷名稱的範例 3. **錯誤提示**: 當書卷名稱不存在時，提供可用名稱的建議列表 ## 🐛 第二個問題：書卷名稱顯示錯誤 ### 問題描述 用戶測試後發現，即使書卷名稱能被識別，回應中仍然顯示 API 的內部縮寫（如「馬一」）而不是友善的中文名稱（如「瑪加伯上」）。 **範例**： ``` **次經經文查詢結果** 版本: 1933年聖公會出版 (c1933) 書卷 ID: 未知 經文數量: 63 馬一 1:1 腓力的兒子亞力山大是馬其頓人... ``` ### 根本原因 1. **API 返回的 `chineses` 欄位**: FHL API 返回的是它自己的內部縮寫（如「馬一」），不是標準名稱 2. **`bid` 欄位位置**: `bid` 在每個 `record` 項目中，不在頂層結構 3. **直接使用 API 數據**: 工具直接使用 API 返回的 `chineses` 和 `bid` 值 ### 修正方案 #### 1. 查詢經文工具修正 **次經** (`handle_get_apocrypha_verse`): - ✅ 在查詢前從 `APOCRYPHA_BOOKS` 取得正確的書卷名稱 - ✅ 從 `record[0]` 中取得 `bid`（而不是頂層） - ✅ 使用我們的 `display_name` 取代 API 的 `chineses` - ✅ 在結果中顯示「書卷」欄位 **使徒教父** (`handle_get_apostolic_fathers_verse`): - ✅ 同樣修正邏輯 - ✅ 使用 `APOSTOLIC_FATHERS_BOOKS` 映射 **修正後的輸出範例**: ``` **次經經文查詢結果** 書卷: 瑪加伯上 版本: 1933年聖公會出版 (c1933) 書卷 ID: 103 經文數量: 63 瑪加伯上 1:1 腓力的兒子亞力山大是馬其頓人... ``` #### 2. 搜尋工具修正 **次經搜尋** (`handle_search_apocrypha`): - ✅ 建立 `bid_to_name` 反向映射字典 - ✅ 根據 `bid` 查找正確的中文書卷名稱 - ✅ 移除 `(Book {bid})` 顯示，直接顯示書卷名稱 **使徒教父搜尋** (`handle_search_apostolic_fathers`): - ✅ 同樣修正邏輯 **修正後的搜尋結果範例**: ``` **次經搜尋結果** 關鍵字: 信心 總結果數: 15 顯示: 10 筆 1. 瑪加伯上 2:50 你們要發出信心和熱誠... 2. 德訓篇 32:24 凡事依靠信心的人... ``` ## 📊 完整修正清單 ### 程式碼修正 - [x] `apocrypha.py` - `handle_get_apocrypha_verse()` 使用正確書卷名稱 - [x] `apocrypha.py` - `handle_search_apocrypha()` 建立 bid 映射 - [x] `apostolic_fathers.py` - `handle_get_apostolic_fathers_verse()` 使用正確書卷名稱 - [x] `apostolic_fathers.py` - `handle_search_apostolic_fathers()` 建立 bid 映射 ### 修正重點 | 項目 | 修正前 | 修正後 | |------|--------|--------| | 經文顯示 | `馬一 1:1` | `瑪加伯上 1:1` | | 搜尋結果 | `馬一 2:50 (Book 103)` | `瑪加伯上 2:50` | | 書卷 ID | `未知` | `103` | | 書卷欄位 | 無 | 顯示「書卷: 瑪加伯上」| ## ✅ 修正確認 **第一階段：支援完整書卷名稱** - [x] 次經工具支援完整書卷名稱（34 個名稱） - [x] 使徒教父工具支援完整書卷名稱（32 個名稱） - [x] README.md 更新 - [x] API.md 文檔更新 - [x] 測試驗證通過 **第二階段：修正顯示問題** - [x] 次經查詢使用正確書卷名稱顯示 - [x] 次經搜尋使用正確書卷名稱顯示 - [x] 使徒教父查詢使用正確書卷名稱顯示 - [x] 使徒教父搜尋使用正確書卷名稱顯示 - [x] 書卷 ID 正確從 record 中提取 - [x] 新增「書卷」欄位顯示 **整體狀態** - [x] 用戶問題完全解決 - [x] 所有查詢方式正常工作 - [x] 顯示結果友善易讀 --- **修正者**: GitHub Copilot **審核者**: 用戶測試確認 **狀態**: ✅ 完成並驗證