诊断工作流与 AI 调用

1. 内存不足或大块分配失败

先获取事实，不要先猜测泄漏，不要通过清理工作集改变现场。

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

顺序：

核对 target.pid 和 collectorPid。
检查 complete、stopReason、scanRange.fullAddressSpace。
看 request.status；未发现时再区分总量不足、碎片和对齐限制。
看分配榜单，确定地址空间主要分布在哪里。
将区域提交量与 counters 分开理解。候选存在仍可能因系统提交限额、配额、堆内部机制等原因分配失败。

2. 保存操作前后的快照

下面两个脚本用于独立采集进程，启动参数 --pid=目标PID 必须明确指定。样例路径位于采集程序的应用目录下。

操作前：

import process.memoryMap;
import JSON;
var pid = tonumber(_ARGV.pid);
if(!pid) return {error="请指定 --pid=目标PID，不能省略目标。"};
var before,err = process.memoryMap.snapshot(pid);
if(!before) return {error=err};
if(!before.complete) return {error="扫描不完整"; detail=before.stopReason};
var ok = JSON.save("/memory-diagnostics/before.json",before,true);
return {saved=ok; target=before.target};

完成需要观察的操作后：

import process.memoryMap;
import JSON;
var mm = process.memoryMap;
var pid = tonumber(_ARGV.pid);
if(!pid) return {error="请指定 --pid=目标PID。"};
var before,err = JSON.load("/memory-diagnostics/before.json");
if(!before) return {error=err};
var after,err = mm.snapshot(pid);
if(!after) return {error=err};
var delta,err = mm.diff(before,after,{top=10});
if(!delta) return {error=err};
JSON.save("/memory-diagnostics/after.json",after,true);
JSON.save("/memory-diagnostics/diff.json",delta,true);
return {text=mm.format(delta); delta=delta.delta};

加载器、线程池、缓存和运行库可能延迟释放资源。要排查增长，建议观察：基线 → 操作一次 → 释放 → 重复多次 → 等待稳定。持续增长是线索，不是泄漏证明。

若必须在目标内采集，第二次快照会包含第一份快照仍驻留所造成的影响。库会提示 SELF_OBSERVATION；不要把快照对象自身误认为业务泄漏。

3. 离线重看同一现场

import process.memoryMap;
import JSON;
var saved,err = JSON.load("/memory-diagnostics/before.json");
if(!saved) return {error=err};
var report,err = process.memoryMap.analyze(saved,{
    requestBytes = 64 * 1048576;
    top = 8;
});
if(!report) return {error=err};
return process.memoryMap.format(report);

更改分析选项不重新扫描目标，因此可用同一份快照分别评估 64 MiB、128 MiB 等请求。

4. 解释错误日志中的地址

import process.memoryMap;
var pid = tonumber(_ARGV.pid);
var address = tonumber(_ARGV.address);
if(!pid || address===null) return {error="请提供 --pid 和 --address。"};
var info,err = process.memoryMap.query(pid,address,{resolveNames=true});
if(!info) return {error=err};
return {text=process.memoryMap.format(info); detail=info};

这里不解引用地址，不触发 PAGE_GUARD。查询结果也不保证之后能安全读取该地址。

5. Autos 的 execute_code process 模式

process 模式创建独立进程。省略目标调用 diagnose()，诊断的就是这个新进程。
要看 Autos 宿主，先在宿主取得 GetCurrentProcessId()，再将该 PID 显式传给子进程。
process 模式不自动收集 return，必须显式写入文件或通过 IPC 回传；不要假设工具会自动回传报告。
跨工具使用文件时注意应用基准目录：建议独立采集代码指定 appBaseDirectory="/"，让代码内的 /文件 与工具读取的工作区 /文件 对应。

可在子进程运行的采集脚本（启动时传 --pid、--output）：

import process.memoryMap;
import JSON;
var pid = tonumber(_ARGV.pid);
var output = _ARGV.output;
if(!pid || !#output) return;
var report,err = process.memoryMap.diagnose(pid,{top=5});
JSON.save(output,{report=report; error=err},true);

报告包含实际 target.pid，接收端仍应核对目标与创建时间，不能只根据文件名推测诊断对象。

6. 给 AI 的检索描述

可把下列短描述加入自己的库清单或工具知识索引；不需要修改基础 process：

process.memoryMap：进程内存诊断。排查内存不足、连续分配失败、虚拟地址空间碎片、保留区过大及内存增长；支持当前/指定 x86 进程、LAA 高地址、保护页分配、快照对比。首先查询库参考，再用 diagnose；保存现场用 snapshot。只查询元信息，不读写内存内容。

不需要安装多个含义相近的别名库，也不要依赖某个固定进程 PID 或某次扫描的统计值。

Markdown 格式