@supernathaniel/sdk

门面包：initFpPerf(config) 一次调用完成性能采集的全部接线。宿主应用（或 umi 插件）只跟这一个函数打交道。

接线内容

runtime（performance clock）→ 浏览器插件（interaction/network/performance/navigation）→ 信封 sender → transport → 生命周期 flush → 采样（本地静态 + 远端覆盖）→ trace 组装 → window.__fp 调试 API。

非浏览器环境或任何初始化异常：fail-open 返回 null，绝不影响宿主应用。

用法

import { initFpPerf } from '@supernathaniel/sdk';

const handle = initFpPerf({
  appKey: 'bom-web',                              // 必填：应用标识，后端按它注册/聚合
  // collectUrl: '/integration/perfCollect/ingest.api', // 默认值，dev 与生产同形（网关前缀路由）
  // configUrl: '/integration/perfConfig/findConfig.api', // 远端采样配置；不传则只用本地静态采样
  // compress: true,                               // gzip 上报；后端未支持 gzip 解码时必须显式 false
});
// handle.stop() 停止采集并恢复全部全局补丁、摘除 __fp

| 字段 | 默认 | 说明 | |---|---|---| | appKey | （必填） | 应用标识，随信封 meta 上报 | | collectUrl | /integration/perfCollect/ingest.api | 事件接收端点 | | configUrl | 无 | 远端采样配置地址；不传则关闭远端采样 | | flushIntervalMs | 3000 | 上报批量间隔 | | traceRate | 1 | 普通 trace 采样率 0~1；localStorage.FP_RATE 可临时调 | | slowTraceMs | 500 | 慢 trace 阈值，超过必采；localStorage.FP_SLOW_MS 可临时调 | | sessionId | sessionStorage 标签页级 id | 会话标识 | | fetchImpl | 打补丁前的 window.fetch | 上报专用，避免进入采集回路 | | compress | true | gzip 压缩上报 | | pluginFlags | 全开 | 浏览器插件开关 | | ignoreUrls | 无 | 不采集的 URL（HMR 等噪声）；string 子串或 RegExp | | streamingUrls | 无 | 采集但不占 trace 在途的长连接 URL（SSE/流式接口）；事件带 streaming:true 标记 | | exposeDebugApi | true | 是否暴露 window.__fp | | panel | true | 取证面板入口 stub；false 时完全零副作用（无监听/无存储读取/无注入） | | panelUrl | /fp-viewer/panel.js | 面板脚本地址，激活时注入 |

取证录制与面板

// 三入口任一命中即激活面板：option+shift+P（以 e.code 判定）/ ?__fp_debug=1 / localStorage.__fp_panel="1"
__fp.activatePanel()                       // 手动激活；已加载则仅 mount，不重复注入 script

const session = __fp.startRecording()      // 开始录制：窗口内 trace 全量保留 + LoAF 深采集（不新开进行中的会话）
const report = await session.stop()        // 幂等；maxDurationMs（默认 30000）超时自动停止
await session.done                         // 会话结束即 resolve 同一份报告（手动 stop 与 auto-stop 同一出口）
// report: { session: { id, startedAt, endedAt, route }, traces, degradations }
// startedAt/endedAt 为 wall clock（epoch 毫秒），可直接 new Date() 格式化
// 浏览器不支持 LoAF 时 degradations 含 "loaf-unsupported"

调试 API（控制台）

__fp.summary()  // buffer 各类型事件计数 + 已上报批次/事件数
__fp.table(50)  // 最近事件表格
__fp.traces()   // 已组装完成的 trace 列表

约束

• 本包只做组装，不实现采集逻辑：新采集能力进 runtime-browser，新事件契约进 runtime-core；
• FpInitConfig 新增字段必须可选且有默认值（破坏式变更 = schema 变更）；
• window.__fp 是消费方契约的一部分（umi 插件 runtime.js 依赖 __fp.runtime）。