排障

安装与启动

macOS 无法打开「已损坏」或「无法验证开发者」

1. 确认从 官方下载 获取安装包
2. 系统设置 → 隐私与安全性 → 仍要打开
3. 若仍失败，检查是否完整下载（对比文件大小）

Windows SmartScreen 拦截

见 安装 — Windows。从 GitHub Releases 重新下载后再试。

应用启动白屏或闪退

1. 完全退出后重启应用
2. 检查是否有杀毒软件拦截 Electron
3. 删除用户数据目录下的缓存后重试（先备份项目资料）
4. 到 GitHub Issues 附上系统版本与日志

AI Provider

测试连接失败

• 核对 API Key 是否过期、是否有 IP 限制
• 检查 Base URL 是否与服务商文档一致
• 公司网络是否拦截 HTTPS 出站

模型列表为空

• 确认 Provider 测试连接已成功
• 部分网关需手动填写模型 ID

移动端

设备未识别（Android）

adb devices

• 确认 USB 调试已开启
• 更换数据线或 USB 口
• 安装对应 OEM 驱动（Windows）

iOS 设备无法连接

• 需在 macOS 上运行熠测
• 安装 Xcode Command Line Tools
• 设备上信任此电脑

HarmonyOS

• 确认鸿蒙调试工具链已按官方文档配置
• 检查设备授权状态

Ember 云平台

ember-mcp doctor 失败

• 检查 EMBER_API_URL 是否可达
• 运行 ember-mcp login 刷新令牌
• 确认 EMBER_DEBUG_TEMPLATE_ID 与 lmweb 配置一致

UI-Genie 执行超时

• 设备是否被其他任务占用
• 指令是否过长，尝试拆分步骤
• 联系平台管理员查看 uiagent 服务日志

文档与网站

文档预览异常时，在本仓库执行 npm run build 查看 MDX 编译错误。

仍无法解决？桌面端问题请提交 GitHub Issue；云平台问题联系租户管理员。