腾讯云 RUM SDK 接入专家。帮助用户将 RUM SDK（腾讯云前端监控）接入到项目中，覆盖 Web、小程序、React Native、Node.js、Hippy、Cocos、LiteApp、QuickApp、Viola 与 Weex。当用户提到：接入 RUM、集成前端监控、安装 aegis SDK、前端埋点、上报数据、接入前端性能监控、配置错误上报、页面测速接入、白屏监控、性能监控时，应使用此技能。不处理：RUM 数据查询与分析（应使用 tencent-cloud-rum）、后端 APM 独立接入、非腾讯云监控平台（如 Sentry、Datadog）。
Scanned 9/8/2026
Install to Claude Code
Skills Directorynpx -y skills add infometa/workbuddyskills --skill rum-sdk-setup --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Rum Sdk Setup?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/infometa-rum-sdk-setup)More formats (shields.io, HTML) on the badges page.
---
name: rum-sdk-setup
description: "腾讯云 RUM SDK 接入专家。帮助用户将 RUM SDK（腾讯云前端监控）接入到项目中，覆盖 Web、小程序、React Native、Node.js、Hippy、Cocos、LiteApp、QuickApp、Viola 与 Weex。当用户提到：接入 RUM、集成前端监控、安装 aegis SDK、前端埋点、上报数据、接入前端性能监控、配置错误上报、页面测速接入、白屏监控、性能监控时，应使用此技能。不处理：RUM 数据查询与分析（应使用 tencent-cloud-rum）、后端 APM 独立接入、非腾讯云监控平台（如 Sentry、Datadog）。"
---
# 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 密钥。
```javascript
// ❌ 错误：这是云 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. 创建独立文件，最小侵入**
```javascript
// ❌ 错误：在入口文件中插入大段初始化代码
// 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 语句必须在文件最顶部**
```javascript
// ❌ 错误：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. 生成代码的语法必须匹配目标文件**
```typescript
// ❌ 错误：目标文件是 .ts，但生成了 .js 语法（无类型标注、用 require）
const Aegis = require('aegis-web-sdk');
// ✅ 正确：匹配目标文件的语言和模块系统
import Aegis from 'aegis-web-sdk';
```
## 🟡 IMPORTANT 规则
1. **CDN 引入必须在 `<head>` 最先** — 晚加载导致早期错误/性能数据丢失
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. 建议封装为独立模块
## 技能资源
### 检测脚本
```bash
python3 {SKILL_DIR}/scripts/detect_project.py <project_root>
```
使用输出字段：`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 加载）
| 项目类型 | 配置文档 |
|---|---|
| `web-*` | `{SKILL_DIR}/references/web-sdk-config.md` |
| `miniprogram-*` | `{SKILL_DIR}/references/mp-sdk-config.md` |
| `react-native` | `{SKILL_DIR}/references/rn-sdk-config.md` |
| `node` | `{SKILL_DIR}/references/node-sdk-config.md` |
| `hippy` | `{SKILL_DIR}/references/hippy-sdk-config.md` |
| `cocos` | `{SKILL_DIR}/references/cocos-sdk-config.md` |
| `liteapp` | `{SKILL_DIR}/references/liteapp-sdk-config.md` |
| `quickapp` | `{SKILL_DIR}/references/quickapp-sdk-config.md` |
| `viola` | `{SKILL_DIR}/references/viola-sdk-config.md` |
| `weex` | `{SKILL_DIR}/references/weex-sdk-config.md` |
### 通用参考
- 排障 → `{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. 检测项目环境
运行检测脚本，获取项目的技术细节：
```bash
python3 {SKILL_DIR}/scripts/detect_project.py <project_root>
```
结合步骤 0 中用户确认的接入端，对检测结果进行交叉验证：
- 用户说的端与 `projectType` 一致 → 继续
- 用户说的端与 `projectType` 不一致 → 以用户确认的为准
- `isCompositeProject = true` → 确认用户选择的端在 `detectedPlatforms` 中有对应代码
- `hasExistingAegis = true` → 查看 `installedAegisPackages` 判断已有哪些平台的 SDK。若当前要接入的 SDK 包已在列表中 → ⏸ 暂停询问是修改配置、升级还是重新接入；若是新增其他平台 → 正常继续
- 识别到入口文件 → 复用，不盲目新建
- 识别到框架和语言 → 保持输出代码一致
### 2. 选择 SDK 包
| 项目类型 | SDK 包 |
|---|---|
| `web-*` | `aegis-web-sdk` |
| `miniprogram-*` | `aegis-mp-sdk` |
| `react-native` | `aegis-rn-sdk` |
| `node` | `aegis-node-sdk` |
| `hippy` | `aegis-hippy-sdk` |
| `cocos` | `aegis-cocos-sdk` |
| `liteapp` | `aegis-liteapp-sdk` |
| `quickapp` | `aegis-quickapp-sdk` |
| `viola` | `aegis-viola-sdk` |
| `weex` | `aegis-weex-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. 删除 <aegis 初始化文件>
2. 移除入口文件中的 import 那一行
3. 卸载依赖：<包管理器> uninstall <SDK 包名>
```
## 按需下钻主题
遇到以下主题时读取对应 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
- 不在配置中硬编码敏感信息
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
