AI 编程工具 《TRAE 官方手册》阅读笔记 AI 编程核心 上

AI 编程工具 《TRAE 官方手册》阅读笔记 AI 编程核心 上

一、参考资料

https://docs.trae.cn/ide_skills

二、笔记总结

1 对话

TRAE IDE 提供多种与 AI 助手对话的方式，帮助你在开发过程中完成代码问答、仓库理解、代码生成、错误修复、代码优化等任务。

侧边对话

侧边对话面板默认显示。如果面板被关闭，可通过快捷键（macOS: Command + U / Windows: Ctrl + U）重新打开。

输入问题后，可以点击模型名称右侧的 优化输入内容 图标，让 AI 帮你优化指令，使其更清晰、更易于理解。

行内对话

你可以通过以下两种方式打开行内对话框：

• 在编辑器中，将光标置于目标位置，然后使用快捷键（macOS: Command + I / Windows: Ctrl + I）。
• 在编辑器中，选中一段代码，然后使用快捷键（macOS: Command + I / Windows: Ctrl + I）或点击代码悬浮菜单中的 编辑 按钮。

图片输入

在侧边对话面板中，你可以添加图片作为上下文，例如报错截图、产品设计稿或参考样式，帮助 AI 更直观地理解你的需求。

你可以通过以下任一方式上传图片：

• 将图片从外部拖入至对话输入框。
• 将图片从当前项目文件树中拖入至对话输入框。
• 在对话输入框内粘贴剪贴板中的图片。
• 点击输入框左下角的 图片 按钮，然后从本地选择图片。

语音输入

在侧边对话输入框右下角，点击 语音输入 图标即可开始说话。系统会将你的语音输入自动转为文字并填入输入框，你可以在发送前手动编辑。

首次使用时，你需要为 TRAE 授权麦克风访问权限。

• Windows：前往 开始 > 设置 > 隐私 & 安全性， 然后在 应用权限 下查找 麦克风。

创建会话副本（Fork Chat）

在多轮对话中，你可以从任意一条 AI 回复创建新的独立对话。新对话将继承该条回复之前的全部上下文，并将自动切换进入；原对话保持不变。

如何创建会话副本：在 AI 回复的底部，点击右侧的 创建会话副本 图标。

2 模型

内置模型 & 自定义模型

TRAE 内置多款主流模型，你可以根据实际任务灵活切换使用。除内置模型外，TRAE 还支持接入自定义模型。

Auto 模式

Auto 模式下，系统会综合考虑问答速度、性能与资源占用情况，调用合适的模型，提供更流畅的 AI 问答体验。

模型调用范围

Auto 模式仅支持调用 TRAE 的内置模型，不支持调用你添加的自定义模型。

开启 Auto 模式

在 AI 对话输入框的右下角，点击模型名称以打开菜单，然后打开 Auto Mode 开关。

3 上下文

基础用法

与 AI 助手对话时，你可以指定上下文供 AI 助手阅读和理解，使 AI 助手的答复更精准。

将编辑器内的内容作为上下文

当你的编辑器中存在正在编辑的代码文件时，AI 助手默认能够看到当前文件。你可以直接向 AI 助手提问与当前文件相关的问题。若期望对文件中的某一段代码进行提问，使用以下步骤：

• 1 选中代码。
• 2 点击悬浮菜单中的 添加到对话 按钮，将选中的内容作为上下文添加至侧边对话框。

将终端中的内容作为上下文

若你希望对终端中的输出内容进行提问（如帮助你修复报错），使用以下步骤：

• 1 在终端中，点击输出内容片段。
• 2 在内容片段区域的右上角，点击 添加到对话 按钮，将选中的内容作为上下文添加至侧边对话框。

使用 # 符号添加上下文

在侧边对话的输入框中，你可以通过 # 符号添加多种类的上下文，包括代码、文件、文件夹、代码仓库、文档集和网页。

通过 # 符号引用上下文

在侧边对话的输入框中，你可以使用 # 符号添加上下文，例如代码、文件、文件夹、工作区和外部文档等，从而帮助 AI 更准确地理解你的需求。

TRAE 会优先推荐与当前打开文件相关的内容，你也可以通过搜索自行选择所需上下文。若有需要，你可以同时添加多种类型的上下文。

工作区代码索引

在 TRAE 中，你可以为项目构建索引。构建索引后，当你通过 #Workspace 或 #Folder 方式与 AI 对话时，AI 能够理解你当前打开的项目并使用整个项目作为上下文进行回答，从而提供更加精准的回答。

若未构建索引或索引构建不完全，在使用 #Workspace 或 #Folder 方式与 AI 助手对话时，可能会导致无法召回完整的上下文，进一步导致回答不完整。此时，AI回答处将出现 "索引建构中" 或 "索引暂未建构" 的提示。

重要提示

• 针对文件数量小于等于 5000 的项目，TRAE 将在打开项目时自动构建代码索引。若项目内的文件数大于 5000 且你期望项目级的回答更准确，则需要手动发起代码索引构建。
• 你可以通过配置忽略文件，来指定在构建代码索引时需剔除的文件。被忽略的文件将完全被排除在代码索引之外，从而有效保护你的敏感数据。

构建代码索引

• 1 点击界面右上角的 设置 图标，进入设置中心
• 2 在左侧导航栏中，选择 索引与文档。
• 3 在 工作区 部分，点击 代码索引管理 处右侧的 Build 按钮。

忽略文件

TRAE 默认忽略 .gitignore 文件中所罗列的文件。除此之外， 你可以自主设置 TRAE 在索引仓库时需要额外忽略的文件列表，以作为 .gitignore 文件中已定义规则的补充。

重要提示

使用 #Workspace 或 #Folder 添加上下文时，被忽略的文件或文件夹将无法被作为上下文。

操作步骤

• 1 点击界面右上角的 设置 图标，进入设置中心。
• 2 在左侧导航栏中，选择 索引与文档。
• 3 在 工作区 部分，点击 忽略文件 处右侧的 编辑 按钮。
• 4 在 .ignore 文件中，添加需要忽略的文件并保存。
• 5 在 代码索引管理 处，点击 Build 按钮以重新构建代码索引。

示例

以下为 .ignore 文件内容的示例：

**/foo:         忽略 /foo, a/foo, a/b/foo 等
*.log:          忽略所有 .log 文件
config.js:      忽略当前路径的 config.js 文件
 
/mtk/           忽略整个文件夹
*.zip           忽略所有.zip文件
/mtk/do.c       忽略某个具体的文件

上下文压缩

每个对话都拥有独立的上下文管理进程。随着问询的不断发送，对话的上下文会逐步累积，而上下文窗口则决定了单个对话可保留和记忆的上下文长度。

在 AI 处理任务的过程中，当使用的上下文超过允许的上下文窗口时，系统会自动触发一次上下文压缩。

通过压缩上下文，你可以移除冗余信息，仅保留与当前任务相关的关键内容，从而确保 AI 聚焦于核心上下文并维持输出质量。

开启新的会话后，先前的上下文将被清空。

使用限制

仅适用于 SOLO Agent。

查看上下文使用率

查看上下文使用率

在 AI 处理任务的过程中，当使用的上下文超过允许的上下文窗口时，系统会自动触发一次上下文压缩。

4 智能体（Agent）

Agent 智能体它不像普通 chat 对话式智能体那样只是回答问题，而是先结合你的目标和项目上下文给出一份可执行计划，等你确认后再按步骤推进开发。

"Agent" 支持调用自定义子智能体完成模块化任务。配置子智能体后，"Agent" 会作为主智能体，在处理上下文较长或任务较复杂的场景中，将任务拆分给更适合的子智能体执行。

不同子智能体在独立上下文中处理任务，可以减少信息混杂，提高输出稳定性。

你可以将高频、重复、边界清晰的工作流封装为可复用的 Subagent，例如：代码审查、性能分析、依赖风险检查等。

智能体概述

智能体是你面向不同开发场景的编程助手。TRAE 提供内置智能体。同时，你还可以创建自定义智能体，通过灵活配置提示词和工具集，使其更高效地帮你完成复杂任务。

智能体的能力

• 自主运行 - 独立探索你的代码库，识别相关文件并进行必要修改。
• 完整的工具访问权限 - 使用所有可用工具进行搜索、编辑、创建文件及运行终端命令。
• 上下文理解 - 建立对你项目的结构和依赖关系的全面理解。
• 多步骤规划 - 将复杂任务拆分为可执行的步骤，并按顺序逐一处理。

智能体的工作流

• 1 需求分析：深入理解任务目标及代码库上下文，明确需求要点。
• 2 代码调研：检索代码库、文档及网络资源，定位相关文件并分析现有实现逻辑。
• 3 方案设计：根据分析结果拆解任务步骤，并动态优化调整修改策略。
• 4 实施变更：照计划在整个代码库中进行必要的代码变更。
• 5 交付验收：完成验证后移交控制权，同步汇总所有修改内容。

内置智能体

TRAE IDE 提供以下内置智能体：

• Chat：Chat 能够快速响应用户的各类技术咨询和问题解答。
• Agent："Agent" 是 TRAE IDE 内置的智能体，专为自动化项目开发而设，能胜任需求拆解、方案设计、代码实现、项目重构、问题修复等多步骤工程任务。

内置智能体：Agent

"Agent" 是 TRAE IDE 内置的智能体，专为自动化项目开发而设，能胜任需求拆解、方案设计、代码实现、项目重构、问题修复等多步骤工程任务。它不像普通对话式智能体那样只是回答问题，而是先结合你的目标和项目上下文给出一份可执行计划，等你确认后再按步骤推进开发。

工作流

"Agent" 推进任务的主要路径是：分析需求 > 生成 PRD 与技术方案 > 生成代码 > 预览成果。具体执行时，它还会根据任务难易程度补上必要的环节，比如读取项目文件、确认改动范围、梳理待办事项、调用子智能体、检查运行结果，或在关键决策上请你确认。

适用场景

• 为现有项目新增功能、修复缺陷或补充测试。
• 拆分复杂代码、调整项目架构或优化性能。
• 处理需要跨文件阅读、修改和验证的工程任务。
• 推进需要多个自定义智能体协同完成的长流程任务。

启用 "Agent"

• 1 点击 AI 对话输入框左下角的 @ 符号。
• 2 在智能体菜单中选择 Agent。
• 3 输入并发送你的需求。
  建议在首次输入时说明目标、约束和验收标准。例如，你可以补充涉及的页面、接口、技术栈、禁止改动的文件、期望输出形式，以及是否需要运行检查。
• 4 查看 "Agent" 生成的 PRD 和技术方案，并在确认后让它继续执行。

编辑 "Agent"

你可以为 "Agent" 配置其可调用的子智能体、MCP Server 和内置工具。

• 1 将鼠标悬浮至 "Agent" 右侧的配置图标。点击面板上的 编辑工具 按钮，前往 "Agent" 的配置面板。
  建议仅配置当前任务确实需要的能力，避免工具过多导致执行路径不清晰。

为 "Agent" 添加子智能体

"Agent" 支持调用自定义智能体完成模块化任务。配置子智能体后，"Agent" 会作为主智能体，在处理上下文较长或任务较复杂的场景中，将任务拆分给更适合的子智能体执行。

子智能体适合承接边界清晰的专业任务，例如代码审查、安全审查、接口分析、文档优化、测试补充或特定模块开发。不同子智能体在独立上下文中处理任务，可以减少信息混杂，提高输出稳定性。

你也可以在提示词中明确指定要调用的子智能体。例如："使用安全审查智能体检查本次改动风险" 或 "使用需求分析智能体分析该需求"。"Agent" 会结合当前上下文，在合适的时机调用对应子智能体。

你可以通过以下两种方式为 "Agent" 添加子智能体：

• 创建自定义智能体：在智能体管理面板中创建自定义智能体，并为其打开 "可被其他智能体调用" 开关，使其能够作为子智能体被 "Agent" 调用。
• 配置 Subagent：通过 Markdown 文件定义 Subagent，供 "Agent" 在合适的时机自动调用。

可被一键导入的自定义智能体

针对项目开发中的不同场景，TRAE 提供了一系列可直接导入并使用的自定义智能体示例。同时，你可以将这些示例作为模板，根据实际需求调整现有配置。

创建并管理自定义智能体

你可以在 TRAE 中创建自定义智能体，并为其配置提示词、MCP Server 与内置工具，使其能够协助你完成特定任务。同时，你也可以对已创建的自定义智能体进行管理，包括修改、分享和删除。

子智能体（Subagent）

子智能体（Subagent）是一种通过 Markdown 文件定义的专用智能体。内置智能体 "Agent" 会在识别到合适任务时自动调用对应的 Subagent。

Subagent 拥有独立的上下文窗口。它的中间推理和执行过程不会污染 "Agent" 的对话历史，因此适合处理需要大量检索、分析或推理，但最终只需要返回结果的任务。

自动运行 & 安全性

安全机制与风险说明

启用 "自动运行" 功能后，智能体可能在无需你逐次确认的情况下执行外部工具或命令。请在开启前评估使用环境、MCP Server 来源、命令执行权限及数据安全风险，并仅在可信环境中使用。

5 技能（Skill）

技能封装了指令、脚本及相关资源，一个技能可以被视为提供给智能体的一套 "专业能力说明书"（类似用户手册或操作指南）。

在执行任务时，智能体可以按需加载相应的技能，从而增强其对任务的理解与执行能力。

技能可以使智能体在不同时间、不同任务中，始终按照既定标准输出结果。

技能可以使智能体自动按照定义好的流程执行，从而减少重复的指令输入，提升效率。

主要特点

• 结构化
  一个技能对应一个 SKILL.md 文件，文件中以结构化的方式描述完成某一类任务所需的信息，例如：任务目标与适用场景；关键约束与注意事项；推荐流程或操作步骤；可选的脚本、模板或示例。
• 动态按需加载
  智能体不会在任务开始时一次性读取所有技能的完整内容。在执行任务前，智能体会先扫描所有技能的简要描述，仅当判断当前任务与某个技能高度相关时，才会加载该技能的详细内容。这种按需加载机制可以有效减少上下文中的 Token 消耗、避免无关信息干扰智能体的决策。

使用场景

• 保证输出结果的一致性与规范性
  需要智能体在不同时间、不同任务中，始终按照既定标准输出结果。例如，将统一设计规范、执行团队标准、保持品牌一致性或确保代码符合项目约定等要求封装为技能，从而将隐性的个人或团队标准转化为显式、可复用的专业能力，最终使输出结果更加稳定、可控。
• 自动化重复性工作流
  需要频繁执行相同或高度相似的多步骤任务。例如，对于测试流程、代码规范检查、常规数据分析等难以避免的日常工作，可以将既有的 SOP 封装为技能。一旦相关任务被触发，智能体即可自动按照定义好的流程执行，从而减少重复的指令输入，提升效率。
• 总结与共享专业能力
  总结个人经验或团队规范，并在更大范围内复用。例如，将技能在社区、交流群等公共平台进行分享，从而在不同的智能体、项目、团队间复用相同的技能。

技能 vs 其他功能

• 技能 vs 规则
  规则采用全量加载机制，一旦开启对话，所有规则都会被注入并持续占用上下文窗口；技能则采用按需加载机制，仅在实际需要被调用时才加载到上下文中，从而显著降低 Token 消耗。
• 技能 vs MCP Server
  技能用于向 TRAE 描述如何完成任务，而 MCP Server 负责向 TRAE 提供可以调用的工具。
  技能可以引导 TRAE 在正确的上下文中高效调用 MCP Server 提供的能力。

支持的技能类型

跨项目全局生效的技能，可用于：

• 统一个人 / 团队的通用开发范式，例如统一代码风格、命名规范、注释习惯；
• 提供跨项目可复用的工程能力，例如通用工具链的使用（Git、CI/CD、Playwright 等）；
• 固化个人或组织的长期偏好，例如输出结构（是否先给结论、是否列步骤、是否给示例）。

仅在当前项目生效的技能，可用于：

• 注入项目专属的业务知识与规则，例如不可违反的业务约束与边界条件、项目内部术语、概念映射；
• 约束 AI 按项目的既定技术方案工作，例如技术栈、框架版本、架构限制等；
• 让 AI 深度参与当前项目的开发和维护，例如针对项目生成测试、Mock、脚手架代码；与项目使用的 MCP Server 或内部工具协同。

技能的结构

一个技能中必须包含一个 SKILL.md 文件，还可以根据实际需求添加其他文件，例如可执行的脚本、可参考的模板和风格指南等。例如：

skill-name/
├── SKILL.md               # （必须）智能体的核心指令
├── examples/              # （可选）输入/输出示例
    ├── input.md
    └── output.md
├── templates/             # （可选）可复用的模板
    └── component.tsx
└── resources/             # （可选）参考文件、运行脚本或素材
    └── style-guide.md

技能所在目录

技能相关文件所在目录如下：

• 项目技能：项目所在路径下的 .trae/skills/ 目录。
• 全局技能：
  macOS/Linux：本地根目录 ~/.trae-cn/skills。
  Windows：本地根目录 %userprofile%/.trae-cn/skills。

SKILL.md 文件格式

SKILL.md 文件的格式如下：

---
name: 技能名称
description: 简要描述这个技能的功能和使用场景

---

# 技能名称

## 描述
描述这个技能的作用。

## 使用场景
描述触发这个技能的条件。

## 指令
清晰的分步说明，告诉智能体具体怎么做。

## 示例 (可选)
输入/输出示例，展示预期效果。