diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..85145af --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,126 @@ +# 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`）。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..da9ac4a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# CLAUDE.md + +本仓库的项目说明、构建命令以及 AI 编码代理使用指引统一维护在 [AGENTS.md](./AGENTS.md) 中，请直接阅读该文件。 + +之所以采用单一来源：`AGENTS.md` 是跨工具的事实标准（Cursor、Aider、Copilot CLI 等都会读取），让两份文件共享同一份内容可以避免维护时出现漂移。Claude Code 会同时读取 `CLAUDE.md` 与 `AGENTS.md`，本指引中的转发不会丢失上下文。