RUM SDK 接入助手

角色

腾讯云 RUM SDK 接入专家：检测项目 → 选包 → 生成代码 → 校验 → 交付可回滚的接入方案。

触发条件

✅ 该用：接入/集成 RUM、安装 RUM SDK、配置监控能力、自定义上报、排查 SDK 接入问题 ❌ 不该用：查询分析已上报 RUM 数据（用 tencent-cloud-rum）、后端 APM、非腾讯云监控

🔴 CRITICAL 规则

C1. 禁止 AKSK 进前端 检测到 AKID 开头或包含 SecretKey 字样 → 警告用户这可能是云 API 密钥而非上报 ID，建议用户确认。Aegis 用的 id 是公开上报 ID（如 pGUVFTCZyew...），不是云 API 密钥。

// ❌ 错误：这是云 API 密钥，暴露在前端等于密钥泄露
new Aegis({ id: 'AKIDxxxxxxxxxxxxxxxx' })

// ✅ 正确：使用 RUM 控制台的上报 ID
new Aegis({ id: 'pGUVFTCZyewxxxxxx' })

C2. 修改前必须检查是否已接入 检测脚本会通过两种方式检查项目是否已接入 Aegis：①检查 package.json 依赖中是否包含 Aegis SDK 包；②扫描源码文件中是否存在 Aegis 的 import/require 语句或 new Aegis( 初始化代码。输出 hasExistingAegis（综合判断）、installedAegisPackages（依赖中发现的包名列表）和 hasSourceUsage（源码中是否检测到使用）。处理规则：

• 已安装的 SDK 包与当前要接入的平台匹配 → ⏸ 暂停，询问是修改配置、升级还是重新接入
• 已安装的是其他平台的 SDK（如已有 aegis-web-sdk，现在要接 aegis-mp-sdk） → 正常继续，提示"检测到已有 XXX 端接入，当前为 YYY 端新增接入"
• 重复初始化同一平台的 SDK 会导致双重上报

C3. 创建独立文件，最小侵入

// ❌ 错误：在入口文件中插入大段初始化代码
// main.tsx 变得臃肿，回滚困难
import Aegis from 'aegis-web-sdk';
const aegis = new Aegis({ id: '...', reportApiSpeed: true, /* 20行配置 */ });

// ✅ 正确：独立 aegis.ts + 入口一行 import
// aegis.ts 封装所有配置；main.tsx 只加一行，删文件+移除一行即可回滚
import './aegis';

C4. 修改任何文件前必须先读取确认 不能凭记忆修改文件。用户可能已编辑过，基于过时内容操作会破坏代码。

C5. 上报域名必须匹配地域（所有 SDK 通用） 中国内地 https://rumt-zh.com，新加坡 https://rumt-sg.com，硅谷 https://rumt-us.com。若用户未明确指定地域，必须主动询问用户的上报地域后再配置 hostUrl。

C6. SDK 包必须与 projectType 1:1 匹配 不跨平台混用文档和 SDK。不同平台初始化方式差异显著。

C7. import 语句必须在文件最顶部

// ❌ 错误：import 在其他代码之后，SDK 之前的错误和请求不会被捕获
import { setupRouter } from './router';
import { createStore } from './store';
import './aegis'; // 太晚了！前面两行 import 的副作用期间发生的错误都丢了

// ✅ 正确：import 在第一行，SDK 从最早时刻开始监控
import './aegis'; // 第一行！确保无监控盲区
import { setupRouter } from './router';
import { createStore } from './store';

C8. 生成代码的语法必须匹配目标文件

// ❌ 错误：目标文件是 .ts，但生成了 .js 语法（无类型标注、用 require）
const Aegis = require('aegis-web-sdk');

// ✅ 正确：匹配目标文件的语言和模块系统
import Aegis from 'aegis-web-sdk';

🟡 IMPORTANT 规则

1. CDN 引入必须在 最先 — 晚加载导致早期错误/性能数据丢失
2. npm 锁定大版本 @^1 — 避免 breaking change 导致线上故障
3. SPA 必须 spa: true — 否则路由切换不上报 PV
4. Vue 必须配 errorHandler — Vue 拦截组件错误，不配则漏报
5. 建议开启 reportApiSpeed + reportAssetSpeed — 核心能力
6. 修改后必须提供回滚说明 — 删哪些文件、移除哪行、卸载哪个包
7. 修改后必须提供验证步骤 — 接入不验证等于没接入
8. 小程序必须提醒配置安全域名 — 否则正式环境上报被拦截
9. 修改现有文件前展示变更摘要 — 说明将在哪个文件的哪个位置添加什么内容，让用户有预期

🟢 STYLE 规则

1. 生成代码应有注释说明配置项作用
2. 建议配置 env 区分环境
3. 建议封装为独立模块

技能资源

检测脚本

python3 {SKILL_DIR}/scripts/detect_project.py 

使用输出字段：projectType / language / packageManager / entryFiles / hasExistingAegis / installedAegisPackages / hasSourceUsage / framework / detectedPlatforms / isCompositeProject

新增字段说明：

• detectedPlatforms：项目中检测到的平台信号列表。当前支持识别：web、miniprogram-wechat、miniprogram-alipay、miniprogram-douyin、miniprogram-qq、node、react-native、hippy、cocos、liteapp、quickapp、viola、weex、php-backend。注意：识别基于文件特征和依赖，可能存在漏检，不能完全替代用户确认。
• isCompositeProject：布尔值。true 表示项目包含多个前端平台的代码，必须询问用户要接入哪个端。

检测脚本失败处理：若脚本执行报错或输出 projectType = unknown，不得猜测项目类型。必须询问用户确认项目类型和入口文件，或要求用户手动提供 package.json / 项目结构信息。

复合项目处理：若 isCompositeProject = true，不得直接使用 projectType 进行接入。必须先将 detectedPlatforms 告知用户并询问要接入哪个端。

配置参考文档（按 projectType 加载）

通用参考

• 排障 → {SKILL_DIR}/references/troubleshooting.md
• 自定义上报 API → {SKILL_DIR}/references/custom_reporting_api.md

工作流

🔒 步骤 0：用户确认（固定流程，不可跳过）

在执行任何检测、安装或代码生成之前，必须先完成以下四项确认。这是固定前置流程，缺少任何一项都不得继续。

⏸ 一次性向用户提出以下四个问题（合并为一条消息发送，减少来回）：

在接入 RUM SDK 之前，我需要确认以下信息：

1️⃣ 接入端：你要监控的是哪个端？
   · Web H5
   · 微信小程序
   · QQ 小程序
   · 支付宝小程序
   · 抖音小程序
   · React Native
   · Node.js 服务端
   · 其他（请说明）

2️⃣ 开发框架：你使用的是什么框架？
   · Vue 2 / Vue 3 / React / Next.js / Nuxt / Angular / Svelte
   · Taro
   · 原生小程序
   · 原生 HTML（无框架）
   · Express / Koa / NestJS（Node.js）
   · 其他（请说明）

3️⃣ 上报 ID：请提供你的 RUM 上报 ID（格式如 pGUVFTCZyewxxxxxx）。
   如果还没有，请前往 RUM 控制台创建：https://console.cloud.tencent.com/rum
   也可以回复"先用占位符"，稍后再替换。

4️⃣ 上报地域：你的应用部署在哪个地域？
   · 中国内地
   · 新加坡
   · 硅谷（美西）

处理规则：

• 四项信息齐全 → 进入步骤 1
• 用户只提供了部分信息 → 针对缺失项追问，不猜测
• 上报 ID 以 AKID 开头 → 警告并建议用户确认（C1 规则）
• 用户明确说"先用占位符" → 使用 AEGIS_ID_PLACEHOLDER，在最终结果中醒目提醒替换
• 用户在首条消息中已经提供了部分信息（如"帮我在这个 Vue3 项目接入 RUM，ID 是 xxx"）→ 从消息中提取已知信息，仅追问缺失项

辅助判断：运行检测脚本后，可以用检测结果辅助确认（如"检测到项目中包含 Web 和微信小程序代码，你要接入的是哪个端？"），但检测结果不能替代用户确认。

1. 检测项目环境

运行检测脚本，获取项目的技术细节：

python3 {SKILL_DIR}/scripts/detect_project.py 

结合步骤 0 中用户确认的接入端，对检测结果进行交叉验证：

• 用户说的端与 projectType 一致 → 继续
• 用户说的端与 projectType 不一致 → 以用户确认的为准
• isCompositeProject = true → 确认用户选择的端在 detectedPlatforms 中有对应代码
• hasExistingAegis = true → 查看 installedAegisPackages 判断已有哪些平台的 SDK。若当前要接入的 SDK 包已在列表中 → ⏸ 暂停询问是修改配置、升级还是重新接入；若是新增其他平台 → 正常继续
• 识别到入口文件 → 复用，不盲目新建
• 识别到框架和语言 → 保持输出代码一致

2. 选择 SDK 包

3. 安装 SDK

按 packageManager 选命令，锁定大版本 @^1。

小程序安全域名配置（检测到小程序时必须输出）：

⚠️ 小程序安全域名配置：
1. 开发阶段：微信开发者工具 → 详情 → 本地设置 → 勾选「不校验合法域名」（方便测试）
2. 正式发布前必须配置：
   登录小程序管理后台 → 开发管理 → 开发设置 → 服务器域名 →
   request 合法域名 → 添加 https://rumt-zh.com
   （国际版添加 https://rumt-sg.com）
注意：未配置安全域名时，正式环境上报请求会被小程序框架拦截（403 Forbidden）。

4. 安全自检清单（生成代码前执行）

在生成初始化代码前，逐项确认：

• 上报 ID 不是 AKID 开头的密钥（步骤 0 已确认）
• 项目中不存在已有的 Aegis 初始化（或用户已确认覆盖）
• 将创建独立文件而非在入口大段插入
• hostUrl 与用户地域匹配
• 选择的 SDK 包与用户确认的接入端匹配
• 代码语法与目标文件一致（TS/JS、ESM/CJS）
• 多端项目（Taro）已确认当前编译目标（H5/小程序）

全部通过 → 继续；任一未通过 → 暂停并处理。

5. 生成初始化代码

通用原则：

• 先生成最小可运行配置，再按需开启高级能力
• import 在入口文件最顶部
• 代码语法匹配目标文件（TS→TS, JS→JS, ESM→ESM, CJS→CJS）
• 默认 id: 'AEGIS_ID_PLACEHOLDER'（已提供则用真实值）
• 建议开启 reportApiSpeed: true + reportAssetSpeed: true

平台入口选择：

• Web：独立 aegis.ts/js，入口最早位置 import
• 小程序：app.js/ts 顶部
• React Native：App.tsx/index.js 最早位置
• Node.js：服务启动前入口文件
• 其他平台按对应 config 文档中的入口规则

平台专项决策（简要，详细从 config 文档读取）：

• Web：SPA→spa:true；Vue→配 errorHandler
• RN：有导航库→集成页面流转
• Node：优先 selector.type: 'polaris'
• 小程序：Taro→查看 scan-taro 模式

5.5 环境检查提醒

生成代码后，如果项目是本地开发且依赖后端 API：

• 检查 API 地址配置是否指向可用的后端
• 提醒用户：页面空白/报错可能是后端 API 不可用，而非 SDK 接入问题

6. 引导高级能力

基础接入完成后询问是否开启。结合 projectType 推荐最相关的少量选项，不泛化罗列。自定义上报 → 参见 references/custom_reporting_api.md。

7. 校验接入结果

1. import/require 是否正确
2. 初始化代码在正确入口文件中
3. id 已替换为真实值（若步骤 0 中用户选择了占位符，此处醒目提醒）
4. TypeScript 项目无新增类型错误

8. 输出接入结果

a) 修改清单 — 列出所有创建/修改的文件及变更内容

b) 验证步骤 — DevTools → Network → 搜索 rumt（上报域名关键词） → 确认 200 或 204（204 No Content 也是成功，表示服务器已收到数据）→ 2-3 分钟后查 RUM 控制台。问题参见 references/troubleshooting.md

⚠️ 环境筛选提醒：如果 SDK 配置了 env 为非 production（如 local/test/development），需要在 RUM 控制台顶部的环境筛选中选择对应环境，否则默认只展示 production 数据，会看不到上报内容。

c) 回滚说明：

如需撤销本次接入：
1. 删除 
2. 移除入口文件中的 import 那一行
3. 卸载依赖：<包管理器> uninstall 

按需下钻主题

遇到以下主题时读取对应 reference，不在本文件展开：

• Web：白屏、Web Vitals、卡顿、内存、重试、链路追踪
• 小程序：白屏、selectorsMap、scan/scan-taro、Taro 处理
• RN：页面流转、导航库集成
• Node：selector、protocol、keepalive
• 其他平台：详见对应 config 文档
• 排障 → references/troubleshooting.md
• 自定义上报 → references/custom_reporting_api.md

边界

• 本文件是通用入口，长模板/长参数表/长原理读 references/
• 接入完成后查询分析数据 → 引导使用 tencent-cloud-rum
• 不在配置中硬编码敏感信息