接入火熊埋点与土熊监控 ​

把「火熊（FireBear）浏览器埋点 + 土熊（NativeBear）前端监控」按已验证的模板接进任意前端项目。默认按 Vue3 + Vite 落地，同时给出非 Vue / 非 Vite 项目的替换方式。

和手写接入的区别：它不只复制三个文件，还会先探测项目现状（框架、路径别名、.env* 的 MODE、是否已有同职责文件、是否装了 vite-plugin-html），再决定模板如何落位，并在最后跑一遍完整性校验。

产物清单 ​

模板文件在 skill 的 templates/ 下，复制后按注释里的「适配点」改。纯 JS 项目把 .ts 落成 .js 即可，同时去掉类型声明。

开始之前 ​

凭证没拿到时不必编造：留空字符串交付即可，封装里的 ready 门禁为 false，SDK 不初始化、功能不受影响，后续把值补上就能生效。

工作流 ​

1. 探测目标项目 ​

先确认事实再决定落位路径，不要假设：

1. 框架与构建工具（vite / webpack / next）、是否有 vue 依赖。
2. 路径别名：vite.config.* 的 resolve.alias、tsconfig.json 的 paths（模板默认写 @/config）。
3. 已有 .env* 文件与全部 MODE 值（development / test / preview / production）。
4. 搜索 fireBear|waterbear|SZHN_NATIVE_BEAR|native-bear|fire-bear：已有同职责文件就只补差异，不要整体覆盖。
5. 是否装了 vite-plugin-html：没有就用 transformIndexHtml 注入。
6. 是否已有 analyticsEnable / monitorEnable 开关，复用优先，避免出现两套开关。

2. 收集参数 ​

一次问完，不要逐条追问：需要接入的环境列表、各环境火熊 appKey + salt、各环境土熊 appKey、两个开关的初始值、生产环境是否走公网替代域名。

域名与环境映射见 skill 的 references/reference.md 第 1 节。

3. 写入封装与统一入口 ​

按 templates/ 复制三个文件后逐项替换：

环境键必须与 import.meta.env.MODE 的实际取值完全一致，否则索引出 undefined、ready 恒为 false。非 Vite 项目把 import.meta.env.MODE 换成项目自己的环境判断。

4. 接入 CDN 脚本与开关 ​

1. .env* 每个环境追加两条变量，值为完整 <script async src="..."></script>。
2. index.html 在 </head> 前加条件注入块；<%- %> 要原样输出，不能写成 <%= %>。
3. 构建配置：有 vite-plugin-html 就在 inject.data 补两个变量，否则加 transformIndexHtml 插件。
4. config 只补 analyticsEnable、monitorEnable 两个布尔开关。不要把接口基址之类的业务配置塞进来。

5. 接入调用点并验证 ​

# 1) 应用入口里 await initSdks()，位置早于 createApp().mount()
# 2) 登录成功 / 退出登录处补两个 SDK 的 setUser(userId)
# 3) 跑完整性校验
node <本 skill 目录>/scripts/verify-integration.mjs .

校验脚本输出 PASS / FAIL 清单，FAIL 按提示修复后重跑；自定义了文件名的项目允许少量误报，人工确认即可。之后再看运行时：window.fireBear、window.SZHN_NATIVE_BEAR 是否存在，Network 里两个 CDN 脚本是否 200。

埋点数据规范（火熊） ​

trackEvent(key, segmentation) 的 segmentation 建议带齐 6 个公共字段，平台才能按页面 / 版本 / 用户维度下钻：

模板已导出 FireBearSegmentation 类型，调用方复用它即可，不要另建一份重复定义；业务自定义维度在此基础上追加。

关键约束（写错会静默失败） ​

1. 参数名不可互换：火熊 init 用 dns，土熊 init 用 dsn。写反不报错，但数据不上报。
2. 初始化顺序固定：analytics → monitor → 业务 SDK。业务 SDK 依赖 nativeBearMonitor.logger()。
3. 必须保留重试：两个 CDN 脚本都是 async，脚本未就绪时 window.* 是 undefined，靠 3 次、间隔 300ms 的 setTimeout 兜底。
4. 必须保留 ready 门禁：只有 ready === true 才 init，这是「配置缺失即自动降级」的唯一开关。
5. 每个 SDK 独立 try/catch：任一 SDK 或 CDN 失败都不能阻塞应用启动。
6. 不碰业务配置：接口基址、接口前缀、认证开关都属于业务侧。只有明确要求「后端日志关联 traceId」时，才往 URL_WHITE_LIST 填接口前缀。
7. 不要在业务代码里直接调 window.fireBear.init：绕过 ready 与重试，会出现「开关关了仍有上报」。

常见问题 ​

参考 ​

• 环境映射、CDN 地址、注入写法、排错表、setUser / trackEvent 用法：skill 的 references/reference.md
• 完整性校验脚本：scripts/verify-integration.mjs（执行，不要只读）