TRTC 配置检查器（TRTC Config Inspector）

将 TRTC 场景配置模板与检查结果进行比对，生成结构化差异报告，并指导 AI Agent 或用户相应调整源代码。

功能说明

本技能实现 TRTC SDK 配置的检查分析与修改建议生成：

1. 资源下载：根据用户提供的 URL，下载场景配置模板 Excel 文件、检查结果 Excel 文件以及项目代码压缩包
2. 解析与比对：解析两个 Excel 文件，逐项比对当前配置与目标配置的差异
3. 定位代码：在项目源码中查找对应的 TRTC API 调用位置
4. 生成修改方案：输出结构化的修改建议（JSON 格式），包含每个差异项的目标值、代码位置及具体修改建议
5. 输出报告：生成差异汇总表格；AI Agent 随后调用代码编辑工具执行实际修改

注意：脚本本身不会修改任何用户代码，仅生成分析报告和修改建议。实际的代码变更由 AI Agent 使用标准代码编辑工具（例如 replace_in_file）完成，且用户可逐条审核每一步修改。

适用场景

当用户提出以下请求时，应触发本技能：

• “请根据这份检查结果和直播配置帮我修改代码”
• “下载这些文件，并依据 TRTC 配置模板优化代码”
• “比对 TRTC 检查配置并按模板修改代码”
• “检查 TRTC SDK 配置是否满足场景需求”
• 用户提供场景配置 Excel 文件（scene_config_*.xlsx）和/或检查结果 Excel 文件（inspection_result_*.xlsx）

使用方法

步骤 1：收集用户输入

确认以下信息（若未完整提供，需向用户确认）：

用户可能以如下方式提供输入：

• 直接提供 URL 链接
• 提供本地文件或目录路径
• 提供 workspace 中已存在的文件

步骤 2：下载资源文件

使用下载脚本获取远程文件：

python3 SKILL_BASE_DIR/scripts/download_files.py 
  --config-url "场景配置 Excel URL" 
  --inspect-url "检查结果 Excel URL" 
  --code-url "代码归档 URL" 
  --output-dir "SKILL_BASE_DIR/workspace"

该脚本将执行以下操作：

• 将场景配置 Excel 下载至 workspace/config.xlsx
• 将检查结果 Excel 下载至 workspace/inspect.xlsx
• 下载并解压代码至 workspace/code/
• 输出 JSON 格式的下载结果，其中包含各文件的本地路径

若用户提供了本地文件路径，则跳过对应文件的下载，直接使用该本地路径。

步骤 3：解析并比对配置

运行差异比对脚本生成差异报告：

python3 SKILL_BASE_DIR/scripts/diff_config.py "inspection_result_excel_path" "scene_config_excel_path"

输出的 JSON 报告包含以下字段：

• diffs — 当前值与目标值不一致的配置项（需修改代码）
• matches — 已匹配的配置项（无需修改）
• unable_to_compare — 无法自动比对的配置项（需人工复核）

若仅有场景配置模板（无检查结果），则直接解析模板：

python3 SKILL_BASE_DIR/scripts/parse_excel.py "scene_config_excel_path" --type config

步骤 4：基于报告定位并修改代码

根据差异报告中的 diffs 数组，AI Agent 使用代码编辑工具在源码中查找对应 API 调用并修改参数值。以下是配置项与代码 API 的映射关系：

4.1 房间进入模式（Scene / AppScene）

查找 enterRoom 调用，修改第二个参数。

4.2 音频质量

查找 startLocalAudio 调用。

4.3 系统音量类型

查找 setSystemVolumeType 调用。

4.4 视频编码器参数

查找 setVideoEncoderParam 调用及 TRTCVideoEncParam 对象。

关键提示 — 视频编码器参数必须逐项比对，不可遗漏任一子参数：

在场景配置 Excel 中，视频编码器参数（分辨率、帧率、码率）被拆分为多行。差异脚本将输出独立的子参数比对结果。所有视频编码器子参数差异均须检查并应用，包括：

• 分辨率：例如 “推荐 720p” → 更新 videoResolution
• 帧率（FPS）：例如 “25fps” → 更新 videoFps（最常被遗漏！）
• 码率：例如 “720p-1800kbps” → 更新 videoBitrate

分辨率常量映射：

• 540p → TRTC_VIDEO_RESOLUTION_960_540
• 720p → TRTC_VIDEO_RESOLUTION_1280_720
• 1080p → TRTC_VIDEO_RESOLUTION_1920_1080

推荐码率：

• 540p → 1300 kbps
• 720p → 1800 kbps
• 1080p → 3000 kbps

4.5 采集音量 / 远端播放音量

查找 setAudioCaptureVolume 和 setAudioPlayoutVolume 调用。

4.6 实验性 API

查找带 JSON 字符串参数的 callExperimentalAPI 调用。Excel 中的 code_example 列提供了具体的 JSON 结构示例。

步骤 5：确保 API 调用顺序正确

AI Agent 修改代码时，TRTC API 调用必须遵循以下顺序：

1. TRTCCloud.sharedInstance() — 创建实例
2. setListener() — 设置回调监听器
3. setSystemVolumeType() — 设置音量类型（需在 enterRoom 之前）
4. callExperimentalAPI() — 实验性设置（需在 enterRoom 之前）
5. setVideoEncoderParam() — 设置视频编码器参数
6. startLocalPreview() — 启动本地摄像头预览
7. startLocalAudio() — 启动本地音频采集
8. enterRoom() — 进入房间

步骤 6：输出修改报告

完成全部修改后，输出汇总表格：

对于标记为“可选”的配置项，需主动告知用户，并由其决定是否应用。

实现细节

依赖项

• Python 3.8+
• openpyxl（缺失时自动安装）
• requests（缺失时自动安装）

脚本清单

核心函数

• download_files.py::download_and_extract(config_url, inspect_url, code_url, output_dir) — 下载并解压全部资源文件
• parse_excel.py::parse_config_excel(filepath) — 解析场景配置 Excel
• parse_excel.py::parse_inspect_excel(filepath) — 解析检查结果 Excel
• diff_config.py::diff_configs(inspect_data, config_data) — 执行比对并输出差异结果

边界情况处理

• URL 不可达：提示用户验证链接有效性，或确认是否需要登录授权
• Excel 格式异常：捕获解析异常，提示用户确认文件格式是否符合 TRTC 平台导出规范
• 代码中未找到对应 API 调用：在报告中标记为“新增”，AI Agent 将按 API 调用顺序在合适位置插入
• 可选配置项：标记为“可选”的配置项不会自动修改，需提示用户决策
• 多平台代码：自动识别代码语言（Kotlin/Java/Swift/ObjC），并适配相应语法
• 代码归档格式：支持 .zip 和 .tar.gz 格式

重要注意事项

• Excel 文件由 TRTC 平台的检查工具与场景配置工具导出
• 修改代码时，须保持原有代码结构，仅更改特定参数值
• 针对 Kotlin 项目，需将 Excel 中的 Java 示例代码转换为 Kotlin 语法
• code_example 列提供参考实现，请结合项目实际代码风格进行适配
• 视频编码器参数必须逐项核查：差异脚本为每个子参数（分辨率、帧率、码率）分别输出独立差异项，所有项均须应用。其中帧率（FPS）是最常被遗漏的项

安全性说明

• 脚本不修改代码：所有 Python 脚本（download_files.py、parse_excel.py、diff_config.py、run_inspector.py）仅执行下载、解析、比对与分析操作。不直接修改任何用户源代码文件。代码修改由 AI Agent 使用标准编辑工具完成，用户可逐条审核每一步操作
• URL 由用户控制：脚本仅从用户显式提供的 URL 下载文件，不访问任何硬编码的外部地址
• 解压范围限定于 workspace：代码归档仅解压至指定的 workspace 输出目录
• 不存储凭证信息：脚本不读取、不存储、不传输任何密钥、Token 或用户凭证
• 运行时依赖：仅自动安装 openpyxl（Excel 解析）和 requests（HTTP 下载）两个标准 PyPI 包