Claude Skill

game-client-to-server-reverse

从游戏客户端(安装包/APK/IPA/EXE 或 dump.cs、lua、usmap、抓包等)反推服务端协议并复现可部署服务端。含阅读路径分派、原理层(primer:三要素/数据包协议/协议表/热更源码)、四阶段路线图(workflow-roadmap:静态分析→建工具+登录链→重定向→补包循环→清单迭代)、11 种反推方法选择器(含内联服务端路线)、接口清单提取器(tools/)、协议规格模板(protocol.spec.yaml)、wire 级定点改写(不等 schema 齐就能跑)、客户端地址来源清查、三轴状态与验收体系、发布运维清单、进度清单(T

LLM Mart · 0 points · 0 views 66 listing impressions 0 install-command copies
Download ShrugYu-game-client-to-server-reverse-game-client-to-server-reverse-7780dd7.zip · 330 KB

Install

skills CLI npx skills add https://github.com/ShrugYu/game-client-to-server-reverse/tree/main/game-client-to-server-reverse
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install shrugyu-game-client-to-server-reverse@llmmart
Git 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.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

不要这样问

  • 只给游戏名就让 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 的使用方式

  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 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 个问题:

  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、日志打了 , 都不是闭环证据。宣布成功前必须逐条排除假阳性 → 见 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 的强制产物与闭环)。没做拓展 ≠ 交付不完整。 不要因为拓展没做就认为交付不完整;也不要把它塞进核心流程。

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.

No comments yet.

Reviews (0)

No reviews yet.