wehub-resource-sync
293 lines
10 KiB
Markdown
293 lines
10 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/bytedance/trae-agent) · [上游 README](https://github.com/bytedance/trae-agent/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# Trae Agent
|
||
|
||
[](https://arxiv.org/abs/2507.23370)
|
||
[](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)
|
||
[](https://github.com/bytedance/trae-agent/actions/workflows/pre-commit.yml)
|
||
[](https://github.com/bytedance/trae-agent/actions/workflows/unit-test.yml)
|
||
[](https://discord.gg/VwaQ4ZBHvC)
|
||
|
||
**Trae Agent** 是一款基于 LLM 的通用软件工程任务智能体（agent）。它提供强大的 CLI 界面，能够理解自然语言指令，并利用多种工具和 LLM 提供商执行复杂的软件工程工作流。
|
||
|
||
技术细节请参阅[我们的技术报告](https://arxiv.org/abs/2507.23370).
|
||
|
||
**项目状态：** 项目仍在积极开发中。若你愿意帮助我们改进 Trae Agent，请参阅 [docs/roadmap.md](docs/roadmap.md) 和 [CONTRIBUTING](CONTRIBUTING.md)。
|
||
|
||
**与其他 CLI 智能体的区别：** Trae Agent 提供透明、模块化的架构，研究人员和开发者可以轻松修改、扩展和分析，使其成为**研究 AI 智能体架构、开展消融实验（ablation studies）以及开发新型智能体能力**的理想平台。这种**_面向研究的设计_** 使学术界和开源社区能够贡献并在此基础上构建基础智能体框架，推动快速发展的 AI 智能体领域创新。
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 🌊 **Lakeview**：为智能体步骤提供简短精炼的摘要
|
||
- 🤖 **多 LLM 支持**：兼容 OpenAI、Anthropic、Doubao、Azure、OpenRouter、Ollama 和 Google Gemini API
|
||
- 🛠️ **丰富的工具生态**：文件编辑、bash 执行、顺序思考（sequential thinking）等
|
||
- 🎯 **交互模式**：面向迭代开发的对话式界面
|
||
- 📊 **轨迹记录**：详细记录所有智能体操作，便于调试与分析
|
||
- ⚙️ **灵活配置**：基于 YAML 的配置，支持环境变量
|
||
- 🚀 **安装简便**：基于 pip 的简单安装
|
||
|
||
## 🚀 安装
|
||
|
||
### 环境要求
|
||
- UV (https://docs.astral.sh/uv/)
|
||
- 所选提供商的 API 密钥（OpenAI、Anthropic、Google Gemini、OpenRouter 等）
|
||
|
||
### 设置
|
||
|
||
```bash
|
||
git clone https://github.com/bytedance/trae-agent.git
|
||
cd trae-agent
|
||
uv sync --all-extras
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
## ⚙️ 配置
|
||
|
||
### YAML 配置（推荐）
|
||
|
||
1. 复制示例配置文件：
|
||
```bash
|
||
cp trae_config.yaml.example trae_config.yaml
|
||
```
|
||
|
||
2. 编辑 `trae_config.yaml`，填入你的 API 凭据和偏好设置：
|
||
|
||
```yaml
|
||
agents:
|
||
trae_agent:
|
||
enable_lakeview: true
|
||
model: trae_agent_model # the model configuration name for Trae Agent
|
||
max_steps: 200 # max number of agent steps
|
||
tools: # tools used with Trae Agent
|
||
- bash
|
||
- str_replace_based_edit_tool
|
||
- sequentialthinking
|
||
- task_done
|
||
|
||
model_providers: # model providers configuration
|
||
anthropic:
|
||
api_key: your_anthropic_api_key
|
||
provider: anthropic
|
||
openai:
|
||
api_key: your_openai_api_key
|
||
provider: openai
|
||
|
||
models:
|
||
trae_agent_model:
|
||
model_provider: anthropic
|
||
model: claude-sonnet-4-20250514
|
||
max_tokens: 4096
|
||
temperature: 0.5
|
||
```
|
||
|
||
**注意：** `trae_config.yaml` 文件已被 git 忽略，以保护你的 API 密钥。
|
||
|
||
### 使用 Base URL
|
||
在某些情况下，我们需要为 API 使用自定义 URL。只需在 `provider` 之后添加 `base_url` 字段，以下配置为例：
|
||
|
||
```
|
||
openai:
|
||
api_key: your_openrouter_api_key
|
||
provider: openai
|
||
base_url: https://openrouter.ai/api/v1
|
||
```
|
||
**注意：** 字段格式请仅使用空格，不允许使用制表符（\t）。
|
||
|
||
### 环境变量（备选方案）
|
||
|
||
你也可以使用环境变量配置 API 密钥，并将其保存在 .env 文件中：
|
||
|
||
```bash
|
||
export OPENAI_API_KEY="your-openai-api-key"
|
||
export OPENAI_BASE_URL="your-openai-base-url"
|
||
export ANTHROPIC_API_KEY="your-anthropic-api-key"
|
||
export ANTHROPIC_BASE_URL="your-anthropic-base-url"
|
||
export GOOGLE_API_KEY="your-google-api-key"
|
||
export GOOGLE_BASE_URL="your-google-base-url"
|
||
export OPENROUTER_API_KEY="your-openrouter-api-key"
|
||
export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
|
||
export DOUBAO_API_KEY="your-doubao-api-key"
|
||
export DOUBAO_BASE_URL="https://ark.cn-beijing.volces.com/api/v3/"
|
||
```
|
||
|
||
### MCP 服务（可选）
|
||
|
||
要启用模型上下文协议（Model Context Protocol，MCP）服务，请在配置中添加 `mcp_servers` 部分：
|
||
|
||
```yaml
|
||
mcp_servers:
|
||
playwright:
|
||
command: npx
|
||
args:
|
||
- "@playwright/mcp@0.0.27"
|
||
```
|
||
|
||
**配置优先级：** 命令行参数 > 配置文件 > 环境变量 > 默认值
|
||
|
||
**旧版 JSON 配置：** 若使用较旧的 JSON 格式，请参阅 [docs/legacy_config.md](docs/legacy_config.md)。我们建议迁移到 YAML。
|
||
|
||
## 📖 用法
|
||
|
||
### 基本命令
|
||
|
||
```bash
|
||
# Simple task execution
|
||
trae-cli run "Create a hello world Python script"
|
||
|
||
# Check configuration
|
||
trae-cli show-config
|
||
|
||
# Interactive mode
|
||
trae-cli interactive
|
||
```
|
||
|
||
### 按提供商的示例
|
||
|
||
```bash
|
||
# OpenAI
|
||
trae-cli run "Fix the bug in main.py" --provider openai --model gpt-4o
|
||
|
||
# Anthropic
|
||
trae-cli run "Add unit tests" --provider anthropic --model claude-sonnet-4-20250514
|
||
|
||
# Google Gemini
|
||
trae-cli run "Optimize this algorithm" --provider google --model gemini-2.5-flash
|
||
|
||
# OpenRouter (access to multiple providers)
|
||
trae-cli run "Review this code" --provider openrouter --model "anthropic/claude-3-5-sonnet"
|
||
trae-cli run "Generate documentation" --provider openrouter --model "openai/gpt-4o"
|
||
|
||
# Doubao
|
||
trae-cli run "Refactor the database module" --provider doubao --model doubao-seed-1.6
|
||
|
||
# Ollama (local models)
|
||
trae-cli run "Comment this code" --provider ollama --model qwen3
|
||
```
|
||
|
||
### 高级选项
|
||
|
||
```bash
|
||
# Custom working directory
|
||
trae-cli run "Add tests for utils module" --working-dir /path/to/project
|
||
|
||
# Save execution trajectory
|
||
trae-cli run "Debug authentication" --trajectory-file debug_session.json
|
||
|
||
# Force patch generation
|
||
trae-cli run "Update API endpoints" --must-patch
|
||
|
||
# Interactive mode with custom settings
|
||
trae-cli interactive --provider openai --model gpt-4o --max-steps 30
|
||
```
|
||
|
||
## Docker 模式命令
|
||
### 准备工作
|
||
**重要**：请确保你的环境中已配置 Docker。
|
||
|
||
### 用法
|
||
```bash
|
||
# Specify a Docker image to run the task in a new container
|
||
trae-cli run "Add tests for utils module" --docker-image python:3.11
|
||
|
||
# Specify a Docker image to run the task in a new container and mount the directory
|
||
trae-cli run "write a script to print helloworld" --docker-image python:3.12 --working-dir test_workdir/
|
||
|
||
# Attach to an existing Docker container by ID (`--working-dir` is invalid with `--docker-container-id`)
|
||
trae-cli run "Update API endpoints" --docker-container-id 91998a56056c
|
||
|
||
# Specify an absolute path to a Dockerfile to build an environment
|
||
trae-cli run "Debug authentication" --dockerfile-path test_workspace/Dockerfile
|
||
|
||
# Specify a path to a local Docker image file (tar archive) to load
|
||
trae-cli run "Fix the bug in main.py" --docker-image-file test_workspace/trae_agent_custom.tar
|
||
|
||
# Remove the Docker container after finishing the task (keep default)
|
||
trae-cli run "Add tests for utils module" --docker-image python:3.11 --docker-keep false
|
||
```
|
||
|
||
### 交互模式命令
|
||
|
||
在交互模式下，你可以：
|
||
- 输入任意任务描述以执行
|
||
- `status` - 显示智能体信息
|
||
- `help` - 显示可用命令
|
||
- `clear` - 清空屏幕
|
||
- `exit` 或 `quit` - 结束会话
|
||
|
||
## 🛠️ 高级功能
|
||
|
||
### 可用工具
|
||
|
||
Trae Agent 为软件工程任务提供全面的工具集，包括文件 editing、Bash 执行、structured thinking（结构化思考）和 task completion（任务完成）。有关所有可用工具及其功能的详细信息，请参阅 [docs/tools.md](docs/tools.md)。
|
||
|
||
### 轨迹记录（Trajectory Recording）
|
||
|
||
Trae Agent 会自动记录详细的执行轨迹，用于调试与分析：
|
||
|
||
```bash
|
||
# Auto-generated trajectory file
|
||
trae-cli run "Debug the authentication module"
|
||
# Saves to: trajectories/trajectory_YYYYMMDD_HHMMSS.json
|
||
|
||
# Custom trajectory file
|
||
trae-cli run "Optimize database queries" --trajectory-file optimization_debug.json
|
||
```
|
||
|
||
轨迹文件包含 LLM 交互、agent 步骤、工具使用情况和执行元数据。更多详情请参阅 [docs/TRAJECTORY_RECORDING.md](docs/TRAJECTORY_RECORDING.md)。
|
||
|
||
## 🔧 开发
|
||
|
||
### 贡献
|
||
|
||
贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||
|
||
### 故障排查
|
||
|
||
**Import Errors:**
|
||
```bash
|
||
PYTHONPATH=. trae-cli run "your task"
|
||
```
|
||
|
||
**API Key Issues:**
|
||
```bash
|
||
# Verify API keys
|
||
echo $OPENAI_API_KEY
|
||
trae-cli show-config
|
||
```
|
||
|
||
**Command Not Found:**
|
||
```bash
|
||
uv run trae-cli run "your task"
|
||
```
|
||
|
||
**Permission Errors:**
|
||
```bash
|
||
chmod +x /path/to/your/project
|
||
```
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT License — 详情请参阅 [LICENSE](LICENSE) 文件。
|
||
|
||
## ✍️ 引用
|
||
|
||
```bibtex
|
||
@article{traeresearchteam2025traeagent,
|
||
title={Trae Agent: An LLM-based Agent for Software Engineering with Test-time Scaling},
|
||
author={Trae Research Team and Pengfei Gao and Zhao Tian and Xiangxin Meng and Xinchen Wang and Ruida Hu and Yuanan Xiao and Yizhou Liu and Zhao Zhang and Junjie Chen and Cuiyun Gao and Yun Lin and Yingfei Xiong and Chao Peng and Xia Liu},
|
||
year={2025},
|
||
eprint={2507.23370},
|
||
archivePrefix={arXiv},
|
||
primaryClass={cs.SE},
|
||
url={https://arxiv.org/abs/2507.23370},
|
||
}
|
||
```
|
||
|
||
## 🙏 致谢
|
||
|
||
我们感谢 Anthropic 构建了 [anthropic-quickstart](https://github.com/anthropics/anthropic-quickstarts) project that served as a valuable reference for the tool ecosystem.
|