wowdump 0.3.8 → 0.3.9

package/README.md

@@ -1,41 +1,61 @@
 # wowdump
 
-WoW 原生内存分析 CLI。用 WinDbg CDB 运行时证据和 IDA Pro/iced-x86 局部反汇编定位字段，生成可复核的 Reader profile。
+Windows 下的 WoW 原生内存分析 CLI。用 CDB 运行时证据和 IDA Pro MCP / iced-x86 分析字段，生成 Reader 可读取的 build profile。
 
-## 安装
+## 安装与更新
 
 ```powershell
 npm install --global wowdump
 wowdump init
+wowdump --version
 ```
 
-安装脚本会初始化 `~/.wowdump`，并把 Skill 与 references 参考文档安装到 `~/.agents/skills/wowdump`。反汇编保底使用 npm 内置的 `iced-x86`。
+安装会初始化 `~/.wowdump`，把包内完整 Skill 安装到 `~/.agents/skills/wowdump`。升级或 init 会同步 Skill，差异文件先备份到 `~/.wowdump/skill-backups/`；个人新增文件和 config.json 保留。iced-x86 随 npm 安装，CDB 从本机探测，不自动下载或修改环境变量。
 
-## 基本流程
+## 使用流程
 
 ```powershell
-# 1. 发现目标并创建/复用 build 数据库
+# 1. 发现目标，取得真实 PID、buildKey、路径与哈希
 wowdump targets
-wowdump database status --build "retail@VERSION"
+wowdump database status --build "<buildKey>"
 
-# 2. 用 CDB 导出运行时模块段
-wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind dump --confirm
+# 2. 仅在需要新的静态证据时导出相关段
+wowdump analyze runtime --pid <pid> --build "<buildKey>" --kind dump --confirm
 
-# 3. 用 IDA Pro MCP（若可用）或 iced-x86 分析 session dump manifest，保存字段候选和证据
-# 4. 需要函数调用参数时，用 CDB 硬件断点
-wowdump analyze debug --pid 1234 --build "retail@VERSION" --rva 0x... --kind breakpoint --confirm
-# 5. 将候选证据交给 verify，再用 Reader 验证
+# 3. Agent 使用 IDA MCP 或 iced-x86 分析，生成候选 profile
+# 4. 验证实际读取；不会修改候选状态
+wowdump analyze runtime --pid <pid> --build "<buildKey>" --kind verify --profile "<candidate.profile.json>" --confirm
 
-# 6. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
-wowdump memory read --pid 1234 --profile "$HOME\.wowdump\retail@VERSION\profile\player-state.json" --field playerAuras
+# 5. 补齐字段和对象身份证据，用户确认后保存至当前 build 的 profile 目录
+wowdump memory read --pid <pid> --build "<buildKey>" --profile "<character-stats.json>" --field critPercent
 
-# 枚举已提交虚拟内存区（复用同一个管理员 broker）
-wowdump memory regions --pid 1234 --start 0x15000000000 --end 0x15400000000 --max-regions 20000
+# 有界页面查询
+wowdump memory regions --pid <pid> --start <startAddress> --end <endAddress> --max-regions 20000
 ```
 
-Windows reader 首次使用时由 Node 请求 UAC 启动 broker，后续内存读取和 CDB 调试请求复用同一 broker，空闲 20 分钟后退出。CDB 路径探测不会下载或修改环境变量；所有调试请求都需要显式 `--confirm`。
+尖括号是待替换参数。已有匹配且适用的 profile 时直接 Reader 读取，无需重新 dump。CDB 诊断与断点不是必经步骤，执行前先查 Skill 的退出和超时限制。
 
-`targets` 会写入 `~/.wowdump/<buildKey>/build.json` 和 `database/database.json`；同一 build 的 IDA 数据库只创建一份。`analyze runtime --kind dump` 默认把 `.text`、`.rdata`、`.pdata` 写入当前 session，`.data` 需通过 `--sections` 显式加入。`analyze runtime --kind verify --profile <file>` 只验证已有 profile 的 RVA。Reader 只读取 `~/.wowdump/<buildKey>/profile/`，不读取 IDA 数据库和 dump 二进制。完整字段和 JSON 约定见 `~/.agents/skills/wowdump/references/commands.md`、`references/request-schema.md`、`references/windbg.md` 与 `references/profiles.md`。
+内存和 CDB 请求复用同一个管理员 broker：首次请求 UAC，空闲 20 分钟退出。所有调试请求需要 `--confirm`。
+
+## 数据放在哪里
+
+统一使用 `~/.wowdump/<buildKey>/`：
+
+- `build.json`：目标身份。
+- `database/`：静态分析数据库位置和状态，不因任务重复创建。
+- `runtime/<session>/`：本轮证据、dump 和候选。
+- `profile/`：用户确认的 Reader 接口。
+
+Dump 默认导出 `.text/.rdata/.pdata`，`.data` 按需加入。Reader 默认选择当前 build 的 profile，也支持显式路径；它不读取 IDA 数据库或 dump 二进制。
+
+## 0.3.9 的读取与验证
+
+- verify 接受 candidate 或 reader_ready；普通 memory read 要求 reader_ready。
+- 输出 `validation.read: "passed"`，替代旧版 `verified:true`；fieldSemantics、rootSemantics、crossProcess 为 not_checked，需要独立证据。命令不自动认证语义、提升状态或保存 profile。
+- 新增 `root.lookup`：按动态键选择有界表项，核对对象键并检查读取期间变化，避免固化本轮哈希槽位。含 lookup 的 profile 需要 0.3.9 或更新版本；旧 Reader 可能忽略未知参数。
+- 校验目标 build 时，缺少 executableSha256 会报错。模块外根 RVA、空根、短读和不一致查表结果均返回结构化错误。
+
+详细用法由安装的 Skill 按需加载：[命令](skills/wowdump/references/commands.md)、[Profile 格式](skills/wowdump/references/profiles.md)、[字段挖掘方法与成功案例](skills/wowdump/references/character-stats-case.md)、[CDB 限制](skills/wowdump/references/windbg.md)。
 
 ## 开发验证
 
@@ -43,5 +63,6 @@ Windows reader 首次使用时由 Node 请求 UAC 启动 broker，后续内存
 npm run typecheck
 npm run build
 npm test
-npm pack --dry-run
+npm run package:verify
+npm run release:verify
 ```

package/dist/cli.js

@@ -313,7 +313,9 @@ async function validateProfileIdentity(home, buildKey, profile, file) {
         : profile.executable && typeof profile.executable === "object" && !Array.isArray(profile.executable)
             ? String(profile.executable.sha256 ?? "")
             : "";
-    if (profileHash && profileHash !== build.executableSha256) {
+    if (!profileHash)
+        throw new CliError("PROFILE_IDENTITY_REQUIRED", "profile executableSha256 is required", { profileFile: file });
+    if (profileHash !== build.executableSha256) {
         throw new CliError("EXECUTABLE_MISMATCH", "profile executable hash does not match the selected build", { expected: build.executableSha256, actual: profileHash, profileFile: file });
     }
 }
@@ -535,8 +537,8 @@ export function createWowdumpCli(dependencies = {}) {
         if (normalized.kind === "verify") {
             if (!profile)
                 throw new CliError("PROFILE_REQUIRED", "verify requires --profile <file>");
-            const result = await profileEngine.read({ pid: normalized.pid, buildKey: normalized.build, executableSha256: buildRecord.executableSha256, profile, fields: undefined }, profileAdapter);
-            writeJson(io, { ...result, command: "analyze.runtime.verify", verified: true });
+            const result = await profileEngine.verify({ pid: normalized.pid, buildKey: normalized.build, executableSha256: buildRecord.executableSha256, profile, fields: undefined }, profileAdapter);
+            writeJson(io, { ...result, command: "analyze.runtime.verify" });
             return;
         }
         const requestedSections = Array.isArray(options.sections) && options.sections.length > 0

package/dist/core/profile-engine.js

@@ -132,10 +132,47 @@ function rootSpec(value, name) {
     const root = record(value, `${name}.root`);
     if (root.rva === undefined && root.address === undefined)
         throw new ProfileEngineError("PROFILE_INVALID", `${name}.root requires rva or address`);
+    if (root.rva !== undefined && root.address !== undefined)
+        throw new ProfileEngineError("PROFILE_INVALID", `${name}.root must use rva or address, not both`);
     return root;
 }
+function validateRootRange(value, module) {
+    const root = rootSpec(value, "field");
+    if (root.rva !== undefined && module.size !== undefined) {
+        const rva = hex(root.rva, "root.rva");
+        const span = root.dereference === true ? 8n : 1n;
+        if (!Number.isSafeInteger(module.size) || module.size < 1 || rva + span > BigInt(module.size)) {
+            throw new ProfileEngineError("RVA_OUT_OF_MODULE", "root RVA falls outside the selected module", { rva: String(root.rva), moduleSize: module.size });
+        }
+    }
+    if (root.lookup !== undefined) {
+        const lookup = record(root.lookup, "root.lookup");
+        for (const key of ["countRoot", "keyRoot"]) {
+            const child = rootSpec(lookup[key], key);
+            if (child.lookup !== undefined)
+                throw new ProfileEngineError("PROFILE_INVALID", "nested lookups are not supported");
+            validateRootRange(child, module);
+        }
+    }
+}
 export class ProfileEngine {
     async read(request, adapter) {
+        return this.readInternal(request, adapter, false);
+    }
+    async verify(request, adapter) {
+        const result = await this.readInternal(request, adapter, true);
+        return {
+            ...result,
+            command: "profile.verify",
+            validation: {
+                read: "passed",
+                fieldSemantics: "not_checked",
+                rootSemantics: "not_checked",
+                crossProcess: "not_checked"
+            }
+        };
+    }
+    async readInternal(request, adapter, allowCandidate) {
         const profile = record(request.profile, "profile");
         const buildKey = String(profile.buildKey ?? "");
         if (!buildKey)
@@ -148,13 +185,16 @@ export class ProfileEngine {
                 ? profile.executable
                 : undefined;
             const profileHash = typeof profile.executableSha256 === "string" ? profile.executableSha256 : String(executable?.sha256 ?? "");
+            if (!profileHash)
+                throw new ProfileEngineError("PROFILE_IDENTITY_REQUIRED", "profile executableSha256 is required when checking a target build");
             if (profileHash && profileHash !== request.executableSha256) {
                 throw new ProfileEngineError("EXECUTABLE_MISMATCH", "profile executable hash does not match the target build", { expected: request.executableSha256, actual: profileHash });
             }
         }
         const status = String(profile.readerStatus ?? profile.status ?? (profile.confidence === "reader_ready" ? "reader_ready" : ""));
-        if (status !== "reader_ready")
-            throw new ProfileEngineError("PROFILE_NOT_READY", "profile is not reader_ready", { status });
+        if (status !== "reader_ready" && !(allowCandidate && status === "candidate")) {
+            throw new ProfileEngineError("PROFILE_NOT_READY", allowCandidate ? "verify requires candidate or reader_ready" : "profile is not reader_ready", { status });
+        }
         const modules = await adapter.modules(request.pid);
         const moduleSpec = profile.module && typeof profile.module === "object" ? record(profile.module, "profile.module") : {};
         const moduleName = String(moduleSpec.name ?? profile.moduleName ?? "Wow.exe");
@@ -163,10 +203,14 @@ export class ProfileEngine {
             throw new ProfileEngineError("MODULE_NOT_FOUND", `${moduleName} was not found`, { modules: modules.map(item => item.name) });
         const definitions = record(profile.fields ?? profile.readers, "profile.fields");
         const names = request.fields?.length ? [...request.fields] : Object.keys(definitions);
+        if (names.length === 0)
+            throw new ProfileEngineError("PROFILE_INVALID", "profile must define at least one field");
         const fields = {};
         const reads = [];
         for (const name of names) {
             const definition = record(definitions[name], `field ${name}`);
+            if (definition.root !== undefined)
+                validateRootRange(definition.root, module);
             fields[name] = await this.readField(request.pid, hex(module.base, "module.base"), name, definition, adapter, reads);
         }
         return { ok: true, command: "profile.read", pid: request.pid, buildKey, profileId: profileId(profile), module, fields, reads };
@@ -195,9 +239,74 @@ export class ProfileEngine {
         if (root.dereference === true) {
             const bytes = await this.readBytes(pid, address, 8, field, adapter, reads);
             address = BigInt(`0x${bytes.toString("hex").match(/../g).reverse().join("")}`);
+            if (address === 0n)
+                throw new ProfileEngineError("NULL_POINTER", `${field} root is null`);
         }
+        if (root.lookup !== undefined)
+            return this.resolveLookup(pid, moduleBase, address, root, adapter, field, reads);
         return address;
     }
+    async resolveLookup(pid, moduleBase, table, root, adapter, field, reads) {
+        const spec = record(root.lookup, `${field}.root.lookup`);
+        const countRoot = rootSpec(spec.countRoot, "lookup.countRoot");
+        const keyRoot = rootSpec(spec.keyRoot, "lookup.keyRoot");
+        if (countRoot.lookup !== undefined || keyRoot.lookup !== undefined)
+            throw new ProfileEngineError("PROFILE_INVALID", "nested lookups are not supported");
+        const stride = integer(spec.stride, "lookup.stride", 4096);
+        const maximum = integer(spec.maxItems, "lookup.maxItems", 65536);
+        const keySize = integer(spec.keySize, "lookup.keySize", 64);
+        const entryKeyOffset = integer(hex(spec.entryKeyOffset ?? "0x0", "lookup.entryKeyOffset"), "lookup.entryKeyOffset", 4096);
+        const valueOffset = integer(hex(spec.valueOffset, "lookup.valueOffset"), "lookup.valueOffset", 4096);
+        const keyOffset = hex(spec.keyOffset ?? "0x0", "lookup.keyOffset");
+        const objectKeyOffset = hex(spec.objectKeyOffset, "lookup.objectKeyOffset");
+        if (!stride || !maximum || !keySize || entryKeyOffset + keySize > stride || valueOffset + 8 > stride || stride * maximum > 1024 * 1024) {
+            throw new ProfileEngineError("PROFILE_INVALID", "lookup bounds must fit within the stride and a 1 MiB maximum table");
+        }
+        const countType = spec.countType ?? "u32";
+        if (countType !== "u32" && countType !== "u64")
+            throw new ProfileEngineError("PROFILE_INVALID", "lookup.countType must be u32 or u64");
+        const countAddress = await this.resolveRoot(pid, moduleBase, countRoot, adapter, field, reads);
+        const countBytes = await this.readBytes(pid, countAddress, countType === "u64" ? 8 : 4, field, adapter, reads);
+        const countBig = countType === "u64" ? countBytes.readBigUInt64LE() : BigInt(countBytes.readUInt32LE());
+        if (countBig > BigInt(maximum))
+            throw new ProfileEngineError("LOOKUP_LIMIT", "table count exceeds maxItems", { count: countBig.toString(), maximum });
+        const keyAddress = await this.resolveRoot(pid, moduleBase, keyRoot, adapter, field, reads) + keyOffset;
+        const key = await this.readBytes(pid, keyAddress, keySize, field, adapter, reads);
+        if (key.every(byte => byte === 0))
+            throw new ProfileEngineError("LOOKUP_KEY_EMPTY", "lookup key is empty");
+        const count = Number(countBig);
+        if (!count)
+            throw new ProfileEngineError("LOOKUP_NOT_FOUND", "lookup table is empty");
+        const bytes = await this.readBytes(pid, table, count * stride, field, adapter, reads);
+        let match = -1;
+        for (let index = 0; index < count; index++) {
+            const offset = index * stride;
+            if (!bytes.subarray(offset + entryKeyOffset, offset + entryKeyOffset + keySize).equals(key))
+                continue;
+            if (match !== -1)
+                throw new ProfileEngineError("LOOKUP_AMBIGUOUS", "multiple table entries match the key");
+            match = offset;
+        }
+        if (match === -1)
+            throw new ProfileEngineError("LOOKUP_NOT_FOUND", "no table entry matches the key");
+        const object = bytes.readBigUInt64LE(match + valueOffset);
+        if (object === 0n)
+            throw new ProfileEngineError("NULL_POINTER", "matching table entry contains a null pointer");
+        const objectKey = await this.readBytes(pid, object + objectKeyOffset, keySize, field, adapter, reads);
+        if (!objectKey.equals(key))
+            throw new ProfileEngineError("LOOKUP_OBJECT_MISMATCH", "object key does not match the selected table entry");
+        const { lookup: _lookup, ...tableRoot } = root;
+        const tableAfter = await this.resolveRoot(pid, moduleBase, tableRoot, adapter, field, reads);
+        const countAddressAfter = await this.resolveRoot(pid, moduleBase, countRoot, adapter, field, reads);
+        const keyAddressAfter = await this.resolveRoot(pid, moduleBase, keyRoot, adapter, field, reads) + keyOffset;
+        const countAfter = await this.readBytes(pid, countAddressAfter, countBytes.length, field, adapter, reads);
+        const keyAfter = await this.readBytes(pid, keyAddressAfter, keySize, field, adapter, reads);
+        const entryAfter = await this.readBytes(pid, table + BigInt(match), stride, field, adapter, reads);
+        if (tableAfter !== table || countAddressAfter !== countAddress || keyAddressAfter !== keyAddress || !countAfter.equals(countBytes) || !keyAfter.equals(key) || !entryAfter.subarray(entryKeyOffset, entryKeyOffset + keySize).equals(key) || entryAfter.readBigUInt64LE(valueOffset) !== object) {
+            throw new ProfileEngineError("LOOKUP_CHANGED", "lookup identity or table changed during the read; retry with a fresh snapshot");
+        }
+        return object;
+    }
     async readLayout(pid, address, layout, field, adapter, reads) {
         const kind = String(layout.kind ?? "scalar");
         if (kind === "linked_list") {
@@ -240,7 +349,7 @@ export class ProfileEngine {
         const bytesRead = Number(result.bytesRead ?? result.dataHex.length / 2);
         const bytes = Buffer.from(result.dataHex, "hex");
         reads.push({ field, address: hexText(address), size, bytesRead, dataHex: result.dataHex, complete: result.complete === true && bytesRead === size });
-        if (bytesRead !== size || bytes.length < size)
+        if (result.complete !== true || bytesRead !== size || bytes.length !== size || !/^(?:[0-9a-f]{2})*$/i.test(result.dataHex))
             throw new ProfileEngineError("PARTIAL_READ", `${field} read was incomplete`, { address: hexText(address), size, bytesRead });
         return bytes.subarray(0, size);
     }

package/dist/toolchain.js

@@ -1,112 +1,87 @@
-import { readdirSync, statSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, extname, join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolveWowdumpHome } from "./core/build-store.js";
-export const DEFAULT_WOWDUMP_SKILL = `---
-name: wowdump
-description: 用 WinDbg CDB 运行时证据和 IDA Pro MCP 或 iced-x86 定位 WoW 字段，生成并验证 Reader profile。
----
-
-# wowdump
-
-先运行 \`wowdump targets\`，再复用 \`~/.wowdump/<buildKey>/database/\`。runtime dump 保存当前 session 的二进制证据，debug 命令保存 CDB 证据，Reader 只读取 build profile。详情见 references/workflow.md、references/commands.md、references/windbg.md、references/disassemble.md 和 references/profiles.md。
-`;
-export const DEFAULT_WOWDUMP_COMMANDS = `# wowdump 命令参考
-
-1. \`wowdump targets\`
-2. \`wowdump database status --build <buildKey>\`
-3. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind dump --confirm\`
-4. \`wowdump analyze debug --pid <pid> --build <buildKey> --rva <rva> --kind breakpoint --confirm\`
-5. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind verify --profile <profile.json> --confirm\`
-6. \`wowdump memory read --pid <pid> --build <buildKey> --profile <profile.json> --field <name>\`
-
-\`dump\` 默认流式导出供 IDA/iced-x86 分析的 PE 段并生成 manifest；\`verify\` 只验证已有候选 RVA。未确认的候选 profile 放在 runtime session 目录；确认后才复制到当前 build 的 profile 目录。
-`;
 function normalizePath(value) { return resolve(value.trim().replace(/^"|"$/g, "")); }
-function directoryExists(value) { try {
-    return statSync(value).isDirectory();
-}
-catch {
-    return false;
-} }
-function fileExists(value) { try {
-    return statSync(value).isFile();
-}
-catch {
-    return false;
-} }
-async function createFileIfMissing(file, contents, created, preserved) { try {
-    await writeFile(file, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
-    created.push(file);
-}
-catch (error) {
-    if (error.code === "EEXIST")
-        preserved.push(file);
-    else
-        throw error;
-} }
 export { resolveWowdumpHome, sha256File } from "./core/build-store.js";
-export function resolveWowdumpSkillHome(env = process.env, userHome = homedir()) { return normalizePath(env.WOWDUMP_SKILL_HOME || join(userHome, ".agents", "skills")); }
+export function resolveWowdumpSkillHome(env = process.env, userHome = homedir()) {
+    return normalizePath(env.WOWDUMP_SKILL_HOME || join(userHome, ".agents", "skills"));
+}
 export async function initializeWowdumpHome(options = {}) {
     const env = options.env ?? process.env;
     const home = normalizePath(options.home ?? resolveWowdumpHome(env, options.userHome));
-    const created = [];
-    const preserved = [];
-    await mkdir(home, { recursive: true });
-    const configFile = join(home, "config.json");
-    await createFileIfMissing(configFile, `${JSON.stringify({ schema: "wowdump.config.v1" }, null, 2)}\n`, created, preserved);
     const skillDirectory = join(normalizePath(options.skillHome ?? resolveWowdumpSkillHome(env, options.userHome)), "wowdump");
-    if (directoryExists(skillDirectory))
-        preserved.push(skillDirectory);
-    else {
-        await mkdir(skillDirectory, { recursive: true });
-        created.push(skillDirectory);
+    const bundled = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", "wowdump");
+    const result = {
+        home, created: [], preserved: [], updated: [], backups: [],
+        configFile: join(home, "config.json"), skillFile: join(skillDirectory, "SKILL.md"),
+        commandsFile: join(skillDirectory, "references", "commands.md")
+    };
+    // Read the complete source before making changes; an incomplete package must not install a fallback skill.
+    const files = new Map();
+    async function collect(directory, prefix = "") {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const name = join(prefix, entry.name);
+            if (entry.isDirectory())
+                await collect(join(directory, entry.name), name);
+            else if (entry.isFile())
+                files.set(name, await readFile(join(directory, entry.name)));
+        }
     }
-    const bundledSkill = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", "wowdump", "SKILL.md");
-    const skillSource = options.skillSource ? normalizePath(options.skillSource) : fileExists(bundledSkill) ? bundledSkill : undefined;
-    const skillFile = join(skillDirectory, "SKILL.md");
-    await createFileIfMissing(skillFile, `${(skillSource ? await readFile(skillSource, "utf8") : DEFAULT_WOWDUMP_SKILL).replace(/\n?$/, "\n")}`, created, preserved);
-    const referencesDirectory = join(skillDirectory, "references");
-    if (directoryExists(referencesDirectory))
-        preserved.push(referencesDirectory);
-    else {
-        await mkdir(referencesDirectory, { recursive: true });
-        created.push(referencesDirectory);
+    await collect(bundled);
+    if (!files.has("SKILL.md") || !files.has(join("references", "commands.md")))
+        throw new Error("SKILL_BUNDLE_INVALID: required skill files are missing");
+    if (options.skillSource)
+        files.set("SKILL.md", await readFile(normalizePath(options.skillSource)));
+    if (options.commandsSource)
+        files.set(join("references", "commands.md"), await readFile(normalizePath(options.commandsSource)));
+    await mkdir(home, { recursive: true });
+    try {
+        await writeFile(result.configFile, JSON.stringify({ schema: "wowdump.config.v1" }, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+        result.created.push(result.configFile);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        result.preserved.push(result.configFile);
     }
-    const commandsFile = join(referencesDirectory, "commands.md");
-    await createFileIfMissing(commandsFile, `${(options.commandsSource ? await readFile(normalizePath(options.commandsSource), "utf8") : DEFAULT_WOWDUMP_COMMANDS).replace(/\n?$/, "\n")}`, created, preserved);
-    const bundledReferences = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", "wowdump", "references");
-    if (directoryExists(bundledReferences))
-        for (const entry of readdirSync(bundledReferences, { withFileTypes: true }))
-            if (entry.isFile() && extname(entry.name).toLowerCase() === ".md")
-                await createFileIfMissing(join(referencesDirectory, entry.name), await readFile(join(bundledReferences, entry.name), "utf8"), created, preserved);
-    const scriptsDirectory = join(skillDirectory, "scripts");
-    if (directoryExists(scriptsDirectory))
-        preserved.push(scriptsDirectory);
-    else {
-        await mkdir(scriptsDirectory, { recursive: true });
-        created.push(scriptsDirectory);
+    const backupDirectory = join(home, "skill-backups", randomUUID());
+    for (const [name, contents] of files) {
+        const destination = join(skillDirectory, name);
+        let existing;
+        try {
+            existing = await readFile(destination);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (existing?.equals(contents)) {
+            result.preserved.push(destination);
+            continue;
+        }
+        if (existing) {
+            const backup = join(backupDirectory, name);
+            await mkdir(dirname(backup), { recursive: true });
+            await writeFile(backup, existing, { flag: "wx", mode: 0o600 });
+            result.backups.push(backup);
+        }
+        await mkdir(dirname(destination), { recursive: true });
+        const temporary = `${destination}.${randomUUID()}.tmp`;
+        await writeFile(temporary, contents, { flag: "wx", mode: 0o600 });
+        await rename(temporary, destination);
+        (existing ? result.updated : result.created).push(destination);
     }
-    const bundledScripts = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", "wowdump", "scripts");
-    if (directoryExists(bundledScripts))
-        for (const entry of readdirSync(bundledScripts, { withFileTypes: true }))
-            if (entry.isFile() && extname(entry.name).toLowerCase() === ".js")
-                await createFileIfMissing(join(scriptsDirectory, entry.name), await readFile(join(bundledScripts, entry.name), "utf8"), created, preserved);
-    return { home, created, preserved, configFile, skillFile, commandsFile, scriptsDirectory };
+    return result;
+}
+export async function bootstrapToolchain(options = {}) {
+    return { ...await initializeWowdumpHome(options), toolchain: { ready: true, disassembler: "iced-x86" }, installed: [] };
+}
+export function resolveToolchain(options = {}) {
+    return { home: normalizePath(options.home ?? resolveWowdumpHome(options.env ?? process.env, options.userHome)), ready: true, disassembler: "iced-x86" };
 }
-export async function bootstrapToolchain(options = {}) { const home = await initializeWowdumpHome(options); return { ...home, toolchain: { ready: true, disassembler: "iced-x86" }, installed: [] }; }
-export function resolveToolchain(options = {}) { return { home: normalizePath(options.home ?? resolveWowdumpHome(options.env ?? process.env, options.userHome)), ready: true, disassembler: "iced-x86" }; }
-export function inspectPeSections(buffer) { if (buffer.length < 0x40 || buffer.toString("ascii", 0, 2) !== "MZ")
-    return []; const pe = buffer.readUInt32LE(0x3c); if (pe + 24 > buffer.length || buffer.toString("ascii", pe, pe + 4) !== "PE\0\0")
-    return []; const count = buffer.readUInt16LE(pe + 6); const optional = buffer.readUInt16LE(pe + 20); const table = pe + 24 + optional; const out = []; for (let i = 0; i < count; i++) {
-    const off = table + i * 40;
-    if (off + 40 > buffer.length)
-        break;
-    out.push({ name: buffer.subarray(off, off + 8).toString("ascii").replace(/\0+$/, ""), virtualSize: `0x${buffer.readUInt32LE(off + 8).toString(16)}`, rva: `0x${buffer.readUInt32LE(off + 12).toString(16)}`, rawSize: `0x${buffer.readUInt32LE(off + 16).toString(16)}`, rawOffset: `0x${buffer.readUInt32LE(off + 20).toString(16)}` });
-} return out; }
 const invokedFile = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : "";
-if (invokedFile === import.meta.url && process.argv.includes("--postinstall")) {
+if (invokedFile === import.meta.url && process.argv.includes("--postinstall"))
     await bootstrapToolchain();
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowdump",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "WoW native memory analysis CLI with WinDbg CDB evidence, IDA/iced-x86 disassembly, and an elevated reader broker",
   "license": "MIT",
   "repository": {
@@ -44,6 +44,6 @@
   },
   "allowScripts": {
     "koffi@2.16.3": true,
-    "wowdump@0.3.8": true
+    "wowdump@0.3.9": true
   }
 }

package/skills/wowdump/SKILL.md

@@ -17,6 +17,7 @@ description: 使用 wowdump CLI 定位和读取 WoW 原生内存字段，结合
 - [命令参数](references/commands.md)：CLI 用法。
 - [字段定义](references/request-schema.md)：目标含义不明确时。
 - [CDB 使用与退出限制](references/windbg.md)：执行 dump 或 debug 前。
+- [字段挖掘方法与角色属性案例](references/character-stats-case.md)：未知字段、根指针不稳定或静态分析卡住时参考；学习证据链，不照抄地址。
 
 目录统一为 `~/.wowdump/<buildKey>/`：`database/` 保存静态数据库，`runtime/<session>/` 保存本轮证据与候选，`profile/` 保存已确认的持久化接口。Reader 读取 profile。broker 首次 UAC 后复用，空闲 20 分钟退出。
 

package/skills/wowdump/references/character-stats-case.md

@@ -0,0 +1,130 @@
+# 字段挖掘参考：从角色属性案例提炼方法
+
+查询暴击、急速、精通等角色属性时参考。这里记录一次真实调查的方法与反例，不把旧 build 的偏移当成新任务的答案。用户要求全新分析时重新建立证据。
+
+## 这次真正奏效的思路
+
+**从取值代码确认字段，从对象身份确认根，最后用 Reader 验证整条路径。** 找到一个数值或一条当前能读的指针链，只完成了其中一部分。
+
+```text
+目标字段、类型和单位
+  → API 名称 / 注册关系 / getter 的真实取值指令
+  → 对象相对字段偏移 + 转换公式
+  → 可读页内的对象候选 + 多字段独立对照
+  → 对象根的引用、初始化、更新与失效路径
+  → 稳定身份来源 + 固定指针链或动态容器选择规则
+  → candidate profile → 实时 verify → 用户已授权的正式 profile
+```
+
+这不是要求所有任务扫描整个流程。已有匹配 build/hash 且适用的正式 profile 时直接读取；已有哪一层证据，就从缺失的一层继续。具体命令见 [commands.md](commands.md)，静态工具选择见 [disassemble.md](disassemble.md)。
+
+### 给下一次调查的操作要点
+
+1. **字段语义先收敛。** “暴击等级”和“暴击百分比”分开；记录 getter 是直接读取还是有公式转换。没有证明的职业修正系数不擅自补上。
+2. **静态分析提供结构，不代替实时值。** 使用原始 PE 和同 build/hash 的运行时段；优先 IDA MCP，缺少时用 iced-x86 做局部分析。按原 RVA 映射，结合 `.rdata` 名称、类型和 `.pdata` 边界，而不是只看少量 `.text` 字节。函数边界是线索，重叠代码仍需按控制流确认。
+3. **工具的空结果也要验证。** 用一条已知 RIP 相对指令检查解码器输出，再信任批量检索。先证明脚本能找到已知样本，别把接口用错造成的零结果解释成程序没有结构。
+4. **按真实路径解码。** 遇到重叠字节、异常指令密集区，回到有证据的入口和跳转目标。只有证明条件互补且中间不改变相关标志，才把两条同目标条件跳转折叠。中间值不是返回值；指针计算失败时保留失败假设，不凭低位相似宣布成功。
+5. **把值与对象身份绑在一起。** 页可读、数值合理、几个字段相等，支持对象候选；还要找 GUID 或其他稳定身份来源，区分自己、目标、附近同类型对象和旧缓存。CDB 与 Reader 一致证明读取实现一致，角色面板或独立状态变化才补充字段语义证据。
+6. **查根的生命周期，而不是挑最短链。** 查看初始化、查找、插入、删除、扩容和清理路径。遇到容器时，确认容量、步长、键、值及空/删除槽含义；固定结构偏移可以存，哈希槽位、列表序号和本轮对象地址不应伪装成固定结构。
+7. **优先找稳定身份路径。** getter 的快速缓存路径难还原时，继续看缓存未命中分支：它可能显式取得身份并查对象。本次正是从回退分支找到玩家 GUID 来源，避开了未完整还原的缓存指针算法；这是一种可选策略，不代表所有 getter 都有这样的分支。
+8. **验证完整的读取规则。** 用实际 profile 读取，而不只运行临时脚本；保留原始字节、解析值、命令和时间。查表要有上限、唯一命中、对象身份复核和变化检测。普通 Reader 对落盘文件再读一次，确认正式接口确实可用。
+
+### 卡住时如何选下一步
+
+| 现象 | 下一项有效动作 |
+|---|---|
+| API 字符串存在但没有直接 XREF | 检查注册表、间接引用、地址映射及检索器已知样本；名字地址不当函数入口。 |
+| 线性反汇编出现大量异常指令 | 回到调用点/分支目标，分析相关标志位，再解码可达块；不扩大同一错误起点的输出。 |
+| 当前读数正确，隔一会变成零或异常值 | 核对对象身份、根槽和容器变化；不把错误结果解释成属性真的为零。 |
+| 多条链都能到同一个对象 | 查它们所属结构和生命周期；短链、重复命中次数都不等于当前玩家语义。 |
+| 固定槽位失效 | 找键及键的动态来源，按容器规则查找；不只换成新的槽位偏移。 |
+| getter 的缓存解码复杂 | 查缓存未命中/重建路径及其返回的标识，再寻找可读的对象索引。 |
+| verify 成功但含义仍不明 | 分开报告读取、字段语义、根语义和跨进程验证；不自动提升状态。 |
+| 容器中找不到玩家 | 返回未找到；检查索引是否覆盖该状态，必要时继续找更完整索引，不选第一项兜底。 |
+
+每轮调查保留“当前假设 → 使用证据 → 结果 → 下一项能区分假设的检查”。失败后改假设或检查工具，不重复同一无效扫描；需要换装、换角色或重启才能区分时，具体说明要用户配合什么，不把缺少这项验证说成永远找不到。
+
+### 什么进 CLI，什么留在任务里
+
+- CLI 负责通用读取、页查询、有界遍历、类型解析及结构化错误；本次新增的是通用 `root.lookup`，不是写死某个游戏表。
+- 本 build 的 RVA、字段偏移、键布局和证据进 profile；临时检索脚本、dump、失败假设进 runtime session。
+- Skill 负责何时选哪条分析路径及如何判断证据。禁止 Hook/Stalker 的现有约束保持不变；本次成功不依赖它们。
+- 只有发现通用工具缺陷或缺少通用读取表达能力才改框架，不为每次查询改源码。新增能力需测试失败路径，并确认实际使用的 CLI 支持它。
+
+下面保留本次具体过程，便于对照上述判断方法。历史读数和地址仅适用于标注的 build 与证据范围。
+
+## 先找字段含义，再找对象
+
+API 名称所在的只读数据不是 getter 函数。需要沿注册关系、代码引用和真实控制流，确定取值指令、对象来源与字段类型。getter 的函数 RVA 与存放对象指针的全局槽位 RVA 也不是同一个地址；Reader 读取后者，不执行 getter。
+
+线性反汇编遇到重叠指令或混淆分支时，按有证据的跳转目标重新解码。不要把错误路径的算式当成指针算法。本次一条重建算法生成了无效高位、看似正确的低 32 位；低位只能缩小候选范围，页检查和多字段匹配才支持进一步调查。
+
+本次 build `retail@12.1.0.69587` 的静态/运行时证据支持以下对象相对位置：
+
+| 字段 | 对象偏移 | 类型及解释 |
+|---|---|---|
+| 智力 | 0x1f70 | u32，属性点 |
+| 耐力 | 0x1f6c | u32，属性点 |
+| 生命值 | 0x19b8 | u64 |
+| 暴击 | 0x723c | f32，百分比 |
+| 急速倍率 | 0x1ccc | f32；getter 转换为 `100 × (1 / value − 1)` |
+| 精通原始值 | 0x7254 | f32，不等于职业专属精通效果百分比 |
+
+这些不是模块 RVA。全能候选尚未完成语义验证，所以没有混入已核对的字段。
+
+## 有界读取与独立对照
+
+用 VirtualQueryEx 结果限定可读区间，每次读取截断到当前 region 末尾；短读保留错误，不用零填补。多个候选要对照一组字段，而不是只匹配一个常见数值。角色切换可能改变数值，也可能更换对象，需记录观测时刻。
+
+本次 Reader 与一次 CDB 非侵入读取分别得到：智力 2669、耐力 31204、生命值 624080、暴击约 17.391304%、急速倍率约 0.818332613（换算约 22.199700%）、精通原始值约 31.326086。这是历史观测，不是下一次查询的预期常量。
+
+CDB 使用方式和退出限制见 [windbg.md](windbg.md)。本次 `-pd` 曾出现退出码为零但命令未执行；改用 `-pvr` 并以 `qd` 结束后才取得实际读数。必须核对输出标记、读数、超时和目标状态，单凭 exitCode:0 不足以认定成功。此案例没有 Hook，也没有调用未知原生函数。
+
+## 从对象反查根：一次命中不代表稳定
+
+在有界模块数据和候选指针范围内查找引用，保存每个候选槽位及间接偏移。读取较多小块时复用 broker 连接，完成后关闭；本次逐请求建连接曾耗尽临时端口，改为单连接解决。
+
+本次发现的链采用记号 `*[地址]` 表示读取 8 字节指针：
+
+| 候选对象链 | 后续实际复核 |
+|---|---|
+| `*[*[base + 0x61f0110] + 0x28]` | 最初命中玩家，后续指向其他地址；智力、耐力、暴击变成零。排除为已验证玩家根。 |
+| `*[*[base + 0x6288450] + 0x3b8]` | 后续读到零和异常浮点数，排除为已验证玩家根。 |
+| `*[*[base + 0x59c5ec8] + 0x1c8]` | 当时仍匹配六项读数；后续证实是容器槽位，正式方案已改为按 GUID 查表。 |
+| `*[*[base + 0x6202890] + 0x980]` | 后续仍匹配上述六项读数；根语义和跨重启表现待确认。 |
+
+最短链失败时，CLI 仍返回 `verified:true`，因为内存读取完整。这是**读取成功不等于对象正确**的实测反例。不要为了落盘而挑一条偶然匹配的链。
+
+## 如何收敛成 profile
+
+继续分析候选根的读写引用、所属对象和列表选择条件，确认它为何指向当前玩家。把得到的模块 RVA、解引用步骤与字段偏移写入候选，使用同一份 profile 反复读取并对照；允许用户配合换装、换角色或重启验证，但分别记录覆盖范围。
+
+按 [profiles.md](profiles.md) 保存：身份必须匹配，根语义成立，字段经过验证，用户已授权。跨重启尚未验证时明确注明；根语义未成立则保留候选，不放进持久化 profile 目录。固定槽位方案后来被排除，最终采用下节的按玩家 GUID 选对象方案。
+
+## 最终确认：玩家 GUID + 动态查表
+
+后续修正临时检索脚本：iced-x86 的接口是 isIpRelMemoryOperand / ipRelMemoryAddress，先前使用不存在的属性导致空结果；旧 root-static-xrefs.json 因此作废。正确检索找到根的读写引用。
+
+初始化函数 RVA 0x258570、查找函数 0x25e57b0 与类型字符串证明 0x59c5ec8 是 GUID → AIObstacle 表，容量在 0x59c5ec0，步长 0x28，键位于条目 +0，关联对象指针位于 +0x10。旧 +0x1c8 是槽位 11 的值，不是结构常量；表扩容或条目位置变化后不应继续使用。
+
+玩家 getter 的缓存回退路径：0x251dc76 调用 0x251e020，正常分支 0x251e373 跳到 0x1f9dfb0；后者正常分支 0x1f9e1a2 返回 `*[base + 0x7dec228] + 0x10`。此处是当前玩家 16 字节 GUID 的来源，而不是猜测选中目标的全局变量。当前进程四处关键代码字节与静态段相同；该 GUID 和已核对属性对象的 +0x10 GUID 完全一致。
+
+正式 profile 使用 root.lookup：动态读取玩家 GUID，在容量上限内寻找唯一相同键，读取对象指针，再比较对象 GUID；最后复读表根、容量、键和命中条目。找不到玩家或发生变化时返回错误，不退回旧槽位。AIObstacle 表并非已证明覆盖所有游戏状态的完整对象索引，玩家条目缺失应明确报告 LOOKUP_NOT_FOUND。
+
+三轮真实 verify 与落盘后的普通 memory read 均成功，且属性随游戏状态变化。最终文件位于 `~/.wowdump/retail@12.1.0.69587/profile/character-stats.json`，只存模块 RVA 和相对布局。未测试真实重启，因此 restartVerified 保持 false；不要把合成重定位测试描述为真实跨进程测试。
+
+## 本次本机证据索引
+
+以下文件位于 `~/.wowdump/retail@12.1.0.69587/runtime/character-stats-11628/`，不是 npm 包内容。其他机器缺少这些文件时，不将案例当作可执行 profile。
+
+- `candidate-comparison.json`：多候选、面板字段对照。
+- `cdb-current-stats-pvr.json`、`cdb-stats-summary.json`：独立读取结果及限制。
+- `character-stats-profile-verification.json`：会话绝对地址 profile 的 Reader 验证。
+- `root-indirect-scan.json`：模块根候选与间接引用。
+- `root-static-xrefs.json`：已作废的错误检索结果；使用 root-xrefs-corrected.json 和 root-functions-corrected.txt。
+- `candidate.profile.json`、`rva-candidate-verify.json`：最短 RVA 候选及其失败的语义复核。
+- `other-roots-verify.json`：其余三条链的 CLI 参数、原始输出和退出码。
+- `root-59c5ec8.candidate.profile.json`、`local-cli-candidate-verify.json`：修订后的本地 CLI 直接验证 candidate，仍得到六项匹配读数；validation 区分读取与未检查项目，候选状态不变。
+- `player-guid-source-verify.json`：玩家 GUID 与对象 GUID 的实时对照。
+- `current-code-check.json`：当前进程关键代码与静态段的字节比对。
+- `guid-lookup-live-verify.json`、`formal-profile-read.json`：按键查表的三轮 verify，以及正式 profile 的普通 Reader 读取结果。

package/skills/wowdump/references/commands.md

@@ -54,7 +54,7 @@ wowdump database status --build "<buildKey>"
 wowdump analyze runtime --pid <pid> --build "<buildKey>" --kind verify --profile <profile.json> --confirm
 ```
 
-`verify` 只读取 profile 定义的 RVA、指针链和类型，不读取 IDA 数据库或 dump 文件。验证成功并得到用户确认后，才保存到 `~/.wowdump/<buildKey>/profile/`。
+`verify` 接受 candidate 和 reader_ready，执行 profile 的 RVA、指针链、lookup 和类型读取，不读取 IDA 数据库或 dump 文件，也不修改候选状态。validation.read 为 passed 仅表示读取成功；字段语义、根语义和跨进程复用不由该命令认证。补齐相关证据并得到用户确认后，才保存到 `~/.wowdump/<buildKey>/profile/`。
 
 ## Reader
 

package/skills/wowdump/references/evidence-workflow.md

@@ -8,6 +8,6 @@
 
 不要求用户每次都重新配合已有验证；新字段首次建立语义时才补相应证据。输出 evidence 文件包含字段名、来源文件/函数 RVA、假设、原始读数、观测时间、对照值、转换公式及验证状态。多个字段逐个记录，局部成功不代表全部成功。
 
-`analyze runtime --kind verify` 当前只执行 ProfileEngine 读取，返回 `verified:true` 表示读取调用成功；它不做角色面板对照，也不自动证明语义或重启复用。当前 candidate 状态兼容步骤见 [profiles.md](profiles.md)。
+`analyze runtime --kind verify` 返回分项 validation：read 为 passed 表示读取成功，fieldSemantics、rootSemantics、crossProcess 为 not_checked。它不做角色面板对照，不自动证明语义或重启复用，也不修改候选状态。旧版本的 verified:true 同样只代表读取调用成功。候选验证见 [profiles.md](profiles.md)。
 
 dump 的日志、manifest 和段字节属于取证材料；检查每段大小、哈希和 shortRead 后再引用。分析输出中的 RVA、结构偏移、类型和调用关系必须能追溯到这些材料或原始 PE。

package/skills/wowdump/references/profiles.md

@@ -34,11 +34,11 @@
 
 替换为本轮证实的身份、RVA、偏移和类型。直接模块标量无需解引用。数组使用 layout.kind:"array"、item、stride、count；动态计数格式先核对当前 Reader 并设置 maxItems。结构使用 layout.kind:"struct" 和 fields。复杂布局先核对当前实现或验证用例，不自创 schema。
 
-## 当前 verify 状态限制
+## 验证候选
 
-CLI 的 verify 调用同一个 ProfileEngine，要求 readerStatus:"reader_ready"；直接传 candidate 会返回 PROFILE_NOT_READY。
+`analyze runtime --kind verify --profile <file> --confirm` 接受 readerStatus 为 candidate 或 reader_ready；普通 memory read 仍要求 reader_ready。
 
-保留 candidate.profile.json 原件。证据足够进行小范围读取后，在 runtime session 创建 verification-input.profile.json，仅为适配执行门槛设置 readerStatus:"reader_ready"，confidence 与 evidence 仍保持候选。用此副本执行 verify，单独保存 verify.json；状态标签不能证明验证完成。若新版本正式支持 candidate 验证，使用其正式流程。
+直接验证 candidate.profile.json，结果另存 verify.json。命令不修改候选、不提升状态、不自动持久化。validation.read 为 passed 只表示此次读取完成；fieldSemantics、rootSemantics、crossProcess 为 not_checked，需另外补证据。不要为执行验证而先将候选改成 reader_ready。
 
 语义验证见 [evidence-workflow.md](evidence-workflow.md)。验证失败时保留错误和候选状态，不复制到持久化目录。
 
@@ -52,3 +52,22 @@ CLI 的 verify 调用同一个 ProfileEngine，要求 readerStatus:"reader_ready
 buildKey 使用 targets 返回的安全单层目录名。profile 必须带真实 executableSha256；build/hash 不匹配重新分析，缺少哈希不视作匹配。
 
 展示字段、单位、验证范围和绝对路径。用户确认后复制到 profile/<id>.json；已有保存授权直接沿用。覆盖现有文件前确认覆盖范围。未做重启测试时保留限制。profile 不保存 moduleBase、堆绝对地址或 IDA session ID。
+
+### 持久化前检查根指针
+
+- 持久化字段从当前 build 的模块 RVA 出发，随后使用有证据支持的相对偏移和解引用；根 RVA 必须落在对应模块范围内。堆地址减 moduleBase 不会变成模块 RVA。
+- 指针扫描命中只说明某个槽位当时引用该对象。先确认槽位的含义、所属结构和生命周期，排除队列、缓存、目标单位或任意列表项。重复读取与当前对象对照；指针改变后仍可读不代表仍是玩家。
+- 单独记录根语义、字段语义、同会话重读、换角色和跨进程验证。允许明确披露尚未进行的重启测试；根语义尚未确认的扫描命中继续留在 runtime，不凭 reader_ready 或 verified:true 提升为持久化接口。
+- 绝对地址 profile 只适合本轮调查。证据里的历史地址可留在 runtime 文件，持久化 profile 引用该证据路径，不携带其本轮对象地址作为读取根。
+
+具体反例见 [角色属性案例](character-stats-case.md)。这些是保存决策规则，不表示当前 CLI 已自动执行全部检查。
+
+## 按键选择动态表项：root.lookup
+
+根处是表而不是唯一对象时，使用有界键查找，不把本轮槽位编号写进 pointerChain。root.rva/dereference 先解析表地址，lookup 返回匹配表项中的对象指针，随后执行字段的 pointerChain。
+
+lookup 参数：countRoot 和 keyRoot 是普通根定义（rva 或会话 address，可选 dereference），不嵌套 lookup；countType 为 u32（默认）或 u64；keyOffset 是键相对 keyRoot 的偏移；keySize 是比较的原始字节数；stride 是表项步长；entryKeyOffset 是表项内的键偏移（默认 0）；valueOffset 是对象指针偏移；objectKeyOffset 用于核对对象本身的键；maxItems 必须显式提供。偏移使用 0x 字符串，大小和数量使用整数。
+
+单次表读取上限 1 MiB，keySize 上限 64，stride 上限 4096，maxItems 上限 65536；实际容量超限返回 LOOKUP_LIMIT。键为空、没有命中、重复命中、对象键不符分别返回 LOOKUP_KEY_EMPTY、LOOKUP_NOT_FOUND、LOOKUP_AMBIGUOUS、LOOKUP_OBJECT_MISMATCH。选择后复读根、容量、键和命中条目；发现变化返回 LOOKUP_CHANGED，不沿用旧槽位。
+
+这些复核不是进程冻结或原子快照保证；目标持续变化时保留失败证据，有限重试。lookup profile 必须使用 0.3.9 或更新版本 Reader；旧版可能忽略未知参数，不要交给旧 Reader 执行。