docs & feat: add license & attribution notice (Apache-2.0 / GPL-3.0) and core system enhancements

docs/README_ZH.md

@@ -0,0 +1,197 @@
+# 🚂 GaCy GO
+
+<div align="center">
+
+**基于 Go 语言开发的高性能《崩坏：星穹铁道》游戏服务端模拟器**  
+移植自 [`GaC-hkrpg-ps`](https://github.com/CAtlas0784/GaC-hkrpg-rust)，并参考 `PearlSR` 与 `Currency-War-SR` 协议规范。
+
+[English](README_EN.md) | [ภาษาไทย](../README.md) | [简体中文](README_ZH.md)
+
+</div>
+
+---
+
+## 🇨🇳 简体中文
+
+<div align="center">
+
+[项目文档](./) • [Windows 快速上手](#-windows-快速上手) • [特色玩法与内置系统](#-特色玩法与内置系统) • [配置与防硬编码规范-agentsmd](#-配置与防硬编码规范-agentsmd) • [鸣谢与致敬](#-鸣谢与致敬-credits--acknowledgments)
+
+</div>
+
+本系统为使用 Go 语言实现的《崩坏：星穹铁道》游戏服务端模拟器，由 [`GaC-hkrpg-ps`](https://github.com/CAtlas0784/GaC-hkrpg-rust) 移植而来，底层协议参考 [PearlSR](https://git.xeondev.com/HonkaiSlopRail/pearl-sr)。包含游戏主服 (Game Server)、SDK 调度分发服 (SDK/Dispatch Server) 以及面向 GaCy-Srtool 的 REST API。
+
+项目当前处于活跃开发状态，目标运行环境对应客户端 **4.6.53 OS**。命令映射表与最新处理器参考 PearlSR commit `005d2c12db4781071f4b5b68e8f364587886a710`（详见 [协议更新记录](protocol-update.md)）。协议结构一致并不代表所有游戏系统与画面均已 100% 具备可玩性。
+
+---
+
+### 🎮 货币战争 (Currency Wars / CW) —— 开发中
+
+- **自走棋模拟引擎 (Autochess Simulation Engine)**: 移植自 [Currency-War-SR by xaodev](https://gaytea.cod-algieba.ts.net/xaodev/Currency-War-SR)，实现了基于 Supply（补给节点）的遭遇战生成、难度/选择矩阵以及模式/章节/Boss 的经验成长规则，并维持经过客户端验证的战斗路径。完整审计记录见 [CW xaodev 交接文档](CW-XAODEV-CLAUDE-HANDOFF.md) 与 [CW 路径推进审计](cw-route-continuation-audit.md)。
+- **时间模拟系统 (FakeTime)**: 在 GaCy-Srtool 中，可使用 `/faketime status` 查看当前模拟的游戏时间，使用 `/faketime <Unix秒数>` 或 `/faketime <RFC3339时间格式>` 自由设定游戏世界时钟，使用 `/faketime off` 恢复宿主机真实时间。状态持久化记录于 `game_clock.state_file`（可通过环境变量 `GAC_GAME_CLOCK_STATE_FILE` 覆盖）。该机制仅作用于游戏登录与心跳逻辑，绝不修改 Windows 系统时钟或网络超时设定。
+- **昔涟 (Cyrene) 登录列车场景**: 通过 `LoginShow_UP` 清单与入场动画结束事件深度绑定，完整还原白色列车、粉紫色天空、花瓣飘落动效以及顺畅的退出重登过渡流程。详见 [登录场景研究笔记](login-cyrene-investigation.md)。
+- **GaCy-Srtool 紧急解卡 (Emergency Unstuck)**: GM 控制台中的 **Unstuck** 按钮会向服务端发送 `POST /api/client/unstuck`，在客户端下一次心跳周期触发 `UIManager.ClearWaitNetPacketFullScreenBlock()`。在不损坏 CW 战斗进度、不跨图传送、不伪造通关的前提下安全解除黑屏与转圈卡死。
+- **角色星级合成与备战席管理**: 自动实现同名同星级角色 3 合 1 升星、Preparation（备战席）装备绑定/追踪及主角焦点 (Spotlight) 选择机制。
+
+#### CW 备战阶段常用指令 (CW Preparation Commands)
+- `/cw status`: 查看当前轮次阶段、金币、生命值 (HP) 与已保存等级。
+- `/cw gold <总额>`: 设定 CW 金币总数（例如 `/cw gold 1000`）。
+- `/cw hp <总额>`: 在当前关卡允许范围内设定角色当前生命值。
+- `/cw exp <增加量>`: 增加经验值并应用匹配的等级、人口容量与商店概率权重。
+- `/cw list role`: 列出服务端支持的 RoleID、AvatarID 与对应星级。
+- `/cw role <RoleID> <星级> [数量]`: 添加角色至备战席并触发自动升星；备战席已满将取消整笔操作。
+- `/cw list equip`: 列出当前捕获的所有装备 ID。
+- `/cw equip <ItemID> [数量]`: 将指定装备添加至 CW 行囊。
+- `/cw list orb|consumable|forge`: 列出当前可用的奖励球、消耗品与锻造 ID。
+- `/cw orb|consumable|forge <ItemID> [数量]`: 在备战阶段发放指定物品。
+- `/cw help`: 查看完整指令帮助与语法。
+
+---
+
+### ✨ 特色玩法与内置系统
+
+#### 阿哈的帮助 (Aha's Help)
+
+GaCy-Srtool 的持久化配置提供独立的 Aha's Help 辅助选择器。等级参数读取自 `resources/AhaHelpConfig.json`。接口 `GET /api/aha-help` 可查询可用层级；`POST /api/aha-help` 接受 `{"level":1}`，设为 0 表示禁用，设为 `null` 则使用原版 FreeSR 的侵蚀辅助开关。该配置通过原子写入保存于 `persistent.aha_help_level`，不影响 CW 及 EX 状态。
+
+选定的 Buff 会在进入包含 `BattleRules.json` 真实侵蚀 (Corruption) 映射的下一场战斗时生效。这包含 srtool 导入侵蚀 Buff 的自定义关卡。官方挑战关卡仍通过 `StageInvasionConfig.json` 解析侵蚀，单纯复用关卡 ID 不会自动注入侵蚀。显式设为 0 会关闭该场侵蚀战的阿哈辅助。本设置独立于全局 Aha Global 开关，且不会中途篡改正在进行的战斗。`server_debug.log` 中的 `AHA_HELP` 字段将记录下发的侵蚀与辅助 ID。
+
+#### 星辰跳跃 (Stella Jump)、活动预览与当期跃迁 (Featured Gacha)
+
+`resources/StellaJumpConfig.json` 包含从当前客户端捕获的 16 个辰菱 GameBoy 挑战关卡。沙盒模式提供挑战包并于 `persistent.stella_jump` 记录最佳成绩与通关状态。开启菜单为只读操作。
+
+`resources/ActivityPreviewPolicy.json` 负责从 `PreviewGameplayCatalog.json` 选择活动面板预制体。其余面板因客户端日志检测到奖励资产缺失或无效物品查询而被暂时封锁。待逐一验证已安装资产及依赖后方可恢复开启。
+
+Warp 仅发送已从当前客户端捕获且确认预制体存在的卡池。客户端日志显示交接包的 2120 不在本机表中，已检查的限定卡池资源也缺失；抽卡暂时禁用，等待核实卡池、奖励与协议。
+
+运行时捕获的数据表及当前验证边界均记录在 [docs/offline-gameplay-continuation.md](offline-gameplay-continuation.md)。
+
+#### 自由镜头 (Freecam) 与面部跟随视角 (FaceCam)
+
+- `Tab`: 开启/关闭 Freecam 及 FaceCam 模式；方向键: 移动镜头位置；按住鼠标右键并拖动: 旋转镜头朝向。
+- `Page Up` / `Page Down`: 镜头升降；`+` / `-`: 调整镜头移动速度。
+- FaceCam 会自动对齐当前操控角色的头部骨骼动画朝向，并持续跟随战斗中的变身角色（例如卡斯兰娜）。鼠标滚轮可临时调节视距。
+- 战斗中开启 Freecam 时，系统会自动通过 `InControlInputModule.allowMouseInput` 并挂起鼠标按键绑定，屏蔽 UI 点击干扰，同时保留键盘技能按键的正常使用。
+
+---
+
+### 🚀 Windows 快速上手
+
+#### 环境需求
+1. Windows 操作系统，配备 PowerShell 环境及用于首次构建的互联网连接。启动脚本会比对 `go.mod` 中声明的 Go 基础版本；若未安装或版本陈旧，将提示从官方镜像自动下载并校验 SHA-256，解压部署至 `launcher.go_install.directory`。
+2. 准备客户端与代理工具，将调度请求重定向至 `server.json` 配置的地址。
+3. 标准可执行程序依赖根目录的 `resources/` 资产；`for ship` 目录下的独立分发版已内置打包资源。
+4. 运行 `run.bat` 并选择对应菜单项：
+
+| 选项 | 功能描述 |
+| :---: | :--- |
+| `1` 或 回车 | 编译 SDK 与 Game 服务器，启动双端服务并调起客户端 |
+| `2` | 直接运行已编译的现成 `.exe` 双端服务器 |
+| `3` | 仅启动 SDK 调度服务器 |
+| `4` | 仅启动 Game 游戏主服务器 |
+| `5` | 启动双端服务器并同时调起 Gay Proxy 代理工具 |
+| `6` | 仅执行双端 `.exe` 编译 |
+| `7` | 退出启动器 |
+| `8` 或 `stop` | 停止本项目关联的所有服务端进程 |
+| `9` 或 `requirements` | 检查本地 Go 环境并支持一键下载安装 |
+
+SDK 服务与 Game 服务将分别在独立的控制台窗口中启动并打印实时运行日志。启动菜单在操作完成后 5 秒将自动退出，后台服务端继续运行。使用 `run.bat stop` 或直接关闭控制台窗口即可终止服务。
+
+---
+
+### ⚙️ 配置与防硬编码规范 (`AGENTS.md`)
+
+依据项目核心准则 `AGENTS.md`，严禁在源码或启动脚本中硬编码任何特定机器路径、用户名、IP、端口或游戏部署版本。
+
+配置加载优先级：**环境变量 > `server.local.json` > `server.json`**
+
+- `server.json`: 启动器、Game 游戏服与 SDK 调度服共享的核心全局配置文件。
+- `server.local.json`: 本机特化配置文件（被 Git 忽略）。可通过复制 `server.local.example.json` 创建。
+- `GAC_CONFIG`: 可指定自定义主配置文件路径。
+
+| 配置字段 | 环境变量覆盖 | 用途说明 |
+| :--- | :--- | :--- |
+| `account_name` | `GAC_ACCOUNT_NAME` | SDK 登录响应返回的用户名及游戏内展示昵称 |
+| `player_uid` | `GAC_PLAYER_UID` | 玩家数字 UID (1–4294967295)，双端共用 |
+| `client_version` | `GAC_CLIENT_VERSION` | 日志及 API 标识的客户端版本号 |
+| `game_host`, `game_port` | `GAC_GAME_HOST`, `GAC_GAME_PORT` | Game 服务端本地监听地址与端口 |
+| `sdk_host`, `sdk_port` | `GAC_SDK_HOST`, `GAC_SDK_PORT` | SDK 调度服本地监听地址与端口 |
+| `public_game_host` | `GAC_PUBLIC_GAME_HOST` | 告知客户端的 Game 网关外部连接地址 |
+| `public_sdk_url` | `GAC_PUBLIC_SDK_URL` | 告知客户端的 Dispatch 调度基础 URL |
+| `launcher.client_path` | `GAC_CLIENT_PATH` | 游戏客户端可执行程序或启动器路径 |
+| `launcher.proxy_path` | `GAC_PROXY_PATH` | 代理软件可执行文件路径 |
+| `launcher.go_command` | `GAC_GO_COMMAND` | 自定义 Go 解释器可执行路径 |
+
+---
+
+### 💖 鸣谢与致敬 (Credits & Acknowledgments)
+
+`GaCy GO` 的成长离不开开源社区与星穹铁道逆向工程先驱者的探索沉淀。我们由衷向以下项目及团队致以最诚挚的敬意与谢意：
+
+<details open>
+<summary><b>🏛️ 服务端架构与协议基础 (Server Architecture & Protocol)</b></summary>
+
+- **PearlSR ([HonkaiSlopRail/pearl-sr](https://git.xeondev.com/HonkaiSlopRail/pearl-sr))**:
+  - 参考 Go 语言服务端模拟器架构设计，提供 Dispatch 分发调度、网关连接管理与底层数据包处理基石。
+  - 上游 Opcode 及 Command ID 定义索引 (`protocol/proto/upstream_cmdids.go`)。
+
+- **LunarCore ([Melledy/LunarCore](https://github.com/Melledy/LunarCore))**:
+  - 由 Melledy 及贡献者开创的 Java 版星穹铁道服务端模拟器 —— 战斗流程状态机、数据包字段结构及抽卡概率模型的行业奠基之作。
+
+- **FreeSR Team**:
+  - 奠定玩家核心数据与库存的 JSON 数据模型规范 (`freesr-data.json`)，用于读取与持久化角色库存档案。
+
+- **March7thHoney ([Mar7thLover/March7thHoney-OpenSource](https://github.com/Mar7thLover/March7thHoney-OpenSource))**:
+  - 高性能 C#/.NET 星穹铁道服务端，在抽卡保底算法、商店机制以及 Muip 远程运维协议设计上提供了重要参考。
+
+- **FFGO ([git.kain.io.vn](https://git.kain.io.vn/))**:
+  - 开源服务端协议研究与参照标杆，在网络工作流阶段流转（Workflow Transitions）及包体兼容性校验上提供了强力参照。
+
+</details>
+
+<details open>
+<summary><b>🎮 玩法模式与逻辑模拟 (Game Modes & Simulation)</b></summary>
+
+- **Currency-War-SR ([xaodev/Currency-War-SR](https://gaytea.cod-algieba.ts.net/xaodev/Currency-War-SR))**:
+  - 在 AGPL-3.0 协议下部分移植（保留于 `third_party/currency-war-sr`）。
+  - 提供 4.6.53 货币战争（自走棋玩法）的核心模拟逻辑架构。
+  - 角色/羁绊矩阵、补给后遭遇战生成算法、难度数值换算与经验成长规则 (`internal/common/currency_wars_xaodev.go`, `internal/gameserver/currency_wars_xaodev.go`, `resources/CurrencyWarsXaodev.json`)。
+
+- **minatoSR ([haltinggoalies/minatoSR](https://github.com/haltinggoalies/minatoSR))**:
+  - 提供了裁决之巅 / 幽影歧路 (Anomaly Arbitration) 全 40 个节点的 NPC 场景坐标与关卡覆盖数据 (`resources/ChallengePeakSceneOverrides.json`)。
+
+</details>
+
+<details open>
+<summary><b>📦 游戏资源与逆向分析工具 (Game Data & Tooling)</b></summary>
+
+- **Dimbreath ([DimbreathBot/TurnBasedGameData](https://github.com/DimbreathBot/TurnBasedGameData))**:
+  - 核心 Excel 数据资产导出 (`ExcelBinOutput`)、哈希校验表与角色、物品、遗器、技能 ID 索引资源。
+
+- **Prydwen Institute ([Prydwen.gg](https://www.prydwen.gg/star-rail/))**:
+  - 提供角色配装养成指南、遗器主副词条推荐及梯队强度评估数据 (`resources/PrydwenRecommendations.json`)。
+
+- **AstralOS ([Ma3-OS/AstralOS](https://gaytea.cod-algieba.ts.net/AstralOS/AstralOS))**:
+  - 高性能协议分析工具箱、IL2CPP 元数据转储器、网络 Hook 框架以及前期架构逆向分析的重要支持工具。
+
+</details>
+
+
+---
+
+## 📜 许可证与修改声明要求 (License & Attribution Notice)
+
+本项目遵循 **Apache License 2.0** 与 **GNU General Public License v3 (GPL-3.0)** 许可证规范，严格执行 **原始出处署名 (Attribution)** 与 **修改内容声明 (State Changes Notice)** 要求。
+
+任何个人或组织若引用、Fork、修改、二次开发或重新分发本项目的任何代码、脚本或工具组件，**必须严格遵守以下条款**：
+
+1. **强制保留原作者署名与原始出处 (Attribution)：**
+   - 必须在项目显著位置明确注明本项目名称，并附带指向本原始仓库的有效链接。
+   - 必须在源码及所有副本中完整保留原有的版权声明、作者名单及原始许可证声明文件。
+
+2. **必须明确注明修改内容与变更记录 (State Changes Notice)：**
+   - 依照 Apache-2.0 第 4(b) 条及 GPL-3.0 第 5(a) 条之规定，**凡对原有文件或代码进行过任何修改、增删、重构或补充的部分，必须在相关文件中附带显著的修改通知（Prominent Notice），明确说明修改了哪些内容及修改时间**。
+   - 严禁隐瞒原作者出处、抹除原作者信息或谎称修改后的衍生版本为独立原创作品。
+
+3. **非商业用途与免责声明 (Non-Commercial Purpose)：**
+   - 本项目仅供网络协议逆向、学术研究与个人学习交流使用，严禁用于任何商业牟利、付费打包或转售行为。