GameMod MCP

用元数据定位 Hook 落点的游戏 Mod 工具集 —— 一个 MCP 服务器，让任意通用 Agent（Claude Code / Codex / Cursor / …）都能做游戏 Mod。

支持 IL2CPP、Mono (.NET)、Unreal 三类引擎，45 个工具覆盖 「找游戏 → 建索引 → 查类/字段/方法 → 注入 → Hook → 读内存」全流程。

它解决什么问题

传统做法是拿内存修改器（Cheat Engine 式）反复搜值、改值、再筛。 问题在于：每一次都是在猜，游戏一更新全部作废，而且改完不知道为什么生效。

本工具集换一条路：游戏自己就带着完整的类型系统。

注意两侧的分工：静态元数据没有字段偏移、也没有方法地址（只有 token）。 偏移与地址一律来自注入后的运行时探针，token 是把两侧对上的钥匙。

具体做法是两段式：

1. 离线解析元数据 —— IL2CPP 的 global-metadata.dat、Mono 的托管 dll。 拿到类型、字段、方法、token 的完整清单。

2. 在线问运行时 —— 注入 Frida 探针，问游戏「这个字段真实偏移多少 / 这个方法真实地址在哪」。两边的 token 对上号，就是「我挂的确实是 我想挂的那个方法」的硬证据。

AOB 扫描（scan_pattern）保留，但只是符号被剥离时的兜底。

Related MCP server: Frida Game Hacking MCP

快速开始

1. 装依赖

pip install -r requirements.txt      # 只有 mcp + frida

引擎解析器（PE / IL2CPP / Mono）全部手写、只用标准库，不依赖 pefile / lief / 任何反编译框架。

一键安装（含冒烟测试）：

python install.py          # 主推：纯 Python，Windows 自带 PowerShell 5.1 读不了
                           # 无 BOM 的 UTF-8 中文脚本（会语法报错），而 pwsh 不一定装了
python install.py --vision # 连可选弱视觉（截图 / OCR）一起装

本项目只支持 Windows。 install.ps1 仍保留，但只能用 pwsh（PowerShell 7）跑 —— 用 Windows 自带的 powershell（5.1）会因中文编码问题直接语法报错。

2. 接进你的 Agent

各客户端的现成配置在 mcp-config/，支持 Claude Code、Codex CLI、Cursor 以及任何标准 MCP 客户端。

以 Claude Code 为例，项目根目录建 .mcp.json：

{
  "mcpServers": {
    "gamemod": {
      "command": "python",
      "args": ["C:/path/to/GameModMCP/src/gamemod_mcp/server.py"],
      "env": {
        "PYTHONPATH": "C:/path/to/GameModMCP/src",
        "PYTHONUTF8": "1"
      }
    }
  }
}

3. 让 Agent 加载 skill

把 skills/gamemod-mod/ 放进你的 Agent 的 skill 目录。它包含完整工作流、各引擎差异、7 个配方（含 Unreal 路线）、以及一份 「查不到东西怎么办」的排查表——这是让 Agent 少走弯路的关键。

4. 开跑

你：帮我找到 Garden of Witches 里的存档服务，看看金币字段叫什么

Agent 会自动：
  get_diagnostics()         → 确认 Frida 可用
  inspect_game(...)         → 识别为 IL2CPP
  open_game(...)            → 建索引（首次约 2s，之后 10ms）
  search_fields("gold")     → 定位候选字段
  class_detail(...)         → 确认所属类与类型
  inject_process()          → 注入探针
  runtime_class_info(...)   → 拿真实字段偏移

工具一览（45 个）

本清单由 python devtools/gen_docs.py 从代码生成（来源：各工具函数的 docstring 首段 + server.py 的层节注释）。 不要手工编辑这一节 —— 下次 --check 会报红。 要改描述就改该工具的 docstring 首段，再跑 python devtools/gen_docs.py --write。

为什么改成生成：校验只能发现漂移，生成本不会产生漂移 —— 本表的工具数曾手工漂过 5 次以上。 改造前做过「知识上移」核对：原单元格里有 402 个特征词是 docstring 没有的， 直接生成会丢掉那些手写事实，所以先把它们补进了 docstring 首段。

发现层

会话层

静态查询层（不需要游戏在运行）

结果句柄层（大结果集翻页）

运行时层

弱视觉 / UI 层（截图 · OCR · 日志 · 等待）

Unreal 引擎层

诊断层

句柄格式与作用域

句柄形如 il2cpp-g3-classes-1（{引擎}-g{代次}-{种类}-{序号}）。 代次段是正确性要求：句柄表是每个索引实例各自的、序号从 0 重来， 不带代次就会让旧句柄在切游戏后静默读到另一个游戏的结果集（实测过）。 所以切游戏或重建索引后旧句柄一律失效，失败时会返回 available_handles。 见 devtools/verify_handle_scope.py。

响应体积上限（256 KB）

任何工具返回都不会超过 256 KB —— 这不是各工具自觉，而是 src/gamemod_mcp/cap.py 在所有工具外面统一兜底（@_cap_response）。

超限时截断最大的那个顶层列表，并把完整列表登记成句柄：

• 返回里多出 capped: true、cap_bytes，note 写明「只回了前 N 条」；

• has_more 一律改成 true、returned 改成实际条数（不许明明还有却说没有）；

• note 里给出续读方式 read_query_result(handle=..., offset=N)， 一条数据都不会丢 —— 完整列表在句柄里。

• 已有 handle 的返回（search_*）复用它的句柄，不再另造一个； 此时续读的 offset 是「原 offset + 已回条数」，按「已回条数」算会跳过前面的条目。

为什么必须有：契约第 5 条原先只靠各工具的 limit 自觉遵守，但 limit 上限是 2000，Agent 完全可以合法地要 2000 条 —— 实测 search_classes('', limit=2000) 的线上文本是 856 KB。截断后同一调用是 260 KB。 见 devtools/verify_cap.py（机制）与 devtools/verify_response_size.py（体积）。

资源（MCP resources）

只有一个：gamemod://guide —— 这份 MCP 自己的完整使用指南 （与 skills/gamemod-mod/SKILL.md 同源，逐字节相同）。

gamemod://guide   text/markdown   约 24 KB

支持 resources 的客户端可以直接读它，不必先在系统提示里塞进这份长文档。 它也是全项目唯一没有工具出口的内容：其余（会话状态、引擎能力矩阵、 缓存与依赖清单）都已经由 get_session / open_game / get_diagnostics 返回，再开一个资源出口就是同一份数据的第二个来源（契约第 3 条）。

为什么没有 prompts

MCP 还有 prompts 这一面，本服务器不做，这是量过的结论而不是遗漏：

证据：在 E:\DSH\resources\app.asar 里按路径检索 JS， dsh-mcp-client 的请求分发 switch 里只有 resources/* 三个分支， prompts/* 零命中。加了 prompt 也传不到模型面前， 只会是一份没人读的声明 —— 与当初否决 outputSchema 是同一套判断方式 （见 docs/项目梳理与优化建议.md §4.14 附近）。

反过来说：换个客户端就要重新量一次。如果某个客户端确实消费 prompts， 「把 SKILL.md 挂成带 engine 参数的 prompt」是现成的做法。 devtools/verify_mcp_resources.py 已经把「资源清单恰好只有 guide」 做成断言，将来补资源时会强制过一次讨论。

人工调试前端（旁路设施）

给人工调试用：在浏览器里看有哪些工具、怎么调、返回什么， 并留下 AI 客户端到底调了什么的流水，便于回溯。

python devtools\debug_ui.py            # → http://127.0.0.1:8770/
python devtools\debug_ui.py --log-on   # 本次启动就打开调用流水
# 装过包之后也可以：gamemod-mcp-dbg-ui

它不重新实现任何工具：工具清单直接问 FastMCP.list_tools()， 入参表单由每个工具的 inputSchema 生成，调用直接走 FastMCP.call_tool()。 所以页面上看到的参数表、返回体与 AI 客户端拿到的是同一份， 不存在「前端能调通、AI 调不通」这种漂移；ok:false 的真实报错也照样显示。 左侧按 server.py 的八个「工具分层」分组，只读 / 破坏性 / 接触外部世界 直接取 MCP 的语义标注。

调用流水（可开关 / 可查看 / 可清理）

页面第二个页签是调用流水：每次调用记下工具名、参数、返回、ok、错误、 耗时、体积。默认关闭，页面上可以随时开关。

日志点落在服务器分发层，而不是前端里 —— 这一点是刻意的： 前端只能看见「经它发出的调用」，而 AI 客户端会自己拉起一个 MCP 服务器进程，前端根本看不见。记在 ToolManager.call_tool（FastMCP 分发工具的唯一入口）上，人工手调的（source: "ui"）与 AI 调的 （source: "mcp"）才会落进同一份流水，靠 source / pid 区分。 verify_debug_ui.py 用另一个进程的 stdio 客户端把这件事验成了断言。

三条约束都做成了断言：① 绝不影响业务 —— 记不上就不记（磁盘满 / 权限 不足 / 路径是文件），不许让一个本来正常的工具失败；② 不许无界增长 —— 超上限就轮转、只留最近几份，单条记录里的超大参数/返回截断并标 truncated； ③ 默认不占磁盘 —— 开关关着一个字节都不写。

这个前端不影响 MCP 业务：不起 stdio、不占 MCP 端口、不改任何工具实现， 关掉它 MCP 一侧完全不受影响。运行期依赖也没变（只用标准库 http.server，不引入 Flask/FastAPI/Node）；对 server.py 的唯一改动 是一个默认关闭的流水钩子。详见 devtools/verify_debug_ui.py（61 项）。

目录结构

GameModMCP/
├── README.md                    本文件
├── pyproject.toml               打包配置（pip install -e . 可用）
├── requirements.txt             运行依赖（只有 mcp + frida）
├── install.py                   一键安装（**主推**）+ 冒烟测试
├── install.ps1                  同上，但**只能用 pwsh 7**（5.1 读中文会语法报错）
│
├── src/gamemod_mcp/
│   ├── server.py                MCP 服务器（45 个工具）
│   ├── debug_ui.py              人工调试前端（HTTP，旁路设施；见下节）
│   ├── debug_ui.html            该前端的界面（单文件，无外部依赖）
│   ├── debuglog.py              工具调用流水（可开关 / 可查看 / 可清理）
│   ├── logutil.py               日志（只走 stderr，stdout 留给 JSON-RPC）
│   ├── engine/                  静态分析层
│   │   ├── pe.py                纯标准库 PE/COFF 解析器
│   │   ├── discovery.py         进程枚举 / 引擎识别（不再做全机 Steam 扫描）
│   │   ├── il2cpp_meta.py       IL2CPP global-metadata.dat 解析器
│   │   ├── mono_meta.py         ECMA-335 元数据解析器（45 张表）
│   │   ├── ue.py                Unreal 提取器（pak / utoc / 清单 / 脚本对象）
│   │   ├── adapt.py             **引擎适配层**（让索引层不关心引擎差异）
│   │   ├── decompile.py         Mono 反编译薄封装（可选外部依赖 ilspycmd）
│   │   ├── index.py             SQLite 索引 + 结果句柄
│   │   └── state.py             会话状态（发现→索引→运行时的粘合层）
│   └── runtime/                 动态分析层
│       ├── agent.js             Frida 探针（IL2CPP 59 + Mono 56 个 API，双后端）
│       └── session.py           Frida 生命周期管理
│
├── skills/gamemod-mod/SKILL.md  Agent 使用指南
├── mcp-config/                  各客户端的 MCP 配置样例
├── agent_logs/                  子 Agent 委派记录（prompt + 产出）
└── devtools/                    验证脚本（见 devtools/README.md）
    ├── verify_*.py              验收脚本（对真实游戏与地面真值）
    ├── check_encoding.ps1       编码校验（UTF-8 无 BOM）
    ├── archive/                 归档的过程产物（不参与验收）
    │   └── probes/              一次性逆向侦察脚本（格式出问题时重启定位用）
    └── groundtruth/             真值来源（MonoGroundTruth / 官方 dump）

引擎支持程度

两个引擎的运行时配方一致：注入 → runtime_class_info 取偏移 → find_hook_target 取落点 → hook_method + drain_events。 探针里是两套实现（il2cpp_* 59 个 API / mono_* 56 个 API）， 对外工具与 token 对账方式完全相同（静态 token == 运行时 token）。 Mono 上有四条差异，都是如实声明而非「未实现」：

1. 没有 RVA：地址来自 mono_compile_method 触发的 JIT， 代码不在 mono-2.0-*.dll 内，所以 in_module: false 且不给 rva； 元数据里的 RVA 指向 IL 字节码，不能拿来 Hook。

2. gc_control 不支持：没有 mono_gc_disable / mono_gc_enable 导出（四个 Mono 样本一致核实），调用会明确返回 ok:false。

3. 程序集懒加载：刚注入时只枚举到十来个程序集，UnityEngine.* 要过几秒才出现（实测 13 → 164）。注入成功后探针会等它加载稳定再返回 （判据是数量连续 4 次采样不变，实测等了 4.0 秒、看到 144 个）， 结果放在 init.assemblies 里；返回里的 searched_images 也会如实给出当前数量，若仍未稳定可稍后重试。 为什么必须等（不是保险起见）：矩阵实测 Archon Soul 在只有 13 个程序集时 被 Hook 并强制调用 get_frameCount，进程随后消失 —— 「注入成功」与「可以 Hook 托管方法」在 Mono 上不是同一件事。

4. 静态索引的范围：Mono 的静态索引默认只收游戏自己的程序集 （Assembly-CSharp.dll），UnityEngine.* 这类框架类型静态查不到。 class_detail 会明确说明这一点并指向 runtime_class_info， 而不是只回一句「用 search_classes 搜短名」（那条路走不通，它压根没被索引）。

实测数据（真实游戏，非构造样本）：

• IL2CPP（Garden of Witches，17 MB 元数据）： 20,072 类型 / 139,501 方法 / 81,872 字段 / 94 映像。 字段类型解析率 90.10%，与地面真值 dump 比对 27,264 条 0 错（100% 精度）。 建索引 2.6s，缓存复用 1.3s。

• Mono（Archon Soul，Assembly-CSharp.dll）： 1,387 类型 / 6,611 方法 / 6,343 字段。 与 Microsoft 官方 System.Reflection.Metadata 交叉验证 45 张表 0 差异， 每类型的全名/基类/字段名/方法名 0 差异，签名解析 100%。 运行时（Frida 注入同一游戏，实测）： mono_* 导出绑定 56 个、零缺失（四个样本的 PE 导出表逐个核实）； 程序集清单随游戏运行从 13 涨到 164（Mono 是懒加载，跨调用缓存会永久漏掉 UnityEngine.*）；UnityEngine.Time 的 token 0x020002e4 与静态元数据 完全一致（Time.get_frameCount 0x06002468 亦然，独立复现了 System.Reflection.Metadata 真值）；短名解析在 27,222 行类型定义里 0.1s 完成；Hook 上 get_frameCount 后捕获到真实返回值（游戏运行 14.5s 时 retval=872，与 60fps 自洽）。方法地址是 JIT 机器码，in_module=false， 因此没有 RVA（不给假数据）；gc_control 如实报不支持。 另一个实测到的坑：游戏跑约 90 秒后，同一个程序集会被加载出两个映像， UnityEngine.Time 于是被枚举出两条行号/token/命名空间/程序集名全同、 只有 klass 指针不同的记录 —— 不按（程序集名 + 命名空间 + 短名）去重的话， 一次本可解析的查询会变成「命中 2 个同名类」，而调用方无法消解 （两条的 image / namespace / full_name 一模一样）。顺带一提， 内存加载的程序集 mono_image_get_filename 返回的是 data-00000219A9D5A040 这种合成名，不是路径，按路径去重不会命中。 第四个样本 Gambonanza 上复现并修掉了「注入太早就 Hook」这个缺陷： 修复前注入后 4 秒时只有 15 个程序集，Transform / Time 一律「没找到类」； 修复后注入即等到 144 个程序集稳定（4.0 秒），UnityEngine.Transform、 UnityEngine.Time、UnityEngine.GameObject 全部解析成功， find_hook_target 给出候选，10 秒后进程仍在。

• Unreal（CatapultHero + Dinoblade 两个样本）： .pak v11/v12 索引与 .utoc v8 目录索引完整解析， 与打包清单交叉校验 4,556/4,556、4,565/4,565、7,178/7,178、18,956/18,956 全部 100% 命中； 含 UTF-16 中文路径（字库、精灵片、角色）正确解码。 FName 池、属性偏移、.usmap 未实现——静态样本中不可得，诊断里如实标注。

可信度：怎么证明它是对的

这个项目不靠「看起来能跑」。devtools/ 下有 52 个可复现的验证脚本， 每个都对着真实游戏和地面真值跑（其中 43 个进自动套件， verify_tool_coverage.py 是静态导航图、不是门禁，故不参加）：

上表与 devtools/verify_*.py 的一致性由 verify_tool_inventory.py 校验， 所以它不会像以前那样悄悄腐坏（本节曾写「10 个脚本」而实际已有 20 多个）。

几个关键的「硬证据」：

• 静态 token == 运行时 token（50/50、17/17、9/9 全中） → 证明确实挂到了目标方法，而不是同名重载。

• PresetLoaderV2.userDataPresetFile 运行时偏移 = 0x20， 与地面真值 dump 里的 /*0x20*/ 一致 → 证明字段偏移是真的。

• 运行时映像数 94 == 静态映像数 94 → 证明探针挂到的是同一个游戏实例。

• 字段类型 27,264 条与 dump 比对 0 错 → 证明 derived 那一档没有蒙错。

跑法（一条命令跑全部，自带垫片、开跑前清空旧日志、结束时卡覆盖率门禁）：

python devtools\run_all_verify.py

只跑一两个排查时用 --only（注意此时会跳过覆盖率门禁，因为子集不可能覆盖全部工具）：

python devtools\run_all_verify.py --only verify_lazy_handles

改纯函数/解析逻辑时用 --fast（离线快检，不拉起任何游戏，约 3 分钟）：

python devtools\run_all_verify.py --fast

--fast 跳过的是「真的会调用 launch_game / inject_process / spawn_and_attach / ensure_runtime」的脚本，清单由 AST 从源码推导 （不是手写名单 —— 手写清单必然漂移，正是本仓库反复吃亏的地方）。 它同时跳过动态覆盖率门禁（覆盖率要求整套跑完才有意义）， 并在结尾如实列出跳过了哪些。 --fast 全绿 ≠ 全量通过：提交完整改动前请跑不带 --fast 的那条。

verify_mcp_tools.py 会真的启动一个游戏并在结束时结束它。 它需要 Frida 与一个 IL2CPP 样本（如 Garden of Witches）。 不需要管理员权限 —— 实测普通用户权限即可（见下方「权限」一节）。 样本不存在的脚本会记为「无法验证」并跳过 —— 跳过不算通过。

多游戏矩阵：能力边界不靠单一样本推断

单一样本只能证明「在某个游戏上能用」。devtools/ 下有两个跑遍全部样本 的报告脚本（只出报告、不改代码，退出码恒为 0）：

python devtools\report_multi_game_matrix.py   # 静态：样本 × 工具的候选分类
python devtools\report_runtime_matrix.py      # 运行时：真的启动/注入/Hook，逐工具判定

report_runtime_matrix.py 会真的启动每个游戏、注入探针、装 Hook、 强制调用并读回参数与返回值，最后按「游戏 × 45 个工具」输出 ok / 不适用 / 失败 三态（--json 落盘 + --md 出报告）。 最近一次全量结果见 docs/多游戏运行时兼容性报告.md。

它对「正确拒绝」与「工具坏了」分得很清：decompile 在 IL2CPP 上返回 「不是 .NET 程序集」、短名有歧义时返回 ambiguous + 候选，都算 不适用 / 正确拒绝，不算失败 —— 否则报告会把设计行为统计成缺陷。

验收套件没全绿？先看失败清单

python devtools\run_all_verify.py 的汇总行只打印失败脚本的名字， 看不出「环境缺样本」还是「代码真坏了」——这两类必须分开处理。 逐项的现象 / 根因 / 修复路径 / 验证方法见 docs/验收失败清单.md。

该文件是滚动更新的：修掉一项就划掉一项。当前快照（2026-10-02）为 通过 33 / 40，7 项失败中 1 项是产品缺陷、2 项是脚本用了 Python 3.12 语法、4 项是缺样本。

设计取舍

为什么不做 MCP 的进度、取消与 tasks

这三样都是协议里有、但这个客户端不消费的东西，量过之后才决定不做：

订正（旧文案已过时）：本表曾写「FastMCP 对同步工具是内联调用、 事件循环被占满，连取消通知都读不到」，并据此说「60 秒的 launch_game 期间 服务器什么都干不了」。这两句现在都不成立：server.py 的 _install_event_loop_guard() 早已把经 MCP 分发的同步工具 offload 到线程池 （ToolManager.call_tool → asyncio.to_thread），并实测慢调用在飞时 get_session 10/10 次秒回（见《重启验证报告-第二轮》§4 与 devtools/verify_report_fixes.py）。 「不做取消」的结论不变，但理由换成了上面那条：结构上够不着 ——同步工具体拿不到 context，没有取消的承接方。

这三条依据由 devtools/verify_mcp_context.py 钉住：变了就报红， 提醒重读判断，而不是让断言变绿。

为什么引擎解析器全部手写，不用现成库

pefile / lief 更省事，但会带来三个问题：依赖体积、版本漂移、 以及遇到魔改文件时无从下手。自己写 PE 解析不到 400 行， IL2CPP 元数据解析 1,000 行——换来的是零依赖和完全可控的错误信息。

为什么要有 adapt.py 这一层

IL2CPP 和 Mono 是两个根本不同的元数据体系：

• IL2CPP：字段/方法各自的索引轨道相互独立，字段的 typeIndex 甚至不在自己的索引空间里，得靠「比它小的最大 byval 键」推算（~90% 可解）。

• Mono：标准 ECMA-335，类型都编码在 #Blob 签名里，能精确解出 完整类型名（数组、泛型、指针都对）。

但两者在「类型/字段/方法的归属关系」上是同构的。把类型引用的 表示差异收进 adapt.py，索引层就能共用一套代码——这也是 verify_adapt.py 存在的意义：证明同一套 API 两边都跑得通。

为什么宁可返回 ok: false 也不猜

工具返回必定带 ok 字段。索引层用 found=False 表示「查了但没有」， 服务器层会把它转成明确的 ok: false + error。

原因很直接：假成功是最危险的一类错误。如果「类不存在」返回 ok: true + 空列表，Agent 会以为类存在但没有字段，然后基于这个 错误结论继续往下走。宁可报错。

同理，IL2CPP v31 的字段记录里没有 flags 槽，所以 field_is_static 返回 None 而不是猜一个 False—— 猜出来的 False 会让 Agent 以为它验证过。

索引缓存怎么管（会一直长大的那个目录）

缓存文件名是 <引擎>-<元数据 sha256 前 16 位>.sqlite。这个键选得对 （换游戏、换版本必定重建，不会串数据），但它有个没人管过的副作用：

「玩过多少游戏」+「游戏更新过多少次」，都会永久堆在 ~/.gamemod/cache 里。实测一个 IL2CPP 游戏的索引 25.7 MB， 而 Mod 开发本来就要反复更新游戏 —— 每次更新换一个新文件， 旧文件再也不可能被命中。

以前这件事在任何工具返回里都看不见（get_diagnostics 只报一个路径字符串）。 现在：

清理有三条护栏，而且只删文件名形状正确的（<引擎>-<16 位十六进制>.sqlite）： 缓存目录里可能有你自己的东西，删文件不可逆，所以宁可漏删不可错删。 按上面的边界，5 个游戏的 ~130 MB 永远不会被碰。

想立刻腾空间就直接删 ~/.gamemod/cache 里的东西 —— 它只是可重建的派生数据， 代价是下次打开那个游戏重新解析（IL2CPP 约 2.6 秒，巨型样本约 12 秒）。 这条策略的验收在 devtools/verify_cache.py（含「把正则放宽就会误删」的反证）。

那「第一次查询」为什么还要等 400 毫秒

缓存命中确实不解析元数据（IL2CPP 528 → 19.6 ms），但紧接着的第一次查询 会把它逼出来：索引里存的是「有哪些类型」，而基类名、字段类型、方法返回类型 这些可读名字是查询时由解析器算的。实测 8 个查询里 7 个会逼出来 （只有 index_info 不用），IL2CPP 约 440 ms，在 5 查询的一次会话里占 65~78%。

把这些名字也存进 SQLite（路线图里的 P1-3b）能省掉这 440 ms。 已经量过，结论是不做，理由三条：

1. 半量修复等于零。search_classes 需要解析器只因 parent 一个字段， 但「只存 parent_name」省不下任何东西 —— 紧接着的 class_detail 仍要解析。 解析是全有或全无，所以「parent_name/field_type 入库」这种按列拆的 写法本身就误导：这两列不能分别计价。

2. 完整修复要动分层。要让 7 个查询都不解析，得把 class_detail / class_hierarchy / analyze_dependency 等 10 个查询层函数改成完全由 SQLite 驱动 —— 那等于在索引层再实现一遍继承语义，而 AGENTS.md §3 要求引擎差异只出现在 adapt.py。两份继承语义互相漂移，正是本项目反复 吃亏的那类错误。

3. 省下的是「每次 open_game 一次」的 440 ms，不是每题 440 ms。

理由与数字钉在 devtools/verify_lazy_meta.py（既是回归门禁，也是这个决策的 门禁）：哪天那张「哪些查询需要解析器」的表空了，它会提醒回来订正结论。

顺带，这个脚本还捞到并钉住了一个真缺陷：元数据载入失败曾被 except Exception 降级成「这些类没有基类」（ok: true + 200 行 parent: null）。 现在载入失败会如实报 ok: false + 原因，验收就是那段「把旧写法搬回来」的反证。

已知限制

• IL2CPP 字段类型约 10% 解不出。这是元数据格式本身的限制 （复合类型只给到元素类型），不是 bug。工具会标记 type_confidence: unknown，需要时用运行时内存读取确认。

• 反调试游戏注入会失败。带 EAC/BattlEye 的网游基本注入不了， 这是预期的，不要反复重试。

• Unreal 支持受限。UE 没有像 IL2CPP 那样集中的元数据文件， 结构信息依赖 UE profile / .usmap。能力以 get_diagnostics() 报告为准。

• Windows 注入不需要管理员权限（实测订正）。 只要 Agent 与游戏的完整性级别相同即可 —— 普通权限的 python 注入普通权限的 IL2CPP 游戏实测成功。唯一的例外是 游戏以管理员身份运行（完整性级别 High），此时才需要同样提权； 反之游戏是普通权限、Agent 是管理员，通常也能注入。

  这条曾经写错成「通常需要管理员权限」，来源是失败提示里的一句 猜测性归因。实测证据：本进程与游戏进程的完整性级别都是 Medium，attach → runtime_info → find_instances 全部成功。

• Headless 环境验证不到自然调用。没有显示/GPU 的机器上游戏不渲染帧， 每帧方法不会自己触发。Hook 有效性通过从注入侧主动调用来证明。

环境要求

• Windows（本项目只支持 Windows）

• Python ≥ 3.10（实测 3.13.1）

• mcp ≥ 1.0, < 2、frida ≥ 16（实测 frida 17.17.0）

⚠️ mcp 必须 < 2：本代码用 1.x 的 mcp.server.fastmcp.FastMCP， 2.x 已改名成 MCPServer（mcp.server.mcpserver）。只写 >=1.0.0 会让全新环境装到 2.x 然后服务器起不来 —— 这是打包分享包时实测到的。

可选弱视觉（截图 / OCR）：dxcam|mss + rapidocr-onnxruntime|pytesseract

• numpy/opencv-python/pillow/pywin32。不装不影响其它工具， get_diagnostics() 的 screen 段会如实报告可用性。

分享包（给别人测试用）

一条命令生成一个自带依赖、开箱即用的分享包：

python devtools\build_share.py            # 打包（会下载 wheel）
python devtools\build_share.py --no-wheels  # 只打源码（体积小）
python devtools\build_share.py --check      # 只校验已有分享包

产物落在仓库同级 ..\GameModMCP-share\（不进 git），并自动打 zip。 形态：

GameModMCP-share/
├── 安装说明.md      ← 给 AI 读的入口（**整个目录直接交给对方的 Agent**）
├── install.py       ← 一键安装（主推）
├── src/ skills/ mcp-config/ devtools/ docs/
└── wheels/required|optional   ← 依赖 wheel（离线可装，必需约 63 MB）

打包后自检 44 项，其中最关键的一条是用包内源码真起一次服务器 数工具数 —— 它能抓到「拷漏了文件」「依赖装错版本」这类只有对方才会踩到的 问题（实测就是靠它发现 mcp>=1.0.0 会装到 2.x 导致起不来）。 另有 6 项专门盯许可：LICENSE 在不在、是不是完整的 MIT 文本、有没有版权行， 以及 README 与 pyproject.toml 是否和它说同一件事 —— 因为分享包会分发 src/，而 COPY_FILES 里文件名写错时是静默跳过的，包照样打得出来、 照样能装，只是没有许可。

为什么入口是 Python 而不是 .ps1：Windows 自带的 PowerShell 5.1 读无 BOM 的 UTF-8 中文脚本会按 GBK 解码、直接语法报错，而 pwsh 对方不一定装了。对方装了 Python 才能跑 MCP，所以 Python 一定在。

许可

MIT © 2026 liwenhao0427

可自由使用、修改、再分发（含商用），只需保留版权与许可声明。 完整授权文本见 LICENSE —— 它与 pyproject.toml 的 license 字段是同一份许可，改动时必须同步。

为什么之前只有这一行字、没有文件：README 与 pyproject.toml 都声明了 MIT，但根目录一直没有 LICENSE，GitHub 因此把本仓库识别成 license: null —— 「声明了许可却没有授权文本」。分享包会分发 src/，所以许可文本必须 随源码一起走（见 devtools/build_share.py 的 COPY_FILES）。