@nebulaaa/sentry 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @nebulaaa/sentry
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+哨兵（异常监控）插件：捕获全局 JavaScript 错误、未处理的 Promise 拒绝与原生错误，统一转发给 `@nebulaaa/reporter` 上报。
+
+## 设计概览
+
+- **三通道捕获**：Web 走 `window` 的 `error` / `unhandledrejection` 事件；原生走 jsb 运行时的 `__errorHandler` 链式接管；小游戏平台当前无覆盖（见注意事项）。
+- **跨 realm 安全**：拒绝原因可能非 `Error`（跨 realm 实例、字符串、任意对象），序列化逐级回退：`message` 属性 → `String` → `JSON.stringify` → `Object.prototype.toString`，任何一级抛错都不逃逸出事件监听器。
+- **链式兼容**：原生处理器接管 `__errorHandler` 前先保存旧处理器，捕获后原样回调，不破坏宿主既有链路。
+- **监控组件底线**：自身故障（监听器抛错、写入失败）不得拖垮宿主；捕获计数与转发双层防御，开发/测试环境只记日志不上报。
+- **依赖收窄**：仅依赖 `@nebulaaa/access`（全局访问）、`@nebulaaa/reporter`（上报）、`@nebulaaa/launcher`（环境守卫）与 `@nebulaaa/ms`（时间戳）。
+
+## 安装
+
+```bash
+npm install @nebulaaa/sentry
+```
+
+依赖 `@nebulaaa/reporter` 建议 1.2.0 及以上（含切后台落盘、优先级排序等修复）。
+
+## 基本用法
+
+```ts
+import { SentryPlugin } from '@nebulaaa/sentry';
+
+const sentry = new SentryPlugin(
+  { Access: access, Reporter: reporter, Launcher: launcher },
+  {},
+);
+// 无需宿主接线：构造时自动注册全局错误监听（Web）或接管 __errorHandler（原生）
+
+// 查看捕获统计（快照副本）
+sentry.Stats; // { Total, Javascript, Promise, Native }
+```
+
+> **单例约束**：插件构造时向全局注册监听且无卸载钩子，整个应用生命周期内仅应实例化一次；重复实例化会导致监听重复注册、原生错误处理器链式叠加。
+
+## 捕获通道
+
+### Web（window 事件）
+
+- `error` → `SentryType.JAVASCRIPT`：提取 `message` / `error.stack` / `filename` / `lineno` / `colno`。
+- `unhandledrejection` → `SentryType.PROMISE`：按 `Error` / `string` / 其它对象分别提取消息与堆栈。
+
+实现说明：`addEventListener` 位于 `EventTarget.prototype`（非全局自有属性），`@access` 委托的自有属性语义（`hasOwnProperty`）不可达，故本插件直接访问 `globalThis` 并 `bind` 接收者——剥离调用在 ESM 严格模式下会因 `this` 为 `undefined` 抛 `Illegal invocation`。
+
+### 原生（`__errorHandler` 链式接管）
+
+- `sys.isNative` 时先读旧 `__errorHandler`（非函数则不参与链式），再写入本插件处理器；捕获后**先**原样回调旧处理器（保持宿主链路时序），**再**构造载荷转发。
+- 全局写入失败（`Set` 返回 `false`）时回退链引用并 `Warn`——旧处理器原位不受影响，本插件原生捕获标记为未生效。
+
+## 公共接口
+
+### `SentryPlugin`
+
+| 成员 | 签名 | 说明 |
+|---|---|---|
+| `constructor` | `(deps: SentryDeps, cfg: SentryCfg)` | 构造即注册全局捕获 |
+| `Stats` | `get Stats(): SentryStats` | 捕获统计（快照副本，消费方不可改内部状态） |
+
+### 类型
+
+```ts
+enum SentryType {
+  JAVASCRIPT = 'JAVASCRIPT',
+  PROMISE = 'PROMISE',
+  NATIVE = 'NATIVE',
+}
+
+interface SentryPayload {
+  Type: SentryType;
+  Code: string;             // JAVASCRIPT_ERROR / PROMISE_REJECTION / NATIVE_ERROR
+  Message: string;
+  Timestamp: number;
+  Stack?: string;
+  Data?: Record<string, unknown>;  // 预留字段，本插件当前不填充
+  Filename?: string;
+  Lineno?: number;
+  Colno?: number;
+}
+
+interface SentryStats {
+  Total: number;       // 捕获总数（含开发环境只记日志的捕获）
+  Javascript: number;
+  Promise: number;
+  Native: number;
+}
+
+interface SentryDeps extends PluginDeps {
+  Access: IAccessPlugin;     // 全局对象访问
+  Reporter: IReporterPlugin; // 上报中心
+  Launcher: ILauncherPlugin; // 环境守卫（IsDev / IsAlpha）
+}
+
+interface SentryCfg extends PluginCfg {}  // 当前无可配置项
+```
+
+## 转发语义
+
+捕获成功后（所有通道统一走 `sendToReporter`）：
+
+1. `Logger.Error('捕获到异常', payload)`——任何环境都记录，保留本地排查线索；
+2. `IsDev || IsAlpha` 环境直接返回（与 `@reporter.Collect` 的守卫对齐，双层防御）；
+3. 其余环境 `Reporter.Collect(ReporterType.ERROR, code, message, payload)`，由 reporter 负责攒批、重试与送达。
+
+`Stats` 在捕获时就递增（含开发环境），因此统计口径是**捕获数**而非**上报数**。
+
+## 注意事项
+
+- **单例约束**：见"基本用法"，重复实例化会叠加全局监听与原生处理器链。
+- **小游戏平台无覆盖**：微信/抖音等小游戏全局对象无 `addEventListener` 且 `sys.isNative` 为 `false`，两个捕获通道均不生效；如需支持请接入对应平台的 `onError` / `onUnhandledRejection` API。
+- **跨源脚本错误**：浏览器安全策略下跨域脚本的 `error` 事件 `error` 为 `null`、`message` 为 `Script error.`，需服务端响应 `Cross-Origin-Resource-Policy` / 脚本 `crossorigin` 属性配合才能拿到完整堆栈。
+- **拒绝原因序列化**：跨 realm `Error` 不是 `instanceof Error`，经鸭子类型提取 `message` / `stack`；自带 `message` 读取器抛错、`String`/`JSON` 转换抛错均有末级回退，不会逃逸。
+- **Data 字段**：`SentryPayload.Data` 为对外保留的扩展位，本插件当前不填充。
+
+## 构建与测试
+
+```bash
+npm run build
+npm test
+```
+
+在仓库内 `@sentry` 目录下也可直接运行：
+
+```bash
+npx tsc --noEmit -p tsconfig.json
+npx jest --config jest.config.mjs --passWithNoTests --runInBand
+```

package/dist/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@nebulaaa/sentry",
+  "version": "1.0.1",
+  "description": "哨兵（异常监控）插件",
+  "author": "doooreyn",
+  "license": "MIT",
+  "keywords": [
+    "sentry",
+    "nebulaaa"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "main": "./sentry.cjs",
+  "module": "./sentry.mjs",
+  "types": "./sentry.d.ts",
+  "exports": {
+    ".": {
+      "types": "./sentry.d.ts",
+      "require": "./sentry.cjs",
+      "import": "./sentry.mjs",
+      "default": "./sentry.cjs"
+    },
+    "./min": {
+      "types": "./sentry.d.ts",
+      "require": "./sentry.min.cjs",
+      "import": "./sentry.min.mjs"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/dist/sentry.cjs

@@ -0,0 +1,219 @@
+'use strict';
+
+var cc = require('cc');
+var ms = require('@nebulaaa/ms');
+var plugin = require('@nebulaaa/plugin');
+var reporter = require('@nebulaaa/reporter');
+
+/**
+ * 异常类型
+ */
+exports.SentryType = void 0;
+(function (SentryType) {
+    /** JavaScript 错误 */
+    SentryType["JAVASCRIPT"] = "JAVASCRIPT";
+    /** Promise 拒绝 */
+    SentryType["PROMISE"] = "PROMISE";
+    /** 原生错误 */
+    SentryType["NATIVE"] = "NATIVE";
+})(exports.SentryType || (exports.SentryType = {}));
+
+/**
+ * 哨兵能力实现
+ *
+ * 职责：
+ * - 捕获全局 JavaScript 错误
+ * - 捕获未处理的 Promise 拒绝
+ * - 通知上报中心报告异常
+ *
+ * @tip 单例组件：构造时向全局对象注册错误监听（Web）或改写 __errorHandler（原生），
+ * 且无卸载钩子，整个应用生命周期内仅应实例化一次；
+ * 重复实例化会导致监听重复注册、原生错误处理器链式叠加。
+ * @tip 平台覆盖：Web 走 window 事件、原生走 __errorHandler；
+ * 小游戏平台（微信/抖音等，全局对象无 addEventListener 且 sys.isNative 为 false）
+ * 当前无捕获覆盖，如需支持请接入对应平台 API。
+ */
+class SentryPlugin extends plugin.Plugin {
+    constructor(deps, cfg) {
+        super(deps, cfg);
+        this._stats = {
+            Total: 0,
+            Javascript: 0,
+            Promise: 0,
+            Native: 0,
+        };
+        this._jsErrorHandler = null;
+        this._promiseRejectionHandler = null;
+        this._nativeErrorHandler = null;
+        const global = this.Deps.Access.Global;
+        // Web 捕获：addEventListener 位于 EventTarget.prototype（非全局自有属性），
+        // Access.Delegate.Has/Get 的自有属性语义取不到（实测浏览器 hasOwnProperty 为 false），
+        // 故此处直接访问 globalThis 并绑定接收者——剥离调用在 ESM 严格模式下
+        // 因 this 为 undefined 抛 Illegal invocation
+        if (typeof globalThis.addEventListener === 'function') {
+            const addEventListener = globalThis.addEventListener.bind(globalThis);
+            // 注册全局错误处理器和 Promise 拒绝处理器
+            this._jsErrorHandler = this.handleJavaScriptError.bind(this);
+            this._promiseRejectionHandler = this.handlePromiseRejection.bind(this);
+            addEventListener('error', this._jsErrorHandler);
+            addEventListener('unhandledrejection', this._promiseRejectionHandler);
+        }
+        if (cc.sys.isNative) {
+            // 注册原生错误处理器：__errorHandler 由 jsb 运行时以自有属性注入，Access 语义可用；
+            // 原有处理器必须为函数才参与链式调用，避免错误发生时才抛 TypeError
+            const legacy = global.Get('__errorHandler');
+            this._nativeErrorHandler =
+                typeof legacy === 'function' ? legacy : null;
+            // Set 失败（返回 false）说明全局写入被拒：旧处理器保持原位不受影响，
+            // 但本插件的原生捕获未生效，回退链引用并告警
+            if (!global.Set('__errorHandler', this.handleNativeError.bind(this))) {
+                this._nativeErrorHandler = null;
+                this.Logger.Warn('原生错误处理器写入失败，原生捕获未生效');
+            }
+        }
+    }
+    /**
+     * 处理 JavaScript 错误
+     */
+    handleJavaScriptError(event) {
+        var _a;
+        this._stats.Total++;
+        this._stats.Javascript++;
+        const error = {
+            Type: exports.SentryType.JAVASCRIPT,
+            Code: 'JAVASCRIPT_ERROR',
+            Message: event.message || 'Unknown error',
+            Timestamp: ms.Now(),
+            Stack: (_a = event.error) === null || _a === void 0 ? void 0 : _a.stack,
+            Filename: event.filename,
+            Lineno: event.lineno,
+            Colno: event.colno,
+        };
+        this.sendToReporter(error);
+    }
+    /**
+     * 处理 Promise 拒绝
+     */
+    handlePromiseRejection(event) {
+        this._stats.Total++;
+        this._stats.Promise++;
+        const { reason } = event;
+        let message;
+        let stack;
+        if (reason instanceof Error) {
+            const { message: _message, stack: _stack } = reason;
+            message = _message;
+            stack = _stack;
+        }
+        else if (typeof reason === 'string') {
+            message = reason;
+        }
+        else {
+            message = this.stringifyReason(reason);
+            stack = this.extractStack(reason);
+        }
+        const error = {
+            Type: exports.SentryType.PROMISE,
+            Code: 'PROMISE_REJECTION',
+            Message: message,
+            Timestamp: ms.Now(),
+            Stack: stack,
+        };
+        this.sendToReporter(error);
+    }
+    /**
+     * 安全序列化拒绝原因
+     *
+     * @tip String(reason) 可因 toPrimitive/toString 抛出异常（异常将从事件监听器逃逸，
+     * 造成计数与转发不一致）；普通对象还会退化为无信息量的 '[object Object]'。
+     * 故逐级回退：message 属性 → String → JSON.stringify → Object.prototype.toString
+     */
+    stringifyReason(reason) {
+        // 跨 realm Error 实例 / 自带 message 的对象，优先提取 message
+        if (reason !== null && typeof reason === 'object') {
+            try {
+                const { message } = reason;
+                if (typeof message === 'string' && message.length > 0) {
+                    return message;
+                }
+            }
+            catch (e) {
+                // message 读取器抛错，走后续回退
+            }
+        }
+        // String 可抛（toPrimitive/toString）；结果为 '[object Object]' 时无信息量
+        try {
+            const text = String(reason);
+            if (text !== '[object Object]') {
+                return text;
+            }
+        }
+        catch (e) {
+            // 忽略，走后续回退
+        }
+        // JSON 可抛（循环引用 / toJSON 抛错）
+        try {
+            const json = JSON.stringify(reason);
+            if (typeof json === 'string') {
+                return json;
+            }
+        }
+        catch (e) {
+            // 忽略，走末级回退
+        }
+        return Object.prototype.toString.call(reason);
+    }
+    /**
+     * 提取 Error 形态对象的堆栈
+     * @tip 跨 realm Error 实例不是 instanceof Error，其 message/stack 属性原样可取
+     */
+    extractStack(reason) {
+        if (reason !== null && typeof reason === 'object') {
+            try {
+                const { stack } = reason;
+                if (typeof stack === 'string') {
+                    return stack;
+                }
+            }
+            catch (e) {
+                // stack 读取器抛错，保持 undefined
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 处理原生错误
+     */
+    handleNativeError(name, line, msg, stack) {
+        this._stats.Total++;
+        this._stats.Native++;
+        if (typeof this._nativeErrorHandler === 'function') {
+            this._nativeErrorHandler(name, line, msg, stack);
+        }
+        const error = {
+            Type: exports.SentryType.NATIVE,
+            Code: 'NATIVE_ERROR',
+            Message: msg,
+            Filename: name,
+            Lineno: line,
+            Timestamp: ms.Now(),
+            Stack: stack,
+        };
+        this.sendToReporter(error);
+    }
+    /**
+     * 报告给记者
+     */
+    sendToReporter(error) {
+        this.Logger.Error('捕获到异常', error);
+        // 开发、测试环境不上报（与 @reporter.Collect 的 IsDev||IsAlpha 守卫对齐，双层防御）
+        if (this.Deps.Launcher.IsDev || this.Deps.Launcher.IsAlpha)
+            return;
+        this.Deps.Reporter.Collect(reporter.ReporterType.ERROR, error.Code, error.Message, Object.assign({}, error));
+    }
+    get Stats() {
+        return Object.assign({}, this._stats);
+    }
+}
+
+exports.SentryPlugin = SentryPlugin;

package/dist/sentry.d.ts

@@ -0,0 +1,125 @@
+import { IAccessPlugin } from '@nebulaaa/access';
+import { ILauncherPlugin } from '@nebulaaa/launcher';
+import { IPlugin, PluginDeps, PluginCfg, Plugin } from '@nebulaaa/plugin';
+import { IReporterPlugin } from '@nebulaaa/reporter';
+
+/**
+ * 异常类型
+ */
+declare enum SentryType {
+    /** JavaScript 错误 */
+    JAVASCRIPT = "JAVASCRIPT",
+    /** Promise 拒绝 */
+    PROMISE = "PROMISE",
+    /** 原生错误 */
+    NATIVE = "NATIVE"
+}
+/**
+ * 异常数据
+ */
+interface SentryPayload {
+    /** 异常类型 */
+    Type: SentryType;
+    /** 异常代码 */
+    Code: string;
+    /** 异常消息 */
+    Message: string;
+    /** 异常时间戳 */
+    Timestamp: number;
+    /** 异常堆栈 */
+    Stack?: string;
+    /** 额外数据 */
+    Data?: Record<string, unknown>;
+    /** 文件名 */
+    Filename?: string;
+    /** 行号 */
+    Lineno?: number;
+    /** 列号 */
+    Colno?: number;
+}
+/**
+ * 哨兵统计
+ */
+interface SentryStats {
+    /** 捕获的错误总数 */
+    Total: number;
+    /** 捕获的 JavaScript 错误总数 */
+    Javascript: number;
+    /** 捕获的 Promise 拒绝总数 */
+    Promise: number;
+    /** 捕获的原生错误总数 */
+    Native: number;
+}
+/** 哨兵插件依赖 */
+interface SentryDeps extends PluginDeps {
+    Access: IAccessPlugin;
+    Reporter: IReporterPlugin;
+    Launcher: ILauncherPlugin;
+}
+/** 哨兵插件配置 */
+interface SentryCfg extends PluginCfg {
+}
+/** 哨兵插件接口 */
+interface ISentryPlugin extends IPlugin<SentryDeps, SentryCfg> {
+    get Stats(): SentryStats;
+}
+
+/**
+ * 哨兵能力实现
+ *
+ * 职责：
+ * - 捕获全局 JavaScript 错误
+ * - 捕获未处理的 Promise 拒绝
+ * - 通知上报中心报告异常
+ *
+ * @tip 单例组件：构造时向全局对象注册错误监听（Web）或改写 __errorHandler（原生），
+ * 且无卸载钩子，整个应用生命周期内仅应实例化一次；
+ * 重复实例化会导致监听重复注册、原生错误处理器链式叠加。
+ * @tip 平台覆盖：Web 走 window 事件、原生走 __errorHandler；
+ * 小游戏平台（微信/抖音等，全局对象无 addEventListener 且 sys.isNative 为 false）
+ * 当前无捕获覆盖，如需支持请接入对应平台 API。
+ */
+declare class SentryPlugin extends Plugin<SentryDeps, SentryCfg> implements ISentryPlugin {
+    /** 统计 */
+    private _stats;
+    /** JavaScript 错误处理器 */
+    private _jsErrorHandler;
+    /** Promise 拒绝处理器 */
+    private _promiseRejectionHandler;
+    /** 原生错误捕获 */
+    private _nativeErrorHandler;
+    constructor(deps: SentryDeps, cfg: SentryCfg);
+    /**
+     * 处理 JavaScript 错误
+     */
+    private handleJavaScriptError;
+    /**
+     * 处理 Promise 拒绝
+     */
+    private handlePromiseRejection;
+    /**
+     * 安全序列化拒绝原因
+     *
+     * @tip String(reason) 可因 toPrimitive/toString 抛出异常（异常将从事件监听器逃逸，
+     * 造成计数与转发不一致）；普通对象还会退化为无信息量的 '[object Object]'。
+     * 故逐级回退：message 属性 → String → JSON.stringify → Object.prototype.toString
+     */
+    private stringifyReason;
+    /**
+     * 提取 Error 形态对象的堆栈
+     * @tip 跨 realm Error 实例不是 instanceof Error，其 message/stack 属性原样可取
+     */
+    private extractStack;
+    /**
+     * 处理原生错误
+     */
+    private handleNativeError;
+    /**
+     * 报告给记者
+     */
+    private sendToReporter;
+    get Stats(): SentryStats;
+}
+
+export { SentryPlugin, SentryType };
+export type { ISentryPlugin, SentryCfg, SentryDeps, SentryPayload, SentryStats };

package/dist/sentry.min.cjs

@@ -0,0 +1 @@
+"use strict";var e,t=require("cc"),r=require("@nebulaaa/ms"),s=require("@nebulaaa/plugin"),n=require("@nebulaaa/reporter");exports.SentryType=void 0,(e=exports.SentryType||(exports.SentryType={})).JAVASCRIPT="JAVASCRIPT",e.PROMISE="PROMISE",e.NATIVE="NATIVE";class i extends s.Plugin{constructor(e,r){super(e,r),this._stats={Total:0,Javascript:0,Promise:0,Native:0},this._jsErrorHandler=null,this._promiseRejectionHandler=null,this._nativeErrorHandler=null;const s=this.Deps.Access.Global;if("function"==typeof globalThis.addEventListener){const e=globalThis.addEventListener.bind(globalThis);this._jsErrorHandler=this.handleJavaScriptError.bind(this),this._promiseRejectionHandler=this.handlePromiseRejection.bind(this),e("error",this._jsErrorHandler),e("unhandledrejection",this._promiseRejectionHandler)}if(t.sys.isNative){const e=s.Get("__errorHandler");this._nativeErrorHandler="function"==typeof e?e:null,s.Set("__errorHandler",this.handleNativeError.bind(this))||(this._nativeErrorHandler=null,this.Logger.Warn("原生错误处理器写入失败，原生捕获未生效"))}}handleJavaScriptError(e){var t;this._stats.Total++,this._stats.Javascript++;const s={Type:exports.SentryType.JAVASCRIPT,Code:"JAVASCRIPT_ERROR",Message:e.message||"Unknown error",Timestamp:r.Now(),Stack:null===(t=e.error)||void 0===t?void 0:t.stack,Filename:e.filename,Lineno:e.lineno,Colno:e.colno};this.sendToReporter(s)}handlePromiseRejection(e){this._stats.Total++,this._stats.Promise++;const{reason:t}=e;let s,n;if(t instanceof Error){const{message:e,stack:r}=t;s=e,n=r}else"string"==typeof t?s=t:(s=this.stringifyReason(t),n=this.extractStack(t));const i={Type:exports.SentryType.PROMISE,Code:"PROMISE_REJECTION",Message:s,Timestamp:r.Now(),Stack:n};this.sendToReporter(i)}stringifyReason(e){if(null!==e&&"object"==typeof e)try{const{message:t}=e;if("string"==typeof t&&t.length>0)return t}catch(e){}try{const t=String(e);if("[object Object]"!==t)return t}catch(e){}try{const t=JSON.stringify(e);if("string"==typeof t)return t}catch(e){}return Object.prototype.toString.call(e)}extractStack(e){if(null!==e&&"object"==typeof e)try{const{stack:t}=e;if("string"==typeof t)return t}catch(e){}}handleNativeError(e,t,s,n){this._stats.Total++,this._stats.Native++,"function"==typeof this._nativeErrorHandler&&this._nativeErrorHandler(e,t,s,n);const i={Type:exports.SentryType.NATIVE,Code:"NATIVE_ERROR",Message:s,Filename:e,Lineno:t,Timestamp:r.Now(),Stack:n};this.sendToReporter(i)}sendToReporter(e){this.Logger.Error("捕获到异常",e),this.Deps.Launcher.IsDev||this.Deps.Launcher.IsAlpha||this.Deps.Reporter.Collect(n.ReporterType.ERROR,e.Code,e.Message,Object.assign({},e))}get Stats(){return Object.assign({},this._stats)}}exports.SentryPlugin=i;

package/dist/sentry.min.mjs

@@ -0,0 +1 @@
+import{sys as t}from"cc";import{Now as e}from"@nebulaaa/ms";import{Plugin as r}from"@nebulaaa/plugin";import{ReporterType as s}from"@nebulaaa/reporter";var n;!function(t){t.JAVASCRIPT="JAVASCRIPT",t.PROMISE="PROMISE",t.NATIVE="NATIVE"}(n||(n={}));class i extends r{constructor(e,r){super(e,r),this._stats={Total:0,Javascript:0,Promise:0,Native:0},this._jsErrorHandler=null,this._promiseRejectionHandler=null,this._nativeErrorHandler=null;const s=this.Deps.Access.Global;if("function"==typeof globalThis.addEventListener){const t=globalThis.addEventListener.bind(globalThis);this._jsErrorHandler=this.handleJavaScriptError.bind(this),this._promiseRejectionHandler=this.handlePromiseRejection.bind(this),t("error",this._jsErrorHandler),t("unhandledrejection",this._promiseRejectionHandler)}if(t.isNative){const t=s.Get("__errorHandler");this._nativeErrorHandler="function"==typeof t?t:null,s.Set("__errorHandler",this.handleNativeError.bind(this))||(this._nativeErrorHandler=null,this.Logger.Warn("原生错误处理器写入失败，原生捕获未生效"))}}handleJavaScriptError(t){var r;this._stats.Total++,this._stats.Javascript++;const s={Type:n.JAVASCRIPT,Code:"JAVASCRIPT_ERROR",Message:t.message||"Unknown error",Timestamp:e(),Stack:null===(r=t.error)||void 0===r?void 0:r.stack,Filename:t.filename,Lineno:t.lineno,Colno:t.colno};this.sendToReporter(s)}handlePromiseRejection(t){this._stats.Total++,this._stats.Promise++;const{reason:r}=t;let s,i;if(r instanceof Error){const{message:t,stack:e}=r;s=t,i=e}else"string"==typeof r?s=r:(s=this.stringifyReason(r),i=this.extractStack(r));const o={Type:n.PROMISE,Code:"PROMISE_REJECTION",Message:s,Timestamp:e(),Stack:i};this.sendToReporter(o)}stringifyReason(t){if(null!==t&&"object"==typeof t)try{const{message:e}=t;if("string"==typeof e&&e.length>0)return e}catch(t){}try{const e=String(t);if("[object Object]"!==e)return e}catch(t){}try{const e=JSON.stringify(t);if("string"==typeof e)return e}catch(t){}return Object.prototype.toString.call(t)}extractStack(t){if(null!==t&&"object"==typeof t)try{const{stack:e}=t;if("string"==typeof e)return e}catch(t){}}handleNativeError(t,r,s,i){this._stats.Total++,this._stats.Native++,"function"==typeof this._nativeErrorHandler&&this._nativeErrorHandler(t,r,s,i);const o={Type:n.NATIVE,Code:"NATIVE_ERROR",Message:s,Filename:t,Lineno:r,Timestamp:e(),Stack:i};this.sendToReporter(o)}sendToReporter(t){this.Logger.Error("捕获到异常",t),this.Deps.Launcher.IsDev||this.Deps.Launcher.IsAlpha||this.Deps.Reporter.Collect(s.ERROR,t.Code,t.Message,Object.assign({},t))}get Stats(){return Object.assign({},this._stats)}}export{i as SentryPlugin,n as SentryType};

package/dist/sentry.mjs

@@ -0,0 +1,217 @@
+import { sys } from 'cc';
+import { Now } from '@nebulaaa/ms';
+import { Plugin } from '@nebulaaa/plugin';
+import { ReporterType } from '@nebulaaa/reporter';
+
+/**
+ * 异常类型
+ */
+var SentryType;
+(function (SentryType) {
+    /** JavaScript 错误 */
+    SentryType["JAVASCRIPT"] = "JAVASCRIPT";
+    /** Promise 拒绝 */
+    SentryType["PROMISE"] = "PROMISE";
+    /** 原生错误 */
+    SentryType["NATIVE"] = "NATIVE";
+})(SentryType || (SentryType = {}));
+
+/**
+ * 哨兵能力实现
+ *
+ * 职责：
+ * - 捕获全局 JavaScript 错误
+ * - 捕获未处理的 Promise 拒绝
+ * - 通知上报中心报告异常
+ *
+ * @tip 单例组件：构造时向全局对象注册错误监听（Web）或改写 __errorHandler（原生），
+ * 且无卸载钩子，整个应用生命周期内仅应实例化一次；
+ * 重复实例化会导致监听重复注册、原生错误处理器链式叠加。
+ * @tip 平台覆盖：Web 走 window 事件、原生走 __errorHandler；
+ * 小游戏平台（微信/抖音等，全局对象无 addEventListener 且 sys.isNative 为 false）
+ * 当前无捕获覆盖，如需支持请接入对应平台 API。
+ */
+class SentryPlugin extends Plugin {
+    constructor(deps, cfg) {
+        super(deps, cfg);
+        this._stats = {
+            Total: 0,
+            Javascript: 0,
+            Promise: 0,
+            Native: 0,
+        };
+        this._jsErrorHandler = null;
+        this._promiseRejectionHandler = null;
+        this._nativeErrorHandler = null;
+        const global = this.Deps.Access.Global;
+        // Web 捕获：addEventListener 位于 EventTarget.prototype（非全局自有属性），
+        // Access.Delegate.Has/Get 的自有属性语义取不到（实测浏览器 hasOwnProperty 为 false），
+        // 故此处直接访问 globalThis 并绑定接收者——剥离调用在 ESM 严格模式下
+        // 因 this 为 undefined 抛 Illegal invocation
+        if (typeof globalThis.addEventListener === 'function') {
+            const addEventListener = globalThis.addEventListener.bind(globalThis);
+            // 注册全局错误处理器和 Promise 拒绝处理器
+            this._jsErrorHandler = this.handleJavaScriptError.bind(this);
+            this._promiseRejectionHandler = this.handlePromiseRejection.bind(this);
+            addEventListener('error', this._jsErrorHandler);
+            addEventListener('unhandledrejection', this._promiseRejectionHandler);
+        }
+        if (sys.isNative) {
+            // 注册原生错误处理器：__errorHandler 由 jsb 运行时以自有属性注入，Access 语义可用；
+            // 原有处理器必须为函数才参与链式调用，避免错误发生时才抛 TypeError
+            const legacy = global.Get('__errorHandler');
+            this._nativeErrorHandler =
+                typeof legacy === 'function' ? legacy : null;
+            // Set 失败（返回 false）说明全局写入被拒：旧处理器保持原位不受影响，
+            // 但本插件的原生捕获未生效，回退链引用并告警
+            if (!global.Set('__errorHandler', this.handleNativeError.bind(this))) {
+                this._nativeErrorHandler = null;
+                this.Logger.Warn('原生错误处理器写入失败，原生捕获未生效');
+            }
+        }
+    }
+    /**
+     * 处理 JavaScript 错误
+     */
+    handleJavaScriptError(event) {
+        var _a;
+        this._stats.Total++;
+        this._stats.Javascript++;
+        const error = {
+            Type: SentryType.JAVASCRIPT,
+            Code: 'JAVASCRIPT_ERROR',
+            Message: event.message || 'Unknown error',
+            Timestamp: Now(),
+            Stack: (_a = event.error) === null || _a === void 0 ? void 0 : _a.stack,
+            Filename: event.filename,
+            Lineno: event.lineno,
+            Colno: event.colno,
+        };
+        this.sendToReporter(error);
+    }
+    /**
+     * 处理 Promise 拒绝
+     */
+    handlePromiseRejection(event) {
+        this._stats.Total++;
+        this._stats.Promise++;
+        const { reason } = event;
+        let message;
+        let stack;
+        if (reason instanceof Error) {
+            const { message: _message, stack: _stack } = reason;
+            message = _message;
+            stack = _stack;
+        }
+        else if (typeof reason === 'string') {
+            message = reason;
+        }
+        else {
+            message = this.stringifyReason(reason);
+            stack = this.extractStack(reason);
+        }
+        const error = {
+            Type: SentryType.PROMISE,
+            Code: 'PROMISE_REJECTION',
+            Message: message,
+            Timestamp: Now(),
+            Stack: stack,
+        };
+        this.sendToReporter(error);
+    }
+    /**
+     * 安全序列化拒绝原因
+     *
+     * @tip String(reason) 可因 toPrimitive/toString 抛出异常（异常将从事件监听器逃逸，
+     * 造成计数与转发不一致）；普通对象还会退化为无信息量的 '[object Object]'。
+     * 故逐级回退：message 属性 → String → JSON.stringify → Object.prototype.toString
+     */
+    stringifyReason(reason) {
+        // 跨 realm Error 实例 / 自带 message 的对象，优先提取 message
+        if (reason !== null && typeof reason === 'object') {
+            try {
+                const { message } = reason;
+                if (typeof message === 'string' && message.length > 0) {
+                    return message;
+                }
+            }
+            catch (e) {
+                // message 读取器抛错，走后续回退
+            }
+        }
+        // String 可抛（toPrimitive/toString）；结果为 '[object Object]' 时无信息量
+        try {
+            const text = String(reason);
+            if (text !== '[object Object]') {
+                return text;
+            }
+        }
+        catch (e) {
+            // 忽略，走后续回退
+        }
+        // JSON 可抛（循环引用 / toJSON 抛错）
+        try {
+            const json = JSON.stringify(reason);
+            if (typeof json === 'string') {
+                return json;
+            }
+        }
+        catch (e) {
+            // 忽略，走末级回退
+        }
+        return Object.prototype.toString.call(reason);
+    }
+    /**
+     * 提取 Error 形态对象的堆栈
+     * @tip 跨 realm Error 实例不是 instanceof Error，其 message/stack 属性原样可取
+     */
+    extractStack(reason) {
+        if (reason !== null && typeof reason === 'object') {
+            try {
+                const { stack } = reason;
+                if (typeof stack === 'string') {
+                    return stack;
+                }
+            }
+            catch (e) {
+                // stack 读取器抛错，保持 undefined
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 处理原生错误
+     */
+    handleNativeError(name, line, msg, stack) {
+        this._stats.Total++;
+        this._stats.Native++;
+        if (typeof this._nativeErrorHandler === 'function') {
+            this._nativeErrorHandler(name, line, msg, stack);
+        }
+        const error = {
+            Type: SentryType.NATIVE,
+            Code: 'NATIVE_ERROR',
+            Message: msg,
+            Filename: name,
+            Lineno: line,
+            Timestamp: Now(),
+            Stack: stack,
+        };
+        this.sendToReporter(error);
+    }
+    /**
+     * 报告给记者
+     */
+    sendToReporter(error) {
+        this.Logger.Error('捕获到异常', error);
+        // 开发、测试环境不上报（与 @reporter.Collect 的 IsDev||IsAlpha 守卫对齐，双层防御）
+        if (this.Deps.Launcher.IsDev || this.Deps.Launcher.IsAlpha)
+            return;
+        this.Deps.Reporter.Collect(ReporterType.ERROR, error.Code, error.Message, Object.assign({}, error));
+    }
+    get Stats() {
+        return Object.assign({}, this._stats);
+    }
+}
+
+export { SentryPlugin, SentryType };

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@nebulaaa/sentry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "哨兵（异常监控）插件",
+  "main": "./dist/sentry.cjs",
+  "module": "./dist/sentry.mjs",
+  "types": "./dist/sentry.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/sentry.d.ts",
+      "import": "./dist/sentry.mjs",
+      "require": "./dist/sentry.cjs",
+      "default": "./dist/sentry.cjs"
+    },
+    "./min": {
+      "types": "./dist/sentry.d.ts",
+      "import": "./dist/sentry.min.mjs",
+      "require": "./dist/sentry.min.cjs",
+      "default": "./dist/sentry.min.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && rollup -c rollup.config.mjs && node ../scripts/write-dist-package.mjs sentry",
+    "test": "jest --config jest.config.mjs --passWithNoTests"
+  },
+  "keywords": [
+    "sentry",
+    "nebulaaa"
+  ],
+  "author": "doooreyn",
+  "license": "MIT",
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=10.0.0",
+      "onFail": "warn"
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "allowScripts": {
+    "unrs-resolver@1.12.2": true,
+    "@parcel/watcher@2.6.0": true
+  },
+  "devDependencies": {
+    "@cocos/creator-types": "^3.8.8",
+    "@rollup/plugin-terser": "^1.0.2",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "jest": "^30.5.2",
+    "rollup": "^4.28.1",
+    "rollup-plugin-dts": "^6.1.1",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "5.7.3"
+  },
+  "dependencies": {
+    "@nebulaaa/access": "^2.0.4",
+    "@nebulaaa/launcher": "^2.0.1",
+    "@nebulaaa/ms": "^1.1.0",
+    "@nebulaaa/plugin": "^1.0.0",
+    "@nebulaaa/reporter": "^1.0.2"
+  }
+}