WandEnhancer 贡献指南：从开发环境搭建到自动化发布流水线的完整实践

• 桌面应用
• 前端

本文以仓库根目录的 CONTRIBUTING.md 为骨架，结合 Wand-Enhancer.sln、scripts 目录下的发布校验脚本、CHANGELOG.md 及 Enhancer.cs 等源码，系统讲解 WandEnhancer（面向 Wand/WeMod 应用的本地 UX 与互操作性扩展工具）的协作规范。读者将掌握：如何搭建开发环境、如何规范地提交 Bug 报告与功能建议、如何遵循项目代码风格创建 Pull Request，以及如何走完"版本号 → 变更日志 → Git 标签 → GitHub Actions 自动校验发布"的完整发布链路。

项目结构：贡献前先读懂代码地图

CONTRIBUTING.md 将仓库划分为五个主要组成部分，这一划分与 Wand-Enhancer.sln 中的工程组织完全对应（该解决方案包含WandEnhancer与AsarSharp两个项目工程）：

• WandEnhancer—— 主工程，承载增强逻辑与用户界面，是 WandEnhancer.csproj 中定义的WinExe应用程序，输出名为WandEnhancer.exe；
• AsarSharp—— 处理 ASAR 归档的独立类库，负责解包与修改 WeMod 的app.asar文件，核心实现见 AsarExtractor.cs 与 AsarCreator.cs；
• Core—— 增强流程核心，包括静态与动态修改逻辑，入口为 Enhancer.cs，其Patch()方法串联了"备份 → 解包 → 打补丁 → 注入远程面板 → 重新打包 → 附加代理 DLL"的完整链路；
• Models—— 项目使用的数据模型，如 WeModConfig.cs、PatchConfig.cs、Signature.cs；
• View—— 用户界面组件，包括 MainWindow 与 PatchVectorsPopup 等。

仓库还包含两个对贡献者同样重要的目录：web-panel（基于 React + Vite + TypeScript 的远程 Web 面板前端，含完整的 Vitest 测试与.po多语言文件）和tools/asar-fuses-bypass（用 CMake 编译的本地代理 DLL 源码，产物version.dll会被嵌入主程序，见 WandEnhancer.csproj 中的ProxyDllPath配置）。

开发环境搭建：三步进入可编译状态

CONTRIBUTING.md 给出的环境搭建流程如下，结合仓库实际配置可补充如下细节：

1. 克隆仓库：使用git clone获取仓库到本地（注意：本项目不发布官方编译产物，构建需在本地或 fork 的 CI 中进行，详见 README.md 的 "How to build from source" 一节）。
2. 打开解决方案：用 Visual Studio 或 JetBrains Rider 打开根目录下的 Wand-Enhancer.sln。该解决方案仅含 Debug/Release 两个配置，且均为Any CPU平台；两个工程的PlatformTarget实际被固定为x64（见 WandEnhancer.csproj）。
3. 还原 NuGet 包：解决方案依赖ILRepack.2.0.41（用于 Release 构建时合并 DLL）与Newtonsoft.Json.13.0.3等包。若本机缺少 ILRepack，WandEnhancer.csproj 中的EnsureNuGetPackageBuildImports目标会在PrepareForBuild阶段直接报错提示启用 NuGet 包还原。
4. 构建项目：需要注意，完整构建并非只靠 MSBuild——WandEnhancer.csproj 中ValidateNativeArtifacts目标要求在构建前已存在由 CMake 生成的version.dll代理文件，ILRepack目标在 Release 下合并输出，同时web-panel/dist目录会被作为嵌入资源打包。因此按 README.md 的说法，推荐直接运行仓库的build.cmd，它会依次安装 web 面板依赖、构建前端、用 CMake 编译本地助手、还原 NuGet 并构建 WPF 解决方案。

Bug 报告：可复现性是第一要求

发现缺陷时，请在 Issue 中提供完整描述。CONTRIBUTING.md 要求包含以下要素：

• WandEnhancer 版本——可参考 AssemblyInfo.cs 中的AssemblyVersion/AssemblyFileVersion（当前为1.0.9.3），也建议附上 CHANGELOG.md 中对应的版本条目；
• 发生问题的 WeMod 版本——因为补丁逻辑与目标客户端版本强耦合（详见下文"测试要求"）；
• 详细的复现步骤；
• 预期行为与实际行为的对照；
• 截图或错误日志（若有）。主程序日志实现在 Logs.cs，补丁过程的[ENHANCER]前缀日志由 Enhancer.cs 中的_logger回调输出，可在报告中一并粘贴。

功能建议：先讲问题，再谈方案

对于新功能或改进建议，CONTRIBUTING.md 要求 Issue 中说明三点：

1. 该改进要解决什么问题——即用户痛点与场景；
2. 你设想如何实现该功能——可参考现有架构，例如"远程 Web 面板类功能应复用web-panel前端的渲染器注入链路"；
3. 你考虑过的替代方案——便于维护者评估取舍。

从 CHANGELOG.md 可以看到，这类 Issue 驱动的贡献是常态：如 #98 贡献者将远程面板的 mod 名称、描述与说明翻译为账号语言，正是"问题—方案"流程的产物。

创建 Pull Request：标准分支工作流

CONTRIBUTING.md 规定的 PR 流程为：

1. Fork 仓库到个人账号；
2. 创建描述性分支，命名规范如下：

git checkout -b feature/feature-name # 新功能 git checkout -b fix/fix-name # 缺陷修复

3. 提交更改，Commit Message 应清晰、有描述性；
4. 确保代码符合项目风格（见下节）；
5. 推送分支到自己的 fork：

git push origin your-branch-name

6. 向主仓库发起 Pull Request，在描述中说明改动内容及必要性。

值得一提的是，仓库内 CHANGELOG.md 的记录（如 #110、#67、#118 等贡献）表明该流程在实践中被广泛使用；部分改动还引用了贡献者署名（如by @Kava-4 in #110），可作为撰写 PR 描述的参考风格。

代码风格：C# 命名与工程原则

CONTRIBUTING.md 明确要求遵循 C# 命名约定，并以 SOLID 与 DRY 为工程原则。仓库源码恰好是这些约定的活教材：

• PascalCase用于类、方法、属性名。例如 Enhancer.cs 中的Patch()、ApplyJsPatch()、InjectRemotePanelFiles()，以及 AsarCreator.cs 中的CreatePackageWithOptions()；
• camelCase用于局部变量与参数。例如string data = File.ReadAllText(item)中的data，方法参数string fileName, string js等；
• _camelCase用于私有字段。典型示例见 Enhancer.cs 顶部的_weModConfig、_logger、_asarPath、_backupPath等字段声明；
• 复杂代码段或补丁方法需要注释。例如 Enhancer.cs 中Patch()方法的"Creating backup / Restoring pristine app.asar"等步骤日志，以及 AssemblyInfo.cs 中关于版本属性的详细注释，都是注释习惯的体现。

此外，补丁系统大量使用常量集中管理文件与目录名（见 Enhancer.cs 顶部const区块），这与 DRY 原则一脉相承：AppAsarFileName = "app.asar"、RemoteBridgeTargetFileName = "bridge.cjs"等字符串只在常量处定义一次。

测试要求：以当前 WeMod 版本为验收基准

提交 PR 前，CONTRIBUTING.md 要求确认四点：

1. 代码可无错误编译；
2. 功能经过手动测试；
3. 补丁在当前版本的 WeMod 上正常工作——这一点尤其重要：从 Enhancer.cs 的ApplyJsPatch()实现可见，补丁基于正则匹配目标 JS 函数，当同一目标出现多处匹配（patch.SingleMatch且NextMatch().Success）时会直接抛出"Looks like the version is not supported"异常，因此"当前版本兼容性"是硬性验收条件；
4. 改动不破坏既有功能。

仓库在自动化测试方面也提供了范例：web-panel前端包含基于 Vitest 的单元测试（如 trainer.test.ts、protocol-router.test.ts、games.test.ts 等），涉及补丁路由、游戏状态规范化、预设存储等纯逻辑层；web-panel/bridge侧同样有 runtime.integration.test.ts 覆盖运行时集成场景。桌面端 C# 逻辑目前以手动验证为主，因此"手动测试补丁"是 PR 前不可省略的环节。

发布流程：一次完整、可自动校验的版本发布

CONTRIBUTING.md 的发布流程共 6 步，是仓库工程化程度最高的部分，配合 scripts 目录可还原完整机制：

第 1 步：更新 WandEnhancer/Properties/AssemblyInfo.cs。需同步修改AssemblyVersion与AssemblyFileVersion两个特性（当前版本示例为1.0.9.3）。validate-release-metadata.ps1 会用正则(?m)^\s*\[assembly:\s*AssemblyVersion\("(?<version>[^"]+)"\)\]与AssemblyFileVersion分别提取这两个值，并要求二者完全一致。

第 2 步：在 CHANGELOG.md 顶部新增同版本的变更章节。其格式约定为## [版本号] - 日期，例如：

## [1.0.9.3] - 2026-07-04 ### Fixes - Fixed the Remote Web Panel no longer applying on newer Wand builds ...

CHANGELOG 头部明确声明它是"release notes 的唯一事实来源"，且"最新条目必须与 AssemblyInfo.cs 中的版本匹配"。校验脚本会检查 CHANGELOG 中最新的## [版本]章节必须等于程序集版本、且该章节不能为空。

第 3 步：配置本地 Git hooks（一次性）：

git config core.hooksPath .githooks

该命令将 Git hooks 目录指向仓库内的.githooks，使提交/推送前自动执行本地校验（如版本元数据一致性检查）。

第 4 步：提交并推送版本/变更日志改动。

第 5 步：创建并推送与版本完全一致的 Git 标签，例如：

git tag 1.0.8.0 git push origin 1.0.8.0

第 6 步：GitHub Actions 自动完成校验与发布。工作流会依次：

• 校验版本：validate-release-metadata.ps1接收标签版本号作为ExpectedVersion，要求标签版本、程序集版本与 CHANGELOG 首个章节三方一致，否则抛出异常终止；
• 构建项目：执行完整构建（含 web 面板前端与 CMake 本地 DLL）；
• 提取匹配的变更日志章节：get-changelog-section.ps1 -Version <标签版本>从 CHANGELOG.md 中按^##\s+\[(?<version>[^\]]+)\]定位目标章节（忽略大小写与v/V前缀），将该章节写为发布说明；
• 发布 notes-only 版本：官方 Release 不附带编译好的二进制文件。这一点在 CHANGELOG.md 1.0.9.2 条目中有明确说明："Official releases no longer include downloadable.exefiles"，并在 README.md 的 Q&A 中解释了原因——未签名/自构建的补丁工具反复被第三方站点重新上传并误报，因此官方不再分发预编译产物，用户应通过 fork 后的 "Build executable" GitHub Actions 工作流自行构建。

行为准则与许可证

参与本项目即承诺与其他社区成员保持互相尊重的交流，任何侮辱、骚扰或其他不可接受的行为将不被容忍（CONTRIBUTING.md "Code of Conduct" 一节）。

关于代码归属：按 CONTRIBUTING.md 的声明，贡献者的贡献将基于Apache License 2.0授权，详见仓库根目录的 LICENSE.md。这也与 README.md 中的项目许可证声明保持一致。在提交 PR 前，请确认你理解并同意这一授权方式。

小结

WandEnhancer 的贡献流程是一套完整闭环：用规范化的 Issue 收集 Bug 与建议，用分支命名与 Commit Message 约定维持协作秩序，用 C# 命名规范与 SOLID/DRY 原则保证代码可读性，再用"AssemblyInfo → CHANGELOG → Git 标签 → Actions 校验发布"的四段式流水线把版本发布变成可自动验证的机械过程。对新手贡献者而言，最稳妥的切入路径是：先按 README.md 在本地成功构建一次（确认 CMake、pnpm、MSBuild 齐备），再对照 CONTRIBUTING.md 的清单提交你的第一个fix/分支。

• 桌面应用
• 前端