feat: graceful degradation when FoJin API is unavailable (P0)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

tools/fojin_bridge.py

@@ -7,12 +7,18 @@ Two modes:
 """
 
 import json
+import logging
 import os
 from typing import Optional
 
 import requests
 
 
+class FojinUnavailableError(Exception):
+    """Raised when FoJin API is unreachable. Callers should handle gracefully."""
+    pass
+
+
 class FojinBridge:
     """Bridge to FoJin Buddhist text platform."""
 
@@ -108,11 +114,21 @@ class FojinBridge:
     # ── Helpers ──────────────────────────────────────────────
 
     def _get(self, path: str, params: Optional[dict] = None) -> dict:
-        """Make GET request to FoJin API."""
+        """Make GET request to FoJin API.
+
+        Raises:
+            FojinUnavailableError: When FoJin is unreachable (connection/timeout)
+            requests.HTTPError: On 4xx/5xx responses
+        """
         url = f"{self.base_url}{path}"
-        resp = self.session.get(url, params=params, timeout=30)
-        resp.raise_for_status()
-        return resp.json()
+        try:
+            resp = self.session.get(url, params=params, timeout=30)
+            resp.raise_for_status()
+            return resp.json()
+        except requests.ConnectionError as e:
+            raise FojinUnavailableError(f"FoJin API unreachable: {e}") from e
+        except requests.Timeout as e:
+            raise FojinUnavailableError(f"FoJin API timeout: {e}") from e
 
     def test_connection(self) -> bool:
         """Test if FoJin API is reachable."""

tools/rag_query.py

@@ -16,7 +16,7 @@ import os
 # Ensure tools/ is on the path so we can import fojin_bridge
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-from fojin_bridge import create_bridge
+from fojin_bridge import create_bridge, FojinUnavailableError
 
 
 def format_search_results(data: dict) -> str:
@@ -215,6 +215,14 @@ def main():
 
     try:
         args.func(args)
+    except FojinUnavailableError:
+        print("[FoJin API 当前不可用]")
+        print("无法检索真实经文。法师将仅基于预置 teaching.md 回答。")
+        print("建议：")
+        print("- 稍后重试")
+        print("- 检查网络连接")
+        print("- 或在 fojin.app 直接查阅原典")
+        sys.exit(0)
     except ConnectionError as e:
         print(f"[错误] 无法连接 FoJin API: {e}", file=sys.stderr)
         sys.exit(1)