@bingine/cemem 0.0.0-stage → 0.1.1

package/docs/backend-dbk.md

@@ -0,0 +1,305 @@
+# DBK 内核驱动后端
+
+让 `node-cheat-engine` 通过 Cheat Engine 自己的 **DBK 内核驱动**读写受保护进程内存。
+
+## 一、为什么需要它
+
+| 后端 | 走什么 | 受保护进程（PPL/反作弊/高权限） |
+| --- | --- | --- |
+| `SelfBackend`（默认） | 用户态 `OpenProcess` + `ReadProcessMemory` | ❌ 读不到 |
+| `NativeCeBackend` | 连 `ceserver` 的 TCP 协议 | ✅（如果那个 ceserver 提权/带驱动） |
+| **`DbkBackend`（本文）** | **DBK 驱动的 `DeviceIoControl`** | ✅ |
+
+受保护进程连句柄都打不开，用户态无解 —— 唯一办法是让**内核**代劳。
+
+## 二、协议（逐行核对 CE 源码，不是猜的）
+
+### 2.1 ioctl 码
+
+来源：`Cheat Engine/dbk32/DBK32functions.pas` 第 22–93 行。
+
+```pascal
+const FILE_READ_ACCESS  = $0001;
+const FILE_WRITE_ACCESS = $0002;
+const FILE_RW_ACCESS    = FILE_READ_ACCESS or FILE_WRITE_ACCESS;   // = 3
+const METHOD_BUFFERED   = 0;
+const FILE_DEVICE_UNKNOWN = $00000022;
+const IOCTL_UNKNOWN_BASE  = FILE_DEVICE_UNKNOWN;
+
+IOCTL_CE_READMEMORY  = (IOCTL_UNKNOWN_BASE shl 16) or ($0800 shl 2) or METHOD_BUFFERED or (FILE_RW_ACCESS shl 14);
+IOCTL_CE_WRITEMEMORY = (IOCTL_UNKNOWN_BASE shl 16) or ($0801 shl 2) or ...
+```
+
+代入 READMEMORY：
+
+```
+(0x22 << 16) | (0x0800 << 2) | 0 | (3 << 14)
+= 0x220000 | 0x2000 | 0 | 0xC000
+= 0x220000 | 0x2000 = 0x222000
+= 0x222000 | 0xC000  = 0x22E000
+```
+
+> ⚠️ **这一步很容易算错**。我在这上面错了两次：先后误以为结果是 `0x22C000`。
+> 原因是 `0x22 << 16` 会占用 bit 17/21，与 `0x0800 << 2` 的 bit 13 **在同一数值区间叠加**，
+> 不能凭"整齐的十六进制"直觉去拼。**必须逐项 OR 累加。**
+> 真机上 ioctl 码错了只表现为"驱动返回无效请求"，几乎无法从现象反推原因 ——
+> 所以测试里把具体数值写死了。
+
+本后端用到的码（都由上面的公式算出）：
+
+| 名称 | 功能号 | ioctl 码 |
+| --- | --- | --- |
+| `READ_MEMORY` | `$0800` | `0x22E000` |
+| `WRITE_MEMORY` | `$0801` | `0x22E004` |
+| `OPEN_PROCESS` | `$0802` | `0x22E008` |
+| `QUERY_VIRTUAL_MEMORY` | `$0803` | `0x22E00C` |
+| `GET_VERSION` | `$0816` | `0x22E058` |
+| `MAKE_WRITABLE` | `$0819` | `0x22E064` |
+| `ALLOCATE_MEM` | `$081F` | `0x22E07C` |
+| `SUSPEND_PROCESS` / `RESUME_PROCESS` | `$0824` / `$0825` | `0x22E090` / `0x22E094` |
+
+### 2.2 读内存
+
+来源：`ReadProcessMemory64_Internal`，第 1523–1584 行。
+
+```pascal
+type TInputstruct = packed record     // ← packed：无对齐填充
+  processid: uint64;
+  startaddress: uint64;
+  bytestoread: word;
+end;
+...
+deviceiocontrol(hdevice, cc, @input, sizeof(input), pointer(bufpointer), toread, br, nil)
+```
+
+- 输入是 **18 字节**（8+8+2）。若按自然对齐会变成 24 字节，驱动读到的偏移就全错。
+- 输出直接写到调用方缓冲区。
+- CE 按 4096 字节分块，且**不跨页**：
+
+  ```pascal
+  if (mempointer and $fff) > 0 then
+    toread := 4096 - (mempointer and $fff)
+  else
+    toread := 4096;
+  ```
+
+### 2.3 写内存
+
+来源：第 1620–1686 行。
+
+```pascal
+input: TInputstruct absolute ao[0];        // 512 字节固定缓冲
+zeromemory(@ao[0], 512);
+input.bytestowrite := towrite;
+input.startaddress := mempointer;
+copymemory(@ao[sizeof(tinputstruct)], bufpointer2, towrite);   // 数据紧跟头部
+deviceiocontrol(hdevice, cc, @ao[0], 512, @ao[0], 512, br, nil);  // ← in/out 同一块
+```
+
+- 缓冲固定 **512 字节**，单次最多 `512 - 18 = 494` 字节。
+- **in 与 out 传同一块缓冲** —— 这是 `METHOD_BUFFERED` 允许的，也是 CE 的做法。
+
+### 2.4 设备名
+
+来源：第 3194 行与第 3436 行。
+
+```pascal
+servicename := 'CEDRIVER73';               // 出厂默认（第 3194 行）
+...
+hDevice := CreateFileW(pwidechar('\\.\'+servicename), GENERIC_READ or GENERIC_WRITE,
+                       FILE_SHARE_READ or FILE_SHARE_WRITE, ...);
+```
+
+但 `servicename` 可以被 CE 目录下的 `driver.dat` / `driver64.dat` **覆盖**
+（第 3217–3225 行按行读入，第 1 行就是服务名）—— CE 安装时会把服务名**随机化**来降低被检测的概率。
+
+因此本后端按以下顺序解析设备路径：
+
+1. 显式配置的 `serviceName`；
+2. `driver.dat` / `driver64.dat` 的第一行（需要给 `cheatEngineDir`）；
+3. 默认 `CEDRIVER73`。
+
+## 三、用法
+
+### 3.1 在 node-cheat-engine 里直接用
+
+```js
+const { DbkBackend, Process, setDefaultBackend } = require('node-cheat-engine');
+
+const backend = new DbkBackend({ cheatEngineDir: 'C:\\Program Files\\Cheat Engine' });
+
+// 先自检：设备能不能打开、驱动版本能不能读到
+const probe = backend.probe();
+console.log(probe);
+// { devicePath: '\\\\.\\CEDRIVER73', opened: false, version: null, error: '...' }
+
+setDefaultBackend(backend);
+const proc = Process.open(1234);
+const buf = proc.readMemory(0x7ff000001000n, 64);   // ← 走内核 ioctl
+proc.close();
+backend.dispose();
+```
+
+### 3.2 在 DSH 插件里切换
+
+```yaml
+config:
+  backend: dbk
+  cheatEngineDir: 'C:\Program Files\Cheat Engine'   # 可选：让插件读 driver.dat 拿真实服务名
+  dbkServiceName: ''                                # 可选：直接指定服务名
+```
+
+### 3.3 自检工具
+
+```
+ce_kernel { action: "probe_driver" }
+```
+
+这是**唯一能在真机上验证本后端的手段**（原因见下一节），它会报告：
+
+```
+设备路径：\\.\CEDRIVER73
+能否打开：能 / 不能
+驱动版本：x.y.z.w
+内核服务 DBK64：RUNNING
+```
+
+## 五、支持的能力
+
+| 操作 | 实现方式 | 说明 |
+| --- | --- | --- |
+| 读 / 写内存 | ✅ **驱动**（`READ_MEMORY` / `WRITE_MEMORY`） | 本后端存在的唯一理由；受保护进程也能读写 |
+| **分配内存** | ✅ **驱动**（`IOCTL_CE_ALLOCATEMEM` = `0x22E07C`） | 驱动 `KeAttachProcess` 到目标进程再调 `ZwAllocateVirtualMemory`，**受保护进程也能分配** |
+| 进程/模块/线程枚举 | 委托 `SelfBackend` | 本来就不受进程保护影响 |
+| 内存区域枚举 | 委托 `SelfBackend`（`VirtualQueryEx`） | 同上 |
+| 改内存保护 | ⚠️ **用户态**（`VirtualProtectEx`） | 见下方说明 —— 驱动侧在 x64 上是空的 |
+| 释放内存 | ⚠️ **用户态**（`VirtualFreeEx`） | 驱动没有释放目标进程内存的 ioctl |
+| 挂起/恢复线程 | ❌ 未实现 | 驱动有 `SUSPENDTHREAD`/`RESUMETHREAD`（`$0822`/`$0823`） |
+| 物理内存读写 | ❌ 未实现 | `IOCTL_CE_READPHYSICALMEMORY`（`$0806`）等 |
+| 内核调试（断点/单步） | ❌ 未实现 | 涉及驱动侧调试器状态机，风险高 |
+
+### 5.1 为什么 `changeProtection` 不走驱动
+
+CE 的驱动里**确实**有一个 `IOCTL_CE_MAKEWRITABLE`（功能号 `$0819`），但它在
+**x64 驱动上是空的** —— `DBKKernel/IOPLDispatcher.c:474-491`：
+
+```c
+case IOCTL_CE_MAKEWRITABLE:
+    {
+#ifdef AMD64
+        //untill I know how win64 handles paging, not implemented
+#else
+        struct InputBuf {
+            UINT64 StartAddress;
+            ULONG  Size;
+            BYTE   CopyOnWrite;
+        } *PInputBuf;
+        PInputBuf = Irp->AssociatedIrp.SystemBuffer;
+        ntStatus = MakeWritable(...) ? STATUS_SUCCESS : STATUS_UNSUCCESSFUL;
+#endif
+        break;
+    }
+```
+
+所以 64 位 Windows 上发这个 ioctl 只会拿到「无效请求」（`STATUS_INVALID_DEVICE_REQUEST`）。
+
+而且它的输入结构里**没有 `processid`** —— `MakeWritable` 是按**调用者进程**的页表
+改 PTE（`deepkernel.c` 里那个 `x->RW=1` 直接写 PTE），本来也不适合"改另一个进程的保护"。
+
+**因此 `changeProtection` 委托用户态 `VirtualProtectEx`**，并如实报告这一点。
+
+> **好消息**：**写内存不需要先改保护**。驱动的写路径本身就在内核态执行，
+> 只读页照样能写（`SelfBackend` 那种"先临时放开保护"的麻烦在 DBK 后端里不存在）。
+> 需要 `changeProtection` 的场景主要是把页改成可执行、或让目标进程自己也能写。
+
+### 5.2 `allocate` 的数据流（容易写错的地方）
+
+CE 源码（`DBK32functions.pas:2217-2223`）的输入结构：
+
+```pascal
+x: record
+  processid: uint64;
+  baseaddress: uint64;
+  size: uint64;
+  AllocationType: uint64;
+  Protect: uint64;
+end;   // 5 × 8 = 40 字节
+```
+
+驱动侧（`IOPLDispatcher.c` 的 `ALLOCATEMEM` 分支）**把结果写回同一块 SystemBuffer**：
+
+```c
+*(PUINT64)Irp->AssociatedIrp.SystemBuffer = 0;
+*(PUINT_PTR)Irp->AssociatedIrp.SystemBuffer = (UINT_PTR)BaseAddress;
+```
+
+⚠️ 所以调用时 **in 与 out 必须是同一块缓冲**，再从**偏移 0** 读返回值：
+
+```js
+const buffer = packAllocInput(pid, preferred, BigInt(size), MEM_COMMIT | MEM_RESERVE, protect);
+ioctl(DBK_IOCTL.ALLOCATE_MEM, buffer, buffer.length, buffer);  // in/out 同一块
+const address = readAllocResult(buffer);                        // 偏移 0 的 uint64
+```
+
+若误把 out 传成另一块空缓冲，读到的永远是 0。
+
+## 六、未验证部分（**请务必读完**）
+
+### 4.1 为什么无法在本机验证
+
+只有驱动**真正加载**后 `\\.\CEDRIVER73` 才存在，而**加载内核驱动需要管理员权限**
+（Windows 硬边界，见 [README 的内核驱动一节](../README.md)）。
+开发这个后端的环境没有管理员权限，因此：
+
+| 项目 | 状态 |
+| --- | --- |
+| ioctl 码与 CE 源码一致 | ✅ 已用**逐项 OR 累加**核对，测试写死具体数值 |
+| 输入结构是 packed 18 字节 | ✅ 已用字段偏移断言验证 |
+| 设备名解析（含 driver.dat） | ✅ 已用真实文件格式测试 |
+| 设备打不开时的错误路径 | ✅ 已测试（本机就是这种情况） |
+| **驱动侧实际期待的结构布局** | ❌ **未验证** —— 只能在装好驱动的机器上试 |
+| **读写在真实受保护进程上的效果** | ❌ **未验证** |
+
+### 4.2 已知的具体风险
+
+1. **`processid` 的宽度**。CE 的 Pascal 源码里是 `uint64`，但 32 位与 64 位构建的
+   `packed record` 布局可能不同。本实现按 **8 字节**写（与 DBK64 的 64 位驱动对应）。
+   若驱动侧实际期待 `dword`，读到的 `startaddress` 会错位 —— 表现为读到全 0 或乱码。
+2. **驱动侧可能有额外的对齐要求**。CE 的 Pascal 用 `packed record`，
+   但 C 侧（`DBKKernel/`）的结构体若未加 `#pragma pack(1)`，布局会不同。
+   CE 的 `DBK32functions.pas` 是**用户态**那份，理论上与驱动侧一致，但这一点没能实测。
+3. **`GET_VERSION` 的返回布局**。本实现把返回的前几个非零 dword 拼成版本号，
+   布局未经确认，因此 `probe()` 里对"版本读不出来"单独给了一条提示
+   （它意味着**协议可能不一致**，而不是驱动没工作）。
+
+### 4.3 出问题时怎么排查
+
+先跑 `ce_kernel action=probe_driver`：
+
+- **打不开设备** → 驱动没加载 / 服务名不对 / 未提权。这一层与本后端无关，
+  按输出里的三条原因逐条排。
+- **能打开但版本读不到** → 高度怀疑 §4.2 的结构布局问题。
+- **能打开、版本正常、但读到的字节不对** → 大概率是 §4.2 第 1 条
+  （`processid` 宽度）。此时可以试着把 `packReadInput` / `packWriteBuffer` 里的
+  `writeBigUInt64LE(pid, 0)` 改成 `writeUInt32LE(pid, 0)` 并把后续偏移整体前移 4 字节，
+  对比两种布局哪个能读对。
+
+## 七、尚未实现的能力
+
+见 §五 的表格。要点复述：
+
+- **挂起/恢复线程**：驱动有 `IOCTL_CE_SUSPENDTHREAD`（`$0822`）/
+  `RESUMETHREAD`（`$0823`），未实现，能力声明里 `suspendThreads: false`。
+- **物理内存读写**：`IOCTL_CE_READPHYSICALMEMORY`（`$0806`）/
+  `WRITEPHYSICALMEMORY`（`$0807`）/ `GETPHYSICALADDRESS`（`$0808`），未实现。
+- **内核调试**：断点、单步、`GETCR3`/`GETSDT`/`GETIDT` 等。涉及驱动侧调试器状态机，
+  风险高，未做。
+- **`ALLOCATEMEM_NONPAGED`**（`$0826`，内核态非分页内存）：CE 用它给驱动自己分配
+  通信缓冲，与"目标进程内存"无关，本后端不需要。
+
+> 这些**不声称支持**是刻意的：能力声明里对应的字段就是 `false`，
+> 上层可以据此降级，而不是在运行时神秘失败。
+>
+> 另外要注意 `changeProtection` / `free` 虽然声明为 `true`，
+> 但它们是**用户态**实现的 —— 对受保护进程会失败。
+> 这是 CE 驱动本身的能力缺口（见 §5.1），不是本后端的偷懒。

package/docs/backends.md

@@ -0,0 +1,273 @@
+# 两种内存后端：自研引擎 与 原生 CE
+
+本移植提供**统一接口 + 两个可切换后端**。上层 API（扫描、地址表、`.CT` 读写、
+地址表达式）对两者一视同仁，因为它们都只依赖 `MemoryBackend` 接口。
+
+| | `SelfBackend`（默认） | `NativeCeBackend` |
+| --- | --- | --- |
+| 名称 | `'self'` | `'native-ce'` |
+| 原理 | 本进程内通过 koffi 直接调 Win32 API | 作为客户端连接 CE 官方 `ceserver` 的 TCP 协议 |
+| 外部依赖 | 无 | 需要运行中的 `ceserver` |
+| 同步性 | **同步**（`capabilities.sync === true`） | **异步**（返回 Promise） |
+| 需要管理员 | 视目标而定 | 视目标与 ceserver 而定 |
+| 受保护进程 | 读不到（无内核驱动） | 取决于服务端权限与扩展 |
+
+---
+
+## 一、自研后端（默认，推荐先用这个）
+
+开箱即用、无外部依赖，覆盖 Cheat Engine 在**未加载内核驱动**时能做的全部用户态操作。
+
+```js
+const { Process, ScanSession, VariableType, ScanOption, RoundingType } = require('node-cheat-engine');
+
+// 默认就是 SelfBackend
+const proc = Process.open(1234);
+const s = new ScanSession(proc);
+s.firstScan({
+  variableType: VariableType.DWord,
+  scanOption: ScanOption.ExactValue,
+  roundingType: RoundingType.Rounded,
+  floatAccuracy: 0,
+  value1: '1000',
+});
+console.log('命中', s.resultCount, '个');
+
+proc.close();
+```
+
+显式指定后端：
+
+```js
+const { Process, SelfBackend } = require('node-cheat-engine');
+
+const backend = new SelfBackend();
+const proc = Process.open(1234, { backend });
+// ...
+proc.close();
+backend.dispose();
+```
+
+全局切换默认后端：
+
+```js
+const { setDefaultBackend, NativeCeBackend } = require('node-cheat-engine');
+setDefaultBackend(new NativeCeBackend({ host: '127.0.0.1', port: 52736 }));
+setDefaultBackend(null); // 恢复自研后端
+```
+
+---
+
+## 二、原生 CE 后端（通过 ceserver）
+
+### 2.1 先准备一个 ceserver
+
+`ceserver` 是 Cheat Engine 官方仓库里的服务端程序（源码在
+`Cheat Engine/ceserver/`），它把 CE 的内存能力通过 TCP 暴露出来。
+本仓库**不含它的可执行文件**，你需要自己准备：
+
+1. 从 Cheat Engine 官方发行版中查找 `ceserver` / `ceserver.exe`；
+2. 或者用 CE 源码里的 `Cheat Engine/ceserver/` 自行编译
+   （Linux/Android 版本在 CE 源码中；Windows 版本同样位于该目录）；
+3. 启动它，默认监听 **52736** 端口。
+
+先用 telnet / 自备脚本确认端口可达，再跑下面的代码。
+
+### 2.2 用法（注意 `await`）
+
+```js
+const { NativeCeBackend, openProcessAsync, ScanSession } = require('node-cheat-engine');
+
+const backend = new NativeCeBackend({ host: '127.0.0.1', port: 52736 });
+
+// 版本探测（可选，用于确认连通）
+console.log('ceserver 版本:', await backend.getVersion());
+
+// 打开进程：必须用异步入口
+const proc = await openProcessAsync(1234, { backend });
+
+// 读内存：用异步变体
+const buf = await proc.readMemoryAsync(0x7ff000001000n, 16);
+
+// 写内存
+await proc.writeMemoryAsync(0x7ff000001000n, Buffer.from([1, 2, 3, 4]));
+
+// 区域与模块
+const regions = await proc.regionsAsync();
+const modules = await proc.modulesAsync();
+
+await proc.closeAsync();
+await backend.dispose();
+```
+
+### 2.3 也可以用异步版的进程枚举
+
+```js
+const { listProcessesAsync, findProcessesByNameAsync } = require('node-cheat-engine');
+const all = await listProcessesAsync(backend);
+const notepads = await findProcessesByNameAsync('notepad', backend);
+```
+
+---
+
+## 三、同步与异步的分工（重要）
+
+`MemoryBackend` 的方法返回 `MaybePromise<T>`：
+
+- **同步后端**（`SelfBackend`）直接返回值，**不**返回 Promise；
+- **异步后端**（`NativeCeBackend`）返回 Promise。
+
+`Process` 同时提供两套方法：
+
+| 同步（仅同步后端可用） | 异步（两种后端都可用） |
+| --- | --- |
+| `Process.open(pid)` | `await openProcessAsync(pid)` |
+| `proc.readMemory(addr, n)` | `await proc.readMemoryAsync(addr, n)` |
+| `proc.writeMemory(addr, buf)` | `await proc.writeMemoryAsync(addr, buf)` |
+| `proc.regions()` | `await proc.regionsAsync()` |
+| `proc.modules()` | `await proc.modulesAsync()` |
+| `proc.threadIds()` | `await proc.threadIdsAsync()` |
+| `proc.allocate(...)` | `await proc.allocateAsync(...)` |
+| `proc.protect(...)` | `await proc.protectAsync(...)` |
+| `proc.isWow64()` | `await proc.isWow64Async()` |
+| `proc.close()` | `await proc.closeAsync()` |
+
+在异步后端上误用同步方法时，会得到**明确错误**而不是崩掉：
+
+```
+后端 "native-ce" 是异步的，不能使用同步方法 readMemory()。
+请改用异步变体（例如 readMemoryAsync()）并 await，
+或改用同步后端 SelfBackend。
+```
+
+`await` 对两种后端都安全（`await` 一个非 Promise 值会原样返回），
+所以如果你只写一套代码，统一用 `await` + `*Async` 即可。
+
+---
+
+## 四、为什么原生 CE 后端必须是异步的
+
+这不是偷懒，而是**已证明技术上不可行**。曾尝试两种同步包装方式，都实测死锁：
+
+### 尝试 1：主线程 `Promise` + `Atomics.wait`
+
+```js
+// 反例（不要这么写）
+const p = socketRoundTrip();
+while (!done) Atomics.wait(ctrl, 0, 0, 50);   // ← 卡死
+```
+
+`Atomics.wait` 会完全阻塞当前线程的事件循环，socket 的 `connect`/`data`
+回调与 Promise 微任务都永远得不到执行。
+最小复现：`docs/evidence/atomics-wait-io.js` → 输出 `FAIL: 死锁/未完成`。
+
+### 尝试 2：socket 放 worker 线程，主线程仍 `Atomics.wait`
+
+```js
+// 同样反例：worker 里也阻塞
+worker: Atomics.wait(ctrl, 0, seq, 20)   // ← worker 自己的事件循环也停了
+```
+
+**worker 线程被阻塞后，它自己的 socket 回调同样不会执行**，
+于是主线程每次都等到超时。最小复现：`docs/evidence/mini-repro.js`。
+
+（补充验证：`setImmediate` 自旋轮询会饥饿 I/O 阶段；`setTimeout` 轮询也不行，
+因为阻塞发生在同一线程。）
+
+### 结论
+
+`Atomics.wait` 与 socket I/O **无法在任何同一线程内共存**。
+子进程方案也验证失败（沙箱下 `spawnSync` 子进程的 socket 无响应）。
+
+因此选择最诚实的做法：**原生 CE 后端暴露为异步 API**，
+而不是用子进程或忙轮询把复杂度藏到别处。
+
+---
+
+## 五、能力矩阵（用于运行时判断）
+
+```js
+const { SelfBackend, NativeCeBackend } = require('node-cheat-engine');
+
+console.table({
+  SelfBackend: new SelfBackend().capabilities,
+  NativeCeBackend: new NativeCeBackend({ port: 1 }).capabilities,
+});
+```
+
+| 能力 | SelfBackend | NativeCeBackend |
+| --- | --- | --- |
+| `sync`（同步完成） | `true` | `false` |
+| `enumerateProcesses` | ✅ | ✅ |
+| `queryRegions` | ✅ | ✅ |
+| `queryModules` | ✅ | ✅ |
+| `queryThreads` | ✅ | ❌（明确抛错） |
+| `suspendThreads` | ✅ | ❌ |
+| `allocateMemory` | ✅ | ✅ |
+| `changeProtection` | ✅ | ✅ |
+| `local` | `true` | `false` |
+| `requiresServer` | `false` | `true` |
+
+调用前建议检查 `backend.capabilities.xxx`，不要假设能力存在。
+`NativeCeBackend.queryThreads()` 会抛出带解释的错误（而不是返回空数组假装成功）。
+
+---
+
+## 六、ceserver 协议实现范围
+
+完整命令号列表见 `CESERVER_CMD`（严格对齐 `ceserver.h`）。已实现：
+
+| 命令 | 用途 |
+| --- | --- |
+| `GETVERSION(0)` | 版本探测 |
+| `OPENPROCESS(3)` / `CLOSEHANDLE(7)` | 打开/关闭进程 |
+| `CREATETOOLHELP32SNAPSHOT(4)` | 建进程/模块快照 |
+| `PROCESS32FIRST(5)` / `PROCESS32NEXT(6)` | 进程枚举 |
+| `VIRTUALQUERYEX(8)` | 内存区域枚举 |
+| `READPROCESSMEMORY(9)` | 读内存（`compress=0`） |
+| `WRITEPROCESSMEMORY(10)` | 写内存 |
+| `MODULE32FIRST(22)` / `MODULE32NEXT(23)` | 模块枚举 |
+| `ALLOC(26)` / `FREE(27)` | 目标内分配/释放 |
+| `CHANGEMEMORYPROTECTION(36)` | 改内存保护 |
+
+**未实现**（调用会抛 `BackendUnsupportedError` 或明确错误）：
+线程枚举 `CREATETOOLHELP32SNAPSHOTEX(35)`（响应布局随版本变化）、
+调试器命令（`STARTDEBUG`/`SETBREAKPOINT` 等）、速度修改 `SPEEDHACK_SETSPEED(30)`、
+管道（`OPENNAMEDPIPE`/`PIPEREAD`/`PIPEWRITE`）、符号文件加载 `GETSYMBOLLISTFROMFILE(24)`。
+
+协议组帧细节（字段宽度、响应布局、两轮读取的原因）都写在
+`src/backend/native-ce-backend.ts` 的注释里，并有用本地假服务端逐字段核对的测试
+（`test/backend.test.js`，20 个用例）。
+
+---
+
+## 七、联调排查
+
+| 现象 | 原因与处理 |
+| --- | --- |
+| `无法连接 ceserver（host:port）：...` | 服务端没起、端口不对、或防火墙。错误信息里带了 host:port。 |
+| `连接 ceserver 超时` | 地址不可达。确认 ceserver 在目标机器上监听。 |
+| `ceserver 无法打开进程 N（...）` | 进程不存在，或服务端权限不足 → 以管理员身份运行 ceserver。 |
+| `ceserver 命令 "X" 响应超时` | 服务端卡住或响应长度与预期不符。可调大 `timeoutMs`。 |
+| `后端 "native-ce" 是异步的...` | 你用了同步方法。改用 `*Async` 变体 + `await`。 |
+| `ceserver 写入不完整` | 服务端只写了部分字节（常见于保护页）。本实现会**抛错而不是静默通过**。 |
+
+需要真实联调时，把 `ceserver` 起来后：
+
+```bash
+npm run test:backend
+```
+
+**注意**：`test/backend.test.js` 目前**全部**使用本地假服务端来逐字段核对协议
+（20 个用例），**不含**依赖真实 `ceserver` 的用例 —— 因为本仓库不含该二进制，
+测试必须能在没有它的环境下通过。因此这 20 个用例证明的是
+**组帧/解析正确**，不证明"你的 ceserver 部署可用"。
+后者请按上面的排查表手工验证：
+
+```js
+const { NativeCeBackend } = require('node-cheat-engine');
+const b = new NativeCeBackend({ host: '127.0.0.1', port: 52736 });
+console.log(await b.getVersion());      // 能打印版本即说明连通
+console.log((await b.listProcesses()).length, '个进程');
+await b.dispose();
+```

package/docs/evidence/atomics-wait-io.js

@@ -0,0 +1,20 @@
+// 验证：主线程 Atomics.wait 期间，Promise 微任务与 socket I/O 能否推进
+const net = require('node:net');
+const server = net.createServer(s => { s.on('data', d => s.write('pong')); });
+server.listen(0, '127.0.0.1', () => {
+  const port = server.address().port;
+  const state = new Int32Array(new SharedArrayBuffer(4));
+  let done = false; let result = null;
+  const p = new Promise((resolve, reject) => {
+    const c = net.connect({ host: '127.0.0.1', port });
+    c.on('connect', () => c.write('ping'));
+    c.on('data', d => { result = d.toString(); c.destroy(); resolve(result); });
+    c.on('error', reject);
+  });
+  p.then(v => { result = v; done = true; Atomics.store(state,0,1); Atomics.notify(state,0); },
+         e => { result = 'ERR:'+e.message; done = true; Atomics.store(state,0,1); Atomics.notify(state,0); });
+  const t0 = Date.now();
+  while (!done && Date.now() - t0 < 3000) { Atomics.wait(state, 0, 0, 50); }
+  console.log(done ? `OK: 主线程 Atomics.wait 期间 socket 往返成功 -> ${result} (${Date.now()-t0}ms)` : `FAIL: 死锁/未完成 (${Date.now()-t0}ms)`);
+  server.close();
+});

package/docs/evidence/mini-repro.js

@@ -0,0 +1,98 @@
+/**
+ * 最小复现（self-contained）：验证
+ *   主线程 `Atomics.wait` 阻塞  +  worker 里非阻塞轮询 + worker 里 socket I/O
+ * 三者能否共存。
+ *
+ * 结论（跑通即证明）：worker 侧**必须全程非阻塞**（setImmediate 轮询）。
+ * 若 worker 里用 `Atomics.wait` 阻塞，则 worker 自己的事件循环被卡死，
+ * socket 回调与 postMessage 都执行不了 —— 主线程每次都超时。
+ */
+'use strict';
+
+const { Worker } = require('node:worker_threads');
+const net = require('node:net');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const WORKER_SRC = `
+const { parentPort } = require('node:worker_threads');
+const { connect } = require('node:net');
+
+let shared = null, host = '127.0.0.1', port = 0;
+
+parentPort.on('message', (msg) => {
+  if (msg.type !== 'init') return;
+  host = msg.host; port = msg.port; shared = msg.buf;
+
+  const ctrl = new Int32Array(shared, 0, 4);
+  let last = Atomics.load(ctrl, 0);
+
+  const pump = () => {
+    const seq = Atomics.load(ctrl, 0);
+    if (seq === last) { setTimeout(pump, 1); return; }   // 关键：用 setTimeout 让出到"定时器阶段"，
+                                                         // 事件循环才会进入 poll 阶段处理 socket I/O。
+                                                         // 用 setImmediate 会自旋饥饿 I/O（实测超时）。
+    last = seq;
+    console.log('[worker] 收到请求 seq =', seq);
+    const c = connect({ host, port });
+    c.on('connect', () => c.write('ping'));
+    c.on('data', (d) => {
+      console.log('[worker] 收到响应:', d.toString());
+      c.destroy();
+      Atomics.store(ctrl, 3, seq);
+      Atomics.notify(ctrl, 3);
+      setTimeout(pump, 1);
+    });
+    c.on('error', (e) => {
+      console.log('[worker] socket 错误', e.message);
+      Atomics.store(ctrl, 3, seq);
+      Atomics.notify(ctrl, 3);
+      setTimeout(pump, 1);
+    });
+  };
+
+  parentPort.postMessage({ type: 'ready' });
+  setImmediate(pump);
+});
+`;
+
+// 写入 worker 文件（每次运行重写，保证与上面的源码一致）
+const workerPath = path.join(__dirname, '_mini-worker.js');
+fs.writeFileSync(workerPath, WORKER_SRC, 'utf8');
+
+const server = net.createServer((s) => {
+  s.on('data', () => s.write('pong'));
+});
+
+server.listen(0, '127.0.0.1', () => {
+  const port = server.address().port;
+  const buf = new SharedArrayBuffer(64);
+  const ctrl = new Int32Array(buf, 0, 4);
+
+  const w = new Worker(workerPath);
+  w.on('message', (m) => {
+    if (m.type !== 'ready') return;
+    console.log('[main] worker 就绪，发请求并阻塞等待');
+    Atomics.store(ctrl, 0, 1);
+    Atomics.notify(ctrl, 0);
+
+    const t0 = Date.now();
+    for (;;) {
+      const done = Atomics.load(ctrl, 3);
+      if (done === 1) {
+        console.log(`[main] ✅ 成功，用时 ${Date.now() - t0}ms`);
+        break;
+      }
+      if (Date.now() - t0 > 5000) {
+        console.log('[main] ❌ 超时 5s');
+        break;
+      }
+      Atomics.wait(ctrl, 3, done, 100);
+    }
+    void w.terminate();
+    server.close();
+    fs.unlinkSync(workerPath);
+  });
+
+  w.postMessage({ type: 'init', host: '127.0.0.1', port, buf });
+});