spy-client 2.1.14 → 2.2.1

package/.travis.yml

@@ -1,7 +1,7 @@
 language: node_js
 
 node_js:
-  - '12'
+  - '24'
 
 env:
   - TRAVIS=true
@@ -9,9 +9,12 @@ env:
 addons:
   chrome: stable
 
+before_install:
+  - "corepack enable"
+
 before_script:
-  - "npm install"
-  - "npm run build"
+  - "pnpm install"
+  - "pnpm build"
 
 script:
-  - "npm run test"
+  - "pnpm test"

package/AGENTS.md

@@ -0,0 +1,132 @@
+# spy-client 开发指南
+
+## 项目定位
+
+本仓库是 spy 日志采集 SDK，使用 TypeScript 开发，提供基础版 `spy-client-basic`、增强版 `spy-client` 和可尽早加载的 `spy-head`。SDK 面向浏览器，也允许基础版通过覆盖 `request` 适配 Node.js、跨端框架和小程序。
+
+SDK 只负责采集、校验、采样和发送，不负责 Nginx 接入、统计聚合或平台查询。修改发送协议时必须联动 `rec-nginx`、`webb-analysis`、`webb-realtime` 和平台查询。
+
+## 技术栈和兼容性
+
+- TypeScript 6、Rollup 4、TypeScript compiler。
+- oxlint 静态检查。
+- Playwright Test 端到端测试，使用本机 Chrome，不下载 Playwright 浏览器。
+- `core-js` 运行时依赖。
+- Performance、Long Task、LCP、FID、CLS、Resource Timing、Navigator 等浏览器 API。
+
+开发环境要求 Node.js `>=24`，包管理器使用 pnpm `10.33.0`。构建目标保持 ES5，发布包保留 UMD、IIFE、ESM 和 `.mjs` 多格式产物。
+
+基础版日志类型包括 `perf`、`except`、`dist`、`count`。增强版包含更多性能和异常采集模块并依赖浏览器能力；`spy-head` 负责全局 JS 错误、资源错误、白屏和部分早期性能观察。
+
+## 运行与发送链路
+
+```text
+业务页面/跨端应用
+  → SpyClient 参数、字段和采样处理
+  → Image / Beacon / fetch 或自定义 request
+  → rec-nginx 日志接入
+  → 批处理或实时分析
+```
+
+公共字段通常包括 `pid`、`lid`、时间戳、类型、分组、`info` 和 `dim`。修改字段名、类型、采样语义、默认服务地址或请求方法时，要检查 Nginx 路由、protobuf 以及下游解析。
+
+## 目录说明
+
+```text
+spy-client/
+├── src/
+│   ├── spy-client.ts          # 增强版入口
+│   ├── spy-client-basic.ts    # 基础版入口和公共发送逻辑
+│   ├── spy-head.ts            # 早期注入入口
+│   ├── module/                # timing、LCP、FID、TTI、资源、LongTask 等
+│   ├── head/                  # 错误、白屏、资源观察
+│   ├── lib/                   # 数据、压缩、工具和接口
+│   └── types/                 # 全局类型
+├── test/e2e/                  # Playwright Test 测试
+├── example/                   # 本地示例和缓存示例
+├── rollup.config.mjs
+├── playwright.config.ts
+├── .oxlintrc.json
+├── tsconfig.json
+├── pnpm-lock.yaml
+└── package.json
+```
+
+## 配置和产物
+
+构建产物全部位于 `dist/`，包括基础版、增强版、`spy-head`、`spy-local-cache` 及其压缩文件和声明文件。`spy-client`、`spy-client-basic` 额外生成 IIFE、ESM 和 `.mjs` 格式。
+
+## 开发命令
+
+```bash
+pnpm install
+pnpm run lint
+pnpm run test
+pnpm run build
+pnpm run dev
+pnpm run watch
+pnpm run example
+```
+
+`build` 是生产 Rollup 构建；`test` 使用 Playwright Test，并通过 `playwright.config.ts` 启动静态服务器和系统 Chrome；`lint` 使用 oxlint 检查 `src`；`example` 会启动开发构建和本地示例服务。
+
+发布命令必须单独确认：
+
+```bash
+pnpm run release_pre
+pnpm run release
+pnpm run release_post
+```
+
+其中 `release_pre` 会重新构建、lint、测试；`release` 会修改版本并发布 npm；`release_post` 会推送分支和 tag，不得在普通验证中执行。
+
+## 测试要求
+
+修改公共发送逻辑时至少覆盖：
+
+- 必填 `pid` 和非法字段。
+- 四种日志类型。
+- 全局采样和单条采样覆盖关系。
+- `info`/`dim` 字段编码和边界。
+- 浏览器发送成功、发送失败和自定义 request。
+- 基础版与增强版运行时差异。
+
+修改性能模块时检查对应浏览器 API 不可用的降级行为。增强版不得引入只适用于 Node.js 的全局假设。
+
+## 常见问题
+
+### 上报没有到达
+
+检查实例参数、采样值、浏览器 Network、请求 URL、CORS/凭据、Nginx 路由和服务端日志。不能只看 SDK 是否调用成功。
+
+### 指标为空或字段丢失
+
+检查指标是否在正确的 `info`/`dim` 中、字段是否通过 SDK 校验、Nginx/Lua 是否截断，以及批处理/实时消费者是否支持新字段。
+
+### Node.js/跨端加载异常
+
+基础版需要按源码约定覆盖请求实现；增强版依赖浏览器 API。不能把 README 中“支持跨端”理解为所有构建产物都能在裸 Node.js 直接加载。
+
+## 跨仓库约束
+
+- SDK payload 变更必须检查 `rec-nginx/conf/proto/` 和 Lua。
+- 日志类型变更必须检查批处理目录、实时同步副本和 Server 查询。
+- 指标或维度变更要评估平台维度组合数和存储成本。
+- README 中历史 CDN 版本、仓库地址和示例只作为线索，不能覆盖当前 package/source 事实。
+
+## 安全边界
+
+- 不在示例、测试和日志中写入 token、Cookie 或真实业务数据。
+- 不将外部输入直接拼接 URL、查询参数或 HTML。
+- 不使用生产服务做自动化压力测试。
+- 采集字段可能包含 URL、错误堆栈和请求相关信息，新增字段需评估隐私与数据量。
+
+## 验证清单
+
+- [ ] `pnpm run lint`
+- [ ] `pnpm run test`
+- [ ] `pnpm run build`
+- [ ] 检查 `dist/` 入口和声明文件
+- [ ] 验证成功、采样为零、非法参数和 request 失败
+- [ ] 检查下游日志协议兼容
+- [ ] 不执行 npm/pnpm 发布和远端推送

package/README.md

@@ -7,11 +7,19 @@
 2. 从2.1.0版本开始，不再兼容IE8及以下IE浏览器
 3. 从2.1.8版本开始，兼容小程序环境（new Image类发送）；通过继承类，覆盖request方法，可以支持Node.js/跨端框架/小程序环境
 
+## 开发环境
+
+- Node.js `>=24`
+- pnpm `10.33.0`（项目通过 `packageManager` 字段声明）
+- 测试需要本机已安装 Google Chrome。Playwright 使用系统 Chrome，不会下载 Playwright 自带的浏览器。
+
+项目使用 Rollup 4 构建，并保留 ES5 兼容目标。`spy-client` 和 `spy-client-basic` 会生成 UMD、IIFE、ESM 和 `.mjs` 格式；`spy-head` 和 `spy-local-cache` 生成 UMD 格式。TypeScript 类型声明由构建脚本单独生成。
+
 
 ## 安装
 
 ```
-npm install spy-client --save
+pnpm add spy-client
 ```
 
 CDN方式
@@ -20,13 +28,13 @@ CDN方式
 
 ```html
 <!--增强版SDK-->
-<script src="https://code.bdstatic.com/npm/spy-client@2.1.8/dist/spy-client.min.js" type="text/javascript"></script>
+<script src="https://code.bdstatic.com/npm/spy-client@2.2.0/dist/spy-client.min.js" type="text/javascript"></script>
 
 <!--增强版SDK spy-head-->
-<script src="https://code.bdstatic.com/npm/spy-client@2.1.8/dist/spy-head.min.js" type="text/javascript"></script>
+<script src="https://code.bdstatic.com/npm/spy-client@2.2.0/dist/spy-head.min.js" type="text/javascript"></script>
 
 <!--基础版SDK-->
-<script src="https://code.bdstatic.com/npm/spy-client@2.1.8/dist/spy-client-basic.min.js" type="text/javascript"></script>
+<script src="https://code.bdstatic.com/npm/spy-client@2.2.0/dist/spy-client-basic.min.js" type="text/javascript"></script>
 
 ```
 
@@ -871,6 +879,9 @@ export interface NavigatorInfoMetric {
 
 ## 自定义构建
 
+#### node版本
+Node.js版本 >= 24，包管理器使用 pnpm 10.33.0
+
 #### clone准备
 如果觉得spy-client太大，只想要部分模块，比如禁用 longtask，可以拉取源码，自行编译
 
@@ -878,7 +889,7 @@ export interface NavigatorInfoMetric {
 git clone https://github.com/kaivean/spy-client.git
 
 cd spy-client
-npm install
+pnpm install
 ```
 
 #### 禁用模块
@@ -898,7 +909,7 @@ npm install
 #### 构建
 
 ```bash
-npm run build
+pnpm run build
 ```
 
 然后找到dist/spy-client.min.js 就是构建压缩版代码
@@ -908,33 +919,33 @@ npm run build
 
 ```bash
 # 启动本地调试页面，进行调试
-npm run example
+pnpm run example
 
 # 进行watch 编译， 一般和上个命令配合使用
-npm run watch
+pnpm run watch
 
-# lint
-npm run lint
+# 使用 oxlint 检查 src
+pnpm run lint
 
-# 测试
-npm run test
+# 使用系统 Chrome 运行 Playwright 测试
+pnpm run test
 
 # production编译，产出到dist
-npm run build
+pnpm run build
 
 # development编译，产出到dist
-npm run dev
+pnpm run dev
 
 # 发布
 # 1. 构建测试
-npm run release_pre
+pnpm run release_pre
 # 2. 提交代码
 git add . && git commit -m "升级/Fix"
 # 3. 发布npm包，增加tag
-npm run release
+pnpm run release
 
 # 4. 修改Readme文档里版本号
 git add . && git commit -m "修改文档版本"
 # 5. 把代码push到远程
-npm run release_post
-```
+pnpm run release_post
+```

package/dist/head/base.d.ts

@@ -1,25 +1,27 @@
-/**
- * @file 资源、JS、白屏监控的基础
- * @author kaivean
- */
-import { SpyHeadConf } from '../lib/spyHeadInterface';
-interface SendObj {
-    type?: 'perf' | 'except' | 'dist' | 'count';
-    group: string;
-    info: any;
-    dim?: any;
-    lid?: string;
-    pid?: string;
-    ts?: number;
-}
-declare const _default: {
-    conf: SpyHeadConf;
-    winerrors: SendObj[];
-    errorDestroy(): void;
-    observerDestroy(): void;
-    entryMap: any;
-    init(conf: SpyHeadConf): void;
-    addError(obj: SendObj): void;
-    send(obj: SendObj, isSend?: boolean, logServer?: string): void;
-};
-export default _default;
+/**
+ * @file 资源、JS、白屏监控的基础
+ * @author kaivean
+ */
+import { SpyHeadConf, SpyHeadUpdateConf } from '../lib/spyHeadInterface';
+interface SendObj {
+    type?: 'perf' | 'except' | 'dist' | 'count';
+    group: string;
+    info: any;
+    dim?: any;
+    lid?: string;
+    pid?: string;
+    ts?: number;
+}
+declare const _default: {
+    conf: SpyHeadConf;
+    winerrors: SendObj[];
+    errorDestroy(): void;
+    observerDestroy(): void;
+    entryMap: any;
+    interceptor: ((obj: SendObj) => void) | undefined;
+    init(conf: SpyHeadConf): void;
+    update(conf: SpyHeadUpdateConf): void;
+    addError(obj: SendObj): void;
+    send(obj: SendObj, isSend?: boolean, logServer?: string): void;
+};
+export default _default;

package/dist/head/error.d.ts

@@ -1,6 +1,6 @@
-/**
- * @file 资源和JS错误监控
- * @author kaivean
- */
-import { SpyHeadConf } from '../lib/spyHeadInterface';
-export declare function init(conf: SpyHeadConf): void;
+/**
+ * @file 资源和JS错误监控
+ * @author kaivean
+ */
+import { SpyHeadConf } from '../lib/spyHeadInterface';
+export declare function init(conf: SpyHeadConf): void;

package/dist/head/observer.d.ts

@@ -1,5 +1,5 @@
-/**
- * @file PerformanceObserver指标采集
- * @author kaivean
- */
-export declare function init(): void;
+/**
+ * @file PerformanceObserver指标采集
+ * @author kaivean
+ */
+export declare function init(): void;

package/dist/head/whitescreen.d.ts

@@ -1,6 +1,6 @@
-/**
- * @file 白屏监控
- * @author kaivean
- */
-import { SpyHeadConf } from '../lib/spyHeadInterface';
-export declare function init(conf: SpyHeadConf): void;
+/**
+ * @file 白屏监控
+ * @author kaivean
+ */
+import { SpyHeadConf } from '../lib/spyHeadInterface';
+export declare function init(conf: SpyHeadConf): void;

package/dist/lib/data.d.ts

@@ -1,6 +1,6 @@
-/**
- * @file 简单的公共数据模块，内部模块之间数据交换
- * @author kaivean
- */
-export declare function setData(key: string, value: any): void;
-export declare function getData(key: string): any;
+/**
+ * @file 简单的公共数据模块，内部模块之间数据交换
+ * @author kaivean
+ */
+export declare function setData(key: string, value: any): void;
+export declare function getData(key: string): any;

package/dist/lib/huffman.d.ts

@@ -1,9 +1,9 @@
-/**
- * @file Huffman
- * @author kaivean
- */
-export declare function huffmanEncode(str: string): {
-    codes: any;
-    result: string;
-};
-export declare function huffmanDecode(codes: any, str: string): string;
+/**
+ * @file Huffman
+ * @author kaivean
+ */
+export declare function huffmanEncode(str: string): {
+    codes: any;
+    result: string;
+};
+export declare function huffmanDecode(codes: any, str: string): string;