@arms/rum-reactnative 0.1.1 → 0.1.3-beta.0

package/ios/RumCrashReporter.mm

@@ -0,0 +1,861 @@
+#import "RumCrashReporter.h"
+
+#import <KSCrash/KSCrash.h>
+#import <KSCrash/KSCrashConfiguration.h>
+#import <KSCrash/KSCrashMonitorType.h>
+#import <KSCrash/KSCrashReportStore.h>
+#import <KSCrash/KSCrashReport.h>
+#import <KSCrash/KSCrashReportFilter.h>
+
+#import <UIKit/UIKit.h>
+#import <dlfcn.h>
+#import <signal.h>
+#import <stdlib.h>
+
+#import "fishhook.h"
+
+#pragma mark - Constants
+
+/** RUM 自定义字段在 KSCrash userInfo 中的命名空间 */
+static NSString *const kRumCrashUserInfoContextKey = @"rum_context";
+
+/** RUM SDK 数据子目录 */
+static NSString *const kRumCrashDirName = @"RumCrashReporter";
+static NSString *const kRumContextFileName = @"context.json";
+static NSString *const kRumCrashedLastRunFlagName = @"crashed_last_run.flag";
+
+/** 旧版目录名（用于升级迁移） */
+static NSString *const kLegacyCrashDirName = @"ARMSCrashReporter";
+
+/** Forward-declare private class methods used by the constructor */
+@interface RumCrashReporter (Private)
++ (NSString *)crashDir;
++ (NSString *)contextPath;
++ (id)readJSONFileAtPath:(NSString *)path;
++ (void)atomicWriteJSONObject:(id)obj toPath:(NSString *)path;
+@end
+
+#pragma mark - Early constructor
+
+/**
+ * 早期安装：dyld 加载本动态库时立即安装 Mach + Signal 监控。
+ * 这两类监控不需要 RN bridge，可在 app 启动最早期捕获原生崩溃。
+ * NSException + CPPException 由 +install 补充安装（需要 RN 环境）。
+ */
+static volatile int gRumCrashLoaded = 0;
+static BOOL gKSCrashInstalled = NO;
+
+__attribute__((constructor))
+static void RumCrashReporterEarlyLoad(void) {
+    // 不在 constructor 里安装 KSCrash —— RN bridge 启动时会调用 RCTInstallSignalHandlers
+    // 覆盖 KSCrash 的信号处理程序。改为在 +install（RN 模块实例化时）一次性安装全部
+    // monitor，确保 KSCrash 的 signal handler 是最后安装的，能真正捕获到崩溃信号。
+    gRumCrashLoaded = 1;
+}
+
+#pragma mark - Helpers
+
+@interface RumCrashReporter ()
+@end
+
+@implementation RumCrashReporter
+
+/** SDK 私有目录：<Library>/Caches/RumCrashReporter/ */
++ (NSString *)crashDir {
+    static NSString *dir;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        NSString *caches = [NSSearchPathForDirectoriesInDomains(
+            NSCachesDirectory, NSUserDomainMask, YES) firstObject];
+        dir = [caches stringByAppendingPathComponent:kRumCrashDirName];
+        NSFileManager *fm = [NSFileManager defaultManager];
+
+        // 迁移旧版目录 ARMSCrashReporter → RumCrashReporter
+        NSString *legacyDir = [caches stringByAppendingPathComponent:kLegacyCrashDirName];
+        if ([fm fileExistsAtPath:legacyDir]) {
+            // 如果新目录已存在，合并内容；否则直接重命名
+            if (![fm fileExistsAtPath:dir]) {
+                [fm moveItemAtPath:legacyDir toPath:dir error:nil];
+            } else {
+                // 逐个迁移文件
+                NSArray *files = [fm contentsOfDirectoryAtPath:legacyDir error:nil];
+                for (NSString *file in files) {
+                    NSString *src = [legacyDir stringByAppendingPathComponent:file];
+                    NSString *dst = [dir stringByAppendingPathComponent:file];
+                    if (![fm fileExistsAtPath:dst]) {
+                        [fm moveItemAtPath:src toPath:dst error:nil];
+                    }
+                }
+                [fm removeItemAtPath:legacyDir error:nil];
+            }
+        }
+
+        if (![fm fileExistsAtPath:dir]) {
+            [fm createDirectoryAtPath:dir
+          withIntermediateDirectories:YES
+                           attributes:nil
+                                error:nil];
+        }
+    });
+    return dir;
+}
+
++ (NSString *)contextPath {
+    return [[self crashDir] stringByAppendingPathComponent:kRumContextFileName];
+}
+
+#pragma mark - Install
+
++ (void)install {
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        @try {
+            KSCrashConfiguration *config = [[KSCrashConfiguration alloc] init];
+            // 重新安装全部监控：Mach + Signal + NSException + CPPException + ApplicationState
+            // KSCrash installWithConfiguration: 会覆盖之前的配置，
+            // 因此必须包含 constructor 中已安装的 Mach + Signal，否则会丢失
+            // ApplicationState monitor 必须启用：它负责持久化 crashedThisLaunch 状态
+            // 到 CrashState.json，下次启动读取为 crashedLastLaunch。不启用的话
+            // crashedLastLaunch 永远是 NO，UI 上的"上次运行是否崩溃"始终为否。
+            config.monitors = KSCrashMonitorTypeMachException
+                            | KSCrashMonitorTypeSignal
+                            | KSCrashMonitorTypeCPPException
+                            | KSCrashMonitorTypeNSException
+                            | KSCrashMonitorTypeApplicationState;
+
+            // 透传当前 context（session/view）作为 userInfo，崩溃时一同落盘
+            NSDictionary *currentContext = [self readJSONFileAtPath:[self contextPath]];
+            if ([currentContext isKindOfClass:[NSDictionary class]]) {
+                config.userInfoJSON = @{ kRumCrashUserInfoContextKey: currentContext };
+            }
+
+            // Detox（如果注入）通过 fishhook swizzle 了 sigaction，会静默丢弃后续对
+            // SIGABRT/SIGSEGV 等致命信号的 sigaction 调用。KSCrash 的 signal monitor
+            // 调用 sigaction 安装自己的 handler 时就会被丢弃，导致 KSCrash 无法捕获
+            // 信号类崩溃。
+            // 这里在 KSCrash install 之前用 fishhook 把 sigaction 的 lazy pointer
+            // 重绑回 libsystem 的真实函数（dlsym 返回的是真实函数地址，不受 fishhook
+            // 影响）。重绑后 KSCrash 的 sigaction 调用会真正生效，其 signal handler
+            // 会覆盖 Detox 的 handler。崩溃发生时 KSCrash 先写报告，再 uninstall +
+            // raise(sig) 触发 Detox 的 handler（KSCrash 在 uninstall 时恢复了 previous
+            // handler），Detox 仍能感知崩溃并通知测试 runner。
+            static int (*real_sigaction)(int, const struct sigaction * __restrict,
+                                         struct sigaction * __restrict) = NULL;
+            if (real_sigaction == NULL) {
+                real_sigaction = (int (*)(int, const struct sigaction * __restrict,
+                                          struct sigaction * __restrict))
+                    dlsym(RTLD_DEFAULT, "sigaction");
+            }
+            if (real_sigaction != NULL) {
+                struct rebinding rebindings[] = {
+                    {"sigaction", (void *)real_sigaction, NULL},
+                };
+                rebind_symbols(rebindings, sizeof(rebindings) / sizeof(rebindings[0]));
+            }
+
+            NSError *error = nil;
+            BOOL ok = [[KSCrash sharedInstance] installWithConfiguration:config error:&error];
+            if (ok) {
+                gKSCrashInstalled = YES;
+            } else {
+                NSLog(@"[RumCrashReporter] KSCrash install failed: %@", error);
+            }
+
+            // 同步 crashedLastRun 到本地 flag file。
+            // KSCrash 的 crashedLastLaunch 在 reports 被删除后会重置为 NO，
+            // 但 SDK 在 setup 阶段就会读取并清理 pending 文件，导致用户后续查询时
+            // 始终拿到 NO。这里把"上次是否崩溃"持久化到文件，install 时按 KSCrash
+            // 状态写入/删除，crashedLastRun 优先读文件。
+            NSString *flagPath = [[self crashDir]
+                stringByAppendingPathComponent:kRumCrashedLastRunFlagName];
+            if ([KSCrash sharedInstance].crashedLastLaunch) {
+                [[NSFileManager defaultManager]
+                    createFileAtPath:flagPath
+                            contents:[NSData data]
+                          attributes:nil];
+            } else {
+                [[NSFileManager defaultManager] removeItemAtPath:flagPath error:nil];
+            }
+            (void)ok;
+        } @catch (NSException *e) {
+            NSLog(@"[RumCrashReporter] install exception: %@", e);
+        }
+    });
+}
+
++ (BOOL)crashedLastRun {
+    // 优先读 flag file —— KSCrash.crashedLastLaunch 在 reports 被清理后会被重置，
+    // 而 SDK 会在 app 启动早期就处理 pending 文件，因此直接读 KSCrash 会导致
+    // 用户在 UI 上查询时永远得到 NO。
+    NSString *flagPath = [[self crashDir]
+        stringByAppendingPathComponent:kRumCrashedLastRunFlagName];
+    if ([[NSFileManager defaultManager] fileExistsAtPath:flagPath]) {
+        return YES;
+    }
+    @try {
+        return [KSCrash sharedInstance].crashedLastLaunch;
+    } @catch (...) {
+        return NO;
+    }
+}
+
+#pragma mark - Pending reports
+
++ (NSArray<NSDictionary *> *)pendingCrashReports {
+    NSMutableArray<NSDictionary *> *result = [NSMutableArray array];
+    @try {
+        KSCrashReportStore *store = [KSCrash sharedInstance].reportStore;
+        if (store == nil) {
+            NSLog(@"[RumCrashReporter] pendingCrashReports: reportStore is nil (gKSCrashInstalled=%d), returning empty.", gKSCrashInstalled);
+            return result;
+        }
+        NSArray<NSNumber *> *reportIDs = store.reportIDs ?: @[];
+        for (NSNumber *reportID in reportIDs) {
+            @autoreleasepool {
+                KSCrashReportDictionary *report = [store reportForID:[reportID longLongValue]];
+                NSDictionary *raw = nil;
+                if (report != nil) {
+                    raw = report.value;
+                }
+                if (![raw isKindOfClass:[NSDictionary class]]) {
+                    continue;
+                }
+                NSDictionary *normalized = [self normalizeKSCrashReport:raw
+                                                              reportID:reportID];
+                if (normalized != nil) {
+                    [result addObject:normalized];
+                }
+            }
+        }
+    } @catch (NSException *e) {
+        NSLog(@"[RumCrashReporter] pendingCrashReports exception: %@", e);
+    }
+    return result;
+}
+
++ (void)clearCrashReportsWithIds:(NSArray<NSString *> *)crashIds {
+    if (crashIds.count == 0) {
+        return;
+    }
+    @try {
+        KSCrashReportStore *store = [KSCrash sharedInstance].reportStore;
+        if (store == nil) {
+            return;
+        }
+
+        // crash_id 可能是 KSCrash 的 report.id（UUID 字符串）或数字 reportID 字符串。
+        // 数字 ID 直接走 deleteReportWithID；UUID 需要遍历 reports 匹配 report.id。
+        NSMutableSet<NSString *> *uuidSet = [NSMutableSet set];
+        NSMutableSet<NSNumber *> *numericIDs = [NSMutableSet set];
+        for (NSString *cid in crashIds) {
+            if (![cid isKindOfClass:[NSString class]] || cid.length == 0) {
+                continue;
+            }
+            // 判断 cid 是否为纯数字字符串（reportID）
+            // 不能用 longLongValue > 0，因为 reportID = 0 时会被误判为 UUID
+            NSCharacterSet *nonDigits = [[NSCharacterSet decimalDigitCharacterSet] invertedSet];
+            if ([cid rangeOfCharacterFromSet:nonDigits].location == NSNotFound) {
+                [numericIDs addObject:@([cid longLongValue])];
+            } else {
+                [uuidSet addObject:cid];
+            }
+        }
+
+        // 1. 数字 ID 直接删除
+        for (NSNumber *rid in numericIDs) {
+            [store deleteReportWithID:[rid longLongValue]];
+        }
+
+        // 2. UUID 匹配：遍历所有 reportIDs，读 report.id，命中则删除
+        if (uuidSet.count > 0) {
+            NSArray<NSNumber *> *allReportIDs = [store.reportIDs copy] ?: @[];
+            for (NSNumber *rid in allReportIDs) {
+                @autoreleasepool {
+                    KSCrashReportDictionary *report = [store reportForID:[rid longLongValue]];
+                    NSDictionary *raw = report ? report.value : nil;
+                    NSDictionary *reportMeta = [raw isKindOfClass:[NSDictionary class]]
+                        ? raw[@"report"]
+                        : nil;
+                    NSString *uuid = [reportMeta isKindOfClass:[NSDictionary class]]
+                        ? reportMeta[@"id"]
+                        : nil;
+                    if ([uuid isKindOfClass:[NSString class]] && [uuidSet containsObject:uuid]) {
+                        [store deleteReportWithID:[rid longLongValue]];
+                    }
+                }
+            }
+        }
+    } @catch (NSException *e) {
+        NSLog(@"[RumCrashReporter] clearCrashReports exception: %@", e);
+    }
+}
+
+#pragma mark - Clear All & Cleanup
+
++ (void)clearAllCrashReports {
+    @try {
+        KSCrashReportStore *store = [KSCrash sharedInstance].reportStore;
+        if (store == nil) {
+            return;
+        }
+        NSArray<NSNumber *> *reportIDs = [store.reportIDs copy] ?: @[];
+        for (NSNumber *reportID in reportIDs) {
+            [store deleteReportWithID:[reportID longLongValue]];
+        }
+    } @catch (NSException *e) {
+        NSLog(@"[RumCrashReporter] clearAllCrashReports exception: %@", e);
+    }
+}
+
++ (void)cleanupOldCrashesWithMaxFiles:(NSInteger)maxFiles maxAgeMs:(double)maxAgeMs {
+    @try {
+        KSCrashReportStore *store = [KSCrash sharedInstance].reportStore;
+        if (store == nil) {
+            return;
+        }
+        NSArray<NSNumber *> *reportIDs = [store.reportIDs copy] ?: @[];
+        if (reportIDs.count == 0) {
+            return;
+        }
+
+        NSInteger maxCount = MAX(maxFiles, 1);
+        double now = [[NSDate date] timeIntervalSince1970] * 1000.0;
+
+        // Collect report timestamps and sort by newest first
+        NSMutableArray<NSDictionary *> *reports = [NSMutableArray array];
+        for (NSNumber *reportID in reportIDs) {
+            @autoreleasepool {
+                KSCrashReportDictionary *report = [store reportForID:[reportID longLongValue]];
+                NSDictionary *raw = report ? report.value : nil;
+                double timestamp = now; // default to now if unknown
+                if ([raw isKindOfClass:[NSDictionary class]]) {
+                    NSDictionary *reportMeta = raw[@"report"];
+                    if ([reportMeta isKindOfClass:[NSDictionary class]]) {
+                        id t = reportMeta[@"timestamp"];
+                        if ([t isKindOfClass:[NSString class]]) {
+                            NSDateFormatter *fmt = [[NSDateFormatter alloc] init];
+                            fmt.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
+                            NSArray<NSString *> *formats = @[
+                                @"yyyy-MM-dd'T'HH:mm:ss.SSSXXX",
+                                @"yyyy-MM-dd'T'HH:mm:ss.SSSZ",
+                                @"yyyy-MM-dd'T'HH:mm:ss'Z'",
+                                @"yyyy-MM-dd'T'HH:mm:ssXXX"
+                            ];
+                            NSDate *d = nil;
+                            for (NSString *format in formats) {
+                                fmt.dateFormat = format;
+                                d = [fmt dateFromString:t];
+                                if (d) break;
+                            }
+                            if (d) {
+                                timestamp = [d timeIntervalSince1970] * 1000.0;
+                            }
+                        } else if ([t isKindOfClass:[NSNumber class]]) {
+                            timestamp = [(NSNumber *)t doubleValue] * 1000.0;
+                        }
+                    }
+                }
+                [reports addObject:@{
+                    @"id": reportID,
+                    @"timestamp": @(timestamp)
+                }];
+            }
+        }
+
+        // Sort by timestamp descending (newest first)
+        [reports sortUsingComparator:^NSComparisonResult(NSDictionary *a, NSDictionary *b) {
+            return [b[@"timestamp"] compare:a[@"timestamp"]];
+        }];
+
+        // 1. Delete expired reports
+        NSMutableArray<NSDictionary *> *remaining = [NSMutableArray array];
+        for (NSDictionary *entry in reports) {
+            double ts = [entry[@"timestamp"] doubleValue];
+            if (now - ts > maxAgeMs) {
+                [store deleteReportWithID:[entry[@"id"] longLongValue]];
+            } else {
+                [remaining addObject:entry];
+            }
+        }
+
+        // 2. Delete oldest beyond maxFiles limit
+        if ((NSInteger)remaining.count > maxCount) {
+            for (NSInteger i = maxCount; i < (NSInteger)remaining.count; i++) {
+                [store deleteReportWithID:[remaining[i][@"id"] longLongValue]];
+            }
+        }
+    } @catch (NSException *e) {
+        NSLog(@"[RumCrashReporter] cleanupOldCrashes exception: %@", e);
+    }
+}
+
+#pragma mark - Context
+
++ (void)updateCrashContext:(NSString *)context {
+    if (context.length == 0) {
+        return;
+    }
+
+    // 1. 同步写入文件（保证崩溃时可读，与 Android 行为一致）
+    NSData *data = [context dataUsingEncoding:NSUTF8StringEncoding];
+    id obj = data ? [NSJSONSerialization JSONObjectWithData:data
+                                                    options:0
+                                                      error:nil] : nil;
+    if (![obj isKindOfClass:[NSDictionary class]]) {
+        return;
+    }
+    @try {
+        [self atomicWriteJSONObject:obj toPath:[self contextPath]];
+    } @catch (NSException *e) {
+        NSLog(@"[RumCrashReporter] updateCrashContext sync write failed: %@", e);
+    }
+
+    // 2. KSCrash userInfo 同步更新（context 变更不频繁，同步开销可忽略；
+    //    消除异步竞态：崩溃发生在 dispatch_async 排队期间时报告中 context 为旧值）
+    NSDictionary *contextObj = obj;
+    @try {
+        [KSCrash sharedInstance].userInfo = @{ kRumCrashUserInfoContextKey: contextObj };
+    } @catch (...) {}
+}
+
+#pragma mark - JSON file IO
+
++ (id)readJSONFileAtPath:(NSString *)path {
+    NSData *data = [NSData dataWithContentsOfFile:path];
+    if (data.length == 0) {
+        return nil;
+    }
+    return [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
+}
+
++ (NSArray *)readJSONArrayAtPath:(NSString *)path {
+    id obj = [self readJSONFileAtPath:path];
+    return [obj isKindOfClass:[NSArray class]] ? (NSArray *)obj : nil;
+}
+
++ (void)atomicWriteJSONObject:(id)obj toPath:(NSString *)path {
+    if (obj == nil || path.length == 0) {
+        return;
+    }
+    NSError *error = nil;
+    NSData *data = [NSJSONSerialization dataWithJSONObject:obj options:0 error:&error];
+    if (data == nil) {
+        return;
+    }
+    [data writeToFile:path atomically:YES];
+}
+
+#pragma mark - Normalization
+
+/**
+ * 将 KSCrash v2 原始报告标准化为协议字典。
+ * 字段映射依据 KSCrash JSON schema：
+ *   raw[@"crash"]            -> 错误/线程
+ *   raw[@"binary_images"]    -> 镜像
+ *   raw[@"system"]           -> 设备/系统/应用
+ *   raw[@"report"][@"id"]    -> uuid
+ *   raw[@"user"]             -> 我们注入的 rum_context
+ */
++ (NSDictionary *)normalizeKSCrashReport:(NSDictionary *)raw
+                                reportID:(NSNumber *)reportID {
+    NSMutableDictionary *out = [NSMutableDictionary dictionary];
+
+    // 原生层事件去重：过滤已被 JS 层上报的 JS 异常
+    // 避免同一错误被 JS ErrorUtils 和原生 NSException 各上报一次
+    NSDictionary *earlyCrash = [raw objectForKey:@"crash"];
+    if ([earlyCrash isKindOfClass:[NSDictionary class]]) {
+        NSDictionary *earlyError = [earlyCrash objectForKey:@"error"];
+        if ([earlyError isKindOfClass:[NSDictionary class]]) {
+            NSString *reason = earlyError[@"reason"] ?: @"";
+            NSString *type = earlyError[@"type"] ?: @"";
+            // JS 异常特征：NSException 类型且 reason 包含 JS 桥相关关键词
+            // 限定 type 为 nsexception，避免 Mach/Signal 崩溃因 reason 碰巧
+            // 包含这些字符串而被误过滤
+            if ([type containsString:@"nsexception"] &&
+                ([reason containsString:@"ExceptionsManager"] ||
+                 [reason containsString:@"Unhandled JS Exception"] ||
+                 [reason containsString:@"RCTFatal"])
+            ) {
+                return nil; // 跳过，已被 JS 层上报
+            }
+        }
+    }
+
+    // crash_id
+    NSDictionary *reportMeta = [raw objectForKey:@"report"];
+    NSString *uuid = nil;
+    if ([reportMeta isKindOfClass:[NSDictionary class]]) {
+        uuid = [reportMeta objectForKey:@"id"];
+    }
+    out[@"crash_id"] = uuid.length > 0 ? uuid : [reportID stringValue];
+
+    // timestamp（毫秒）
+    NSNumber *ts = nil;
+    if ([reportMeta isKindOfClass:[NSDictionary class]]) {
+        id t = reportMeta[@"timestamp"];
+        if ([t isKindOfClass:[NSString class]]) {
+            NSDateFormatter *fmt = [[NSDateFormatter alloc] init];
+            fmt.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
+
+            NSArray<NSString *> *formats = @[
+                @"yyyy-MM-dd'T'HH:mm:ss.SSSXXX",
+                @"yyyy-MM-dd'T'HH:mm:ss.SSSZ",
+                @"yyyy-MM-dd'T'HH:mm:ss'Z'",
+                @"yyyy-MM-dd'T'HH:mm:ssXXX"
+            ];
+
+            NSDate *d = nil;
+            for (NSString *format in formats) {
+                fmt.dateFormat = format;
+                d = [fmt dateFromString:t];
+                if (d) break;
+            }
+
+            if (d) {
+                ts = @((long long)([d timeIntervalSince1970] * 1000));
+            } else {
+                // 所有格式都失败，降级为当前时间
+                ts = @((long long)([[NSDate date] timeIntervalSince1970] * 1000));
+            }
+        } else if ([t isKindOfClass:[NSNumber class]]) {
+            // 已是数值（秒级），转毫秒
+            ts = @((long long)([(NSNumber *)t doubleValue] * 1000));
+        }
+    }
+    out[@"timestamp"] = ts ?: @((long long)([[NSDate date] timeIntervalSince1970] * 1000));
+
+    out[@"platform"] = @"ios";
+
+    NSDictionary *crash = [raw objectForKey:@"crash"];
+    if (![crash isKindOfClass:[NSDictionary class]]) {
+        crash = @{};
+    }
+    NSDictionary *errorInfo = [crash objectForKey:@"error"];
+    if (![errorInfo isKindOfClass:[NSDictionary class]]) {
+        errorInfo = @{};
+    }
+
+    // signal
+    NSMutableDictionary *signal = [NSMutableDictionary dictionary];
+    NSDictionary *signalRaw = errorInfo[@"signal"];
+    if ([signalRaw isKindOfClass:[NSDictionary class]]) {
+        signal[@"name"] = signalRaw[@"name"] ?: @"";
+        signal[@"code"] = signalRaw[@"code_name"] ?: signalRaw[@"code"] ?: @"";
+        // 信号编号：KSCrash raw report 中信号编号存储在 "signal" 键下，
+        // 与 Android NDK 的 signal.number 对齐，供 JS 层读取放入 snapshots。
+        signal[@"number"] = signalRaw[@"signal"] ?: @0;
+    }
+    id addr = errorInfo[@"address"];
+    if (addr) {
+        signal[@"fault_address"] = [self hexStringFromValue:addr];
+    }
+    out[@"signal"] = signal;
+
+    // exception
+    NSMutableDictionary *exception = [NSMutableDictionary dictionary];
+    NSString *errType = errorInfo[@"type"];
+    if (errType.length == 0) {
+        errType = @"unknown";
+    }
+    NSString *normalizedType = errType;
+    if ([errType isEqualToString:@"mach"]) {
+        normalizedType = @"mach_exception";
+    } else if ([errType isEqualToString:@"signal"]) {
+        normalizedType = @"signal";
+    } else if ([errType isEqualToString:@"cpp_exception"]) {
+        normalizedType = @"cpp_exception";
+    } else if ([errType isEqualToString:@"nsexception"]) {
+        normalizedType = @"ns_exception";
+    } else if ([errType isEqualToString:@"user"]) {
+        normalizedType = @"user_reported";
+    }
+    exception[@"type"] = normalizedType;
+
+    NSDictionary *nsex = errorInfo[@"nsexception"];
+    NSDictionary *cppex = errorInfo[@"cpp_exception"];
+    if ([nsex isKindOfClass:[NSDictionary class]]) {
+        exception[@"class_name"] = nsex[@"name"] ?: @"";
+        exception[@"message"] = nsex[@"reason"] ?: errorInfo[@"reason"] ?: @"";
+    } else if ([cppex isKindOfClass:[NSDictionary class]]) {
+        exception[@"class_name"] = cppex[@"name"] ?: @"";
+        exception[@"message"] = cppex[@"reason"] ?: errorInfo[@"reason"] ?: @"";
+    } else {
+        exception[@"class_name"] = normalizedType;
+        exception[@"message"] = errorInfo[@"reason"] ?: @"";
+    }
+    out[@"exception"] = exception;
+
+    // mechanism：标记崩溃捕获机制，参照 Sentry 实践
+    // JS 层会将此字段放入 snapshots 容器
+    NSMutableDictionary *mechanism = [NSMutableDictionary dictionary];
+    mechanism[@"type"] = normalizedType;
+    mechanism[@"handled"] = @NO;
+    out[@"mechanism"] = mechanism;
+
+    // crashed_thread + registers
+    NSArray *threads = crash[@"threads"];
+    NSDictionary *crashedThread = nil;
+    if ([threads isKindOfClass:[NSArray class]]) {
+        for (NSDictionary *t in threads) {
+            if (![t isKindOfClass:[NSDictionary class]]) {
+                continue;
+            }
+            if ([t[@"crashed"] boolValue]) {
+                crashedThread = t;
+                break;
+            }
+        }
+        if (crashedThread == nil && threads.count > 0) {
+            crashedThread = threads.firstObject;
+        }
+    }
+    out[@"crashed_thread"] = [self normalizeThread:crashedThread];
+    out[@"registers"] = [self normalizeRegisters:crashedThread];
+
+    // binary_images — 按需过滤：仅保留栈帧实际涉及的镜像（参照 Sentry 的实践）
+    // Sentry 在 SentryCrashReportConverter 的 debugMetaForThreads: 中通过遍历线程
+    // stacktrace frames 收集被引用的 imageAddress，仅保留这些镜像，减少 90%+ 数据量。
+    // 实现：从标准化后的 crashed_thread.frames 收集指令地址，通过地址范围匹配
+    // [image_addr, image_addr + image_size) 过滤 raw binary_images 数组（路径 B）。
+    NSArray *rawImages = raw[@"binary_images"];
+
+    // 1. 收集崩溃线程栈帧中的指令地址（已标准化的 hex 字符串），转为数值集合
+    NSDictionary *normalizedThread = out[@"crashed_thread"];
+    NSArray *normalizedFrames = normalizedThread[@"frames"];
+    NSMutableSet *frameAddrs = [NSMutableSet set];
+    for (NSDictionary *f in normalizedFrames) {
+        if (![f isKindOfClass:[NSDictionary class]]) {
+            continue;
+        }
+        NSString *addrStr = f[@"address"];
+        if (![addrStr isKindOfClass:[NSString class]] || addrStr.length == 0) {
+            continue;
+        }
+        unsigned long long addr = strtoull([addrStr UTF8String], NULL, 16);
+        if (addr != 0) {
+            [frameAddrs addObject:@(addr)];
+        }
+    }
+
+    // 2. 过滤 raw binary_images：仅保留地址范围包含至少一个栈帧地址的镜像
+    NSMutableArray *filteredImages = [NSMutableArray array];
+    if ([rawImages isKindOfClass:[NSArray class]]) {
+        for (NSDictionary *img in rawImages) {
+            if (![img isKindOfClass:[NSDictionary class]]) {
+                continue;
+            }
+            // 解析 image_addr（hex 字符串或数值）和 image_size（hex 字符串或数值）
+            id imgAddrVal = img[@"image_addr"];
+            unsigned long long imgAddr = 0;
+            if ([imgAddrVal isKindOfClass:[NSString class]]) {
+                imgAddr = strtoull([imgAddrVal UTF8String], NULL, 16);
+            } else if ([imgAddrVal isKindOfClass:[NSNumber class]]) {
+                imgAddr = [(NSNumber *)imgAddrVal unsignedLongLongValue];
+            }
+            id imgSizeVal = img[@"image_size"];
+            unsigned long long imgSize = 0;
+            if ([imgSizeVal isKindOfClass:[NSString class]]) {
+                // 使用 base 0 自动检测 0x 前缀，兼容 hex 字符串
+                imgSize = strtoull([imgSizeVal UTF8String], NULL, 0);
+            } else if ([imgSizeVal isKindOfClass:[NSNumber class]]) {
+                imgSize = [(NSNumber *)imgSizeVal unsignedLongLongValue];
+            }
+            if (imgAddr == 0) {
+                continue;
+            }
+            // imgSize 为 0 时无法确定地址范围，保守保留该镜像，避免丢失符号化信息
+            if (imgSize == 0) {
+                [filteredImages addObject:img];
+                continue;
+            }
+            // 检查是否有栈帧地址落在 [imgAddr, imgAddr + imgSize) 范围内
+            // 使用减法比较避免 imgAddr + imgSize 溢出
+            BOOL referenced = NO;
+            for (NSNumber *frameAddrNum in frameAddrs) {
+                unsigned long long fa = [frameAddrNum unsignedLongLongValue];
+                if (fa >= imgAddr && (fa - imgAddr) < imgSize) {
+                    referenced = YES;
+                    break;
+                }
+            }
+            if (referenced) {
+                [filteredImages addObject:img];
+            }
+        }
+    }
+
+    // 3. fallback：如果过滤结果为空（匹配失败），输出全量镜像，避免丢失符号化信息
+    if (filteredImages.count == 0 && [rawImages isKindOfClass:[NSArray class]]) {
+        filteredImages = (NSMutableArray *)[rawImages mutableCopy];
+    }
+
+    out[@"binary_images"] = [self normalizeBinaryImages:filteredImages];
+
+    // context（来自我们注入）
+    NSDictionary *user = raw[@"user"];
+    NSDictionary *context = nil;
+    if ([user isKindOfClass:[NSDictionary class]]) {
+        id ctx = user[kRumCrashUserInfoContextKey];
+        if ([ctx isKindOfClass:[NSDictionary class]]) {
+            context = (NSDictionary *)ctx;
+        }
+    }
+    out[@"context"] = context ?: @{};
+
+    // device / app
+    NSDictionary *system = raw[@"system"];
+    if (![system isKindOfClass:[NSDictionary class]]) {
+        system = @{};
+    }
+    out[@"device"] = @{
+        @"brand": @"Apple",
+        @"model": system[@"machine"] ?: system[@"model"] ?: @"",
+        @"os_version": system[@"os_version"] ?: system[@"system_version"] ?: @"",
+    };
+    NSString *bundleIdentifier = [[NSBundle mainBundle] bundleIdentifier] ?: @"";
+    out[@"app"] = @{
+        @"version": system[@"CFBundleShortVersionString"] ?: @"",
+        @"build": system[@"CFBundleVersion"] ?: @"",
+        @"rn_version": system[@"react_native_version"] ?: @"",
+        @"package": bundleIdentifier,
+    };
+
+    return out;
+}
+
++ (NSDictionary *)normalizeThread:(NSDictionary *)thread {
+    if (![thread isKindOfClass:[NSDictionary class]]) {
+        return @{ @"id": @"", @"name": @"", @"frames": @[] };
+    }
+    NSMutableDictionary *out = [NSMutableDictionary dictionary];
+    id idx = thread[@"index"];
+    out[@"id"] = idx ? [NSString stringWithFormat:@"%@", idx] : @"";
+    out[@"name"] = thread[@"name"] ?: thread[@"dispatch_queue"] ?: @"";
+
+    NSMutableArray *frames = [NSMutableArray array];
+    NSArray *backtrace = thread[@"backtrace"];
+    NSArray *contents = nil;
+    if ([backtrace isKindOfClass:[NSDictionary class]]) {
+        contents = ((NSDictionary *)backtrace)[@"contents"];
+    } else if ([backtrace isKindOfClass:[NSArray class]]) {
+        contents = (NSArray *)backtrace;
+    }
+    // 双侧截断（参照 Sentry 推荐方案）：帧数超过 512 时保留首尾各 256 帧，
+    // 中间插入标记帧，防止递归崩溃（如 StackOverflow 产生数千帧）丢失程序入口点。
+    // normalizeThread 不在信号处理器中运行，可安全访问完整帧数组。
+    static const NSUInteger kTruncationThreshold = 512;
+    static const NSUInteger kKeepPerSide = 256;
+    if ([contents isKindOfClass:[NSArray class]]) {
+        NSUInteger totalCount = contents.count;
+        if (totalCount > kTruncationThreshold) {
+            // 前 kKeepPerSide 帧
+            for (NSUInteger i = 0; i < kKeepPerSide; i++) {
+                NSDictionary *f = contents[i];
+                if ([f isKindOfClass:[NSDictionary class]]) {
+                    [frames addObject:[self normalizeFrame:f]];
+                }
+            }
+            // 截断标记帧
+            [frames addObject:@{
+                @"truncated": @YES,
+                @"omitted_count": @(totalCount - kTruncationThreshold)
+            }];
+            // 后 kKeepPerSide 帧
+            NSUInteger tailStart = totalCount - kKeepPerSide;
+            for (NSUInteger i = tailStart; i < totalCount; i++) {
+                NSDictionary *f = contents[i];
+                if ([f isKindOfClass:[NSDictionary class]]) {
+                    [frames addObject:[self normalizeFrame:f]];
+                }
+            }
+        } else {
+            // 帧数未超阈值，全部保留
+            for (NSDictionary *f in contents) {
+                if (![f isKindOfClass:[NSDictionary class]]) {
+                    continue;
+                }
+                [frames addObject:[self normalizeFrame:f]];
+            }
+        }
+    }
+    out[@"frames"] = frames;
+    return out;
+}
+
+/** 将 KSCrash 原始帧字典标准化为协议帧字典。 */
++ (NSMutableDictionary *)normalizeFrame:(NSDictionary *)f {
+    NSMutableDictionary *frame = [NSMutableDictionary dictionary];
+    frame[@"address"] = [self hexStringFromValue:f[@"instruction_addr"]];
+    frame[@"library"] = f[@"object_name"] ?: @"";
+    id objAddr = f[@"object_addr"];
+    id insAddr = f[@"instruction_addr"];
+    if ([objAddr isKindOfClass:[NSNumber class]]
+        && [insAddr isKindOfClass:[NSNumber class]]) {
+        long long offset = [insAddr longLongValue] - [objAddr longLongValue];
+        frame[@"offset"] = [NSString stringWithFormat:@"0x%llx", offset];
+    } else {
+        frame[@"offset"] = @"";
+    }
+    return frame;
+}
+
++ (NSDictionary *)normalizeRegisters:(NSDictionary *)thread {
+    NSMutableDictionary *out = [NSMutableDictionary dictionary];
+    out[@"pc"] = @"";
+    out[@"lr"] = @"";
+    out[@"sp"] = @"";
+    out[@"fp"] = @"";
+    if (![thread isKindOfClass:[NSDictionary class]]) {
+        return out;
+    }
+    NSDictionary *registers = thread[@"registers"];
+    if (![registers isKindOfClass:[NSDictionary class]]) {
+        return out;
+    }
+    NSDictionary *basic = registers[@"basic"];
+    if (![basic isKindOfClass:[NSDictionary class]]) {
+        basic = registers;
+    }
+    // arm64 寄存器名
+    out[@"pc"] = [self hexStringFromValue:basic[@"pc"]];
+    out[@"lr"] = [self hexStringFromValue:basic[@"lr"]];
+    out[@"sp"] = [self hexStringFromValue:basic[@"sp"]];
+    out[@"fp"] = [self hexStringFromValue:basic[@"fp"] ?: basic[@"x29"]];
+    return out;
+}
+
++ (NSArray *)normalizeBinaryImages:(NSArray *)images {
+    NSMutableArray *out = [NSMutableArray array];
+    if (![images isKindOfClass:[NSArray class]]) {
+        return out;
+    }
+    for (NSDictionary *img in images) {
+        if (![img isKindOfClass:[NSDictionary class]]) {
+            continue;
+        }
+        [out addObject:@{
+            @"name": img[@"name"] ?: @"",
+            @"uuid": img[@"uuid"] ?: @"",
+            @"image_addr": [self hexStringFromValue:img[@"image_addr"]],
+            @"image_size": img[@"image_size"] ?: @0,
+        }];
+    }
+    return out;
+}
+
++ (NSString *)hexStringFromValue:(id)value {
+    if ([value isKindOfClass:[NSString class]]) {
+        NSString *s = (NSString *)value;
+        if ([s hasPrefix:@"0x"] || [s hasPrefix:@"0X"]) {
+            return s;
+        }
+        return s;
+    }
+    if ([value isKindOfClass:[NSNumber class]]) {
+        unsigned long long v = [(NSNumber *)value unsignedLongLongValue];
+        return [NSString stringWithFormat:@"0x%llx", v];
+    }
+    return @"";
+}
+
+@end