arkts-crash-diagnosis

诊断并修复 HarmonyOS ArkTS/JS 运行期崩溃：编译能过、一跑就闪退/白屏/异常退出。核心方法是先拿到具体崩溃锚点（error_type / error_message / suspected_file / top_stack），再做聚焦的代码阅读与最小修复，禁止在拿到锚点前大范围通读工程。本技能内置 Node 解析脚本（faultlogger 探测、faultlog 拉取、jscrash 解析、hilog 采集）与崩溃模式知识库（9 份 patterns 文档）。

本技能的脚本与知识库经用户许可，吸收自本机安装技能 arkts-runtime-fix（知识库上游：hmos-jscrash-analysis）；技能目录名有意与该已安装技能不同，避免同名冲突。

When to Use This Skill

Follow this skill's workflow whenever any of the following conditions is met:

• 运行日志出现 TypeError / ReferenceError / RangeError / SyntaxError / BusinessError / OutOfMemoryError / URIError 等运行期异常
• 应用闪退、崩溃、白屏，或点击/启动后立即退出
• 用户提供 jscrash 日志、堆栈，或以 @file 方式给出临时日志文件
• 构建成功，但运行行为立刻失败（无编译错误）
• 需要从设备侧拉取 faultlog 或采集 hilog 作为崩溃证据

Do not force this skill onto "编译期报错"（hvigor/ArkCompiler 编译失败）、"构建/签名/部署失败" 或 "C++ native 层崩溃工具链" 场景 — 使用对应 skill（见下表）。

Boundary with Other Skills

This skill covers 「编译通过后的运行期崩溃诊断与修复」, not 「编译错误」, 「构建链路」, or 「NDK native 工具链」:

Workflow (Follow Strictly)

1. 先定锚点，禁止盲目探索

拿到以下任意一个具体锚点之前，不要大范围 Read / Glob / 全工程搜索：

• 用户提供的崩溃日志或堆栈
• 用户指明的页面/模块
• 设备侧最近的 faultlog 或 hilog

锚点形态：error_type、error_message、suspected_file、top_stack。用户已给出足够证据时，直接解析该证据，不要过度采集日志。

2. 解析崩溃证据

脚本通过 Shell 运行（{SKILL_DIR} 为本技能目录绝对路径；需要 Node.js，不可用时停止并说明，不要假装执行）：

node "{SKILL_DIR}/scripts/jscrash-report.mjs" --log-text "{crashLog}" --bundle-name "{bundleName}" --include-text
node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{logFilePath}" --bundle-name "{bundleName}" --include-text

Case A 用户直接给了崩溃文本 → 用 jscrash-report.mjs --log-text。 Case B 用户给了 @file 或本地日志路径 → 用 parse-jscrash-log.mjs --log-file。 Case C 用户只描述了症状 → 按需采集设备侧证据：

1. 读 AppScope/app.json5 取准确的 app.bundleName，作为所有脚本的 {bundleName}——禁止从 vendor、模块目录名或 com.example 前缀猜
2. 用 hdc list targets 确认设备：恰好一台直接用；多台必须让用户选；无设备则报告无法采集，请用户连接设备或提供本地日志
3. 用户复现崩溃后探测 faultlogger：

node "{SKILL_DIR}/scripts/probe-faultlogger.mjs" --bundle-name "{bundleName}" --device-id "{deviceId}" --max-age-minutes "30" --limit "10"

4. status: found → 拉取并解析最新 faultlog：

node "{SKILL_DIR}/scripts/fetch-faultlog.mjs" --faultlog-name "{latestFaultlog}" --device-id "{deviceId}" --output-dir "{tempDir}"
node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{localFaultlogPath}" --bundle-name "{bundleName}" --source file --include-text

5. status: not_found → 不要转而大范围读工程或凭症状猜；请用户再次复现后立即重探
6. faultlogger 不可用或证据仍不足 → 回退 hilog：

node "{SKILL_DIR}/scripts/collect-hilog.mjs" --device-id "{deviceId}" --lines "4000" --output-dir "{tempDir}"
node "{SKILL_DIR}/scripts/parse-jscrash-log.mjs" --log-file "{hilogPath}" --bundle-name "{bundleName}" --source hilog --include-text

脚本输出以 key: value 文本块为准：status（detected / no_crash_signature / parse_failed）、source、error_type、error_message、suspected_file、top_stack（| 分隔帧）、keywords、next_action。--include-text 追加人类可读摘要。非零退出码表示该步骤无法继续——报告原因，不要猜测。status: no_crash_signature 时说明证据薄弱，先要更好的日志/复现路径，再进入代码阅读。

3. 匹配崩溃模式

1. 先读 references/fault-mode-library.md，用 Reason / Error name / Error message 匹配 JSError → 次级原因 → 三级原因
2. 按 error_type 只读对应 patterns 文档：

3. 多个模式同时命中时，选 Error message + Error code + 顶部应用栈帧同时支持的那个（各文档内有可信度规则）
4. 高频模式速查：

4. 最小修复并复测

• 对 top_stack 指向的应用文件做最小修复，不要扩大重构；优先应用帧而非框架噪声；第一个具体 .ets/.ts 路径是起点不是终点
• 用户给了复现步骤时，复现步骤优先于纯堆栈推断；堆栈指向非入口页时默认交互触发路径，除非证据表明冷启崩溃
• 红线：不许用重试、任意延时或大范围防御式重写代替根因修复；不许凭推理宣称"已修复"——修复后用 arkts-build 的 hvigorw 流程重建、hdc 安装运行并复测
• 涉及不熟悉的 @ohos.* / @kit.* API 时，先查其约束再改

5. 引用来源

回复中标注依据的 patterns 文档，例如：

修复依据 references/typeerror_patterns.md「Cannot read property」模式。

Directory Structure

arkts-crash-diagnosis/
├── SKILL.md                                  # This file
├── references/
│   ├── INDEX.md                              # Must read first
│   ├── fault-mode-library.md                 # 崩溃模式总库（JSError→次级→三级原因）
│   ├── referenceerror_patterns.md            # ReferenceError 模式
│   ├── typeerror_patterns.md                 # TypeError 模式
│   ├── error_patterns.md                     # Error/BusinessError 业务错误模式
│   ├── businesserror_patterns.md             # BusinessError 参数校验模式
│   ├── syntaxerror_patterns.md               # SyntaxError 模式
│   ├── rangeerror_patterns.md                # RangeError 模式
│   ├── outofmemoryerror_patterns.md          # OutOfMemoryError 模式
│   └── urierror_patterns.md                  # URIError 模式
└── scripts/
    ├── jscrash-report.mjs                    # 崩溃文本 → 结构化报告
    ├── parse-jscrash-log.mjs                 # 日志文件/hilog → 结构化报告
    ├── probe-faultlogger.mjs                 # 设备侧 faultlogger 探测
    ├── fetch-faultlog.mjs                    # 拉取 faultlog 到本地
    ├── collect-hilog.mjs                     # 采集 hilog
    └── shared/                               # hdc 调用与解析公共模块

Documentation Source & Maintenance

• 知识库上游：https://gitcode.com/HarmonyOS_Skills/harmonyos-agent-skills/tree/main/03-solutions/quality/stability/hmos-jscrash-analysis（references/*.md 头部均标注；吸收自本机安装技能 arkts-runtime-fix，2026-08-29）
• 脚本：Apache-2.0（Huawei Device Co., Ltd.），经 hdc/DEVECO_HOME 解析调用，自包含无外部依赖
• 更新策略：知识库未覆盖的新错误模式，先用 harmony-fetch 查官方 faultlog/hilog 文档补充；重大更新可重新同步上游知识库