Trae Agent：打造高效的软件工程自动化助手
“
前言：
随着软件交付节奏加快，工程师常常需要在 CLI、脚本、测试、文档之间反复切换。Trae Agent 致力于让你通过自然语言指令，就能在代码编辑、测试、部署等环节执行复杂工作流，解放双手与思维焦点。
一、Trae Agent 简介
Trae Agent 是一个面向通用软件工程任务的 LLM 驱动代理（agent）工具，提供了：
-
自然语言任务执行：通过 trae-cli run "任务描述"，即可完成从生成脚本到修复 Bug、编写测试的全流程。 -
多模支持：兼容 OpenAI 和 Anthropic 官方 API，灵活切换模型和参数。 -
丰富工具箱：集成文件编辑、Bash 执行、顺序思考（sequential thinking）等多种工具，覆盖绝大多数开发场景。 -
交互式模式： trae-cli interactive打开对话式界面，实时查看状态、调用帮助、清理环境。 -
灵活配置：支持 JSON 配置文件与环境变量，优先级清晰。 -
轨迹记录：自动或自定义保存详细的执行日志（trajectory），助力调试、审核与分析。
二、核心功能一览
| 功能模块 | 作用 | 适用场景 |
|---|---|---|
| 🌊 Lakeview | 为每一步代理执行提供简洁摘要 | 快速理解多步任务脉络 |
| 🤖 Multi-LLM Support | 支持 OpenAI、Anthropic 多家模型 | 按需求选择高精度或低成本模型 |
| 🛠️ Rich Tool Ecosystem | 文件编辑、Bash、顺序思考、标记任务完成等工具一应俱全 | 代码生成、脚本调试、文档修改 |
| 🎯 Interactive Mode | 对话式界面，实时发命令、查看状态、帮助、清屏、退出 | 灵活实验、快速验证 |
| 📊 Trajectory Recording | 记录所有 LLM 交互、代理步骤、工具调用、执行元数据 | 调试故障、审计合规、性能分析 |
| ⚙️ Flexible Configuration | JSON 配置 + 环境变量，命令行参数优先 | 在 CI/CD 与本地开发环境间轻松切换 |
三、安装与快速上手
“
步骤概览（HowTo）
克隆项目 同步依赖 配置 API Key 执行任务
git clone <repository-url> # 克隆仓库到本地
cd trae-agent # 进入项目目录
uv sync # 使用 UV 同步依赖（推荐）
export OPENAI_API_KEY="xxx" # 配置 OpenAI API Key
export ANTHROPIC_API_KEY="yyy" # 配置 Anthropic API Key
trae-cli run "创建一个 Hello World 脚本"
-
命令行参数优先，可通过 --model、--provider、--max-steps动态覆盖配置文件。 -
交互模式： trae-cli interactive --provider openai --model gpt-4o，进入对话式环境。
四、配置详解
配置项支持四种优先级（由高到低）：
-
命令行参数 -
配置文件（ trae_config.json） -
环境变量 -
默认值
{
"default_provider": "anthropic",
"max_steps": 20,
"model_providers": {
"openai": {
"api_key": "your_openai_api_key",
"model": "gpt-4o",
"max_tokens": 128000,
"temperature": 0.5,
"top_p": 1
},
"anthropic": {
"api_key": "your_anthropic_api_key",
"model": "claude-sonnet-4-20250514",
"max_tokens": 4096,
"temperature": 0.5,
"top_p": 1,
"top_k": 0
}
}
}
-
default_provider：默认 LLM 提供方 -
max_steps：最大思考与执行步数，防止死循环 -
model_providers：多模型参数，支持并行测试与对比
五、轨迹记录功能深度解析
5.1 为什么要记录轨迹？
-
调试：精确回溯 Agent 在每一步的决策、工具调用与 LLM 响应。 -
审计：在合规场景下，完整保留执行记录与版本信息。 -
优化：通过元数据分析模型使用效率、Token 消耗与工具调用频率。
5.2 轨迹文件结构
轨迹文件为 JSON 格式，主要字段：
| 字段 | 含义 |
|---|---|
task |
原始任务描述 |
start_time / end_time |
ISO 时间戳 |
provider / model |
使用的 LLM 提供方及模型 |
max_steps |
允许最大步数 |
llm_interactions |
包含每次请求的消息、响应、Token 用量和工具调用 |
agent_steps |
逐步记录 Agent 状态（thinking、calling_tool、reflecting、completed、error） |
success |
任务是否成功 |
final_result |
最终输出 |
execution_time |
执行总时长（秒） |
“
示例片段：
{ "timestamp": "2025-06-12T22:05:47.000000", "provider": "anthropic", "input_messages": [...], "response": { "content": "I'll help you create a hello world script...", "tool_calls": [...] } } ``` :contentReference[oaicite:1]{index=1}
5.3 启用与自定义轨迹文件名
-
自动文件名（默认当前目录）：
trae-cli run "任务描述" # 会生成：trajectory_YYYYMMDD_HHMMSS.json -
指定文件名：
trae-cli run "修复 main.py 错误" --trajectory-file my_debug.json
六、工具生态与拓展
-
str_replace_based_edit_tool
-
…查看、创建、编辑文件
-
-
bash
-
执行脚本与命令，持久化工作目录
-
-
sequential_thinking
-
分块思考、多次反馈、灵活回退
-
-
task_done
-
标记任务结束，并输出总结
-
“
示例：
trae-cli run "为 utils 模块添加单元测试" --working-dir ./project执行过程中，Agent 会依次思考、写测试、运行、报告结果。
七、常见问题（FAQ）
1. Trae Agent 支持哪些平台？
支持所有能运行 Python 3.12+ 的操作系统，包括 macOS、Linux 和 Windows（通过 WSL）。
2. 如何切换 LLM 提供方？
通过 `–provider openai` 或 `–provider anthropic`，也可在配置文件中修改 `default_provider`。
3. 轨迹文件是否会覆盖已有文件？
若指定文件名已存在，则会覆盖；默认生成的时间戳文件不会重复。
4. 怎样查看可用命令？
“`bash
trae-cli –help
trae-cli run –help
“`
5. 如何调优模型参数？
在配置文件或命令行添加 `–temperature`、`–top_p` 等参数即可。
八、HowTo：快速开启轨迹记录
# 1. 安装并同步
git clone <repo>
cd trae-agent
uv sync
# 2. 配置环境变量
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
# 3. 执行并记录
trae-cli run "重构数据库模块" --trajectory-file db_refactor.json
九、结语
通过 Trae Agent，你可以将常见的软件工程任务抽象为自然语言指令，借助 LLM 和插件工具，快速完成脚本编写、Bug 修复、测试生成与部署准备。其灵活的配置与详尽的轨迹记录，为团队协作、调试与审计提供有力支持。立即动手试用，让 AI 助手替你分担重复枯燥的开发工作，聚焦更重要的核心逻辑与创意实现。
