From 4eb92ab0487e367280d629e2a156d19d18c6f6ad Mon Sep 17 00:00:00 2001 From: xianren Date: Fri, 10 Apr 2026 14:27:32 +0800 Subject: [PATCH] docs(readme): sync README to v0.3 reality, bring EN in lockstep with CN MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md and README_EN.md had drifted from the code. The Chinese README still claimed "SKILL.md < 100 行" (actual: 386 lines at repo root, 124–159 lines in prebuilt/*), and the English README still advertised the v0.2 release — completely missing NPX install, provenance, fidelity tests, HARD-GATE, two-stage review, and multi-platform plugins. Changes in both languages: - Remove the "SKILL.md < 100 lines" claim (it was never true of the rebuilt v0.3 files and made the whole doc feel aspirational) - Add v0.3 post-iteration banner covering two-stage review, HARD-GATE, multi-platform plugin support, session-start hook, pressure tests, and CI validation - Expand Features list with HARD-GATE, two-stage review, unified multi-platform plugin bullets - Rewrite the architecture diagram so it shows the session-start hook, HARD-GATE placement, two-stage review step (Step 3.5), and the five-platform manifest layout - Add a Troubleshooting / 常见问题 section covering: FoJin API unreachability and offline fallback, CBETA citation format and verification, `npx master-skill install` failure recovery, correction-mode for historical accuracy, and how to contribute a new prebuilt master - Update Contributing to reference the actual v0.3 layout (references/, sources/, tests/fidelity.jsonl) and CI fidelity dry-run gate Chinese-specific: - Fix the "OpenClaw" typo in the usage environment list (Claude Code / Codex CLI / OpenClaw → Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI) English-specific (larger catch-up): - Replace the stale "v0.2 Update" banner with the v0.3 banner - Replace the v0.2 Features list (Dual-mode output, Incremental evolution, Version management) with the current v0.3 feature set - Add the missing "Compare Masters" section (the English README never documented /compare-masters at all) - Rewrite the architecture diagram — it still showed teaching.md and voice.md at the top level of prebuilt/{slug}/ and referenced tools/version_manager.py, which is not the v0.3 layout - Fix the same "OpenClaw" typo No behavioral changes — docs only. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 74 ++++++++++++++++++++++------ README_EN.md | 135 ++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 155 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 473ccf6..9c7abe0 100644 --- a/README.md +++ b/README.md @@ -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 (决策树 + 铁律) + | +-- 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//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-/` 残留目录再重试。如果是 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//`、跑通 `scripts/validate.py --strict`、补齐 `tests/fidelity.jsonl` 的 5 条以上样例，然后提 PR。 + +--- + ## 贡献指南 欢迎提交新的预置法师、修正文献来源错误、补充经文片段，或改进工具链。 -新增祖师需遵循 v0.3 架构：`prebuilt//` 下包含 SKILL.md（<100行，含 provenance frontmatter）、references/、sources/、tests/fidelity.jsonl。提交前运行 `python3 scripts/validate.py --strict` 确保 0 errors。 +新增祖师需遵循 v0.3 架构：`prebuilt//` 下包含 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，内容忠实于佛教经典文献，无宗派偏见。 diff --git a/README_EN.md b/README_EN.md index 5a38209..a5af328 100644 --- a/README_EN.md +++ b/README_EN.md @@ -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 + ) + | +-- 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//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-/` 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//`, 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//` 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. ---