# AGENTS.md 本文档为 Claude Code（claude.ai/code）以及其他 AI 编码代理（Cursor、Aider、Copilot CLI 等）在本仓库工作时提供项目指引。 ## 仓库概述 这是 **Oshima Studios 为 FunGame 引擎制作的模组（addon pack）**，并非独立可运行的应用程序。每个项目都会生成一个 DLL，由宿主 FunGame 运行时作为插件加载。上游引擎仓库：。 代码中的大多数标识符、角色 / 技能 / 物品类名以及游戏内字符串均为**中文（CJK）**。源文件统一使用 UTF‑8 编码，请勿"规范化"这些标识符名称。 ## 构建与运行 解决方案目标框架为 **`.NET 10.0`**（WPF 项目使用 `net10.0-windows7.0`）。使用标准 .NET SDK 构建： ```sh dotnet build OshimaGameModule.sln # 构建全部项目 dotnet build OshimaWebAPI/OshimaWebAPI.csproj # 构建单个项目 dotnet run --project OshimaWebAPI # 开发服务器: https://localhost:11108, http://localhost:11109 ``` ### 必需的同级仓库 `OshimaGameModule.sln` 通过相对路径引用了**本目录以外**的项目： | 引用 | 被谁依赖 | | ------------------------------------------------------ | --------------------------------- | | `../FunGame.Core/FunGame.Core.csproj` | 所有项目 | | `../FunGame.Extension/FunGame.SQLQueryExtension/...` | `OshimaWebAPI`、`OshimaServers` | | `../FunGame.Desktop/FunGame.Desktop/...` | 仅出现在 `.sln` 中 | 构建前请将这些仓库克隆为 `OshimaGameModule/` 的**同级目录**，否则 restore 阶段会失败。 ### 输出目录布局 各类库项目均设置 `..\bin\`，因此所有构建产物会汇集到解决方案根目录的 **`OshimaGameModule/bin/`**，而不是各项目自己的 `bin/` 文件夹。宿主 FunGame 运行时正是从此聚合目录中发现并加载插件。 ### 平台说明 - `OshimaModes` 是 WPF 项目（`UseWPF=True`、`net10.0-windows7.0`），**只能在 Windows 上构建**。在 macOS / Linux 上请单独构建非 WPF 项目，整体 `.sln` 构建会因 `OshimaModes` 失败。 - `OshimaWebAPI` 是 ASP.NET Core 项目（`FrameworkReference Microsoft.AspNetCore.App`），跨平台运行。 仓库中**没有测试项目**。 ## 架构：各插件如何协作 ``` OshimaCore ──┐ ├── OshimaModules ──┐ OshimaMaps ───┤ ├── OshimaServers ──┐ │ │ ├── OshimaWebAPI └────────── OshimaModes (WPF) ──────────┘ (同时依赖 Modules + Maps) ``` 每个项目的 `RootNamespace` 都按 `Oshima.FunGame.$(MSBuildProjectName)` 的模板生成（`OshimaCore` 例外 → `Oshima.Core`）。 ### 各项目职责 | 项目 | 职责 | 插件类与 FunGame 基类 | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `OshimaCore` | 常量、基于 JSON 的设置（`GeneralSettings`、`Daily`、`SayNo`、`Ignore`、`QQOpenID`、`BlackList`） | `OSMCore.InitOSMCore()` 启动入口；本身不是插件类 | | `OshimaModules` | 实体定义（角色、技能、物品、特效、地区、单位） | `CharacterModule`、`SkillModule`、`ItemModule` —— 继承自 FunGame 的 `Library.Common.Addon.*Module` | | `OshimaMaps` | `GameMap` 实现 | `FastAutoMap`、`AnonymousMap` | | `OshimaServers` | 游戏服务器插件 + 业务服务层（`Service/FunGameService.cs`、`FunGameSimulation.cs`、`OnlineService.cs`、`SQLService.cs`、`CSBettingService.cs`） | `OshimaServer`（`ServerPlugin`）、`FastAutoServer` 与 `AnonymousServer`（`GameModuleServer`） | | `OshimaWebAPI` | ASP.NET Core 控制器 + 定时任务 + QQ / RainBOT 集成 | `OshimaWebAPI : WebAPIPlugin, IHotReloadAware, ILoginEvent` | | `OshimaModes` | 游戏模式的 Windows 桌面 UI（WPF） | 仅承载模式，本身不是 FunGame 插件 | ### 插件标识符集中在常量表中 所有插件名、addon ID 以及 `GameModuleDepend` 依赖图都集中在 **`OshimaCore/Constant/Constant.cs`** 的 `OshimaGameModuleConstant` 类中。新增一种 addon 时，请在此注册它的 kebab-case ID —— 宿主引擎正是通过这些字符串来连接依赖关系的。 ### 实体注册模式（重要） `CharacterModule` / `SkillModule` / `ItemModule` 各自覆写一个 `*Factory()` 方法，返回的委托通过一个庞大的 `switch` 按整数 ID 分派（见 `OshimaModules/Modules/*.cs`）。要新增一个角色 / 技能 / 物品，需要： 1. 在合适的目录下定义实体类（如 `Characters/`、`Skills/魔法/`、`Items/Weapon/`）。 2. 在对应的 ID 枚举中加一项（`SkillID`、`MagicID`、`SuperSkillID`、`PassiveID`、`ItemPassiveID`、`WeaponID` 等 —— 见 `Skills/SkillID.cs`、`Items/ItemID.cs`）。 3. 在该模块的工厂 `switch` 中加一行 `case (long)YourEnum.X => new X()`。 仓库中**没有**基于反射的自动发现机制；这些 `switch` 表就是唯一的事实来源。 ### 持久化 通过宿主 FunGame 运行时提供两层持久化： - **`PluginConfig`**（位于宿主配置目录下的 key/value JSON 文件，例如 `new PluginConfig("rainbot", "config")`）—— 用于 `GeneralSettings`、每日 / 黑名单状态、各服务器的统计数据（`FunGameSimulation.StatsConfig`、`FastAutoServer.StatsConfig`）。 - **`SQLHelper`**（在插件中通过 `Controller.GetSQLHelper()` 获取，配合 `NewTransaction()` / `Rollback()` / `Commit()` 使用）—— 用于用户、库存、角色 / 物品所有权。`OshimaWebAPI/Constant/*.sql` 下的脚本是游戏专属表（如 `CSBetting.sql`）的参考 SQL。 ### 生命周期钩子（FunGame addon 契约） 所有插件都实现 `IHotReloadAware`。扩展时请留意以下方法： - `AfterLoad(loader, params object[] objs)` —— 接入 DI / `SQLHelper` / 事件处理器。对于 `OshimaWebAPI`，`objs[0]` 是 `WebApplicationBuilder` —— 在此注册 scoped 服务。 - `OnWebAPIStarted(params object[] objs)` —— 对 `WebAPIPlugin` 而言，`objs[0]` 是已运行的 `WebApplication`。此处会调用 `FunGameConstant.InitFunGame()`、`FunGameSimulation.InitFunGameSimulation()`，并注册**所有 `TaskScheduler.Shared.AddTask(...)` / `AddRecurringTask(...)` 定时任务**（见 `OshimaWebAPI.cs`）。 - `OnBeforeUnload()` —— 必须按名称移除自己曾添加的每个定时任务，否则热重载会泄露重复任务。 ### 定时任务（在 `OshimaWebAPI.cs` 注册） 任务名为中文；新增任务时记得在 `OnBeforeUnload` 中按相同名称移除： ``` "重置每日运势" 每日 00:00 — Daily.ClearDaily / 活动缓存 / 公告 / 商店预刷新 "上九" / "下三" 每日 09:00 / 15:00 — 物品交易冷却重置 + 地区天气刷新 "刷新存档缓存" 每 1 分钟 — RefreshSavedCache、RefreshClubData、RoomsAutoDisband "刷新每日任务" 每日 04:00 — 每日任务、签到、商店、市场、活动缓存、公告 "刷新boss" 每 1 小时 "刷新活动缓存" 每 4 小时 ``` ### 认证（WebAPI） `OshimaWebAPI` 接入了 FunGame 的 `WebAPIAuthenticator.WebAPICustomBearerTokenAuthenticator`。token 仅与 **`GeneralSettings.TokenList`**（从 `rainbot/config` 的 `PluginConfig` 加载）中的列表做匹配。带 `[Authorize(AuthenticationSchemes = "CustomBearer")]` 的控制器需要鉴权（见 `Controllers/FunGameController.cs`）；标记 `[AllowAnonymous]` 的接口为有意公开（`/funGame/test`、`/funGame/last`、`/funGame/stats`）。 ### 两类不同的 "Server" 插件，容易混淆 - **`OshimaServer : ServerPlugin`** —— 接入宿主服务器的控制台（`.osm` 指令、商店事件）。 - **`FastAutoServer` / `AnonymousServer : GameModuleServer`** —— 真正的游戏房间逻辑。`FastAutoServer` 通过 `MixGamingQueue` 跑自动对战循环（见 `FastAutoServer.cs` 的 `StartGame`）；`AnonymousServer` 是供外部 bot 使用的、基于 token 的 WebSocket 桥。 两类插件会同时加载进同一个运行时 —— 互不替代。 ## 值得遵循的约定 - 新的字符串 ID 一律加入 `OshimaGameModuleConstant`；不要在代码中散布 `"oshima.fungame.xxx"` 这类字面量。 - 新 addon 必须**同时**更新实体工厂和对应的 ID 枚举。 - 在 `OnWebAPIStarted` 中通过 `TaskScheduler.Shared.AddTask` 注册的任务，必须在 `OnBeforeUnload` 中以同名 `RemoveTask` 注销 —— 热重载会反复执行两边，否则任务会成倍累积。 - 大量使用中文标识符是有意为之。`.csproj` 中关闭了 `CS8981`（小写标识符）与 `IDE1006`（命名风格）正是这个原因 —— 请勿重新启用。 - WebAPI 开发配置使用 `ASPNETCORE_ENVIRONMENT=Development`，监听 `https://localhost:11108;http://localhost:11109`（见 `OshimaWebAPI/Properties/launchSettings.json`）。