@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.1

package/docs/tracker.md

@@ -0,0 +1,339 @@
+# Tracker 上报文档
+
+## 概述
+
+miniapp-simulator SDK 内置生命周期 Tracker，监控模拟器从初始化到销毁的全链路关键节点，并上报 bridge 调用情况。
+
+## APM 应用信息
+
+| 字段                           | 值                        |
+| ------------------------------ | ------------------------- |
+| 应用名（context_artifactName） | `skillbuilder-miniapp`    |
+| 点位名（measurement_name）     | `miniapp_simulator_event` |
+
+## 接入方式
+
+内置默认上报直接把自定义打点 POST 到 APM 端点，接入方无需额外安装。
+
+```typescript
+// 内置默认上报 —— business_line 必填
+createMiniAppSimulator({ tracker: { business_line: 'creator' } });
+
+// 上报到海外（rednote）
+createMiniAppSimulator({ tracker: { business_line: 'creator', region: 'sg' } });
+
+// 覆盖上报端点（可选，优先级高于 region）
+createMiniAppSimulator({
+  tracker: { business_line: 'creator', endpoint: 'https://your-apm/api/data' },
+});
+
+// 不启用（默认）
+// tracker 不传或传 false
+```
+
+> - `business_line` 取值 `creator`（创作平台）/ `audit`（审核平台），作为公共字段注入每条打点（缺省兜底 `unknown`）。
+> - 如需上报用户 ID，可在 tracker 选项里提供 `getUserInfo`（见下文「默认上报说明」）。
+> - `region`：`cn`（默认）/ `sg`（海外）。端点只按当前 hostname 选择：`localhost` / `127.0.0.1` / `0.0.0.0` / 包含 `.sit.` / 以 `local.` 开头走测试 APM；`.beta.` 和其他域名继续上报正式 APM。
+> - `endpoint`：直接指定上报 URL，传了则忽略 `region`。
+> - `debug`：打印到 console 而非真正上报；仅显式传 `true` 时开启。
+
+### 默认上报说明
+
+- **`getUserInfo` 取用户 ID**：在 tracker 选项里提供 `getUserInfo()`，SDK 上报时会调用它取
+  `userId` 作为 APM 用户标识；可同步或异步返回，未提供 / 返回空则 `userId` 留空，不影响其它字段。
+
+  ```typescript
+  createMiniAppSimulator({
+    tracker: {
+      business_line: 'creator',
+      async getUserInfo() {
+        return { userId: 'current-user-id' };
+      },
+    },
+  });
+  ```
+
+- **批量上报**：打点先进缓冲，满 10 条或最多 10s 后合并成一次请求发送；页面隐藏（`visibilitychange`）
+  与 `destroy()` 时立即冲刷，避免关闭前丢数据。
+- **本地开发**：`localhost` / `127.0.0.1` 默认上报到测试 APM；需要只看 console 时显式传 `debug: true`。
+
+## 字段说明
+
+### 公共字段
+
+每条打点自动注入，无需各事件单独声明。
+
+| 字段            | 类型     | 说明                                                                  |
+| --------------- | -------- | --------------------------------------------------------------------- |
+| `event_name`    | `string` | 事件名称                                                              |
+| `timestamp`     | `number` | 打点时间戳（ms）                                                      |
+| `business_line` | `string` | 业务线：区分使用模拟器的平台（`creator` / `audit`，默认上报模式必填） |
+| `sdk_version`   | `string` | SDK 版本号                                                            |
+| `content_mode`  | `string` | 内容模式：`half` / `fullscreen`                                       |
+| `renderer`      | `string` | 渲染器类型：`iframe-service-worker` / `webview`                       |
+
+### 事件字段
+
+同一字段在不同 `event_name` 下含义不同。
+
+| 字段         | 类型     | 说明                                                                                   |
+| ------------ | -------- | -------------------------------------------------------------------------------------- |
+| `url`        | `string` | 相关 URL                                                                               |
+| `source`     | `string` | 来源（触发来源 / 导航来源 URL）                                                        |
+| `duration`   | `number` | 耗时（ms）                                                                             |
+| `message`    | `string` | 文本信息（错误信息 / 销毁原因等）                                                      |
+| `error_name` | `string` | 标识名（错误码 / bridge 事件名）                                                       |
+| `result`     | `string` | 操作结果（`success` / `fail` / `allow` / `deny` / `cancel` / `injected` / `fallback`） |
+| `type`       | `string` | 类型标识（`zip` / `files` / 权限种类）                                                 |
+| `count`      | `number` | 数量                                                                                   |
+| `entry`      | `string` | 入口文件名                                                                             |
+
+## 上报事件清单
+
+### 维护范围
+
+| 分类 | 事件 | 策略 |
+| --- | --- | --- |
+| 核心加载 | `simulator_load_stage`、`simulator_before_load`、`simulator_ready`、`simulator_load`、`simulator_load_error`、`simulator_render_done`、`simulator_parse_done`、`simulator_sw_register`、`simulator_sw_mount` | 持续维护，用于加载耗时与成功率看板 |
+| 故障上下文 | `simulator_guest_error`、`simulator_inject_done` | 持续维护，用于解释加载失败、白屏和运行异常 |
+| 非加载生命周期 | `simulator_init`、`simulator_reload`、`simulator_navigation_blocked`、`simulator_permission_result`、`simulator_destroy`、`bridge_invoke` | 保留已有上报兼容性，不纳入核心加载口径，不继续扩展字段 |
+
+历史事件在确认无下游查询和告警依赖前不直接删除。核心加载看板只依赖前两类，避免把人工操作和普通
+JSAPI 调用耗时误判为模拟器加载耗时。
+
+### simulator_init
+
+模拟器实例构造完成时触发。
+
+| 字段  | 值             |
+| ----- | -------------- |
+| `url` | 小应用入口 URL |
+
+### simulator_before_load
+
+`load()` 触发前发出。
+
+| 字段     | 值                                                                                                    |
+| -------- | ----------------------------------------------------------------------------------------------------- |
+| `url`    | 即将加载的 URL                                                                                        |
+| `source` | 触发来源：`load` / `reload` / `switch-mode` / `switch-frame` / `load-app` / `load-zip` / `load-files` |
+
+### simulator_ready
+
+渲染容器 mount 完成时触发。仅公共字段。
+
+### simulator_load
+
+内容加载完成时触发。
+
+| 字段       | 值             |
+| ---------- | -------------- |
+| `url`      | 加载的 URL     |
+| `duration` | 加载耗时（ms） |
+
+### simulator_load_error
+
+加载失败时触发。
+
+| 字段         | 值                                                           |
+| ------------ | ------------------------------------------------------------ |
+| `url`        | 失败的 URL                                                   |
+| `error_name` | 错误码：`LOAD_TIMEOUT` / `LOAD_FAILED` / `RENDERER_ERROR` 等 |
+| `message`    | 错误信息                                                     |
+
+### simulator_render_done
+
+子文档首帧渲染完毕时触发。
+
+| 字段       | 值                 |
+| ---------- | ------------------ |
+| `url`      | 完成渲染的 URL     |
+| `duration` | 首帧渲染耗时（ms） |
+
+### simulator_reload
+
+调用 `simulator.reload()` 时触发。
+
+| 字段  | 值             |
+| ----- | -------------- |
+| `url` | 重新加载的 URL |
+
+### simulator_inject_done
+
+head 注入完成时触发。
+
+| 字段       | 值                                                      |
+| ---------- | ------------------------------------------------------- |
+| `url`      | 注入的 URL                                              |
+| `result`   | `injected`（走注入路径）/ `fallback`（降级为 src 直连） |
+| `duration` | 注入耗时（ms）                                          |
+
+### simulator_navigation_blocked
+
+iframe/webview 内部导航被拦截时触发。
+
+| 字段     | 值       |
+| -------- | -------- |
+| `source` | 来源 URL |
+| `url`    | 目标 URL |
+
+### simulator_guest_error
+
+小工具内部发生未捕获错误时触发。
+
+| 字段          | 值                                                                                                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`        | 监听的事件名：`error`（JS 异常 + 资源加载失败）/ `unhandledrejection`（Promise 未处理拒绝）/ `securitypolicyviolation`（CSP 拦截）/ `fetch`（网络失败） |
+| `error_name`  | 错误名（JS：error.name；资源：`ResourceError`；CSP：`CSPViolation`；fetch：error.name）                                                                 |
+| `message`     | JS / Promise 为错误堆栈，其余为错误消息（截断至 1000 字符）；CSP 为被拦截的指令                                                                         |
+| `source`      | JS：`filename:line:col`；资源：标签名；CSP：`sourceFile:line:col`                                                                                       |
+| `url`         | 出错脚本 / 失败资源 / 被拦截资源的 URL                                                                                                                  |
+| `disposition` | CSP 处置方式：`enforce`（拦截）/ `report`（仅上报）。仅 CSP 有                                                                                          |
+
+### simulator_parse_done
+
+`loadZip()` / `loadFiles()` 解析完成时触发。
+
+| 字段       | 值              |
+| ---------- | --------------- |
+| `type`     | `zip` / `files` |
+| `duration` | 解析耗时（ms）  |
+| `count`    | 文件数量        |
+| `entry`    | 入口文件名      |
+
+### simulator_permission_result
+
+权限弹窗操作完成时触发。
+
+| 字段     | 值                          |
+| -------- | --------------------------- |
+| `type`   | 权限种类（逗号分隔）        |
+| `result` | `allow` / `deny` / `cancel` |
+
+### simulator_destroy
+
+模拟器销毁时触发。
+
+| 字段      | 值       |
+| --------- | -------- |
+| `message` | 销毁原因 |
+
+### bridge_invoke
+
+bridge（jsapi）调用完成时触发。
+
+| 字段         | 值                              |
+| ------------ | ------------------------------- |
+| `error_name` | bridge 事件名（如 `showToast`） |
+| `result`     | `success` / `fail`              |
+| `duration`   | 成功时的执行耗时（ms）          |
+| `message`    | 失败时的错误原因                |
+
+## 核心加载链路
+
+核心诊断统一使用 `simulator_load_stage`，阶段差异放在 `stage`，不为每个阶段新增点位或字段。
+Client、Runtime 和 Core 复用远程协议中已有的 `sessionId`，上报字段统一命名为 `session_id`；
+上报不经过 MessageChannel，不增加协议字段。
+
+### 字段登记
+
+| 字段              | 类型     | 说明                                                      |
+| ----------------- | -------- | --------------------------------------------------------- |
+| `session_id`      | `string` | 一次远程模拟器连接，全链路关联键                          |
+| `app_id`          | `string` | 小工具 ID                                                 |
+| `runtime_version` | `string` | Runtime 发布版本                                          |
+| `stage`           | `string` | 低基数加载阶段                                            |
+| `result`          | `string` | `success` / `fail` / `timeout` / `fallback` / `protocol_mismatch` |
+| `duration`        | `number` | 当前阶段耗时，单位 ms                                     |
+| `type`            | `string` | 通用分类，如 `zip` / `files` / `primary` / `fallback`     |
+| `count`           | `number` | 文件或资源数量                                            |
+| `bytes`           | `number` | 包或传输体积，单位 byte                                   |
+| `network_duration` | `number` | 网络资源总耗时，单位 ms                                  |
+| `dns_duration`    | `number` | DNS 耗时，单位 ms                                         |
+| `connect_duration` | `number` | TCP/TLS 建连耗时，单位 ms                                |
+| `ttfb_duration`   | `number` | 请求发出到首字节耗时，单位 ms                             |
+| `code`            | `number` | HTTP 状态码                                               |
+| `error_name`      | `string` | 字符串业务错误码或网络错误分类                            |
+| `message`         | `string` | 截断后的错误信息，仅失败时上报                            |
+
+`business_line`、`sdk_version` 和 `renderer` 继续复用公共字段。网络字段为跨请求类型通用字段，
+同样用于 manifest、Runtime 文档、Runtime 脚本和动态策略请求。
+`request_id` 复用已有字段，不需要新增登记：`session_id` 关联一次 Runtime 连接，`request_id`
+关联该连接中的一次 `loadZip` / `loadFiles`，从 Client 资源物化一直串到 Core 和 Guest。
+`loadZip` / `loadFiles` 是核心加载入口；其他远程方法仍上报通用调用耗时，但不计入核心加载
+成功率、耗时分位和阶段漏斗。
+下载耗时不单独登记字段，统一使用 `<stage>_download` 阶段的 `duration`，例如
+`runtime_manifest_download`、`runtime_document_download` 和 `runtime_config_download`。
+
+当前 Runtime 与 Service Worker 都是单文件 bundle。模拟器自身资源由 `runtime_manifest`、
+`runtime_document`、`runtime_script`、`runtime_config` 和 `simulator_sw_register` 覆盖；其中
+`simulator_sw_register` 是 SW bootstrap、CDN SW 模块加载、安装和激活的端到端耗时。
+`request-manager` 按业务网络请求懒加载，不属于模拟器首次 ready 的关键路径。
+
+### 阶段清单
+
+| 阶段                                  | 诊断目标                                     |
+| ------------------------------------- | -------------------------------------------- |
+| `runtime_manifest`                    | Runtime 清单请求总耗时和主/备用服务结果      |
+| `runtime_document`                    | Client 观察到的 Runtime iframe 总加载耗时：导航到 `load`，包含文档、模块依赖和执行 |
+| `runtime_bootstrap`                   | Runtime 页面启动时采集的导航、模块执行和 DOM 初始化耗时，只采一次 |
+| `runtime_script`                      | Runtime 模块脚本网络分段                     |
+| `<stage>_download`                    | 对应网络阶段的响应体下载耗时                 |
+| `runtime_handshake`                   | connect 到 ready                             |
+| `runtime_config`                      | 动态策略请求总耗时和网络分段                 |
+| `simulator_create`                    | Runtime 内创建 Core 模拟器                   |
+| `runtime_ready`                       | Runtime 收到 connect 到返回 ready            |
+| `client_ready`                        | Client 创建到可调用的端到端总耗时            |
+| `package_materialize`                 | Client 侧 Blob/File 转 ArrayBuffer，带本次加载的 `request_id` |
+| `remote_request`                      | 所有远程方法调用的端到端耗时，`type` 为方法名；核心加载只筛选 `loadZip` / `loadFiles` |
+| `runtime_request`                     | Runtime 处理 `loadZip` / `loadFiles` 的耗时，旧 Client 连接时也可采集 |
+| `zip_parse`                           | 审核 Runtime 的 zip 解压                     |
+| `review_wait`                         | ZIP 解析完成到开始审核，仅隔离人工等待       |
+| `review_app_load`                     | 开始审核到 Core `loadFiles` 完成              |
+| `renderer_setup`                      | 渲染器、SW 前置准备和容器初始化              |
+| `injection_build`                     | 注入脚本与 CSP 构建                          |
+| `guest_document`                      | 小工具 iframe 文档 load                      |
+| `guest_dom_ready`                     | 小工具 DOMContentLoaded                      |
+| `guest_script_execution`              | 小工具 DOM 解析及同步脚本执行                |
+| `guest_first_paint`                   | 小工具首绘                                   |
+| `guest_resources`                     | 小工具资源数量和传输体积                     |
+| `guest_render`                        | 小工具 render-done                           |
+| `guest_error`                         | 小工具加载阶段错误码与错误信息               |
+
+Core 中的 `simulator_parse_done`、`simulator_sw_register`、`simulator_sw_mount`、
+`simulator_load` 和 `simulator_render_done` 使用同一个 `session_id`，核心包加载期间同时带
+`request_id` 和 `type`。核心加载看板依赖这些事件与 `simulator_load_stage`；权限、bridge、
+销毁等生命周期点位不纳入加载耗时口径。
+
+### 时序
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant S as Simulator Server
+    participant R as Runtime
+    participant W as Service Worker
+    participant G as Guest iframe
+    participant A as APM
+
+    C->>S: GET runtime-manifest
+    C-->>A: runtime_manifest + network phases
+    C->>R: navigate Runtime document
+    R-->>A: runtime_bootstrap / runtime_script
+    C->>R: connect(sessionId, protocol v6)
+    R->>S: fetch runtime config
+    R-->>A: runtime_config / simulator_create
+    R-->>C: ready(protocol v6)
+    C-->>A: runtime_handshake / client_ready
+    C->>R: loadZip / loadFiles
+    C-->>A: package_materialize / remote_request
+    R-->>A: runtime_request / zip_parse
+    Note over R: review_wait 隔离人工等待
+    R->>R: reviewer starts loading
+    R->>W: parse files / register / build injection / mount
+    W-->>R: MOUNT ACK
+    R->>G: navigate virtual entry
+    G-->>R: load / DOM ready / first paint / render done
+    R-->>A: review_app_load / guest_* stages
+    Note over C,A: session_id 串连接，request_id 串单次 loadZip/loadFiles
+```

package/docs/worker-runtime.md

@@ -0,0 +1,62 @@
+# 模拟器 Worker 接入
+
+模拟器和客户端使用同一份 `device-capabilities-seal.iife.min.js` 安全脚本文件。
+脚本在 miniapp-js-api 仓库的 miniapp-secure-runtime 中构建，包含设备封印、Worker 构造函数限制、
+onTerminate/offTerminate 原型 patch、单实例配额和连续隐藏 30 秒回收。
+模拟器不依赖安全运行时 npm 包，也不导入其源码、函数或类型。
+
+客户端只维护 Worker 的 `enabled` 开关。
+OffscreenCanvas、WebGL 和 transferable 使用原生行为，由业务 JS 检测、实测。
+
+## 本地联调
+
+先构建安全脚本，再将文件显式同步到模拟器：
+
+```bash
+# miniapp-js-api 仓库
+pnpm --filter @skillbuilder/miniapp-secure-runtime build
+pnpm --filter @skillbuilder/miniapp-secure-runtime test:worker
+
+# skill-designable-kit 仓库，参数为本次构建产物的绝对路径
+pnpm --filter @skillbuilder/miniapp-simulator sync:secure-runtime -- /absolute/path/to/miniapp-js-api/packages/miniapp-secure-runtime/dist/device-capabilities-seal.iife.min.js
+pnpm --filter @skillbuilder/miniapp-simulator test:worker
+pnpm --filter @skillbuilder/miniapp-simulator build:sw:dev
+pnpm --filter @skillbuilder/miniapp-simulator build:remote:dev
+```
+
+同步脚本校验文件语法、必要标记和 20,000 字节上限，按原字节复制到
+`src/injection/modules/device-capabilities-seal.iife.min.js` 并输出 SHA-256。
+该文件随模拟器代码保存；模拟器构建只读取此本地文件，不需要访问另一仓库或安装安全运行时包。
+安全运行时变更后，显式重新构建、同步文件并验证模拟器。
+完整客户端配置与约束见 miniapp-secure-runtime 的 `docs/worker-runtime.md`。
+
+## 模拟器职责
+
+`src/seal-config.ts` 由模拟器维护设备能力枚举、元数据和白名单配置。
+`src/capabilities/security-head-snippet.ts` 的 `buildSealScriptSource` 负责宿主配置序列化与静态安全脚本拼装。
+`src/worker/adapters/` 由模拟器维护以下内容：
+
+- `protocol.ts` / `manifest.json`：宿主接入类型、协议常量和默认 Worker CSP。
+- `csp-policy.ts`：Worker CSP 的校验、逐指令覆盖与默认策略回退。
+- `package-policy.ts`：根据 Worker 开关和会话标识生成宿主配置。
+- `service-worker.ts`：识别 Worker 请求，校验请求归属，将原始文件字节与独立 Worker CSP 返回。
+- `mount-recovery.ts`：资源 Service Worker 重启后，通过可信宿主恢复包快照并校验请求所属会话。
+- `page-lifecycle.ts`：将可信父窗口状态接入私有控制器。
+- `host-lifecycle.ts`：监听 iframe、宿主 CSS 可见性，接入远程 SDK 私有 MessagePort。
+- `scripts.ts`：将安全脚本返回的私有 Worker 控制器连接到模拟器生命周期适配脚本。
+
+Apollo `miniappSimulatorWorkerCspPolicies` 的获取、运行配置下发、CSP 策略处理和响应头附加均属于模拟器链路。
+Worker 用户代码原字节加载，不解析、拼接、包装或注入管理片段。
+
+## 配置与安装
+
+宿主通过只读 `__MINITOOL_WORKER_CONTEXT__` 提供 Worker 配置；设备白名单使用
+`__MINI_APP_SEAL_CONFIG__.allow`。`__MINITOOL_WORKER_STATE__` 是运行时只读状态输出。
+模拟器只注册一次 security 注入，执行完整安全脚本后将私有控制器连接到 iframe/远程宿主生命周期。
+页面可见性与销毁监听由安全脚本完成。
+
+## 验证
+
+安全运行时维护构造函数、原型 patch、生命周期和产物体积测试；
+模拟器维护包资源隔离、本地 CSP 策略、原始字节响应及 Chromium 集成测试，覆盖真实 Worker、CSP 阻断、宿主可见性与资源 SW 重启。
+Playground `/worker` 使用远程模拟器和手机壳，包含正常、关闭、旧端未接入三种模式、绘图/传输测试与 ZIP 导出。