codechakorn/Master-skill
1
0
Fork 0
mirror of https://github.com/xr843/Master-skill.git synced 2026-05-10 05:16:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7 from xr843/docs/sync-readme-v03

Browse Source 
docs(readme): sync README to v0.3 reality, bring EN in lockstep with CN
This commit is contained in:
Tim Ren
2026-04-10 14:36:06 +08:00
committed by GitHub
parent 3f51fc7ee7 4eb92ab048
commit 38e7eb09dd
2 changed files with 155 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+58 -16
View File
@@ -35,7 +35,9 @@
---
> **v0.3 更新**：全面架构重构——渐进式披露（SKILL.md < 100 行）、CBETA 经文溯源（provenance frontmatter）、离线经文片段（sources/）、自动化保真度测试（fidelity.jsonl）、NPX 一键安装、cite.py/query.py 离线工具链。
> **v0.3 更新**：全面架构重构——CBETA 经文溯源（provenance frontmatter）、离线经文片段（sources/）、自动化保真度测试（fidelity.jsonl）、NPX 一键安装、cite.py/query.py 离线工具链。
>
> **v0.3 后续迭代**：`/create-master` 生成管线新增二阶段独立审查（教义准确性 → 风格一致性）、HARD-GATE 铁律（无 CBETA 引证不得写入）、多平台插件支持（Claude Code / Cursor / Codex / OpenCode / Gemini CLI 五端统一）、session-start hook 自动注入法师列表、8 位预置法师的 pressure tests 与 CI 验证流水线。
---
@@ -62,8 +64,11 @@
- **预置八位汉传祖师大德**：涵盖唯识、中观、禅、天台、华严、净土、跨宗派七大核心宗派，开箱即用
- **经文溯源（Provenance）**：每位祖师附 CBETA ID、FoJin text ID，所有教义断言强制附经证引用
- **离线经文片段**：`sources/` 目录收录核心经典关键段落，FoJin 不可用时仍可离线引用
- **渐进式披露**：SKILL.md < 100 行（决策树 + Quick Ref），references/ 和 sources/ 按需加载，节省 70% context
- **自动化保真度测试**：每位祖师 `tests/fidelity.jsonl` 5 条 Q&A，验证引用和关键词覆盖
- **渐进式披露**：SKILL.md 以决策树 + Quick Ref 为主，`references/`、`sources/` 按需加载，Context 随查随取
- **HARD-GATE 铁律**：`/create-master` 与预置法师内置红线——无 CBETA 引证的教义断言不得写入、不得捏造经号、不得为虚构人物建角色
- **二阶段独立审查**：生成管线在写入前强制经过"教义准确性 → 风格一致性"两轮独立审查，FAIL 自动修复最多 2 轮
- **自动化保真度测试**：每位祖师 `tests/fidelity.jsonl` 5 条 Q&A，验证引用和关键词覆盖；CI 在每次推送时 dry-run 验证
- **多平台统一插件**：Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI 共用一份 `prebuilt/`，session-start hook 跨平台注入法师列表
- **NPX 一键安装**：`npx master-skill install zhiyi` 直接部署到 Claude Code
- **离线工具链**：`scripts/cite.py`（CBETA 引用查询）、`scripts/query.py`（离线语义检索）、`scripts/validate.py`（frontmatter linter）
- **FoJin 数据桥**：接入 [fojin.app](https://fojin.app) 的 503 个数据源、10K+ 文本、678K+ 语义向量和 31K 实体知识图谱
@@ -125,7 +130,7 @@ git clone https://github.com/xr843/Master-skill ~/Master-skill
### 使用预置法师
在支持 AgentSkills 的环境（Claude Code / Codex CLI / OpenClaw）中直接调用：
在支持 AgentSkills 的环境（Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI）中直接调用：
```
/xuanzang — 玄奘法师（法相唯识宗）
@@ -231,32 +236,45 @@ git clone https://github.com/xr843/Master-skill ~/Master-skill
用户请求
|
v
SKILL.md (AgentSkills 入口, <100行)
session-start hook ──> 自动注入法师列表（5 端统一）
|
v
SKILL.md (AgentSkills 入口：决策树 + Quick Ref)
|
+-- 预置法师 --> prebuilt/{slug}/
| +-- SKILL.md (决策树+Quick Ref)
| +-- meta.json
| +-- SKILL.md (决策树 + <HARD-GATE> 铁律)
| +-- meta.json (version / lineage / provenance)
| +-- references/ (按需加载)
| | +-- teaching.md
| | +-- voice.md
| +-- sources/ (离线经文片段)
| | +-- *.md (CBETA)
| | +-- *.md (CBETA 段落)
| +-- tests/
| +-- fidelity.jsonl
| +-- 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)
|
+-- 自定义生成
+-- prompts/ (信息录入+分析)
+-- tools/sutra_collector.py
| +---> FoJin API ---> 知识图谱 + 语义检索
+-- tools/master_builder.py (角色构建)
+-- tools/skill_writer.py (文件写入)
+-- 自定义生成 (/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 自动加载)
```
---
@@ -291,11 +309,35 @@ Master-skill 通过 `tools/fojin_bridge.py` 接入 FoJin API，实现：
---
## 常见问题
**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。
---
## 贡献指南
欢迎提交新的预置法师、修正文献来源错误、补充经文片段，或改进工具链。
新增祖师需遵循 v0.3 架构：`prebuilt/<name>/` 下包含 SKILL.md（<100行，含 provenance frontmatter）、references/、sources/、tests/fidelity.jsonl。提交前运行 `python3 scripts/validate.py --strict` 确保 0 errors。
新增祖师需遵循 v0.3 架构：`prebuilt/<name>/` 下包含 SKILL.md（含 provenance frontmatter 与决策树）、`references/teaching.md` 与 `references/voice.md`（按需加载）、`sources/*.md`（离线经文片段）、`tests/fidelity.jsonl`（5 条以上 Q&A 保真度样例）。提交前运行 `python3 scripts/validate.py --strict` 确保 0 errors，并让 CI 的保真度 dry-run 通过。
提交前请确认：文献来源可追溯至 CBETA，内容忠实于佛教经典文献，无宗派偏见。
README_EN.md
+97 -38
View File
@@ -38,7 +38,9 @@
---
> **v0.2 Update**: New `/compare-masters` command for multi-master comparison; per-master RAG queries with tradition-specific terminology for precise FoJin text_id citations.
> **v0.3 Update**: Full architecture rebuild — CBETA provenance in frontmatter, offline source passages (`sources/`), automated fidelity tests (`fidelity.jsonl`), one-command NPX installer, and offline toolchain (`cite.py` / `query.py`).
>
> **Post-v0.3 iterations**: `/create-master` pipeline now enforces a two-stage independent review (doctrinal accuracy → voice consistency), HARD-GATE rules (no CBETA citation → no write), multi-platform plugin support across Claude Code / Cursor / Codex / OpenCode / Gemini CLI, a session-start hook that auto-injects the master list, plus pressure tests and CI validation for all 8 prebuilt masters.
---
@@ -63,12 +65,17 @@ No installation required — try all pre-built masters directly in your browser:
## Features
- **8 pre-built Chinese Buddhist masters**: across Yogacara, Madhyamaka, Chan, Tiantai, Huayan, Pure Land, and cross-tradition — ready to use out of the box
- **Provenance enforcement**: Every master ships with CBETA IDs and FoJin text IDs in frontmatter; every doctrinal claim must carry a scriptural citation
- **Offline source passages**: `sources/` captures key passages from each master's core canon, so citations still work when FoJin is unreachable
- **Progressive disclosure**: SKILL.md is a decision tree + quick reference; `references/` and `sources/` are loaded on demand to keep context lean
- **HARD-GATE discipline**: Both `/create-master` and every prebuilt master embed hard rules — no unverified CBETA ID, no uncited doctrinal claim, no fictional personas
- **Two-stage independent review**: The generation pipeline forces a "doctrinal accuracy → voice consistency" review before write; FAIL triggers up to 2 rounds of automatic repair
- **Automated fidelity tests**: Each master's `tests/fidelity.jsonl` holds 5+ Q&A samples validating citations and keyword coverage; CI runs a dry-run on every push
- **Unified multi-platform plugin**: Claude Code, Cursor, Codex CLI, OpenCode, and Gemini CLI share one `prebuilt/` tree, with a session-start hook injecting the master list on every platform
- **NPX one-shot install**: `npx master-skill install zhiyi` drops skills straight into Claude Code
- **Offline toolchain**: `scripts/cite.py` (CBETA lookup), `scripts/query.py` (offline semantic search), `scripts/validate.py` (frontmatter linter)
- **FoJin data bridge**: Connected to [fojin.app](https://fojin.app) with 503 data sources, 10K+ texts, 678K+ semantic embeddings, and a 31K-entity knowledge graph
- **Runtime RAG retrieval**: Answers grounded in real Buddhist texts via FoJin semantic search, not just LLM training data
- **AgentSkills standard**: Compliant with the AgentSkills specification; can be invoked as a sub-skill by other agents
- **Dual-mode output**: Each master generates both `teaching.md` (doctrinal system) and `voice.md` (teaching style)
- **Incremental evolution**: Existing masters can be enhanced by appending new source texts via incremental merging
- **Version management**: Built-in versioning with timestamps, supporting rollback to any prior version
- **AgentSkills standard**: Compliant with [Anthropic Agent Skills](https://github.com/anthropics/skills) — progressive disclosure, decision trees, black-box script pattern
---
@@ -106,7 +113,7 @@ ln -sf "$(pwd)" ~/.claude/skills/create-master
### Use a Pre-built Master
In any AgentSkills-compatible environment (Claude Code / Codex CLI / OpenClaw):
In any AgentSkills-compatible environment (Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI):
```
/xuanzang — Master Xuanzang (Yogacara)
@@ -119,6 +126,24 @@ In any AgentSkills-compatible environment (Claude Code / Codex CLI / OpenClaw):
/xuyun — Master Xuyun (Chan, Five Houses)
```
### Compare Masters
Ask the same question to 2-3 masters in parallel and surface the differences between traditions:
```
# Auto-pick relevant masters
/compare-masters what is emptiness
# Manually pick masters (recommended for precise results)
/compare-masters how to read the Heart Sutra --masters xuanzang,huineng,zhiyi
# Natural-language triggers
compare Huineng and Yinguang on nianfo
how do Chan and Pure Land differ on practice
```
**Selection logic**: the command first tries to extract keywords from the question and match them against each master's core concepts; if nothing matches strongly, it falls back to topic mapping (nianfo / meditation / Yogacara-Madhyamaka / classification, etc.). **If the auto-pick feels off, use `--masters` to override.**
### Generate a Custom Master
```
@@ -193,37 +218,45 @@ Invoke: `/xuyun`
User request
|
v
SKILL.md (AgentSkills entry point)
session-start hook ──> auto-injects master list (5 platforms, unified)
|
+-- Pre-built masters ----------------> prebuilt/{slug}/
| +-- SKILL.md
| +-- teaching.md
| +-- voice.md
| +-- meta.json
v
SKILL.md (AgentSkills entry: decision tree + quick reference)
|
+-- Custom generation
|
+-- prompts/intake.md (information intake)
|
+-- tools/sutra_collector.py
| |
| +--> FoJin API ---> knowledge graph + semantic search + text
|
+-- prompts/sutra_analyzer.md (doctrinal analysis)
+-- prompts/voice_analyzer.md (style analysis)
+-- prompts/teaching_builder.md
+-- prompts/voice_builder.md
|
+-- tools/master_builder.py (persona construction)
+-- tools/skill_writer.py (file writing)
+-- tools/version_manager.py (version management)
|
v
masters/{slug}/
+-- SKILL.md
+-- teaching.md
+-- voice.md
+-- meta.json
+-- Pre-built masters --> prebuilt/{slug}/
| +-- SKILL.md (decision tree + <HARD-GATE>)
| +-- meta.json (version / lineage / provenance)
| +-- references/ (loaded on demand)
| | +-- teaching.md
| | +-- voice.md
| +-- sources/ (offline CBETA passages)
| | +-- *.md
| +-- tests/
| +-- fidelity.jsonl (CI dry-run samples)
|
+-- Offline toolchain
| +-- scripts/validate.py (frontmatter linter)
| +-- scripts/cite.py (CBETA lookup)
| +-- scripts/query.py (offline semantic search)
| +-- scripts/test-fidelity.py (fidelity runner)
| +-- scripts/validate-fidelity.py
| +-- bin/cli.mjs (NPX installer)
|
+-- Custom generation (/create-master, HARD-GATE enforced)
+-- Step 1-2 prompts/intake.md → tools/sutra_collector.py
| └─> FoJin API (KG + semantic search + text)
+-- Step 3 prompts/{sutra,voice}_analyzer.md → two-stage analysis
+-- Step 3.5 two-stage independent review ──┬─ prompts/doctrine_reviewer.md
| └─ prompts/voice_reviewer.md
+-- Step 4-5 tools/master_builder.py → tools/skill_writer.py
└─> tools/verify_sources.py (final pre-write check)
Unified multi-platform manifests:
.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 (referenced from opencode.json)
gemini-extension.json → Gemini CLI (auto-loaded with GEMINI.md)
```
---
@@ -262,11 +295,37 @@ All citations include traceable FoJin links to ensure transparency of sources.
---
## Troubleshooting
**Q: Does it still work when the FoJin API is unreachable?**
Yes. Each prebuilt master ships with `prebuilt/<name>/sources/` — key passages from that master's core canon, stored offline. When FoJin is down, the master degrades to offline mode and declares "currently running on offline passages" in the reply. The `/create-master` pipeline asks the user to switch to manual-input mode when the API fails, so you can paste source text and continue.
**Q: What does a valid CBETA citation look like, and how is it verified?**
Every CBETA citation must carry a `Txxn####` identifier (for example, the Lotus Sutra is `T9n262`). `scripts/validate.py` lints the frontmatter `sources` block; `tools/verify_sources.py` checks every FoJin `text_id` against the live API before writing. Broken links are downgraded to FoJin search URLs — no dead references make it into the final file.
**Q: `npx master-skill install` fails with ENOTEMPTY or a permission error — what now?**
Clean up any leftover `~/.claude/skills/master-<name>/` directories before retrying. For npm-cache weirdness, run `npm cache clean --force` and rerun NPX. Windows users should execute from Git Bash or WSL to avoid cmd.exe path-escaping issues.
**Q: The generated master says things that don't match the historical record — how do I correct it?**
Just tell the master in-chat: "he wouldn't phrase it like that" or "he should sound more stern." The `/create-master` correction mode classifies the fix (doctrinal → appended to `teaching.md`; stylistic → appended to `voice.md`), writes it as a `## Correction` block with timestamp, and bumps the patch version. Correction blocks take priority over analysis-generated content at runtime.
**Q: How do I contribute a new prebuilt master?**
See "Contributing" below. The short version: follow the v0.3 layout under `prebuilt/<name>/`, pass `scripts/validate.py --strict` with zero errors, ship at least 5 fidelity Q&A samples in `tests/fidelity.jsonl`, then open a PR.
---
## Contributing
Contributions are welcome: new pre-built masters (follow the format in `prebuilt/`), corrections to source attributions, or improvements to the toolchain.
Contributions are welcome: new prebuilt masters, corrections to source attributions, offline passage additions, or toolchain improvements.
Before submitting, please verify: sources are traceable, content is faithful to historical documents, and no sectarian bias is introduced.
New masters must follow the v0.3 layout: `prebuilt/<name>/` containing SKILL.md (with provenance frontmatter and a decision tree), `references/teaching.md` and `references/voice.md` (loaded on demand), `sources/*.md` (offline CBETA passages), and `tests/fidelity.jsonl` (5+ Q&A fidelity samples). Run `python3 scripts/validate.py --strict` for zero errors, and make sure the CI fidelity dry-run passes before opening a PR.
Before submitting, verify that sources trace back to CBETA, content is faithful to historical documents, and no sectarian bias is introduced.
---