developtools_dfx_skills

本仓库包含了用于系统 DFX（Design for eXcellence）问题定界定位的核心技能（Skills）。通过结合 AI Agent 框架，这些技能可赋予大语言模型对复杂系统日志（如 faultlog等）的自动化分析、根因定位及修复建议生成能力。

📑 目录结构

每个 Skill 都独立存放在专属的文件夹中，采用模块化设计，确保技能的解耦与易扩展性。目录结构如下：

.
├── 01-fault-analysis/            # 故障分析技能集合
│   ├── appfreeze-analysis/       # 冻屏/卡死问题分析技能
│   │   ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│   │   ├── scripts/              # 辅助脚本（日志提取、堆栈分析等）
│   │   └── references/           # 知识库与参考文件（如故障模式库）
│   ├── jsleak-analysis/          # JS 内存泄漏问题分析技能
│   │   ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│   │   ├── scripts/              # rawheap 转换、heapsnapshot 聚类与预处理工具
│   │   └── references/           # 泄漏故障模式库与根因分类规则
│   ├── nativeleak-analysis/      # Native 内存泄漏问题分析技能
│   │   ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│   │   ├── scripts/              # sample、smaps、kernel 与 profiler 分析脚本
│   │   └── references/           # Native 泄漏故障模式库与 DMA/GPU 分析模板
│   ├── jscrash-analysis/         # ArkTS/JS 层闪退分析技能
│   │   ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│   │   └── references/           # JS Crash 故障模式库与错误模式矩阵
│   ├── cppcrash-analysis/        # Native 层 CppCrash 崩溃分析技能
│   │   ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│   │   ├── scripts/              # 日志提取、符号解析与反汇编辅助工具
│   │   └── references/           # ArkUI、ArkWeb、JSRuntime 等故障知识库
│   ├── fdleak-analysis/          # 文件描述符/句柄泄漏分析技能
│   │   ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│   │   ├── scripts/              # FD 快照、类型/目录 Top 与申请栈解析脚本
│   │   └── references/           # FD Leak 日志规格与故障模式库
│   └── jank-analysis/            # 卡顿问题分析技能
│       ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│       ├── scripts/              # trace 分析脚本
│       └── references/           # 卡顿故障模式库
├── 02-fault-code-fix/            # 故障代码修复技能集合
├── 03-fault-static-check/        # 故障静态检查技能集合
│   └── apifault-analysis/        # 开发者问题定位技能
│       ├── SKILL.md              # 技能定义与 Agent Prompt（核心工作流）
│       └── references/           # 模块映射表、日志解析模式与知识库
├── changelog/                    # 变更日志
└── README.md                     # 本说明文档

🧩 核心组件说明

每个技能文件夹下必须包含以下三个核心组件：

• SKILL.md: 技能的“大脑”与说明书。它定义了该技能的触发条件、AI 扮演的角色、分析目标、严格的约束条件以及 Agent 需要逐步执行的分析工作流 (Workflow)。AI Agent 会读取此文件作为核心 System Prompt。
• scripts/: 包含 Agent 在分析过程中需要调用的外部工具或脚本。例如提取关键日志的工具、计算热点函数的采样分析器等。通过调用这些脚本，Agent 能够准确获取量化数据，避免模型幻觉。
• references/: 存放特定于该技能的静态知识库文件。Agent 在输出最终结论前，会检索这些文件以完成标准化的模式匹配。

⚠️ 跨平台执行特别说明

不同技能的脚本形态不同，使用前应以对应 SKILL.md 中的调用方式为准。

appfreeze-analysis 当前使用 Python 脚本，Windows / Linux / macOS 均通过 Python 入口执行：

python "<skill-root>/scripts/freeze/main.py" -p "<faultlog文件或目录>" --section overview
python "<skill-root>/scripts/freeze/main.py" -p "<faultlog文件或目录>" --section <resources|event-queue|fault-stack|other-threads|binder|attachments>
python "<skill-root>/scripts/freeze/main.py" -p "<faultlog文件或目录>" --section full
python "<skill-root>/scripts/sample_stack_analyzer.py" "<sample_stacks.txt路径>"

<skill-root> 为 appfreeze-analysis 技能根目录。首次只读取 overview；后续根据区段索引按需读取。省略 --section 时仍输出完整报告，与旧命令兼容。

nativeleak-analysis 当前使用 Python 脚本，Windows / Linux / macOS 均通过 Python 入口执行：

python scripts/file_process.py -p <日志目录>
python scripts/sample.py -p <sample文件路径>
python scripts/native_parser.py -p <smaps文件路径> -t <jemalloc|ashmem|anon>
python scripts/kernel_leak.py -p <kernel文件路径>
python scripts/flame_analyzer.py <trace数据库路径> <内存块大小>

fdleak-analysis 使用 Python 标准库脚本，支持单文件、目录最新日志和目录批量分析：

python "<skill-root>/scripts/fd_leak_parser.py" -p "<FD Leak日志文件或目录>"
python "<skill-root>/scripts/fd_leak_parser.py" -p "<日志目录>" --all
python "<skill-root>/scripts/fd_leak_parser.py" -p "<日志文件或目录>" --format json

<skill-root> 为 fdleak-analysis 技能根目录。目录输入默认选择修改时间最新的 [pid]_fd_leak.txt 或 RESOURCE_OVERLIMIT_[TIMESTAMP]_[PID].log；脚本无第三方依赖。

jsleak-analysis 的高级 Heap Cluster 使用 Node 24 源码入口，首次运行安装锁定依赖：

pnpm --dir 01-fault-analysis/jsleak-analysis/scripts/node install --frozen-lockfile --ignore-scripts
node 01-fault-analysis/jsleak-analysis/scripts/node/heap_cluster.js --multi <snapshot_dir> <output_dir>
node 01-fault-analysis/jsleak-analysis/scripts/node/heap_cluster.js --compare <baseline_dir> <current_dir> <output_dir>

cppcrash-analysis 当前使用 Python 脚本提取关键日志与 HiLog，Windows / Linux / macOS 均通过 Python 入口执行：

python 01-fault-analysis/cppcrash-analysis/scripts/main.py -p <cppcrash日志文件或目录>
python 01-fault-analysis/cppcrash-analysis/scripts/main.py -p <cppcrash日志目录> --all
python 01-fault-analysis/cppcrash-analysis/scripts/extract_hilog.py <faultlog文件路径>

脚本仅使用 Python 标准库。目录输入默认选择时间最新的日志；需要分析目录内全部日志时使用 --all。

如脚本存在 Python 第三方依赖，可在仓库根目录通过 requirements.txt 安装；当前 appfreeze 与 cppcrash Python 脚本仅使用 Python 标准库，nativeleak Python 脚本依赖 dill。

🚀 技能工作流使用示例 (以 appfreeze-analysis 为例)

标准输入可以为：请使用appfreeze-analysis skill，分析故障日志：xx.log 和采样栈：xx

或者当用户输入包含 "冻屏"、"卡死" 或上传了包含 APPFREEZE 关键字的日志时，Agent 将自动命中 appfreeze-analysis 技能，并严格按照以下路径执行：

1. 轻量概览：调用 python "<skill-root>/scripts/freeze/main.py" -p "<faultlog文件或目录>" --section overview，只获取日志元数据和区段索引。
2. 系统状态排查：存在资源信息时读取 resources，校验时间差异、CPU 负载（>85%）、内存水位（<800MB）和温度等级；命中明确整机异常后可提前结束。
3. 队列分析：存在 EventHandler 信息时读取 event-queue，分析当前任务与历史队列耗时。
4. 堆栈分析：未被整机异常定性时读取 fault-stack；仅在故障栈等锁时读取 other-threads。
5. Binder 分析：仅在栈包含 Binder 等待、出现 IPC FULL，或已有证据无法闭环时读取 binder。
6. 附件分析：仅在需要采样栈或其他 faultlog 路径时读取 attachments；随后调用 python "<skill-root>/scripts/sample_stack_analyzer.py" "<sample_stacks.txt路径>" 统计业务热点函数。
7. 知识库匹配与报告：读取 references 中的故障模式库，输出标准化三级根因、证据链、根因模块与修复建议。只有用户明确要求完整提取或调试解析器时才读取 full。

---

🚀 技能工作流使用示例 (以 jsleak-analysis 为例)

标准输入可以为：请使用jsleak-analysis skill，分析内存快照：xx.rawheap 或 xx.heapsnapshot

也可以直接提供 heap_cluster 已聚类完成的报告文本或文件。当用户输入包含 "内存泄漏"、"rawheap"、"heapsnapshot"、"Retainer Chain"、"Retained Size"、"GC Root" 等关键字，或上传 .rawheap / .heapsnapshot 文件时，Agent 将自动命中 jsleak-analysis 技能，并严格按照以下路径执行：

1. 输入识别：判断输入是 .rawheap 原始文件、.heapsnapshot 原始快照，还是已经聚类好的内存对象报告。
2. rawheap 前置转换：当输入为 .rawheap 时，先调用本地 scripts 中对应系统版本的 rawheap_translator，将 rawheap 转换为 .heapsnapshot。Windows 使用 scripts/windows/rawheap_translator.exe，Linux 使用 scripts/linux/rawheap_translator，Mac 根据架构使用 scripts/macos/rawheap_translator_arm64 或 scripts/macos/rawheap_translator_x64。
3. 快照预处理：当输入为 .heapsnapshot 时，调用 scripts/node/heap_cluster.js；单快照可通过 --top <N> 自定义业务对象和公共对象的 Top 数量，默认为 5。单快照、目录批处理、多快照总榜、普通/测试版双版本对比均生成 Markdown、HTML 和 JSON。
4. GlobalHandler对象关联native堆栈（按需）：用户明确要求时，可提供 .heapsnapshot + native hook DB，或包含 .rawheap + .htrace + js_map*.txt 的三合一目录。三合一模式执行 node "<repo-root>/01-fault-analysis/jsleak-analysis/scripts/node/heap_node_native_stack.mjs" --case-dir "<日志目录>" --out-dir "<输出目录>"，自动复用 NativeLeak 的 trace_streamer 完成 HTrace 转 DB、聚类和地址关联。地址级数据可用时输出每个对象的 Native Top 3；只有统计表时输出明确标记的 GlobalHandle 聚合 Top 栈，不归因到具体对象。版本对比默认不自动执行该功能。
5. 数据校验：确认报告中包含对象名称/类型、引用链、Retained Size、数量或 Distance 等关键字段；缺失必要字段时先告知用户。
6. 泄漏规则分析：按 Retained Size 从大到小检查 Detached 对象、全局引用、闭包持有、异常大对象等高风险模式。
7. 故障模式匹配：读取 references/fault-modes.md，根据引用链 root 端的特征节点匹配 ROOT_VM、ROOT_FRAME、ROOT_LOCAL_HANDLE、ROOT_GLOBAL_HANDLE 或 Unknown。
8. 报告生成：输出结构化内存泄漏分析报告，包含嫌疑对象清单、完整引用链、故障模式、根因分析、修复建议以及故障模式分布总结。

---

🚀 技能工作流使用示例 (以 nativeleak-analysis 为例)

标准输入可以为：请使用nativeleak-analysis skill，分析 Native 内存泄漏日志目录：logs/

或者当用户输入包含 "Native 内存泄漏"、"native泄漏"、"PSS泄漏"、"DMA泄漏"、"GPU泄漏"、"应用内存一直涨"、"OOM" 等关键字，或上传 sample、smaps、kernel、profiler、NMD 数据时，Agent 将自动命中 nativeleak-analysis 技能，并严格按照以下路径执行：

1. 文件识别：调用 python scripts/file_process.py -p <日志目录> 识别 sample、smaps、profiler、kernel 等输入文件，并判断是否为统一管控场景。
2. 泄漏类型判定：调用 python scripts/sample.py -p <sample文件路径> 分析 totalmem、totalpss、DMA、GPU 等列，输出内存增长趋势和 PSS / DMA / GPU 泄漏类型占比。
3. PSS 子类型分析：当判定为 PSS 泄漏时，结合 smaps 数据调用 python scripts/native_rate_parser.py -p <smaps文件路径> 或 python scripts/native_parser.py -p <smaps文件路径> -t <类型>，识别 jemalloc、ArkTS、ashmem、anon 等泄漏子类型。
4. 堆栈与热点定位：对 jemalloc / anon 等需要定位调用路径的场景，结合 profiler 或 trace 数据，使用 flame_analyzer.py 查询未释放内存块的调用栈、模块和函数路径。
5. Kernel / DMA / GPU 分析：当存在 kernel 侧泄漏或 DMA / GPU 占比较高时，调用 python scripts/kernel_leak.py -p <kernel文件路径>，并结合 references/dma.md、references/dma_template.md 识别 DMA buffer、GPU 资源或共享内存未释放的可能原因。
6. 故障模式匹配：读取 references/fault-mode-library.md，按 RSS 泄漏、进程泛 PSS 泄漏及其二级、三级根因规则匹配最终故障模式。
7. 报告生成：输出 Native 内存泄漏综合分析报告，包含分析信息概览、泄漏类型判定、内存增长趋势、关键证据链、故障模式匹配结果、根因判断和修复建议。

---

🚀 技能工作流使用示例 (以 fdleak-analysis 为例)

标准输入可以为：请使用fdleak-analysis skill，分析句柄泄漏日志：1234_fd_leak.txt

当输入包含 "FD Leak"、"句柄泄漏"、"文件描述符泄漏"、leaked fd nums、Leaked fd Top 10、 LOGGER_MEMCHECK_FD_STACK_INFO，或上传标准 FD Leak 日志时，Agent 将命中 fdleak-analysis：

1. 环境与输入检查：确认 Python 3、解析脚本和输入路径可用；脚本无第三方依赖。
2. 快照提取：调用 python "<skill-root>/scripts/fd_leak_parser.py" -p "<文件或目录>"，提取时间、进程、泄漏句柄总数和区段数据。
3. 类型与目录分析：结合 Leaked fd Top 10 和 Dir Type Top 10，计算主要句柄占比并识别文件集中目录。
4. 专项明细分析：主要类型为 ashmem、socket、pipe、sync_file 或 dmabuf 且数量超过 1000 时，读取申请方、inode、Fence 或 Buffer 等专项字段。
5. 申请热点分析：按最右帧到最左帧还原 FdTrack 调用方向；需要精准函数时先用匹配 BuildID 的符号表反解。
6. 证据口径校验：区分当前句柄存量和 10 分钟全量申请统计；FdTrack 包含已关闭 FD，不单独作为泄漏实锤。
7. 知识库匹配与报告：读取日志规格和故障模式库，输出 Markdown 三级根因、证据链、可信度和修复建议。

---

🚀 技能工作流使用示例 (以 cppcrash-analysis 为例)

标准输入可以为：请使用cppcrash-analysis skill，分析 Native 崩溃日志：cppcrash.log，并结合符号文件目录：symbols/

当输入包含 "CppCrash"、"NativeCrash"、Reason:Signal、Fault thread info、Native .so 调用栈、寄存器或 GWP-ASan 报告时，Agent 将命中 cppcrash-analysis。只有“应用崩溃/闪退”而没有 JS 或 Native 证据时，应先识别日志类型，避免与 jscrash-analysis 冲突。

1. 环境与输入检查：确认 Python 3.8+ 和输入路径可用；脚本无第三方依赖。
2. 关键日志提取：调用 python 01-fault-analysis/cppcrash-analysis/scripts/main.py -p <文件或目录>；批量分析增加 --all。提取结果缺失字段时回读原始日志。
3. 分支选择：普通 Native Crash 读取信号模式；GWP-ASan 输入保留并分析违规访问、释放和申请三段调用栈。
4. 按需知识加载：根据 .so、函数和日志证据，仅加载匹配的 ArkUI、ArkData、ArkWeb、JSRuntime、RenderService、JSVM、Text、内存破坏或多线程 reference。
5. 调用栈分层：分别输出崩溃帧、首个非运行时调用方和首个应用侧帧，不把运行时帧直接作为业务根因。
6. 证据链分析：联合信号、故障地址、寄存器、指令、Maps、对象生命周期和线程证据判断第一现场及可信度。
7. 可选深入分析：仅在符号、二进制或源码可用时执行 llvm-addr2line、llvm-objdump 和源码分析；HiLog 只作时序辅助证据。
8. 报告生成：使用 Markdown 表格输出三级故障分类、代码根因、关键证据、责任归属、可信度、竞争解释和修复建议，不输出内部故障编码。

---

🚀 技能工作流使用示例 (以 apifault-analysis 为例)

标准输入可以为：请使用apifault-analysis skill，分析故障日志：xx.log，问题描述：xx

或者当用户输入包含 "错误码"、"错误信息"、"执行失败"、"接口调用失败"、"定位问题" 等关键字，或上传包含错误码、调用失败日志的故障文件时，Agent 将自动命中 apifault-analysis 技能，并严格按照以下路径执行：

1. 线索提取与模块识别：从日志或问题描述中提取错误码、事件名、DOMAIN、调用栈（含 .so 库名）、API 名称、hilog domain_id 等线索，读取 references/module_mapping.md 匹配涉及的模块。
2. 分诊查询：读取 references/knowledge/{module_name}/ 下的知识库文件（error_codes.json、api_chain.json、common_issues.md），按错误码精确匹配、API 调用链匹配、常见问题模式匹配；查询官方文档中的错误码说明和相关 API 用法；评估诊断置信度。
3. 深潜分析（低置信度时执行）：按 API 调用链追踪代码实现，搜索代码仓错误头文件获取错误码定义，分析项目源码的 API 调用时序与权限声明，交叉验证多来源证据，并追溯根因至应用侧具体操作行为。
4. 分析与修复建议（可选）：扫描源码文件，定位问题相关源码，检查权限声明、API 调用时序和语法问题，生成具体可操作的代码修改建议。
5. 报告生成：输出结构化问题诊断报告，包含问题摘要、线索提取、知识库匹配、根因分析（含证据链和置信度）、修复建议及参考文档。

---

🚀 技能工作流使用示例 (以 jscrash-analysis 为例)

标准输入可以为：请使用jscrash-analysis skill，分析 JS Crash 日志：jscrash.log

或者当用户输入包含 "JS Crash"、"ArkTS 崩溃"、"应用闪退"、"ReferenceError"、"TypeError"、"BusinessError"、"OutOfMemoryError"、"Stacktrace"、"HybridStack" 等关键字，或上传包含 Reason、Error message、Error code、Stacktrace 等字段的 faultlogger 日志时，Agent 将自动命中 jscrash-analysis 技能，并严格按照以下路径执行：

1. 关键信息提取：从日志中提取 Reason、Error name、Error message、Error code、page、Stacktrace、Uid/Pid、故障时间等字段。
2. SourceMap 反解：关键业务栈未还原时，使用故障版本匹配的 sourceMaps.json 和 Skill 内置跨平台 hstack 反解；Windows 调用 <skill-root>\scripts\hstack\bin\hstack.bat，Linux/macOS 调用 <skill-root>/scripts/hstack/bin/hstack；启用名称混淆时同时提供 nameCache.json。
3. 故障类型分类：优先使用 Reason 分类；缺失时使用 Error name；两者都缺失时结合 Error message 关键词推断，并标注可信度。
4. 故障模式匹配：读取 references/fault-mode-library.md，按 Reason / Error name / Error message 匹配 JSError 一级、二级、三级根因。
5. 错误模式补充：读取 references/jscrash-patterns.md，补充未覆盖错误的分析结论、触发条件和修复建议。
6. 调用栈分析：优先使用反解后的第一个应用栈帧定位源码文件、行号、列号和触发路径；框架栈仅作为传播路径辅助判断。
7. 根因定界：结合错误信息、错误码、栈顶应用帧和模式库，区分应用代码、三方 SDK、系统框架或证据不足的不确定场景。
8. 报告生成：输出 SourceMap 反解状态、故障基本信息、故障模式库匹配表、根因判断、关键证据链、修复建议和需要补充的材料。

---