TRAE SOLO（字节跳动）

# TRAE IDE 使用指南

## 一、产品介绍

TRAE IDE 是字节跳动推出的 AI 原生集成开发环境，深度融合 AI 能力，提供代码编写、项目理解、调试运行到变更管理的完整开发体验。支持自定义模型接入，同时具备 CUE 智能编程、MCP 协议扩展、隐私模式等能力。

### IDE 模式 vs SOLO 模式

TRAE 提供两种开发模式，可在界面左上角自由切换：

![](https://static.cloudcare.cn/cloudcare-mrdoc/img/2026-07-27_134937_1415840.8672379253945586.png)

|              | **IDE 模式**                                                 | **SOLO 模式**                                                |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **主导方**   | 开发者主导，AI 辅助                                          | AI 主导，开发者验收                                          |
| **工作方式** | 保留传统 IDE 的编辑器、终端、调试、插件、Git 等工作流，AI 在侧边栏或行内提供建议 | 用自然语言描述需求后，AI 自动规划任务、生成代码、运行测试、预览结果，全流程自主推进 |
| **控制粒度** | 开发者对每一步代码改动有完全控制权                           | <u>开发者只需描述需求并验收最终结果</u>                      |
| **适用场景** | 日常编码、精细调试、代码审查、需要逐步确认改动的场景         | 快速原型开发、从 0 到 1 搭建项目、端到端任务交付             |
| **适用人群** | 习惯传统 IDE 工作流、需要对代码有完全掌控的开发者            | 希望快速验证想法、不想手动写代码的产品经理或全栈开发者       |

### 与 TRAE Work 的配置共享

TRAE IDE 的 SOLO 模式已演进为独立的 TRAE Work 产品，两者共享同一底层配置目录（`~/.trae-cn/`）。因此，自定义模型配置在两端互通，如果你在 TRAE IDE 中已配置了自定义模型，切换到 TRAE Work 后无需重新配置，可直接使用。

---

## 二、安装部署

### 2.1 系统要求

| 操作系统 | 最低版本 / 发行版                                            | 架构                         |
| -------- | ------------------------------------------------------------ | ---------------------------- |
| macOS    | 12.0 及以上                                                  | Apple Silicon、Intel         |
| Windows  | Windows 10、Windows 11                                       | 64 位（x64）                 |
| Linux    | Ubuntu 20.04、Debian 11（.deb）；Fedora 42、RHEL 9.x（.rpm） | 64 位（x64）、64 位（ARM64） |

> **硬件建议**：Intel Core i5 / Apple M1 或更高，8GB RAM 及以上，至少 2GB 可用存储空间。

### 2.2 下载安装包

前往 TRAE 官网下载对应操作系统的安装包：

| 版本               | 官网地址                                           | 说明                                                         |
| ------------------ | -------------------------------------------------- | ------------------------------------------------------------ |
| **国内版（推荐）** | [https://www.trae.com.cn](https://www.trae.com.cn) | 国内直连，内置豆包、DeepSeek 等模型，支持手机号/抖音/苹果/稀土掘金账号登录 |
| **国际版**         | [https://www.trae.ai](https://www.trae.ai)         | 需海外网络环境，内置 GPT、Claude、Gemini 等模型              |

> **注意**：国际版需要海外网络环境，国内访问可能不稳定。

### 2.3 各平台安装步骤

#### macOS

1. 下载 `.dmg` 安装包（区分 Apple Silicon 和 Intel 版本）
2. 双击打开 `.dmg` 文件
3. 将 TRAE 图标拖拽到「应用程序」文件夹
4. 从「应用程序」文件夹启动 TRAE
5. 若出现安全提示，前往 **系统偏好设置 > 安全性与隐私** 允许运行

> 若 macOS 版本低于 12.0，可下载低于 3.3.25 版本的 TRAE IDE：
>
> - [Apple Silicon 版本](https://lf-cdn.trae.com.cn/obj/trae-com-cn/pkg/app/releases/stable/2.3.4283/darwin/Trae%20CN-darwin-arm64.dmg)
> - [Intel 版本](https://lf-cdn.trae.com.cn/obj/trae-com-cn/pkg/app/releases/stable/2.3.4283/darwin/Trae%20CN-darwin-x64.dmg)

#### Windows

1. 下载 `Trae-CN-Setup-x64.exe` 安装包（约 100MB）
2. 双击运行安装程序，若弹出安全提示选择「允许」
3. 勾选「创建桌面快捷方式」和「将 TRAE 添加到系统 PATH 环境变量」
4. 等待 1-2 分钟安装完成，点击「完成」自动启动

#### Linux

1. 根据发行版选择 `.deb`（Ubuntu/Debian）或 `.rpm`（Fedora/RHEL）格式下载

2. 使用包管理器安装：

```bash
   # Debian/Ubuntu
   sudo dpkg -i trae-cn_xxx_amd64.deb
   
   # Fedora/RHEL
   sudo rpm -i trae-cn-xxx.x86_64.rpm
   ```

### 2.4 首次启动配置

1. **选择主题和语言**：推荐选择 Dark+ 深色主题，语言默认简体中文
2. **导入配置（可选）**：如之前使用 VS Code 或 Cursor，可直接导入已有配置（插件、主题、快捷键）
3. **添加命令行工具（可选）**：将 TRAE 相关命令添加到系统 PATH，方便终端调用
4. **登录账号**：点击右上角「登录」，支持手机号、抖音账号、苹果账号、稀土掘金账号登录。登录后才能激活 AI 功能

---

## 三、自定义 API 配置

TRAE 内置多款主流模型可直接使用，同时也支持通过 API Key 接入自定义模型，满足个性化需求。

### 3.1 切换模型

在 AI 对话输入框的右下角，点击当前模型名称，打开模型列表，选择想使用的模型。将鼠标悬浮至模型名称上可查看该模型支持的能力。

![](https://static.cloudcare.cn/cloudcare-mrdoc/img/image-20260723110138141_1785131425.png)

### 3.3 添加自定义模型

有两种方式添加自定义模型：**模型服务商**（预设）和**自定义配置**。

#### 方式一：通过模型服务商添加

适用于 TRAE 已预设的服务商（Anthropic、OpenAI、Gemini、xAI、DeepSeek、火山引擎、阿里云、腾讯云、硅基流动、PPIO、Novita、BytePlus 等）。

1. 点击右上角 **设置** 图标（齿轮），进入设置中心
2. 在左侧导航栏选择 **模型**，进入模型管理面板
3. 点击 **+ 添加模型** 按钮
4. 选择 **模型服务商** 选项
5. 选择服务商，然后从列表中选择预置模型，或点击「使用其他模型」填写自定义模型 ID
6. 填写 API 密钥
7. （可选）展开 **高级配置**，设置模型展示名称、上下文窗口、工具调用轮次等
8. 点击 **添加模型**，TRAE 会自动检测 API 密钥是否有效

#### 方式二：通过自定义配置添加

适用于 TRAE 未预设的模型服务商，通过配置 API 格式、请求地址、模型 ID 和鉴权信息来接入。

1. 点击右上角 **设置** 图标，进入设置中心
2. 在左侧导航栏选择 **模型**
3. 点击 **+ 添加模型** 按钮
4. 选择 **自定义配置** 选项
5. 设置 **API 格式**（如 OpenAI Chat Completions 格式）
6. 填写 **自定义请求地址**：
   - 方式一：打开「完整 URL」开关，填写完整地址
   - 方式二：关闭「完整 URL」开关，填写基础地址（`/chat/completions` 将自动补充到地址末尾）
7. 输入 **模型 ID**
8. 设置 **多模态** 开关（默认开启，关闭后无法上传图片）
9. 填写 **API 密钥**
10. （可选）展开 **高级配置**，设置模型系列、展示名称、上下文窗口、工具调用轮次
11. 点击 **添加模型**

### 3.3 自定义配置界面说明

以下为添加自定义模型的界面截图及操作说明：

![设置入口与模型管理面板](https://static.cloudcare.cn/cloudcare-mrdoc/img/image-20260723101612708_1785131461.png)

> **操作步骤**：
>
> - **Step 01**：点击右上角的 **设置** 图标（齿轮）
> - **Step 02**：在左侧导航栏选择 **模型**
> - **Step 03**：在模型管理面板中，展开「自定义」分类，点击「添加自定义模型」

![添加模型 - 自定义配置](https://static.cloudcare.cn/cloudcare-mrdoc/img/image-20260723102000808_1785131489.png)

> **自定义配置字段说明**：
>
> - **API 格式**：选择 API 协议格式，如 OpenAI Chat Completions 格式
> - **自定义请求地址**：填写兼容 OpenAI API 的服务端点地址，不要以斜杠结尾。关闭「完整 URL」开关时，`/chat/completions` 将自动补充到地址末尾。 **（使用 ee 平台配置关闭「完整 URL」开关后，粘贴 url 和 ak 即可）**
> - **模型 ID**：输入要使用的模型完整 ID（**ee 平台模型列表的名称**）
> - **API 密钥**：填写模型鉴权所需的 API Key
> - **高级配置**：包含模型系列、展示名称、上下文窗口等配置

### 3.4 管理自定义模型

| 操作          | 说明                                                     |
| ------------- | -------------------------------------------------------- |
| 编辑模型      | 点击编辑图标，修改服务商、模型名称、API 密钥等信息       |
| 删除模型      | 点击删除图标，二次确认后移除模型                         |
| 启用/禁用模型 | 禁用后模型保留在设置中，但不出现在对话框的模型选择列表里 |

---

## 四、推荐配置

### 4.1 开发环境配置建议

| 配置项   | 推荐设置                           | 说明                                   |
| -------- | ---------------------------------- | -------------------------------------- |
| 主题     | Dark+ 深色主题                     | 长时间编码保护眼睛                     |
| 语言     | 简体中文                           | 全中文界面，术语解析友好               |
| Node.js  | 使用 TRAE 内置版本或本地已安装版本 | 前往 设置 > 开发环境 配置              |
| 插件     | 按需安装 VS Code 兼容插件          | 兼容 VS Code 插件市场                  |
| 隐私模式 | 按需开启                           | 开启后对话内容不用于模型训练           |
| 沙箱运行 | 建议开启                           | 限制智能体命令执行权限，降低误操作风险 |

### 4.2 规则（Rules）配置建议

通过配置规则，可以让 AI 的输出更符合你的个人偏好和项目要求，一次配置长期生效。

#### 规则类型

| 规则类型     | 作用范围   | 适用场景                                                |
| ------------ | ---------- | ------------------------------------------------------- |
| **全局规则** | 所有项目   | 语言风格（简洁/严谨）、操作系统偏好、内容深度、交互方式 |
| **项目规则** | 仅当前项目 | 代码风格（缩进/命名规范）、语言与框架偏好、API 使用限制 |

#### 创建方式

- **全局规则**：设置 > 规则 > + 创建 > 全局，直接输入规则内容后保存
- **项目规则**：设置 > 规则 > + 创建 > 项目，系统自动在 `.trae/rules/` 目录下创建规则文件，使用 Markdown 语法编写

#### 项目规则生效方式

| 生效方式     | 说明                                                   |
| ------------ | ------------------------------------------------------ |
| 始终生效     | 在当前项目所有 AI 对话中生效                           |
| 指定文件生效 | 仅在匹配指定文件模式（如 `*.js`、`src/**/*.ts`）时生效 |
| 智能生效     | AI 根据规则描述自动判断是否适用                        |
| 手动触发     | 仅在对话中通过 `#Rule` 提及该规则时生效                |

#### 规则文件组织

- 规则存放在项目根目录的 `.trae/rules/` 文件夹下，支持最多 3 层子目录嵌套
- 也支持在子模块目录下放置 `.trae/rules/`，仅在该模块相关文件被读取时生效
- 兼容 `AGENTS.md`、`CLAUDE.md` 和 `CLAUDE.local.md` 文件（需在设置中开启对应开关）

#### Git Commit Message 规则

在规则文件中添加 `scene: git_message` 字段，即可规范 AI 生成的提交信息格式：

```markdown
---
scene: git_message
---
使用 Conventional Commits 规范，格式为 type(scope): description
```

### 4.3 智能体使用建议

- **Builder 智能体**：适合多文件修改、项目构建等复杂任务
- **Builder with MCP**：需要调用外部工具或 API 时使用
- **自定义智能体**：通过配置提示词和工具集，适配特定任务场景（如代码审查、文档生成等）
- **智能生成智能体**：在创建面板中输入功能描述，AI 自动生成智能体配置，推荐优先使用

### 4.4 CUE 智能编程配置建议

CUE 是 TRAE 内置的智能编程工具，建议按需开启以下功能：

| 功能           | 说明                                                         | 开启路径                        |
| -------------- | ------------------------------------------------------------ | ------------------------------- |
| **Tab-Cue**    | 基础代码补全，理解当前文件代码并自动续写                     | 设置 > CUE                      |
| **Cue-Pro**    | 仓库级链式补全，结合完整仓库上下文生成连续编辑建议           | 资源管理器 > Cue-Pro 视图 > ··· |
| **智能导入**   | 自动识别并导入依赖模块（Python/TypeScript/Golang）           | 设置 > CUE                      |
| **智能重命名** | 跨文件识别变量/函数引用并同步修改（Python/TypeScript/Golang） | 设置 > CUE                      |

> **提示**：Tab-Cue 为全局开关，关闭后智能导入和智能重命名同步关闭。CUE 支持休眠功能，可设置一段时间内不触发补全。

### 4.5 快捷键参考

#### 通用快捷键

| 快捷键                 | 功能                           |
| ---------------------- | ------------------------------ |
| `Ctrl + I` / `Cmd + I` | 唤出行内对话（Inline Chat）    |
| `Ctrl + L` / `Cmd + L` | 在当前行与 AI 对话             |
| `@`                    | 唤出智能体/上下文选择面板      |
| `#`                    | 在对话中引用规则、文件等上下文 |

#### CUE 快捷键

| 快捷键                                | 功能                                 |
| ------------------------------------- | ------------------------------------ |
| `Tab`                                 | 接受 CUE 代码补全建议 / 跳转至修改点 |
| `Cmd + →` / `Ctrl + →`                | 逐字接受一个建议的修改               |
| `Escape`                              | 拒绝一个建议的修改                   |
| `Option` / `Alt`                      | 预览采纳后的代码状态                 |
| `Cmd + Shift + C` / `Shift + Win + C` | 展开/关闭 Cue-Pro 视图               |
| `Cmd + ↓` / `Alt + ↓`                 | 跳转至 Cue-Pro 下一个变更            |
| `Cmd + ↑` / `Alt + ↑`                 | 跳转至 Cue-Pro 上一个变更            |

### 4.6 常见问题

| 问题                 | 解决方案                                                     |
| -------------------- | ------------------------------------------------------------ |
| AI 对话无响应        | ① 检查网络，关闭异常代理 ② 退出账号重新登录 ③ 切换其他模型避开高峰 ④ 校准系统时间（UTC+8） |
| 自定义模型连接失败   | 检查 API Key 是否有效、请求地址格式是否正确（注意是否以斜杠结尾） |
| macOS 安全提示       | 前往 系统偏好设置 > 安全性与隐私 > 通用，允许 TRAE 运行      |
| 国内访问国际版不稳定 | 切换至国内版（trae.com.cn），国内直连无需代理                |
| 规则配置后未生效     | 开启全新对话再使用，避免历史上下文与新规则冲突               |
| CUE 补全不出现       | 检查设置 > CUE 中 Tab-Cue 开关是否开启；可尝试 CUE 休眠后重新唤醒 |