TRAE 教程

TRAE 是字节跳动推出的 AI 原生编程产品，将集成开发环境（IDE）与 AI 助手结合起来，帮助开发者理解项目、编写代码、排查问题和完成开发任务。

IDE 可以理解为程序员的工作台：编辑器用来写代码，终端用来运行命令，调试工具用来定位问题，版本控制用来管理修改。TRAE 在这些工具的基础上加入 AI，让我们可以直接用自然语言描述需求，再查看生成的代码和运行结果。

例如，我们可以输入"解释这个函数的作用"，也可以提出"为当前网页增加搜索功能"。学习代码时，可以边问边看；实现功能时，可以让智能体协助拆解任务、修改文件，再由我们检查结果。

TRAE 的主要特点

中文界面与中文交互：支持使用中文描述需求，方便初学者理解操作和阅读回复。
AI 问答与自动编程：既能解释代码、分析报错，也能结合项目文件协助实现功能。
IDE / SOLO 双模式：可以在代码编辑界面中逐步操作，也可以围绕任务让 AI 规划和执行；另有 Agent 窗口用于集中管理任务。
CUE 智能代码补全：在编写代码时提供补全与修改建议，减少重复输入。
延续熟悉的开发工具：支持 VS Code 扩展，并提供从 VS Code 或 Cursor 导入配置的入口，迁移后仍需检查所需扩展是否正常可用。
多模型选择：支持内置模型与自定义模型，可以按任务需要切换，或配置自己的 API Key。
多平台支持：桌面端提供 Windows、macOS 和 Linux 版本，按系统及芯片架构选择安装包。

TRAE 适合做什么？

使用场景	可以提出的需求
学习编程	"请解释这段 JavaScript，并给出一个简单例子。"
制作小工具	"帮我制作一个待办事项网页，支持添加、完成和删除任务。"
维护已有项目	"先阅读相关文件，再给当前列表增加关键词搜索。"
排查问题	"这是报错信息和复现步骤，请定位原因并提出修复方案。"

一、下载、安装并登录 TRAE

下载 TRAE，开始 AI 编程 前往国内官网，选择适合你电脑的版本

前往官网下载

操作系统	下载选择
Windows	选择 Windows 安装包
macOS（Intel）	选择 Intel 版本的 .dmg 安装包
macOS（Apple Silicon）	选择 Apple Silicon 版本的 .dmg 安装包
Linux	按发行版与架构选择 .deb 或 .rpm 安装包

本节以 macOS 版 TRAE CN 为例。

先访问 TRAE 官网，按操作系统与芯片类型下载安装包。

Mac 用户可在苹果菜单的关于本机中查看芯片类型：Apple 芯片选择 Apple Silicon 版本，Intel 处理器选择 Intel 版本，Windows 用户请在官网下载入口选择 Windows 安装包。

1、把 TRAE 拖入"应用程序"

下载完成后，双击打开 .dmg 安装文件。在出现的窗口中，按住左侧 TRAE CN 图标，将它拖到右侧的 Applications 文件夹。

Applications 就是 Mac 的"应用程序"目录。等待复制完成，再从"应用程序"中打开 TRAE CN。

这一步是 Mac 的安装方式。Windows 用户打开安装程序后，按安装向导操作即可。

2、点击登录，选择个人用户

启动 TRAE 后，若出现主题、语言或配置导入引导，按需要完成设置。进入主界面后，点击右侧绿色的 "登录" 按钮，也可以使用窗口右上角的登录入口。

弹出身份选择窗口后，个人学习或日常开发选择 "个人用户"。只有使用企业分配的账号时，才选择"企业用户"。

3、使用手机号完成登录

在打开的登录页面中，依次完成：

输入自己的手机号码。
点击 "获取验证码"，填写收到的短信验证码。
阅读服务条款和隐私协议，同意后勾选确认。
点击 "登录"。

也可以选择图中的抖音或苹果登录入口，按相应页面完成授权。

4、确认登录并返回客户端

出现 "登录以使用 TRAE" 页面后，点击绿色的 "登录并打开 TRAE" 按钮。

如果浏览器询问是否打开 TRAE 应用，确认打开。若需要换一个账号，点击"使用其他账号登录"，重新完成登录流程。

返回客户端后，检查右上角是否已显示账号头像。如果浏览器没有自动切回，可以手动打开 TRAE 查看登录状态。

二、发送第一条消息

5、在右侧输入框中开始对话

登录后，先不用创建复杂项目。在右侧面板底部输入一句简单的问题，点击右下角的 向上箭头按钮 发送：

你好，我是编程初学者。请介绍一下你能帮我完成哪些开发任务，并用简单的例子解释 HTML、CSS 和 JavaScript 的作用。

收到回复后，可以继续追问，例如"再举一个网页按钮的例子"。图中左侧是更新日志，不是必须填写的页面；当前操作主要在右侧对话区完成。

先问答，再操作项目：普通概念问答可以先直接体验。如果需要 AI 创建或修改本地文件，请先按后文步骤打开项目文件夹。

三、选择模型与添加自定义模型

6、从 Auto 入口选择模型

点击对话输入框右下角的 "Auto" 或当前模型名称，会展开模型列表。点击某个可用模型，即可选择它进行后续对话。

初次使用可以先保留 Auto，熟悉对话流程后再比较不同模型。截图中的模型列表和数字反映的是截图时的界面，不作为固定可用清单或价格承诺。

新手只需先分清两个概念：

类型	如何使用
内置模型	从当前账号可用的模型中选择，无须为每个模型单独填写 API Key。
自定义模型	接入自己的模型服务，按服务商要求填写 API Key 等信息。

7、按需添加自己的模型

如果已经拥有模型服务商的 API Key，可点击模型列表底部的 "添加模型"，或通过设置进入 "模型" 页面。在模型管理页点击 "＋添加模型"。

API Key 是调用模型服务的访问凭证，不是 TRAE 登录密码。没有 API Key 的用户可以跳过这一步，继续使用可用的内置模型。

添加时，根据自己使用的服务选择配置方式：

预设服务商：选择服务商、模型，并填写该服务商提供的 API 密钥。
自定义模型：按服务商文档填写 API 格式、请求地址、模型 ID 和鉴权信息。

首次配置可以保留高级参数的默认值。添加后，返回对话区选择该模型，发送一句简单问题检查连接。配置失败时，根据错误提示核对密钥、模型 ID 和请求地址。

自定义模型的用量与费用以对应服务商说明为准。API Key 只填入模型配置中，不要放进教程截图、聊天提示词或公开代码。

配置步骤参考：TRAE 内置模型与自定义模型文档。图 7 展示的是模型管理入口，后续表单以实际客户端为准。

四、打开你的第一个项目

1、新建本地练习目录

在电脑中创建一个空文件夹，命名为 trae-todo。在 TRAE 中点击"打开文件夹"，选择这个目录。

把一个项目放进独立文件夹，便于确认 AI 新建和修改了哪些文件。本教程后续操作都在该目录内进行。

2、已有仓库也可以克隆导入

如果项目已托管在 GitHub，可选择"克隆 Git 仓库"，再选择"从 GitHub 克隆"，按照提示授权并选择仓库。

图 8：从 GitHub 克隆仓库的入口（TRAE 官方文档配图，点击查看原图）

如果你已经知道仓库地址，可以直接粘贴 URL，再选择本地保存位置。

本次练习使用刚创建的空文件夹即可，无须准备 GitHub 仓库。

五、切换 IDE / SOLO 模式与使用 Agent

TRAE 中有多个工作入口，第一次使用容易混淆。先记住：左上角切换 IDE / SOLO 模式，右上角的 Agent 按钮打开 Agent 窗口。

入口	适合做什么	新手理解
IDE 模式	查看文件、手动改代码、配合 AI 完成功能	边看代码，边与 AI 讨论
SOLO 模式	围绕任务描述需求、查看 AI 执行过程和产物	把一个明确任务交给 AI 推进
Agent 窗口	集中发起和管理智能体任务	以任务为中心的独立工作区

Agent 还有另一处入口：对话框底部的 @ Agent 是选择执行任务的智能体；右上角的 Agent ↗ 是打开窗口。它们不是同一个按钮。

1、从 IDE 切换到 SOLO

在 IDE 模式中，左侧和中间主要用于查看、编辑项目文件，右侧是 AI 对话区域。想一边学习代码、一边修改网页时，可以先使用这个模式。

将鼠标移到左上角的 IDE 标识处，会出现"切换至 SOLO 模式"的提示。点击该入口，即可切换。

切换前建议先打开准备操作的项目文件夹。这样描述"修改当前项目"时，AI 才有明确的工作目录。

2、在 SOLO 模式中发起任务

进入后，左上角显示绿色的 SOLO 标识。左侧可以查看任务列表，右侧用于输入需求、阅读执行过程和查看回复。

在顶部"选择项目"处确认目标项目。
点击左侧 "新任务"，开始一个独立任务。
在底部输入具体需求，点击发送按钮。
观察执行过程；出现需要确认的操作时，阅读内容后再处理。
完成后查看文件变更，并实际运行检查结果。

例如，已有待办事项网页后，可以发送：

请为当前待办事项网页增加“全部、未完成、已完成”三个筛选按钮。
先阅读现有代码，再实现功能。
保留添加、删除和本地保存功能，兼容已有数据。
完成后列出修改的文件，并说明如何检查筛选结果。

如果想回到文件编辑界面，使用左上角的模式切换入口返回 IDE。任务列表显示"完成"后，仍需要检查实际效果是否符合要求。

3、打开 Agent 窗口

点击窗口右上角的 "Agent ↗"，即可进入 Agent 工作窗口。这个入口与左上角的 IDE / SOLO 模式切换分开。

如果当前只是修改一个函数或查看几行代码，可以继续留在 IDE 中；需要围绕任务集中查看进度时，再尝试 Agent 窗口。

4、在 Agent 窗口中创建任务

进入后，可以看到中央的大输入框，以及左侧的"新建任务"、项目和任务列表。右上角的 "IDE ↗" 用于返回 IDE 窗口。

第一次体验，建议沿用本地项目：

点击左侧 "新建任务"。
确认输入框下方的运行位置为 "本地"。
如果任务需要读写文件，点击 "选择文件夹"，选择练习项目目录。
输入需求，保留当前可用的默认模型设置，点击向上箭头发送。
在左侧任务列表中查看进度。若显示 "待确认"，打开任务查看需要确认的内容。

可以先用一个只分析、不修改文件的任务熟悉流程：

请阅读当前项目，用适合初学者的语言说明：
1. 项目是做什么的。
2. 主要文件分别负责什么。
3. 如何在本地运行。
这次只分析，不修改文件，不安装依赖。

新手建议：先完成一个任务，再尝试同时处理多个任务。截图中的"手动审批"提示你留意执行确认；看清命令或修改范围后再决定是否继续。

参考：TRAE 快速开始、SOLO 模式概览。本节配图使用 RUNOOB 提供的实际界面截图。

六、实战：用 AI 制作待办事项网页

下面是为本教程设计的练习，并非官方演示项目。我们使用最基础的 HTML、CSS 和 JavaScript，减少环境配置，把重点放在如何与 AI 协作。

1、先让 AI 说明实现思路

确认打开的是 trae-todo 文件夹，在对话区发送：

我要制作一个待办事项网页，支持添加、完成和删除任务，刷新后保留数据。
请用初学者能理解的方式解释 HTML、CSS、JavaScript 各自负责什么，以及 localStorage 如何保存数据。
这一步先说明思路，不修改文件。

先理解方案，可以帮助你判断后续生成的文件和代码是否符合预期。

2、发送完整需求，创建文件

在对话中选择可执行代码任务的内置智能体。官方文档支持通过输入 @ 或点击当前智能体名称进行选择。发送下面这段提示词：

请在当前文件夹中制作一个中文待办事项网页。

技术要求：
- 使用 HTML、CSS 和原生 JavaScript。
- 创建 index.html、style.css 和 script.js。
- 不使用框架、构建工具、外部 CDN 或后端服务。
- 允许直接用浏览器打开 index.html。

功能要求：
1. 输入内容后点击按钮或按回车添加任务。
2. 不允许添加空白任务。
3. 支持完成、取消完成和删除任务。
4. 显示未完成任务的数量。
5. 使用 localStorage 保存任务及完成状态。
6. 页面重新打开后恢复数据；存储失败时给出提示。
7. 用户输入必须作为普通文本显示。

界面要求：白色背景、绿色按钮、卡片布局，适配手机。
请直接创建文件。完成后说明文件用途、打开方式，以及哪些功能已经验证、哪些需要我手动验证。

参考：创建并管理自定义智能体：选择智能体

执行过程中留意文件变更和操作提示。完成后，应能在项目目录中找到以下文件：

文件	作用
index.html	输入框、按钮和任务列表的结构
style.css	颜色、间距和移动端布局
script.js	添加、完成、删除与本地保存逻辑

3、打开网页并验收

保存文件后，用浏览器打开 index.html。按下面的顺序检查，不要只看 AI 的完成说明。

添加"学习 TRAE"，确认列表出现任务。
只输入空格，确认没有创建空白任务。
标记任务完成，再取消完成，观察计数是否同步。
刷新页面，确认任务和完成状态保留。
删除任务后刷新，确认不会重新出现。
缩窄浏览器窗口，确认手机宽度下也能操作。

直接打开本地 HTML 时，浏览器对本地存储的处理可能有差异。若保存失败，且电脑已安装 Python 3，可在项目目录运行 python3 -m http.server 8000（Windows 可使用 py -m http.server 8000），再访问 http://localhost:8000。验证期间保持同一个访问地址。

4、用具体反馈修复问题

假设刷新后完成状态丢失，可以这样反馈：

问题：任务的完成状态没有保存。
复现步骤：添加两条任务，将第一条标记为完成，然后刷新页面。
实际结果：第一条任务恢复为未完成。
预期结果：刷新后仍保持已完成状态。
请检查保存和恢复逻辑，修复后说明原因，并列出验证步骤。

"操作步骤、实际结果、预期结果"一起给出，能减少反复猜测。一个问题确认修复后，再继续增加搜索、分类或导出等功能。

5、审查修改内容

在 SOLO 模式中，可以通过对话里的"查看变更"或"代码变更"入口检查本次改动。重点确认修改的文件是否合理、原有功能是否仍然正常。

建议每完成一个可运行阶段，就用 Git 保存一次版本。这样后续改动不符合预期时，更容易定位和回退。

七、使用 CUE 辅助编写代码

CUE 会根据代码上下文提供补全和修改建议。在设置中心找到 CUE，可以管理 Tab-Cue 等开关。

可以在 script.js 中输入一条注释，观察补全建议：

// 统计尚未完成的任务数量

操作	快捷键
接受当前建议，或按提示跳转到修改点	Tab
拒绝建议	Esc
预览采纳后的代码	macOS：Option；Windows：Alt

接受前检查变量名和条件是否符合当前项目。补全内容取决于上下文，不一定与教程中的描述完全相同。

参考：超级代码补全：CUE

八、把常用要求写成项目规则

如果每次都要重复"中文说明""不引入框架"等要求，可以把它们保存为项目规则。全局规则适用于个人的多个项目，项目规则只针对当前项目。

在 IDE 窗口进入 设置 → 规则与记忆，创建项目规则，选择合适的生效方式。官方文档使用 .trae/rules/ 保存项目规则文件。

下面是本练习可以采用的规则正文。通过界面创建规则后，保留工具生成的配置部分，再填写这些要求：

请使用中文解释修改内容。
本项目使用原生 HTML、CSS 和 JavaScript，不引入框架或外部 CDN。
修改前先阅读相关文件，沿用现有命名和结构。
用户输入按普通文本渲染，不拼接为 HTML。
新增功能需要兼容已保存的数据。
完成后说明修改了哪些文件、如何验证，以及尚未验证的部分。

参考：规则（Rule）

九、常见问题

为什么 AI 只解释，没有创建文件？

先确认已经打开项目目录，再检查是否选择了可以编辑文件的智能体。把要求写成"请在当前项目中创建文件"，并检查是否有等待处理的权限提示。

生成的网页打不开怎么办？

确认文件已经保存，文件名和 CSS、JavaScript 引用路径一致。打开浏览器开发者工具查看错误，将报错全文和复现步骤发给 AI。不要只说"不能用"。

为什么我的界面与配图不同？

版本、模式和账号可用功能可能不同。先区分当前是 IDE 窗口还是 Agent 窗口，再对照按钮文字。配图用于定位功能，实际操作以客户端为准。

是否必须开通付费套餐？

本文不假定某项功能永久免费。开始前查看当前账号的可用模型、额度与功能提示；本练习优先使用账号已有能力。

菜鸟教程