TRAE Agent 与 SOLO 实战手册

根据 TRAE 官方学习资料独立整理的任务导向手册。涵盖工作区上下文、Rules、Agent 与 SOLO 工作流、子智能体、MCP、Git、验收、安全沙箱、隐私与排错。产品名称和界面会变化，使用旧教程前应先核对更新日志。

TRAE 从上下文、规则到智能体执行和验收的工作流 — 可靠的 TRAE 任务应组合最小必要上下文、持久规则、明确计划、受控执行和人工验收。

1. 选择合适的工作界面

界面	适合任务	控制方法
编辑器 + Agent	问答、局部修改、调试、解释	附上精确上下文，检查每项差异
SOLO Agent	多步骤修改、构建、测试、Git 和端到端交付	高风险或大范围任务先开启 Plan
自定义智能体／子智能体	可复用的专业工作	限定角色，只授予必要工具
Cue	编辑器内预测修改	只接受你能理解的建议

较早的官方文章可能使用 Builder、Builder with MCP、SOLO Builder 或 SOLO Coder。当前版本已把相关体验整合为 Agent 和 SOLO Agent；请以已安装版本显示的名称为准。

2. 安装、登录与准备项目

从官网下载并安装当前版本的 TRAE。
登录后打开真实项目文件夹，要求修改前先确认 Git 状态。
等待工作区索引完成；项目级答案过期时，到设置 → 上下文 → 代码索引管理重建索引。
在设置 → 上下文 → 忽略文件中排除密钥、生成文件、依赖和无关的大目录。
先执行只读任务：让 TRAE 解释技术栈、入口、测试方法和风险，不进行修改。

请概述这个代码库，找出运行入口、测试命令、构建命令、数据存储，
以及绝不能保存密钥的文件。暂时不要修改文件或运行命令。

3. 编写可以验收的任务

写明结果、证据、范围、验收条件，以及必须先确认的动作。

目标：修复管理后台一直停留在“正在登录”的问题。
证据：使用本地测试账号在 /admin 复现。
范围：仅前端认证状态和登录 API 客户端。
验收：登录成功进入后台；错误密码显示提示；刷新后会话保留；
现有后端测试继续通过。
安全：不得重置数据库或修改生产配置。
先复现并说明根因，再提出计划。

4. 用 # 添加精确上下文

引用	用途	示例
`#Code`	当前文件内的函数或类	解释令牌刷新流程
`#File`	一个或多个指定文件	比较表单校验与 API 结构
`#Folder`	限定目录	梳理认证模块
`#Workspace`	全项目检索	找出登录接口的所有调用方
`#Doc`	已索引的本地或在线文档集	按产品规范实现超时规则
`#Web`	实时网页检索或指定网址	核对当前框架迁移指南

文档集可以从网址添加，也可上传支持的本地文本文件。官方说明会抓取同一路径下指定深度的页面。来源变化后应刷新，并等待索引完成。

#File src/auth/login.ts #File src/auth/session.ts #Doc Authentication Spec
找出加载状态无法结束的原因，引用相关函数和规范条目。
不要检查无关的客户数据目录。

5. 大范围执行前使用 Plan

迁移、跨模块功能、安全工作或陌生代码库应在 SOLO 中开启 Plan。可以像编辑文档一样修改计划，直到文件范围、测试、回滚和未决问题清楚为止。

只制定计划，内容包括：
1. 复现和根因检查；2. 要修改的文件和原因；3. 新增或更新的测试；
4. 迁移或回滚步骤；5. 阻碍安全实现的问题。
得到批准前不要修改。

6. 使用持久 Rules

项目 Rules 存放代码库约定，用户 Rules 存放稳定的个人偏好。规则要短、可检查，不要混入一次性任务内容。官方给出的优先级是：用户本次输入 → 自定义智能体提示 → user_rules.md → project_rules.md。新版还支持子仓库中的嵌套 Rules 和 AGENTS.md，实际作用范围请以当前版本为准。

# 项目工程规则
- 使用 pnpm，禁止创建 package-lock.json。
- 声称完成前运行 lint 和受影响测试。
- 不得修改 .env、凭据、generated/ 或生产数据。
- 增加依赖或修改公共 API 前先询问。
- 交付时列出新增、修改和未验证的文件。

7. 创建聚焦的智能体和子智能体

TRAE 智能体由提示和工具组成。可在 Agent → Create 使用智能生成或手动配置，定义角色、模型、上下文与工具。SOLO 会在任务匹配时调用子智能体。

名称：安全审查员
职责：审查当前差异中的认证、授权、注入、密钥泄露、不安全依赖和破坏性操作。
工具：只读代码库、差异和测试工具；不得部署或向外部写入。
输出：按严重程度列出问题、文件位置、触发条件和测试。
除非明确要求，否则不修改代码。

优先使用多个职责明确的专业智能体，不要给一个智能体开放所有工具。没有统一整合负责人时，不要让多个智能体同时修改同一文件。

8. 通过 MCP 连接工具

MCP 可向智能体提供外部数据和动作。只添加可信服务，检查启动命令、参数、环境变量和工具列表，再把必要工具分配给对应智能体。凭据应放在受支持的密钥机制中，不要写进提示或可分享配置。

MCP 安全部署清单：
1. 核对发布者和安装命令。
2. 用非敏感数据测试只读工具。
3. 审查写入、删除、发布和付款能力。
4. 限定智能体职责和工作目录。
5. 导出或分享智能体/MCP 配置前清除令牌。
6. 工作流不再需要时关闭服务。

TRAE 表示会扫描分享或导入的智能体与 MCP 配置中的凭据，但这只是额外防护，不能作为把密钥写入可导出文件的理由。

9. 让 SOLO 构建、测试和处理 Git

SOLO 可以实现功能、重构、编写测试、运行构建、审查修改、更新文档和执行 Git 任务。需要明确批准点时，把代码修改和版本控制发布分开。

按已批准计划实现。每个逻辑步骤后运行最小相关测试。
最后显示 git status、总结差异，并列出测试和精确结果。
不要提交、推送、切换分支或修改远程状态。

我批准差异后：创建 feature/session-timeout 分支，只暂存已审查文件，
用简洁信息提交，然后在推送前停止。

10. 在实际产品中验收，而不只看对话

阅读真实差异，拒绝无关修改。
运行适合项目的 lint、类型检查、针对性测试和构建。
打开受影响页面或服务，检查成功、错误、加载、空状态和刷新。
确认密钥和调试数据没有进入代码库或智能体上下文。
要求智能体明确说出没有验证的项目。

执行交付审计：打开修改后的界面，复现原问题，测试成功和错误流程，
检查控制台及网络错误，并逐项对照验收条件。
不能仅凭 HTTP 200 就报告“完成”。

11. 管理上下文和长会话

切换到无关任务时压缩或重置上下文；压缩后重新附上权威要求。文档集保存稳定资料，Rules 保存稳定行为，本次提示保存任务决定。智能体记忆只能作为便利功能，不能替代事实来源。

继续前请重新说明：当前目标、已确认决定、修改文件、测试结果、
未解决风险和下一个安全动作。凡不是从代码库或附加资料验证的内容，
都要标记为推断。

12. 沙箱、审批和隐私

官方安全指南列出三种模式：带允许名单的沙箱（默认，适合多数用户）、手动运行（每条命令都确认）和自动运行（在沙箱外执行，风险更高）。陌生项目或工具应使用手动审批；破坏性命令、外部写入、部署和读取凭据必须明确确认。

TRAE 表示代码文件保留在设备本地；为了计算代码索引，明文代码可能临时上传，随后删除，但会保留嵌入和相关元数据。聊天数据是否保存或使用取决于设置。需要时使用忽略文件和 Privacy Mode；受监管工作必须核对最新隐私政策。

13. 常见问题排查

现象	检查内容
代码答案错误或过期	重建索引、附上指定文件、移除冲突的旧上下文
智能体忽略规范	规则作用范围和优先级；缩短互相矛盾的规则
命令被阻止	阅读沙箱原因；只批准准确且安全的命令或缩小范围
MCP 工具缺失	服务进程、配置、凭据、工具分配、日志和超时
SOLO 循环或卡住	停止任务、要求状态摘要、缩小范围、补充缺失证据
上下文索引失败	格式、大小、忽略规则、路径、网络和索引状态
用量或限制异常	当前套餐、模型/模式、Max Mode 和官方计费页

14. 官方学习路线

建议依次阅读官方 SOLO 快速入门、上下文指南、Rules 最佳实践、自定义 Agent 与 MCP 说明、沙箱指南、数据实践说明和更新日志。

编辑复核日期：2026 年 8 月 11 日。本页是独立编写的使用手册，并非 TRAE 官方文档的复制。使用前请重新核对当前界面、套餐、模型、限制、数据政策和安全行为。