From 35b883b5b265b7a83e57847b363485a72882c984 Mon Sep 17 00:00:00 2001 From: milimoe Date: Tue, 10 Nov 2026 01:46:47 +0800 Subject: [PATCH] docs(S9): rewrite README for the completed migration --- OshimaBot/README.md | 101 ++++++++++++++++++++++++++++++++------------ 1 file changed, 75 insertions(+), 26 deletions(-) diff --git a/OshimaBot/README.md b/OshimaBot/README.md index 0d38c73..ff4c3f9 100644 --- a/OshimaBot/README.md +++ b/OshimaBot/README.md @@ -1,51 +1,100 @@ -# OshimaBot WebAPI +# OshimaBot -基于 FunGame.Core v3 与 OshimaBot.Content 的独立 ASP.NET Core 游戏服务器,不依赖 FunGameServer、OshimaServers 或旧 WebAPI 插件。 +基于 **FunGame.Core v3** 的 QQ 机器人 MUD 服务端。由旧版 `OshimaGameModule`(Core v2 / FunGameServer v2)迁移而来,**不再依赖 FunGameServer、MySQL 或旧插件体系**,独立部署。 + +- 接入:**WebSocket 单模式**(开发与部署一致);Webhook 按官方规范补齐验签 / ACK,但默认关闭。 +- 存储:**SQLite + EF Core 10**,33 张业务表;用户存档、背包、经济流水、模拟统计全部入库,不再有 `saved/*.json`。 +- 指令:**66 条**显式注册(零反射扫描),中文动词为主、旧版别名兼容,Markdown 4 段式回复 + 可点击指令 / 自定义按钮。 ## 项目结构 -- `OshimaBot`:WebAPI、RainBot、QQ Bot 与后台消息队列。 -- `OshimaBot.Game`:共享的 `FunGameService`、模拟器和初始化逻辑。 -- `OshimaBot.Content`:角色、技能、物品内容包。 +| 项目 | 职责 | +|---|---| +| `OshimaBot` | ASP.NET Core WebAPI、QQ 事件管线、消息层、指令框架、玩法仓储、数据层 | +| `OshimaBot.Game` | `FunGameService` 内容目录、模拟器、运行态上下文、统计仓储接口 | +| `OshimaBot.Content` | 18 角色 / 118 技能 / 198 物品的内容定义 | +| `OshimaBot.Tests` | xunit 单测(128 条,含真实 SQLite 端到端) | -## 启动 +目录要点:`Commands/`(显式 `CommandCatalog` + Router)、`Messaging/`(QQ Markdown / 按钮 / 发送)、`Gameplay/`(规则、玩家存档、经济)、`Data/`(DbContext / Migration)、`Security/`(验签、身份、ApiKey)、`Services/Gateway/`(WebSocket 网关)。 + +> `OshimaBot.slnx` 以相对路径引用仓库外的 `../../FunGame/FunGame.Core/src/FunGame.Core.csproj`;换机器或公开仓库前需改为子模块 / 包引用。 + +## 快速开始 在解决方案根目录执行: ```powershell -dotnet run --project OshimaBot/OshimaBot.csproj +dotnet build OshimaBot.slnx +dotnet test OshimaBot.Tests/OshimaBot.Tests.csproj +dotnet run --project OshimaBot/OshimaBot.csproj --urls http://127.0.0.1:5090 ``` -默认地址为 `http://localhost:5090`,开发环境 OpenAPI 文档位于 `/openapi/v1.json`。也可在解决方案目录构建全部项目: +开发环境的 OpenAPI 文档位于 `/openapi/v1.json`;`GET /health` 返回模式、网关连接状态与最近错误。端口可用 `--urls` 或环境变量覆盖。 + +数据库默认 `Data Source=oshimobot.db`(相对 `OshimaBot/` 内容根),启动时自动应用 Migration 并开启 WAL / 外键。需要手动管理迁移时: ```powershell -dotnet build OshimaBot.slnx +dotnet tool install dotnet-ef --version 10.0.11 --tool-path .tools +./.tools/dotnet-ef.exe migrations add --project OshimaBot/OshimaBot.csproj +./.tools/dotnet-ef.exe database update --project OshimaBot/OshimaBot.csproj ``` -## 首轮接口 - -保留旧版核心路由: - -- `GET /FunGame/test`、`/FunGame/testdebug`:混战或团队模拟,支持种子、地图、初始等级等参数。 -- `GET /FunGame/last?full=false`:最近模拟日志。 -- `GET /FunGame/characterinfo`、`skillinfo`、`skillinfoname`、`iteminfo`、`iteminfoname`。 -- `GET /FunGame/stats`、`teamstats`、`winraterank`、`ratingrank`。 -- `GET /FunGame/newmagiccard`、`newmagiccardpack`。 -- `POST /QQBot`:QQ Webhook;`POST /QQBot/thirdparty`:第三方机器人消息。 - -新增 `GET /FunGame/status`、`characters`、`skills`、`items` 用于服务状态和目录查询。 - ## 配置 -QQ 外部发送默认关闭。通过用户机密、环境变量或部署配置设置,不要提交真实凭据: +**不要把真实凭据提交进仓库**,用 `dotnet user-secrets` 或环境变量: ```powershell dotnet user-secrets set "QQBot:Enabled" "true" --project OshimaBot/OshimaBot.csproj dotnet user-secrets set "QQBot:AppId" "" --project OshimaBot/OshimaBot.csproj -dotnet user-secrets set "QQBot:Secret" "" --project OshimaBot/OshimaBot.csproj +dotnet user-secrets set "QQBot:Secret" "" --project OshimaBot/OshimaBot.csproj dotnet user-secrets set "Server:ApiKey" "" --project OshimaBot/OshimaBot.csproj ``` -第三方接口使用 `X-API-Key: ` 或 `Authorization: Bearer `。未配置 `Server:ApiKey` 时,第三方接口返回 503。 +| 配置节 | 关键项 | 说明 | +|---|---|---| +| `QQBot` | `Enabled` / `Mode=WebSocket` / `Environment` | WS 仅在 `Enabled=true && Mode=WebSocket` 时启动;`Intents=100663296` = `GROUP_AND_C2C_EVENT \| INTERACTION` | +| | `EnableWebhook=false` | 打开后 `POST /QQBot` 才接受回调,并执行 Ed25519 入站验签 + 时间戳防重放 | +| | `GatewayUrl` / `ShardId` / `GatewayMaxReconnectDelaySeconds` | 留空 `GatewayUrl` 时走 `GET /gateway/bot` 自动发现;支持 Resume 与会话持久化 | +| `Database` | `ConnectionString` / `ApplyMigrationsOnStartup` / `ProcessedEventRetentionHours` | SQLite 单实例;事件幂等记录保留 24 小时 | +| `Server` | `ApiKey` | **仅首次启动引导**:把 SHA-256 写入 `api_keys` 后应从配置移除明文;认证只查库,密钥支持吊销 / 过期 / 分权 | +| | `BindCodeTtlSeconds` / `SuperAdminOpenIds` | 一次性绑定码 300 秒;超管白名单与 `user_roles` 双轨 | +| | `ArchiveSimulationRounds=false` | 默认不生成 `rounds_archive.zip`,复盘时再打开 | +| | `StoreFullSimulationLog=true` | 完整模拟日志写入 `simulation_runs.rounds_json`,重启后可恢复 `/上次的完整日志` | -RainBot 首轮支持帮助、角色/技能/物品查询、魔法卡预览、模拟战、统计和排行。存档、库存、交易、社团、活动等依赖旧数据库与 FunGameServer 的模块不在本轮范围内。 +`Server:ApiKey` 首次启动会为第三方通道懒建一个独立内部用户;每个 ApiKey 一个账号,需要多人共用时显式指定 `api_keys.user_id`。 + +## HTTP 接口 + +| 路由 | 说明 | +|---|---| +| `GET /`、`GET /health` | 服务信息与健康检查 | +| `POST /QQBot` | Webhook 回调(默认 404;开启后验签 + op13 验证 + op12 ACK + 事件分发) | +| `POST /QQBot/thirdparty` | 第三方消息(JSON body),需 `X-API-Key` 或 `Authorization: Bearer` | +| `POST /QQBot/thirdpartytest?msg=...&openID=...` | 联调用的简化入口,同样需 ApiKey | +| `POST /QQBot/bind` | 用 6 位一次性绑定码兑换外部身份,需 ApiKey | + +第三方消息自报的 `openid` 只用于回显,身份一律以 ApiKey 的 `ClaimsPrincipal` 为准。 + +## 指令概览 + +语法 `/动词 [目标] [参数]`,`/` 可省略;`@编号` 按列表顺序稳定映射,`x2` 表示数量,`p2` 翻页。`/帮助` 由注册表自动生成(11 页)。 + +| 批次 | 代表指令 | +|---|---| +| 系统 / 查询 | `/帮助`、`/战斗帮助`、`/取消`、`/绑定`、`/查角色`、`/查技能`、`/查物品`、`/上次的日志` | +| 战斗模拟 | `/FunGame模拟`、`/混战模拟`、`/FunGame团队模拟`、`/查个人评分`、`/查团队胜率` | +| P1 存档 | `/状态`、`/观察`、`/签到`、`/每日任务`、`/领奖 @1`、`/抽卡`、`/十连抽卡`、`/背包`、`/使用 @1`、`/分解 @1`、`/装备 @1`、`/我的角色`、`/设主战 @1`、`/升级 @1`、`/突破 @1`、`/练级 @1`、`/小队` | +| P2 经济 | `/商店`、`/购买 @1`、`/市场`、`/上架 @1 200`、`/购买市场 @1`、`/报价列表`、`/报价 @1 300`、`/锻造 @1`、`/秘境 精英`、`/决斗`、`/Boss`、`/排行榜 战绩` | + +所有货币变动与物品变动在**同一事务**完成并写 `ledger_entries`;市场 / 报价成交时买卖双方各记一笔,可对账。市场上架物品会进入托管状态,成交前不出现在任何玩家背包。 + +## 数据与持久化 + +- 首访懒建档:`users` / `user_identities` / `user_roles` + `player_states`;外部 OpenID 与内部 `users.id` 解耦,支持换绑。 +- **旧版 MySQL 存档不导入**(数据已丢失、OpenID→uid 不可重建);所有旅人从今天重新开始。 +- 模拟统计与日志存 `simulation_statistics` / `simulation_runs`,启动时 `LoadAsync` 恢复,重启后 `/上次的日志` 与评分排行仍在;`rounds_archive.zip` 默认不再生成。 +- 备份:停服后直接复制 `oshimobot.db`(含 WAL 时一并复制 `-wal` / `-shm`),或用 `VACUUM INTO` 生成一致性快照。 + +## 范围 + +玩法交付 **P0(查询 / 模拟)→ P1(存档 / 养成)→ P2(经济 / 战斗)**。P3(社团、赛马、赛事预测、探索地图、私信)按计划不在本轮范围,相关表未建。完整迁移计划与运维说明见 `docs/`(本地资料,不纳入版本控制)。