# process.memoryMap：进程内存诊断与虚拟地址空间地图

用于排查 **内存不足、连续大块分配失败、地址空间碎片、保留区过大和内存增长**。不用临时编写 VirtualQuery 扫描代码。

只查询当前或指定 **x86 进程**的区域元信息，不读取目标内存内容，不触碰保护页，不分配、释放或修改目标内存。基础 `process` 不需要修改。

## 最短调用

```aardio
import process.memoryMap;
var report,err = process.memoryMap.diagnose();
if(!report) return {error=err};
return report;
```

`null` / 省略目标参数只表示**执行代码的当前进程**，不是父进程或宿主。指定其他进程时传正整数 PID，或有效的 `process` 对象。

查看简短文本，并评估新预留 128 MiB 连续地址空间：

```aardio
import process.memoryMap;
var mm = process.memoryMap;
var report,err = mm.diagnose(,{
    requestBytes = 128 * 1048576;
    top = 5;
    resolveNames = true;
    threadCount = true;
});
if(!report) return {error=err};
return {text=mm.format(report); complete=report.complete};
```

**先看 `complete`，再看 `findings`、`summary`、`request`。** 采集失败返回 `null,err`；扫描中途停止仍返回已采集的数据，但 `complete=false`。排行榜的 `displayTruncated` 只表示展示截断，不代表扫描不完整。

## 选哪个入口

| 任务 | 入口 |
| --- | --- |
| AI 首次诊断、需要简短报告 | `diagnose(target, options)` |
| 保存地址布局、之后对比 | `snapshot(target, options)` |
| 离线分析已有快照 | `analyze(snapshot, options)` |
| 查看操作前后的变化 | `diff(before, after, options)` |
| 解释一个地址的页状态、保护、分配基址 | `query(target, address, options)` |
| 将已有结果显示成 CRLF 文本 | `format(result)` |

所有结果均为可 JSON 序列化的数据表，无须调用 `close` / `free`。库另开只查询/同步权限的句柄并自行关闭，不接管调用者的进程句柄。库不会提升权限；无权查询时直接返回错误。

## 能得到什么

- 空闲、仅保留、已提交区域的字节统计；按 private / image / mapped / unknown 分类。
- 最大连续空闲区域；按分配粒度对齐、按页向上取整后的连续预留候选。
- 最大分配、最多提交、最多保留、最大空闲区、带保护页的私有分配、重复尺寸榜单。
- 可选 NT 格式映像/映射文件名、工作集/私有提交量计数器、OS 线程数。
- 快照差异：新增提交、退回保留、释放、保护属性及分配基址变化；区域仅拆分不会产生伪分配事件。
- PID + 创建时间身份检查、扫描范围及中断原因、自观测干扰提示。

## 三个必要限制

1. `MEM_COMMIT` 区域字节数不是驻留 RAM；`private.virtualBytes` 包含仅保留空间。
2. 带 `PAGE_GUARD` 的分配不一定是线程栈；增长也不是泄漏证明。
3. 这是逐区域、非原子快照。默认不暂停进程，候选地址不能保证之后实际分配成功。

版本：`0.1.0`。首版仅实现 x86 目标；已在 Windows 11 x64 + 32 位 aardio 验证。64 位、ARM32、ARM64 目标明确拒绝，不会静默只扫描低 4 GiB。LAA 查询依赖 Native API，失败时拒绝猜测范围；详见兼容边界。

## 文档地图

- [API 与数据结构](api.html)
- [诊断工作流与 AI 调用](workflows.html)
- [统计口径与兼容边界](limits.html)