diff --git a/SKILL.md b/SKILL.md
index d868b2d..b6a0831 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -295,6 +295,8 @@ OpenClaw 用户：
 | 版本管理 | `${CLAUDE_SKILL_DIR}/tools/version_manager.py` |
 | 来源验证 | `${CLAUDE_SKILL_DIR}/tools/verify_sources.py` |
 
+**直接访问 FoJin API**：当 `rag_query.py` 不够用时（如需要 KG 深度遍历、跨词典分组对比），参考 `${CLAUDE_SKILL_DIR}/references/fojin-api.md`，直接用 Python 调用 FoJin REST API。
+
 ## 敏感性边界
 
 **不做：**
diff --git a/references/README.md b/references/README.md
new file mode 100644
index 0000000..c38c135
--- /dev/null
+++ b/references/README.md
@@ -0,0 +1,5 @@
+# References
+
+按需加载的深度参考文档。SKILL.md 会在相关场景引用这些文件。
+
+- `fojin-api.md` — FoJin REST API 完整参考，供 LLM 即兴写查询
diff --git a/references/fojin-api.md b/references/fojin-api.md
new file mode 100644
index 0000000..49a6f92
--- /dev/null
+++ b/references/fojin-api.md
@@ -0,0 +1,223 @@
+# FoJin API 完整参考
+
+本文档供 LLM 在 `rag_query.py` 不够用时即兴写 Python 查询使用。
+
+基础 URL：`https://fojin.app`
+
+## 认证
+
+目前公开只读 API 无需认证。
+
+## 搜索 API
+
+### GET /api/search
+
+关键词搜索佛教文本。
+
+**参数：**
+- `q` (必填) - 搜索关键词，最长 200 字符
+- `page` (默认 1) - 页码
+- `size` (默认 20，最大 100) - 每页结果数
+- `dynasty` - 朝代筛选（如"唐"、"宋"）
+- `category` - 分类筛选
+- `lang` - 语言筛选（lzh=文言汉语, pi=巴利, sa=梵文, bo=藏文, en=英文）
+- `sources` - 数据源筛选，逗号分隔（cbeta, suttacentral, gretil）
+- `sort` - 排序（relevance, title, dynasty）
+
+**响应：**
+```json
+{
+  "total": 42,
+  "page": 1,
+  "size": 20,
+  "results": [
+    {
+      "id": 1234,
+      "cbeta_id": "T01n0001",
+      "title_zh": "长阿含经",
+      "translator": "佛陀什",
+      "dynasty": "后秦",
+      "category": "阿含部",
+      "source_code": "cbeta",
+      "score": 0.95
+    }
+  ]
+}
+```
+
+### GET /api/search/semantic
+
+向量语义搜索（pgvector）。比关键词搜索更能理解语义相似性。
+
+**参数：**
+- `q` (必填) - 自然语言问题
+- `size` (默认 10) - 返回结果数
+
+### GET /api/search/content
+
+全文内容搜索（带高亮）。
+
+### GET /api/search/cross-language
+
+跨语言搜索（中/英/梵/巴/藏）。
+
+## 文本 API
+
+### GET /api/texts/{text_id}
+
+获取文本元数据。
+
+### GET /api/texts/{text_id}/juans/{juan_num}
+
+获取某卷的完整内容。
+
+**参数：**
+- `lang` - 语言代码
+
+**响应：**
+```json
+{
+  "text_id": 1234,
+  "cbeta_id": "T01n0001",
+  "title_zh": "长阿含经",
+  "juan_num": 1,
+  "content": "...",
+  "prev_juan": null,
+  "next_juan": 2
+}
+```
+
+### GET /api/texts/{text_id}/juans/{juan_num}/similar
+
+通过 pgvector 相似度查找类似段落。**研究级功能**：跨经典找"同义段落"。
+
+### GET /api/texts/lookup-cbeta
+
+CBETA ID 批量映射到内部 text_id。
+
+**参数：**
+- `ids` - 逗号分隔的 CBETA ID 列表
+
+### GET /api/texts/{text_id}/juans
+
+列出某部文本的所有卷。
+
+## 知识图谱 API
+
+### GET /api/kg/entities
+
+搜索知识图谱实体。
+
+**参数：**
+- `q` (必填) - 搜索词
+- `entity_type` - 类型筛选（person, text, school, concept, place, event）
+- `limit` (默认 20) - 最大结果数
+
+### GET /api/kg/entities/{entity_id}
+
+获取实体详情（含关系列表）。
+
+### GET /api/kg/entities/{entity_id}/graph
+
+获取实体的关系图谱。**这是利用 23K 师承关系的核心 API。**
+
+**参数：**
+- `depth` (默认 2，1-4) - 遍历深度
+- `max_nodes` (默认 150) - 节点上限
+- `predicates` - 关系类型筛选（逗号分隔）
+
+**响应：**
+```json
+{
+  "nodes": [{"id": 456, "name": "玄奘", "entity_type": "person"}],
+  "links": [{"source": 456, "target": 1234, "predicate": "translated"}]
+}
+```
+
+## 词典 API
+
+### GET /api/dictionary/search
+
+搜索佛学词典。
+
+**参数：**
+- `q` (必填) - 搜索词
+- `lang` - 语言筛选
+- `source` - 词典来源筛选
+
+### GET /api/dictionary/search/grouped
+
+**按词典来源分组返回结果**。利用 FoJin 的 32 部词典，可以看同一术语在不同传承的释义差异。
+
+**响应：**
+```json
+{
+  "query": "般若",
+  "groups": [
+    {"source_code": "foguang", "source_name": "佛光大辞典", "entries": [...]},
+    {"source_code": "dingfubao", "source_name": "丁福保佛学大辞典", "entries": [...]}
+  ]
+}
+```
+
+## 常见用法示例
+
+### 场景 1：查找某法师的所有相关经典
+
+```python
+import requests
+
+# 先从 KG 找到实体
+r = requests.get("https://fojin.app/api/kg/entities", 
+                 params={"q": "玄奘", "entity_type": "person"})
+entity_id = r.json()["results"][0]["id"]
+
+# 遍历师承/著作关系
+r = requests.get(f"https://fojin.app/api/kg/entities/{entity_id}/graph",
+                 params={"depth": 2, "predicates": "translated,authored"})
+```
+
+### 场景 2：跨词典对比术语释义
+
+```python
+r = requests.get("https://fojin.app/api/dictionary/search/grouped",
+                 params={"q": "空性"})
+for group in r.json()["groups"]:
+    print(f"【{group['source_name']}】")
+    for entry in group["entries"]:
+        print(f"  {entry['definition'][:100]}")
+```
+
+### 场景 3：找与某段经文最相似的其他段落
+
+```python
+# 获取某部经的某卷
+r = requests.get("https://fojin.app/api/texts/43/juans/1/similar")
+for similar in r.json()["similar"]:
+    print(f"{similar['title']} 卷{similar['juan_num']}: {similar['score']:.3f}")
+```
+
+## 错误处理
+
+- **200** - 成功
+- **404** - 资源不存在（text_id 无效等）
+- **429** - 速率限制（默认 200 req/min）
+- **500** - 服务器错误
+
+连接失败时应优雅降级（见 `tools/rag_query.py` 的 fallback 逻辑）。
+
+## 速率限制
+
+- 默认：200 req/min
+- 全文内容搜索：30 req/min
+- 聊天 API：登录用户 20/day，匿名 5/day
+
+## 何时使用直接 API 而非 rag_query.py
+
+`rag_query.py` 只封装了 4 种常用查询（search/semantic/dict/kg）。遇到以下情况时，LLM 应直接写 Python 调 API：
+
+- 需要 KG 深度遍历（depth >= 2）
+- 需要跨词典分组对比
+- 需要按多个维度组合筛选
+- 需要相似段落查找
+- 需要跨语言对比