docs: expand SKILL.md with detailed flow control, error handling, and priority rules (P1)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

SKILL.md

@@ -55,6 +55,32 @@ allowed-tools:
 2. 关注方面 → 教义/修行/讲解/全部
 3. 语言偏好 → 根据传承自动推荐
 
+**快捷入口**：如用户直接提供法师名称（如 `/create-master 弘一大师`），跳过交互式问答，自动填充默认值（关注方面=全部，语言=根据传承推荐），进入确认流程。展示确认摘要：
+
+```
+即将创建：弘一大师
+传承：汉传（律宗）
+关注方面：全部
+语言：中文
+确认创建？(Y/n)
+```
+
+用户确认后直接进入 Step 2。
+
+**语言自动检测**：根据用户第一条消息的语言决定后续全部交互语言。中文消息 → 中文回复；English message → English replies；其他语言同理。
+
+**FoJin 知识图谱匹配**：
+- 匹配成功 → 自动填充传承、时代、宗派等元数据，展示给用户确认
+- 匹配失败 → 提示："未在 FoJin 知识图谱中找到「{name}」。请确认名称是否正确，或提供以下信息以手动创建：传承（汉传/南传/藏传）、时代、宗派。"
+- 用户提供补充信息后，以手动模式继续
+
+**校验规则**：
+- 名称必须为历史真实人物，不接受虚构角色（如小说人物、游戏角色）
+- 如检测到非历史人物，回复："本工具仅支持历史上真实存在的高僧大德，无法为虚构人物创建教学角色。"
+- 名称不可为空，不可为纯数字或特殊字符
+- 如用户输入的名称有多种写法（如"鸠摩罗什"/"鸠摩罗什婆"），优先使用 FoJin KG 中的标准名称
+- 如该法师已存在于预置列表或已生成列表中，提示："「{name}」已存在，可直接使用 /{slug} 调用。如需重新生成，请先执行 /delete-master {slug}。"
+
 ### Step 2：数据采集
 
 使用 `${CLAUDE_SKILL_DIR}/tools/sutra_collector.py` 从 FoJin 采集数据：
@@ -68,22 +94,91 @@ python3 ${CLAUDE_SKILL_DIR}/tools/sutra_collector.py --name "<法师名>" --trad
 - 相关经典列表和内容摘录
 - 传承相关术语
 
+**API 故障处理**：
+- 如 FoJin API 返回错误或不可达，向用户说明："FoJin API 暂时不可用（错误信息：{error}）。您可以：1) 稍后重试；2) 进入手动输入模式，提供经文文本。"
+- 手动输入模式下，用户可粘贴经文原文或提供 CBETA 经号，系统基于用户提供的材料继续生成
+
+**超时设置**：每次 API 调用超时时间为 30 秒。超时后自动重试一次，仍失败则触发上述故障处理。
+
+**最低数据阈值**：如采集到的经文结果少于 3 条，向用户发出警告："仅找到 {n} 条相关经文，生成的角色内容可能不够丰富。建议：1) 追加关键词重新搜索；2) 手动补充经文材料；3) 继续生成（内容可能有限）。"
+
+**CBETA ID 验证**：采集完成后，使用 `verify_sources.py` 验证所有 CBETA 链接的有效性：
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/tools/verify_sources.py --check-links collected_data.json
+```
+
+无效链接将被标记并在 Step 3 中排除，避免生成内容引用不存在的出处。
+
+**采集结果确认**：采集完成后，向用户简要报告采集情况：
+
+```
+数据采集完成：
+  知识图谱实体：{n} 个
+  相关经典：{m} 部
+  内容摘录：{k} 段
+  无效链接：{j} 个（已排除）
+继续分析？(Y/n)
+```
+
 ### Step 3：分析与生成
 
 **运行时检索规则**：加载 `${CLAUDE_SKILL_DIR}/prompts/rag_instructions.md`，将其中的检索指引嵌入生成的每个法师 SKILL.md 的运行规则中，确保法师回答时调用 FoJin 实时检索而非仅依赖 LLM 自身知识。
 
-**教义分析**：加载 `${CLAUDE_SKILL_DIR}/prompts/sutra_analyzer.md`，填入采集数据，分析教义结构。
+**两阶段分析**：
 
-**风格分析**：加载 `${CLAUDE_SKILL_DIR}/prompts/voice_analyzer.md`，填入采集数据，分析说法风格。
+1. **教义分析（第一阶段）**：加载 `${CLAUDE_SKILL_DIR}/prompts/sutra_analyzer.md`，填入采集数据，分析教义结构。输出包括核心教义维度、关键经典、修行次第等。
+
+2. **风格分析（第二阶段）**：加载 `${CLAUDE_SKILL_DIR}/prompts/voice_analyzer.md`，填入采集数据，分析说法风格。输出包括语言特征、说法模式、常用譬喻等。
+
+**传承标签自动检测**：根据 FoJin 知识图谱中该法师的宗派/传承信息，自动应用 voice_analyzer 中对应传承的风格规则。例如：
+- 禅宗 → 应用机锋、公案风格规则
+- 净土宗 → 应用劝信、念佛开示风格规则
+- 南传 → 应用巴利经典引用、内观指导风格规则
+- 藏传 → 应用次第道、灌顶开示风格规则
+
+**质量门控**：如分析器输出中任一维度标记为 `"insufficient_data": true`，在继续前向用户提示：
+- "以下维度的数据不足，生成质量可能受影响：{dimensions}。"
+- "建议追加相关经文材料后重新分析，或选择继续生成（不足部分将标注警告）。"
+- 用户选择继续 → 在生成的文件中对不足维度添加 `<!-- DATA_LIMITED -->` 注释标记
+
+**RAG 指引嵌入**：加载 `${CLAUDE_SKILL_DIR}/prompts/rag_instructions.md`，将检索规则（查询构造、结果过滤、引用格式）嵌入生成的 SKILL.md 运行时规则段落中。
 
 **教义生成**：加载 `${CLAUDE_SKILL_DIR}/prompts/teaching_builder.md`，基于分析结果生成 teaching.md。
 
-**风格生成**：加载 `${CLAUDE_SKILL_DIR}/prompts/voice_builder.md`，基于分析结果生成 voice.md。
+**风格生成**：加载 `${CLAUDE_SKILL_DIR}/prompts/voice_builder.md`，基于分析结果生成 voice.md。voice.md 采用分层结构：
+- Layer 0：硬规则（不可违反的底线，如"不自称佛"、"不预言未来"）
+- Layer 1：核心风格（该法师最显著的说法特征）
+- Layer 2：辅助风格（次要但常见的表达模式）
+- Layer 3：情境风格（特定场景下的应对方式）
 
 ### Step 4：预览与确认
 
 展示生成的 teaching.md 和 voice.md 预览，请用户确认。
 
+**结构化预览格式**：
+
+```
+══ 教义预览（teaching.md）══
+核心教义：{1-3 条核心教义概要}
+关键经典：{主要引用经典列表}
+修行次第：{修行路径概要}
+
+══ 风格预览（voice.md）══
+风格特征：{2-3 条风格特点}
+语言模式：{典型表达方式}
+示例句：
+  1. "{模拟该法师风格的示例句1}"
+  2. "{模拟该法师风格的示例句2}"
+══════════════════════════
+```
+
+**用户修改请求**：用户可在确认前要求修改，支持以下指令：
+- "修改教义部分" → 重新展示 teaching.md 详情，接受用户逐条调整
+- "调整风格更严厉一些" / "语气更温和" → 调整 voice.md 中的风格参数后重新预览
+- "添加更多关于{主题}的内容" → 针对性补充特定教义维度
+- "重新生成" → 以调整后的参数重新执行 Step 3，重新展示预览
+
 ### Step 5：写入文件
 
 使用 `${CLAUDE_SKILL_DIR}/tools/skill_writer.py` 写入文件：
@@ -92,23 +187,69 @@ python3 ${CLAUDE_SKILL_DIR}/tools/sutra_collector.py --name "<法师名>" --trad
 python3 ${CLAUDE_SKILL_DIR}/tools/master_builder.py --name "<法师名>" --output masters/
 ```
 
+**写入前验证**：调用 `verify_sources.py` 最终验证所有 FoJin 链接：
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/tools/verify_sources.py --final-check masters/{slug}/
+```
+
+无效链接将被替换为 FoJin 搜索链接（降级策略），确保用户始终能找到相关内容。
+
+**生成文件**：
+
 生成目录结构：
 ```
 masters/{slug}/
-├── SKILL.md          # /{slug} 触发
-├── teaching.md       # 教义体系
-├── voice.md          # 说法风格
-└── meta.json         # 元数据
+├── SKILL.md          # /{slug} 触发（完整角色定义）
+├── teaching.md       # 教义体系（可单独使用）
+├── voice.md          # 说法风格（可单独使用）
+└── meta.json         # 元数据（版本、生成时间、数据来源）
+```
+
+**角色注册**：
+
+Claude Code 用户：
+1. 生成的 SKILL.md 已放置在 `masters/{slug}/` 目录下
+2. 确保 `masters/` 目录在 Claude Code 的 skill 搜索路径中（检查 `.claude/settings.json` 的 `skillDirs` 配置）
+3. 完成后自动可通过 `/{slug}` 命令触发
+
+OpenClaw 用户：
+1. 将 `masters/{slug}/` 目录复制到 OpenClaw 的 skills 目录
+2. 在 OpenClaw 配置中注册新 skill
+3. 参考 OpenClaw 文档完成注册流程
+
+**完成提示**：写入成功后展示最终摘要：
+
+```
+已生成「{master_name}」教学角色
+  目录：masters/{slug}/
+  调用命令：/{slug}
+  包含文件：SKILL.md, teaching.md, voice.md, meta.json
+  数据来源：{n} 条经文，{m} 个知识图谱实体
 ```
 
 ## 追加材料（进化模式）
 
-用户可以追加新的经文材料来增强已有法师：
+用户可以追加新的经文材料来增强已有法师。
+
+**触发短语**：
 - "给印光大师追加《文钞三编》的材料"
+- "追加《经名》的材料"
+- "补充关于{主题}的内容"
 - "用这段语录更新阿姜查的说法风格"
 
 加载 `${CLAUDE_SKILL_DIR}/prompts/merger.md` 进行增量合并。
 
+**合并冲突处理**：
+- merger.md 采用"新数据优先、保留原有结构"策略
+- 如新材料与现有教义存在矛盾（如不同经典对同一概念的阐述差异），保留双方并添加注释说明差异
+- 风格维度的冲突：新材料的风格特征会与现有特征合并，不会覆盖
+
+**版本自动递增**：
+- 每次追加材料后，meta.json 中的 `version` 自动递增（如 1.0.0 → 1.1.0）
+- 旧版本自动归档到 `masters/{slug}/.versions/` 目录
+- 可通过 `/master-rollback` 命令回退到任意历史版本
+
 ## 纠正模式
 
 用户在使用法师角色时，可以对 AI 的表现提出纠正：
@@ -116,13 +257,37 @@ masters/{slug}/
 - "他应该更严厉一些"
 - "他遇到这种问题会先引用《法华经》"
 
-加载 `${CLAUDE_SKILL_DIR}/prompts/correction_handler.md` 进行纠正处理。纠正记录追加到对应法师的 teaching.md 或 voice.md 中，优先级高于分析生成的内容。
+加载 `${CLAUDE_SKILL_DIR}/prompts/correction_handler.md` 进行纠正处理。
+
+**纠正处理流程**：
+1. 识别纠正类型：教义纠正 → 写入 teaching.md；风格纠正 → 写入 voice.md
+2. 以 `## Correction` 块格式追加到对应文件末尾，包含时间戳和原始反馈
+3. 纠正记录的优先级高于分析生成的内容（参见「执行优先级」）
+4. 每次纠正后自动递增 meta.json 版本号（patch 级别，如 1.1.0 → 1.1.1）
 
 ## 管理命令
 
-- `/list-masters` — 列出所有已生成的法师
-- `/master-rollback <slug> <version>` — 回滚到指定版本
-- `/delete-master <slug>` — 删除一个法师
+- `/list-masters` — 列出所有已生成的法师（含预置和自定义），显示传承、时代、版本号信息。预置法师标记为 `[预置]`，自定义法师标记为 `[自定义]`。
+- `/master-rollback <slug> <version>` — 回滚到指定版本。当前版本自动归档到 `.versions/` 目录，指定版本恢复为当前版本。如指定版本不存在，列出所有可用版本供选择。
+- `/delete-master <slug>` — 删除一个法师目录。执行前需用户二次确认："确定要删除「{master_name}」吗？此操作不可恢复。输入 'yes' 确认。" 预置法师不可删除。
+
+## 执行优先级
+
+法师角色运行时，按以下优先级处理：
+
+1. voice.md Layer 0 硬规则（最高优先级，无条件执行）
+2. Correction 记录（用户纠正，优先于分析生成内容）
+3. voice.md Layer 1-3（分析生成的风格规则）
+4. teaching.md 教义内容
+5. FoJin RAG 实时检索结果
+6. LLM 自身知识（最低优先级）
+
+当不同层级产生冲突时，高优先级层级覆盖低优先级。
+
+**示例**：
+- 如 voice.md Layer 0 规定"不自称已证悟"，即使 teaching.md 中有该法师证悟的记载，回答时也不以第一人称宣称证悟
+- 如用户纠正"他从不直接回答是非题"，则该纠正覆盖 voice.md Layer 1-3 中可能存在的直接回答模式
+- 如 FoJin RAG 检索到的经文与 teaching.md 中的记载有细节差异，以 teaching.md 为准（RAG 作为补充参考）
 
 ## 工具路由
 
@@ -134,6 +299,7 @@ masters/{slug}/
 | 角色生成 | `${CLAUDE_SKILL_DIR}/tools/master_builder.py` |
 | 文件写入 | `${CLAUDE_SKILL_DIR}/tools/skill_writer.py` |
 | 版本管理 | `${CLAUDE_SKILL_DIR}/tools/version_manager.py` |
+| 来源验证 | `${CLAUDE_SKILL_DIR}/tools/verify_sources.py` |
 
 ## 敏感性边界
 
@@ -141,8 +307,12 @@ masters/{slug}/
 - 不对宗派优劣进行评判
 - 不宣称神通感应
 - 不涉及政治化宗教议题
+- 不为用户做重大人生决定（如出家、离婚等），仅提供佛法视角的参考
+- 不声称能替代真实善知识的指导
 
 **要做：**
 - 忠实依据经文原文，所有回答附 FoJin 出处链接
 - 通过 rag_query.py 实时检索真实经文
 - 遇到超出范围的问题坦诚说明
+- 涉及不同宗派观点时，注明"此为{宗派}观点"
+- 遇到心理健康相关问题时，建议用户寻求专业帮助