环境安装向导

环境安装向导引导用户完成 SDK 下载或登记已有 SDK，适合首次搭建 Ameba 开发环境的用户。

触发方式： 命令面板 Advanced → Setup Wizard；SDK 环境未就绪时，也可点击面板中 SDK environment not ready. 提示旁的 Setup Wizard 按钮

向导全程在独立的 WebviewPanel 中运行，步骤如下：

步骤	名称	内容
1	环境检查	检测 git，全部通过后方可继续；Linux / macOS 还需检测 Python（≥ 3.8），Windows 无需检测
2	选择 SDK 来源	GitHub、Gitee（中国大陆用户推荐 Gitee），或 Use Existing Local SDK（使用本机已有 SDK）
3	选择 SDK 版本	从所选源动态拉取 Branches 和 Release Tags 并分组展示，默认选中第一个分支
4	选择下载类型	SDK（基础仓库，体积小）或 XDK（含音频、UI、AI 算法等子模块，体积大）
5	确认 & 安装	显示 Version / Type / Source / Destination 摘要，点击 Start Download 开始下载
6	执行下载	进度条 + 实时日志滚动显示
7	完成	显示 SDK 路径，并自动完成工程配置，见下文

使用已有本地 SDK： 在步骤 2 选择 Use Existing Local SDK 后，可从曾经使用过的 SDK 路径列表中选择，或点击 Browse… 手动指定 SDK 根目录。该路径通过校验后直接登记，跳过步骤 3、4，确认按钮变为 Use This SDK，不会下载。

下载说明：

• SDK 下载到 ~/.realtek-ameba/<版本>/ameba-rtos 目录

• 若该目录已存在完整 SDK，会弹出对话框，可选择 Use existing 直接使用，或 Reinstall (overwrite) 删除后重新下载；目录不完整（如上次下载被取消）时会自动清理后重新下载

• 下载超过约 60 秒仍未完成时，会提示可点击 Cancel & Switch Source 取消并更换下载源

完成后的自动配置：

向导完成后，SDK 路径会自动记录到 ~/.realtek-ameba/config.json，并根据当前打开的工作区自动处理：

• 外部工程：自动生成 .vscode 配置，将 ameba.rootSDKPath 指向该 SDK，优先沿用当前已选芯片，无需再次选择

• SDK Root 工程：当前工作区本身就是 SDK，插件始终继续使用该工作区的 SDK，向导的结果按所选 SDK 分三种情况处理：

  • 所选 SDK 就是当前工作区，且工作区尚无 .vscode 配置（未配置 ameba.rootSDKPath）：自动生成 .vscode 配置

  • 所选 SDK 就是当前工作区，但已有 .vscode 配置：不覆盖已有配置，仅刷新面板状态

  • 所选 SDK 是其他 SDK（如在当前 SDK 工程中新下载了另一个版本）：仅登记该 SDK 路径，不修改当前工作区的 .vscode 配置，当前工作区也不会切换到新 SDK；如需使用新 SDK，请通过 文件 → 打开文件夹 打开该 SDK 目录

• 未打开工作区：仅登记 SDK 路径，需打开工程文件夹后才会生效

备注

向导记录的 SDK 路径，会出现在后续 New External Project 和 Set Root SDK Path 的 SDK 快速选择列表中，无需重新输入。