From 1e7b17bca71331e910c20a48353f94088cf1995c Mon Sep 17 00:00:00 2001 From: Bad0RANG3 <110911829+Bad0RANG3@users.noreply.github.com> Date: Sun, 25 Oct 2026 16:13:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BE=8E=E5=8C=96=20README=EF=BC=8C?= =?UTF-8?q?=E8=A1=A5=E6=9E=B6=E6=9E=84=E5=9B=BE=E4=B8=8E=E4=BA=A7=E7=89=A9?= =?UTF-8?q?=E8=A1=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 213 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 159 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index b68dc1c..5873b62 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,90 @@ -# Ichino +
+ Ichino -基于 QR Code 登录的 *某游戏* 客户端，Flutter 实现，覆盖 -Android / iOS / Windows / macOS / Linux。 +

Ichino

-包名 `ichino`，应用标识 `dev.naominet.ichino`。 +

基于 QR Code 登录的「某游戏」客户端 · Flutter

-> ⚠️ 「风险」页里的功能会向服务器发送伪造的 `UpsertUserAllApi` 数据包，属于高危操作， -> 可能封号。请自行评估风险。 +

+ Flutter + Dart + Platform + License + Build +

-## 功能 +

ichino · dev.naominet.ichino · v1.0.0

+
-| 入口 | 说明 | +[功能一览](#功能一览) · [快速开始](#快速开始) · [目录结构](#目录结构) · [架构概览](#架构概览) · [关键实现说明](#关键实现说明) · [构建环境注意事项](#构建环境注意事项) · [CI](#ci) + +> [!WARNING] +> 「风险」页里的功能会向服务器发送伪造的 `UpsertUserAllApi` 数据包，属于高危操作，可能封号。请自行评估风险。 + +## 功能一览 + +| 模块 | 能力 | | --- | --- | -| 主页 | Aime 登录（QR / 令牌）、Rating 详情、入坑信息、游玩统计、状态、账号备份 | -| 票据 | 功能票查询与使用 | -| B50 | Best 50 成绩图，可导出 PNG（移植自 Empurple 的 `Best50ImageRenderer`） | -| 风险 | 歌曲解锁、收藏品获取、旅行伙伴发放与编组（含等级）、修改总 Rating、添加舞里程、一键跑图、万花筒专区 | -| 设置 | Title Server / 机器参数 / Keychip，支持配置导入导出 | -| 连接信息（实验性） | 主页导出 uid + JSESSIONID + token 的 Base64 快照，登录页粘贴即可恢复会话；内容未加密，请勿外传 | -| 账号备份 | 主页只读地把服务器上的用户数据汇成一串 JSON（道具、舞里程、游玩统计、旅行伙伴、区域与万花筒进度、Rating/成绩）。全程只发 `GetUser*Api`，不写任何数据；单段读失败不整体作废，失败段列在结果里 | +| **主页** | Aime 登录（QR / 令牌）、Rating 详情、入坑信息、游玩统计、状态、账号备份 | +| **票据** | 功能票查询与使用 | +| **B50** | Best 50 成绩图，可导出 PNG（移植自 Empurple 的 `Best50ImageRenderer`） | +| **风险** | 歌曲解锁、收藏品获取、旅行伙伴发放与编组（含等级）、修改总 Rating、添加舞里程、一键跑图、万花筒专区 | +| **设置** | Title Server / 机器参数 / Keychip，支持配置导入导出 | +| **连接信息（实验性）** | 主页导出 uid + JSESSIONID + token 的 Base64 快照，登录页粘贴即可恢复会话；内容未加密，请勿外传 | +| **账号备份** | 主页只读地把服务器上的用户数据汇成一串 JSON（道具、舞里程、游玩统计、旅行伙伴、区域与万花筒进度、Rating/成绩）。
全程只发 `GetUser*Api`，不写任何数据；单段读失败不整体作废，失败段列在结果里 | -## 开发 +### 风险页 + +| 功能 | 说明 | +| --- | --- | +| 歌曲解锁 | 写入 itemKind 5 / 6 / 7，分别对应歌曲、Master、Re:Master | +| 收藏品获取 | itemKind 1 / 2 / 3 / 10 / 11 / 12：姓名框、称号、头像、搭档、背景板、功能票 | +| 旅行伙伴 | 发放角色、修改等级、编辑出战编组（`UserDetail.charaSlot`） | +| 修改 Rating | 只改总 Rating（0 ~ 99999），不动每首歌各自的 Rating | +| 添加舞里程 | 直接写 `UserDetail.point`，支持累加与直接设定，可为负 | +| 一键跑图 | 把区域 `distance` 推到上限，完成态交给客户端派生 | +| 万花筒 | 发现门、获取钥匙、标记通关，三者都在同一行 | + +## 快速开始 + +### 环境要求 + +- Flutter **stable**（开发验证版本 3.47.8 / Dart 3.13.7；`pubspec.yaml` 要求 `sdk: ^3.12.0`） +- 各平台常规工具链：Android SDK 与 JDK 17、Xcode、Visual Studio（C++ 桌面开发）、CMake / Clang +- Windows 上构建前请先看[构建环境注意事项](#构建环境注意事项) + +### 运行 ```bash +git clone https://github.com/AirFoundation/Ichino.git +cd Ichino flutter pub get flutter run # 默认设备 +``` + +提交前请保持质量门槛： + +```bash flutter analyze # 需保持 0 error/warning flutter test ``` -构建产物： +### 构建 -```bash -flutter build apk --release # Android -flutter build windows --release # Windows（产物为 ichino.exe） -flutter build macos --release # macOS -flutter build linux --release # Linux -flutter build ios --release --no-codesign # iOS（无证书时只验证可编译） -``` +| 平台 | 命令 | 产物 | +| --- | --- | --- | +| Android | `flutter build apk --release` | `build/app/outputs/flutter-apk/app-release.apk` | +| Windows | `flutter build windows --release` | `build/windows/x64/runner/Release/ichino.exe` | +| macOS | `flutter build macos --release` | `build/macos/Build/Products/Release/Ichino.app` | +| Linux | `flutter build linux --release` | `build/linux/x64/release/bundle/` | +| iOS | `flutter build ios --release --no-codesign` | `build/ios/iphoneos/Runner.app`（未签名） | + +> [!NOTE] +> Release APK 目前使用 debug 签名（`android/app/build.gradle.kts` 的 `signingConfig`），产物可直接安装，但不是正式发布签名。 ## 目录结构 -``` +```text lib/ ├── main.dart # 入口（MyApp + MaterialApp） ├── config/ # 字符串、响应式布局、Title Server 配置 @@ -59,7 +102,8 @@ tools/ # 离线开发工具（不参与构建产物） data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽出的 ID 映射表 ``` -### 共享抽象 +
+共享抽象：风险页与通用组件收口 功能票 / 解锁歌曲 / 收藏品 / 旅行伙伴 / 数值修改 / 一键跑图 / 万花筒 / 高危 hub 这些页面以前各抄一份脚手架，现已收口到： @@ -82,6 +126,8 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 - `services/user_all_payload_builder.dart` — 占位 `musicData`（`placeholderMusicData`）。 - `services/api_log.dart` —`ApiLog`：传输层日志，仅 debug 输出，release 下不落 token/cookie。 +
+ 主页的六个页签由 `HomeTab` 枚举驱动，`IndexedStack` 只构建访问过的页签， 票据 / B50 / 风险 hub 不会再在启动时各自发一轮请求。 `TitleApiService.lastRawResponse` 是实例状态，`SessionModel` 把预览原文透传给主页调试卡，不会跨请求串数据。 @@ -90,8 +136,37 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 `SceneDelegate` 通过 `dev.naominet.ichino/qr_scanner` 这个 MethodChannel 提供， 桌面平台没有该 handler，因此从图片识别二维码仅在移动端可用。 +## 架构概览 + +```mermaid +flowchart TB + subgraph PAGES["页面"] + Login["登录页"] + Home["主页 / 票据 / B50"] + Risk["风险页"] + end + + Login --> ApiService["ApiService
扫码登录"] + ApiService --> AimedbTransport["AimedbTransport
Windows: WinHTTP · 其他: HttpClient"] + AimedbTransport --> Aimedb[("aimedb")] + + Home --> Session["SessionModel
uid · token · Cookie"] + Risk --> Session + Session --> TitleApiService["TitleApiService
MD5 路由 · ZLib · AES-CBC"] + TitleApiService --> Title[("Title Server")] +``` + +- `SessionModel` 是会话与 Cookie 的唯一持有者；Cookie 轮换经 `onCookiesChanged` 回写。 +- `TitleApiService` 统一生成路由、编解码与用户可读的错误文本，页面不自己拼传输层。 +- 扫码登录走独立的 `ApiService` / `AimedbTransport`，与游戏服务器的 Title Server 链路分开。 + ## 关键实现说明 +以下内容是真机行为与客户端代码对齐后的结论，排查「上传成功但没生效」时优先看这里。 + +
+登录与传输：aimedb 签名、TLS 指纹与 WinHTTP + - **扫码登录**：`ApiService` 对齐 Astral 的 `api/Chime.py` —— 端点与签名盐写死在代码里 （`https://ai.sys-allnet.cn/wc_aime/api/get_data`），签名是 `SHA-256(完整 Keychip + 本机本地时间 + 签名盐)`，请求体带 `titlekey: SDGB`， @@ -99,12 +174,38 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 带了 aimedb 直接回 `errorID=57`。输入既可以是 84 位二维码串，也可以是 `wq.wahlap.net/qrcode/req/….html` 二维码链接；Keychip 设置里填 11 位短值也能用， 会按 placeId 补成完整形式（扫码登录用完整形式，游戏服务器才用短值）。 +- **登录传输**：`AimedbTransport` 在 Windows 上走 WinHTTP FFI（`dart:ffi` + + `Isolate.run`），其他平台走 Dart `HttpClient` 并手动补上服务器缺失的 GlobalSign + 中间证书。这么做是为了绕开服务器对 Dart/BoringSSL 的 TLS 指纹拦截——握手能被接受， + 但连接紧接着被服务端关掉；证书校验本身始终开启。 - **传输层**：`TitleApiService` 负责 `MD5(apiName + salt + obfuscateParam)` 生成 URL 路径、 JSON → ZLib → AES-CBC 编解码、`Set-Cookie` 会话维持。 + +
+ +
+B50：固定像素版面与导出分辨率 + - **B50 成绩图**：底图 `assets/b50/base.png`（1762×1850）之上按固定像素坐标叠加头像、 昵称、50 张卡片与页脚；卡片 300×100、每行 5 张，BEST35 从 y=350 起、BEST15 固定从 y=1250 起。RA 与评级由 `RatingCalculator` 计算，曲名与定数取自 diving-fish 的 `music_data`。导出走 `RepaintBoundary`，预览缩放不影响导出分辨率。 + +
+ +
+写包语义：isNew*List、角色、舞里程与总 Rating + +- **`isNew*List` 每一位都是插入/更新标志，不能一律发 '1'**：真机 + `VOExtensions.BuildListData`（:335-355）拿本地新列表与服务器快照做 + `Except()` 增量，再按「服务器是否已有同主键行」给每位填 '0'（更新）或 + '1'（新增）。主键分别是 characterId / mapId / gateId / + **(itemKind, itemId)** / **(musicId, level)**。所以我们所有 patch 都要先回读 + 服务器状态再算这一串——`userItemList` 那处原先硬写全 '1'，重复解锁一首 + 已存在的歌时会被服务器判成插入冲突丢掉，表现为「上传成功但没生效」， + 现在改成先 `GetUserItemApi` 回读再算标志位。 + `GetUserItemApi` 是**按 itemKind 分页**的，首次请求的 `nextIndex` 要按 + `itemKind * 1e10` 编码（`PacketGetUserItem.cs:19`），发 0 只会拿到空页。 - **旅行伙伴 ≠ 搭档**：旅行伙伴是 `ItemKind.Character = 9`，走 `upsertUserAll.userCharacterList`（`{characterId, level, awakening, useCount}`）； 搭档是 `ItemKind.Partner = 10`，走 `userItemList`。出战编组是 @@ -117,6 +218,10 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 `GetUserCharacterApi`，用来区分「服务器没写入」与「写入了但机台不认这个 ID」。 角色的 `awakening` 由客户端从 `level` 反推（`UserChara.CalcLevelToAwake`）， 读回时并不取服务端值。 +- **旅行伙伴等级**：真实等级区间 `1 ~ 999999`，界面显示的等级是 `level % 10000`、 + 转生次数是 `level ~/ 10000`，所以 `999999` = 99 转生 + 9999 级。给已有角色改等级要发 + `isNewCharacterList` 对应位为 `'0'` 的更新行（`'1'` 是插入），且必须带上原有 + `useCount`，否则整行覆盖会把使用次数清零。 - **舞里程 = `UserDetail.point`**（余额），`totalPoint` 是累计获得量。客户端只在 「获得」时钳到 99999（`UserDetail.AddMile`），商店扣款走不带钳位的 `Point -= cost`，展示是裸的 `num.ToString()`，所以直接写更大的值不会被覆回。 @@ -127,16 +232,12 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 `0 ~ 99999`。`ratingList` / `newRatingList` 里每首歌各自的 Rating 原样带回， 不重排也不改值。占位 playlog 的 `before/afterRating`（及 `DeluxRating`）一起对齐成 新写的值，否则存档里那条记录与 `playerRating` 自相矛盾。 -- **`isNew*List` 每一位都是插入/更新标志，不能一律发 '1'**：真机 - `VOExtensions.BuildListData`（:335-355）拿本地新列表与服务器快照做 - `Except()` 增量，再按「服务器是否已有同主键行」给每位填 '0'（更新）或 - '1'（新增）。主键分别是 characterId / mapId / gateId / - **(itemKind, itemId)** / **(musicId, level)**。所以我们所有 patch 都要先回读 - 服务器状态再算这一串——`userItemList` 那处原先硬写全 '1'，重复解锁一首 - 已存在的歌时会被服务器判成插入冲突丢掉，表现为「上传成功但没生效」， - 现在改成先 `GetUserItemApi` 回读再算标志位。 - `GetUserItemApi` 是**按 itemKind 分页**的，首次请求的 `nextIndex` 要按 - `itemKind * 1e10` 编码（`PacketGetUserItem.cs:19`），发 0 只会拿到空页。 + +
+ +
+曲目、区域与万花筒：选曲池、DX 解锁、跑图与门钥匙 + - **一首歌能不能出现在选曲界面，和用户包无关**：`NotesListManager.cs:70` 只在 `IsOpenEvent(musicData.eventName.id) && !IsGameNgMusicId(id)` 时才把这首歌 放进全局曲池 `_notesList`。事件窗口来自服务器 `GetGameEventApi` @@ -155,6 +256,16 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 `ScoreDic` 那个长度固定 6 的数组越界。 `musicId >= 100000` 才有 `level → 10` 的重写（宴曲， `ConstParameter.UtageDifficultyId`），与 DX 段无关。 +- **一键跑图只发得动「完成态」**：区域进度是 `upsertUserAll.userMapList`，行结构 + `{mapId, distance, isLock, isClear, isComplete, unlockFlag}`，主键 mapId。 + `isClear` / `isComplete` 在客户端是从 `distance` 派生的 + （`MapMaster.CreateUserDataMapList` 拿 distance 与该区域的 ReleaseFlag / End + 里程针比较，没有对应针时甚至强制写回 false），所以单发 flag 下次进区域选择页就被冲掉； + 这里把 `distance` 直接推到 `UserMapData.MaxDistance = 999999999`。`unlockFlag` + 语义是反的（`IsFinishedOpening ? 0 : 1`，取 0 才是已开启），`isLock` 客户端根本不回读。 + **该区域的收藏品发不了**：`区域 → 宝藏 → 物品` 的对应关系在机台的 `Map.xml` / + `MapTreasure.xml` 里（`DataManager.LoadMaps` / `LoadMapTresures` 从本地数据目录读， + 不经 title server），App 没有这份表，页面里也明写了这个限制。 - **万花筒的门、钥匙、通关在同一行**：`upsertUserAll.userKaleidxScopeList`， `UserKaleidxScope` 共 15 个字段、主键 `gateId`，「发现门」是 `isGateFound`、 「获取钥匙」是 `isKeyFound`、「已通关」是 `isClear`。钥匙**不走** @@ -173,20 +284,8 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 合法 `gateId` 只存在于机台的 `KaleidxScopeGate.xml`，代码里除了 `ForceAddMasterKey` 写死的 `gateId = 7`（万能钥匙门）以外没有任何清单， 而且还要该门绑定的活动处于开启状态才会显示。 -- **旅行伙伴等级**：真实等级区间 `1 ~ 999999`，界面显示的等级是 `level % 10000`、 - 转生次数是 `level ~/ 10000`，所以 `999999` = 99 转生 + 9999 级。给已有角色改等级要发 - `isNewCharacterList` 对应位为 `'0'` 的更新行（`'1'` 是插入），且必须带上原有 - `useCount`，否则整行覆盖会把使用次数清零。 -- **一键跑图只发得动「完成态」**：区域进度是 `upsertUserAll.userMapList`，行结构 - `{mapId, distance, isLock, isClear, isComplete, unlockFlag}`，主键 mapId。 - `isClear` / `isComplete` 在客户端是从 `distance` 派生的 - （`MapMaster.CreateUserDataMapList` 拿 distance 与该区域的 ReleaseFlag / End - 里程针比较，没有对应针时甚至强制写回 false），所以单发 flag 下次进区域选择页就被冲掉； - 这里把 `distance` 直接推到 `UserMapData.MaxDistance = 999999999`。`unlockFlag` - 语义是反的（`IsFinishedOpening ? 0 : 1`，取 0 才是已开启），`isLock` 客户端根本不回读。 - **该区域的收藏品发不了**：`区域 → 宝藏 → 物品` 的对应关系在机台的 `Map.xml` / - `MapTreasure.xml` 里（`DataManager.LoadMaps` / `LoadMapTresures` 从本地数据目录读， - 不经 title server），App 没有这份表，页面里也明写了这个限制。 + +
## 构建环境注意事项 @@ -211,10 +310,12 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 `.github/workflows/build.yml` 在 push / PR / 手动触发时执行： -- `checks`：`flutter analyze` + `flutter test`，作为其余作业的前置门槛 -- `android`：`app-release.apk` -- `windows`：`ichino-windows-x64.zip`（含 `ichino.exe` 及运行所需 dll/assets） -- `ios`：`ichino-ios-unsigned.ipa` +| 作业 | 运行环境 | 产物 | +| --- | --- | --- | +| `checks` | ubuntu-latest | `flutter analyze` + `flutter test`，作为其余作业的前置门槛 | +| `android` | ubuntu-latest | `ichino-android-apk`（`app-release.apk`） | +| `windows` | windows-latest | `ichino-windows-exe`（内含 `ichino-windows-x64.zip`） | +| `ios` | macos-latest | `ichino-ios-unsigned-ipa` | 产物以 artifact 形式上传。**注意 iOS 包是未签名的**：GitHub 托管的 macOS runner 没有 证书与描述文件，该 ipa 只能用于验证编译，无法直接安装到设备。要出可安装的 ipa，需要在 @@ -225,3 +326,7 @@ data/id_mapping/ # 由 tools/gen_id_mapping.dart 从机台数据包抽 - 图标与封面资源：assets2.lxns.net - 乐曲定数与曲名：diving-fish - B50 版面与本作 UI：chuxuehaocai + +## 许可证 + +本项目以 [MIT](LICENSE) 许可证发布。