已合并
jscrash-analysis: SourceMap 反解前新增 UUID/构建指纹校验 #40
Vitamins创建于 15 天前
jscrash-analysis: SourceMap 反解前新增 UUID/构建指纹校验 #40
已合并
共 3 个文件变更+32-9
| @@ -39,7 +39,8 @@ metadata: | |||
| 39 | 2. SourceMap 反解门禁 | 39 | 2. SourceMap 反解门禁 |
| 40 | - 分析调用栈前先判断其是否已还原到源码。出现 `Cannot get SourceMap info, dump raw stack`、构建缓存路径、混淆函数名，或行列号无法对应源码时，视为未完成 SourceMap 反解。 | 40 | - 分析调用栈前先判断其是否已还原到源码。出现 `Cannot get SourceMap info, dump raw stack`、构建缓存路径、混淆函数名，或行列号无法对应源码时，视为未完成 SourceMap 反解。 |
| 41 | - 用户提供与故障版本匹配的 `sourceMaps.json`、SourceMap 归档目录或工程构建产物时，读取 `references/sourcemap-symbolication.md`，优先使用仓库内置 `scripts/hstack/` 生成反解后的堆栈，再继续根因分析。 | 41 | - 用户提供与故障版本匹配的 `sourceMaps.json`、SourceMap 归档目录或工程构建产物时，读取 `references/sourcemap-symbolication.md`，优先使用仓库内置 `scripts/hstack/` 生成反解后的堆栈，再继续根因分析。 |
| 42 | - - 启用了名称混淆时，同时使用同一构建产物中的 `nameCache.json` 还原方法名。SourceMap、nameCache、应用版本、VersionCode、product、模块和构建模式必须匹配，不得混用其他版本的映射文件。 | 42 | + - 反解前必须先做 UUID / 构建指纹校验：比对故障日志中的 `Fingerprint`（构建指纹/UUID 字段）与 SourceMap 产物携带的构建指纹（如 `build-info.json` 或 sourcemap 元数据 `fingerprint`）。一致才允许反解；不一致时不得使用该产物，按“未提供匹配 SourceMap”处理，并要求补充与故障构建指纹一致的映射产物。 |
| 43 | + - 启用了名称混淆时，同时使用同一构建产物中的 `nameCache.json` 还原方法名。SourceMap、nameCache、应用版本、VersionCode、product、模块、构建模式和构建指纹必须匹配，不得混用不匹配版本的映射文件。 | ||
| 43 | - 后续应用帧、源码位置和责任代码判断以反解后的堆栈为主，同时保留原始栈帧作为证据。若反解结果未产生有效应用源码帧，不得标记为反解成功。 | 44 | - 后续应用帧、源码位置和责任代码判断以反解后的堆栈为主，同时保留原始栈帧作为证据。若反解结果未产生有效应用源码帧，不得标记为反解成功。 |
| 44 | - 用户未提供 SourceMap 时仍可使用 raw stack 初步分析，但必须标记“未反解”、降低源码定位可信度，并将补充匹配版本 SourceMap 后重新分析作为第一项建议。 | 45 | - 用户未提供 SourceMap 时仍可使用 raw stack 初步分析，但必须标记“未反解”、降低源码定位可信度，并将补充匹配版本 SourceMap 后重新分析作为第一项建议。 |
| 45 | 46 | ||
| @@ -97,8 +98,10 @@ metadata: | |||
| 97 | - 错误信息：<Error message 原文> | 98 | - 错误信息：<Error message 原文> |
| 98 | - 错误码：<Error code，若有> | 99 | - 错误码：<Error code，若有> |
| 99 | - 页面/Ability：<page 或日志中的页面信息，若有> | 100 | - 页面/Ability：<page 或日志中的页面信息，若有> |
| 100 | -- SourceMap 反解状态：<日志已还原 / hstack 反解成功 / 未提供映射文件 / 反解失败> | 101 | +- 日志 Fingerprint（构建指纹/UUID）：<Fingerprint 原文；日志缺失时写“缺失”> |
| 101 | -- SourceMap 输入：<sourceMaps.json / nameCache.json 所属版本和路径；未提供时写“未提供”> | 102 | +- UUID 校验：<一致 / 不一致 / 无法校验；一致时注明产物指纹与日志一致，不一致时给出两侧指纹值，无法校验时说明缺失字段> |
| 103 | +- SourceMap 反解状态：<日志已还原 / hstack 反解成功 / UUID 不匹配未反解 / 未提供映射文件 / 反解失败> | ||
| 104 | +- SourceMap 输入：<sourceMaps.json / nameCache.json 所属版本、构建指纹和路径；未提供时写“未提供”> | ||
| 102 | - 栈顶应用帧：<第一个应用栈帧> | 105 | - 栈顶应用帧：<第一个应用栈帧> |
| 103 | - 源码位置：<反解后的文件:行:列；未反解时标记为 raw stack 位置> | 106 | - 源码位置：<反解后的文件:行:列；未反解时标记为 raw stack 位置> |
| 104 | 107 | ||
| @@ -125,7 +128,7 @@ metadata: | |||
| 125 | 2. 故障模式库证据：<一级根因 -> 二级根因 -> 三级根因，必须与上方“故障模式库匹配”一致> | 128 | 2. 故障模式库证据：<一级根因 -> 二级根因 -> 三级根因，必须与上方“故障模式库匹配”一致> |
| 126 | 3. 调用栈证据：<反解后的栈顶应用帧及关键上游帧；系统/框架帧只作为传播路径> | 129 | 3. 调用栈证据：<反解后的栈顶应用帧及关键上游帧；系统/框架帧只作为传播路径> |
| 127 | 4. HybridStack / Native 桥接证据（如有）：<NAPI、libfs、libark_jsruntime 等关键帧及其意义> | 130 | 4. HybridStack / Native 桥接证据（如有）：<NAPI、libfs、libark_jsruntime 等关键帧及其意义> |
| 128 | -5. SourceMap 映射证据：<原始栈帧 -> 反解后源码帧；未反解时说明缺少的匹配构建产物> | 131 | +5. SourceMap 映射证据：<日志 Fingerprint 与产物指纹比对结果；原始栈帧 -> 反解后源码帧；未反解时说明缺少的匹配构建产物（版本/构建指纹）> |
| 129 | 132 | ||
| 130 | ### OOM 快照分析（仅在触发 jsleak-analysis Skill 时输出） | 133 | ### OOM 快照分析（仅在触发 jsleak-analysis Skill 时输出） |
| 131 | - 快照输入：<rawheap / heapsnapshot 文件及其与 Crash 的时间、PID、进程关联> | 134 | - 快照输入：<rawheap / heapsnapshot 文件及其与 Crash 的时间、PID、进程关联> |
| @@ -8,9 +8,13 @@ | |||
| 8 | 8 | ||
| 9 | 1. `node --version` 能正常运行，并使用当前系统对应的内置入口执行 `--help`：Windows 使用 `"<skill-root>\scripts\hstack\bin\hstack.bat" --help`，Linux/macOS 使用 `"<skill-root>/scripts/hstack/bin/hstack" --help`。 | 9 | 1. `node --version` 能正常运行，并使用当前系统对应的内置入口执行 `--help`：Windows 使用 `"<skill-root>\scripts\hstack\bin\hstack.bat" --help`，Linux/macOS 使用 `"<skill-root>/scripts/hstack/bin/hstack" --help`。 |
| 10 | 2. SourceMap 来自故障应用的同一版本、VersionCode、product、模块和构建模式。 | 10 | 2. SourceMap 来自故障应用的同一版本、VersionCode、product、模块和构建模式。 |
| 11 | -3. `sourceMaps.json` 通常位于模块构建目录的 `build/default/cache/default@CompileArkTS/esmodule/release/` 下。 | 11 | +3. `sourceMaps.json` 通常位于模块构建目录的 `build/default/cache/default@CompileArkTS/esmodule/release/` 下；`hstack` 实际读取该目录下后缀为 `.map` 的映射文件。 |
| 12 | 4. 启用名称混淆时，同时提供同一次构建生成的 `nameCache.json`；只需要恢复文件和行列号时可以不提供。 | 12 | 4. 启用名称混淆时，同时提供同一次构建生成的 `nameCache.json`；只需要恢复文件和行列号时可以不提供。 |
| 13 | 5. 不覆盖原始 crash 日志，反解结果写入独立输出目录。 | 13 | 5. 不覆盖原始 crash 日志，反解结果写入独立输出目录。 |
| 14 | +6. UUID / 构建指纹校验（必须）： | ||
| 15 | + - 故障日志必须包含构建指纹/UUID 字段（faultlogger 中一般为 `Fingerprint`），SourceMap 构建产物必须携带同一次构建的指纹（例如产物目录中的 `build-info.json` 或 sourcemap 元数据 `fingerprint` 字段）。 | ||
| 16 | + - 反解前先比对：日志 `Fingerprint` 与产物指纹一致才允许使用该产物反解；不一致时不得使用，视为“匹配版本的 SourceMap 缺失”，并要求用户补充与故障版本一致（版本、VersionCode、product、模块、构建模式、构建指纹均匹配）的映射产物。 | ||
| 17 | + - 只有 UUID/指纹一致仍不够，还必须同时满足第 2 条（版本等字段一致）；UUID 校验用于防止“同版本号但不同构建”的产物混用。 | ||
| 14 | 18 | ||
| 15 | ## 执行命令 | 19 | ## 执行命令 |
| 16 | 20 | ||
| @@ -48,13 +52,16 @@ Linux/macOS 使用： | |||
| 48 | 52 | ||
| 49 | ## 结果校验 | 53 | ## 结果校验 |
| 50 | 54 | ||
| 51 | -1. 对照原始栈和反解结果，确认至少一个关键应用帧被还原为可识别的源码文件、函数或行列号。 | 55 | +1. 反解前先完成 UUID / 构建指纹校验：日志 `Fingerprint`（或 UUID 字段）与产物 `build-info.json` / sourcemap 元数据的指纹必须一致，不一致的结果一律不得作为证据。 |
| 52 | -2. 使用反解后的第一个应用帧定位责任代码，同时在证据链保留对应原始栈帧。 | 56 | +2. 对照原始栈和反解结果，确认至少一个关键应用帧被还原为可识别的源码文件、函数或行列号。 |
| 53 | -3. 反解结果为空、仍只有构建缓存路径，或行列号无法对应源码时，标记为“反解失败”，优先核对映射文件版本和构建模式。 | 57 | +3. 使用反解后的第一个应用帧定位责任代码，同时在证据链保留对应原始栈帧。 |
| 54 | -4. SourceMap 版本无法确认时，不得把映射结果作为确定性根因证据。 | 58 | +4. 反解结果为空、仍只有构建缓存路径，或行列号无法对应源码时，标记为“反解失败”，优先核对映射文件版本、构建模式和构建指纹。 |
| 59 | +5. SourceMap 版本无法确认时，不得把映射结果作为确定性根因证据。 | ||
| 55 | 60 | ||
| 56 | ## 降级处理 | 61 | ## 降级处理 |
| 57 | 62 | ||
| 58 | - 内置 `hstack` 文件缺失：标记工具不完整，重新获取完整 Skill 仓库；Node.js 缺失时先安装或配置 Node.js。 | 63 | - 内置 `hstack` 文件缺失：标记工具不完整，重新获取完整 Skill 仓库；Node.js 缺失时先安装或配置 Node.js。 |
| 59 | - 未提供 SourceMap：基于 raw stack 初步定界，源码位置可信度降低，第一项建议要求补充匹配版本的 `sourceMaps.json`。 | 64 | - 未提供 SourceMap：基于 raw stack 初步定界，源码位置可信度降低，第一项建议要求补充匹配版本的 `sourceMaps.json`。 |
| 65 | +- 日志缺少 `Fingerprint`/UUID 字段或产物缺少构建指纹：无法完成 UUID 校验，标记“无法校验”，不得将映射结果作为确定性证据，并要求补充可核对指纹的产物。 | ||
| 66 | +- 日志与产物指纹不一致：标记“UUID/构建指纹不匹配”，禁止使用该产物反解；即使 hstack 能输出映射，也按“未提供匹配 SourceMap”处理，要求补充与故障构建指纹一致的产物。 | ||
| 60 | - 已启用名称混淆但缺少 `nameCache.json`：可以恢复文件和行列号，但方法名保持未还原状态，报告中必须明确说明。 | 67 | - 已启用名称混淆但缺少 `nameCache.json`：可以恢复文件和行列号，但方法名保持未还原状态，报告中必须明确说明。 |
| @@ -1,5 +1,18 @@ | |||
| 1 | # 更新日志 | 1 | # 更新日志 |
| 2 | 2 | ||
| 3 | +## [Unreleased] - 2026-09-02 | ||
| 4 | + | ||
| 5 | +### 新增 | ||
| 6 | +- 新增 SourceMap 反解前 UUID / 构建指纹校验门禁：反解前必须比对故障日志中的 `Fingerprint`（构建指纹/UUID 字段）与 SourceMap 产物携带的构建指纹（如 `build-info.json` 或 sourcemap 元数据 `fingerprint`），一致才允许反解；不一致时不得使用该产物，按“未提供匹配 SourceMap”处理，并要求补充与故障构建指纹一致的映射产物。 | ||
| 7 | +- `references/sourcemap-symbolication.md` 新增 UUID / 构建指纹校验要求：明确日志与产物指纹的来源和比对时机，并说明指纹一致仍需同时满足版本等字段一致，用于防止“同版本号但不同构建”的产物混用。 | ||
| 8 | +- 新增两种降级处理：日志缺少 `Fingerprint`/UUID 字段或产物缺少构建指纹时标记“无法校验”，不得将映射结果作为确定性证据；日志与产物指纹不一致时标记“UUID/构建指纹不匹配”，即使 hstack 能输出映射也禁止使用该产物反解。 | ||
| 9 | + | ||
| 10 | +### 变更 | ||
| 11 | +- 分析报告模板新增“日志 Fingerprint（构建指纹/UUID）”和“UUID 校验”字段；SourceMap 反解状态新增“UUID 不匹配未反解”，SourceMap 输入补充构建指纹信息。 | ||
| 12 | +- 证据链“SourceMap 映射证据”增加日志指纹与产物指纹的比对结果；未反解时说明缺少的匹配构建产物需包含构建指纹。 | ||
| 13 | +- SourceMap 匹配要求由版本、VersionCode、product、模块、构建模式扩展为同时要求构建指纹匹配，不得混用不匹配版本的映射文件。 | ||
| 14 | +- 反解结果校验将 UUID / 构建指纹校验列为前置步骤，指纹不一致的结果一律不得作为证据。 | ||
| 15 | + | ||
| 3 | ## [1.3.0] - 2026-09-01 | 16 | ## [1.3.0] - 2026-09-01 |
| 4 | 17 | ||
| 5 | ### 变更 | 18 | ### 变更 |