一、输入格式问题

1.1 不支持 .insight 格式输入

问题: 用户提供的 .insight 文件是一个 Zip 压缩包，内含多个 .heapsnapshot 文件、.db 文件和 manifest.json。但 SKILL.md 的 Step -1 和 Step 0 只支持 .rawheap 和 .heapsnapshot 两种输入格式，完全没有提及 .insight 格式。

影响: 需要手动 unzip 解压 .insight 文件，手动从 manifest.json 中解析出 heapsnapshot 文件路径和元数据信息（设备型号、PID、应用名等），增加了额外的前置工作。

建议: 在 SKILL.md 中新增 Step -2，支持 .insight 格式自动解压和元数据提取。

---

1.2 不支持双快照对比分析

问题: .insight 文件中包含两个 .heapsnapshot 文件（间隔约 29.7 秒），这是用于对比分析内存增长趋势的标准场景。但 SKILL.md 的整个流程（Step 0 ~ Step 4）只针对单个 heapsnapshot 进行聚类和泄漏识别，完全没有快照对比（Diff）的能力。

影响: 无法自动识别两次快照间增长的业务对象（如 Metadata 从 257→479、ChannelzCallTracker 从 242→458），必须手动编写 Python 脚本进行对比分析。

建议: 在 SKILL.md 中新增 Step 4.5（快照对比），支持：

• 对两个 heapsnapshot 分别聚类后对比对象数量变化
• 自动识别增长率超过阈值的对象类型
• 生成增长趋势表

---

二、工具链问题

2.1 heap_cluster 内置工具 OOM 崩溃（致命问题）

问题: SKILL Step 0 要求使用内置的 heap_cluster_arm64 二进制工具对 heapsnapshot 进行聚类。但在 macOS 上处理 20-22 MB 的 heapsnapshot 文件时，该工具被系统 OOM Killer 杀死（内存占用过大）。

影响: 这是 SKILL 流程的关键瓶颈——Step 0 失败导致后续所有步骤（Step 1 数据校验、Step 2 规则匹配、Step 3 故障模式分类）都无法正常执行，因为它们都依赖于 heap_cluster 的聚类输出。

临时方案: 手动编写 Python 脚本解析 heapsnapshot JSON，自行实现节点/边解析、Retained Size 近似计算（BFS 支配树）、引用链构建等功能。

建议:

1. 优化 heap_cluster 的内存使用，支持流式处理大文件
2. 在 SKILL.md 中提供 heap_cluster 失败时的降级方案（如 Python 脚本替代分析）
3. 增加工具内存占用预估和文件大小限制说明

2.2 SKILL.md Step 0 仅文档 Windows 路径

问题: SKILL.md Step 0 的命令示例只写了 scripts/windows/heap_cluster.exe，没有提供 macOS 和 Linux 的路径。虽然实际存在 scripts/macos/heap_cluster_arm64 和 scripts/macos/heap_cluster_x64，但文档中未提及。

对比: Step -1（rawheap 转换）则完整列出了 Windows/Linux/macOS ARM64/macOS X64 四种平台的命令，格式不一致。

建议: 统一 Step 0 的文档格式，补充所有平台的命令示例，与 Step -1 保持一致。

2.3 缺少 heapsnapshot 格式解析文档

问题: SKILL.md 假设用户/Agent 拿到的是 heap_cluster 的聚类输出，没有提供 heapsnapshot 原始 JSON 格式的解析说明。当 heap_cluster 失败后，需要自行逆向分析 V8 兼容的 heapsnapshot 格式：

• meta.node_fields: 8 个字段（type, name, id, self_size, edge_count, trace_node_id, detachedness, native_size）
• meta.edge_fields: 3 个字段（type, name_or_index, to_node）
• nodes[] 和 edges[] 是扁平数组，需要按 field 数量分组
• to_node 是字节偏移而非节点索引（需除以 node_fields.length）
• 边的 name 对于不同 edge type 有不同含义（property/context/internal 用 strings 索引，element 用数字）

影响: 手动解析格式耗费大量时间，容易出错。

建议: 在 references/ 下新增 heapsnapshot_format.md，说明 V8 heapsnapshot 的 JSON 结构、字段含义、节点/边的索引方法。

---

三、脚本工程问题

3.1 Python heredoc 内联脚本语法错误（多次发生）

问题: 分析过程中多次通过 cat << 'EOF' > script.py 的 heredoc 方式在终端内编写 Python 脚本，频繁出现括号/字典/字符串转义等语法错误，导致脚本无法执行。

根因: heredoc 方式下，Python 代码中的特殊字符（$, \, `）容易被 shell 解释，且多行字典/列表的缩进在 heredoc 中容易出错。

建议: 直接使用 create_file 工具创建 Python 脚本文件，避免 heredoc 方式。

3.2 ManagerMap 实例对象检测逻辑 Bug

问题: 第一版分析脚本 analyze_diff.py 未能正确找到 ManagerMap 实例对象。原因是脚本使用了 node_type == 'object' 的精确匹配，但实际 heapsnapshot 中 ManagerMap 实例的 type 编号对应的名称可能不完全一致，或者节点名匹配条件过严。

修复: 在 analyze_diff2.py 中放宽匹配条件，使用 node_name 包含 ManagerMap(line:11)[entry] 且 self_size == 64 的组合条件定位实例对象。

建议: 在 references/ 中补充常见对象类型的匹配模式说明。

3.3 UUID 检测逻辑缺陷

问题: 第一版脚本报告 "Total unique UUIDs across all Maps: 0"，即未检测到任何 UUID。原因是 UUID 作为 Map key 嵌在 edge name 字符串中（格式如 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxresponse），脚本没有正确提取 UUID 前缀。

修复: 在 analyze_maps.py 中改用 len(name) > 36 and '-' in name 条件，取前 36 字符作为 UUID，后缀作为事件类型。

影响: 首次分析结果完全错误（显示 0 个请求 ID），差点导致泄漏趋势误判。

建议: 在 heapsnapshot 格式文档中说明 Map 类型节点的 edge 命名规则（key 直接作为 edge name）。

---

四、分析能力缺失

4.1 无 Retained Size 计算能力

问题: SKILL 流程依赖 heap_cluster 输出 Retained Size，但 heap_cluster 失败后，SKILL 没有提供任何替代的 Retained Size 计算方法。Retained Size 需要构建支配树（Dominator Tree），这是一个非平凡的图算法。

临时方案: 手动实现 BFS-based 支配树近似算法，但精度可能不如 heap_cluster 的精确实现。

建议: 在 scripts/ 下提供 Python 版本的 Retained Size 计算脚本作为降级方案。

4.2 无引用链自动构建能力

问题: SKILL Step 2 要求分析"引用链（对象的路径 -> GC Root）"，但 SKILL 没有提供从 heapsnapshot 原始数据自动构建引用链的工具。heap_cluster 的输出包含引用链，但工具失败后无法获取。

临时方案: 手动编写 BFS 从目标节点反向遍历到 SyntheticRoot，构建引用链。

建议: 在 scripts/ 下提供引用链构建脚本。

4.3 故障模式匹配依赖人工判断

问题: SKILL Step 3 要求根据 distance=1 节点名匹配故障模式（FM-01 ~ FM-04），但这一步骤完全依赖人工阅读 fault-modes.md 后手动判断，没有自动化匹配脚本。

建议: 提供自动化故障模式匹配脚本，输入引用链，输出匹配的 FM 编号。