3.8 KiB
3.8 KiB
DuckovMods — agent 快速上手说明
目标：为 AI 编码代理提供立即可用的、本仓库可执行的上下文和约定，便于快速完成修改、补丁与功能实现。
-
仓库概览
- 顶层为多个独立 mod 项目文件夹（例如
HideCharacter/,HitFeedback/,SceneSnapshot/,Theme/,UIFrame/）。每个模块通常包含一个*.csproj、ModBehaviour.cs与若干源文件。 - 解决方案文件：
DuckovMods.sln。README 位于根目录，简短说明了仓库目的。
- 顶层为多个独立 mod 项目文件夹（例如
-
关键约定（必须遵循）
- 每个 mod 通过类
ModBehaviour实现，且继承自Duckov.Modding.ModBehaviour（示例：Theme/ModBehaviour.cs）。常用生命周期钩子：OnAfterSetup()、OnBeforeDeactivate()。 - 模块间互操作通常通过反射和“安全 API 包装器”完成（示例：
HideCharacter/Api/ModConfigApi.cs）。这些包装器：- 在运行时用
AppDomain.CurrentDomain.GetAssemblies()扫描目标程序集并反射所需类型/方法； - 做好异常捕获并返回布尔成功标志或默认值；
- 约定配置键名为
${modName}_${key}（见SafeLoad/SafeSave用法）。
- 在运行时用
- 配置与版本兼容：一些 API 会检查目标 mod 的静态
VERSION字段（例中ModConfig.ModBehaviour.VERSION）。在交互前请优先调用包装器的Initialize()。 - 日志使用 UnityEngine 的
Debug.Log/Debug.LogWarning/Debug.LogError。
- 每个 mod 通过类
-
构建 / 调试工作流
- 这是一个 .NET 多项目解决方案。常规命令（PowerShell）：
- 构建（调试）：
dotnet build d:\vs_project\DuckovMods\DuckovMods.sln - 构建（发布）：
dotnet build d:\vs_project\DuckovMods\DuckovMods.sln -c Release
- 构建（调试）：
- 注意：部分项目输出见
bin/Debug/netstandard2.1/或bin/Release/net9.0/，在修改目标框架或依赖时，请检查对应*.csproj的<TargetFramework>。 - 仓库内未发现独立的单元测试项目 —— 若需要添加测试，请在顶层新建
tests/并使用常见测试框架（xUnit/NUnit）。
- 这是一个 .NET 多项目解决方案。常规命令（PowerShell）：
-
常见开发任务与示例
- 添加新 mod：在仓库根添加新文件夹并创建
YourMod.csproj、ModBehaviour.cs（继承Duckov.Modding.ModBehaviour），在解决方案中加入 csproj。 - 与 ModConfig 交互：参考
HideCharacter/Api/ModConfigApi.cs的模式，优先编写“安全静态封装”以免反射调用抛出未捕获异常。 - 读取/保存配置：使用
SafeLoad<T>(modName, key, default)与SafeSave<T>(modName, key, value)，键名需按${modName}_${key}规则。
- 添加新 mod：在仓库根添加新文件夹并创建
-
代码风格与约定（可自动化检查）
- 命名：模块文件夹以 PascalCase，类名以 PascalCase。
- 公共跨 mod API 放在各模块的
Api/子目录（例如HideCharacter/Api/），以降低命名冲突。 - 反射查找尽量包含日志输出以便定位加载顺序问题（本仓库中已有此类日志用法）。
-
易出错点（agent 在修改时应特别留意）
- 直接调用其他 mod 的内部类型/方法会因加载顺序或版本不兼容而失败——请优先使用或添加“安全包装器”。
- 修改 TargetFramework 可能导致与 Unity 或已有二进制不兼容。先在本地构建并检查
bin/输出。 - 不要假设存在单元测试；对行为敏感修改请手动验证或添加小型验证脚本。
-
推荐起始文件（优先阅读）
Theme/ModBehaviour.cs（mod 生命周期示例）HideCharacter/Api/ModConfigApi.cs（反射 + 安全包装器范例）UIFrame/UIFrameAPI.cs（公共 API 占位）DuckovMods.sln与根README.md
如果上面有遗漏或需要更详细的“如何运行/调试某个 mod”步骤，请指出具体目标（例如：“在 Unity 中热重载某 mod”或“为 HideCharacter 添加新的 ModConfig 项”），我会把说明扩展成更精确的操作步骤。