master-skill 0.10.0 → 0.11.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "master-skill",
       "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传 plus compare, debate, and curriculum meta-skills.",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "source": "./",
       "author": {
         "name": "xr843",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "master-skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传 plus compare, debate, and curriculum meta-skills.",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "author": {
     "name": "xr843",
     "email": "xr843@users.noreply.github.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "master-skill",
   "displayName": "Master Skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传.",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "author": {
     "name": "xr843",
     "email": "xr843@users.noreply.github.com"

package/ETHICS.md

@@ -8,12 +8,12 @@
 
 **所有通过 Master-skill 生成的对话、文本、回答，均为 AI 合成内容，不是真实祖师的著作、开示或教言。**
 
-- 每位预置法师的回答均由大型语言模型基于 CBETA 经典文献 + `teaching.md` / `voice.md` 合成，**不代表**历史上该法师的原话、亲口开示或亲笔著作
+- 每位预置法师的回答均由大型语言模型基于该 persona 声明的原典来源（CBETA、BDRC / Toh、SuttaCentral / PTS 或合规编纂开示）+ `teaching.md` / `voice.md` 合成，**不代表**历史上该法师的原话、亲口开示或亲笔著作
 - AI 角色对祖师表达风格的还原是**近似**，非权威：语言选词、句式节奏、比喻用法由模型生成，不可直接引用为"某法师说过"
-- 所有引经据典的 CBETA 编号来自 `sources/` 离线片段或 FoJin 实时检索，但**回答中的文义阐释**是 AI 组合生成，可能与祖师原文含义有偏差
+- 所有引经据典的来源标识必须来自 persona 的 `meta.json.sources[]`；即使来源标识真实，**回答中的文义阐释**仍是 AI 组合生成，可能与祖师原文含义有偏差
 - 使用时请始终默认："这是基于文献的 AI 学习辅助"，不是"与祖师对话"。前者是工具，后者是误解
 
-如你在任何公开场合引用、转发、发表由本项目生成的文本，**必须明确标注 AI 生成属性与原始出处**（CBETA 经号 / FoJin 链接）。将 AI 生成内容作为祖师原话传播，既违反本协议，也违背佛教"不妄语"的基本戒律。
+如你在任何公开场合引用、转发、发表由本项目生成的文本，**必须明确标注 AI 生成属性与原始出处**（来源家族、声明 ID、题名及可用定位信息）。将 AI 生成内容作为祖师原话传播，既违反本协议，也违背佛教"不妄语"的基本戒律。
 
 ---
 
@@ -171,7 +171,7 @@ Master-skill 采取**双轨授权**，代码与内容分开授权：
 | 源代码（`scripts/`、`tools/`、`bin/`、`hooks/`、`.github/`、workflow、CI） | **MIT** | 任意使用、修改、商用 | 去除版权声明 |
 | 预置法师内容（`prebuilt/**/SKILL.md`、`teaching.md`、`voice.md`、`sources/*.md`、`fidelity.jsonl`） | **CC BY-NC-SA 4.0** | 署名 + 非商用 + 相同方式共享下任意使用 | 未署名、纯商业闭源分发 |
 | Prompts 模板（`prompts/**`） | **CC BY 4.0** | 署名后任意使用 | 去署名 |
-| FoJin 检索返回的原始经文 | **CBETA 知识共用 非商业性 禁止改作 3.0** | 遵循 CBETA 原协议 | 违反 CBETA 协议 |
+| FoJin 检索返回的原始经文 / 元数据 / 编纂开示 | **按返回来源族、具体版本与权利人的原始许可**（CBETA、BDRC / Toh、SuttaCentral / PTS、compiled teachings 各自适用） | 在对应许可与合理引用范围内使用并保留出处 | 把某一来源许可套用于其他来源、移除归属、超授权复制或商用 |
 
 **商业化使用（含但不限于）：**
 - SaaS 付费问答服务嵌入 Master-skill 法师内容
@@ -184,24 +184,30 @@ Master-skill 采取**双轨授权**，代码与内容分开授权：
 
 ## 5. 数据来源透明 (Data Provenance)
 
-每位法师 `SKILL.md` frontmatter 必须声明：
-
-```yaml
-sources:
-  - title: {经典名称}
-    cbeta_id: {CBETA 编号，如 T30n1579}
-    fojin_text_id: {FoJin 内部 ID}
-citation_format: "【《{title}》卷{juan}，{cbeta_id}】"
-verified_by: {维护者 GitHub 用户名}
-verified_at: {YYYY-MM-DD}
+每位 persona 的 `meta.json` 必须声明来源清单与同源 citation contract：
+
+```json
+{
+  "sources": [
+    {"type": "cbeta | tibetan_canon | pali_canon | compiled_teaching | ...", "id": "来源族内的声明 ID", "title": "经典或开示题名"}
+  ],
+  "citation_contract": {
+    "version": 1,
+    "claim_policy": "declared_sources_only",
+    "required_for": ["doctrinal_claim", "practice_guidance", "text_interpretation"],
+    "allowed_source_types": ["由 sources[].type 自动派生"],
+    "minimum_claim_coverage": 0.9,
+    "live_retrieval_allowed": true
+  }
+}
 ```
 
 **HARD-GATE 铁律：**
-- 无 CBETA 经号的教义断言不得写入 `teaching.md`
-- 不得捏造 CBETA 编号（CI `scripts/validate.py` 会对照 FoJin 反查）
+- 教义断言、修行指导与文本解释若不能解析到 `meta.json.sources[]` 的声明来源，不得写入 `teaching.md`
+- 不得捏造来源 ID，来源类型必须属于 `citation_contract.allowed_source_types`
 - 不得为虚构人物、合成 persona、无史实记载者建立 `prebuilt/`
 
-违反以上任一，PR 将被自动驳回。
+`scripts/validate-citation-contract.py` 与 `verify_sources.py --check-links/--final-check` 会离线检查来源清单、家族 ID 与合同一致性；它们不解析正文自由文本，也不保证外部站点可达。违反以上任一，PR 将被自动驳回。
 
 ---
 

package/GEMINI.md

@@ -1,2 +1,2 @@
 @./SKILL.md
-@./prebuilt/compare/SKILL.md
+@./prebuilt/compare-masters/SKILL.md

package/README.md

@@ -143,12 +143,12 @@ Master-skill 是由 [FoJin](https://fojin.app) 驱动的佛教 AI 祖师人格
 ## 特性
 
 - **预置十五位四大传统祖师**：1 位印度（龙树 · 中观）+ 8 位汉传（唯识、中观、禅、天台、华严、净土、跨宗派）+ 3 位藏传（阿底峡 · 噶当；宗喀巴 · 格鲁；米拉日巴 · 噶举）+ 3 位南传（觉音 · 上座部论师；马哈希 · 缅甸内观；阿姜查 · 泰国森林）—— 另含 `compare-masters` 多祖师对比 meta-skill，开箱即用
-- **经文溯源（Provenance）**：每位祖师附原典标识（CBETA / BDRC / SuttaCentral）+ FoJin text ID，所有教义断言强制附原典引证
+- **经文溯源（Provenance）**：每位祖师附声明来源 ID（CBETA / BDRC / Toh / SuttaCentral / PTS / 合规编纂开示）；实时检索仅在返回真实 `text_id` 时附 FoJin 定位链接，所有教义断言强制附原典引证
 - **离线经文片段**：`sources/` 目录收录核心经典关键段落，FoJin 不可用时仍可离线引用
 - **渐进式披露**：SKILL.md 以决策树 + Quick Ref 为主，`references/`、`sources/` 按需加载，Context 随查随取
-- **HARD-GATE 铁律**：`/create-master` 与预置法师内置红线——无 CBETA 引证的教义断言不得写入、不得捏造经号、不得为虚构人物建角色
+- **HARD-GATE 铁律**：`/create-master` 与预置法师内置红线——教义断言、修行指导与文本解释必须引用该 persona 声明的来源（CBETA / BDRC / Toh / SuttaCentral / PTS / 合规编纂开示），不得捏造来源 ID，不得为虚构人物建角色
 - **二阶段独立审查**：生成管线在写入前强制经过"教义准确性 → 风格一致性"两轮独立审查，FAIL 自动修复最多 2 轮
-- **自动化保真度测试**：每位祖师 `tests/fidelity.jsonl` 10+ 条 Q&A（`compare-masters` 元技能 18 条），验证引用和关键词覆盖；CI 在每次推送时 dry-run 验证（结构校验）；实跑评分需 `ANTHROPIC_API_KEY`，作为本地/发版前手动步骤执行
+- **自动化保真度测试**：每位祖师 `tests/fidelity.jsonl` 10+ 条 Q&A（`compare-masters` 元技能 18 条），验证引用和关键词覆盖；CI 在每次推送时 dry-run 验证（结构校验）；实跑评分需 `ANTHROPIC_API_KEY`，作为本地/发版前手动步骤执行——首份[实测基线](#保真度基线首次实测)已提交：59/84 已测通过（70%），全量 211 条覆盖率 40%（详见 [eval/reports/](eval/reports/)）
 - **多平台统一插件**：Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI 共用一份 `prebuilt/`，session-start hook 跨平台注入法师列表
 - **NPX 一键安装**：`npx master-skill install master-zhiyi` 直接部署到 Claude Code
 - **离线工具链**：`scripts/cite.py`（CBETA 引用查询）、`scripts/query.py`（离线语义检索）、`scripts/validate.py`（frontmatter linter）
@@ -163,149 +163,51 @@ Master-skill 的核心不是"角色扮演提示词集合"，而是一个可验
 |---|---|
 | 有来源 | 每位祖师声明 `sources[]`、离线 excerpts、FoJin live fallback 与引用自审 |
 | 守边界 | `ETHICS.md`、每位祖师 Layer 0 HARD-GATE、版权 Tier 与教界越界报告机制 |
-| 可评测 | `tests/fidelity.jsonl`、persona-fidelity schema、promptfoo RAW / SPE / CUS 评测层 |
+| 可评测 | `tests/fidelity.jsonl`、persona-fidelity schema、promptfoo RAW / SPE / CUS 评测层，[实测基线见下](#保真度基线首次实测) |
 | 可运行 | `prebuilt/master-*` AgentSkills、npm CLI、多平台 hooks、FoJin runtime contract |
 
 后续 v1.0 路线以框架稳定为优先：见 [docs/v1-framework-roadmap.md](docs/v1-framework-roadmap.md) 与 [docs/fojin-runtime-contract.md](docs/fojin-runtime-contract.md)。
 
----
-
-## 开发者安装
-
-> 👤 **只是想体验？** 直接用 [fojin.app/chat](https://fojin.app/chat)，跳过下面的安装步骤。
-> 🛠️ **本节面向**：Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI 用户，希望在终端 AgentSkill 环境中直接调用 `/master-xuanzang` `/master-huineng` 等命令。
+### 保真度基线（首次实测）
 
-### 安装
-
-**NPX 一键安装（推荐，无需常驻）**
-
-```bash
-# 安装指定祖师
-npx master-skill install master-zhiyi master-fazang master-huineng
+`tests/fidelity.jsonl` 曾经只是"存在的夹具"——`scripts/test-fidelity.py` 只打印到终端，仓库里从未提交过一次真实评分。2026-08-18 首次跑出并提交了这份基线（commit [`c697d5d`](https://github.com/xr843/Master-skill/commit/c697d5d3be78ce6738cf1f969ca057c7e4c16bb5)，模型 `claude-sonnet-4-6`）：
 
-# 安装全部 15 位（四大传统）
-npx master-skill install --all
-
-# 查看可用祖师
-npx master-skill list
-```
-
-**全局安装（频繁使用 / 离线场景）**
+| | 数值 |
+|---|---|
+| 已测通过 / 已测总数 | **59 / 84（70%）** |
+| 全量夹具覆盖率 | 84 / 211（40%）—— 运行途中 API 账户余额耗尽（HTTP 400），非限流也非代码缺陷，剩余 127 条**未测**，不计入失败 |
+| 真实失败聚集 | 关键词未覆盖 14/25；禁用词命中 12/25；引用缺失 5/25；虚构引用 0——**但该审计只在 84 条里的 6 条上真正运行过**，见下 |
+| 分测试类型 | 常规教理 43/48 = **89.6%**；守边界 12/26 = **46.2%**；抗压守引用 4/10 = **40.0%** —— 弱项是护栏，不是教理内容 |
+| ⚠️ 量具告警 | 12 条禁用词失败里有 **10 条，禁用词本就出现在提问中**（陷阱题），而检查是对回答做纯子串匹配——正确的驳斥与真正的越界会被同等判失败。**故真实值落在 70.2%–75.0%**（10 条中仅 4 条剔除该项后会翻成 PASS，其余 6 条另有检查未过），详见基线报告 |
+| ⚠️ 伪造引用审计的实际口径 | 该审计**逐条夹具选配**，全仓 211 条里只有 7 条开启（6 条属 `master-curriculum`、1 条属 `master-huineng`），本次实测到的只有 6 条——**15 位祖师无一被查过伪造引用**。且审计器的 ID 正则只认 CBETA 经号，声明 `PTS:` / `Toh:` / `BDRC:` / `SuttaCentral` 的六位南传、藏传祖师即便开启也无法触发。本行于 2026-08-31 更正，此前表述为「零虚构引用」 |
 
-```bash
-npm install -g master-skill            # 一次性装到 $PATH
-master-skill install master-zhiyi      # 之后省掉 npx，直接调
-master-skill list
-npm update -g master-skill             # 升到下一个 minor / patch
-```
+这是**关键词/引用字符串覆盖率检查，不是教义正确性或 LLM 判分的答案质量**。完整表格、失败案例与方法论说明见 **[eval/reports/BASELINE.md](eval/reports/BASELINE.md)**。
 
-**Claude Code（插件方式）**
+---
 
-```bash
-# npx（上方）与 git clone 手动安装为正式发布渠道：
-git clone https://github.com/xr843/Master-skill ~/Master-skill
-cd ~/Master-skill && pip install -r requirements.txt
-for d in prebuilt/*/; do ln -sf "$(pwd)/$d" ~/.claude/skills/"$(basename $d)"; done
-ln -sf "$(pwd)" ~/.claude/skills/create-master
-```
+## 开发者安装
 
-**Cursor**
+> 👤 **只是想体验？** 直接用 [fojin.app/chat](https://fojin.app/chat)，无需安装。
+> 🛠️ **本节面向** Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI 用户。
 
 ```bash
-git clone https://github.com/xr843/Master-skill ~/Master-skill
-# Cursor 自动检测 .cursor-plugin/plugin.json 并注册技能
-```
-
-**OpenCode**
-
-在 `opencode.json` 中添加：
-
-```json
-{
-  "plugin": ["master-skill@git+https://github.com/xr843/Master-skill.git"]
-}
+npx master-skill install --all          # 一次装全部 20 个 Skill
+npx master-skill install master-huineng # 或只装一位
+npx master-skill list                   # 看全部可装的
+npx master-skill recommend "念佛怎么念才算老实"   # 不知道该问谁？让它推荐
 ```
 
-**Codex CLI**
-
-参见 [.codex/INSTALL.md](.codex/INSTALL.md)
-
-**Gemini CLI**
-
-本项目包含 `gemini-extension.json` 和 `GEMINI.md`，Gemini CLI 自动发现并加载。
-
-### 使用预置法师
+装好后在对话里直接调 `/master-huineng`、`/compare-masters` 等。
 
-在支持 AgentSkills 的环境（Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI）中直接调用：
-
-```
-# 印度
-/master-nagarjuna      — 龙树菩萨（印度·中观｜八宗共祖）
-
-# 汉传
-/master-xuanzang       — 玄奘法师（法相唯识宗）
-/master-kumarajiva     — 鸠摩罗什（三论宗/中观）
-/master-huineng        — 慧能大师（禅宗六祖）
-/master-zhiyi          — 智顗大师（天台宗）
-/master-fazang         — 法藏大师（华严宗）
-/master-yinguang       — 印光大师（净土宗）
-/master-ouyi           — 蕅益大师（天台/净土·跨宗派）
-/master-xuyun          — 虚云老和尚（禅宗·五宗兼嗣）
-
-# 藏传
-/master-atisha         — 阿底峡尊者（噶当派开祖 · 三士道 · 982-1054）
-/master-tsongkhapa     — 宗喀巴大师（格鲁派创始人 · 三主要道 · 应成中观）
-/master-milarepa       — 米拉日巴尊者（噶举派 · 大手印 · 那洛六法）
-
-# 南传
-/master-buddhaghosa    — 觉音尊者（上座部论师 · 《清净道论》· 5世纪）
-/master-mahasi-sayadaw — 马哈希尊者（缅甸内观 · 标记法 · 1904-1982）
-/master-ajahn-chah     — 阿姜查（泰国森林禅林派 · 巴蓬寺传承）
-```
-
-### 教学模式（v0.7）
-
-- **`/compare-masters`** — 多位法师对同一问题的并列对比（横向 / 单轮）
-- **`/master-debate`** — 祖师就争议议题做多轮交叉辩论（v0.8 起：**每轮派 fresh subagent**，只携带对方上一轮 ≤80 字摘要 + 本方 cross_critique 弹药；轮数由 `debate_protocol.per_pair_overrides` 决定，默认 4 轮，`huineng-vs-tsongkhapa` / `ouyi-vs-tsongkhapa` 默认 5 轮）
-- **`/master-curriculum`** — 按你的传统（禅 / 净 / 天台 / 华严 / 唯识 / 中观 / 格鲁 / 上座部）与当前位置（L0-L3）给出有时序的学修路径
-
-**`/compare-masters` 用法示例：**
-
-```
-# 自动选择相关法师
-/compare-masters 什么是空性
-
-# 手动指定法师（推荐，结果更精准）
-/compare-masters 什么是遍行因 --masters master-xuanzang,master-zhiyi,master-ouyi
-
-# 自然语言触发
-请慧能和印光对比回答"如何看待念佛"
-比较禅宗和净土宗对修行的看法
-```
-
-**选择逻辑**：系统先尝试从用户提问中提取关键词，与每位法师的核心概念匹配；若无强匹配，则按主题映射兜底（念佛/禅修/唯识中观/判教等）。**如果自动选的法师不符合预期，直接用 `--masters` 手动指定**。
-
-### 自定义生成
-
-```
-/create-master 弘一大师
-```
-
-或自然语言触发：
-
-```
-帮我创建一个弘一大师的教学角色
-```
-
-系统将引导完成三步信息录入，然后自动从 FoJin 采集数据、生成教义分析与风格文件。
-
----
+> 五端安装细节（Claude Code 插件 / Cursor / OpenCode / Codex CLI / Gemini CLI）、
+> 全局安装、教学模式用法、`/create-master` 自定义生成
+> → **[docs/install.md](docs/install.md)**
 
 ## 桌面管理器
 
-原生桌面控制台(纯 Rust,egui,单二进制,无 Electron),统一管理 17 个 master skill 的安装状态、fidelity 评测覆盖率、运行追踪与质量门禁:
+原生桌面控制台(纯 Rust,egui,单二进制,无 Electron),统一管理 19 个 master skill 的安装状态、fidelity 评测覆盖率、运行追踪与质量门禁:
 
-![Master-skill Desktop Manager](https://raw.githubusercontent.com/xr843/Master-skill/master/docs/assets/desktop-manager.png)
+![Master-skill Desktop Manager](https://raw.githubusercontent.com/xr843/Master-skill/main/docs/assets/desktop-manager.png)
 
 **下载**:[Releases](https://github.com/xr843/Master-skill/releases) 提供 Linux / Windows / macOS 预编译二进制,下载后直接运行(仓库根目录下执行,需本地已 clone 本仓库)。Linux / macOS 下载后需先 `chmod +x` 赋予可执行权限;macOS 上二进制未签名,首次运行需右键"打开"或执行 `xattr -d com.apple.quarantine <文件名>` 解除隔离。
 
@@ -321,153 +223,33 @@ cd desktop && cargo build --release
 
 ## 预置法师
 
-### 龙树菩萨（Nāgārjuna，约150-250） — 印度 · 中观
-
-大乘中观奠基者，汉传尊为「八宗共祖」——三论、天台、净土、华严、禅皆溯源于他，藏传应成中观亦以他为根本所依。立「八不中道」破一切戏论，以「众因缘生法，我说即是空」开显缘起性空，依二谛说法而归于毕竟空、戏论寂灭，并以难易二道判摄修行。所著《中论》为后世中观学之根本论典，《大智度论》则为般若义海之百科。
-主要来源：CBETA《中论》T30n1564、《大智度论》T25n1509、《十二门论》T30n1568、《迴诤论》T32n1631、《十住毗婆沙论》T26n1521。
-调用命令：`/master-nagarjuna`
-
-### 玄奘法师（602-664）
-
-唐代高僧，中国佛教史上最伟大的译经家。西行求法十七年，遍学印度诸部，归国后主持译经事业，译出经论七十五部一千三百三十五卷。创立法相唯识宗，以严谨精确的翻译风格著称，确立"五种不翻"原则。
-主要来源：CBETA《大般若经》《瑜伽师地论》《成唯识论》《心经》等。
-调用命令：`/master-xuanzang`
-
-### 鸠摩罗什（Kumarajiva，344-413）
-
-龟兹出身，后秦长安译经，中国四大译经家之一。其译文以文学性和流畅度著称，《妙法莲华经》《金刚经》《维摩诘经》《中论》等译本至今最为通行。奠定了三论宗（中观）在中国的基础。
-主要来源：CBETA《妙法莲华经》《金刚经》《维摩诘经》《中论》《大智度论》等。
-调用命令：`/master-kumarajiva`
-
-### 慧能大师（638-713）
-
-禅宗六祖，南宗禅创立者。不识文字的卖柴樵夫，闻《金刚经》而开悟，得五祖弘忍传法。著《六祖坛经》——中国人著作中唯一被尊为"经"者。主张"直指人心，见性成佛"，开顿悟法门。
-主要来源：CBETA《六祖大师法宝坛经》T48n2008。
-调用命令：`/master-huineng`
-
-### 智顗大师（538-597）
-
-天台宗创始人，被尊为"东土小释迦"。建立中国佛教第一个完整的判教体系（五时八教），著天台三大部《摩诃止观》《法华玄义》《法华文句》。核心思想：一念三千、三谛圆融、止观双修。
-主要来源：CBETA《摩诃止观》T46n1911、《法华玄义》T33n1718 等。
-调用命令：`/master-zhiyi`
-
-### 法藏大师（643-712）
-
-华严宗三祖，华严哲学体系的实际创立者。武则天国师，以"金师子章"为武后说华严义。核心思想：法界缘起、四法界、十玄门、六相圆融——一切现象互含互摄，事事无碍。
-主要来源：CBETA《华严经探玄记》T35n1733、《华严五教章》T45n1866 等。
-调用命令：`/master-fazang`
-
-### 印光大师（1861-1940）
-
-汉传净土宗第十三代祖师，近代净土复兴的核心人物。
-文字平实恳切，戒行严谨，以书信形式广度众生，著有《印光法师文钞》三编。
-主要来源：CBETA 汉文大藏经，含文钞正编、续编、三编及净土三经。
-调用命令：`/master-yinguang`
-
-### 蕅益大师（1599-1655）
-
-明末四大高僧之一，净土宗九祖。"教宗天台，行归净土"——融通禅、教、律、净四宗，是中国佛教史上最重要的跨宗派综合者。其《阿弥陀经要解》被印光大师赞为"即使古佛再来，也不能超过其上"。
-主要来源：CBETA《阿弥陀经要解》T37n1762、《教观纲宗》等。
-调用命令：`/master-ouyi`
-
-### 虚云老和尚（1840-1959）
-
-近代禅宗泰斗，世寿一百二十岁，一身兼嗣禅门五宗（临济、曹洞、沩仰、云门、法眼）法脉——佛教史上绝无仅有。复兴六大祖庭，历经清末、民国、新中国三个时代。主张参话头、老实修行、禅净双修。
-主要来源：CBETA《楞严经》《金刚经》《六祖坛经》等。
-调用命令：`/master-xuyun`
-
-### 阿底峡尊者（Atiśa Dīpaṃkara, 982-1054） — 藏传 · 噶当派 · 印藏桥梁
-
-印度孟加拉萨霍尔国王子出身，超戒寺住持。1042 年应藏王智光邀请入藏，著《菩提道灯论》(Bodhipathapradīpa)——藏地后弘期道次第之祖。首座弟子仲敦巴建热振寺，开**噶当派**（佛语教授派）。后被宗喀巴新噶当派（即格鲁派）继承。藏传四派（宁玛、萨迦、噶举、格鲁）皆视其为根本师之一。
-主要来源：Toh 4465《菩提道灯论》（sDe dge bsTan 'gyur 标准编号）+ 噶当口耳传承《父法·子法》。
-调用命令：`/master-atisha`
-
-### 宗喀巴大师（Tsongkhapa, 1357-1419） — 藏传 · 格鲁派创始人
-
-藏传佛教**格鲁派**（"善规派"，俗称"黄教"）创始人，达赖喇嘛与班禅喇嘛传承根基。出生于青海宗喀（今西宁附近），师承萨迦派仁达瓦等。深感当时藏地戒律松弛、显密混淆，立"三主要道"（出离心 / 菩提心 / 清净见）为道次第凝练，著《菩提道次第广论》《密宗道次第广论》《辨了不了义善说藏论》。1409 年建甘丹寺（dGa' ldan），格鲁派开山祖庭。
-主要来源：宗喀巴全集 gsung 'bum（BDRC.io 检索 'tsong kha pa'）。汉译参考法尊法师本。
-调用命令：`/master-tsongkhapa`
-
-> ⚠️ 续部具体修法步骤、灌顶仪轨、生起圆满次第细节、本尊咒语、明点观想**只介绍历史与原理，不传授具体修法步骤**。
-
-### 米拉日巴尊者（Milarepa, 1052-1135） — 藏传 · 噶举派
-
-藏传佛教噶举派精神祖师，"瑜伽士"传统（不入寺院、山中闭关、以歌教化）的典范。早年咒杀仇家造重业，依止玛尔巴译师净罪求法，于雪山闭关数十年以荨麻为食。以**道歌（mGur）**说法，影响后世整个藏传佛教。
-主要来源：BDRC《米拉日巴道歌集》（W1KG14334，《十万歌集》mGur 'bum）、《密勒日巴尊者传》（W22272）。
-调用命令：`/master-milarepa`
-
-> ⚠️ 那洛六法、拙火、生起／圆满次第等密法**只介绍历史与原理，不传授具体修法步骤**。具体修持必须依止具格上师亲传与灌顶。
-
-### 觉音尊者（Buddhaghosa, 5世纪） — 南传 · 上座部论师
-
-上座部佛教史上最具影响力的注释家与论师。原为印度南部婆罗门学者，赴斯里兰卡大寺（Mahāvihāra），将古僧伽罗注释翻译为巴利语。著《清净道论》(Visuddhimagga)——以**戒（sīla）、定（samādhi）、慧（paññā）三学**为骨架，系统组织上座部禅修与教理之百科全书（23 章）。其著作奠定南传上座部正统教理体系——东南亚一切论师皆依其判摄。
-主要来源：PTS edition《清净道论》(Visuddhimagga) + 四部尼柯耶注释（aṭṭhakathā）+ Samantapāsādikā 律藏注释 + Atthasālinī 阿毗达摩注释。
-调用命令：`/master-buddhaghosa`
-
-### 马哈希尊者（Mahāsi Sayādaw U Sobhana, 1904-1982） — 南传 · 缅甸内观传统
-
-缅甸现代最具国际影响力的内观禅修大师之一。1947 年起主持仰光 Mahasi Sasana Yeiktha，形成**'马哈希内观法'**（标记法 / Noting Method）——以观察腹部起伏为主所缘，系统培育七清净十六观智。1954-1956 年第六次结集（Chaṭṭha Saṅgāyana）任**'最终编辑长老'**，审定整个巴利三藏。其法系深刻影响美国 Insight Meditation Society 三位创办人（Goldstein、Kornfield、Salzberg）。
-主要来源：《Manual of Insight》(Wisdom Publications, 2016)、《The Progress of Insight》(BPS Sri Lanka)、《Practical Vipassanā Meditation Exercises》(Mahasi Sasana Yeiktha)。
-调用命令：`/master-mahasi-sayadaw`
-
-> ⚠️ **本平台 AI 不得对个体作证果判定或观智阶位确认**——印证须由具格禅师面对面访谈鉴定。这是马哈希教学体系最严肃的 guardrail。
-
-### 阿姜查 Ajahn Chah Subhaddo（1918-1992） — 南传 · 泰国森林禅林派
-
-泰国森林禅林派最具国际影响力的禅师之一。以巴利戒律严格持守、四念处禅修、朴素生活化教学著称。其英语弟子（阿姜苏美多、阿姜帕沙诺等）建立了无畏山林、阿马罗筏底、奇泰罗等海外分院，将森林禅林派传至欧美。代表名言："如果你少放下一点，你就少一点苦。"
-主要来源：巴利三藏（SuttaCentral）+ 公开开示集《Food for the Heart》《A Still Forest Pool》《Living Dhamma》。
-调用命令：`/master-ajahn-chah`
-
----
+十五位祖师，四大传统。命令即技能名，装好后直接在对话里调用。
+
+| 命令 | 祖师 | 传统 · 宗派 | 年代 |
+|---|---|---|---|
+| `/master-nagarjuna` | 龙树菩萨 | 印度 · 中观（八宗共祖） | 约 150-250 |
+| `/master-kumarajiva` | 鸠摩罗什 | 汉传 · 三论／中观 | 344-413 |
+| `/master-zhiyi` | 智顗大师 | 汉传 · 天台 | 538-597 |
+| `/master-xuanzang` | 玄奘法师 | 汉传 · 法相唯识 | 602-664 |
+| `/master-huineng` | 慧能大师 | 汉传 · 禅宗六祖 | 638-713 |
+| `/master-fazang` | 法藏大师 | 汉传 · 华严 | 643-712 |
+| `/master-ouyi` | 蕅益大师 | 汉传 · 天台／净土（跨宗派） | 1599-1655 |
+| `/master-xuyun` | 虚云老和尚 | 汉传 · 禅宗五宗兼嗣 | 1840-1959 |
+| `/master-yinguang` | 印光大师 | 汉传 · 净土 | 1861-1940 |
+| `/master-atisha` | 阿底峡尊者 | 藏传 · 噶当（三士道） | 982-1054 |
+| `/master-milarepa` | 米拉日巴尊者 | 藏传 · 噶举（大手印） | 1052-1135 |
+| `/master-tsongkhapa` | 宗喀巴大师 | 藏传 · 格鲁（应成中观） | 1357-1419 |
+| `/master-buddhaghosa` | 觉音尊者 | 南传 · 上座部论师 | 5 世纪 |
+| `/master-mahasi-sayadaw` | 马哈希尊者 | 南传 · 缅甸内观 | 1904-1982 |
+| `/master-ajahn-chah` | 阿姜查 | 南传 · 泰国森林禅林派 | 1918-1992 |
+
+**教学模式**：`/compare-masters` 并列对比 · `/master-debate` 多轮对辩 · `/master-curriculum` 学修路径 · `/master-help` 我该问谁 · `/create-master` 自定义生成
+
+> 每位祖师的生平、核心思想与声明来源 → **[docs/masters.md](docs/masters.md)**
 
 ## 架构图
 
-```
-用户请求
-    |
-    v
-session-start hook ──> 自动注入法师列表（5 端统一）
-    |
-    v
-SKILL.md (AgentSkills 入口：决策树 + Quick Ref)
-    |
-    +-- 预置法师 --> prebuilt/{slug}/
-    |                   +-- SKILL.md          (决策树 + <HARD-GATE> 铁律)
-    |                   +-- meta.json         (version / lineage / provenance)
-    |                   +-- references/       (按需加载)
-    |                   |   +-- teaching.md
-    |                   |   +-- voice.md
-    |                   +-- sources/          (离线经文片段)
-    |                   |   +-- *.md (CBETA 段落)
-    |                   +-- tests/
-    |                       +-- fidelity.jsonl  (保真度样例, CI dry-run)
-    |
-    +-- 工具链
-    |   +-- scripts/validate.py         (frontmatter linter)
-    |   +-- scripts/cite.py             (CBETA 引用查询)
-    |   +-- scripts/query.py            (离线语义检索)
-    |   +-- scripts/test-fidelity.py    (保真度测试)
-    |   +-- scripts/validate-fidelity.py
-    |   +-- bin/cli.mjs                 (NPX installer)
-    |
-    +-- 自定义生成 (/create-master, 带 HARD-GATE)
-          +-- Step 1-2  prompts/intake.md → tools/sutra_collector.py
-          |             └─> FoJin API (KG + 语义检索 + 文本)
-          +-- Step 3    prompts/{sutra,voice}_analyzer.md → 两阶段分析
-          +-- Step 3.5  二阶段独立审查 ──┬─ prompts/doctrine_reviewer.md
-          |                             └─ prompts/voice_reviewer.md
-          +-- Step 4-5  tools/master_builder.py → tools/skill_writer.py
-                        └─> tools/verify_sources.py (写入前最终验证)
-
-多平台插件统一入口：
-  .claude-plugin/    → Claude Code      (hooks/run-hook.cmd → session-start)
-  .cursor-plugin/    → Cursor           (hooks/hooks-cursor.json)
-  .codex/            → Codex CLI        (.codex/INSTALL.md)
-  .opencode/         → OpenCode         (opencode.json 引用)
-  gemini-extension.json → Gemini CLI    (GEMINI.md 自动加载)
-```
-
----
+目录结构与数据流 → **[docs/architecture.md](docs/architecture.md)**
 
 ## 与 FoJin 的关系
 
@@ -479,7 +261,7 @@ Master-skill 通过 `tools/fojin_bridge.py` 接入 FoJin API，实现：
 - 语义向量相似度搜索（教义相关经文）
 - 原文段落提取与出处追踪
 
-所有引用均附带可追溯的 FoJin 链接，确保内容来源透明。
+所有引用都必须能追溯到 persona 声明的来源 ID；仅当实时检索返回真实 `text_id` 时附 FoJin 定位链接，否则使用对应官方目录或离线声明来源。
 
 ---
 
@@ -493,35 +275,15 @@ Master-skill 通过 `tools/fojin_bridge.py` 接入 FoJin API，实现：
 
 **要做：**
 
-- 忠实依据经文原文，所有回答附 FoJin 出处链接
-- 通过运行时 RAG 检索真实经文，而非仅依赖 AI 自身知识
+- 忠实依据声明来源，回答附可追溯的来源 ID；有真实 `text_id` 时再附 FoJin 定位链接
+- 仅在 citation contract 允许且离线资料不足时通过运行时 RAG 检索，不以 AI 自身知识冒充原典
 - 遇到超出范围的问题坦诚说明
 
 ---
 
 ## 常见问题
 
-**Q：FoJin API 不可达时还能用吗？**
-
-能。每位预置法师的 `prebuilt/<name>/sources/` 收录了该法师核心经典的关键段落（离线经文片段）。FoJin 不可用时，法师会降级到离线模式并在回答中声明"当前使用离线片段"。`/create-master` 管线遇到 API 故障会提示用户切换手动输入模式，由用户粘贴经文原文继续生成。
-
-**Q：CBETA 引用格式是什么样的？怎么验证？**
-
-所有 CBETA 引证必须带 `Txxn####` 形式的经号（例如《妙法蓮華經》→ `T9n262`）。`scripts/validate.py` 会检查 frontmatter 的 `sources` 字段格式；`tools/verify_sources.py` 在写入前会逐条核对 FoJin `text_id` 的有效性，失效链接自动降级为 FoJin 搜索链接，不会留下死链。
-
-**Q：`npx master-skill install` 执行失败、报 ENOTEMPTY 或权限错误怎么办？**
-
-先清理 `~/.claude/skills/master-<name>/` 残留目录再重试。如果是 npm 缓存问题，`npm cache clean --force` 后重跑 NPX。Windows 用户请在 Git Bash 或 WSL 中执行，避免 cmd.exe 的路径转义问题。
-
-**Q：生成的法师内容和历史记载不符，怎么纠正？**
-
-直接在对话中告诉法师"他不会这样说话"或"他应该更严厉一些"。`/create-master` 的纠正模式会识别纠正类型（教义纠正 → 追加到 `teaching.md`；风格纠正 → 追加到 `voice.md`），以 `## Correction` 块形式记录并自动递增 patch 版本号。纠正记录的优先级高于分析生成的内容。
-
-**Q：如何贡献一位新的预置法师？**
-
-见下方「贡献指南」。基本流程：遵循 v0.3 目录结构生成 `prebuilt/<name>/`、跑通 `scripts/validate.py --strict`、补齐 `tests/fidelity.jsonl` 的 5 条以上样例，然后提 PR。
-
----
+安装、调用、检索的常见问题 → **[docs/troubleshooting.md](docs/troubleshooting.md)**
 
 ## 贡献指南