wowdump 0.3.7 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowdump",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "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.7": true
+    "wowdump@0.3.8": true
   }
 }

package/skills/wowdump/SKILL.md

@@ -1,31 +1,23 @@
 ---
 name: wowdump
-description: 使用 WinDbg CDB、Reader broker 和 IDA/iced-x86 证据定位并验证 WoW 原生内存字段。
+description: 使用 wowdump CLI 定位和读取 WoW 原生内存字段，结合 CDB、IDA Pro MCP 或 iced-x86 证据生成并验证 Reader profile。
 ---
 
 # wowdump
 
-用于读取角色属性、Buff/Debuff、技能冷却、附近单位等原生字段。先确认目标和 build，再按缺口收集 CDB 证据，最后只让 Reader 读取已验证 profile。
+先明确要读的对象、字段和单位。例如“角色属性”中的暴击等级与暴击百分比是不同字段；不要用 Aura、资源值等其他结果替代。
 
-## 默认策略
+1. 运行 `wowdump targets`，使用返回的 PID、路径、buildKey 和哈希；多个目标且用户尚未指定时请用户选择。
+2. 有匹配 build/hash 的已验证 profile 时直接 Reader 读取。用户要求全新分析时，创建新 session，不使用旧候选作为本轮发现。
+3. 未知字段按 [定位流程](references/workflow.md) 收集证据；需要静态分析时先读 [IDA 与局部反汇编](references/disassemble.md)。
+4. 按 [Profile 格式与生命周期](references/profiles.md) 构建候选，按 [验证方法](references/evidence-workflow.md) 分别验证读取、字段含义和复用能力。
+5. 返回字段、单位、观测时间和证据路径。用户确认持久化后保存 profile；已有保存授权时沿用。
 
-1. 运行 `wowdump targets`。如果有多个 `Wow.exe`，让用户选择 PID；不要猜 buildKey。该命令会创建或复用 `~/.wowdump/<buildKey>/database/`。
-2. 用 `wowdump database status --build <buildKey>` 查看数据库状态。
-3. 有 `reader_ready` profile 时直接使用 `wowdump memory read --pid <pid> --build <buildKey> --profile <profile> --field <name>`。
-4. 需要 PE 段时运行 `wowdump analyze runtime --kind dump --confirm`。它由 broker 启动 CDB，把段写入当前 runtime session，不创建新数据库。
-5. 需要确认一个函数调用时运行 `wowdump analyze debug --kind breakpoint --rva <rva> --confirm`；只提供静态确认过的单个 RVA。
-6. 需要 CDB 的其他诊断能力时使用 `wowdump analyze debug --kind command --cdb-commands <JSON数组> --confirm`。参数和命令都是数组，不经过 shell。
-7. 由 IDA Pro MCP 优先分析原始 Wow.exe；没有 IDA MCP 时用 iced-x86 做局部反汇编。输出 RVA、调用关系、结构偏移和字段类型。
-8. 将证据整理为 candidate profile，再运行 `wowdump analyze runtime --kind verify --profile <profile> --confirm`。
-9. Reader 实读成功且用户确认后，才把 profile 放到 `~/.wowdump/<buildKey>/profile/`。
+按需查阅：
+- [命令参数](references/commands.md)：CLI 用法。
+- [字段定义](references/request-schema.md)：目标含义不明确时。
+- [CDB 使用与退出限制](references/windbg.md)：执行 dump 或 debug 前。
 
-## 组件边界
+目录统一为 `~/.wowdump/<buildKey>/`：`database/` 保存静态数据库，`runtime/<session>/` 保存本轮证据与候选，`profile/` 保存已确认的持久化接口。Reader 读取 profile。broker 首次 UAC 后复用，空闲 20 分钟退出。
 
-- WinDbg/CDB：一次性的 dump、断点和调试命令证据；不改写目标函数入口。
-- Reader broker：一次 UAC 后复用 20 分钟，负责 `ReadProcessMemory`、`VirtualQueryEx`、模块枚举和 CDB 子进程。
-- IDA/iced-x86：静态分析，不读取运行时堆状态。
-- Reader：根据 profile 的 RVA、指针链、类型和边界做有界读取；不猜地址。
-
-详细命令、调试器参数、证据门槛和 profile 格式见 references 目录。
-
-IDA MCP 使用长 TTL 会话（默认 `idle_ttl_sec: 3600`）。每次查询前先做 health probe；出现 `worker not reachable` 时按 `references/disassemble.md` 重新打开并只重试一次。IDA worker 与 Windows broker 独立，broker 的 UAC 复用不会保持 IDA worker 存活。
+脚本和任务证据放在 runtime session，具体地址由本轮分析确定。保留禁用 Frida Hook 和 Stalker 的约束。

package/skills/wowdump/references/commands.md

@@ -6,7 +6,7 @@ Windows 下内存和 CDB 请求都连接同一个管理员 broker。首次连接
 
 ```powershell
 wowdump targets
-wowdump targets --pid 33976
+wowdump targets --pid <pid>
 ```
 
 使用输出中的 `pid`、`path`、`buildKey` 和哈希。多个目标时先让用户选择。
@@ -15,8 +15,8 @@ wowdump targets --pid 33976
 
 ```powershell
 wowdump analyze runtime `
-  --pid 33976 `
-  --build "retail@12.1.0.69587" `
+  --pid <pid> `
+  --build "<buildKey>" `
   --kind dump `
   --sections .text .rdata .pdata `
   --confirm
@@ -28,17 +28,17 @@ wowdump analyze runtime `
 
 ```powershell
 wowdump analyze debug `
-  --pid 33976 `
-  --build "retail@12.1.0.69587" `
-  --rva 0x18acbf0 `
+  --pid <pid> `
+  --build "<buildKey>" `
+  --rva <confirmedRva> `
   --kind breakpoint `
   --max-hits 3 `
   --duration-ms 3000 `
   --confirm
 
 wowdump analyze debug `
-  --pid 33976 `
-  --build "retail@12.1.0.69587" `
+  --pid <pid> `
+  --build "<buildKey>" `
   --kind command `
   --cdb-commands '["lm","r","~"]' `
   --cdb-args '["-lines"]' `
@@ -50,8 +50,8 @@ wowdump analyze debug `
 ## 数据库和验证
 
 ```powershell
-wowdump database status --build "retail@12.1.0.69587"
-wowdump analyze runtime --pid 33976 --build "retail@12.1.0.69587" --kind verify --profile <profile.json> --confirm
+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/`。
@@ -60,11 +60,13 @@ wowdump analyze runtime --pid 33976 --build "retail@12.1.0.69587" --kind verify
 
 ```powershell
 wowdump memory read `
-  --pid 33976 `
-  --build "retail@12.1.0.69587" `
-  --profile "$HOME\.wowdump\retail@12.1.0.69587\profile\player-state.json" `
+  --pid <pid> `
+  --build "<buildKey>" `
+  --profile "$HOME\.wowdump\<buildKey>\profile\player-state.json" `
   --field playerStats
-wowdump memory regions --pid 33976 --start 0x15000000000 --end 0x15400000000 --max-regions 20000
+wowdump memory regions --pid <pid> --start <startAddress> --end <endAddress> --max-regions 20000
 ```
 
 Reader 使用 `ReadProcessMemory` 和 `VirtualQueryEx` 做有界读取，返回实际地址、读取长度、解析值和证据。
+
+断点退出限制见 [windbg.md](windbg.md)；candidate 验证步骤见 [profiles.md](profiles.md)。尖括号参数需替换后运行。

package/skills/wowdump/references/disassemble.md

@@ -1,52 +1,62 @@
-# 反汇编与 IDA Pro 分支
+# IDA 与局部反汇编
 
-静态分析是按需使用的证据放大器，不是每个查询的必经步骤。需要静态证据时，先用 `wowdump analyze runtime --kind dump` 导出运行时 `.text`、`.rdata`、`.pdata` 以及 manifest；`.data` 只有在字段需要运行时全局状态时才通过 `--sections` 加入。原始 Wow.exe 始终是 IDA 的主输入，runtime 二进制只是 overlay 证据。先检查当前 Agent 是否能调用本机 IDA Pro MCP：
+## 选择与复用
 
-## IDA Pro MCP 下载与安装
+先发现当前可调用的 IDA Pro MCP 工具及参数 schema，不假定存在特定工具名或 TTL 参数。
 
-官方来源：
+用 database status 获取数据库路径和状态。身份匹配且 ready 时优先打开已有数据库；不存在或 stale 时以原始 Wow.exe 创建。写库前使用环境提供的数据库锁；工具缺少锁能力时保持单一写入者并记录限制。保存后检查文件与状态，不能把打开 session 当作完成建库，也不手工改成 ready 冒充完成。
 
-- GitHub：https://github.com/mrexodia/ida-pro-mcp
-- Hex-Rays 插件页：https://plugins.hex-rays.com/mrexodia/ida-pro-mcp
+原始 PE 是主输入，保留节区、导入和异常信息。需要运行时证据时先读 [windbg.md](windbg.md)，用 dump 导出 .text/.rdata/.pdata，按需加 .data。段 .bin 是 overlay，不作为完整程序打开。检查 manifest 身份、大小、哈希及 shortRead。
 
-使用 Codex 时，官方仓库提供插件市场安装方式：
+## 地址映射
 
-```text
-codex plugin marketplace add mrexodia/codex-marketplace
-codex plugin add ida-pro-mcp@mrexodia
-```
+段内偏移 = 目标 RVA - sectionRva，读取窗口必须落在实际文件范围内。
+IDA 地址 = 数据库 image base + sectionRva，不硬编码 image base。
 
-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 代码。
+runtime dump 的绝对指针包含 ASLR。改变段加载地址不等于修正指针；分析表项时先减 manifest.moduleBase 得到 RVA，再映射到 IDA 地址。保留原始指针作证据。.data 只代表当前 session；写入持久库前保留 overlay 来源和恢复方式，避免污染原始文件视图。
 
-- 能调用时，让 MCP 只分析当前字段相关样本附近的函数、字符串、调用关系和结构，把结果保存为 JSON。随后回到 broker Reader 或 CDB 断点做有界验证，不要直接把静态候选当成可读字段。
+只输出请求字段相关的函数/字符串 RVA、引用、结构偏移、类型和调用关系。查找方法见 [workflow.md](workflow.md)，全量函数/字符串列表不是 profile。
 
-## IDA MCP 会话保活与重连
+## 会话失联
 
-IDA 的 headless worker 不是常驻进程。`idb_list` 中仍有 session 记录，不代表对应 worker 仍然可用；查询返回 `Worker for session ... is not reachable` 时，不能继续复用该 session。
+用实际支持的健康查询或轻量读取检查 session；支持 TTL 时可延长空闲时间。失联后保存证据，重新打开同一数据库并重试一次。仍失败则转 iced-x86 或报告环境问题。broker 与 IDA worker 生命周期独立。
 
-打开数据库时使用较长的空闲 TTL，并开启自动分析和缓存：
+## iced-x86 局部解码示例
 
-```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
-}
-```
+在任务 session 创建 .cjs 文件。传入已安装 wowdump 的 package.json 绝对路径以解析随包依赖；全局安装根可通过 npm root -g 获取。
 
-每次查询前先调用 `server_health({ database: sessionId })`，确认 `status: "ok"`、`auto_analysis_ready: true`。长查询之间也要做一次 health probe，避免 worker 被回收后才发现会话失效。
+参数依次为 package.json、段 .bin、sectionRva、起始 RVA、字节数、manifest.moduleBase。示例有界解码一个窗口，输出指令 RVA，不提供自动反编译或全局 XREF。
 
-失联时只做一次恢复：
+~~~javascript
+const fs = require("node:fs");
+const { createRequire } = require("node:module");
+const [pkg, file, section, start, size, base] = process.argv.slice(2);
+const { Decoder, DecoderOptions, Formatter, FormatterSyntax } = createRequire(pkg)("iced-x86");
+const rva = BigInt(start), sectionRva = BigInt(section), moduleBase = BigInt(base);
+const offset = rva - sectionRva, length = Number(size);
+const bytes = fs.readFileSync(file);
+if (offset < 0n || !Number.isSafeInteger(length) || length < 1 || length > 65536 ||
+    offset + BigInt(length) > BigInt(bytes.length)) throw new Error("Invalid byte window");
+const decoder = new Decoder(64, bytes.subarray(Number(offset), Number(offset) + length), DecoderOptions.None);
+const formatter = new Formatter(FormatterSyntax.Intel);
+decoder.ip = moduleBase + rva;
+try {
+  while (decoder.canDecode) {
+    const instruction = decoder.decode();
+    try {
+      console.log(JSON.stringify({ rva: "0x" + (instruction.ip - moduleBase).toString(16),
+        text: formatter.format(instruction), invalid: instruction.isInvalid }));
+      if (instruction.isInvalid) break;
+    } finally { instruction.free(); }
+  }
+} finally { decoder.free(); formatter.free(); }
+~~~
 
-1. 丢弃失联的 session ID；如果服务仍列出它，调用 `idb_close`。
-2. 用相同 `input_path` 和 `idle_ttl_sec: 3600` 重新调用 `idb_open`。
-3. 对新 session 做 `server_health`，成功后重试原查询一次。
-4. 第二次仍失联时停止扩大分析范围，保存已取得的 JSON 证据并转用 iced-x86 或请求用户稍后重试。
+起点应来自函数边界或已确认控制流，任意字节可解码不代表代码。RIP 相对目标由下一条指令地址加有符号位移得到，地址运算使用 BigInt。窗口不足时按控制流扩展并记录范围；解码成功不证明字段语义。
 
-不要把 `session_id`、IDA 临时 worker PID 或 `0x140000000` 这类 IDA image base 写入持久化 profile。profile 只保存相对模块的 RVA、字段类型和可复核证据。IDA MCP 会话和 wowdump 的 Windows broker 是两条独立链路：前者负责反汇编，后者负责管理员内存读取；broker 复用不会延长 IDA worker 生命周期。
-- IDA 不可用时，Agent 使用 npm 内置的 `iced-x86` 对 manifest 指向的局部 RVA 反汇编，输出模块 RVA、指令文本、访问偏移和证据。Agent 负责把这些线索与运行时字段对应起来，再用 CDB 断点或 Reader 验证 `root`、`pointerChain`、`layout/type`、计数上限和停止条件。不要把一次运行的绝对地址写进持久化 profile。
+## IDA MCP 来源
 
-输出中的 `readerStatus: "reader_ready"` 只适用于每个字段都有可验证 RVA/地址、类型和边界，并且 reader 实际读成功的情况；否则保持 `candidate`，回到 CDB 或继续局部静态分析。只做一次性查询时可以不生成持久化 profile。
+- [项目仓库](https://github.com/mrexodia/ida-pro-mcp)
+- [Hex-Rays 插件目录](https://plugins.hex-rays.com/mrexodia/ida-pro-mcp)
+
+按安装版本 README 发现工具；已有可用 MCP 时直接使用。

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

@@ -1,41 +1,13 @@
-# 证据工作流
+# 验证字段，而不只验证读取
 
-## 选择路径
+每个字段分别记录三层结论：
 
-先判断用户要的是“一次当前值”还是“可复用 Reader 字段”。一次当前值优先走 Reader 或有限 CDB 命令；可复用字段才补 IDA/iced 和 Reader 验证。两者可以来回切换。
+1. **读取有效**：build/hash 匹配，指针链有来源，读取完整，类型和边界正确。保留地址、dataHex、bytesRead、complete、解析值及命令结果。短读或错误不转换为零值。
+2. **语义有效**：与同一时刻角色面板或其他独立观测对照。百分比、等级、基础值和有效值分开；记录允许的舍入误差。请用户配合一次可控变化（例如换装），读取变化前后值，核对变化方向和幅度。一次相等仅是候选支持证据。
+3. **复用有效**：新进程或重启后的 moduleBase 变化时，同一 profile 仍解析到正确对象。未做这一步就标记“跨进程未验证”，不要报告长期稳定。
 
-## CDB 证据
+不要求用户每次都重新配合已有验证；新字段首次建立语义时才补相应证据。输出 evidence 文件包含字段名、来源文件/函数 RVA、假设、原始读数、观测时间、对照值、转换公式及验证状态。多个字段逐个记录，局部成功不代表全部成功。
 
-段导出使用 `analyze runtime --kind dump`，函数调用证据使用 `analyze debug --kind breakpoint`，其他诊断使用 `analyze debug --kind command`。输出至少包含：
+`analyze runtime --kind verify` 当前只执行 ProfileEngine 读取，返回 `verified:true` 表示读取调用成功；它不做角色面板对照，也不自动证明语义或重启复用。当前 candidate 状态兼容步骤见 [profiles.md](profiles.md)。
 
-- `buildKey`、进程 PID、模块名、`moduleBase`
-- 候选地址或 `rva`、字节样本、来源和采样时间
-- 每个请求字段对应的线索
-
-不要导出整段进程内存。把 `durationMs`、命中次数、命令数量和读取范围限制在请求所需范围内。
-
-## Disassemble（按需使用）
-
-`analyze runtime --kind dump` 的 `manifest.json` 和段文件是静态分析输入。只有 CDB 证据不足以确认函数、布局或类型时才调用 IDA Pro MCP；没有时再用 iced-x86 解码。分析后回到 `analyze debug` 或 `analyze runtime --kind verify --profile <file>` 验证。输出 profile 时，每个字段至少给出：
-
-```json
-{
-  "name": "playerAuras",
-  "module": "Wow.exe",
-  "rva": "0x123456",
-  "pointerChain": [{ "offset": "0x20", "type": "pointer" }],
-  "type": "array",
-  "elementSize": 64,
-  "evidence": [{ "source": "ida-pro-mcp", "functionRva": "0x123000" }]
-}
-```
-
-没有可靠定位时输出 `confidence: "candidate"`，不要填充猜测地址。
-
-## Reader
-
-Reader 根据模块名、RVA、指针链和类型执行原子读取；它不负责猜测结构，也不执行 CDB/IDA。一次读取结果应保留实际地址、请求大小、已读字节、解析值和错误状态。
-
-需要连续数据时使用 `memory watch` 或重复 `memory read`。运行时模块基址可能变化，profile 保存 RVA，不保存本次运行的绝对地址。
-
-## Verify
+dump 的日志、manifest 和段字节属于取证材料；检查每段大小、哈希和 shortRead 后再引用。分析输出中的 RVA、结构偏移、类型和调用关系必须能追溯到这些材料或原始 PE。

package/skills/wowdump/references/profiles.md

@@ -1,45 +1,54 @@
-# Profile 生命周期
+# Profile 格式与生命周期
 
-## 目录约定
+## 地址规则
 
-每次 `targets` 确认 buildKey 后，创建对应目录：
+- runtime VA = 本轮 moduleBase + RVA；IDA VA = 数据库 image base + RVA。
+- 对象偏移以对象指针为基准，不直接加到模块基址。
+- root.rva 默认只加模块基址；root.dereference:true 才读取根处的 8 字节指针。
+- pointerChain 每步先加 offset，默认再读取指针；dereference:false 仅加偏移。
+- fields 是字段名到定义的对象；复杂布局使用 layout。
 
-```text
-~/.wowdump/<buildKey>/
-├── build.json
-├── database/
-│   ├── database.json
-│   └── ida/Wow.i64
-├── profile/                 # 只放用户确认保存的 profile
-│   ├── player-state.json
-│   └── combat-state.json
-└── runtime/<session-id>/    # 当前任务证据
-    ├── target.json
-    ├── debug.json
-    ├── dump/manifest.json
-    ├── ida-evidence.json
-    ├── candidate.profile.json
-    └── verify.json
-```
+## 最小示例
 
-buildKey 只能作为单层目录名使用。保留 `@`、点和连字符；拒绝路径分隔符、`..` 和其他会改变目录层级的字符。不同 build 必须使用不同目录。
+下例全部地址、build 和哈希都是合成测试数据，不能用于游戏。它读取全局指针，再从对象 +0x20 读取 f32。
 
-## 临时结果
+~~~json
+{
+  "schema": "wowdump.profile.v1",
+  "id": "example-stat",
+  "buildKey": "fixture@1",
+  "executableSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "readerStatus": "candidate",
+  "confidence": "candidate",
+  "module": { "name": "Fixture.exe" },
+  "fields": {
+    "exampleValue": {
+      "root": { "rva": "0x100", "dereference": true },
+      "pointerChain": [{ "offset": "0x20", "dereference": false }],
+      "type": "f32"
+    }
+  },
+  "evidence": [{ "source": "synthetic-example", "semanticVerified": false, "restartVerified": false }]
+}
+~~~
 
-动态导出、反汇编候选和未确认的 profile 放到本次任务的临时目录，例如：
+替换为本轮证实的身份、RVA、偏移和类型。直接模块标量无需解引用。数组使用 layout.kind:"array"、item、stride、count；动态计数格式先核对当前 Reader 并设置 maxItems。结构使用 layout.kind:"struct" 和 fields。复杂布局先核对当前实现或验证用例，不自创 schema。
 
-```text
-~/.wowdump/<buildKey>/runtime/<session-id>/
-```
+## 当前 verify 状态限制
 
-它们不是持久化 profile，任务结束后可以清理。不要把候选文件直接写入 `<buildKey>/profile/`。
+CLI 的 verify 调用同一个 ProfileEngine，要求 readerStatus:"reader_ready"；直接传 candidate 会返回 PROFILE_NOT_READY。
 
-## 保存流程
+保留 candidate.profile.json 原件。证据足够进行小范围读取后，在 runtime session 创建 verification-input.profile.json，仅为适配执行门槛设置 readerStatus:"reader_ready"，confidence 与 evidence 仍保持候选。用此副本执行 verify，单独保存 verify.json；状态标签不能证明验证完成。若新版本正式支持 candidate 验证，使用其正式流程。
 
-1. 汇总 CDB 与必要的 IDA/iced 证据，检查 buildKey、模块、哈希、RVA 和字段证据一致；不要求固定先后顺序。
-2. 向用户展示候选 profile 的路径、字段和验证结果，询问是否保存为该 build 的持久化 profile。
-3. 用户确认后，将候选复制到 `~/.wowdump/<buildKey>/profile/<profile-id>.json`，保留 `buildKey`、来源和验证证据。
-4. 目标文件已存在时先询问覆盖，或使用新的 profile-id；不要静默覆盖。
-5. 后续读取优先使用这个绝对路径，或用 `wowdump profiles --build <buildKey>` 列出它。Reader 只读取 profile，不读取 `database/ida` 和 `runtime/dump/*.bin`。
+语义验证见 [evidence-workflow.md](evidence-workflow.md)。验证失败时保留错误和候选状态，不复制到持久化目录。
 
-profile 只对记录的 buildKey 和模块布局有效。发现 buildKey 不匹配时停止读取并重新走分析流程，不修改旧 profile。
+## 保存与复用
+
+统一在 ~/.wowdump/<buildKey>/：
+- database/ 保存每个 build 的静态数据库。
+- runtime/<session>/ 保存 target、dump、静态证据、候选、验证副本和 verify.json。
+- profile/ 保存用户确认的已验证 profile。
+
+buildKey 使用 targets 返回的安全单层目录名。profile 必须带真实 executableSha256；build/hash 不匹配重新分析，缺少哈希不视作匹配。
+
+展示字段、单位、验证范围和绝对路径。用户确认后复制到 profile/<id>.json；已有保存授权直接沿用。覆盖现有文件前确认覆盖范围。未做重启测试时保留限制。profile 不保存 moduleBase、堆绝对地址或 IDA session ID。

package/skills/wowdump/references/request-schema.md

@@ -1,28 +1,12 @@
-# 字段请求格式
+# 确定字段含义
 
-先把用户要查的内容写成一个请求文件。字段名是本次任务的目标，不是地址；地址由 dynamic 证据和 IDA Pro MCP/iced-x86 局部分析产生。
+通常在任务记录中列明目标即可；无需为每次查询创建额外请求 JSON。这些描述不是 CLI 接受的 schema。
 
-```json
-{
-  "schema": "wowdump.read-request.v1",
-  "target": { "pid": 33976, "buildKey": "retail@12.1.0.69587", "module": "Wow.exe" },
-  "fields": [
-    { "name": "playerAuras", "kind": "aura", "scope": "player", "direction": "both" },
-    { "name": "nearbyEnemies", "kind": "unit-list", "scope": "around-player" },
-    { "name": "cooldowns", "kind": "cooldown", "scope": "player" }
-  ],
-  "limits": { "maxUnits": 64, "maxAuras": 64, "maxEvents": 100, "durationMs": 5000 },
-  "debug": { "kind": "breakpoint", "rva": "0x...", "maxHits": 3, "durationMs": 3000 }
-}
-```
+| 用户目标 | 需要确定 |
+| --- | --- |
+| 角色属性 | 玩家；暴击/急速/精通/全能；等级数值还是百分比；当前有效值还是基础值 |
+| Buff/Debuff | 玩家还是目标；有益/有害；持续时间单位和层数 |
+| 技能冷却 | 技能 ID；剩余时间、完整冷却还是充能；区分 GCD |
+| 附近敌人 | 范围、单位类型、敌对/存活条件；姓名板集合不等于附近全部敌人 |
 
-`kind` 和 `scope` 帮助选择脚本，不会被 CLI 当作固定语义。脚本可以返回不同的数据结构，但必须包含模块基址和每个候选的地址、RVA 或字节线索。
-
-常见字段映射：
-
-- 我方 Buff：`kind: "aura", scope: "player", direction: "helpful"`
-- 敌方 Debuff：`kind: "aura", scope: "target", direction: "harmful"`
-- 技能冷却：`kind: "cooldown", scope: "player"`
-- 周围敌人：`kind: "unit-list", scope: "around-player"`
-
-这些是查询意图。没有 reader-ready profile 定义前，不要把 CDB 一次性证据中的绝对地址交给长期 reader。
+用户已说“暴击全能那些”时，先按面板当前二级属性组织字段；等级与百分比分开命名。只在含义影响分析且上下文不足时询问。每个字段记录原始类型、单位、转换公式和观测条件；原始数值不带单位时不要猜换算系数。

package/skills/wowdump/references/windbg.md

@@ -36,7 +36,7 @@ wowdump analyze debug `
   --confirm
 ```
 
-默认脚本使用硬件执行断点，只记录 RIP、RCX、RDX、R8、R9、RSP、返回地址和线程 ID。命中达到上限或超时后立即清除断点并退出 CDB。broker 用 `VirtualQueryEx` 检查入口页和返回地址页，结果写入 session 的 `debug.json`。
+默认脚本使用硬件执行断点，只记录 RIP、RCX、RDX、R8、R9、RSP、返回地址和线程 ID。当前脚本在下一次命中时才检查计数上限，达到记录上限不保证立即退出。broker 用 `VirtualQueryEx` 检查入口页和返回地址页，结果写入 session 的 `debug.json`。
 
 ## 其他调试命令
 
@@ -53,3 +53,11 @@ wowdump analyze debug `
 ```
 
 命令和参数通过 `spawn(file, args, {shell:false})` 传递；不要把它们拼成 shell 字符串。调试命令必须有时限，输出会截断到证据上限。
+
+## 当前生命周期限制
+
+当前 CLI 使用 -p 附加、-cf 命令文件，默认末尾追加 q，没有默认选择非侵入式附加。shell:false 只描述启动方式，不限制 CDB 命令本身的作用。
+
+超时会终止 CDB，并在 Windows 使用 taskkill /T /F 清理进程树；这不能证明正常 detach。detached:true 当前是固定输出，也不是证据。不要把 q 当成经过实测的正常脱离保证。
+
+执行前核对当前版本的附加方式、退出命令和时限。断点退出与真实目标存活尚未完成端到端验证；字段定位先使用静态证据和 Reader，调试退出验证先在可控测试进程完成。超时后记录目标是否存活和可响应，不仅看退出码。透传参数会改变附加模式，避免重复提供冲突的目标参数。

package/skills/wowdump/references/workflow.md

@@ -1,30 +1,23 @@
-# 混合分析决策
+# 从目标字段到地址
 
-## 先确认目标
+## 建立本轮证据
 
-1. `wowdump targets` 获取 PID、路径、buildKey、哈希和模块信息。
-2. `wowdump database status --build <buildKey>` 确认静态数据库是否可复用。
-3. 运行时证据都放在当前 build 的 runtime session；profile 只保存稳定的 RVA、相对偏移、类型和边界。
+运行 targets 后确认身份，检查 database status。为当前任务保留 runtime session，记录目标字段、已证实事实、候选、已排除假设和下一项证据缺口。继续任务时读取这份记录，避免重复全量扫描。
 
-## 每轮只解决一个证据缺口
+## 定位字段
 
-| 缺口 | 下一步 | 成功标准 |
-| --- | --- | --- |
-| 不知道进程和模块 | `targets`、broker `modules` | PID、路径、模块基址明确 |
-| 需要 PE 样本 | `analyze runtime --kind dump` | manifest 和段二进制已落盘 |
-| 需要确认函数入口 | IDA/iced 局部分析 | 得到单个函数 RVA 和调用关系 |
-| 需要观察调用参数 | `analyze debug --kind breakpoint` | 获得有限次数寄存器、返回地址和页证据 |
-| 需要其他诊断 | `analyze debug --kind command` | CDB 命令输出带时限且有证据文件 |
-| 需要稳定字段 | `analyze runtime --kind verify` | broker 实读成功，类型和边界一致 |
+从与目标相关的字符串、符号、调用点或已有本轮证据开始，按需使用 IDA；具体输入和地址映射见 [disassemble.md](disassemble.md)。
 
-## 证据门槛
+- 名称字符串只说明存在该名称。检查其引用、邻近表项、注册调用和重定位线索，确定哪里存放函数指针。没有直接 XREF 时，检查 RIP 相对引用和表间接访问；不要把字符串 RVA 当作函数入口。
+- 沿已确认函数分析参数来源、调用者、返回路径和实际内存访问。区分 getter、包装函数和格式化函数；看见名称或一条 load 指令不足以证明字段含义。
+- 沿对象来源回溯到可解释的根：模块全局指针、索引表或对象容器。记录每次“加偏移”及“解引用”。函数 RVA 与堆对象字段偏移分开记录。
+- 区分读取原始字段和计算结果。若返回值由多个量计算，记录各依赖及公式；Reader 没有相应表达能力时明确返回原始量，不把它标成最终面板值。
+- 用页面查询和小范围读取检验指针链、类型、容器边界。需要调用证据时先读 [windbg.md](windbg.md) 中的当前限制。
 
-`reader_ready` 必须同时满足：build/hash 匹配；RVA 有静态或运行时证据；root、指针链、字段类型和上限可解释；broker Reader 实读成功；结果与目标字段一致。否则保留 `candidate`，不填猜测地址。
+一次只扩大足以检验假设的范围，但没有找到候选时继续换证据路径：字符串引用失败可检查注册表和调用者；入口存在但对象不明可回溯根；值不匹配可检查类型、派生公式和状态条件。每次记录排除理由。工具失败不等于字段不存在。
 
-## 运行约束
+## 转交 Reader
 
-- CDB 只由 broker 启动，使用 `spawn` 参数数组和命令文件，绝不经过 shell。
-- 断点只接受单个已确认入口，不修改入口字节，不调用未知函数，不做大范围读取。
-- 每次 debug 都设置命中上限和时限；超时清理 CDB、断点和临时命令文件。
-- `memory regions` 先用 `VirtualQueryEx` 确认页面，再进行有界 `memory read`。
-- 只有用户确认后的 profile 才复制到 `~/.wowdump/<buildKey>/profile/`。
+根据证据填写 [profiles.md](profiles.md) 的真实字段结构，执行 [evidence-workflow.md](evidence-workflow.md) 的验证。页面可读、数值合理和名称相似都不能单独证明语义正确。
+
+真正缺少目标进程、工具入口或可观察状态时，明确缺少的条件并保留进度；不要以“少量扫描没结果”代替结论。