常见问题
若在 MCP、登录、依赖包或各平台环境上遇到问题，可按下表快速跳转到对应章节。
MCP 连接
MCP 服务显示离线或工具未加载
现象： 在设置中 MCP 服务显示为离线，或工具列表中看不到 tencent-rtc 相关工具。
按 1–4 顺序排查，问题解决后即可停止。
1. Node.js：在终端执行
node -v，需为 v18 及以上。若不符合，可从 nodejs.org 安装 LTS 版本。2. 手动运行一次服务：在终端（如项目根目录或任意目录）执行：
npx -y @tencent-rtc/mcp。若无报错，重启 IDE 并重新启用该 MCP 服务。3. 配置 JSON：检查是否有拼写错误、多余逗号或缺少引号。可使用 jsonlint.com 校验。
4. 重启 IDE：配置修改后通常需完整重启 IDE 才能生效。
如何手动安装 MCP 服务？
现象： IDE 自动安装失败，或需要确认服务能正常运行。在终端（如项目根目录或任意目录）执行：
npx -y @tencent-rtc/mcp
运行成功后，重启 IDE 并在设置中重新启用 MCP 服务。
AI 不会自动使用 tencent-rtc 的 MCP 工具
现象： 您已请求 Chat 集成，但 AI 没有调用 tencent-rtc 工具。部分 IDE 不会自动选择 MCP 服务，需在提示词中明确指定：
使用 tencent-rtc 的 MCP 工具为 test001 生成 userSig
UserSig 凭证
AI 把 UserSig 写入代码后登录失败
现象： 登录或初始化失败；代码中的 userSig 可能被转义或格式异常。
userSig 中的特殊字符（如 +、=、/）在 AI 自动写入文件时可能被转义。解决方法：让 AI 重新生成，然后手动复制到代码中：
用 MCP 工具重新为 test001 生成 userSig
AI 输出 JSON 后，复制其中的原始
userSig 字符串，自行粘贴到代码中。UserSig 过期
现象： 登录曾成功，几天后失败。UserSig 默认有效期为 7 天。重新生成可提示：
用 MCP 工具为 test001 和 test002 重新生成 userSig，并更新到代码里
SDK_APP_ID 与 SECRET_KEY 不匹配
现象： 鉴权或初始化失败；可能来自不同应用或填写错误。
确认两个值均来自控制台中同一应用（SDK_APP_ID 为数字；SECRET_KEY 为长字符串——若有异常可到该应用页面重新复制）。
若有多个应用，确认当前查看的是目标应用。
依赖包与框架
各框架对应的包名是什么？
现象： 需要 React 或 Vue TUIKit 的准确 npm 包名。
框架 | 包名 |
React | @tencentcloud/chat-uikit-react |
Vue 3 | @tencentcloud/chat-uikit-vue3 |
二者不可混用，装错会导致运行时报错。
AI 装错了 TUIKit 的包
现象： 安装了错误框架的包（如在 React 项目中装了 Vue 的包）。在提示词中明确写出正确包名：
卸载当前的 TUIKit 包，并安装 @tencentcloud/chat-uikit-react
Skills
已配置 Skills 但 AI 仍不识别我的 Chat 请求
现象： 用户请求了 Chat/TUIKit，但 AI 未使用 tencent-rtc 工具或 Skills。
1. 确认 CLI 已成功安装 Skill，且
tencent-rtc-skills 目录存在于 CLI 输出的路径下（如 ~/.cursor 或项目内）。2. 重启 IDE 以重新加载 Skills。
3. 若仍无效，可在提示词中加入明确关键词："TUIKit"、"Chat"、"React" 或 "Vue"。
Skills 路径应使用什么格式？
现象： Skills 路径错误或未加载。
请使用绝对路径或带
~ 的路径（如 ~/.skills/tencent-rtc-skills）。相对路径会随 IDE 工作目录变化而失效。平台相关
Android：创建文件时提示 "Permission denied"
现象： IDE 或 AI 无法在 Android 项目目录下创建文件（在开发机上）。
修复权限：执行以下命令（将
/path/to/your/project 替换为您的 Android 项目路径）：sudo chmod -R 755 /path/to/your/project
或者将项目移到当前用户有写权限的目录（如
~/Projects/）。iOS：pod install 失败
现象： 在 iOS 项目中执行
pod install 或 CocoaPods 失败。可能是 CocoaPods 源过旧或版本不兼容。可让 AI 协助：pod install 失败了，请帮我排查并修复
Flutter：flutter doctor 报错
现象： Flutter 工具链或环境异常。可提示：
运行 flutter doctor，告诉我需要修复哪些项
安全相关
把 SECRET_KEY 写在 mcp.json 里安全吗？
不确定本地 mcp.json 在开发环境是否安全。mcp.json 仅存在于本地，只要不提交到代码仓库，用于本地开发调试即不会有风险。
为避免被纳入版本控制可：
将
.cursor/mcp.json 加入 .gitignore，或将配置放在全局路径
~/.cursor/mcp.json，使其完全脱离项目目录。
