wowdump 0.3.2 → 0.3.3

package/README.md

@@ -14,19 +14,19 @@ wowdump init
 ## 基本流程
 
 ```powershell
-# 1. 导出运行时模块或 provider
-wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind text --duration-ms 5000 --max-events 100 --confirm > runtime.json
+# 1. 导出运行时模块段
+wowdump analyze runtime --pid 1234 --build "retail@VERSION" --kind dump --confirm
 
-# 2. 通过 IDA Pro MCP（若可用）或 iced-x86 局部反汇编生成 profile
-wowdump analyze disassemble --exe "C:\Games\World of Warcraft\_retail_\Wow.exe" --build "retail@VERSION" --runtime-export "$HOME\.wowdump\runtime\<session-id>\text.json" --output "$HOME\.wowdump\runtime\<session-id>\candidate.profile.json"
+# 2. 用 IDA Pro MCP（若可用）或 iced-x86 分析 dump-<id>\manifest.json，保存字段候选和证据
+# 3. 将候选证据交给 profile 生成步骤，再用 reader 验证
 
-# 3. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
+# 4. 用户确认后，把 profile 保存到当前 build 的 profile 目录，再读取
 wowdump memory read --pid 1234 --profile "$HOME\.wowdump\retail@VERSION\profile\player-state.json" --field playerAuras
 ```
 
 Windows reader 首次使用时由 Node 请求 UAC 启动 broker，后续调用复用同一 broker，空闲 20 分钟后退出。Frida 运行时导出需要显式 `--confirm`；高开销 Stalker 默认关闭。
 
-当前 build 的持久化 profile 放在 `~/.wowdump/<buildKey>/profile/`；动态导出、静态候选和验证报告放在 runtime 会话临时目录。完整字段和 JSON 约定见 `~/.agents/skills/wowdump/references/commands.md`、`references/request-schema.md` 与 `references/profiles.md`；短时 Hook 示例见 `~/.agents/skills/wowdump/scripts/dynamic-session.js`。
+`analyze runtime --kind dump` 会把 `.text`、`.rdata`、`.data` 和 `.pdata` 导出为二进制文件，并写入 `manifest.json`；manifest 供 IDA Pro MCP 或 iced-x86 使用。`analyze runtime --kind verify --profile <file>` 只验证已有 profile 的 RVA。当前 build 的持久化 profile 放在 `~/.wowdump/<buildKey>/profile/`；动态导出、静态候选和验证报告放在 runtime 会话临时目录。完整字段和 JSON 约定见 `~/.agents/skills/wowdump/references/commands.md`、`references/request-schema.md` 与 `references/profiles.md`；短时 Hook 示例见 `~/.agents/skills/wowdump/scripts/dynamic-session.js`。
 
 ## 开发验证
 

package/dist/analysis/runtime-script.js

@@ -1,36 +1,170 @@
-/** Built-in bounded sampler used by `analyze runtime`; dynamic stays caller-owned. */
+/**
+ * Built-in runtime evidence operations used by `analyze runtime`.
+ *
+ * The caller-supplied `analyze dynamic` path remains the escape hatch for
+ * field-specific GumJS. This script only provides two bounded primitives:
+ * `dump` exports PE sections for static analysis and `verify` reads profile
+ * candidates at runtime.
+ */
 export const RUNTIME_EXPORT_SCRIPT = String.raw `
 "use strict";
 const input = globalThis.__WOWDUMP_INPUT__ || {};
 const moduleName = typeof input.module === "string" && input.module ? input.module : "Wow.exe";
 const module = Process.findModuleByName(moduleName);
-const limit = Math.min(Math.max(Number(input.maxEvents || 16), 1), 256);
-const sampleBytes = Math.min(Math.max(Number(input.sampleBytes || 64), 1), 256);
-function bytes(address, size) { const value = address.readByteArray(size); return value ? Array.from(new Uint8Array(value), byte => byte.toString(16).padStart(2, "0")).join("") : ""; }
-function collect() {
-  if (!module) return { ok: false, module: { name: moduleName }, records: [], evidence: [{ source: "frida", kind: "module-missing" }] };
-  if (input.kind === "text") {
-    const ranges = Process.enumerateRanges("r-x").filter(range => range.base.compare(module.base) >= 0 && range.base.compare(module.base.add(module.size)) < 0);
-    const textRanges = ranges.map(range => ({ base: range.base.toString(), rva: range.base.sub(module.base).toString(), size: range.size, protection: range.protection }));
-    const records = [];
-    for (const range of ranges) {
-      if (records.length >= limit) break;
-      const rva = range.base.sub(module.base);
-      const offset = rva.isNull() && range.size > 0x1000 ? 0x1000 : 0;
-      const address = range.base.add(offset);
-      records.push({ address: address.toString(), rva: address.sub(module.base).toString(), size: Math.min(sampleBytes, range.size - offset), bytesHex: bytes(address, Math.min(sampleBytes, range.size - offset)) });
+const maxCandidates = Math.min(Math.max(Number(input.maxCandidates || input.maxEvents || 256), 1), 4096);
+const maxSectionBytes = Math.min(Math.max(Number(input.maxSectionBytes || 128 * 1024 * 1024), 1), 512 * 1024 * 1024);
+const maxTotalBytes = Math.min(Math.max(Number(input.maxTotalBytes || 256 * 1024 * 1024), 1), 768 * 1024 * 1024);
+const chunkSize = Math.min(Math.max(Number(input.chunkSize || 1024 * 1024), 4096), 4 * 1024 * 1024);
+const maxVerifyBytes = Math.min(Math.max(Number(input.maxVerifyBytes || 256), 1), 4096);
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+function readBytes(address, size) {
+  const value = address.readByteArray(size);
+  return value ? new Uint8Array(value) : null;
+}
+
+function bytesHex(address, size) {
+  const bytes = readBytes(address, size);
+  if (!bytes) return "";
+  let output = "";
+  for (let index = 0; index < bytes.length; index++) output += bytes[index].toString(16).padStart(2, "0");
+  return output;
+}
+
+function base64(bytes) {
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index];
+    const second = index + 1 < bytes.length ? bytes[index + 1] : 0;
+    const third = index + 2 < bytes.length ? bytes[index + 2] : 0;
+    const value = (first << 16) | (second << 8) | third;
+    output += BASE64[(value >>> 18) & 63];
+    output += BASE64[(value >>> 12) & 63];
+    output += index + 1 < bytes.length ? BASE64[(value >>> 6) & 63] : "=";
+    output += index + 2 < bytes.length ? BASE64[value & 63] : "=";
+  }
+  return output;
+}
+
+function ascii(address, size) {
+  const bytes = readBytes(address, size);
+  if (!bytes) return "";
+  let output = "";
+  for (let index = 0; index < bytes.length; index++) {
+    const value = bytes[index];
+    output += value >= 0x20 && value <= 0x7e ? String.fromCharCode(value) : "";
+  }
+  return output;
+}
+
+function u16(address) { return address.readU16(); }
+function u32(address) { return address.readU32(); }
+function sectionName(address) {
+  return ascii(address, 8).replace(/\0/g, "").trim();
+}
+
+function parseSections() {
+  if (!module) return { error: "module-missing", sections: [] };
+  try {
+    const base = module.base;
+    if (u16(base) !== 0x5a4d) return { error: "invalid-dos-signature", sections: [] };
+    const peOffset = u32(base.add(0x3c));
+    if (peOffset < 0x40 || peOffset > module.size - 24) return { error: "invalid-pe-offset", sections: [] };
+    const pe = base.add(peOffset);
+    if (u32(pe) !== 0x00004550) return { error: "invalid-pe-signature", sections: [] };
+    const count = u16(pe.add(6));
+    const optionalSize = u16(pe.add(20));
+    if (count < 1 || count > 96 || optionalSize < 0x60) return { error: "invalid-section-table", sections: [] };
+    const table = pe.add(24 + optionalSize);
+    const sections = [];
+    for (let index = 0; index < count; index++) {
+      const header = table.add(index * 40);
+      const name = sectionName(header);
+      const virtualSize = u32(header.add(8));
+      const rva = u32(header.add(12));
+      const rawSize = u32(header.add(16));
+      const characteristics = u32(header.add(36));
+      const size = Math.max(virtualSize, rawSize);
+      if (!name || !size || rva >= module.size) continue;
+      const boundedSize = Math.min(size, module.size - rva);
+      const executable = (characteristics & 0x20000000) !== 0;
+      const writable = (characteristics & 0x80000000) !== 0;
+      const readable = (characteristics & 0x40000000) !== 0;
+      sections.push({
+        name,
+        rva: "0x" + rva.toString(16),
+        runtimeAddress: base.add(rva).toString(),
+        virtualSize,
+        rawSize,
+        characteristics: "0x" + characteristics.toString(16),
+        protection: (readable ? "r" : "") + (writable ? "w" : "") + (executable ? "x" : ""),
+        size: boundedSize
+      });
     }
-    return { ok: true, kind: "text", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, textRanges, samples: records, records, evidence: [{ source: "frida", kind: "frida-runtime-text", samples: records.length }] };
+    return { error: null, sections };
+  } catch (error) {
+    return { error: String(error), sections: [] };
+  }
+}
+
+function dumpSection(section, totalState) {
+  const requestedSize = Math.min(section.size, maxSectionBytes);
+  const available = Math.max(0, maxTotalBytes - totalState.bytes);
+  const readSize = Math.min(requestedSize, available);
+  const chunks = [];
+  let offset = 0;
+  while (offset < readSize) {
+    const size = Math.min(chunkSize, readSize - offset);
+    const bytes = readBytes(module.base.add(parseInt(section.rva, 16)).add(offset), size);
+    if (!bytes) break;
+    chunks.push({ offset, size: bytes.length, dataBase64: base64(bytes) });
+    offset += bytes.length;
+    if (bytes.length !== size) break;
+  }
+  totalState.bytes += offset;
+  return { ...section, requestedSize, readSize: offset, truncated: offset < section.size, chunks };
+}
+
+function candidateEntries(profile) {
+  const entries = [];
+  const fields = profile && typeof profile.fields === "object" && !Array.isArray(profile.fields) ? profile.fields : {};
+  for (const [name, value] of Object.entries(fields)) entries.push({ name, value });
+  return entries.slice(0, maxCandidates);
+}
+
+function candidateRva(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const item = value;
+  const root = item.root && typeof item.root === "object" && !Array.isArray(item.root) ? item.root : {};
+  const rva = item.rva ?? root.rva;
+  if (typeof rva !== "string" && typeof rva !== "number") return null;
+  try { return ptr(String(rva)).toString(); } catch (_) { return null; }
+}
+
+function collect() {
+  if (!module) return { ok: false, kind: input.kind || "dump", module: { name: moduleName }, sections: [], records: [], evidence: [{ source: "frida", kind: "module-missing" }] };
+  if (input.kind === "dump") {
+    const parsed = parseSections();
+    if (parsed.error) return { ok: false, kind: "dump", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, sections: [], records: [], evidence: [{ source: "frida", kind: "pe-parse-failed", error: parsed.error }] };
+    const selected = parsed.sections.filter(section => [".text", ".rdata", ".data", ".pdata"].includes(section.name.toLowerCase()));
+    const totalState = { bytes: 0 };
+    const sections = selected.map(section => dumpSection(section, totalState));
+    return { ok: true, kind: "dump", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size, path: module.path }, sections, totalBytes: totalState.bytes, limits: { maxSectionBytes, maxTotalBytes, chunkSize }, truncated: sections.some(section => section.truncated), evidence: [{ source: "frida", kind: "frida-runtime-pe-sections", sections: sections.map(section => section.name), totalBytes: totalState.bytes }] };
   }
-  const profile = input.profile && typeof input.profile === "object" ? input.profile : {};
-  const candidates = Array.isArray(profile.providers) ? profile.providers : [];
+  if (input.kind !== "verify") return { ok: false, kind: input.kind || null, module: { name: module.name }, records: [], evidence: [{ source: "frida", kind: "unsupported-runtime-kind" }] };
+  const profile = input.profile && typeof input.profile === "object" ? input.profile : null;
+  if (!profile) return { ok: false, kind: "verify", module: { name: module.name, moduleBase: module.base.toString() }, records: [], evidence: [{ source: "frida", kind: "profile-required" }] };
   const records = [];
-  for (const candidate of candidates.slice(0, limit)) {
-    if (!candidate || typeof candidate.rva !== "string") continue;
-    const address = module.base.add(ptr(candidate.rva));
-    records.push({ name: candidate.name || "candidate", rva: candidate.rva, runtimeAddress: address.toString(), bytesHex: bytes(address, Math.min(Number(candidate.size || 16), 256)), source: "frida" });
+  for (const entry of candidateEntries(profile)) {
+    const rva = candidateRva(entry.value);
+    if (rva === null) { records.push({ name: entry.name, ok: false, reason: "missing-rva", source: "frida" }); continue; }
+    const address = module.base.add(ptr(rva));
+    try {
+      const bytes = bytesHex(address, Math.min(Number(entry.value.size || entry.value.byteSize || maxVerifyBytes), maxVerifyBytes));
+      records.push({ name: entry.name, rva, runtimeAddress: address.toString(), bytesHex: bytes, bytesRead: bytes.length / 2, complete: bytes.length > 0, ok: bytes.length > 0, source: "frida" });
+    } catch (error) { records.push({ name: entry.name, rva, runtimeAddress: address.toString(), ok: false, reason: String(error), source: "frida" }); }
   }
-  return { ok: true, module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size }, records, evidence: [{ source: "frida", kind: "frida-runtime-read", count: records.length }] };
+  return { ok: true, kind: "verify", module: { name: module.name, moduleBase: module.base.toString(), moduleSize: module.size, path: module.path }, records, evidence: [{ source: "frida", kind: "frida-runtime-verify", candidates: records.length, passed: records.filter(item => item.ok).length }] };
 }
 rpc.exports = { collect };
 `;

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, realpathSync, readFileSync } from "node:fs";
-import { readFile, readdir } from "node:fs/promises";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command } from "commander";
@@ -248,7 +249,7 @@ function selected(source, keys) {
 function requireRuntimeConfirmation(options) {
     if (options.confirm === true)
         return;
-    throw new CliError("CONFIRMATION_REQUIRED", "runtime export requires --confirm", {
+    throw new CliError("CONFIRMATION_REQUIRED", "runtime analysis requires --confirm", {
         pid: options.pid,
         buildKey: options.build,
         operation: "runtime",
@@ -259,6 +260,62 @@ function requireRuntimeConfirmation(options) {
         cleanupDeadlineMs: options.cleanupDeadlineMs
     });
 }
+function safeBuildDirectory(buildKey) {
+    const value = buildKey.trim();
+    if (!value || !/^[A-Za-z0-9_.@-]+$/.test(value))
+        throw new CliError("ARGUMENT_INVALID", "build key contains unsupported path characters");
+    return value;
+}
+function decodeBase64(value, expectedSize, label) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(value))
+        throw new CliError("RUNTIME_DUMP_INVALID", `${label} is not valid base64`);
+    const data = Buffer.from(value, "base64");
+    if (data.length !== expectedSize)
+        throw new CliError("RUNTIME_DUMP_INVALID", `${label} size does not match metadata`);
+    return data;
+}
+export async function persistRuntimeDump(value, outputDirectory) {
+    const sections = Array.isArray(value.sections) ? value.sections : [];
+    if (value.ok !== true || sections.length === 0)
+        return value;
+    const directory = resolve(outputDirectory);
+    await mkdir(directory, { recursive: true });
+    const summaries = [];
+    for (const raw of sections) {
+        const section = jsonRecord(JSON.stringify(raw), "runtime section");
+        const name = typeof section.name === "string" && /^[A-Za-z0-9_.-]+$/.test(section.name) ? section.name : "section";
+        const file = join(directory, `${name}.bin`);
+        const chunks = Array.isArray(section.chunks) ? section.chunks : [];
+        const buffers = chunks.map((chunk, index) => {
+            const item = jsonRecord(JSON.stringify(chunk), `runtime section ${name} chunk ${index}`);
+            return decodeBase64(item.dataBase64, Number(item.size), `${name} chunk ${index}`);
+        });
+        const data = Buffer.concat(buffers);
+        await writeFile(file, data);
+        summaries.push({
+            ...selected(section, ["name", "rva", "runtimeAddress", "virtualSize", "rawSize", "characteristics", "protection", "requestedSize", "readSize", "truncated"]),
+            file,
+            bytes: data.length,
+            sha256: createHash("sha256").update(data).digest("hex")
+        });
+    }
+    const manifest = {
+        schema: "wowdump.runtime-dump.v1",
+        kind: "dump",
+        buildKey: value.buildKey ?? null,
+        pid: value.pid ?? null,
+        module: value.module ?? null,
+        totalBytes: value.totalBytes ?? summaries.reduce((total, item) => total + Number(item.bytes ?? 0), 0),
+        truncated: value.truncated === true || summaries.some(item => item.truncated === true),
+        limits: value.limits ?? null,
+        sections: summaries,
+        evidence: value.evidence ?? [],
+        generatedAt: new Date().toISOString()
+    };
+    const manifestFile = join(directory, "manifest.json");
+    await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return { ...value, sections: summaries, outputDirectory: directory, manifestFile, manifest };
+}
 export function createWowdumpCli(dependencies = {}) {
     const io = dependencies.io ?? { stdout: process.stdout, stderr: process.stderr };
     const env = dependencies.env ?? process.env;
@@ -406,7 +463,7 @@ export function createWowdumpCli(dependencies = {}) {
         .description("Decode Frida text evidence and produce a Reader profile")
         .requiredOption("--exe <path>", "path to Wow.exe")
         .requiredOption("--build <buildKey>", "build key")
-        .requiredOption("--runtime-export <file>", "Frida runtime text JSON")
+        .requiredOption("--runtime-export <file>", "runtime evidence JSON")
         .option("--ida-evidence <file>", "JSON produced by an IDA Pro MCP analysis")
         .option("--output <file>", "profile output JSON")
         .option("--max-instructions <count>", "maximum decoded instructions", "256")
@@ -421,14 +478,19 @@ export function createWowdumpCli(dependencies = {}) {
         dryRun: options.dryRun === true
     })));
     analyze.command("runtime")
-        .description("Read runtime evidence through the elevated Frida broker")
+        .description("Dump runtime PE sections or verify profile candidates through the elevated Frida broker")
         .requiredOption("--pid <pid>", "target process ID")
         .requiredOption("--build <buildKey>", "build key")
         .option("--build-key <buildKey>", "alias for --build")
-        .option("--kind <kind>", "text or providers", "providers")
+        .option("--kind <kind>", "dump or verify", "dump")
         .option("--worker <path>", "Frida worker entry")
-        .option("--profile <path>", "existing reader profile containing candidate RVAs")
-        .option("--max-hooks <count>", "maximum hooks", "1")
+        .option("--profile <path>", "reader profile containing candidate RVAs (verify only)")
+        .option("--output-dir <path>", "directory for dump manifest and section binaries")
+        .option("--max-section-bytes <bytes>", "per-section dump limit", "134217728")
+        .option("--max-total-bytes <bytes>", "total dump limit", "268435456")
+        .option("--chunk-size <bytes>", "dump chunk size", "1048576")
+        .option("--max-verify-bytes <bytes>", "maximum bytes read per candidate", "256")
+        .option("--max-hooks <count>", "reserved compatibility limit", "1")
         .option("--duration-ms <ms>", "maximum duration", "5000")
         .option("--max-events <count>", "maximum events", "100")
         .option("--cleanup-deadline-ms <ms>", "cleanup deadline", "2000")
@@ -442,11 +504,17 @@ export function createWowdumpCli(dependencies = {}) {
             durationMs: positiveInteger(options.durationMs, "duration-ms"),
             maxEvents: positiveInteger(options.maxEvents, "max-events"),
             cleanupDeadlineMs: positiveInteger(options.cleanupDeadlineMs, "cleanup-deadline-ms"),
+            maxSectionBytes: positiveInteger(options.maxSectionBytes, "max-section-bytes"),
+            maxTotalBytes: positiveInteger(options.maxTotalBytes, "max-total-bytes"),
+            chunkSize: positiveInteger(options.chunkSize, "chunk-size"),
+            maxVerifyBytes: positiveInteger(options.maxVerifyBytes, "max-verify-bytes"),
             confirm: options.confirm === true
         };
-        if (!["text", "providers"].includes(normalized.kind))
-            throw new CliError("ARGUMENT_INVALID", "kind must be text or providers");
+        if (!["dump", "verify"].includes(normalized.kind))
+            throw new CliError("ARGUMENT_INVALID", "kind must be dump or verify");
         requireRuntimeConfirmation(normalized);
+        if (normalized.kind === "verify" && !options.profile)
+            throw new CliError("PROFILE_REQUIRED", "verify requires --profile <file>");
         const worker = resolve(options.worker ?? env.WOWDUMP_FRIDA_WORKER ?? join(packageDist, "frida-worker.js"));
         if (!existsSync(worker))
             throw new CliError("FRIDA_WORKER_NOT_FOUND", `Frida worker was not found: ${worker}`);
@@ -465,6 +533,10 @@ export function createWowdumpCli(dependencies = {}) {
                 durationMs: normalized.durationMs,
                 maxEvents: normalized.maxEvents,
                 cleanupDeadlineMs: normalized.cleanupDeadlineMs,
+                maxSectionBytes: normalized.maxSectionBytes,
+                maxTotalBytes: normalized.maxTotalBytes,
+                chunkSize: normalized.chunkSize,
+                maxVerifyBytes: normalized.maxVerifyBytes,
                 ...(profile ? { profile } : {})
             },
             callArgs: [],
@@ -475,7 +547,14 @@ export function createWowdumpCli(dependencies = {}) {
             throw new CliError("FRIDA_WORKER_FAILED", result.stderr.trim() || `Frida worker exited with ${result.exitCode}`);
         const line = result.stdout.split(/\r?\n/).find(value => value.trim());
         const value = line ? jsonRecord(line, "runtime result") : { ok: true, stdout: result.stdout };
-        writeJson(io, { ...value, command: "analyze.runtime" });
+        if (normalized.kind === "dump" && value.ok === true) {
+            const defaultDirectory = join(home, safeBuildDirectory(normalized.build), "runtime", `dump-${Date.now()}`);
+            const persisted = await persistRuntimeDump(value, options.outputDir ?? defaultDirectory);
+            writeJson(io, { ...persisted, command: "analyze.runtime.dump" });
+        }
+        else {
+            writeJson(io, { ...value, command: "analyze.runtime.verify" });
+        }
     });
     analyze.command("dynamic")
         .description("Run a caller-supplied GumJS script through Frida")

package/dist/toolchain.js

@@ -18,12 +18,12 @@ description: 使用 Frida 运行时证据和 IDA/iced-x86 定位 WoW 字段，
 export const DEFAULT_WOWDUMP_COMMANDS = `# wowdump 命令参考
 
 1. \`wowdump targets\`
-2. \`wowdump analyze runtime --pid <pid> --build <buildKey> --kind text --confirm\`
+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>\`
 
-若 Agent 能调用 IDA Pro MCP，先用 MCP 分析 runtime text，再把结果保存为 JSON 并通过 \`--ida-evidence\` 交给 disassemble 命令。未确认的候选 profile 放在 runtime 目录；确认后才复制到当前 build 的 profile 目录。
+\`dump\` 会导出供 IDA/iced-x86 分析的 PE 段并生成 manifest；\`verify\` 需要 \`--profile\`，只验证已有候选 RVA。若 Agent 能调用 IDA Pro MCP，先用 MCP 分析 dump manifest 指向的段，再把结果保存为 JSON 并通过 \`--ida-evidence\` 交给 disassemble 命令。未确认的候选 profile 放在 runtime 目录；确认后才复制到当前 build 的 profile 目录。
 `;
 function normalizePath(value) { return resolve(value.trim().replace(/^"|"$/g, "")); }
 function directoryExists(value) { try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowdump",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "WoW native memory analysis CLI with Frida evidence, IDA/iced-x86 disassembly, and an elevated reader broker",
   "license": "MIT",
   "repository": {
@@ -42,5 +42,9 @@
   "devDependencies": {
     "@types/node": "^22.13.4",
     "typescript": "^5.7.3"
+  },
+  "allowScripts": {
+    "frida@17.17.0": true,
+    "koffi@2.16.3": true
   }
 }

package/skills/wowdump/SKILL.md

@@ -13,10 +13,12 @@ description: 以 Frida 运行时探测为主，按证据需要交替使用 IDA P
 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、对象布局或字段类型时，再对相关样本调用 IDA Pro MCP；没有 IDA 时才用 `wowdump analyze disassemble` 的 iced-x86 输出。静态和动态可以交替执行，每轮只扩大当前字段所需的证据范围。
+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 memory read --profile <profile> --field <name>` 做 broker-backed 验证；只有地址、类型和实际读取都成功后才标记 `reader_ready`。经用户确认后再保存到该 build 的 `profile/`。
+7. 用 `wowdump analyze runtime --kind verify --profile <profile> --confirm` 或 `wowdump memory read --profile <profile> --field <name>` 做 broker-backed 验证；只有地址、类型和实际读取都成功后才标记 `reader_ready`。经用户确认后再保存到该 build 的 `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)。
+
+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

@@ -24,18 +24,32 @@ wowdump analyze dynamic `
   --confirm > $HOME\.wowdump\runtime\<session-id>\state.json
 ```
 
-固定采样：
+导出供静态分析的运行时模块段：
 
 ```powershell
 wowdump analyze runtime `
   --pid 33976 `
   --build "retail@12.1.0.69587" `
-  --kind text `
-  --duration-ms 5000 `
-  --max-events 100 `
-  --confirm > $HOME\.wowdump\runtime\<session-id>\text.json
+  --kind dump `
+  --output-dir "$HOME\.wowdump\retail@12.1.0.69587\runtime\dump-01" `
+  --confirm
+```
+
+输出目录中包含 `manifest.json` 和 `.text`、`.rdata`、`.data`、`.pdata` 二进制段。stdout 只返回 manifest 路径和摘要，不打印整段十六进制。
+
+验证已有候选 profile：
+
+```powershell
+wowdump analyze runtime `
+  --pid 33976 `
+  --build "retail@12.1.0.69587" `
+  --kind verify `
+  --profile "$HOME\.wowdump\retail@12.1.0.69587\runtime\candidate.profile.json" `
+  --confirm
 ```
 
+`verify` 不负责发现地址；没有 profile 时会直接提示缺少验证目标。
+
 ## 需要时做静态定位
 
 只有 dynamic 结果缺少函数 RVA、对象布局或字段类型时，才调用 IDA Pro MCP；没有 IDA 时使用 iced-x86 兜底：

package/skills/wowdump/references/disassemble.md

@@ -1,15 +1,59 @@
 # 反汇编与 IDA Pro 分支
 
-静态分析是按需使用的证据放大器，不是每个查询的必经步骤。运行时 text、字节样本、Hook 调用记录或返回值都可以作为输入。先检查当前 Agent 是否能调用本机 IDA Pro MCP：
+静态分析是按需使用的证据放大器，不是每个查询的必经步骤。需要静态证据时，先用 `wowdump analyze runtime --kind dump` 导出运行时 `.text`、`.rdata`、`.data`、`.pdata` 以及 manifest；运行时字节样本、Hook 调用记录或返回值也可以作为输入。先检查当前 Agent 是否能调用本机 IDA Pro MCP：
+
+## IDA Pro MCP 下载与安装
+
+官方来源：
+
+- GitHub：https://github.com/mrexodia/ida-pro-mcp
+- Hex-Rays 插件页：https://plugins.hex-rays.com/mrexodia/ida-pro-mcp
+
+使用 Codex 时，官方仓库提供插件市场安装方式：
+
+```text
+codex plugin marketplace add mrexodia/codex-marketplace
+codex plugin add ida-pro-mcp@mrexodia
+```
+
+IDA Pro MCP 需要 **IDA Pro 8.3+**（不支持 IDA Free）、Python 3.11+，headless `idalib` 路径还需要 `uv`。安装后重启 IDA 和 Codex，使 MCP 工具生效。若插件市场不可用，按官方仓库 README 的 GUI 或 `idalib-mcp` 安装说明操作；不要在项目中复制或维护 MCP 的内部 Python/IDA 代码。
 
 - 能调用时，让 MCP 只分析当前字段相关样本附近的函数、字符串、调用关系和结构，把结果保存为 JSON。随后回到 dynamic Hook 验证候选函数，不要直接把静态候选当成可读字段。
-- 不能调用时执行：
+
+## IDA MCP 会话保活与重连
+
+IDA 的 headless worker 不是常驻进程。`idb_list` 中仍有 session 记录，不代表对应 worker 仍然可用；查询返回 `Worker for session ... is not reachable` 时，不能继续复用该 session。
+
+打开数据库时使用较长的空闲 TTL，并开启自动分析和缓存：
+
+```json
+{
+  "input_path": "C:\\Games\\World of Warcraft\\_retail_\\Wow.exe",
+  "mode": "prefer_headless",
+  "run_auto_analysis": true,
+  "build_caches": true,
+  "init_hexrays": true,
+  "idle_ttl_sec": 3600
+}
+```
+
+每次查询前先调用 `server_health({ database: sessionId })`，确认 `status: "ok"`、`auto_analysis_ready: true`。长查询之间也要做一次 health probe，避免 worker 被回收后才发现会话失效。
+
+失联时只做一次恢复：
+
+1. 丢弃失联的 session ID；如果服务仍列出它，调用 `idb_close`。
+2. 用相同 `input_path` 和 `idle_ttl_sec: 3600` 重新调用 `idb_open`。
+3. 对新 session 做 `server_health`，成功后重试原查询一次。
+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\runtime\SESSION\text.json" `
+  --runtime-export "$HOME\.wowdump\retail@VERSION\runtime\SESSION\state.json" `
   --output "$HOME\.wowdump\runtime\SESSION\candidate.profile.json"
 ```
 

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

@@ -16,7 +16,7 @@
 
 ## Disassemble（按需使用）
 
-`--runtime-export` 指向 dynamic JSON。只有 dynamic 线索不足以确认函数、布局或类型时才调用 IDA Pro MCP；没有时再用 `analyze disassemble` 的 iced-x86 解码。分析后回到 dynamic 验证。输出 profile 时，每个字段至少给出：
+`analyze runtime --kind dump` 的 `manifest.json` 和段文件是静态分析输入；`--runtime-export` 仍可指向 dynamic JSON。只有 dynamic 线索不足以确认函数、布局或类型时才调用 IDA Pro MCP；没有时再用 iced-x86 解码。分析后回到 dynamic 或 `analyze runtime --kind verify --profile <file>` 验证。输出 profile 时，每个字段至少给出：
 
 ```json
 {

package/skills/wowdump/references/workflow.md

@@ -11,6 +11,7 @@
 | --- | --- | --- |
 | 不知道模块/进程 | `wowdump targets` | PID、路径、buildKey、模块基址明确 |
 | 不知道对象或函数是否被调用 | Dynamic GumJS 枚举、有限扫描或 Hook | 得到对象地址、候选函数或调用事件 |
+| 需要给 IDA/iced 完整模块证据 | `wowdump analyze runtime --kind dump` | 得到 `.text`、`.rdata`、`.data`、`.pdata` 和 manifest |
 | 有候选函数但不知道其语义 | Dynamic Hook，配合用户触发一次相关动作 | `this`、参数、返回值与目标字段相关 |
 | 有调用但不知道字段偏移/类型 | IDA Pro MCP 局部反汇编；无 IDA 时 iced-x86 | 指令访问行为能解释对象和字段 |
 | 静态候选需要运行时确认 | 回到 Dynamic Hook 或快照 | 候选 RVA 在当前模块命中且数据变化符合预期 |
@@ -20,7 +21,7 @@
 
 1. 先检查是否已有同 build 的 `reader_ready` profile；有则直接 Reader，失败再回到 Dynamic。
 2. 没有 profile 时优先执行 Agent 编写的 GumJS。脚本可以直接 Hook 已知 RVA，也可以在限定范围内扫描候选。
-3. Dynamic 只拿到线索时，再让 IDA Pro MCP 分析对应函数或字节附近区域。不要对整个模块做无目标导出。
+3. Dynamic 只拿到线索时，先用 `analyze runtime --kind dump` 导出相关 PE 段，再让 IDA Pro MCP 分析对应函数、字符串和交叉引用。不要把 dump 当成 profile。
 4. 没有 IDA 时使用 `analyze disassemble`/iced-x86 作为局部解码工具，得到候选后仍回到 Dynamic 验证。
 5. 每轮最多扩大一个维度：函数数量、扫描范围、读取字节数或采样时长。连续两轮没有新增证据时，停止扩大并请求用户触发相关游戏动作或确认字段范围。