inspector

注入到任意 64 位 Windows 进程的通用运行时调试工具。DLL 在目标进程内启动一个 TCP 服务（绑定 0.0.0.0:37651，同机或远端均可连），通过一个 tab-separated line 协议对外暴露 Cheat Engine 风格的调试能力；MCP 桥则把这些能力转成 50 个 Claude tools。

---

1. 概述

设计原则：

• 零项目耦合：DLL / MCP 都不依赖任何特定游戏结构。
• 有状态：扫描会话、snapshot、watcher、structure 定义在 DLL 里常驻，MCP 调用不会在中途重建。
• 协议极简：每次请求一行 tab 分隔的文本，响应一个 JSON envelope {ok, command, text}。

---

2. 目录结构

inspector/
├── README.md                      # 本文
├── dll/
│   ├── CMakeLists.txt
│   ├── toolchain-mingw-w64.cmake
│   ├── include/inspector/
│   │   ├── types.hpp              # u8..f64 基础类型
│   │   ├── formatting.hpp         # 解析 / hex / JSON 小工具
│   │   ├── memory_view.hpp        # SEH 保护的本地内存读
│   │   ├── service_util.hpp       # 区域枚举 / PE 解析
│   │   ├── service.hpp            # Service 公共 API
│   │   └── server.hpp
│   ├── src/
│   │   ├── dllmain.cpp / server.cpp
│   │   ├── service.cpp            # 分发 + watcher 线程
│   │   ├── service_memory.cpp     # 内存读写 / patch / hexview / pointer_chain
│   │   ├── service_scan.cpp       # 所有 scan_* / find_code_refs / pointer_path
│   │   ├── service_snapshot.cpp   # snapshot_*
│   │   ├── service_watch.cpp      # watch_* + event 队列
│   │   ├── service_dissect.cpp    # dissect / compare / compare_many / infer
│   │   ├── service_struct.cpp     # CE structure 会话
│   │   ├── service_module.cpp     # modules / module_info / resolve_symbol
│   │   ├── service_disasm.cpp     # Zydis 反汇编
│   │   └── service_thread.cpp     # thread_list / thread_context
│   └── thirdparty/zydis/
└── mcp/
    └── server.py

---

3. 编译

依赖：MinGW-w64（brew install mingw-w64）+ CMake ≥ 3.24。

cd inspector/dll
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain-mingw-w64.cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
# 产物: build/inspector.dll  (约 15 MB，静态链接 Zydis/Zycore/libstdc++)

在 Windows 本地直接用 MSVC 也可以；CMakeLists 在 MSVC 下会启用 /W4 /permissive- /utf-8。

---

4. 注入与启动

1. 把 inspector.dll 注入目标进程（手动注入器 / DLL injector / LoadLibrary 均可）。

2. DllMain → DLL_PROCESS_ATTACH 会：

   • 调 AllocConsole() 拉一个控制台窗口用于日志；
   • 绑定 0.0.0.0:37651 + 启动 accept 线程；
   • 启动 20 Hz 的 watcher 轮询线程。

3. 控制台里看到：

   inspector (generic memory / CE-style debug)
   pid         = ...
   host module = 0x00007FF7...
   wire port   = 0.0.0.0:37651
   [inspector] server started
   

   就可以从 MCP 端发命令了。

4. 卸载时 DLL_PROCESS_DETACH 会停 accept 线程 + watcher 线程并释放 socket。

远程联通：DLL 是 bind(INADDR_ANY, 37651)，如果 MCP 和游戏不在同一台机器，把 端口穿透出来（或走 SSH 转发 / 内网直连）即可。这是开发工具，别暴露给非可信网络。

---

5. MCP 配置

5.1 本仓库已写好的 .mcp.json

{
  "mcpServers": {
    "inspector": {
      "command": "python3",
      "args": [
        "/绝对路径/inspector/mcp/server.py"
      ],
      "env": {
        "INSPECTOR_HOST": "127.0.0.1",
        "INSPECTOR_PORT": "37651"
      }
    }
  }
}

• 名称 inspector 决定了 Claude 里看到的工具前缀： mcp__inspector__inspector_process_info 等。
• INSPECTOR_HOST / INSPECTOR_PORT 可选；默认 127.0.0.1:37651。
• 远程机器把 INSPECTOR_HOST 改成游戏机的 IP 即可。

5.2 Claude Code

• 项目级配置：直接把 .mcp.json 放到仓库根目录（本仓已经有了）。
• 用户级配置：放 ~/.claude/mcp.json，内容同上。
• 首次注册需要重启一次 Claude，让工具 schema 被加载进 tool list。

5.3 Cursor / 其它 MCP 客户端

同样的 JSON 片段塞进该客户端的 MCP 注册文件（具体路径参考各客户端文档）。

5.4 验证

不开游戏也可以先烟雾测试 MCP 桥本身：

printf '{"jsonrpc":"2.0","id":1,"method":"initialize"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' \
  | python3 inspector/mcp/server.py

应该看到 serverInfo 与 50 条工具列表。

---

6. 协议

• 端口：37651/TCP。
• 请求：一行 \t 分隔的文本，以 \n 结束。 示例：read\t0x7FF712345000\t256\thex\n
• 响应：{"ok":bool,"command":str,"text":str} 后跟 \n。
  • ok=false 时 text 是错误原因（如 "bad args"、"read failed"）。
  • text 里直接是人类可读的报告，MCP 会原样透传给 Claude。
• 每个连接只处理一次请求-响应就关闭，便于客户端做超时。

---

7. 工具全表

工具名都带 inspector_ 前缀。分组列出：

7.1 进程 / 模块

7.2 内存原语

7.3 内存视图（CE MemoryView 等价）

示例：

inspector_hexview  address=0x7FF712340000  size=64  cell_type=f32  row_width=16

7.4 扫描（CE first/next 流）

7.5 逆向辅助

7.6 结构 Dissect（ReClass 风格）

7.7 Snapshot

7.8 Watcher（长轮询）

7.9 CE Structure 会话

CE 的 Dissect Data/Structures 功能的线协议版本。字段类型完全对齐 CE 的 TVariableType：

典型流程：

struct_define name=Player default_hex=false
struct_add_field name=Player offset=0x10 kind=pointer field_name=pActor
struct_add_field name=Player offset=0x40 kind=single field_name=hp
struct_add_field name=Player offset=0x44 kind=single field_name=hpMax
struct_apply name=Player addresses=0x1B6160F9BD8,0x1B6B0DB4B48 depth=1
struct_save_xml

7.10 反汇编

7.11 线程

---

8. 典型流程

8.1 找一个浮点血量

scan_value  type=f32 op=between value1=99.0 value2=101.0
# 让游戏里角色掉血到 50
scan_next   op=decreased
scan_next   op=between value1=49.0 value2=51.0
scan_peek   offset=0 count=32

8.2 patch 一段代码

scan_aob_in_module module= pattern="E8 ? ? ? ? 48 8B 5C 24 ? 48 83 C4 20"
# 记录命中地址 A
disasm      address=A count=4
patch       address=A hex_bytes="90 90 90 90 90"
disasm      address=A count=4         # 确认 NOP 生效

8.3 监控坐标抖动

watch_add   name=pos   address=0x...1F0  type=vec3 eps=0.01
watch_events since_seq=0 max_wait_ms=2000 max_events=32

8.4 结构对齐 + 导出给 CE

struct_define name=Hero default_hex=1
struct_guess  name=Hero base=0x1B6...  size=0x200 overwrite=1
struct_apply  name=Hero addresses=0x1B6...,0x1B7...  depth=2
struct_save_xml     # 把返回的 XML 粘到 CE Load structure

---

9. 限制 / 注意事项

• 只调试 64 位。Zydis 的模式固定在 LONG_64；thread_context 只打印 x64 寄存器。
• 全局扫描会读大段已提交页，几秒到几十秒都可能；MCP 桥把单次请求超时设为 300 s。
• DLL 被注入的进程退出后会卡住 accept 线程的阻塞 recv — 正常卸载 DLL（FreeLibrary / 进程退出）会触发 DLL_PROCESS_DETACH，stop 干净。
• patch/nop 会自动 FlushInstructionCache，但不会 hook 反作弊信号；别往有完整性校验的段写东西。
• 结构定义只在 DLL 进程内内存；宿主进程一关就丢。需要持久化请用 struct_save_xml 落盘。

---

10. 版本

• inspector.dll：1.0.0
• MCP serverInfo：inspector-mcp / 1.0.0
• Zydis：v4.1.0（vendored）
• 依赖的 CE 语义参照：上游 cheat-engine/cheat-engine（仅参考，不构建）