wowdump 0.3.3 → 0.3.5

package/dist/core/build-store.js

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, normalize, resolve } from "node:path";
+export function resolveWowdumpHome(env = process.env, userHome = homedir()) {
+    return normalize(resolve(env.WOWDUMP_HOME || join(userHome, ".wowdump")));
+}
+export function safeBuildKey(buildKey) {
+    const value = buildKey.trim();
+    if (!value || value === "." || value === ".." || !/^[A-Za-z0-9_.@-]+$/.test(value))
+        throw new Error("build key contains unsupported path characters");
+    return value;
+}
+export function buildDirectory(home, buildKey) {
+    return join(resolve(home), safeBuildKey(buildKey));
+}
+export function buildPaths(home, buildKey) {
+    const build = buildDirectory(home, buildKey);
+    const database = join(build, "database");
+    return {
+        root: resolve(home),
+        build,
+        database,
+        databaseFile: join(database, "database.json"),
+        databaseLock: join(database, "database.lock"),
+        ida: join(database, "ida"),
+        profile: join(build, "profile"),
+        runtime: join(build, "runtime")
+    };
+}
+export async function sha256File(file) {
+    return new Promise((resolveHash, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(file);
+        stream.on("data", chunk => hash.update(chunk));
+        stream.once("error", reject);
+        stream.once("end", () => resolveHash(hash.digest("hex")));
+    });
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeJson(file, value) {
+    await mkdir(resolve(file, ".."), { recursive: true });
+    await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+export async function readBuild(home, buildKey) {
+    return readJson(join(buildDirectory(home, buildKey), "build.json"));
+}
+export async function readDatabase(home, buildKey) {
+    return readJson(buildPaths(home, buildKey).databaseFile);
+}
+async function ensureBuildUnlocked(home, input) {
+    const paths = buildPaths(home, input.buildKey);
+    await mkdir(paths.profile, { recursive: true });
+    await mkdir(paths.ida, { recursive: true });
+    await mkdir(paths.runtime, { recursive: true });
+    const now = new Date().toISOString();
+    const oldBuild = await readJson(join(paths.build, "build.json"));
+    const oldDatabase = await readJson(paths.databaseFile);
+    const sameIdentity = Boolean(oldBuild && oldDatabase
+        && oldBuild.executableSha256 === input.executableSha256
+        && oldBuild.preferredImageBase === input.preferredImageBase
+        && oldBuild.moduleSize === input.moduleSize
+        && oldDatabase.executableSha256 === input.executableSha256
+        && oldDatabase.preferredImageBase === input.preferredImageBase
+        && oldDatabase.moduleSize === input.moduleSize);
+    const build = {
+        schema: "wowdump.build.v1",
+        ...input,
+        createdAt: oldBuild?.createdAt ?? now,
+        updatedAt: now
+    };
+    const database = {
+        schema: "wowdump.database.v1",
+        buildKey: input.buildKey,
+        executableSha256: input.executableSha256,
+        preferredImageBase: input.preferredImageBase,
+        moduleSize: input.moduleSize,
+        idaDatabase: join(paths.ida, "Wow.i64"),
+        idaVersion: oldDatabase?.idaVersion ?? null,
+        status: sameIdentity ? (oldDatabase?.status ?? "creating") : oldDatabase ? "stale" : "creating",
+        createdAt: oldDatabase?.createdAt ?? now,
+        updatedAt: now,
+        lastAnalysisAt: oldDatabase?.lastAnalysisAt ?? null
+    };
+    await writeJson(join(paths.build, "build.json"), build);
+    await writeJson(paths.databaseFile, database);
+    return { build, database, reused: sameIdentity && database.status === "ready" };
+}
+export async function ensureBuild(home, input) {
+    const release = await acquireDatabaseLock(home, input.buildKey);
+    try {
+        return await ensureBuildUnlocked(home, input);
+    }
+    finally {
+        await release();
+    }
+}
+export async function markDatabaseReady(home, buildKey, patch = {}) {
+    const current = await readDatabase(home, buildKey);
+    if (!current)
+        throw new Error(`database for ${buildKey} does not exist`);
+    const database = { ...current, ...patch, status: "ready", updatedAt: new Date().toISOString(), lastAnalysisAt: new Date().toISOString() };
+    await writeJson(buildPaths(home, buildKey).databaseFile, database);
+    return database;
+}
+export async function acquireDatabaseLock(home, buildKey) {
+    const paths = buildPaths(home, buildKey);
+    await mkdir(paths.database, { recursive: true });
+    let handle;
+    try {
+        handle = await open(paths.databaseLock, "wx");
+    }
+    catch (error) {
+        throw new Error(`database is locked: ${paths.databaseLock}`, { cause: error });
+    }
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
+    return async () => {
+        await handle.close().catch(() => undefined);
+        await rm(paths.databaseLock, { force: true }).catch(() => undefined);
+    };
+}
+export async function databaseStatus(home, buildKey) {
+    const paths = buildPaths(home, buildKey);
+    const [build, loadedDatabase, lock] = await Promise.all([
+        readJson(join(paths.build, "build.json")),
+        readJson(paths.databaseFile),
+        stat(paths.databaseLock).then(() => true).catch(() => false)
+    ]);
+    let database = loadedDatabase;
+    if (database && database.status === "creating" && await stat(database.idaDatabase).then(() => true).catch(() => false)) {
+        database = { ...database, status: "ready", updatedAt: new Date().toISOString(), lastAnalysisAt: database.lastAnalysisAt ?? new Date().toISOString() };
+        if (!lock)
+            await writeJson(paths.databaseFile, database);
+    }
+    return { ok: true, buildKey: safeBuildKey(buildKey), buildDirectory: paths.build, databasePath: paths.databaseFile, exists: Boolean(database), locked: lock, build, database };
+}
+export async function findReusableDump(home, buildKey, criteria) {
+    const runtime = buildPaths(home, buildKey).runtime;
+    let sessions;
+    try {
+        sessions = await readdir(runtime, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    for (const session of sessions.filter(item => item.isDirectory())) {
+        const manifestFile = join(runtime, session.name, "dump", "manifest.json");
+        const manifest = await readJson(manifestFile);
+        if (!manifest || typeof manifest.moduleBase !== "string" || JSON.stringify(manifest.dumpParameters ?? null) !== JSON.stringify(criteria))
+            continue;
+        return { ...manifest, manifestFile };
+    }
+    return null;
+}

package/dist/core/profile-engine.js

@@ -143,6 +143,15 @@ export class ProfileEngine {
         if (request.buildKey && request.buildKey !== buildKey) {
             throw new ProfileEngineError("BUILD_MISMATCH", `profile build ${buildKey} does not match ${request.buildKey}`);
         }
+        if (request.executableSha256) {
+            const executable = profile.executable && typeof profile.executable === "object" && !Array.isArray(profile.executable)
+                ? profile.executable
+                : undefined;
+            const profileHash = typeof profile.executableSha256 === "string" ? profile.executableSha256 : String(executable?.sha256 ?? "");
+            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 });

package/dist/frida-worker.js

@@ -1,6 +1,8 @@
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { FridaCommandRuntime } from "./analysis/frida-runtime.js";
+import { RuntimeDumpWriter } from "./analysis/runtime-dump.js";
+import { isAbsolute, resolve } from "node:path";
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -15,7 +17,7 @@ function positive(value, name) {
  * GumJS source; this process only attaches, loads, calls, and cleans it up.
  */
 async function run(input) {
-    if (input.command !== "dynamic-script")
+    if (input.command !== "dynamic-script" && input.command !== "runtime-dump")
         throw new Error("unsupported worker command");
     const pid = positive(input.pid, "pid");
     const buildKey = String(input.build ?? input.buildKey ?? "").trim();
@@ -29,24 +31,74 @@ async function run(input) {
     const runtime = new FridaCommandRuntime({ artifactDir: process.env.WOW_ANALYZE_DIR });
     let sessionId;
     let loaded = false;
+    const isDump = input.command === "runtime-dump";
+    const outputDirectory = isDump ? resolve(String(input.outputDir ?? "")) : undefined;
+    const outputDirectoryInput = isDump ? String(input.outputDir ?? "") : "";
+    const writer = isDump ? new RuntimeDumpWriter({
+        outputDirectory: outputDirectory,
+        buildKey,
+        pid,
+        executableSha256: typeof input.executableSha256 === "string" ? input.executableSha256 : null,
+        preferredImageBase: typeof input.preferredImageBase === "string" ? input.preferredImageBase : null,
+        moduleSize: Number.isSafeInteger(Number(input.moduleSize)) ? Number(input.moduleSize) : null,
+        dumpParameters: input.dumpParameters && typeof input.dumpParameters === "object" ? input.dumpParameters : undefined
+    }) : undefined;
+    let finalized = false;
     try {
+        if (isDump) {
+            if (!outputDirectoryInput || !isAbsolute(outputDirectoryInput))
+                throw new Error("runtime dump outputDir must be an absolute path");
+            await writer.initialize();
+        }
         const attached = await runtime.execute({ operation: "attach", pid, buildKey, allowUnmatched: true });
         sessionId = String(attached.sessionId);
         const modules = await runtime.execute({ operation: "modules", sessionId, pid, buildKey });
         const module = Array.isArray(modules.modules)
             ? modules.modules.find(item => String(item.name ?? "").toLowerCase() === "wow.exe")
             : undefined;
+        const scriptSource = `globalThis.__WOWDUMP_INPUT__ = Object.freeze(${JSON.stringify(input.args ?? {})});\n${source}`;
+        let value;
+        let messages = [];
+        if (isDump) {
+            await writeFile(resolve(outputDirectory, "..", "target.json"), `${JSON.stringify({ schema: "wowdump.runtime-target.v1", pid, buildKey, module, executableSha256: input.executableSha256 ?? null, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8").catch(() => undefined);
+            let progressBytes = 0;
+            const streamed = await runtime.streamScriptCall({
+                operation: "script_load",
+                sessionId,
+                pid,
+                buildKey,
+                source: scriptSource,
+                exportName: typeof input.exportName === "string" ? input.exportName : "collect"
+            }, undefined, async (message, data) => {
+                const envelope = message && typeof message === "object" ? message : {};
+                if (envelope.type !== "send" || !data)
+                    return;
+                const payload = envelope.payload && typeof envelope.payload === "object" ? envelope.payload : {};
+                if (payload.type !== "wowdump.dump.chunk")
+                    return;
+                await writer.writeChunk(payload, data);
+                progressBytes += data.byteLength;
+                if (input.progress !== false)
+                    process.stderr.write(`wowdump dump ${progressBytes} bytes\\n`);
+            });
+            value = streamed.value;
+            const result = value && typeof value === "object" ? value : {};
+            if (result.ok !== true)
+                throw new Error(String(result.error ?? "runtime dump failed"));
+            const persisted = await writer.finalize({ ...result, module: module ?? result.module });
+            finalized = true;
+            await writeFile(resolve(outputDirectory, "..", "dynamic.json"), `${JSON.stringify({ ...result, manifestFile: persisted.manifestFile, generatedAt: new Date().toISOString() }, null, 2)}\n`, "utf8").catch(() => undefined);
+            return { ok: true, command: "analyze.runtime.dump", pid, buildKey, manifestFile: persisted.manifestFile, outputDirectory, manifest: persisted.manifest, sections: persisted.sections };
+        }
         await runtime.execute({
             operation: "script_load",
             sessionId,
             pid,
             buildKey,
-            source: `globalThis.__WOWDUMP_INPUT__ = Object.freeze(${JSON.stringify(input.args ?? {})});\n${source}`,
+            source: scriptSource,
             scriptId: "dynamic"
         });
         loaded = true;
-        let value;
-        let messages = [];
         if (typeof input.exportName === "string" && input.exportName.trim()) {
             const called = await runtime.execute({
                 operation: "script_call",
@@ -79,6 +131,8 @@ async function run(input) {
     finally {
         if (sessionId && loaded)
             await runtime.execute({ operation: "script_unload", sessionId, scriptId: "dynamic" }).catch(() => undefined);
+        if (isDump && writer && !finalized)
+            await writer.abort().catch(() => undefined);
         await runtime.close();
     }
 }

package/dist/reader/broker.js

@@ -5,6 +5,9 @@ export const DEFAULT_RIGHTS = Object.freeze([
     "PROCESS_QUERY_INFORMATION",
     "PROCESS_VM_READ"
 ]);
+const MEM_COMMIT = 0x1000;
+const DEFAULT_QUERY_END = BigInt("0x7fffffffffff");
+const MAX_QUERY_REGIONS = 100_000;
 function hexAddress(value) {
     const normalized = value.trim();
     if (!/^0x[0-9a-f]+$/i.test(normalized)) {
@@ -30,6 +33,15 @@ function boundedPid(value) {
     }
     return pid;
 }
+function boundedCount(value, name, maximum, fallback) {
+    if (value === undefined)
+        return fallback;
+    const count = Number(value);
+    if (!Number.isSafeInteger(count) || count < 1 || count > maximum) {
+        throw new ReaderProtocolError("INVALID_COUNT", `${name} must be an integer between 1 and ${maximum}`);
+    }
+    return count;
+}
 function toHex(bytes) {
     return Buffer.from(bytes).toString("hex");
 }
@@ -169,6 +181,8 @@ export class ReaderBroker {
                 return this.runFrida(request);
             case "modules":
                 return this.modules(request);
+            case "regions":
+                return this.regions(request);
             case "open":
                 return this.open(request);
             case "close":
@@ -255,6 +269,63 @@ export class ReaderBroker {
         }
         return { pid, modules: await this.backend.enumerateModules(pid) };
     }
+    async regions(request) {
+        if (!this.backend.virtualQueryEx) {
+            throw new ReaderProtocolError("VIRTUAL_QUERY_UNAVAILABLE", "native VirtualQueryEx backend is not installed");
+        }
+        const pid = boundedPid(request.pid);
+        const start = hexAddress(request.start ?? "0x0");
+        const end = hexAddress(request.end ?? `0x${DEFAULT_QUERY_END.toString(16)}`);
+        if (end < start)
+            throw new ReaderProtocolError("INVALID_RANGE", "end must be greater than or equal to start");
+        const maxRegions = boundedCount(request.maxRegions, "maxRegions", MAX_QUERY_REGIONS, 4096);
+        const includeFree = request.includeFree === true;
+        const handle = await this.getHandle(pid, request.handle);
+        const regions = [];
+        let cursor = start;
+        let truncated = false;
+        while (cursor <= end) {
+            const raw = await this.backend.virtualQueryEx(handle, cursor);
+            const baseAddress = hexAddress(String(raw.baseAddress ?? "0x0"));
+            let regionSize;
+            try {
+                regionSize = BigInt(String(raw.regionSize ?? "0"));
+            }
+            catch {
+                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx returned an invalid region size");
+            }
+            if (regionSize <= 0n)
+                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx returned a non-positive region size");
+            const next = baseAddress + regionSize;
+            if (next <= cursor)
+                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx did not advance the query address");
+            const state = Number(raw.state);
+            if (includeFree || state === MEM_COMMIT) {
+                regions.push({
+                    ...raw,
+                    baseAddress: `0x${baseAddress.toString(16)}`,
+                    regionSize: regionSize.toString(),
+                    committed: state === MEM_COMMIT
+                });
+            }
+            cursor = next;
+            if (regions.length >= maxRegions) {
+                truncated = cursor <= end;
+                break;
+            }
+        }
+        return {
+            pid,
+            handle: handle.id,
+            start: `0x${start.toString(16)}`,
+            end: `0x${end.toString(16)}`,
+            includeFree,
+            maxRegions,
+            regions,
+            nextAddress: `0x${cursor.toString(16)}`,
+            truncated
+        };
+    }
     async watchStart(request) {
         const pid = boundedPid(request.pid);
         const address = hexAddress(request.address);

package/dist/toolchain.js

@@ -1,29 +1,28 @@
-import { createHash } from "node:crypto";
-import { createReadStream, readdirSync, statSync } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { pipeline } from "node:stream/promises";
-export const WOWDUMP_HOME_DIRECTORIES = ["profiles", "logs", "runtime", "cache", "skills", "monitors", "toolchains"];
+import { resolveWowdumpHome } from "./core/build-store.js";
 export const DEFAULT_WOWDUMP_SKILL = `---
 name: wowdump
-description: 使用 Frida 运行时证据和 IDA/iced-x86 定位 WoW 字段，生成 Reader 可用 profile。
+description: 用 Frida 运行时证据和 IDA Pro MCP 或 iced-x86 定位 WoW 字段，生成并验证 Reader profile。
 ---
 
 # wowdump
 
-查字段时先读取 targets，再用显式 GumJS 导出运行时线索。静态定位优先交给可用的 IDA Pro MCP；没有时运行 \`wowdump analyze disassemble\`，由 Agent 根据 iced-x86 输出分析并补齐字段定义。两条路径都必须最终生成 \`wowdump.profile.v1\`，且只有地址、类型和证据齐全时才标记 \`reader_ready\`。详情见 references/workflow.md、references/dynamic.md、references/disassemble.md 和 references/profiles.md。
+先运行 \`wowdump targets\`，再复用 \`~/.wowdump/<buildKey>/database/\`。动态脚本必须由 Agent 显式提供；runtime dump 保存当前 session 的二进制证据，Reader 只读取 build profile。详情见 references/workflow.md、references/commands.md、references/dynamic.md、references/disassemble.md 和 references/profiles.md。
 `;
 export const DEFAULT_WOWDUMP_COMMANDS = `# wowdump 命令参考
 
 1. \`wowdump targets\`
-2. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind dump --confirm\`
-3. \`wowdump analyze dynamic --pid <pid> --build <buildKey> --script <GumJS> --export collect --confirm\`
-4. \`wowdump analyze disassemble --exe <Wow.exe> --build <buildKey> --runtime-export <runtime.json> --output <profile.json>\`
-5. \`wowdump memory read --pid <pid> --build <buildKey> --profile <profile.json> --field <name>\`
+2. \`wowdump database status --build <buildKey>\`
+3. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind dump --confirm\`
+4. \`wowdump analyze dynamic --pid <pid> --build <buildKey> --script <GumJS> --export collect --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\` 需要 \`--profile\`，只验证已有候选 RVA。若 Agent 能调用 IDA Pro MCP，先用 MCP 分析 dump manifest 指向的段，再把结果保存为 JSON 并通过 \`--ida-evidence\` 交给 disassemble 命令。未确认的候选 profile 放在 runtime 目录；确认后才复制到当前 build 的 profile 目录。
+\`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 {
@@ -48,7 +47,7 @@ catch (error) {
     else
         throw error;
 } }
-export function resolveWowdumpHome(env = process.env, userHome = homedir()) { return normalizePath(env.WOWDUMP_HOME || join(userHome, ".wowdump")); }
+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 async function initializeWowdumpHome(options = {}) {
     const env = options.env ?? process.env;
@@ -56,15 +55,6 @@ export async function initializeWowdumpHome(options = {}) {
     const created = [];
     const preserved = [];
     await mkdir(home, { recursive: true });
-    for (const name of WOWDUMP_HOME_DIRECTORIES) {
-        const dir = join(home, name);
-        if (directoryExists(dir))
-            preserved.push(dir);
-        else {
-            await mkdir(dir, { recursive: true });
-            created.push(dir);
-        }
-    }
     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");
@@ -108,7 +98,6 @@ export async function initializeWowdumpHome(options = {}) {
 }
 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 async function sha256File(file) { const hash = createHash("sha256"); await pipeline(createReadStream(file), hash); return hash.digest("hex"); }
 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++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowdump",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "WoW native memory analysis CLI with Frida evidence, IDA/iced-x86 disassembly, and an elevated reader broker",
   "license": "MIT",
   "repository": {

package/skills/wowdump/SKILL.md

@@ -5,20 +5,22 @@ description: 以 Frida 运行时探测为主，按证据需要交替使用 IDA P
 
 # wowdump
 
-用于读取角色属性、Buff/Debuff、技能冷却、附近单位等原生字段。优先从当前进程取得真实值；需要长期复用时，再把已验证的线索固化为带证据的 `wowdump.profile.v1`。
+用于读取角色属性、Buff/Debuff、技能冷却、附近单位等原生字段。每个 build 有一个静态数据库，运行时证据按 session 保存，Reader 只读取已验证的 profile。
 
 ## 默认策略
 
-1. 先运行 `wowdump targets`，确认 PID、Wow.exe 路径和 buildKey；多个目标时让用户选择。
-2. 在 `~/.wowdump/<buildKey>/runtime/<session>/` 保存临时证据，在 `~/.wowdump/<buildKey>/profile/` 只保存用户确认的持久化 profile。
-3. 默认编写并显式传入 GumJS，使用 `wowdump analyze dynamic --script <GumJS> --confirm` 做运行时发现、原生 Hook、快照或事件采集。
-4. 若已有 `reader_ready` profile，先用 reader 读取；若动态结果已足够回答问题，直接返回，不强行做静态分析。
-5. 动态结果需要函数 RVA、对象布局或字段类型时，先用 `wowdump analyze runtime --kind dump` 导出 `.text`、`.rdata`、`.data`、`.pdata` 和 manifest，再调用 IDA Pro MCP；没有 IDA 时才用 iced-x86 输出。静态和动态可以交替执行，每轮只扩大当前字段所需的证据范围。
-6. 将确认的 RVA、指针链、类型、边界和证据写入候选 profile。字段证据不足时保持 `candidate`，回到 dynamic 补采样或回到 IDA/iced 缩小候选。
-7. 用 `wowdump analyze runtime --kind verify --profile <profile> --confirm` 或 `wowdump memory read --profile <profile> --field <name>` 做 broker-backed 验证；只有地址、类型和实际读取都成功后才标记 `reader_ready`。经用户确认后再保存到该 build 的 `profile/`。
+1. 先运行 `wowdump targets`，确认 PID、Wow.exe 路径、哈希和 buildKey；多个目标时让用户选择。该命令会创建或复用 `~/.wowdump/<buildKey>/database/`。
+2. 先检查 `wowdump database status --build <buildKey>`。同一可执行文件哈希、首选 image base 和模块大小时复用已有 IDA 数据库；哈希变化时数据库为 `stale`。
+3. 有 `reader_ready` profile 时先用 `wowdump memory read --pid <pid> --build <buildKey> --profile <profile> --field <name>`；Reader 不读取 IDA 数据库、dump 二进制或 runtime JSON。
+   需要定位堆或确认可读范围时，先用 `wowdump memory regions --pid <pid> --start <hex> --end <hex>` 枚举 `VirtualQueryEx` 返回的已提交区，再用同一 broker 做有界 `memory read`；默认不包含 free/reserved 区。
+4. 没有可用 profile 时，由 Agent 编写并显式传入 GumJS：`wowdump analyze dynamic --pid <pid> --build <buildKey> --script <GumJS> --confirm`。脚本可做快照、有限 Hook 和事件采集。
+5. 动态线索需要静态证据时运行 `wowdump analyze runtime --kind dump`。dump 只写当前 session 的 `.text/.rdata/.pdata`，`.data` 通过 `--sections` 按需加入；不创建新的静态数据库。
+6. 优先让 IDA Pro MCP 打开该 build 的 `database/ida/Wow.i64`，按 manifest 将 runtime overlay 映射到原始 Wow.exe，输出函数 RVA、字符串 RVA、XREF、结构偏移和字段类型。没有 IDA MCP 时，用 iced-x86 对相关范围局部反汇编。
+7. 将静态结果和动态证据合并为 runtime session 下的 `candidate.profile.json`，只保存 RVA/相对偏移，不保存绝对地址。
+8. 用 `wowdump analyze runtime --kind verify --profile <candidate> --confirm` 做 broker 实读；确认 build/hash、地址、类型、边界和读取值一致后，才把 profile 复制到 `~/.wowdump/<buildKey>/profile/`。
 
 不要把 dynamic、IDA 或 iced 固定成一次性线性流水线。选择下一步的依据是当前字段缺少什么证据：值用 dynamic，函数/布局用 IDA/iced，稳定读取用 reader。
 
-具体的交替决策见 [references/workflow.md](references/workflow.md)；动态 Hook 规则见 [references/dynamic.md](references/dynamic.md)；IDA/iced 的选择和交替策略见 [references/disassemble.md](references/disassemble.md)；请求字段和 profile 生命周期见 [references/request-schema.md](references/request-schema.md) 与 [references/profiles.md](references/profiles.md)。
+具体决策见 [references/workflow.md](references/workflow.md)；命令参数见 [references/commands.md](references/commands.md)；动态 Hook 规则见 [references/dynamic.md](references/dynamic.md)；IDA/iced 规则见 [references/disassemble.md](references/disassemble.md)；请求字段和 profile 生命周期见 [references/request-schema.md](references/request-schema.md) 与 [references/profiles.md](references/profiles.md)。
 
 IDA MCP 使用长 TTL 会话（默认 `idle_ttl_sec: 3600`）。每次查询前先做 health probe；出现 `worker not reachable` 时按 `references/disassemble.md` 重新打开并只重试一次。IDA worker 与 Windows broker 独立，broker 的 UAC 复用不会保持 IDA worker 存活。

package/skills/wowdump/references/commands.md

@@ -21,21 +21,29 @@ wowdump analyze dynamic `
   --export collect `
   --args '{"fields":["playerAuras","nearbyEnemies","cooldowns"]}' `
   --duration-ms 5000 `
-  --confirm > $HOME\.wowdump\runtime\<session-id>\state.json
+  --confirm
 ```
 
-导出供静态分析的运行时模块段：
+CLI 会把结果保存到 `~/.wowdump/<buildKey>/runtime/<session-id>/dynamic.json`，并在 stdout 返回 session 目录。
+
+导出供静态分析的运行时模块段。默认只导出 `.text/.rdata/.pdata`；需要运行时全局状态时显式加入 `.data`：
 
 ```powershell
 wowdump analyze runtime `
   --pid 33976 `
   --build "retail@12.1.0.69587" `
   --kind dump `
-  --output-dir "$HOME\.wowdump\retail@12.1.0.69587\runtime\dump-01" `
+  --sections .text .rdata .pdata `
   --confirm
 ```
 
-输出目录中包含 `manifest.json` 和 `.text`、`.rdata`、`.data`、`.pdata` 二进制段。stdout 只返回 manifest 路径和摘要，不打印整段十六进制。
+输出写入 `~/.wowdump/<buildKey>/runtime/<session-id>/dump/`，包含 `manifest.json` 和二进制段文件。Frida 按块发送，worker 直接写盘；stdout 只返回 manifest 路径、段摘要、字节数和 SHA-256，不打印 Base64 或整段十六进制。相同 build 哈希、段选择和限制参数会复用已有 manifest。
+
+查看静态数据库状态：
+
+```powershell
+wowdump database status --build "retail@12.1.0.69587"
+```
 
 验证已有候选 profile：
 
@@ -50,16 +58,12 @@ wowdump analyze runtime `
 
 `verify` 不负责发现地址；没有 profile 时会直接提示缺少验证目标。
 
-## 需要时做静态定位
+## 静态定位
 
-只有 dynamic 结果缺少函数 RVA、对象布局或字段类型时，才调用 IDA Pro MCP；没有 IDA 时使用 iced-x86 兜底：
+只有 dynamic 结果缺少函数 RVA、对象布局或字段类型时，才调用 IDA Pro MCP。优先复用 `~/.wowdump/<buildKey>/database/ida/Wow.i64`；runtime manifest 只作为 overlay 证据，不作为独立程序导入。没有 IDA MCP 时使用 iced-x86 对 manifest 指向的局部范围兜底。静态结果保存到当前 session 的 `ida-evidence.json`，候选 profile 保存到 `candidate.profile.json`。
 
 ```powershell
-wowdump analyze disassemble `
-  --exe "D:\Game\World of Warcraft\_retail_\Wow.exe" `
-  --build "retail@12.1.0.69587" `
-  --runtime-export "$HOME\.wowdump\runtime\<session-id>\state.json" `
-  --output "$HOME\.wowdump\runtime\<session-id>\retail-12.1.0.69587.profile.json"
+IDA MCP 或 iced-x86 的输出至少包含：函数 RVA、字符串 RVA、XREF、结构偏移、字段类型、调用关系和证据来源。
 ```
 
 ## 读取
@@ -74,4 +78,16 @@ wowdump memory read `
 
 需要连续观察时使用 `memory watch start/poll/stop`。字段未定义、模块不匹配、指针为空或发生短读时，保留 JSON 证据并停止该字段，不改写 profile。
 
+需要枚举目标进程的虚拟内存布局时使用 `memory regions`。它通过同一个管理员 broker 调用 Windows `VirtualQueryEx`，默认只返回 `MEM_COMMIT` 区域；查询有地址范围和数量上限，不会把整片地址空间读入内存：
+
+```powershell
+wowdump memory regions `
+  --pid 33976 `
+  --start 0x15000000000 `
+  --end 0x15400000000 `
+  --max-regions 20000
+```
+
+需要诊断空闲/保留区时显式加入 `--include-free`。输出包含 `baseAddress`、`regionSize`、`state`、`protect`、`type` 和 `committed`，可将已提交的 heap 区域交给后续只读扫描。
+
 静态分析完成后回到 `analyze dynamic` Hook 验证候选，再生成 profile。短时 Hook/事件采集可以复制 [scripts/dynamic-session.js](../scripts/dynamic-session.js) 后按请求修改；它不会被 CLI 自动执行。详细脚本规则见 [dynamic.md](dynamic.md) 和 [disassemble.md](disassemble.md)。字段请求格式见 [request-schema.md](request-schema.md)，profile 生命周期见 [profiles.md](profiles.md)。

package/skills/wowdump/references/disassemble.md

@@ -1,6 +1,6 @@
 # 反汇编与 IDA Pro 分支
 
-静态分析是按需使用的证据放大器，不是每个查询的必经步骤。需要静态证据时，先用 `wowdump analyze runtime --kind dump` 导出运行时 `.text`、`.rdata`、`.data`、`.pdata` 以及 manifest；运行时字节样本、Hook 调用记录或返回值也可以作为输入。先检查当前 Agent 是否能调用本机 IDA Pro MCP：
+静态分析是按需使用的证据放大器，不是每个查询的必经步骤。需要静态证据时，先用 `wowdump analyze runtime --kind dump` 导出运行时 `.text`、`.rdata`、`.pdata` 以及 manifest；`.data` 只有在字段需要运行时全局状态时才通过 `--sections` 加入。原始 Wow.exe 始终是 IDA 的主输入，runtime 二进制只是 overlay 证据。先检查当前 Agent 是否能调用本机 IDA Pro MCP：
 
 ## IDA Pro MCP 下载与安装
 
@@ -47,16 +47,6 @@ IDA 的 headless worker 不是常驻进程。`idb_list` 中仍有 session 记录
 4. 第二次仍失联时停止扩大分析范围，保存已取得的 JSON 证据并转用 iced-x86 或请求用户稍后重试。
 
 不要把 `session_id`、IDA 临时 worker PID 或 `0x140000000` 这类 IDA image base 写入持久化 profile。profile 只保存相对模块的 RVA、字段类型和可复核证据。IDA MCP 会话和 wowdump 的 Windows broker 是两条独立链路：前者负责反汇编，后者负责管理员内存读取；broker 复用不会延长 IDA worker 生命周期。
-- IDA 不可用时执行：
-
-```powershell
-wowdump analyze disassemble `
-  --exe "C:\Games\World of Warcraft\_retail_\Wow.exe" `
-  --build "retail@VERSION" `
-  --runtime-export "$HOME\.wowdump\retail@VERSION\runtime\SESSION\state.json" `
-  --output "$HOME\.wowdump\runtime\SESSION\candidate.profile.json"
-```
-
-CLI 使用 `iced-x86` 解码 runtime 样本，返回模块基址、RVA、指令文本、PE sections 和证据。Agent 负责把这些线索与运行时字段对应起来，再用 dynamic 验证 `root`、`pointerChain`、`layout/type`、计数上限和停止条件。不要把一次运行的绝对地址写进持久化 profile。
+- IDA 不可用时，Agent 使用 npm 内置的 `iced-x86` 对 manifest 指向的局部 RVA 反汇编，输出模块 RVA、指令文本、访问偏移和证据。Agent 负责把这些线索与运行时字段对应起来，再用 dynamic 验证 `root`、`pointerChain`、`layout/type`、计数上限和停止条件。不要把一次运行的绝对地址写进持久化 profile。
 
 输出中的 `readerStatus: "reader_ready"` 只适用于每个字段都有可验证 RVA/地址、类型和边界，并且 reader 实际读成功的情况；否则保持 `candidate`，回到 dynamic 或继续局部静态分析。只做一次性查询时可以不生成持久化 profile。