mirror of
https://github.com/xr843/Master-skill.git
synced 2026-05-10 05:16:25 +00:00
chore(community): add contributing infra, issue/PR templates, npm publish workflow
Tier A infrastructure to convert 204★ momentum into durable community and distribution. Pairs with PR #12 (ETHICS / CHANGELOG / fidelity smoke) — merge PR #12 first, then this. **Community docs** - `CONTRIBUTING.md` — three-tier contribution flow (code vs docs vs master content), with a detailed §3 "how to contribute a new master" covering copyright tier self-check, `/create-master` vs manual path, SKILL.md frontmatter spec, voice.md Layer 0-3, fidelity.jsonl authoring. - `CODE_OF_CONDUCT.md` — Contributor Covenant 2.1 + Buddhist-project-specific rules (no doctrinal supremacy, no using the repo as a dharma platform, no impersonating clergy, no apocryphal scripture citations). - `SECURITY.md` — threat model (prompt injection, supply chain, secret leak, installer safety, religious-boundary adversarial input), SLA table, GH Security Advisory as primary channel. **Issue / PR templates** - `bug_report.yml` — area selector, master selector, repro template. - `feature_request.yml` — non-master enhancement requests. - `new_master.yml` — **MUST precede any new-master PR**; forces tier A/B/D self-judgment and citation planning before sunk cost. - `boundary_violation.yml` — P0 template for ETHICS.md §3 violations. - `config.yml` — directs users to Discussions for chatter, Security Advisory for vulnerabilities, email for urgent takedowns. - `PULL_REQUEST_TEMPLATE.md` — change-type checkboxes, self-check list, new- master fields, local-test block. **npm publish** - `.github/workflows/npm-publish.yml` — release-tag + workflow_dispatch, with dry-run mode, tag-version match check, `npm publish --provenance`. First-time publish needs NPM_TOKEN secret (user action). - `package.json` hardening: - `engines.node: >=18` - scripts: `validate`, `validate:fidelity`, `test`, `test:smoke`, `prepack` - `publishConfig` (public, npm registry) - `files` list expanded to include platform manifests + governance docs - richer `keywords`, `author`, `bugs`, `homepage` fields - expanded description mentions all 8 masters for search discoverability **README** - 贡献指南 section rewritten to point at CONTRIBUTING.md + Discussions + four issue templates, with "先开 New Master issue 征询" gate spelled out. Discussions were enabled on the repo alongside this commit via `gh api`, so the links in README/templates resolve immediately on merge. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
xianren
+245
@@ -0,0 +1,245 @@
|
||||
# Contributing to Master-skill
|
||||
|
||||
欢迎贡献！本项目分三类改动，每类流程不同——**请先判断你的改动属于哪一类**，再按对应流程走。
|
||||
|
||||
> 📜 贡献前**必读**：[`ETHICS.md`](ETHICS.md) — AI 透明度、版权 Tier、教界边界、内容授权。违反伦理条款的 PR 不会 review。
|
||||
|
||||
---
|
||||
|
||||
## 三类改动
|
||||
|
||||
### ① 代码 / CI / 工具链
|
||||
|
||||
`scripts/**`, `tools/**`, `bin/**`, `hooks/**`, `.github/**`, `tests/`（非 fidelity）
|
||||
|
||||
流程：**普通 GitHub PR**。满足 Python 3.9+、现有测试通过、`python scripts/validate.py --strict` 绿色即可。
|
||||
|
||||
### ② 文档 / README / 脚本注释 / 翻译
|
||||
|
||||
`README.md`, `README_EN.md`, `docs/**`, `CHANGELOG.md`, 其它非 `prebuilt/**` 的 markdown
|
||||
|
||||
流程：**普通 PR**。不需要跑 fidelity 测试，CI 中的 validate / smoke job 会跳过（除非改了其它触发路径）。
|
||||
|
||||
### ③ 贡献 / 修改法师内容（⚠️ 最严，必读）
|
||||
|
||||
`prebuilt/**`, `prompts/**`
|
||||
|
||||
涉及：
|
||||
|
||||
- 新增一位法师
|
||||
- 修改已有法师的 `teaching.md` / `voice.md` / `sources/`
|
||||
- 修改 fidelity 测试用例
|
||||
|
||||
流程：见下方 [§3 贡献一位新法师](#3-贡献一位新法师)。
|
||||
|
||||
---
|
||||
|
||||
## 开发环境
|
||||
|
||||
```bash
|
||||
git clone https://github.com/xr843/Master-skill
|
||||
cd Master-skill
|
||||
|
||||
# Python（用于 validate / fidelity / verify-links）
|
||||
python3 -m venv .venv && source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
pip install anthropic # 仅 fidelity 实跑需要
|
||||
|
||||
# Node（用于 npx installer）
|
||||
# 需要 Node.js >= 18
|
||||
npm install -g . # 可选，本地测试 CLI
|
||||
```
|
||||
|
||||
**基本健康检查：**
|
||||
|
||||
```bash
|
||||
# Lint SKILL.md frontmatter — 每位法师必须通过
|
||||
python scripts/validate.py --strict
|
||||
|
||||
# Fidelity 结构（不调 API）
|
||||
python scripts/validate-fidelity.py
|
||||
|
||||
# Fidelity 干跑（显示测试用例，不调 API）
|
||||
python scripts/test-fidelity.py --all --dry-run
|
||||
|
||||
# Fidelity 实跑（需要 ANTHROPIC_API_KEY，一次 ≈ $0.05-0.10）
|
||||
ANTHROPIC_API_KEY=sk-... python scripts/test-fidelity.py --master zhiyi --max-tests 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## § 1 分支与提交约定
|
||||
|
||||
- **分支命名**：`feat/<short>`、`fix/<short>`、`docs/<short>`、`chore/<short>`、`master/<slug>`
|
||||
- **Commit 格式**：[Conventional Commits](https://www.conventionalcommits.org/)（`feat:` / `fix:` / `docs:` / `chore:` / `refactor:` / `test:` + 可选 scope）
|
||||
- **Commit message 语言**：代码/基础设施类改动用英文，佛教内容类改动中英文均可，但 PR description 需要有中文摘要（方便教内读者审阅）
|
||||
|
||||
---
|
||||
|
||||
## § 2 PR 评审清单
|
||||
|
||||
提交 PR 前自检：
|
||||
|
||||
- [ ] CI 绿色（validate / fidelity-smoke 必过；forks 无 API key 会 skip 并 warning，OK）
|
||||
- [ ] CHANGELOG.md 的 `[Unreleased]` 章节已更新（除非是纯 typo）
|
||||
- [ ] 涉及 `prebuilt/**` 的改动 → 已 review ETHICS.md §2（版权 Tier）、§3（教界边界）
|
||||
- [ ] PR description 说明**做了什么 + 为什么**，而非只列改动文件
|
||||
|
||||
---
|
||||
|
||||
## § 3 贡献一位新法师
|
||||
|
||||
### 3.1 前置检查（必看 [`ETHICS.md`](ETHICS.md)）
|
||||
|
||||
**这位法师可以收录吗？**
|
||||
|
||||
| 情形 | 判断 |
|
||||
|-----|------|
|
||||
| 生卒明确，圆寂超过 50 年（CN/TW）或 70 年（大多数其它辖区） | ✅ Tier A，可直接 PR |
|
||||
| 近现代法师，亲授弟子在世 / 所属寺院仍运营 | ⚠️ Tier B，PR 必须附 `prebuilt/{slug}/LICENSE.md` 授权证明 |
|
||||
| 在世法师 | ❌ Tier C，不接受 |
|
||||
| 主流学界对身份 / 著作有争议 | ❌ Tier C，不接受 |
|
||||
| 汉传以外（南传 / 藏传 / 日莲 / 天台日宗等）| ⏳ 当前版本仅汉传，未来独立分支规划中，不接受 |
|
||||
|
||||
**想收录但不确定？** 先开一个 [new_master Issue](https://github.com/xr843/Master-skill/issues/new?template=new_master.yml) 征询意见，**不要先写完再提 PR**——已经投入精力再被拒成本太高。
|
||||
|
||||
### 3.2 选项 A：交给 `/create-master` 生成（推荐）
|
||||
|
||||
```bash
|
||||
# 在 Claude Code / Cursor 等 AgentSkills 环境
|
||||
/create-master 某某法师
|
||||
```
|
||||
|
||||
生成管线会：
|
||||
|
||||
1. **intake** — 3 问收集信息（传承、核心教义、可用文献）
|
||||
2. **collect** — 从 FoJin 采集该法师的 CBETA 文本
|
||||
3. **analyze** — `sutra_analyzer` + `voice_analyzer` 并行分析
|
||||
4. **review** — 二阶段独立审查：教义准确性 → 风格一致性
|
||||
5. **write** — 生成 `prebuilt/<slug>/` 目录结构
|
||||
6. **validate** — 自动跑 `validate.py` + `validate-fidelity.py`
|
||||
|
||||
然后你手动：
|
||||
|
||||
- Review 生成结果，补充 `references/teaching.md`、`voice.md` 的细节
|
||||
- 起草 5 条 `tests/fidelity.jsonl`（1 basic + 2 intermediate + 2 advanced）
|
||||
- 跑一次 `test-fidelity.py --master <slug>` 确认 ≥ 4/5 通过
|
||||
- 提 PR
|
||||
|
||||
### 3.3 选项 B：手工编写
|
||||
|
||||
参考现有法师 `prebuilt/yinguang/` 的完整结构：
|
||||
|
||||
```
|
||||
prebuilt/<slug>/
|
||||
├── SKILL.md # 必须。frontmatter 见下
|
||||
├── meta.json # 必须。search_scope + keywords
|
||||
├── references/
|
||||
│ ├── teaching.md # 必须。教义体系，每条断言附 CBETA 引证
|
||||
│ └── voice.md # 必须。Layer 0/1/2/3 四层表达风格
|
||||
├── sources/
|
||||
│ ├── INDEX.md # 必须。本目录导览
|
||||
│ └── *.md # ≥ 2 篇 CBETA 核心段落摘录
|
||||
└── tests/
|
||||
└── fidelity.jsonl # 必须。5 条 Q&A 测试用例
|
||||
```
|
||||
|
||||
**SKILL.md frontmatter 必填字段：**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <slug> # 小写英文或拼音，作为 `/命令` 触发词
|
||||
description: Use when user asks about ..., triggers include ...
|
||||
version: 0.1.0
|
||||
license: MIT
|
||||
lineage: <宗派>
|
||||
dates: 生年-卒年
|
||||
sources:
|
||||
- title: <经典名称>
|
||||
cbeta_id: <T 或 X + 数字>
|
||||
fojin_text_id: <FoJin 内部 text_id>
|
||||
- ... # 至少 3 部经
|
||||
citation_format: "【《{title}》卷{juan}，{cbeta_id}】"
|
||||
verified_by: <你的 GitHub handle>
|
||||
verified_at: <YYYY-MM-DD>
|
||||
---
|
||||
```
|
||||
|
||||
**HARD-GATE 铁律（写入任何 `teaching.md` 前请自检）：**
|
||||
|
||||
1. 每一条教义断言必须附一个**真实**的 CBETA 经号
|
||||
2. 不得捏造经号（`scripts/validate.py` 会对照 FoJin 反查）
|
||||
3. 不得为虚构 / 神话 / 未有史实记载的人物建角色
|
||||
4. 不得大段抄录仍在版权期内的现代白话译本或学术校注
|
||||
|
||||
### 3.4 Voice.md 四层结构
|
||||
|
||||
见 `prebuilt/yinguang/references/voice.md` 作为参照。重点：
|
||||
|
||||
- **Layer 0 — 硬规则**：[`ETHICS.md` §3](ETHICS.md) 的禁止行为必须原文复制到此
|
||||
- **Layer 1 — 身份**：生卒、传承、核心立场
|
||||
- **Layer 2 — 表达风格**：常用比喻、开场方式、称呼
|
||||
- **Layer 3 — 教学方法**：循序渐进的路径、遇困惑时的处理
|
||||
|
||||
### 3.5 Fidelity 测试用例怎么写
|
||||
|
||||
`tests/fidelity.jsonl` 每行一个 JSON，字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "用户会问的典型问题",
|
||||
"must_cite": ["T48n2008", "某经号"],
|
||||
"must_mention": ["核心术语1", "核心术语2"],
|
||||
"must_not_contain_first_turn": ["学生啊", "师兄"],
|
||||
"difficulty": "basic|intermediate|advanced"
|
||||
}
|
||||
```
|
||||
|
||||
**5 条分布建议：**
|
||||
|
||||
- 1 条 `basic` — 宗派入门问题（smoke 会优先跑这条）
|
||||
- 2 条 `intermediate` — 核心教义（如 "三性" / "信愿行"）
|
||||
- 1 条 `advanced` — 跨宗派对话 / 批判性问题
|
||||
- 1 条 boundary 测试 — 试探 "给我授戒 / 印证我开悟了吗" 一类，must_not_contain 检查 AI 是否正确拒绝
|
||||
|
||||
### 3.6 Review 过程
|
||||
|
||||
PR 提交后：
|
||||
|
||||
1. CI 自动跑 validate + fidelity-smoke（抽本 PR 修改的法师做 smoke）
|
||||
2. 维护者 review 教义准确性 + 风格一致性 + 版权 Tier 判断
|
||||
3. 如有佛学学者 / 教内法师愿意 review，欢迎在 PR 评论 tag 维护者协调
|
||||
4. Review 周期：7-14 天（含教内邀请意见）
|
||||
|
||||
---
|
||||
|
||||
## § 4 修改已有法师
|
||||
|
||||
- 小修（typo、措辞）：直接 PR
|
||||
- 大修（新增教义章节、修改 Layer 1-3 风格）：先开 issue 讨论
|
||||
- 修改 fidelity 测试用例：**PR description 必须说明新旧用例的差异以及为何新用例更能体现该法师风格**——不要为了让测试通过而放宽标准
|
||||
|
||||
---
|
||||
|
||||
## § 5 行为准则
|
||||
|
||||
见 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。
|
||||
|
||||
本项目涉及佛教内容，请在讨论中：
|
||||
|
||||
- 不评判宗派高下
|
||||
- 不借项目传播个人修行见解
|
||||
- 不对其他贡献者做教学式 / 居高临下的发言
|
||||
- 教理争议以学界主流共识 + CBETA 原文为准，而非个人修学经验
|
||||
|
||||
---
|
||||
|
||||
## 问题？
|
||||
|
||||
- 技术问题 → [Bug Report](https://github.com/xr843/Master-skill/issues/new?template=bug_report.yml)
|
||||
- 新法师建议 → [New Master Proposal](https://github.com/xr843/Master-skill/issues/new?template=new_master.yml)
|
||||
- 教界边界疑虑 → [Boundary Violation](https://github.com/xr843/Master-skill/issues/new?template=boundary_violation.yml)（P0，优先处理）
|
||||
- 一般讨论 → [GitHub Discussions](https://github.com/xr843/Master-skill/discussions)
|
||||
- 紧急版权下架 → xianren843@protonmail.com（48 小时回复）
|
||||
|
||||
感谢你愿意为汉传佛教数字人文贡献一份力。合十。
|
||||
Reference in New Issue
Block a user