NFraw · Oct 19, 2026 · Oct 19, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -0,0 +1,20 @@
+name: build
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: build-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    uses: NFraw/Craft-Cards/.github/workflows/build-reusable.yml@main
+    with:
+      mc_target: "1.21.1"
+      loader: neoforge
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,9 +1,40 @@
 # 贡献指南
 
-感谢关注 Crafty Cards。本分支固定为 neoforge / Minecraft 1.21.1；构建入口与产物见 [README](README.md)。修改共用代码或版本覆盖时，请验证这个目标。
+感谢关注 Crafty Cards。本分支固定为 **neoforge / Minecraft 1.21.1**，构建入口与产物见 [README](README.md)。
+
+## 提交 PR 前必读
+
+- **PR 的 base 必须是本分支 `neoforge-mc1.21.1`，不要选 `main`。** 本分支是从 main 裁剪出的单版本快照，提到 `main` 会显示大量文件被删除。
+- 一个 PR 只做一件事；合并用 **Squash and merge**，一个 PR 对应一个提交，方便 `cherry-pick` 到其它版本分支。
+- 不要把“改代码”和“改本分支专属文件”（`TARGET.md`、`build-target.ps1`、`common/gradle/minecraft-target.gradle`、`README.md`、本文件）混在同一个提交里。
+- 版本分支之间只 cherry-pick，不要互相 merge，也不要 merge 回 `main`。
+- 不提交 `build/`、`run*/`、`.ogg`、本地配置或 IDE 文件。
+- **Issue/PR 模板只存放在 `main`**，本分支不复制；CI 由本分支的 `.github/workflows/build.yml` 调用 main 的可复用 workflow。
+
+## 构建与自测
+
+Windows：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\build-target.ps1
+```
+
+Linux / macOS 或任意平台：
+
+```bash
+./gradlew build -PmcTarget=1.21.1
+```
+
+提交前至少跑一次 `build`（包含单测）；能跑桌面时再按 [验收脚本](docs/自动化验收.md) 完成一轮真实客户端对局。
+
+## 报告问题
 
 提交问题时说明 Minecraft、加载器、模组版本和重现步骤；画面问题附 GUI 缩放、窗口/全屏分辨率与截图，音频问题附包 id 和 `latest.log` 相关行。上传前删去私人路径、账号、服务器地址和世界敏感数据。安全漏洞请按 [安全说明](SECURITY.md) 私密报告。
 
-代码修改尽量先在 `common/` 解决共用行为，仅把注册、网络/输入/渲染钩子与版本 API 差异放进加载器或 `versions/`。纯逻辑错误补有意义的单测；客户端渲染问题提供实际截图；涉及会话关闭、物品结算或私有手牌时验证服务端权威和多人路径。至少运行受影响目标的 `build`/`test`，可运行桌面时再用 [验收脚本](docs/自动化验收.md) 完成真实客户端对局。不要把测试通过写成“所有版本都无问题”。
+## 代码约定
+
+代码修改尽量先在 `common/` 解决共用行为，仅把注册、网络/输入/渲染钩子与版本 API 差异放进加载器或 `versions/`。纯逻辑错误补有意义的单测；客户端渲染问题提供实际截图；涉及会话关闭、物品结算或私有手牌时验证服务端权威和多人路径。不要把测试通过写成“所有版本都无问题”。
+
+## 更多
 
-目前没有公开远端与正式提交流程；本文件为发布前待审稿。接受外部贡献的具体渠道将在仓库公开时确定。
+仓库分工、文件归属、跨版本同步和新增分支步骤见 main 的 [仓库结构与维护职责](https://github.com/NFraw/Craft-Cards/blob/main/docs/open-source/REPO-STRUCTURE.md)；全局贡献规则见 [main 的 CONTRIBUTING](https://github.com/NFraw/Craft-Cards/blob/main/CONTRIBUTING.md)。
diff --git a/README.en.md b/README.en.md
@@ -13,14 +13,20 @@ Crafty Cards brings three-player multiplayer Dou Dizhu into Minecraft. See [CRED
 | Minecraft | 1.21.1 |
 | Loader dependency | NeoForge 21.1.236 |
 | Java | 21 |
-| Installable JAR | `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-1.0.0.jar` |
+| Installable JAR | `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-<mod_version>.jar` (currently `1.0.0`) |
 
-After downloading this branch, run from the repository root in Windows PowerShell:
+After downloading this branch, run from the repository root. On Windows PowerShell:
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\build-target.ps1
 ```
 
+On Linux, macOS, or any platform:
+
+```bash
+./gradlew build -PmcTarget=1.21.1
+```
+
 This builds and tests only **neoforge / Minecraft 1.21.1** and verifies the release JAR name. A `-sources.jar`, when present, is a source archive for the same target, not an installable mod. Gradle rejects a different `-PmcTarget`. See the [branch version guide](versions/README.md) and [testing scope](docs/open-source/TESTING.md).
 
 ## Start a Dou Dizhu game
@@ -78,12 +84,16 @@ Add source files and assign keys and weights, then open **Review Configuration**
 
 ## Build and verify
 
-Run `powershell -ExecutionPolicy Bypass -File .\build-target.ps1` from the repository root. The only installable output is `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-1.0.0.jar`. Shared sources are in `common/`; loader sources are in `./`; required version overlays are in `versions/`.
+Run `powershell -ExecutionPolicy Bypass -File .\build-target.ps1` (or `./gradlew build -PmcTarget=1.21.1`) from the repository root. The only installable output is `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-<mod_version>.jar`. Shared sources are in `common/`; loader sources are in `./`; required version overlays are in `versions/`.
 
 The [developer guide](docs/open-source/DEVELOPMENT.md) covers this branch's source layout. The [testing scope](docs/open-source/TESTING.md) distinguishes build verification from client and audio checks.
 
+### Version branch and contributions
+
+This branch is an independent product line for **neoforge / Minecraft 1.21.1**. Open pull requests against `neoforge-mc1.21.1`, **not `main`** — this branch is a trimmed snapshot, so a PR based on `main` shows many deleted files. Keep one logical change per PR (merged with squash) so it can be cherry-picked to other version branches. Never merge version branches into each other or back into `main`. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [release process](docs/open-source/RELEASE.md).
+
 ## Artwork, credits, and license
 
 Some card faces, backs, chips, and block textures were inherited from PlayingCards; 69 PNGs in this repository match the local upstream reference byte-for-byte. The current mod icon also combines inherited artwork. Read [CREDITS.md](CREDITS.md) and the [asset review](docs/open-source/ASSETS.md) before publishing code, a jar, an icon, or the default sound pack. The repository's [GPL-3.0-only license](LICENSE) does not by itself resolve upstream artwork or audio redistribution rights.
 
-The [publication materials](docs/open-source/README.md) are still a local review draft. Nothing has been uploaded to GitHub yet.
+The [publication materials](docs/open-source/README.md) describe the process; branch, tag, and release state live on GitHub.
diff --git a/README.md b/README.md
@@ -13,14 +13,20 @@ Crafty Cards 在 Minecraft 世界里提供三人联机斗地主。项目来源
 | Minecraft | 1.21.1 |
 | 加载器依赖 | NeoForge 21.1.236 |
 | Java | 21 |
-| 安装用 JAR | `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-1.0.0.jar` |
+| 安装用 JAR | `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-<mod_version>.jar`（当前 `1.0.0`） |
 
-下载或解压本分支源码后，在仓库根目录使用 Windows PowerShell：
+下载或解压本分支源码后，在仓库根目录构建。Windows PowerShell：
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\build-target.ps1
 ```
 
+Linux / macOS 或任意平台：
+
+```bash
+./gradlew build -PmcTarget=1.21.1
+```
+
 该命令只构建并测试 **neoforge / Minecraft 1.21.1**，同时核对安装用 JAR 的文件名。若同时看到 `-sources.jar`，那是同一目标的源码包，不能放入 `mods`。尝试传入其他 `-PmcTarget` 会在 Gradle 配置阶段报错。版本覆盖与路径说明见 [本分支版本说明](versions/README.md)；测试范围见 [验证与已知边界](docs/open-source/TESTING.md)。
 
 ## 快速上手
@@ -169,10 +175,21 @@ python tools/soundpack_maker.py --cli <音频目录> --name <显示名>
 
 ## 开发
 
-本分支的构建入口为 `powershell -ExecutionPolicy Bypass -File .\build-target.ps1`，产物为 `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-1.0.0.jar`。测试已包含在 `build` 中。共享逻辑位于 `common/`，版本覆盖位于 `versions/`，加载器实现位于 `./`。
+本分支的构建入口为 `powershell -ExecutionPolicy Bypass -File .\build-target.ps1`（或 `./gradlew build -PmcTarget=1.21.1`），产物为 `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-<mod_version>.jar`。测试已包含在 `build` 中。共享逻辑位于 `common/`，版本覆盖（如有）位于 `versions/`，加载器实现位于 `./`。
 
 架构与实现细节见 [AGENTS.md](AGENTS.md)，功能说明见 [docs/斗地主玩法与实现介绍.md](docs/斗地主玩法与实现介绍.md)，测试范围与证据见 [验证与已知边界](docs/open-source/TESTING.md)。
 
+## 参与贡献
+
+本分支是一个**独立的版本产品线**，只接受针对 neoforge / Minecraft 1.21.1 的改动：
+
+- **PR 的 base 必须是 `neoforge-mc1.21.1`，不要提到 `main`**——本分支是从主线裁剪出的快照，提到 `main` 会显示大量文件被删除。
+- 一个 PR 只做一件事，合并时用 Squash，方便 `cherry-pick` 到其它版本分支。
+- 版本分支之间只 cherry-pick，不互相 merge，也不 merge 回 `main`。
+- Issue/PR 模板由 `main` 统一维护（GitHub 只读默认分支）；本分支只保留一个调用 main 可复用 CI 的 `.github/workflows/build.yml`。
+
+完整规则与构建方式见 [CONTRIBUTING.md](CONTRIBUTING.md)，发布与跨版本同步规则见 [版本分支与发布流程](docs/open-source/RELEASE.md)；仓库分工与文件归属见 main 的 [仓库结构与维护职责](https://github.com/NFraw/Craft-Cards/blob/main/docs/open-source/REPO-STRUCTURE.md)。
+
 ## 素材声明
 
 部分卡牌和筹码资源源自 PlayingCards；项目来源与致谢见 [CREDITS.md](CREDITS.md)。

diff --git a/TARGET.md b/TARGET.md
@@ -7,6 +7,6 @@ This branch contains the neoforge source snapshot for Minecraft 1.21.1. It keeps
 | Minecraft | 1.21.1 |
 | Loader dependency | NeoForge 21.1.236 |
 | Java | 21 |
-| Release JAR | `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-1.0.0.jar` |
+| Release JAR | `build/mc-1.21.1/libs/crafty_cards-neoforge-mc1.21.1-<mod_version>.jar` |
 
 From a fresh download on Windows, run `powershell -ExecutionPolicy Bypass -File .\build-target.ps1` at the repository root. The script builds and tests only this target, then checks the release JAR filename. A `-sources.jar` file, when produced, is source code and is not a mod to install. A different `-PmcTarget` is rejected during Gradle configuration.
diff --git a/docs/open-source/RELEASE.md b/docs/open-source/RELEASE.md
@@ -1,25 +1,32 @@
 # 版本分支与发布流程
 
-Crafty Cards 1.0.0 发布包提供三人联机斗地主。发布说明与版本标签以该版实际功能和逐目标验收记录为准。
+本分支固定为 **neoforge / Minecraft 1.21.1**。发布说明与版本标签以该版实际功能和验收记录为准。
 
-## 单源与目标分支
+## 分支模型
 
-当前仓库以一套公共源码覆盖多个目标，构建时用 `-PmcTarget=<Minecraft版本>` 选版本，工程目录选加载器。为方便逐目标开发与审查，采用 `<加载器>-mc<版本>` 命名本地开发分支，例如 `neoforge-mc1.21.1`。完整清单由 [分支脚本](../../tools/prepare-version-branches.ps1) 从 `common/gradle/minecraft-target.gradle` 的目标表与 `versions/targets.json` 生成；Forge 1.21.2 不创建分支。
-
-分支初建于同一基础提交，**名称本身不是独立通过测试的证据**，也不会在分支里复制整套源码。后续某版本独有的修复进该目标分支并回合并至共享主线/适配层；公共逻辑先在集成分支验证再分发。分支默认不改变 `gradle.properties`，因此在某分支构建时仍须显式传 `-PmcTarget`。每个分支最终应记录目标 jar 的 SHA-256、构建日志、单测、客户端验收与人工检查结果。
+- `main` 是集成分支，保留全部加载器与全部 Minecraft 版本的源码。
+- 每个发布目标一个分支，命名为 `<加载器>-mc<版本>`。分支由主线的 [分支脚本](../../tools/prepare-version-branches.ps1) 建出后，把该目标用不到的文件裁剪掉，形成**独立可构建的快照**（本分支即如此）。
+- 分支之间是独立产品线，各自维护自己的 `mod_version`、构建产物和发布 tag。
+- **同步规则：只 cherry-pick，不 merge。** 公共修复从 `main` cherry-pick 到需要的版本分支；版本专属修复在分支上提交后，用 `git cherry-pick -x <提交>` 搬回 `main` 或其它分支。
+- **不要把版本分支 merge 进 `main`，也不要把 `main` merge 进版本分支。** 版本分支裁剪掉的文件会被 git 理解为“要删除”，一次 merge 就会删掉 `fabric/`、`forge/` 和 `versions/` 下的适配层；两边都改过的 `README.md` 还会冲突。
+- 为了让 cherry-pick 干净：一个提交只做一件事；不要把“改代码”和“改本分支专属文件”（`TARGET.md`、`build-target.ps1`、`common/gradle/minecraft-target.gradle`、`README.md`）混在同一个提交里。
 
 ## 发版步骤
 
-1. 冻结待发布源码，完成 [开源资料审阅](README.md) 与素材授权核对；选择默认分支及实际远端仓库地址。
-2. 对要发布的每个组合从对应提交构建，确认 jar 中不含开发验收类或 `.ogg`，元数据与目标 Minecraft/加载器一致。
-3. 运行公共单测、NeoForge 1.21.1 GameTest、逐组合三客户端验收；人工看图听音并记录差异和已知限制。
-4. 生成每个 jar 的 SHA-256，保留构建与验收的原始证据；从干净安装环境再测试正式 jar。
-5. 只有作者审阅通过并提供 GitHub 地址后，配置 remote、推送所批准的分支、创建对应版本标签与 Release。发布说明列出支持组合、依赖、验证级别、已知限制和校验值。
+1. 冻结待发布源码，完成 [开源资料审阅](README.md) 与素材授权核对。
+2. 在本分支修改 `gradle.properties` 的 `mod_version` 并提交。每个分支独立递增，不必与其它版本对齐。
+3. 构建并验证：Windows 跑 `powershell -ExecutionPolicy Bypass -File .\build-target.ps1`；其它平台跑 `./gradlew build -PmcTarget=1.21.1`。确认 jar 中不含 GameTest 类或 `.ogg`，`META-INF/neoforge.mods.toml` 的 Minecraft / NeoForge 版本区间正确。
+4. 运行单测与 `runGameTestServer`；有条件再跑一轮真实客户端验收，人工看图听音并记录差异和已知限制。
+5. 生成 jar 的 SHA-256，保留构建日志与验收证据。
+6. 打 tag 并推送：`git tag -a v<mod_version>-neoforge-mc1.21.1 -m "..."`，然后 `git push origin v<mod_version>-neoforge-mc1.21.1`。**tag 一旦推送不要移动**，发错了就发下一个版本号。
+7. 在 GitHub 建 Release，附上 jar 和 `SHA256SUMS.txt`，说明支持的 Minecraft/加载器组合与验证级别；CurseForge 上传同一个 jar。
 
 ## 下载文件安排
 
-同一个 GitHub `v1.0.0` Release 附上按 Minecraft 版本与加载器命名的安装 jar、支持导入已有包的 `crafty-cards-soundpack-maker-1.0.1.zip` 和三个带音频的 1.21.1 学习包（另有合集）。制作工具 zip 内有图形界面脚本、Windows 启动器、中文说明、音乐包格式与 Harness 提示词；玩家从 Release 附件直接下载，无需另开仓库。Python 与可选转码依赖不打包进源码仓库。音乐包的来源与授权风险见 [音频权利说明](../../release-materials/AUDIO-RIGHTS.md)。Release 附上 `SHA256SUMS.txt`，并明确指出每个 jar 的 Minecraft/加载器组合与验证级别。
+Release 附上按 Minecraft 版本与加载器命名的安装 jar、`crafty-cards-soundpack-maker-1.0.1.zip` 和三个带音频的 1.21.1 学习包（另有合集）。制作工具 zip 内有图形界面脚本、Windows 启动器、中文说明、音乐包格式与 Harness 提示词。音乐包的来源与授权风险见 [音频权利说明](../../release-materials/AUDIO-RIGHTS.md)。同一 Release 附 `SHA256SUMS.txt`，并明确指出每个 jar 的 Minecraft/加载器组合与验证级别。
+
+## 仓库内容
 
-GitHub 源码仓库保留三端源码、共用资源、构建脚本、测试、必要的 Gradle wrapper 启动 jar、文档和验收证据；不跟踪下载的依赖库、编译产物、测试实例、音频包及本机未来版本工作目录。统一源码提交打 `v1.0.0` 标签；各目标开发分支从这一提交建立，分支名不是独立测试通过的证明。
+GitHub 源码仓库保留三端源码、共用资源、构建脚本、测试、Gradle wrapper（含 `gradlew` 与 `gradlew.bat`）、文档和验收证据；不跟踪下载的依赖库、编译产物、测试实例、音频包及本机工作目录。主线统一源码提交打 `v1.0.0` 标签；各目标分支从该提交建立，再各自按上面的规则发版。
 
-本目录是**本地待审稿**，不表示上述发版步骤已完成。当前仓库尚未配置 Git remote，也没有获得上传许可。
+本文件描述的是发布流程；分支、tag 与 Release 的实际状态以 GitHub 仓库为准。
diff --git a/docs/open-source/TESTING.md b/docs/open-source/TESTING.md
@@ -7,17 +7,15 @@
 ## 自动验证
 
 ```powershell
-# 先运行基准：公共规则、NeoForge GameTest、一个服务端与三个真实客户端
-.\gradlew.bat test runGameTestServer
+# 本分支只验证 neoforge / Minecraft 1.21.1
+.\gradlew.bat test
+.\gradlew.bat -PmcTarget=1.21.1 runGameTestServer
 .\tools\run-acceptance-matrix.ps1 -Versions 1.21.1 -Loaders neoforge -Fullscreen
-
-# 再对指定版本的三种加载器运行完整对局；Forge 1.21.2 会标记不支持
-.\tools\run-acceptance-matrix.ps1 -Versions 1.21.11 -Loaders neoforge,fabric,forge -Fullscreen
-
-# 最后重新生成本地单页结果
 .\tools\generate-acceptance-dashboard.ps1
 ```
 
+1.21.2 – 1.21.11 的验收只在各自的版本分支执行；本分支裁剪掉了那些版本的适配目录，不能构建它们。
+
 自动流程每组启动一个专用服务器、三个真实客户端，检查放桌、配置筹码、三人入局、叫分、选牌、出牌/过牌、地主正常胜利和筹码守恒；检查私有手牌快照、倒计时、模型、世界渲染回调、音乐包事件资源及资源重载。截图覆盖叫分、HUD、选牌、结算和多个配置页；`-Fullscreen` 额外采集窗口/全屏对比。失败、超时和未运行在结果页独立标出。
 
 **当前结果以 [本地验收总览](../evidence/multi-version-2026-09-27/README.md) 与原始 `build/acceptance-matrix/` 记录为准。** 该总览在被重新生成后会变化；旧版 [2026-09-27 构建交付记录](../evidence/modern-versions-2026-09-27/README.md) 只证明当时 122 项公共单测与构建，不能当作最新的三人实机证据。NeoForge 基线原有 35 项 GameTest；现代版本没有统一移植该 GameTest 套件。