# process.memoryMap 库模块帮助文档
AI快速选择入口

## 首次排查内存不足/OOM与碎片 ```aardio import process.memoryMap; var report,err = process.memoryMap.diagnose(,{requestBytes=128*1048576;top=5}); if(!report) return {error=err}; return report; ``` 先核对 target.pid、collectorPid、complete 和扫描范围，再看 findings 与 request。 省略目标只表示执行代码的当前进程；在独立子进程中诊断宿主必须显式传入宿主 PID。 ## 保存和复查现场 snapshot 返回完整区域数据；analyze 离线分析；diff 对比同一进程实例、同范围的完整快照；format 不重新采集。 用 JSON.save/JSON.load 保存和恢复纯数据，无须释放句柄。诊断报告默认仅显示榜单前几项。 ## 不作无证据的结论 区域提交不是物理 RAM，保护页分配不是线程栈计数，增长不是泄漏证明，候选空闲区不保证分配成功。 只支持 x86 目标；不能确定运行时 LAA 或遇到不支持的架构时明确失败，不静默截断。

[进程内存诊断与虚拟地址空间地图](https://www.aardio.com/zh-cn/docs/library/process/memoryMap/) ## process.memoryMap 成员列表 # 进程内存诊断：内存不足、连续大块分配失败、地址空间碎片、保留区与内存增长。 当前或指定 x86 进程，只查询区域元信息、不读取内存内容。 AI 首选 diagnose；保存及前后比较使用 snapshot + diff。 ### process.memoryMap.analyze() # [返回对象:memoryMapReportObject](#memoryMapReportObject) ### process.memoryMap.analyze(snapshot,options) # 离线分析快照，不查询进程，不修改输入。 options: top=8（0~1000）、requestBytes、alignment（分配粒度的正整数倍）。 失败返回 null,err。 ### process.memoryMap.diagnose() # [返回对象:memoryMapReportObject](#memoryMapReportObject) ### process.memoryMap.diagnose(target,options) # 一次获得精简诊断表；target 为 PID/process 对象，省略仅表示当前进程。 options 可指定 requestBytes、top、resolveNames、startAddress、endAddress、timeoutMs、maxRegions、counters、threadCount。 失败返回 null,err；扫描中断则报告 complete=false。 ### process.memoryMap.diff() # [返回对象:memoryMapDiffObject](#memoryMapDiffObject) ### process.memoryMap.diff(before,after,options) # 按地址区间比较完整快照，不把区域拆分误认为分配变化。 检查进程创建身份及相同扫描范围；拒绝不完整快照。 options.top=20；仅截断展示，不截断汇总。增长不是泄漏证明。失败返回 null,err。 ### process.memoryMap.format(report,options) # 将 snapshot/diagnosis/diff/query 格式化为简短 CRLF 文本，不重新扫描。 只有输入 snapshot 时 options 才传给 analyze。失败返回 null,err。 ### process.memoryMap.query() # [返回对象:memoryMapQueryObject](#memoryMapQueryObject) ### process.memoryMap.query(target,address,options) # 查询一个地址（数值/指针）所在页向后的同属性区域后缀。 target 可省略占位为 null；options.resolveNames 可解析映像/映射文件名。 不读取内存内容，不保证地址之后可安全访问。失败返回 null,err。 ### process.memoryMap.snapshot() # [返回对象:memoryMapSnapshotObject](#memoryMapSnapshotObject) ### process.memoryMap.snapshot(target,options) # 采集可 JSON 序列化的完整区域快照，无句柄资源需要释放。 options: startAddress/endAddress（左闭右开）、maxRegions=131072、timeoutMs=5000、resolveNames=false、counters=true、threadCount=false。 失败返回 null,err；务必检查 complete。 ### process.memoryMap.version # 当前库版本 ## memoryMapDiffObject 成员列表 # ### memoryMapDiffObject.changes # 变化最大的若干地址区间及前后状态，非分配事件日志 ### memoryMapDiffObject.delta # 全范围统计的 after-before 增量 ### memoryMapDiffObject.displayTruncated # 仅详情是否截断；汇总没有截断 ### memoryMapDiffObject.transitions # 状态转换字节数，包括 committed->committed 的属性变化 ## memoryMapQueryObject 成员列表 # ### memoryMapQueryObject.region # 指定地址所在页向后的区域后缀，不一定覆盖整个分配 ## memoryMapReportObject 成员列表 # ### memoryMapReportObject.complete # 扫描是否完整，必须优先检查 ### memoryMapReportObject.findings # 有证据、有边界的诊断发现：code,severity,message,evidence,advice ### memoryMapReportObject.limitations # 解释结果必须遵守的统计口径与限制 ### memoryMapReportObject.rankings # 最大分配/提交/保留/空闲区/保护页私有分配/重复尺寸榜；各榜有 items,total,displayTruncated ### memoryMapReportObject.request # 指定 requestBytes 时的连续预留评估；candidateObserved 不承诺实际分配成功 ### memoryMapReportObject.summary # 原始字节统计、byKind 分类、最大连续空闲区域、保护页分配数量 ### memoryMapReportObject.target # 实际目标身份 ### memoryMapReportObject.warnings # 采集警告，包括自观测及可选计数器不可用 ## memoryMapSnapshotObject 成员列表 # ### memoryMapSnapshotObject.collectorPid # 采集器 PID；与 target.pid 相同则存在自观测干扰 ### memoryMapSnapshotObject.complete # 是否完成整个请求范围；true 不表示原子快照 ### memoryMapSnapshotObject.counters # 可选进程级计数器，不能与区域提交量或物理内存混为一谈 ### memoryMapSnapshotObject.observedEndAddress # 实际覆盖到的末端地址（不包含），中断时小于请求末端 ### memoryMapSnapshotObject.regions # 全部已观察区域，包含 free/reserved/committed；字节及地址为无符号数值 ### memoryMapSnapshotObject.scanRange # startAddress/endAddress，末端不包含；fullAddressSpace 区分全地址空间和自定义范围 ### memoryMapSnapshotObject.stopReason # `completed/maxRegions/timeout/queryFailed/invalidRegion/targetExited` ### memoryMapSnapshotObject.target # 目标 pid、name、architecture、creationTimeKey、imagePath