Shadow CE — AI操作手册

项目概览

ARM64 Android内核级内存扫描器 + debugger，类似Windows Cheat Engine。

• 内核模块 shadow_ce.ko — 通过页表walk读写任意进程内存，零ptrace
• 用户态server ce_server — TCP server，CE协议兼容
• Python客户端 — PyQt6 UI + MCP server（AI可直接调用）
• HW断点 — 用户态perf_event_open，不用内核模块，零ptrace痕迹

Build & Flash（必须遵循）

编译server（纯C，静态链接）

cd /root/shadow_ce/server
aarch64-linux-gnu-gcc -O2 -static -o server server.c -lpthread

编译ko（需要对应内核源码树）

# Ace 5 Pro (SM8750, 6.6.89)
KDIR=/root/oneplus_ace5pro_kernel/oneplus_ace5pro_kernel_build/kernel_workspace/kernel_platform/common
export PATH="/root/aosp-clang-r510928/bin:/usr/bin:/bin"
make -C $KDIR O=$KDIR/out M=/root/shadow_ce/server ARCH=arm64 LLVM=1 CC=clang LD=ld.lld CROSS_COMPILE=aarch64-linux-gnu- modules

推送 & 启动

adb.exe push server /data/local/tmp/ce_server
adb.exe push shadow_ce.ko /data/local/tmp/shadow_ce.ko
adb.exe shell "su -c 'chmod 755 /data/local/tmp/ce_server; insmod /data/local/tmp/shadow_ce.ko; nohup /data/local/tmp/ce_server -p 16900 > /dev/null 2>&1 &'"
adb.exe forward tcp:16900 tcp:16900

运行客户端

# WSL2:
GALLIUM_DRIVER=d3d12 python3 /root/shadow_ce/client/shadow_ce.py
# Windows原生:
python client/shadow_ce.py

关键规则（血泪教训）

绝对不能做的事

• 不要在agent里改代码 — agent改了文件可能和其他agent冲突，只让agent做研究
• 不要用insmod -f加载vermagic不匹配的ko — 会kernel panic重启
• 不要在perf_event_create_kernel_counter的自定义overflow handler里做Execute BP — 框架不帮你做单步恢复，会无限循环panic
• 不要在ce_client的方法里忘记with self._lock — write_memory曾经没加锁，导致TCP流破坏，Memory View全零20秒
• 不要在PyQt signal里传64位地址用pyqtSignal(int) — int在PyQt是32位，会溢出。用pyqtSignal(object)
• 不要在connect.py的run()方法内部import os — 会shadow全局的os，Windows上UnboundLocalError

架构决策（已验证，不要改）

• 4条独立TCP连接：scan / refresh / freeze / hwbp，互不干扰
• HW断点用perf_event_open（用户态），不用内核模块 — 师傅的方案已验证，框架自动做单步恢复
• Execute BP不能用内核态自定义overflow handler — uses_default_overflow_handler()返回FALSE时框架不做单步，CPU返回同一PC无限触发
• scan的SCAN_EXACT不能fallback到float_near — 会导致所有接近零的地址匹配任何小整数（ULP 256容差）

已知陷阱

• WSL2用llvmpipe软渲染 — 设GALLIUM_DRIVER=d3d12启用GPU，否则UI巨卡
• fontconfig out of memory — 删/etc/fonts/local.conf，重装fontconfig
• 游戏重启后PID变了 — Memory View的_own_client还连着旧PID，必须关掉重开
• _refreshing卡True — _reader_loop的TCP读阻塞时所有timer refresh被跳过，显示全零直到超时
• cache.refresh()读512KB持锁太久 — _own_client._lock被持有15-25秒，其他read全阻塞
• ART GC移动对象 — 内核扫描捕获瞬态值（扫到时匹配，读时已被GC清零），不是代码bug

文件结构

shadow_ce/
├── client/
│   ├── shadow_ce.py      # 入口
│   ├── main_window.py    # 主窗口（scan/rescan/address list）
│   ├── connect.py        # 连接向导（adb forward + server启动 + 选进程）
│   ├── ce_client.py      # CE协议TCP客户端（所有内存R/W通过这里）
│   ├── scanner.py        # 扫描结果管理
│   ├── memory_view.py    # Memory View窗口（disasm + hex + inspector）
│   ├── disasm_view.py    # ARM64反汇编视图（capstone）
│   ├── hex_view.py       # 十六进制视图
│   ├── mem_cache.py      # 页级内存缓存（4KB页，LRU 128页）
│   ├── hwbp_window.py    # HW断点结果窗口（Found Code）
│   ├── add_address_dialog.py  # 手动添加地址对话框
│   ├── settings.py       # 设置对话框
│   ├── style.py          # 全局暗色主题 + Memory View配色
│   └── mcp_server.py     # MCP server（18个AI工具）
├── server/
│   ├── server.c          # TCP server（CE协议 + hwbp CMD）
│   ├── shadow_ce.c       # 内核模块（页表walk + 内存读写 + 扫描）
│   ├── shadow_ce.h       # ioctl定义
│   ├── hwbp.h            # HW断点（perf_event_open，用户态）
│   ├── patch_vermagic.py # 自动patch ko的vermagic匹配设备内核
│   ├── Makefile          # ko编译
│   └── shadow_ce.ko      # 编译好的内核模块
└── CLAUDE.md             # 本文件

CE协议CMD编号

MCP工具（client/mcp_server.py）

AI可直接调用：ping → connect_process → read_memory / scan_all / set_data_breakpoint 等18个工具。 配置在~/.mcp.json：

{
  "mcpServers": {
    "shadow-ce": {
      "command": "python3",
      "args": ["/root/shadow_ce/client/mcp_server.py"]
    }
  }
}

调试经验

Memory View全零

1. 检查游戏是否重启（PID变了）→ 关掉Memory View重开
2. 检查_own_client连接是否断了 → _safe_read会自动重连
3. 检查_refreshing是否卡True → socket超时30秒后自动恢复

scan结果全是误报

• val_match的SCAN_EXACT之前有float_near fallback → 已修，现在纯整数比较
• ART GC瞬态值 → first scan后立刻rescan过滤

HW断点panic

• Execute BP用perf_event_open用户态方案（师傅验证过的）
• 不要用内核态perf_event_create_kernel_counter的自定义handler
• Watchpoint（R/W/RW）不会panic — 数据访问后PC自然推进

UI卡顿

• Windows原生运行最流畅（Direct2D硬件加速）
• WSL2必须设GALLIUM_DRIVER=d3d12
• data()里不做任何计算 — 全部预缓存到_static_cache
• refresh在后台线程 — 主线程零TCP阻塞