infometa 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 规则
- CDN 引入必须在
<head>最先 — 晚加载导致早期错误/性能数据丢失 - npm 锁定大版本
@^1— 避免 breaking change 导致线上故障 - SPA 必须
spa: true— 否则路由切换不上报 PV - Vue 必须配
errorHandler— Vue 拦截组件错误，不配则漏报 - 建议开启
reportApiSpeed+reportAssetSpeed— 核心能力 - 修改后必须提供回滚说明 — 删哪些文件、移除哪行、卸载哪个包
- 修改后必须提供验证步骤 — 接入不验证等于没接入
- 小程序必须提醒配置安全域名 — 否则正式环境上报被拦截
- 修改现有文件前展示变更摘要 — 说明将在哪个文件的哪个位置添加什么内容，让用户有预期
🟢 STYLE 规则
- 生成代码应有注释说明配置项作用
- 建议配置
env区分环境 - 建议封装为独立模块
技能资源
检测脚本
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. 检测项目环境
运行检测脚本，获取项目的技术细节：
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. 校验接入结果
- import/require 是否正确
- 初始化代码在正确入口文件中
id已替换为真实值（若步骤 0 中用户选择了占位符，此处醒目提醒）- 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
- 不在配置中硬编码敏感信息