game-client-to-server-reverse
从游戏客户端(安装包/APK/IPA/EXE 或 dump.cs、lua、usmap、抓包等)反推服务端协议并复现可部署服务端。含阅读路径分派、原理层(primer:三要素/数据包协议/协议表/热更源码)、四阶段路线图(workflow-roadmap:静态分析→建工具+登录链→重定向→补包循环→清单迭代)、11 种反推方法选择器(含内联服务端路线)、接口清单提取器(tools/)、协议规格模板(protocol.spec.yaml)、wire 级定点改写(不等 schema 齐就能跑)、客户端地址来源清查、三轴状态与验收体系、发布运维清单、进度清单(T
Install
npx skills add https://github.com/ShrugYu/game-client-to-server-reverse/tree/main/game-client-to-server-reverse
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install shrugyu-game-client-to-server-reverse@llmmart
git clone https://github.com/ShrugYu/game-client-to-server-reverse.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole shrugyu/game-client-to-server-reverse collection as a plugin from our marketplace. Git is the plain clone.
README
游戏客户端 → 离线本地化 Skill
完整支持 Unity(IL2CPP / Mono / Lua) 与 Unreal Engine(UE4 / UE5),也覆盖 C#/AS3/Lua/JS/Java 等各类客户端。 从客户端反推服务端协议 → 复现本地离线服务端 → 部署 → 让原版客户端本地离线运行。
[x] 本包自带的服务端已实测跑通:握手 → 登录 → 建角 → 选角 → 进场景 → 移动 → 心跳, 并验证 XOR 加密 + zlib 压缩 + 充值/邮件发放。
服务端参考实现原Github地址:https://github.com/Nanako660/peach-haven
2026-09-22 更新(v2.0) —— 本版主题:原理层 + 四阶段路线 + 换服务端(重定向): ⓪ 版本升至 2.0:整合 1.x 全部成果 + 以下 ①⑪; ① 原理层
references/primer.md:三要素(配置=数值 / 协议=格式 / 代码=用法)、 数据包协议本质、协议号与协议表、热更新代码是比 dump 更好读的源码; ② 四阶段路线总纲references/workflow-roadmap.md(静态分析 → 建工具+登录链 → 重定向 → 补包循环 → 清单迭代)+ 四层重定向表; ③ 模板:templates/login-chain.md(登录链条)、templates/function-checklist.md(功能清单); ④ SKILL §0 开头新增阅读地图(三条主线); ⑤ 反推对象地图references/server-architecture-basics.md(逆向视角):你在还原哪几类服、 网关留下的隐藏层(合并/加解密/压缩 flag)、从包里认 Protobuf/KCP、同步模型决定"要还原多少逻辑" (来源:平台云架构演进、GameDevAndOps、KCP/protobuf 官方、Skynet/Pomelo/KBEngine/NF); ⑥ 取长补短(折进现有文件):methods.mdM8 补入现成实现速查(按类型) + "先查别人做过没" + 先锁版本;protocol-spec.md补入人类可读协议文档格式; ⑦ SKILL.md 瘦身:与 references 重复的 §1§8、§11、§14~§19 压成"要点+指针"(1122 → ~650 行);§11 常见坑并入closure-verification.md §附; ⑧ 跨模型阅读优化(GLM / DeepSeek / Claude):SKILL 顶部改为模型无关的显式阅读协议("打开哪个文件"写死); 去掉顶部大段变更历史;给 5 篇 >300 行的 reference 补章节目录;reading-path.md顶部声明按它分派; ⑨ 去除 emoji:全库清理(状态标记转 ASCII、装饰 emoji 删除、箭头保留); ⑩ 框架修正 + 资源:§0改为"主动改客户端对接本地离线服务端"(按重定向四层表、优先跑起来); ⑪ 换服务端手法补全(v2.0 新增):client-address-sources.md §3.0b加入 Xposed / LSPatch 模块重定向 (第三方代理模块实测范例,免 root);methods.mdM8 加"多人/联机复活项目"检索入口; ⑫ 签名绕过:repack-rename.md §8加入 LSPatch Signature Bypass(等级 2)机制 / 独立签名破解 (ApkSignatureKiller/ 核心破解) / 真正不改签名的虚拟容器(VirtualXposed / 太极);§7 落点表述改为"按代价从低到高"; 接入点:account.md §6、release-and-ops.md §7、SKILL §16;2026-09-15 实战沉淀(v1.8 新增): ⑬ 内联服务端:不起外部服务端,在客户端进程内拦截网络门面合成响应 (三类入口 / 回调投递纪律 / 延迟派发 / 双通路 / 内联版验收与假阳性)→
references/inline-server.md⑭ 运行时对象合成与字段发现:用客户端自己的类型系统当 schema,先 dump 再合成 →references/runtime-object-synthesis.md⑮ 平台 SDK 登录态复用 + 目录服→区服两段准入 →references/platform-sdk-and-admission.md⑯ 真实案例:Unity IL2CPP + 平台 SDK 的内联服务端 →references/case-il2cpp-inline.md2026-09-13 实战沉淀(新增): ② 改包名 / 重打包 / 保留原签名全清单 →
references/repack-rename.md④ 闭环验证与 6 类假阳性(端口在听≠服务可用、自环≠客户端兼容)→references/closure-verification.md⑤ 真实案例:Unity IL2CPP + ECDH 登录服(帧格式 / SPKI / 已证伪项)→references/case-il2cpp-ecdh.md⑥ SKILL 铁律 3 → 4 条:不把「能跑」当成「跑通」 ⑦ 工程范式(实机跑通项目的做法:fixture 回放 / 具名完成点 / 证据分档 / ADR)→references/engineering-practices.md⑧ 文档模板:templates/adr-template.md、templates/e2e-evidence-template.md⑨ 实现层核心:不依赖 protobuf 运行时的 wire 级定点改写(帧 codec + 字段遍历 + splice 替换 + 空子消息必须保留)→references/wire-level-patching.md⑩ 客户端地址来源清查(六类来源 + 落点优先级 + 重签后果 + 阶段验收)→references/client-address-sources.md⑪ 三轴状态与验收体系(实现 / 自动测试 / 客户端验收 + 可达性五分类 + 提交门禁)→references/verification-and-status.md⑫ 发布、部署与运营(监听 vs 对外地址 / 端口族 / 启动期冻结配置 / CDN 版本策略 / 备份)→references/release-and-ops.md
目录映射(本 skill 的结构)
本 skill 遵循 Agent Skills 规范:一个文件夹 = 一个 skill,且 frontmatter 的
name必须与文件夹名一致。本文件夹即game-client-to-server-reverse/;内部目录是对规范约定目录的映射。
| 规范约定 | 本 skill 实际 | 说明 |
|---|---|---|
SKILL.md |
SKILL.md |
必需:元数据 + 主干(已瘦身到 < 500 行,符合规范建议) |
references/ |
references/ |
按需加载的详细文档(正文下沉于此) |
assets/ |
templates/、schema/、server/ |
模板 / 中间产物模板 / 可运行参考实现 |
scripts/ |
tools/ |
可执行脚本(extract_interfaces.py / `` / repack_zip.py) |
| — | examples/、extensions/ |
推演示例 / 可选拓展 |
阅读顺序:
SKILL.md(导航+主干)→references/reading-path.md(按任务分派)→ 按需打开具体文件。
先读什么(别一次读完整包)
本包有 37 篇参考 + 一份长主文档。通读完再动手 = 上下文耗尽 + 在半懂的地方开始猜。
1. references/reading-path.md ← 按任务类型拿到 3~5 个文件的阅读路径
2. SKILL.md §0.0 ~ §0.6 ← 方法选择 + 铁律 + 工作流主干
3. 按路径读完场景层文件 → 动手
收工前:reading-path.md §2 的「收工前检查」
上下文极少时的优先级:
SKILL §0 → reading-path.md → wire-level-patching.md → closure-verification.md → client-address-sources.md
skill 是查询手册,不是必读教材。
如何使用本 Skill
一句话
把游戏(安装包 / 客户端 / 辅助文件)交给 AI,说清「要什么」, AI 会自己取证 → 产出协议规格 → 生成并部署本地离线服务端 → 让客户端本地离线运行。
你最少只需给一样
| 给什么 | 推荐度 | AI 会做什么 |
|---|---|---|
一个安装包(.apk / .ipa / .exe) |
最推荐 | 自己解包、判引擎、跑 dump、抓包(见 references/from-installer.md) |
客户端目录 / dump.cs / *.lua / *.usmap |
直接进静态分析 | |
抓包 *.pcap / mitm 导出 |
直接做协议分层 | |
| 已有服务端样本 / 协议文档 | 对照分析 | |
| 只有一个游戏名 | [x] | 没有证据,建议先提供安装包 |
提问模板(直接复制改)
① 最简
帮我反推这个游戏的服务端:/文件路径/game.apk
② 带目标
用这个 APK 反推服务端协议,先跑通登录,然后部署到本地。
③ 带约束
这是 Unity 手游,服务端请分析根据当前用户给出客户端来用什么编写(如Go编写),要支持局域网联机链接到我们当前写的服务端上,先做协议分析.md文档再写代码。
④ 指定阶段
先别写代码,只做协议分层,产出 protocol.spec.yaml 和证据清单。
一个好提问包含 4 个要素
| 要素 | 说明 | 例子 |
|---|---|---|
| 输入 | 你给什么 | game.apk / dump.cs / capture.pcap |
| 目标 | 做到哪一步 | 只分析 / 跑通登录 / 完整服务端+部署 |
| 约束 | 语言/平台/版本 | Go / 安卓局域网 / 客户端 1.8.1 |
| 环境 | 跑在哪 | 本地 / 云服务器 / Termux |
缺哪个都行,AI 会用占位符推进;但输入最好给一个。
AI 会按这个顺序回应(重要)
1. project-profile.yaml ← 我读了什么、还缺什么 (项目档案)
2. evidence-inventory ← 每条结论的证据 + 置信度 (证据清单)
3. protocol.spec.yaml ← 协议规格(唯一事实来源)
4. 服务端代码 + 部署 + 验证 ← 由 Spec 派生
注意: 如果 AI 直接甩给你一堆代码,却没有前 3 样,让它重来。 「先规格,后代码」是本 skill 的硬性要求(见
references/ai-contract.md)。
另有两份"开工/收工"契约(详见 references/ai-contract.md):
AGENTS.md ← 工作区边界 + 验证命令 + 收工状态(放在项目根)
docs/status/support-matrix ← 三轴状态:实现 / 自动测试 / 客户端验收
可以这样追问
- 「先给我证据清单」
- 「先只做协议分层」
- 「为什么判定是 4 字节大端?证据是哪条?」
- 「服务端换成 Go 重写」
- 「把 opcode 表填进去」
- 「客户端连不上,帮我定位是哪一步」
- 「先把账号/登录接口列出来,登记到 TRACKER」
常见问题指路
| 问题 | 看哪 |
|---|---|
| 不懂"在反推什么"/第一次做 | references/primer.md(原理层) |
| 不知道先做什么、在哪验收 | references/workflow-roadmap.md(四阶段路线) |
| 只有安装包怎么办 | references/from-installer.md |
| 怎么注册账号 / 替换登录接口 | references/account.md(§16) |
| 需要人机(假玩家) | extensions/(§18,可选) |
| 不想起服务端 / 想单机化 | references/inline-server.md(M11 内联服务端) |
| 进度/接口清单 | TRACKER.md |
不要这样问
- 只给游戏名就让 AI 凭空写服务端 —— 没有证据 = 必错
- 「直接给我能用的服务端」却不给任何输入
使用守则与限制
完整守则见
references/usage-policy.md;每次动手前先读。
可做(允许):自研 / 已授权 / 离线单机目标的互操作性研究、协议文档化、学习与教学、已停服游戏的本地化存档(非商业)、授权范围内的安全评估。
不做(禁止):未授权架设 / 运营他人游戏的服务器、绕过或破坏他人的技术保护 / 完整性校验 / 反作弊、商业化牟利、侵犯他人权益、破坏性攻击。
硬性约束:证据驱动(无证据 = 假设)、先规格后代码、只给方法不给具体游戏的成品 / 密钥、不提供保护绕过、fail closed(缺信息就说缺什么)、越界即停并给出合规替代。
- 使用参考项目 / 代码前先看其许可证。
目录结构
离线本地化/
├── SKILL.md 主流程(18 节,核心方法论)
├── README.md 本文件
├── TRACKER.md 进度与接口清单(每模块更新,从简)
├── schema/ 中间产物模板(AI 填这些)
│ ├── project-profile.yaml 项目档案
│ └── protocol.spec.yaml 协议规格(唯一事实来源)
├── references/
│ ├── adaptation.md 自适应方法论:项目→证据→决策→Spec
│ ├── reading-path.md 最小必读路径(按任务类型分派)
│ ├── primer.md 原理层:三要素/数据包协议/协议表/热更源码/双证据链
│ ├── workflow-roadmap.md 四阶段路线总纲(静态分析→建工具+登录链→重定向→补包循环→清单迭代)
│ ├── phases-detail.md §1~§10 反推主流程详细版(命令/工具/判断/坑)
│ ├── ai-contract.md AI 行为契约(强制产物/禁止/终点/回滚)
│ ├── usage-policy.md 使用守则与限制(允许/禁止用途 + 硬性约束 + 自检)
│ ├── server-architecture-basics.md 反推对象地图(逆向视角:你在还原哪几类服/网关隐藏层/同步模型)
│ ├── methods.md 10 种反推方法 + 选择矩阵(动手前先看)
│ ├── closure-verification.md 闭环验证 6 类假阳性(宣布成功前必看)
│ ├── engineering-practices.md 实机跑通范式:fixture 回放 + 完成点 + 证据分档 + ADR
│ ├── wire-level-patching.md 实现层核心:不依赖 pb runtime 的 wire 级定点改写
│ ├── client-address-sources.md 客户端地址来源清查 + 落点策略
│ ├── verification-and-status.md 三轴状态 + 可达性分类 + 测试门禁
│ ├── release-and-ops.md 发布 / 部署 / 运营 / CDN / 备份
│ ├── case-il2cpp-ecdh.md 真实案例:IL2CPP + ECDH 登录服 + 卡点复核
│ ├── inline-server.md 内联服务端:进程内合成响应(与外部服务端并列的第二条路)
│ ├── runtime-object-synthesis.md 运行时对象合成与字段发现(对象级 schema 自举)
│ ├── platform-sdk-and-admission.md 平台 SDK 登录态复用 + 目录服→区服两段准入
│ ├── case-il2cpp-inline.md 真实案例:IL2CPP + 平台 SDK 的内联服务端
│ ├── account.md 账号体系与接口还原(登录/注册/接口替换)
│ ├── combat.md 房间与战斗(局内、同步模型、服务端权威)
│ ├── drops.md 掉落与物资(掉落表、掷骰、背包满转邮件)
│ ├── gacha.md 抽卡/扭蛋(服务端掷骰、保底、重复转换)
│ ├── decision-tree.md 逐层决策树(引擎/传输/封装/加密/序列化/架构)
│ ├── protocol-spec.md 协议规格规范 + codegen 映射
│ ├── codegen.md 由 Spec 生成/改造服务端(多语言)
│ ├── client-languages.md 客户端语言分支(C#/AS3/Lua/JS/Java/C++)
│ ├── from-installer.md 零输入自举:只有安装包怎么自产证据
│ ├── cases.md 两个真实成功项目案例(Go / Node)
│ ├── unity.md Unity(IL2CPP/Mono/Lua) 深潜
│ ├── unreal.md Unreal(UE4/UE5) 深潜
│ ├── windows.md 端游:Windows 运行服务端
│ ├── termux.md 手游:Android/Termux 运行服务端
│ └── repack-rename.md 改包名/重打包/签名/包名派生密钥
├── examples/ 推演示例(同 skill,不同项目→不同方案)
│ ├── A-unity-il2cpp-protobuf.md
│ ├── B-ue-kcp-custom.md
│ ├── C-unity-lua-http.md
│ └── D-real-lua-client.md 真实 Lua 源码分析(1794 个 opCode)
├── tools/
│ └── extract_interfaces.py 接口清单提取器(扒 opCode/路由)
├── templates/ 参考代码与文档模板
│ ├── mock_server.py 极简桩
│ ├── frida_bypass_ssl.js / kcp_sniff.py
│ ├── frida-redirect.js 客户端重定向:hook getaddrinfo/connect(native/il2cpp)
│ ├── xposed-redirect/ LSPosed 模块骨架:改写 URL(Java/OkHttp 客户端)
│ ├── register-site/ 注册网站(index.html + 最小 Flask 后端)
│ ├── AGENTS.md 工作区 AI 协作契约(放在项目根)
│ ├── adr-template.md 架构决策记录(含「当前不做的事情」+ 回滚)
│ ├── e2e-evidence-template.md 实机端到端证据(帧序表 + 差异解释 + 重连快照)
│ ├── status-matrix.md 三轴状态矩阵(实现 / 测试 / 客户端验收)
│ ├── login-chain.md 登录链条文档(启动到主场景每一步)
│ └── function-checklist.md 功能清单(按子系统登记实通/未通)
├── extensions/ 后续拓展(可选,不影响核心运行)
│ ├── README.md 拓展说明与判断标准
│ ├── bots.md 服务端人机(假玩家)
│ └── bot-reverse.md 反推人机机制再复刻
└── server/ 参考实现:长连接二进制协议服务端(Python)
(GitHub: https://github.com/ShrugYu/game-client-to-server-reverse/tree/main/game-client-to-server-reverse/server)
端游 / 手游怎么跑
| 平台 | 启动 | 常驻 | 客户端对接 |
|---|---|---|---|
| Windows(端游) | deploy/start_windows.bat |
NSSM 服务 | 改 hosts → 127.0.0.1 |
| Android(手游) | bash start_termux.sh |
wake-lock + tmux | hosts / DNS 重定向 |
| Linux 服务器 | deploy/deploy.sh |
systemd | 域名解析 / 端口转发 |
| Docker | docker compose up -d |
容器策略 | 同上 |
客户端语言不只有 Unity/UE
| 客户端语言 | 反编译工具 | 能拿到源码? | 客户端补丁方式 |
|---|---|---|---|
| C#(Unity Mono / .NET) | dnSpy / ILSpy | [x] 近源码 | 配置 / 重编译 / hook |
| C#(Unity IL2CPP) | Il2CppDumper + IDA | [x] 仅签名 | Frida hook |
| ActionScript3 / Flash | JPEXS FFDec | [x] 反编译 | 改源码重编译 |
| Lua 热更 | unluac / luadec | [x] | 改 lua |
| Java/Kotlin | jadx | [x] | smali patch / hook |
| JS / H5 | beautify / sourcemap | [x] | 改 js |
| C++ / UE | SDK dump | 注意: 结构 | hook / patch |
详见 references/client-languages.md。
真实项目案例(Go 服务端 + C# 启动器;Node/TS 服务端 + AS3 客户端)见 references/cases.md。
服务端语言也不固定
Python 只是本仓库的参考实现。真实案例里:Go(某 Unity 手游)、Node/TS(某 Cocos 手游)。
选型见 references/codegen.md,由 Spec 决定,不是照抄。
充值 / 发放(自托管支付)
game.pay_grant_mode:direct(直接进背包)/mail(发邮件领取)game.pay_auto_success: true→ 点击购买直接成功- 商品表
PAY_PRODUCTS键 = 客户端真实product_id
后续拓展(可选,不影响核心运行)
判断标准:去掉它,游戏还能不能正常玩?能 → 就是拓展。
注意: 内联服务端不是拓展:它是与「外部服务端」并列的核心路线(M11,见
references/inline-server.md), 不适用本判断标准。
| 拓展 | 文件 | 一句话 |
|---|---|---|
| 服务端人机(假玩家) | extensions/bots.md |
多人游戏凑不齐人时用 AI 补位 |
| 反推人机机制 | extensions/bot-reverse.md |
无参考项时,从客户端反推它的人机实现 |
人机为什么是拓展:单人也能玩的游戏完全不需要;多人游戏缺人只是体验受损, 服务端本身能跑,不影响「本地离线运行 / 登录 / 进游戏」。
- 参考骨架:
server/app/logic/bots.py(只是骨架,默认auto_fill: 0不生成假玩家) - 联调:
python server/test_bots.py
注意: 拓展不参与核心验收。没做拓展 ≠ 交付不完整。
两种服务端模板怎么选
| templates/mock_server.py | server/ | |
|---|---|---|
| 用途 | 抓包后快速验证协议结论 | 真正部署、长期运营 |
| 规模 | 单文件 | 分层工程 |
| 能力 | 帧收发 + opcode 桩 | 数据库/状态机/客户端保护/部署 |
| 何时用 | 逆向中期试探 | 逆向完成、要跑起来 |
最快上手
# 1. 起服务端
cd server && chmod +x start.sh && ./start.sh
# 2. 联调自测(另开一个终端)
./venv/bin/python client_test.py --host 127.0.0.1 --port 8888 \
--user alice --password 123456 --name Hero01
# 期望输出结尾:[+] full flow OK
# 3. 部署到服务器
sudo bash server/deploy/deploy.sh
工作流
[只有安装包?] 解包 → 判引擎/语言 → 自产 dump/lua/资源 → 抓包 → 动态dump
↓
侦察引擎 → 协议分层 → 客户端静态定位 → 字段推断
→ 服务端建模 → 部署 → 客户端对接 → 闭环验证
只有
.apk/.ipa/.exe也能开始 —— 见references/from-installer.md。
给 AI 的使用方式
- 把辅助文件(
dump.cs/*.lua/*.usmap/ SDK.h)丢进来。 - AI 按
SKILL.md §1分类,自动进入 Unity 或 UE 分支。 - 逆向结论落到
server/app/proto/(消息号 + 结构)与config.yaml(协议参数)。 - 起点验证用
templates/mock_server.py,终点交付用server/。
免责声明
使用本资料库skill即表示你已阅读、理解并同意以下全部条款;若不同意,请立即停止使用。
用途限定:本 skill 资料仅供学习、研究与技术交流,以及针对自研、已获授权或离线单机游戏的互操作性研究与本地化部署。这是一份方法论文档,不针对任何特定特定项目。
禁止非法用途:严禁将本资料用于任何未经授权的入侵、攻击、破坏、篡改、绕过安全机制、窃取数据,或侵犯他人知识产权、违反目标游戏服务条款及所在地法律法规的行为。
无担保:本资料按"现状(as-is)"提供,不附带任何明示或暗示的担保,包括但不限于适销性、特定用途适用性与不侵权担保。作者不保证其准确性、完整性或可用性。
责任限制:在适用法律允许的最大范围内,作者及贡献者不对因使用或无法使用本资料而产生的任何直接、间接、附带、特殊、惩戒性或后果性损失承担责任(包括但不限于数据丢失、设备损坏、ai平台账号封禁及法律纠纷)。
使用者自负其责:使用者须自行确保其使用行为合法合规(含取得必要授权),并独立承担由此产生的全部法律责任与后果。
第三方内容:本资料引用或链接的第三方项目、代码、工具、文档及服务,其版权与许可归各自所有者所有;使用前请自行查阅并遵守其各自条款。作者不对第三方内容及其后果负责。
权利主张:若你是某作品的权利人,并认为本资料侵犯了你的合法权益,请通过仓库 Issue 联系,作者将在核实后及时更正或删除。
平台规则:权利人可发起 DMCA 下架;GitHub 会因违反可接受使用政策处理本仓库。
AI 平台安全提示与账号责任:本 skill 涉及逆向 / 协议分析等可能触发 AI 平台安全规则的内容。使用本 skill 时,你接入的 AI 服务(如 GPT / Codex / Claude 等)可能因你的提示词内容性质触发安全提示、限制响应,甚至导致你的 AI 账号被限制或封禁。本 skill 作者不对任何 AI 平台对你账号采取的任何措施负责,包括但不限于警告、降级、限制或封禁。使用前请充分了解你所使用的 AI 平台的服务条款与安全策略,并自行承担相应风险。
条款变更:本免责声明可能随时更新,更新后自发布之日起生效,恕不另行通知。
关于复活已停止运营的网络游戏的说明
本资料常被用于**已停止运营(停服 / 官方终止在线服务)**的网络游戏的存档保存、历史研究与本地化重开。就此类用途,特别声明如下:
- 「已停服」不等于「进入公有领域」。该类游戏的代码、美术、商标、剧情、音频等知识产权仍归原权利人所有;停服不等于权利人放弃权利,也不构成对第三方运营的授权。
- 本资料仅支持面向既有玩家社区或个人的非商业性研究、存档与延续用途。严禁将其用于冒充官方、商业化牟利、发行收费服务,或损害原权利人及原玩家社区利益的行为。
- AI 生成内容所涉及的复活、部署与运营所引发的一切法律、经济与声誉风险,由使用者自行承担;作者不参与项目、不提供背书、不承担任何责任。
- 若原权利人或其权利继承方提出异议,作者将配合删除本仓库相关资料。
Skill manifest
游戏客户端 → 离线本地化 Skill
定位:把「只有客户端」的游戏,还原出「服务端协议 + 本地离线服务端」,并让原版客户端本地离线运行。 适用:互操作性研究、本地离线化 / 离线版建模、协议文档化、安全评估、游戏存档研究。 边界:仅用于自研、已授权或离线/单机目标。禁止未授权破坏性测试与商业化他人资产。
版本 v2.0(完整变更历史见
README.md)。2.0 较 1.x 新增:原理层primer.md、四阶段路线图workflow-roadmap.md、反推对象地图server-architecture-basics.md、重定向落点(含 Xposed/LSPatch 模块)、 复活 / 本地离线项目合集、登录链/功能清单模板、全库去除 emoji、跨模型阅读优化,并对 SKILL.md 大幅瘦身。
阅读协议(任何模型通用:GLM / DeepSeek / Claude / …)
本包 = 1 份长文档(
SKILL.md)+ 37 篇references/+templates/+tools/+ 参考实现server/。 不要一次读完——会耗尽上下文,结果在没读完的地方开始猜。 注意:多数模型不会自动加载 references,必须显式打开文件。 先读references/usage-policy.md(使用守则与限制)——确认用途合规、不越界,再动手。
标准三步(照做即可):
1. 先读完本文件 §0(方法选择 + 铁律 + 工作流 + 补包循环)—— 必读核心
2. 打开 references/reading-path.md → 按你的任务类型拿到 3~5 个文件的阅读顺序
3. 按顺序打开并读完那些文件 → 再动手
收工前:打开 references/reading-path.md §2,过一遍「收工前检查」
上下文很少时(只能读 1~2 篇),按此优先级取:
SKILL §0 → reading-path.md → wire-level-patching.md → closure-verification.md → client-address-sources.md
一句话:SKILL.md 是导航,references 是正文。先读导航,再按需读正文。
阅读地图:三条主线,先认清自己在哪条
这个包讲三件事。先确认自己卡在哪条主线,再去读对应文件,不要混着读。
| 主线 | 回答的问题 | 先读 | 关键产物 |
|---|---|---|---|
| A. 原理 | 「到底在反推什么?」 | references/primer.md、references/server-architecture-basics.md |
(认知:三要素 / 协议表 / 热更源码 / 反推对象地图) |
| B. 路线 | 「先做什么、后做什么、在哪验收?」 | references/workflow-roadmap.md |
login-chain.md、进度 |
| C. 方法 | 「用哪个手段取证?」 | references/methods.md |
选定方法 → project-profile.yaml |
| D. 规格 | 「怎么把结论固定下来?」 | references/protocol-spec.md |
protocol.spec.yaml(唯一事实来源) |
一句话:A 讲「找什么」,B 讲「什么顺序」,C 讲「怎么找」,D 讲「怎么记」。
- 新手 / 第一次接触某客户端 → 先读 A(
primer.md+server-architecture-basics.md),再看 B。 - 知道自己要干什么、只是缺手法 → 直接看 C(
methods.md)+ §0.0。 - 已经拿到证据、要落盘 → 直接看 D(
protocol-spec.md)。
0. 本 Skill 的定位:通用适配器,不是固定方案
核心认知(先读三遍):
这个 skill 里附带的任何代码(
server/、templates/、examples/)都只是参考实现, 不是对某个游戏的答案。每个游戏的引擎、传输、封装、加密、序列化、消息号、字段布局 都不一样。AI 必须先读取用户实际给的项目,产出协议规格(Protocol Spec), 再据此生成或改造服务端。
0.0 第一步:选对方法 (最容易做错的一步)
方法选错 = 后面全白干。 完整方法论见
references/methods.md。
先回答 3 个问题:
- 有什么?
PKG(只有安装包) /CAP(抓包) /SRC(源码或反编译产物) /RUN(能运行) /DBG(能注入) /MANIP(能改客户端或代理) /REF(有同类实现) - 要什么?
DOC(只要文档) /FLOW(跑通主流程) /FULL(完整服务端) /PATCH(改客户端) - 什么约束? 客户端保护 / 时间 / 权限
十一种方法速览(详见 methods.md):
| 代号 | 方法 | 何时用 |
|---|---|---|
| M1 | 白盒源码法 | 有 SRC → 首选 |
| M2 | 黑盒抓包法 | 有 CAP → 通用 |
| M3 | 灰盒 Hook 法 | 有 RUN+DBG → 破加密 |
| M4 | 辅助 Artifact 法 | 有 .proto/.usmap/SDK → 一步到位 |
| M5 | 代理透传+逐接口替换 | 有 CAP+MANIP → 最稳落地 |
| M6 | 差分探测法 | 定字段 |
| M7 | 回放/录像法 | 有录像 → 战斗协议 |
| M8 | 已知实现移植法 | 有 REF → 抄作业 |
| M9 | 自环法 | 起桩看客户端要什么 |
| M10 | 穷举校验法 | 兜底(优先 M3) |
| M11 | 内联服务端法 | 有 RUN+DBG/MANIP 且可单机化 → 不起外部服务端 |
默认路线(不知选什么就用它):
M1/M4(有源码就抄)→ M2+M3(拿明文)→ M6(定字段)→ M9(跑通连接)
→ M5(透传+逐接口替换)→ 闭环验证
另有一条主干分叉:目标可单机化 + 客户端能注入/能改 → 走 M11 内联服务端(
inline-server.md), 传输 / 封装 / 加密层不必还原。先判分叉,再选方法。
注意: 现实中都是组合使用(如 M1+M6+M5)。 选定后记进
project-profile.yaml的method段;发现更好路径可中途切换。
0.1 五条铁律
- 证据驱动,不臆测:所有结论必须来自用户项目里的实际证据(dump.cs / lua / 抓包 / SDK / 资源文件 / 客户端行为)。
没有证据 → 标注为「假设」并写进 Spec 的
unresolved列表。 - 先产出规格,再产出代码:中间必须有一个语言无关的协议规格文件
(见
references/protocol-spec.md与schema/protocol.spec.yaml)。 代码是从规格派生出来的,换游戏 = 换规格,不是重写一堆散代码。 - 闭环验证:服务端必须能让原版客户端跑通到某个状态(握手/登录/进场景),否则推断就是错的。
- 不把「能跑」当成「跑通」:端口在 listen、自环脚本报
OK、日志打了 , 都不是闭环证据。宣布成功前必须逐条排除假阳性 → 见references/closure-verification.md(接手别人项目时尤其必读)。 内联路线另有一套判据:界面截图不算,要看网络 / 状态层的完成点 →inline-server.md§6。 - 三件事分开记:「服务端实现了」「自动测试覆盖了」「客户端验收了」。
用一个状态列会掩盖后两项 → 见
references/verification-and-status.md。 不支持的输入要 fail closed,不要猜一个值。
0.2 双证据链
任何字段结论 = 流量证据(抓包里字节变化) + 代码证据(客户端里的结构体/序列化代码)。 单侧只算假设。
0.3 四层剥离(先分层,再解字段)
不要一上来抠某个字节。先弄清
传输层 → 封装层 → 加密/压缩层 → 序列化层,每层剥离后再看内容。
0.4 自适应工作流(本 skill 的主干)
输入可能是零:如果用户只给了一个安装包(apk/ipa/exe),先走
references/from-installer.md的自举流水线把证据造出来,再进入下面的步骤。
[第0步] 读取输入
├─ 只有安装包 ? ──▶ references/from-installer.md
│ 解包 → 判引擎/语言 → 自产 dump.cs/dll/lua/资源 → 抓包 → 动态 dump
└─ 已有 dump/lua/抓包 ? ──▶ 直接进第1步
↓
[第0.5步] 建立工作区契约 → 在项目根放 AGENTS.md(边界/目录分区/验证命令) ← templates/AGENTS.md
↓
[第1步] 产出「项目档案 project-profile」 ← references/adaptation.md
扫描目录/文件,识别引擎、语言、网络库、资源格式、已知工具产物
↓
[第2步] 证据清点 → 证据清单 evidence-inventory
每条证据:来源、类型、能得出什么结论、置信度
↓
[第3步] 决策引擎 → 逐层决策(引擎/传输/封装/加密/序列化/架构) ← references/decision-tree.md
每个决策点都有"若…则…"的分支,禁止默认套用参考实现
↓
[第4步] 产出协议规格 protocol.spec.yaml ← references/protocol-spec.md
语言无关,含 opcodes / frames / crypto / serialize / state_machine / client / subsystems
↓
[第5步] 由规格生成/改造服务端(多语言参考) ← references/codegen.md
选一个最贴近目标协议的语言;参考实现只提供"套路",不提供"答案"
↓
[第6步] 平台部署(端游/手游/服务器) ← §14
↓
[第7步] 客户端对接 + 闭环验证 ← §8/§9
可选分叉(M11 内联服务端):若目标可单机化且客户端能注入 / 能改,可跳过传输与加密层的还原, 直接在客户端进程内合成响应 →
references/inline-server.md。
换个视角看同一件事——四阶段路线(见 references/workflow-roadmap.md):
阶段0 静态分析(清点线索) → 阶段1 建工具+登录链文档 → 阶段2 重定向(让请求到达本地离线服务端)
→ 阶段3 补包循环(上游→下游,客户端能走到下一步才算通) → 阶段4 功能清单迭代
§0.4 是"按产物推进的流水线",四阶段是"按顺序+验收推进的路线图",两者是同一件事的两种记法。 不确定从哪下手时,先看
workflow-roadmap.md的全景图。
0.4b 补包循环 (进游戏阶段的核心工作模式)
这是**"让客户端一步步前进"的唯一主线**。四阶段的阶段 3 就是它。 前两步(静态分析、重定向)都只是为它铺路。
方向:从【登录链最上游】往下游补回包
① 先回【服务器列表】 ← 地址来自这里
② 再回【登录握手】 ← 鉴权 / token / hash
③ 最后补【游戏需要的数据】← 角色 / 背包 / 任务 / VIP / 签到 …
通过标准:每补一块,以「客户端能走到下一步」为准
不是"服务端没报错",而是客户端真的前进了一步(界面前进 / 状态推进)。 —— 这是铁律 4「不把『能跑』当『跑通』」在补包阶段的落地。
出错怎么查:对照报错 + 两侧日志
拿 客户端报错、网络日志、服务端日志 三边对齐,判断属于哪一种:
| 症状 | 大概率原因 |
|---|---|
| 客户端没反应 / 静默断开 | 格式错了(帧 / 字节序 / 字段布局 + 长度) |
| 明确报错 / 空指针 | 数据缺失(少字段、空子消息被省略) |
| 走到了下一步但还是不对 | 逻辑根本没有写(该给的条件数据没给) |
里程碑:能进入游戏主场景 = 成功一大半。
之后工作流程就只有这一条路线——不断让用户测试工作区目标,循环:
测试 →(看日志)→ 定位 →(改)→ 修改 → 再测试 ↺
收尾:整理【功能清单文档】放到工作区,反复迭代直到基本完善 → templates/function-checklist.md。
详细版(含三边对齐的排错顺序、假阳性排查):
references/workflow-roadmap.md§阶段 3~4。
0.5 参考实现的正确用法
| 参考物 | 是什么 | 怎么用 |
|---|---|---|
references/primer.md |
原理层:三要素(配置/协议/代码)、数据包协议本质、协议号与协议表、热更源码、双证据链 | 第一次接触某客户端时先读,避免"不知道在找什么" |
references/workflow-roadmap.md |
四阶段路线总纲(静态分析→建工具+登录链→重定向→补包循环→清单迭代)+ 四层重定向表 | 动手前看全景图;它把 §0.4 与 M1~M11 串成一条有验收的线 |
references/server-architecture-basics.md |
反推对象地图(逆向视角):你在还原哪几类服、网关留下的隐藏层、从包里认 Protobuf/KCP、同步模型决定"要还原多少逻辑" | 判断"你在反推哪几类服、去哪找证据"时读;避免在网关层迷路 |
server/ |
长连接二进制协议的参考实现(Python) | 只借鉴分层结构与套路,协议参数全部按 Spec 改 |
templates/mock_server.py |
极简单文件桩 | 逆向早期快速验证用 |
examples/*.md |
不同游戏类型的推演示例 | 看"给定这类证据会怎么决策",不要照搬结论 |
references/cases.md |
两个真实成功的服务端项目(Go / Node) | 看真实项目的子系统与取舍,校准自己的方案 |
references/client-languages.md |
各客户端语言的反编译与打补丁 | 先判语言,再选工具 |
references/cocos2d.md |
Cocos2d-x / Cocos Creator 深潜(.jsc/.lua 解包 / 自加密 HTTP-RPC / 多端口 / 热更 / 语言表还原 / §H2 进服后的 Live 运营:note 双层包裹、客户端本地存档合并、双表版本差异、自愈设计、部署纪律) | 目标是 cocos 客户端时必读(另见 examples/E-cocos2dx-http-js.md §8 Live 运营阶段) |
references/live-ops.md |
Live 运营手册(进服后 30+ 子系统按投诉频率排序的补全次序 / 契约反推法 / 自愈设计 / 双表差异处置) | 进服之后读,与 cocos2d.md §H2 互补、引擎无关 |
references/from-installer.md |
零输入自举:只有安装包怎么自产证据 | 最常见的入口,必读 |
references/reading-path.md |
最小必读路径(按任务类型给 3~5 个文件的阅读顺序) | 打开 skill 的第一件事 |
references/methods.md |
10 种反推方法 + 选择矩阵 | 动手前先看(§0.0) |
references/closure-verification.md |
闭环验证 6 类假阳性 + 检查表 | 宣布"成功"前必看;接手别人项目时第一条 |
references/engineering-practices.md |
实机跑通项目的工程范式(fixture 回放 / 具名完成点 / 证据分档 / ADR) | 动手前定策略;配套 templates/adr-*.md、templates/e2e-*.md |
references/wire-level-patching.md |
实现层核心:不依赖 protobuf 运行时的 wire 级定点改写 | 写服务端之前必读;决定"先跑起来还是先凑 schema" |
references/client-address-sources.md |
客户端地址来源清查(六类来源 + 落点策略 + 重签后果) | 改包/对接客户端之前必读;解决"改了 URL 还连官方" |
references/verification-and-status.md |
三轴状态 + 可达性分类 + 测试门禁 | 写 TRACKER / 宣称完成之前必读 |
references/release-and-ops.md |
发布、部署与运营(配置冻结 / 端口族 / CDN / 备份) | 跑通之后要交付时看 |
references/case-il2cpp-ecdh.md |
真实案例:Unity IL2CPP + ECDH 登录服(进行中) | 看"分层结论怎么写 + 卡点怎么复核" |
references/repack-rename.md |
改包名 / 重打包 / 签名 / 包名派生密钥 | 想产独立安装包时看 |
references/inline-server.md |
内联服务端:在客户端进程内合成响应(门面三类入口 / 回调投递纪律 / 延迟派发 / 双通路 / 内联版验收与假阳性) | 能注入且要单机化时先读这个 —— 它决定你要不要起外部服务端 |
references/runtime-object-synthesis.md |
运行时对象合成与字段发现(对象级 schema 自举 / dump 循环 / 填值纪律 / 对象级→wire 级切换) | 走内联路线时必读;也可用来先拿一份可信字段清单 |
references/platform-sdk-and-admission.md |
平台 SDK 登录态复用 + 目录服→区服两段准入 | 大厂手游(第三方平台账号 SDK)登录卡点时读 |
references/case-il2cpp-inline.md |
真实案例:Unity IL2CPP + 平台 SDK 的内联服务端 | 看「不起服务端」这条路怎么走、哪些结论已被证伪 |
schema/*.yaml |
规格/档案模板 | 直接复制填,作为 AI 的中间产物 |
extensions/ |
后续拓展(可选),不影响核心运行 | 跑通之后再考虑,见 §19 |
注意: 反例:直接把
server/config/config.yaml的opcode_size=2拿去套一个 1 字节消息号的游戏 —— 必错。 正确做法:Spec 里写明opcode_size: 1,再改代码。
0.6 启动阶段的两把钥匙
来自实机跑通到「主界面」的真实项目范式,详见
references/engineering-practices.md。 先读这两条,能少走几周弯路。
钥匙一:fixture 回放(抓包 → 原样重放 + 定点改写)
启动时客户端要一次性吃下几十个字段的嵌套状态(角色/背包/任务/VIP/签到…), 纯靠反推字段拼几乎必卡在某个页面。更快的路径:
原版客户端连原版服务器 → 抓一次完整启动序列 → 落成 fixture(含方向/消息号/seq/flag/原始 body)
→ 本地服务端按【原始顺序】重放 → 未知字段【原样保留】,只对已确认字段做 wire-level 定点改写
具体怎么实现(不引入 protobuf 运行时的字段遍历 + splice 替换)
→ references/wire-level-patching.md(含帧 codec、字段遍历器、
patch_varint/bytes/string、"空子消息也要保留"等实测经验)
注意: 两个红线:① 不要用「缺字段的伪造对象」代替真实启动数据; ② 一个账号的 fixture 带着它的 UID/角色数据,不能直接发给别的账号。
钥匙二:具名「完成点」做验收
不要写「登录成功」。要写客户端上的一个可观察状态,例如: 「收到启动结束消息后进入主界面,不是只保持 TCP 连接」。 再补一次强制停止 + 重启 + 重连,确认状态仍在。
配合使用:templates/e2e-evidence-template.md(帧序表 + 主动解释帧长差异 + 重连快照)、
templates/adr-template.md(写清「当前不做的事情」与回滚条件)。
1. 输入分类与预处理
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
2. 阶段一:侦察与引擎识别
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
3. 阶段二:流量获取
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
4. 阶段三:协议分层识别
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
5. 阶段四:客户端静态分析(分引擎)
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
6. 阶段五:字段语义推断
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
7. 阶段六:服务端建模与实现
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
8. 阶段七:部署(本地 / 服务器 / 容器)
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
9. 阶段八:验证与回滚
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
10. 输出物清单(交付模板)
详细步骤(命令 / 工具 / 判断 / 常见坑)见
references/phases-detail.md。
11. 常见坑(速记)
完整清单见
references/closure-verification.md§附「高频常见坑速查」。这里只留最要记住的几条:
- 改包顺序:先"不改包 + 端口劫持"跑通协议,最后才改包(动手前读 )。
- raw deflate ≠ 加密:先在
decision-tree.md §4.0做 30 秒快筛,别在错误的加密假设上耗数小时。 - 别把"能跑"当"跑通":端口在听 / 自环 OK / 日志打勾都不是闭环证据(铁律 4)。
- 只跑通登录不算完:状态机未闭环,客户端进场景即崩。
12. 工具速查
| 用途 | 工具 |
|---|---|
| Unity IL2CPP dump | Il2CppDumper / Il2CppInspector / r2unity |
| Unity Mono | dnSpy / ILSpy |
| Lua 反编译 | unluac / luadec |
| 反汇编 | IDA Pro / Ghidra / Hopper |
| 动态 | Frida / x64dbg / lldb |
| UE 资源 | FModel / UnrealPak / umodel / AesFinder |
| UE SDK/mapping | Dumper-7 / UE4SS / usmap dumper |
| 抓包 | mitmproxy / Charles / Wireshark / tcpdump |
| 协议试解 | protoc --decode_raw / binwalk / ent |
| 接口清单提取 | tools/extract_interfaces.py(本 skill 自带) |
| so 结构 / 依赖 / 符号 | readelf -d(NEEDED)、readelf --dyn-syms --wide(FUNC + OBJECT 都要看)、strings -a(找硬编码常量) |
| APK 编辑 / 资源 / 重打包 / 签名 | MT 管理器(含 MCP:http://127.0.0.1:8787/mcp,可 dex/资源/构建/签名一条龙)、apktool、apksigner |
| ZIP 原样复制重打包 | 本 skill tools/ 的 repack 脚本(2GB 包秒级,只替换目标条目) |
| 动态调试 / 内存 | Frida、/proc/<pid>/maps(看加载了哪些 so) |
13. 使用本 Skill 的 AI 行为契约(必读)
完整行为契约(强制产物 / 硬性禁止 / 缺信息做法 / 决策可追溯 / 终点定义 / 回滚)见
references/ai-contract.md。使用守则与限制(允许 / 禁止用途 + 硬性约束 + 自检清单)见
references/usage-policy.md——每次动手前先读。
14. 运行环境与工具链(端游 / 手游)
服务端代码同一套,差别只在运行平台 + 保活 + 客户端对接 → 详见 references/termux.md(手游/Android)、references/windows.md(端游/Windows)。
环境选择:
只用 Python+SQLite → Termux / 裸 Windows
要 AES 或大量 Linux 工具 → Termux+proot Ubuntu / WSL2
要长期对外在线 → 云服务器(Ubuntu + deploy.sh) / Windows NSSM
仅本机自测 → 直接跑,客户端连 127.0.0.1
注意: 保活是最容易翻车的点:Termux 要
termux-wake-lock+ 关电池优化;Windows 用服务/计划任务,别用前台窗口。 脚本:server/start_termux.sh、server/deploy/start_windows.bat。
15. 充值 / 邮件 / 道具奖励发放
客户端连的是我们自己的服务端,第三方支付 SDK 不存在 → 下单直接判成功并发放("点击购买即成功")。 参考实现:
logic/handlers/pay.py/mail.py;商品表store/models.py: PAY_PRODUCTS(键 = 客户端真实 product_id)。
- 两条路径(
game.pay_grant_mode):direct货币直接进角色 /mail发附件邮件自助领取;pay_auto_success:true跳过真实校验。 - 协议:
PAY_PRODUCT_LIST 0x0501/2、PAY 0x0503/4、MAIL_{LIST,READ,CLAIM} 0x0401~0x0406、MAIL_NEW_NTF 0x0407。 - 踩过的坑:① 邮件推送必须在 PayRes 之后发(否则被当成充值回包);② 领取/已读/删除共用结构但必须用各自 opcode;③
order_no UNIQUE保幂等;④ 发放全在服务端。 - 边界:仅自建/离线/已授权;不接真实支付渠道、不伪造凭证。
16. 账号体系与接口还原
目标:官方客户端用我们自己注册的账号登录我们的服务端。方法论 →
references/account.md。
- 账号从哪来:A 客户端内注册 / B 独立注册网站(写同一 DB,客户端只登录;模板 →
templates/register-site/)/ C 脚本批量建号。 - 注意: 最大的坑——密码预处理:客户端常先
MD5(pwd+salt)再发包,必须复刻其哈希,否则注册的密码登不上。找法:读登录函数 / 抓两次包看密文是否固定;落 Spec 的account.password_hash/salt/client_side_hashing。 - 接口替换:优先改配置 / hosts,不动二进制;有服务器列表就返回我们自己的地址(→ §8.6、
client-address-sources.md)。 - 典型链路:
版本/公告 → 登录(账号+密文) → token → 服务器列表 → 带 token 连游戏服(TCP)。 - 账号接口逐条登记进
TRACKER.md。
17. 房间 / 战斗 / 掉落(核心玩法)
没有战斗和掉落,游戏就不成立。 方法论 →
references/combat.md、references/drops.md; 参考实现 →server/app/logic/rooms.py、loot.py、handlers/{room,battle,drop}.py。
- 关系:
大厅/场景 → 房间(匹配/组队) → 战斗(回合/实时) → 结算 → 掉落(掷骰) → 背包/邮件。 - 房间:创建→加入/退出→准备→房主开始→战斗→回等待;必备槽位上限、房主权限、全准备才开、房主退出移交、空房回收。
- 战斗(铁律:结算在服务端):客户端只发意图;回合制=服务端算结果并广播,实时=服务端定权威状态。必备回合推进/伤害/超时判负/异常退出;结束广播
BATTLE_RESULT_NTF。 - 掉落:
table_id → {rolls, entries:[{item_id, count[min,max], rate}]}(从客户端配置表反推);服务端掷骰;背包满 → 自动转邮件补发。 - 协议:房间
0x0601~0x060B、战斗0x0701~0x0704、掉落/背包0x0801~0x0805(详表见server/app/proto/opcodes.py)。 - 经济系统复用:抽卡(
references/gacha.md) / 商店 / 背包 共用同一套「随机→结算→入库」,不要写两套。
18. 快速上手(AI 第一次拿到项目的动作序列)
[第 0 步 · 最重要] 选对方法
· 回答 3 个问题:有什么 / 要什么 / 什么约束
· 对照 references/methods.md §4/§5 选定方法 → 记进 project-profile.yaml 的 method 段
· 默认路线:M1/M4 → M2+M3 → M6 → M9 → M5
[如果只有安装包]
0. 走 references/from-installer.md:解包 → 判引擎/语言 → 自产证据 → 抓包
(详见该文件第 9 节的 10 项动作清单)
[通用主流程]
1. 列目录 → 跑 references/adaptation.md 的探测命令
2. 填 out/project-profile.yaml(包括 needs 清单)
3. 逐条记录证据 → out/evidence-inventory.md
4. 走 references/decision-tree.md → 填 out/protocol.spec.yaml
(含 client / subsystems 两段)
5. 检查 protocol-spec.md 的「Spec 完成度清单」
5.5 账号/接口:读 references/account.md → 在 TRACKER.md 登记接口清单
6. 按 references/codegen.md 选语言 + 改造/新建服务端
7. 增量验证(连接→登录→…)→ 回填置信度
8. 部署(§14)+ 客户端对接(§8)→ 闭环
看 examples/ 里的三个推演,理解"同样流程、不同结论"。
19. 后续拓展(可选,不影响核心运行)
判断标准:去掉它,游戏还能不能正常玩?能 → 它就是拓展(放
extensions/),不写进核心流程。
| 拓展 | 文件 | 一句话 |
|------|------|--------|
| 服务端人机(假玩家) | extensions/bots.md | 多人副本凑不齐人时用 AI 自动补位 |
| 反推人机机制 | extensions/bot-reverse.md | 无参考项时从客户端获取信息反推它的人机实现 |
人机为什么是拓展:单人游戏完全不需要;多人缺人只损体验、服务端本身能跑;参考实现默认 auto_fill: 0(不生成假玩家)。
用法(跑通后再做):核心链路先通 → 确认是否"必须多人" → bot-reverse.md 反推机制写进 Spec → bots.md 实现 → 调试(bots spawn/clear/difficulty)→ 原版客户端验收。
注意: 拓展不参与核心验收(§13 的强制产物与闭环)。没做拓展 ≠ 交付不完整。 不要因为拓展没做就认为交付不完整;也不要把它塞进核心流程。
Files (game-client-to-server-reverse)
-
examples
-
A-unity-il2cpp-protobuf.md 3.5 KB
Loading… -
B-ue-kcp-custom.md 3.3 KB
Loading… -
C-unity-lua-http.md 2.9 KB
Loading… -
D-real-lua-client.md 8.3 KB
Loading… -
E-cocos2dx-http-js.md 10.2 KB
Loading… -
README.md 1.3 KB
Loading…
-
-
extensions
-
bot-reverse.md 8.9 KB
Loading… -
bots.md 8.5 KB
Loading… -
README.md 2.3 KB
Loading…
-
-
references
-
account.md 4.3 KB
Loading… -
adaptation.md 5.5 KB
Loading… -
ai-contract.md 3 KB
Loading… -
case-il2cpp-ecdh.md 6.4 KB
Loading… -
case-il2cpp-inline.md 4.3 KB
Loading… -
cases.md 5.1 KB
Loading… -
client-address-sources.md 17.5 KB
Loading… -
client-languages.md 6.3 KB
Loading… -
closure-verification.md 11.6 KB
Loading… -
cocos2d.md 15.3 KB
Loading… -
codegen.md 4.9 KB
Loading… -
combat.md 3.8 KB
Loading… -
decision-tree.md 10 KB
Loading… -
drops.md 3.1 KB
Loading… -
engineering-practices.md 15.9 KB
Loading… -
from-installer.md 10.7 KB
Loading… -
gacha.md 5.4 KB
Loading… -
inline-server.md 10.9 KB
Loading… -
live-ops.md 6.7 KB
Loading… -
methods.md 11.5 KB
Loading… -
phases-detail.md 10.2 KB
Loading… -
platform-sdk-and-admission.md 4.8 KB
Loading… -
primer.md 10.8 KB
Loading… -
protocol-spec.md 7.7 KB
Loading… -
reading-path.md 8.8 KB
Loading… -
release-and-ops.md 11.8 KB
Loading… -
repack-rename.md 8 KB
Loading… -
runtime-object-synthesis.md 5.2 KB
Loading… -
server-architecture-basics.md 9.9 KB
Loading… -
termux.md 4 KB
Loading… -
unity.md 2.4 KB
Loading… -
unreal.md 2.2 KB
Loading… -
usage-policy.md 3.4 KB
Loading… -
verification-and-status.md 8.4 KB
Loading… -
windows.md 9.1 KB
Loading… -
wire-level-patching.md 13.1 KB
Loading… -
workflow-roadmap.md 12.3 KB
Loading…
-
-
schema
-
project-profile.yaml 2.8 KB
Loading… -
protocol.spec.yaml 5.5 KB
Loading…
-
-
server
-
app
-
logic
-
handlers
-
auth.py 4.2 KB
Loading… -
battle.py 3.2 KB
Loading… -
char.py 3.6 KB
Loading… -
drop.py 1.9 KB
Loading… -
mail.py 5.1 KB
Loading… -
pay.py 4.9 KB
Loading… -
room.py 4.4 KB
Loading… -
scene.py 3 KB
Loading… -
__init__.py 313 B
Loading…
-
-
bots.py 7.8 KB
Loading… -
loot.py 3.4 KB
Loading… -
rooms.py 7.4 KB
Loading… -
security.py 2.1 KB
Loading… -
state.py 1.1 KB
Loading… -
__init__.py 15 B
Loading…
-
-
net
-
codec.py 6.5 KB
Loading… -
crypto.py 3.9 KB
Loading… -
dispatcher.py 1.5 KB
Loading… -
server.py 5.9 KB
Loading… -
session.py 2.2 KB
Loading… -
__init__.py 14 B
Loading…
-
-
proto
-
messages.py 9.8 KB
Loading… -
opcodes.py 3.6 KB
Loading… -
__init__.py 15 B
Loading…
-
-
store
-
db.py 8.1 KB
Loading… -
models.py 4.5 KB
Loading… -
__init__.py 15 B
Loading…
-
-
config.py 3.2 KB
Loading… -
log.py 919 B
Loading… -
main.py 1.9 KB
Loading… -
__init__.py 35 B
Loading…
-
-
config
-
config.yaml 3.2 KB
Loading…
-
-
deploy
-
deploy.sh 1.4 KB
Loading… -
docker-compose.yml 1.2 KB
Loading… -
Dockerfile 448 B · in bundle
-
gsrv.service 593 B · in bundle
-
install_windows_service.bat 842 B · in bundle
-
start_windows.bat 450 B · in bundle
-
-
client_test.py 4.8 KB
Loading… -
README.md 5.1 KB
Loading… -
requirements.txt 271 B
Loading… -
start.sh 354 B
Loading… -
start_termux.sh 1010 B
Loading… -
test_battle.py 5.6 KB
Loading… -
test_pay_mail.py 4.4 KB
Loading…
-
-
templates
-
register-site
-
index.html 15.8 KB · in bundle
-
README.md 2.6 KB
Loading… -
server.py 6.2 KB
Loading…
-
-
xposed-redirect
-
AndroidManifest.xml 583 B · in bundle
-
build.gradle 302 B · in bundle
-
MainHook.java 4.6 KB · in bundle
-
README.md 2.6 KB
Loading… -
redirect_config.txt 129 B
Loading… -
xposed_init 26 B · in bundle
-
-
adr-template.md 2.8 KB
Loading… -
AGENTS.md 5.3 KB
Loading… -
e2e-evidence-template.md 4.2 KB
Loading… -
frida-redirect.js 3.4 KB
Loading… -
frida_bypass_ssl.js 2.5 KB
Loading… -
function-checklist.md 3.5 KB
Loading… -
kcp_sniff.py 1.8 KB
Loading… -
login-chain.md 3.6 KB
Loading… -
mock_server.py 3.7 KB
Loading… -
README.md 4.4 KB
Loading… -
status-matrix.md 3 KB
Loading…
-
-
tools
-
extract_interfaces.py 5.4 KB
Loading… -
repack_zip.py 4.9 KB
Loading…
-
-
README.md 24.5 KB
# 游戏客户端 → 离线本地化 Skill 完整支持 **Unity(IL2CPP / Mono / Lua)** 与 **Unreal Engine(UE4 / UE5)**,也覆盖 C#/AS3/Lua/JS/Java 等各类客户端。 从客户端反推服务端协议 → 复现本地离线服务端 → 部署 → 让原版客户端**本地离线运行**。 > [x] 本包自带的服务端已**实测跑通**:握手 → 登录 → 建角 → 选角 → 进场景 → 移动 → 心跳, > 并验证 XOR 加密 + zlib 压缩 + 充值/邮件发放。 > > 服务端参考实现原Github地址:https://github.com/Nanako660/peach-haven > > **2026-09-22 更新(v2.0)** —— 本版主题:原理层 + 四阶段路线 + **换服务端(重定向)**: > ⓪ **版本升至 2.0**:整合 1.x 全部成果 + 以下 ①~⑪; > ① **原理层** `references/primer.md`:三要素(配置=数值 / 协议=格式 / 代码=用法)、 > 数据包协议本质、协议号与协议表、**热更新代码是比 dump 更好读的源码**; > ② **四阶段路线总纲** `references/workflow-roadmap.md`(静态分析 → 建工具+登录链 → 重定向 → 补包循环 → 清单迭代)+ **四层重定向表**; > ③ 模板:`templates/login-chain.md`(登录链条)、`templates/function-checklist.md`(功能清单); > ④ SKILL §0 开头新增**阅读地图(三条主线)**; > ⑤ **反推对象地图** `references/server-architecture-basics.md`(逆向视角):你在还原哪几类服、 > 网关留下的隐藏层(合并/加解密/压缩 flag)、从包里认 Protobuf/KCP、同步模型决定"要还原多少逻辑" > (来源:平台云架构演进、GameDevAndOps、KCP/protobuf 官方、Skynet/Pomelo/KBEngine/NF); > ⑥ **取长补短(折进现有文件)**:`methods.md` M8 补入**现成实现速查(按类型)** + "先查别人做过没" + **先锁版本**;`protocol-spec.md` 补入人类可读协议文档格式; > ⑦ **SKILL.md 瘦身**:与 references 重复的 §1~§8、§11、§14~§19 压成"要点+指针"(1122 → ~650 行);§11 常见坑并入 `closure-verification.md §附`; > ⑧ **跨模型阅读优化(GLM / DeepSeek / Claude)**:SKILL 顶部改为**模型无关的显式阅读协议**("打开哪个文件"写死); > 去掉顶部大段变更历史;给 5 篇 >300 行的 reference 补**章节目录**;`reading-path.md` 顶部声明按它分派; > ⑨ **去除 emoji**:全库清理(状态标记转 ASCII、装饰 emoji 删除、箭头保留); > ⑩ **框架修正 + 资源**:` §0` 改为"**主动改客户端对接本地离线服务端**"(按重定向四层表、优先跑起来); > ⑪ **换服务端手法补全(v2.0 新增)**:`client-address-sources.md §3.0b` 加入 **Xposed / LSPatch 模块重定向** > (第三方代理模块实测范例,免 root);`methods.md` M8 加"**多人/联机复活项目**"检索入口; > ⑫ **签名绕过**:`repack-rename.md §8` 加入 **LSPatch Signature Bypass(等级 2)机制** / 独立签名破解 > (`ApkSignatureKiller` / 核心破解) / 真正不改签名的虚拟容器(VirtualXposed / 太极);§7 落点表述改为"按代价从低到高"; > 接入点:`account.md §6`、`release-and-ops.md §7`、`SKILL §16`; > > **2026-09-15 实战沉淀(v1.8 新增)**: > ⑬ **内联服务端**:不起外部服务端,在客户端**进程内**拦截网络门面合成响应 > (三类入口 / 回调投递纪律 / 延迟派发 / 双通路 / 内联版验收与假阳性)→ `references/inline-server.md` > ⑭ **运行时对象合成与字段发现**:用客户端自己的类型系统当 schema,先 dump 再合成 → `references/runtime-object-synthesis.md` > ⑮ **平台 SDK 登录态复用 + 目录服→区服两段准入** → `references/platform-sdk-and-admission.md` > ⑯ 真实案例:Unity IL2CPP + 平台 SDK 的内联服务端 → `references/case-il2cpp-inline.md` > > **2026-09-13 实战沉淀(新增)**: > ② **改包名 / 重打包 / 保留原签名**全清单 → `references/repack-rename.md` > ④ **闭环验证与 6 类假阳性**(端口在听≠服务可用、自环≠客户端兼容)→ `references/closure-verification.md` > ⑤ **真实案例:Unity IL2CPP + ECDH 登录服**(帧格式 / SPKI / 已证伪项)→ `references/case-il2cpp-ecdh.md` > ⑥ SKILL 铁律 3 → 4 条:**不把「能跑」当成「跑通」** > ⑦ **工程范式**(实机跑通项目的做法:fixture 回放 / 具名完成点 / 证据分档 / ADR)→ `references/engineering-practices.md` > ⑧ 文档模板:`templates/adr-template.md`、`templates/e2e-evidence-template.md` > ⑨ **实现层核心**:不依赖 protobuf 运行时的 **wire 级定点改写**(帧 codec + 字段遍历 + splice 替换 + 空子消息必须保留)→ `references/wire-level-patching.md` > ⑩ **客户端地址来源清查**(六类来源 + 落点优先级 + 重签后果 + 阶段验收)→ `references/client-address-sources.md` > ⑪ **三轴状态与验收体系**(实现 / 自动测试 / 客户端验收 + 可达性五分类 + 提交门禁)→ `references/verification-and-status.md` > ⑫ **发布、部署与运营**(监听 vs 对外地址 / 端口族 / 启动期冻结配置 / CDN 版本策略 / 备份)→ `references/release-and-ops.md` --- ## 目录映射(本 skill 的结构) > 本 skill 遵循 **Agent Skills** 规范:**一个文件夹 = 一个 skill**,且 frontmatter 的 `name` > 必须与文件夹名一致。本文件夹即 `game-client-to-server-reverse/`;内部目录是对规范约定目录的映射。 | 规范约定 | 本 skill 实际 | 说明 | |----------|--------------|------| | `SKILL.md` | `SKILL.md` | 必需:元数据 + 主干(已瘦身到 < 500 行,符合规范建议) | | `references/` | `references/` | 按需加载的详细文档(正文下沉于此) | | `assets/` | `templates/`、`schema/`、`server/` | 模板 / 中间产物模板 / 可运行参考实现 | | `scripts/` | `tools/` | 可执行脚本(`extract_interfaces.py` / `` / `repack_zip.py`) | | — | `examples/`、`extensions/` | 推演示例 / 可选拓展 | > 阅读顺序:`SKILL.md`(导航+主干)→ `references/reading-path.md`(按任务分派)→ 按需打开具体文件。 --- ## 先读什么(别一次读完整包) 本包有 37 篇参考 + 一份长主文档。**通读完再动手 = 上下文耗尽 + 在半懂的地方开始猜。** ``` 1. references/reading-path.md ← 按任务类型拿到 3~5 个文件的阅读路径 2. SKILL.md §0.0 ~ §0.6 ← 方法选择 + 铁律 + 工作流主干 3. 按路径读完场景层文件 → 动手 收工前:reading-path.md §2 的「收工前检查」 ``` **上下文极少时**的优先级: `SKILL §0` → `reading-path.md` → `wire-level-patching.md` → `closure-verification.md` → `client-address-sources.md` > skill 是**查询手册**,不是必读教材。 --- # 如何使用本 Skill ## 一句话 把游戏(安装包 / 客户端 / 辅助文件)交给 AI,说清「要什么」, AI 会**自己取证 → 产出协议规格 → 生成并部署本地离线服务端 → 让客户端本地离线运行**。 ## 你最少只需给一样 | 给什么 | 推荐度 | AI 会做什么 | |--------|--------|------------| | **一个安装包**(`.apk` / `.ipa` / `.exe`) | 最推荐 | 自己解包、判引擎、跑 dump、抓包(见 `references/from-installer.md`) | | 客户端目录 / `dump.cs` / `*.lua` / `*.usmap` | | 直接进静态分析 | | 抓包 `*.pcap` / mitm 导出 | | 直接做协议分层 | | 已有服务端样本 / 协议文档 | | 对照分析 | | 只有一个游戏名 | [x] | 没有证据,建议先提供安装包 | ## 提问模板(直接复制改) ``` ① 最简 帮我反推这个游戏的服务端:/文件路径/game.apk ② 带目标 用这个 APK 反推服务端协议,先跑通登录,然后部署到本地。 ③ 带约束 这是 Unity 手游,服务端请分析根据当前用户给出客户端来用什么编写(如Go编写),要支持局域网联机链接到我们当前写的服务端上,先做协议分析.md文档再写代码。 ④ 指定阶段 先别写代码,只做协议分层,产出 protocol.spec.yaml 和证据清单。 ``` ## 一个好提问包含 4 个要素 | 要素 | 说明 | 例子 | |------|------|------| | **输入** | 你给什么 | `game.apk` / `dump.cs` / `capture.pcap` | | **目标** | 做到哪一步 | 只分析 / 跑通登录 / 完整服务端+部署 | | **约束** | 语言/平台/版本 | Go / 安卓局域网 / 客户端 1.8.1 | | **环境** | 跑在哪 | 本地 / 云服务器 / Termux | > 缺哪个都行,AI 会用占位符推进;但**输入**最好给一个。 ## AI 会按这个顺序回应(重要) ``` 1. project-profile.yaml ← 我读了什么、还缺什么 (项目档案) 2. evidence-inventory ← 每条结论的证据 + 置信度 (证据清单) 3. protocol.spec.yaml ← 协议规格(唯一事实来源) 4. 服务端代码 + 部署 + 验证 ← 由 Spec 派生 ``` > 注意: **如果 AI 直接甩给你一堆代码,却没有前 3 样,让它重来。** > 「先规格,后代码」是本 skill 的硬性要求(见 `references/ai-contract.md`)。 **另有两份"开工/收工"契约**(详见 `references/ai-contract.md`): ``` AGENTS.md ← 工作区边界 + 验证命令 + 收工状态(放在项目根) docs/status/support-matrix ← 三轴状态:实现 / 自动测试 / 客户端验收 ``` ## 可以这样追问 - 「先给我证据清单」 - 「先只做协议分层」 - 「为什么判定是 4 字节大端?证据是哪条?」 - 「服务端换成 Go 重写」 - 「把 opcode 表填进去」 - 「客户端连不上,帮我定位是哪一步」 - 「先把账号/登录接口列出来,登记到 TRACKER」 ## 常见问题指路 | 问题 | 看哪 | |------|------| | 不懂"在反推什么"/第一次做 | `references/primer.md`(原理层) | | 不知道先做什么、在哪验收 | `references/workflow-roadmap.md`(四阶段路线) | | 只有安装包怎么办 | `references/from-installer.md` | | 怎么注册账号 / 替换登录接口 | `references/account.md`(§16) | | 需要人机(假玩家) | `extensions/`(§18,可选) | | 不想起服务端 / 想单机化 | `references/inline-server.md`(M11 内联服务端) | | 进度/接口清单 | `TRACKER.md` | ## 不要这样问 - [x] 只给游戏名就让 AI 凭空写服务端 —— 没有证据 = 必错 - [x] 「直接给我能用的服务端」却不给任何输入 ## 使用守则与限制 > 完整守则见 [`references/usage-policy.md`](references/usage-policy.md);每次动手前先读。 **可做(允许)**:自研 / 已授权 / 离线单机目标的互操作性研究、协议文档化、学习与教学、已停服游戏的本地化存档(非商业)、授权范围内的安全评估。 **不做(禁止)**:未授权架设 / 运营他人游戏的服务器、绕过或破坏他人的技术保护 / 完整性校验 / 反作弊、商业化牟利、侵犯他人权益、破坏性攻击。 **硬性约束**:证据驱动(无证据 = 假设)、先规格后代码、只给方法不给具体游戏的成品 / 密钥、不提供保护绕过、fail closed(缺信息就说缺什么)、越界即停并给出合规替代。 - 使用参考项目 / 代码前先看其许可证。 --- ## 目录结构 ``` 离线本地化/ ├── SKILL.md 主流程(18 节,核心方法论) ├── README.md 本文件 ├── TRACKER.md 进度与接口清单(每模块更新,从简) ├── schema/ 中间产物模板(AI 填这些) │ ├── project-profile.yaml 项目档案 │ └── protocol.spec.yaml 协议规格(唯一事实来源) ├── references/ │ ├── adaptation.md 自适应方法论:项目→证据→决策→Spec │ ├── reading-path.md 最小必读路径(按任务类型分派) │ ├── primer.md 原理层:三要素/数据包协议/协议表/热更源码/双证据链 │ ├── workflow-roadmap.md 四阶段路线总纲(静态分析→建工具+登录链→重定向→补包循环→清单迭代) │ ├── phases-detail.md §1~§10 反推主流程详细版(命令/工具/判断/坑) │ ├── ai-contract.md AI 行为契约(强制产物/禁止/终点/回滚) │ ├── usage-policy.md 使用守则与限制(允许/禁止用途 + 硬性约束 + 自检) │ ├── server-architecture-basics.md 反推对象地图(逆向视角:你在还原哪几类服/网关隐藏层/同步模型) │ ├── methods.md 10 种反推方法 + 选择矩阵(动手前先看) │ ├── closure-verification.md 闭环验证 6 类假阳性(宣布成功前必看) │ ├── engineering-practices.md 实机跑通范式:fixture 回放 + 完成点 + 证据分档 + ADR │ ├── wire-level-patching.md 实现层核心:不依赖 pb runtime 的 wire 级定点改写 │ ├── client-address-sources.md 客户端地址来源清查 + 落点策略 │ ├── verification-and-status.md 三轴状态 + 可达性分类 + 测试门禁 │ ├── release-and-ops.md 发布 / 部署 / 运营 / CDN / 备份 │ ├── case-il2cpp-ecdh.md 真实案例:IL2CPP + ECDH 登录服 + 卡点复核 │ ├── inline-server.md 内联服务端:进程内合成响应(与外部服务端并列的第二条路) │ ├── runtime-object-synthesis.md 运行时对象合成与字段发现(对象级 schema 自举) │ ├── platform-sdk-and-admission.md 平台 SDK 登录态复用 + 目录服→区服两段准入 │ ├── case-il2cpp-inline.md 真实案例:IL2CPP + 平台 SDK 的内联服务端 │ ├── account.md 账号体系与接口还原(登录/注册/接口替换) │ ├── combat.md 房间与战斗(局内、同步模型、服务端权威) │ ├── drops.md 掉落与物资(掉落表、掷骰、背包满转邮件) │ ├── gacha.md 抽卡/扭蛋(服务端掷骰、保底、重复转换) │ ├── decision-tree.md 逐层决策树(引擎/传输/封装/加密/序列化/架构) │ ├── protocol-spec.md 协议规格规范 + codegen 映射 │ ├── codegen.md 由 Spec 生成/改造服务端(多语言) │ ├── client-languages.md 客户端语言分支(C#/AS3/Lua/JS/Java/C++) │ ├── from-installer.md 零输入自举:只有安装包怎么自产证据 │ ├── cases.md 两个真实成功项目案例(Go / Node) │ ├── unity.md Unity(IL2CPP/Mono/Lua) 深潜 │ ├── unreal.md Unreal(UE4/UE5) 深潜 │ ├── windows.md 端游:Windows 运行服务端 │ ├── termux.md 手游:Android/Termux 运行服务端 │ └── repack-rename.md 改包名/重打包/签名/包名派生密钥 ├── examples/ 推演示例(同 skill,不同项目→不同方案) │ ├── A-unity-il2cpp-protobuf.md │ ├── B-ue-kcp-custom.md │ ├── C-unity-lua-http.md │ └── D-real-lua-client.md 真实 Lua 源码分析(1794 个 opCode) ├── tools/ │ └── extract_interfaces.py 接口清单提取器(扒 opCode/路由) ├── templates/ 参考代码与文档模板 │ ├── mock_server.py 极简桩 │ ├── frida_bypass_ssl.js / kcp_sniff.py │ ├── frida-redirect.js 客户端重定向:hook getaddrinfo/connect(native/il2cpp) │ ├── xposed-redirect/ LSPosed 模块骨架:改写 URL(Java/OkHttp 客户端) │ ├── register-site/ 注册网站(index.html + 最小 Flask 后端) │ ├── AGENTS.md 工作区 AI 协作契约(放在项目根) │ ├── adr-template.md 架构决策记录(含「当前不做的事情」+ 回滚) │ ├── e2e-evidence-template.md 实机端到端证据(帧序表 + 差异解释 + 重连快照) │ ├── status-matrix.md 三轴状态矩阵(实现 / 测试 / 客户端验收) │ ├── login-chain.md 登录链条文档(启动到主场景每一步) │ └── function-checklist.md 功能清单(按子系统登记实通/未通) ├── extensions/ 后续拓展(可选,不影响核心运行) │ ├── README.md 拓展说明与判断标准 │ ├── bots.md 服务端人机(假玩家) │ └── bot-reverse.md 反推人机机制再复刻 └── server/ 参考实现:长连接二进制协议服务端(Python) (GitHub: https://github.com/ShrugYu/game-client-to-server-reverse/tree/main/game-client-to-server-reverse/server) ``` ## 端游 / 手游怎么跑 | 平台 | 启动 | 常驻 | 客户端对接 | |------|------|------|-----------| | Windows(端游) | `deploy/start_windows.bat` | NSSM 服务 | 改 hosts → 127.0.0.1 | | Android(手游) | `bash start_termux.sh` | wake-lock + tmux | hosts / DNS 重定向 | | Linux 服务器 | `deploy/deploy.sh` | systemd | 域名解析 / 端口转发 | | Docker | `docker compose up -d` | 容器策略 | 同上 | ## 客户端语言不只有 Unity/UE | 客户端语言 | 反编译工具 | 能拿到源码? | 客户端补丁方式 | |-----------|-----------|------------|--------------| | C#(Unity Mono / .NET) | dnSpy / ILSpy | [x] 近源码 | 配置 / 重编译 / hook | | C#(Unity IL2CPP) | Il2CppDumper + IDA | [x] 仅签名 | Frida hook | | ActionScript3 / Flash | JPEXS FFDec | [x] 反编译 | 改源码重编译 | | Lua 热更 | unluac / luadec | [x] | 改 lua | | Java/Kotlin | jadx | [x] | smali patch / hook | | JS / H5 | beautify / sourcemap | [x] | 改 js | | C++ / UE | SDK dump | 注意: 结构 | hook / patch | 详见 `references/client-languages.md`。 真实项目案例(Go 服务端 + C# 启动器;Node/TS 服务端 + AS3 客户端)见 `references/cases.md`。 ## 服务端语言也不固定 Python 只是本仓库的参考实现。真实案例里:**Go**(某 Unity 手游)、**Node/TS**(某 Cocos 手游)。 选型见 `references/codegen.md`,由 Spec 决定,不是照抄。 ## 充值 / 发放(自托管支付) - `game.pay_grant_mode`: `direct`(直接进背包)/ `mail`(发邮件领取) - `game.pay_auto_success: true` → 点击购买直接成功 - 商品表 `PAY_PRODUCTS` 键 = 客户端真实 `product_id` ## 后续拓展(可选,不影响核心运行) > **判断标准**:去掉它,游戏还能不能正常玩?**能 → 就是拓展。** > > 注意: **内联服务端不是拓展**:它是与「外部服务端」并列的**核心路线**(M11,见 `references/inline-server.md`), > 不适用本判断标准。 | 拓展 | 文件 | 一句话 | |------|------|--------| | 服务端人机(假玩家) | `extensions/bots.md` | 多人游戏凑不齐人时用 AI 补位 | | 反推人机机制 | `extensions/bot-reverse.md` | 无参考项时,从客户端反推它的人机实现 | **人机为什么是拓展**:单人也能玩的游戏完全不需要;多人游戏缺人只是**体验受损, 服务端本身能跑**,不影响「本地离线运行 / 登录 / 进游戏」。 - 参考骨架:`server/app/logic/bots.py`(**只是骨架**,默认 `auto_fill: 0` 不生成假玩家) - 联调:`python server/test_bots.py` > 注意: 拓展**不参与**核心验收。没做拓展 ≠ 交付不完整。 ## 两种服务端模板怎么选 | | templates/mock_server.py | server/ | |---|---|---| | 用途 | 抓包后快速验证协议结论 | 真正部署、长期运营 | | 规模 | 单文件 | 分层工程 | | 能力 | 帧收发 + opcode 桩 | 数据库/状态机/客户端保护/部署 | | 何时用 | 逆向中期试探 | 逆向完成、要跑起来 | ## 最快上手 ```bash # 1. 起服务端 cd server && chmod +x start.sh && ./start.sh # 2. 联调自测(另开一个终端) ./venv/bin/python client_test.py --host 127.0.0.1 --port 8888 \ --user alice --password 123456 --name Hero01 # 期望输出结尾:[+] full flow OK # 3. 部署到服务器 sudo bash server/deploy/deploy.sh ``` ## 工作流 ``` [只有安装包?] 解包 → 判引擎/语言 → 自产 dump/lua/资源 → 抓包 → 动态dump ↓ 侦察引擎 → 协议分层 → 客户端静态定位 → 字段推断 → 服务端建模 → 部署 → 客户端对接 → 闭环验证 ``` > 只有 `.apk`/`.ipa`/`.exe` 也能开始 —— 见 `references/from-installer.md`。 ## 给 AI 的使用方式 1. 把辅助文件(`dump.cs` / `*.lua` / `*.usmap` / SDK `.h`)丢进来。 2. AI 按 `SKILL.md §1` 分类,自动进入 Unity 或 UE 分支。 3. 逆向结论落到 `server/app/proto/`(消息号 + 结构)与 `config.yaml`(协议参数)。 4. 起点验证用 `templates/mock_server.py`,终点交付用 `server/`。 ## 免责声明 > 使用本资料库skill即表示你已阅读、理解并同意以下全部条款;若不同意,请立即停止使用。 1. **用途限定**:本 skill 资料仅供**学习、研究与技术交流**,以及针对**自研、已获授权或离线单机**游戏的互操作性研究与本地化部署。这是一份**方法论文档**,不针对任何特定特定项目。 2. **禁止非法用途**:严禁将本资料用于任何**未经授权**的入侵、攻击、破坏、篡改、绕过安全机制、窃取数据,或侵犯他人知识产权、违反目标游戏服务条款及所在地法律法规的行为。 3. **无担保**:本资料按"**现状**(as-is)"提供,不附带任何明示或暗示的担保,包括但不限于适销性、特定用途适用性与不侵权担保。作者不保证其准确性、完整性或可用性。 4. **责任限制**:在适用法律允许的最大范围内,作者及贡献者**不对因使用或无法使用本资料而产生的任何直接、间接、附带、特殊、惩戒性或后果性损失承担责任**(包括但不限于数据丢失、设备损坏、ai平台账号封禁及法律纠纷)。 5. **使用者自负其责**:使用者须**自行确保**其使用行为合法合规(含取得必要授权),并**独立承担由此产生的全部法律责任与后果**。 6. **第三方内容**:本资料引用或链接的第三方项目、代码、工具、文档及服务,其版权与许可归各自所有者所有;使用前请自行查阅并遵守其各自条款。作者不对第三方内容及其后果负责。 7. **权利主张**:若你是某作品的权利人,并认为本资料侵犯了你的合法权益,请通过仓库 Issue 联系,作者将在核实后**及时更正或删除**。 8. **平台规则**:权利人可发起 DMCA 下架;GitHub 会因违反可接受使用政策处理本仓库。 9. **AI 平台安全提示与账号责任**:本 skill 涉及逆向 / 协议分析等**可能触发 AI 平台安全规则**的内容。使用本 skill 时,你接入的 AI 服务(如 GPT / Codex / Claude 等)**可能因你的提示词内容性质触发安全提示、限制响应,甚至导致你的 AI 账号被限制或封禁**。**本 skill 作者不对任何 AI 平台对你账号采取的任何措施负责**,包括但不限于警告、降级、限制或封禁。使用前请充分了解你所使用的 AI 平台的服务条款与安全策略,并自行承担相应风险。 10. **条款变更**:本免责声明可能随时更新,更新后自发布之日起生效,恕不另行通知。 ### 关于复活已停止运营的网络游戏的说明 本资料常被用于**已停止运营(停服 / 官方终止在线服务)**的网络游戏的存档保存、历史研究与本地化重开。就此类用途,特别声明如下: - **「已停服」不等于「进入公有领域」**。该类游戏的代码、美术、商标、剧情、音频等知识产权仍归**原权利人**所有;停服**不等于**权利人放弃权利,也不构成对第三方运营的授权。 - 本资料仅支持**面向既有玩家社区或个人的非商业性研究、存档与延续**用途。**严禁**将其用于冒充官方、商业化牟利、发行收费服务,或损害原权利人及原玩家社区利益的行为。 - AI 生成内容所涉及的复活、部署与运营所引发的一切**法律、经济与声誉风险,由使用者自行承担**;作者不参与项目、不提供背书、不承担任何责任。 - 若原权利人或其权利继承方提出异议,作者将**配合删除本仓库**相关资料。 -
SKILL.md 29.5 KB
--- name: game-client-to-server-reverse description: 从游戏客户端(安装包/APK/IPA/EXE 或 dump.cs、lua、usmap、抓包等)反推服务端协议并复现可部署服务端。含阅读路径分派、原理层(primer:三要素/数据包协议/协议表/热更源码)、四阶段路线图(workflow-roadmap:静态分析→建工具+登录链→重定向→补包循环→清单迭代)、11 种反推方法选择器(含内联服务端路线)、接口清单提取器(tools/)、协议规格模板(protocol.spec.yaml)、wire 级定点改写(不等 schema 齐就能跑)、客户端地址来源清查、三轴状态与验收体系、发布运维清单、进度清单(TRACKER.md)、登录链条与功能清单模板。覆盖:账号登录注册、房间匹配、战斗、掉落物资、抽卡、充值与邮件、部署(本地/服务器/Termux/Windows)、客户端对接、闭环验证;并支持 Unity(IL2CPP/Mono/Lua)、Unreal(UE4/UE5)、Cocos2d-x/Cocos Creator(JS/Lua 热更)、C#、AS3、Java、JS 等客户端;含进服后的 Live 运营手册;并含「内联服务端」路线(客户端进程内合成响应、运行时对象合成与字段发现、平台 SDK 登录态复用与目录服/区服两段准入)。 license: 仅限自研 / 已授权 / 离线单机目标用于互操作性研究与本地化部署;不得用于未授权破坏性测试或商业化他人资产(边界详见 README.md) compatibility: 需要 Python 3.10+(pip 可装 flask / PyYAML / aiosqlite);参考服务端可在本机、Termux、WSL2 或 Windows PowerShell 运行;联网可选(查资料、下载工具时)。跨平台:android / ios / windows / linux。 metadata: version: "2.0" platforms: "android, ios, windows, linux" spec: 遵循 Agent Skills 规范(name 与父目录名一致;SKILL.md < 500 行;references 按需加载) --- # 游戏客户端 → 离线本地化 Skill > **定位**:把「只有客户端」的游戏,还原出「服务端协议 + 本地离线服务端」,并让原版客户端**本地离线运行**。 > **适用**:互操作性研究、本地离线化 / 离线版建模、协议文档化、安全评估、游戏存档研究。 > **边界**:仅用于自研、已授权或离线/单机目标。禁止未授权破坏性测试与商业化他人资产。 > **版本 v2.0**(完整变更历史见 `README.md`)。2.0 较 1.x 新增:**原理层** `primer.md`、**四阶段路线图** > `workflow-roadmap.md`、**反推对象地图** `server-architecture-basics.md`、**重定向落点(含 Xposed/LSPatch 模块)**、 > 复活 / 本地离线项目合集、登录链/功能清单模板、全库去除 emoji、跨模型阅读优化,并对 SKILL.md 大幅瘦身。 --- ## 阅读协议(任何模型通用:GLM / DeepSeek / Claude / …) > 本包 = 1 份长文档(`SKILL.md`)+ 37 篇 `references/` + `templates/` + `tools/` + 参考实现 `server/`。 > **不要一次读完**——会耗尽上下文,结果在没读完的地方开始猜。 > **注意:多数模型不会自动加载 references,必须显式打开文件。** > **先读 `references/usage-policy.md`(使用守则与限制)——确认用途合规、不越界,再动手。** **标准三步(照做即可)**: ``` 1. 先读完本文件 §0(方法选择 + 铁律 + 工作流 + 补包循环)—— 必读核心 2. 打开 references/reading-path.md → 按你的任务类型拿到 3~5 个文件的阅读顺序 3. 按顺序打开并读完那些文件 → 再动手 收工前:打开 references/reading-path.md §2,过一遍「收工前检查」 ``` **上下文很少时**(只能读 1~2 篇),按此优先级取: `SKILL §0` → `reading-path.md` → `wire-level-patching.md` → `closure-verification.md` → `client-address-sources.md` > 一句话:**SKILL.md 是导航,references 是正文**。先读导航,再按需读正文。 --- ## 阅读地图:三条主线,先认清自己在哪条 > 这个包讲三件事。**先确认自己卡在哪条主线,再去读对应文件**,不要混着读。 | 主线 | 回答的问题 | 先读 | 关键产物 | |------|-----------|------|---------| | **A. 原理** | 「到底在反推什么?」 | `references/primer.md`、`references/server-architecture-basics.md` | (认知:三要素 / 协议表 / 热更源码 / 反推对象地图) | | **B. 路线** | 「先做什么、后做什么、在哪验收?」 | `references/workflow-roadmap.md` | `login-chain.md`、进度 | | **C. 方法** | 「用哪个手段取证?」 | `references/methods.md` | 选定方法 → `project-profile.yaml` | | **D. 规格** | 「怎么把结论固定下来?」 | `references/protocol-spec.md` | `protocol.spec.yaml`(唯一事实来源) | **一句话**:A 讲「找什么」,B 讲「什么顺序」,C 讲「怎么找」,D 讲「怎么记」。 - **新手 / 第一次接触某客户端** → 先读 A(`primer.md` + `server-architecture-basics.md`),再看 B。 - **知道自己要干什么、只是缺手法** → 直接看 C(`methods.md`)+ §0.0。 - **已经拿到证据、要落盘** → 直接看 D(`protocol-spec.md`)。 --- ## 0. 本 Skill 的定位:通用适配器,不是固定方案 **核心认知(先读三遍)**: > 这个 skill 里附带的任何代码(`server/`、`templates/`、`examples/`)都只是**参考实现**, > **不是**对某个游戏的答案。每个游戏的引擎、传输、封装、加密、序列化、消息号、字段布局 > **都不一样**。AI 必须先**读取用户实际给的项目**,产出**协议规格(Protocol Spec)**, > 再据此**生成或改造**服务端。 ### 0.0 第一步:选对方法 (最容易做错的一步) > **方法选错 = 后面全白干。** 完整方法论见 `references/methods.md`。 **先回答 3 个问题**: 1. **有什么?** `PKG`(只有安装包) / `CAP`(抓包) / `SRC`(源码或反编译产物) / `RUN`(能运行) / `DBG`(能注入) / `MANIP`(能改客户端或代理) / `REF`(有同类实现) 2. **要什么?** `DOC`(只要文档) / `FLOW`(跑通主流程) / `FULL`(完整服务端) / `PATCH`(改客户端) 3. **什么约束?** 客户端保护 / 时间 / 权限 **十一种方法速览**(详见 `methods.md`): | 代号 | 方法 | 何时用 | |------|------|--------| | M1 | 白盒源码法 | 有 `SRC` → **首选** | | M2 | 黑盒抓包法 | 有 `CAP` → 通用 | | M3 | 灰盒 Hook 法 | 有 `RUN`+`DBG` → 破加密 | | M4 | 辅助 Artifact 法 | 有 `.proto`/`.usmap`/SDK → 一步到位 | | M5 | 代理透传+逐接口替换 | 有 `CAP`+`MANIP` → **最稳落地** | | M6 | 差分探测法 | 定字段 | | M7 | 回放/录像法 | 有录像 → 战斗协议 | | M8 | 已知实现移植法 | 有 `REF` → 抄作业 | | M9 | 自环法 | 起桩看客户端要什么 | | M10 | 穷举校验法 | 兜底(优先 M3) | | M11 | 内联服务端法 | 有 `RUN`+`DBG`/`MANIP` 且可单机化 → **不起外部服务端** | **默认路线**(不知选什么就用它): ``` M1/M4(有源码就抄)→ M2+M3(拿明文)→ M6(定字段)→ M9(跑通连接) → M5(透传+逐接口替换)→ 闭环验证 ``` > **另有一条主干分叉**:目标可单机化 + 客户端能注入/能改 → 走 **M11 内联服务端**(`inline-server.md`), > 传输 / 封装 / 加密层**不必还原**。先判分叉,再选方法。 > 注意: 现实中都是**组合使用**(如 M1+M6+M5)。 > 选定后记进 `project-profile.yaml` 的 `method` 段;发现更好路径可**中途切换**。 ### 0.1 五条铁律 1. **证据驱动,不臆测**:所有结论必须来自用户项目里的实际证据(dump.cs / lua / 抓包 / SDK / 资源文件 / 客户端行为)。 没有证据 → 标注为「假设」并写进 Spec 的 `unresolved` 列表。 2. **先产出规格,再产出代码**:中间必须有一个**语言无关的协议规格文件** (见 `references/protocol-spec.md` 与 `schema/protocol.spec.yaml`)。 代码是从规格派生出来的,换游戏 = 换规格,不是重写一堆散代码。 3. **闭环验证**:服务端必须能让**原版客户端**跑通到某个状态(握手/登录/进场景),否则推断就是错的。 4. **不把「能跑」当成「跑通」**:端口在 listen、自环脚本报 `OK`、日志打了 [x], **都不是**闭环证据。宣布成功前必须逐条排除假阳性 → **见 `references/closure-verification.md`**(接手别人项目时尤其必读)。 内联路线另有一套判据:**界面截图不算**,要看网络 / 状态层的完成点 → `inline-server.md` §6。 5. **三件事分开记**:「服务端实现了」「自动测试覆盖了」「客户端验收了」。 用一个状态列会掩盖后两项 → **见 `references/verification-and-status.md`**。 不支持的输入要 **fail closed**,不要猜一个值。 ### 0.2 双证据链 任何字段结论 = **流量证据**(抓包里字节变化) + **代码证据**(客户端里的结构体/序列化代码)。 单侧只算假设。 ### 0.3 四层剥离(先分层,再解字段) 不要一上来抠某个字节。先弄清 `传输层 → 封装层 → 加密/压缩层 → 序列化层`,每层剥离后再看内容。 ### 0.4 自适应工作流(本 skill 的主干) > **输入可能是零**:如果用户只给了一个安装包(apk/ipa/exe),先走 > `references/from-installer.md` 的**自举流水线**把证据造出来,再进入下面的步骤。 ``` [第0步] 读取输入 ├─ 只有安装包 ? ──▶ references/from-installer.md │ 解包 → 判引擎/语言 → 自产 dump.cs/dll/lua/资源 → 抓包 → 动态 dump └─ 已有 dump/lua/抓包 ? ──▶ 直接进第1步 ↓ [第0.5步] 建立工作区契约 → 在项目根放 AGENTS.md(边界/目录分区/验证命令) ← templates/AGENTS.md ↓ [第1步] 产出「项目档案 project-profile」 ← references/adaptation.md 扫描目录/文件,识别引擎、语言、网络库、资源格式、已知工具产物 ↓ [第2步] 证据清点 → 证据清单 evidence-inventory 每条证据:来源、类型、能得出什么结论、置信度 ↓ [第3步] 决策引擎 → 逐层决策(引擎/传输/封装/加密/序列化/架构) ← references/decision-tree.md 每个决策点都有"若…则…"的分支,禁止默认套用参考实现 ↓ [第4步] 产出协议规格 protocol.spec.yaml ← references/protocol-spec.md 语言无关,含 opcodes / frames / crypto / serialize / state_machine / client / subsystems ↓ [第5步] 由规格生成/改造服务端(多语言参考) ← references/codegen.md 选一个最贴近目标协议的语言;参考实现只提供"套路",不提供"答案" ↓ [第6步] 平台部署(端游/手游/服务器) ← §14 ↓ [第7步] 客户端对接 + 闭环验证 ← §8/§9 ``` > **可选分叉(M11 内联服务端)**:若目标可单机化且客户端能注入 / 能改,可跳过传输与加密层的还原, > 直接在客户端进程内合成响应 → `references/inline-server.md`。 **换个视角看同一件事——四阶段路线(见 `references/workflow-roadmap.md`)**: ``` 阶段0 静态分析(清点线索) → 阶段1 建工具+登录链文档 → 阶段2 重定向(让请求到达本地离线服务端) → 阶段3 补包循环(上游→下游,客户端能走到下一步才算通) → 阶段4 功能清单迭代 ``` > §0.4 是"**按产物**推进的流水线",四阶段是"**按顺序+验收**推进的路线图",两者是同一件事的两种记法。 > 不确定从哪下手时,先看 `workflow-roadmap.md` 的全景图。 ### 0.4b 补包循环 (进游戏阶段的核心工作模式) > 这是**"让客户端一步步前进"的唯一主线**。四阶段的**阶段 3** 就是它。 > 前两步(静态分析、重定向)都只是为它铺路。 **方向:从【登录链最上游】往下游补回包** ``` ① 先回【服务器列表】 ← 地址来自这里 ② 再回【登录握手】 ← 鉴权 / token / hash ③ 最后补【游戏需要的数据】← 角色 / 背包 / 任务 / VIP / 签到 … ``` **通过标准:每补一块,以「客户端能走到下一步」为准** > 不是"服务端没报错",而是**客户端真的前进了一步**(界面前进 / 状态推进)。 > —— 这是铁律 4「不把『能跑』当『跑通』」在补包阶段的落地。 **出错怎么查:对照报错 + 两侧日志** 拿 `客户端报错`、`网络日志`、`服务端日志` **三边对齐**,判断属于哪一种: | 症状 | 大概率原因 | |------|-----------| | 客户端没反应 / 静默断开 | **格式错了**(帧 / 字节序 / 字段布局 + 长度) | | 明确报错 / 空指针 | **数据缺失**(少字段、空子消息被省略) | | 走到了下一步但还是不对 | **逻辑根本没有写**(该给的条件数据没给) | **里程碑:能进入游戏主场景 = 成功一大半。** 之后**工作流程就只有这一条路线**——不断让用户测试工作区目标,循环: ``` 测试 →(看日志)→ 定位 →(改)→ 修改 → 再测试 ↺ ``` **收尾:整理【功能清单文档】放到工作区,反复迭代直到基本完善** → `templates/function-checklist.md`。 > 详细版(含三边对齐的排错顺序、假阳性排查):`references/workflow-roadmap.md` §阶段 3~4。 ### 0.5 参考实现的正确用法 | 参考物 | 是什么 | 怎么用 | |--------|--------|--------| | `references/primer.md` | **原理层**:三要素(配置/协议/代码)、数据包协议本质、协议号与协议表、热更源码、双证据链 | **第一次接触某客户端时先读**,避免"不知道在找什么" | | `references/workflow-roadmap.md` | **四阶段路线总纲**(静态分析→建工具+登录链→重定向→补包循环→清单迭代)+ 四层重定向表 | **动手前看全景图**;它把 §0.4 与 M1~M11 串成一条有验收的线 | | `references/server-architecture-basics.md` | **反推对象地图(逆向视角)**:你在还原哪几类服、网关留下的隐藏层、从包里认 Protobuf/KCP、同步模型决定"要还原多少逻辑" | **判断"你在反推哪几类服、去哪找证据"时读**;避免在网关层迷路 | | `server/` | 长连接二进制协议的参考实现(Python) | **只借鉴分层结构与套路**,协议参数全部按 Spec 改 | | `templates/mock_server.py` | 极简单文件桩 | 逆向早期快速验证用 | | `examples/*.md` | 不同游戏类型的**推演示例** | 看"给定这类证据会怎么决策",不要照搬结论 | | `references/cases.md` | **两个真实成功的服务端项目**(Go / Node) | 看真实项目的子系统与取舍,校准自己的方案 | | `references/client-languages.md` | 各客户端语言的反编译与打补丁 | 先判语言,再选工具 | | `references/cocos2d.md` | **Cocos2d-x / Cocos Creator 深潜**(.jsc/.lua 解包 / 自加密 HTTP-RPC / 多端口 / 热更 / 语言表还原 / **§H2 进服后的 Live 运营**:note 双层包裹、客户端本地存档合并、双表版本差异、自愈设计、部署纪律) | 目标是 cocos 客户端时必读(另见 `examples/E-cocos2dx-http-js.md` §8 Live 运营阶段) | | `references/live-ops.md` | **Live 运营手册**(进服后 30+ 子系统按投诉频率排序的补全次序 / 契约反推法 / 自愈设计 / 双表差异处置) | **进服之后**读,与 cocos2d.md §H2 互补、引擎无关 | | `references/from-installer.md` | **零输入自举**:只有安装包怎么自产证据 | 最常见的入口,必读 | | `references/reading-path.md` | **最小必读路径**(按任务类型给 3~5 个文件的阅读顺序) | **打开 skill 的第一件事** | | `references/methods.md` | **10 种反推方法 + 选择矩阵** | **动手前先看**(§0.0) | | `references/closure-verification.md` | **闭环验证 6 类假阳性 + 检查表** | **宣布"成功"前必看**;接手别人项目时第一条 | | `references/engineering-practices.md` | **实机跑通项目的工程范式**(fixture 回放 / 具名完成点 / 证据分档 / ADR) | **动手前定策略**;配套 `templates/adr-*.md`、`templates/e2e-*.md` | | `references/wire-level-patching.md` | **实现层核心**:不依赖 protobuf 运行时的 wire 级定点改写 | **写服务端之前必读**;决定"先跑起来还是先凑 schema" | | `references/client-address-sources.md` | **客户端地址来源清查**(六类来源 + 落点策略 + 重签后果) | **改包/对接客户端之前必读**;解决"改了 URL 还连官方" | | `references/verification-and-status.md` | **三轴状态 + 可达性分类 + 测试门禁** | 写 TRACKER / 宣称完成之前必读 | | `references/release-and-ops.md` | **发布、部署与运营**(配置冻结 / 端口族 / CDN / 备份) | 跑通之后要交付时看 | | `references/case-il2cpp-ecdh.md` | 真实案例:Unity IL2CPP + ECDH 登录服(进行中) | 看"分层结论怎么写 + 卡点怎么复核" | | `references/repack-rename.md` | 改包名 / 重打包 / 签名 / 包名派生密钥 | 想产独立安装包时看 | | `references/inline-server.md` | **内联服务端**:在客户端进程内合成响应(门面三类入口 / 回调投递纪律 / 延迟派发 / 双通路 / 内联版验收与假阳性) | **能注入且要单机化时先读这个** —— 它决定你要不要起外部服务端 | | `references/runtime-object-synthesis.md` | **运行时对象合成与字段发现**(对象级 schema 自举 / dump 循环 / 填值纪律 / 对象级→wire 级切换) | 走内联路线时必读;也可用来先拿一份可信字段清单 | | `references/platform-sdk-and-admission.md` | **平台 SDK 登录态复用 + 目录服→区服两段准入** | 大厂手游(第三方平台账号 SDK)登录卡点时读 | | `references/case-il2cpp-inline.md` | 真实案例:Unity IL2CPP + 平台 SDK 的内联服务端 | 看「不起服务端」这条路怎么走、哪些结论已被证伪 | | `schema/*.yaml` | 规格/档案模板 | 直接复制填,作为 AI 的中间产物 | | `extensions/` | **后续拓展(可选)**,不影响核心运行 | 跑通之后再考虑,见 §19 | > 注意: 反例:直接把 `server/config/config.yaml` 的 `opcode_size=2` 拿去套一个 1 字节消息号的游戏 —— 必错。 > 正确做法:Spec 里写明 `opcode_size: 1`,再改代码。 ### 0.6 启动阶段的两把钥匙 > 来自实机跑通到「主界面」的真实项目范式,详见 `references/engineering-practices.md`。 > **先读这两条,能少走几周弯路。** **钥匙一:fixture 回放(抓包 → 原样重放 + 定点改写)** 启动时客户端要一次性吃下几十个字段的嵌套状态(角色/背包/任务/VIP/签到…), 纯靠反推字段拼几乎必卡在某个页面。更快的路径: ``` 原版客户端连原版服务器 → 抓一次完整启动序列 → 落成 fixture(含方向/消息号/seq/flag/原始 body) → 本地服务端按【原始顺序】重放 → 未知字段【原样保留】,只对已确认字段做 wire-level 定点改写 ``` **具体怎么实现**(不引入 protobuf 运行时的字段遍历 + splice 替换) → **`references/wire-level-patching.md`**(含帧 codec、字段遍历器、 `patch_varint/bytes/string`、"空子消息也要保留"等实测经验) > 注意: 两个红线:① 不要用「缺字段的伪造对象」代替真实启动数据; > ② 一个账号的 fixture 带着它的 UID/角色数据,**不能直接发给别的账号**。 **钥匙二:具名「完成点」做验收** 不要写「登录成功」。要写**客户端上的一个可观察状态**,例如: 「收到启动结束消息后进入**主界面**,**不是只保持 TCP 连接**」。 再补一次**强制停止 + 重启 + 重连**,确认状态仍在。 配合使用:`templates/e2e-evidence-template.md`(帧序表 + 主动解释帧长差异 + 重连快照)、 `templates/adr-template.md`(写清「当前不做的事情」与回滚条件)。 --- ## 1. 输入分类与预处理 > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 2. 阶段一:侦察与引擎识别 > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 3. 阶段二:流量获取 > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 4. 阶段三:协议分层识别 > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 5. 阶段四:客户端静态分析(分引擎) > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 6. 阶段五:字段语义推断 > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 7. 阶段六:服务端建模与实现 > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 8. 阶段七:部署(本地 / 服务器 / 容器) > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 9. 阶段八:验证与回滚 > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 10. 输出物清单(交付模板) > 详细步骤(命令 / 工具 / 判断 / 常见坑)见 `references/phases-detail.md`。 ## 11. 常见坑(速记) > **完整清单见 `references/closure-verification.md` §附「高频常见坑速查」**。这里只留最要记住的几条: - **改包顺序**:先"不改包 + 端口劫持"跑通协议,**最后**才改包(动手前读 )。 - **raw deflate ≠ 加密**:先在 `decision-tree.md §4.0` 做 30 秒快筛,别在错误的加密假设上耗数小时。 - **别把"能跑"当"跑通"**:端口在听 / 自环 OK / 日志打勾都不是闭环证据(铁律 4)。 - **只跑通登录不算完**:状态机未闭环,客户端进场景即崩。 --- ## 12. 工具速查 | 用途 | 工具 | |------|------| | Unity IL2CPP dump | Il2CppDumper / Il2CppInspector / r2unity | | Unity Mono | dnSpy / ILSpy | | Lua 反编译 | unluac / luadec | | 反汇编 | IDA Pro / Ghidra / Hopper | | 动态 | Frida / x64dbg / lldb | | UE 资源 | FModel / UnrealPak / umodel / AesFinder | | UE SDK/mapping | Dumper-7 / UE4SS / usmap dumper | | 抓包 | mitmproxy / Charles / Wireshark / tcpdump | | 协议试解 | protoc --decode_raw / binwalk / ent | | **接口清单提取** | `tools/extract_interfaces.py`(本 skill 自带) | | **so 结构 / 依赖 / 符号** | `readelf -d`(NEEDED)、`readelf --dyn-syms --wide`(**FUNC + OBJECT 都要看**)、`strings -a`(找硬编码常量) | | **APK 编辑 / 资源 / 重打包 / 签名** | MT 管理器(含 MCP:`http://127.0.0.1:8787/mcp`,可 dex/资源/构建/签名一条龙)、apktool、apksigner | | **ZIP 原样复制重打包** | 本 skill `tools/` 的 repack 脚本(2GB 包秒级,只替换目标条目) | | **动态调试 / 内存** | Frida、`/proc/<pid>/maps`(看加载了哪些 so) | --- ## 13. 使用本 Skill 的 AI 行为契约(必读) > 完整行为契约(强制产物 / 硬性禁止 / 缺信息做法 / 决策可追溯 / 终点定义 / 回滚)见 `references/ai-contract.md`。 > > **使用守则与限制(允许 / 禁止用途 + 硬性约束 + 自检清单)见 `references/usage-policy.md`——每次动手前先读。** ## 14. 运行环境与工具链(端游 / 手游) 服务端代码同一套,差别只在**运行平台 + 保活 + 客户端对接** → 详见 `references/termux.md`(手游/Android)、`references/windows.md`(端游/Windows)。 **环境选择**: ``` 只用 Python+SQLite → Termux / 裸 Windows 要 AES 或大量 Linux 工具 → Termux+proot Ubuntu / WSL2 要长期对外在线 → 云服务器(Ubuntu + deploy.sh) / Windows NSSM 仅本机自测 → 直接跑,客户端连 127.0.0.1 ``` > 注意: **保活**是最容易翻车的点:Termux 要 `termux-wake-lock` + 关电池优化;Windows 用**服务/计划任务**,别用前台窗口。 > 脚本:`server/start_termux.sh`、`server/deploy/start_windows.bat`。 --- ## 15. 充值 / 邮件 / 道具奖励发放 > 客户端连的是**我们自己的服务端**,第三方支付 SDK 不存在 → **下单直接判成功并发放**("点击购买即成功")。 > 参考实现:`logic/handlers/pay.py` / `mail.py`;商品表 `store/models.py: PAY_PRODUCTS`(键 = 客户端真实 product_id)。 - **两条路径**(`game.pay_grant_mode`):`direct` 货币直接进角色 / `mail` 发附件邮件自助领取;`pay_auto_success:true` 跳过真实校验。 - **协议**:`PAY_PRODUCT_LIST 0x0501/2`、`PAY 0x0503/4`、`MAIL_{LIST,READ,CLAIM} 0x0401~0x0406`、`MAIL_NEW_NTF 0x0407`。 - **踩过的坑**:① 邮件推送必须在 PayRes **之后**发(否则被当成充值回包);② 领取/已读/删除共用结构但**必须用各自 opcode**;③ `order_no UNIQUE` 保**幂等**;④ 发放全在服务端。 - **边界**:仅自建/离线/已授权;不接真实支付渠道、不伪造凭证。 --- ## 16. 账号体系与接口还原 > 目标:**官方客户端**用**我们自己注册的账号**登录我们的服务端。方法论 → `references/account.md`。 - **账号从哪来**:A 客户端内注册 / **B 独立注册网站**(写同一 DB,客户端只登录;模板 → `templates/register-site/`)/ C 脚本批量建号。 - **注意: 最大的坑——密码预处理**:客户端常先 `MD5(pwd+salt)` 再发包,**必须复刻其哈希**,否则注册的密码登不上。找法:读登录函数 / 抓两次包看密文是否固定;落 Spec 的 `account.password_hash/salt/client_side_hashing`。 - **接口替换**:优先**改配置 / hosts**,不动二进制;有服务器列表就返回我们自己的地址(→ §8.6、`client-address-sources.md`)。 - **典型链路**:`版本/公告 → 登录(账号+密文) → token → 服务器列表 → 带 token 连游戏服(TCP)`。 - 账号接口逐条登记进 `TRACKER.md`。 --- ## 17. 房间 / 战斗 / 掉落(核心玩法) > **没有战斗和掉落,游戏就不成立。** 方法论 → `references/combat.md`、`references/drops.md`; > 参考实现 → `server/app/logic/rooms.py`、`loot.py`、`handlers/{room,battle,drop}.py`。 - **关系**:`大厅/场景 → 房间(匹配/组队) → 战斗(回合/实时) → 结算 → 掉落(掷骰) → 背包/邮件`。 - **房间**:创建→加入/退出→准备→房主开始→战斗→回等待;必备**槽位上限、房主权限、全准备才开、房主退出移交、空房回收**。 - **战斗(铁律:结算在服务端)**:客户端只发意图;回合制=服务端算结果并广播,实时=服务端定权威状态。必备回合推进/伤害/超时判负/异常退出;结束广播 `BATTLE_RESULT_NTF`。 - **掉落**:`table_id → {rolls, entries:[{item_id, count[min,max], rate}]}`(从客户端配置表反推);**服务端掷骰**;背包满 → **自动转邮件补发**。 - **协议**:房间 `0x0601~0x060B`、战斗 `0x0701~0x0704`、掉落/背包 `0x0801~0x0805`(详表见 `server/app/proto/opcodes.py`)。 - **经济系统复用**:抽卡(`references/gacha.md`) / 商店 / 背包 **共用同一套「随机→结算→入库」**,不要写两套。 --- ## 18. 快速上手(AI 第一次拿到项目的动作序列) ``` [第 0 步 · 最重要] 选对方法 · 回答 3 个问题:有什么 / 要什么 / 什么约束 · 对照 references/methods.md §4/§5 选定方法 → 记进 project-profile.yaml 的 method 段 · 默认路线:M1/M4 → M2+M3 → M6 → M9 → M5 [如果只有安装包] 0. 走 references/from-installer.md:解包 → 判引擎/语言 → 自产证据 → 抓包 (详见该文件第 9 节的 10 项动作清单) [通用主流程] 1. 列目录 → 跑 references/adaptation.md 的探测命令 2. 填 out/project-profile.yaml(包括 needs 清单) 3. 逐条记录证据 → out/evidence-inventory.md 4. 走 references/decision-tree.md → 填 out/protocol.spec.yaml (含 client / subsystems 两段) 5. 检查 protocol-spec.md 的「Spec 完成度清单」 5.5 账号/接口:读 references/account.md → 在 TRACKER.md 登记接口清单 6. 按 references/codegen.md 选语言 + 改造/新建服务端 7. 增量验证(连接→登录→…)→ 回填置信度 8. 部署(§14)+ 客户端对接(§8)→ 闭环 ``` 看 `examples/` 里的三个推演,理解"同样流程、不同结论"。 --- ## 19. 后续拓展(可选,不影响核心运行) > **判断标准**:去掉它,游戏还能不能正常玩?**能 → 它就是拓展**(放 `extensions/`),**不写进核心流程**。 | 拓展 | 文件 | 一句话 | |------|------|--------| | **服务端人机(假玩家)** | `extensions/bots.md` | 多人副本凑不齐人时用 AI 自动补位 | | **反推人机机制** | `extensions/bot-reverse.md` | 无参考项时从客户端获取信息反推它的人机实现 | **人机为什么是拓展**:单人游戏完全不需要;多人缺人只损体验、**服务端本身能跑**;参考实现默认 `auto_fill: 0`(不生成假玩家)。 **用法**(跑通后再做):核心链路先通 → 确认是否"必须多人" → `bot-reverse.md` 反推机制写进 Spec → `bots.md` 实现 → 调试(`bots spawn/clear/difficulty`)→ 原版客户端验收。 > 注意: 拓展**不参与**核心验收(§13 的强制产物与闭环)。没做拓展 ≠ 交付不完整。 > 不要因为拓展没做就认为交付不完整;也不要把它塞进核心流程。 -
TRACKER.md 10.4 KB
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.