Trae Agent 專案詳細介紹

專案概述

Trae Agent 是字節跳動開源的基於大語言模型（LLM）的智能代理，專為通用軟體工程任務而設計。該專案提供了強大的命令列介面，能夠理解自然語言指令並執行複雜的軟體工程工作流程。

GitHub 地址： https://github.com/bytedance/trae-agent

核心特性

🌊 Lakeview

• 為代理步驟提供簡潔明瞭的摘要功能
• 幫助使用者快速理解代理執行過程

🤖 多LLM支援

• 支援 OpenAI 官方 API
• 支援 Anthropic 官方 API
• 靈活的模型選擇機制

🛠️ 豐富的工具生態系統

• 檔案編輯功能
• Bash 命令執行
• 順序思考（Sequential Thinking）
• 更多擴展工具

🎯 互動模式

• 對話式介面，支援迭代開發
• 即時互動，提升開發體驗

📊 軌跡記錄

• 詳細記錄所有代理操作
• 支援偵錯和分析
• 自動生成執行報告

⚙️ 靈活配置

• 基於JSON的配置系統
• 支援環境變數配置
• 多層級配置優先順序

🚀 簡易安裝

• 基於pip的簡單安裝流程
• 推薦使用UV進行專案設定

安裝指南

推薦安裝方式（使用UV）

git clone https://github.com/bytedance/trae-agent.git
cd trae-agent
uv sync

環境變數配置

# OpenAI API Key
export OPENAI_API_KEY="your-openai-api-key"

# Anthropic API Key  
export ANTHROPIC_API_KEY="your-anthropic-api-key"

使用方法

基本任務執行

# 簡單任務
trae-cli run "Create a hello world Python script"

# 指定提供商和模型
trae-cli run "Fix the bug in main.py" --provider anthropic --model claude-sonnet-4-20250514

# 指定工作目錄
trae-cli run "Add unit tests for the utils module" --working-dir /path/to/project

# 儲存軌跡檔案用於偵錯
trae-cli run "Refactor the database module" --trajectory-file debug_session.json

# 強制生成補丁
trae-cli run "Update the API endpoints" --must-patch

互動模式

# 啟動互動會話
trae-cli interactive

# 使用自訂配置
trae-cli interactive --provider openai --model gpt-4o --max-steps 30

互動模式命令

• 輸入任務描述執行任務
• status - 查看代理資訊
• help - 顯示可用命令
• clear - 清屏
• exit 或 quit - 結束會話

配置管理

# 顯示當前配置
trae-cli show-config

# 使用自訂配置檔案
trae-cli show-config --config-file my_config.json

配置檔案

Trae Agent 使用 JSON 配置檔案 (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
    }
  }
}

配置優先順序

1. 命令列參數（最高優先順序）
2. 配置檔案值
3. 環境變數
4. 預設值（最低優先順序）

內建工具

str_replace_based_edit_tool - 檔案操作工具

• view - 顯示檔案內容或目錄列表
• create - 建立新檔案
• str_replace - 替換檔案中的文字
• insert - 在指定行插入文字

bash - Shell命令執行

• 執行命令和腳本
• 持久狀態處理
• 處理長時間執行的程序
• 捕獲輸出和錯誤

sequential_thinking - 結構化問題解決

• 分解複雜問題
• 迭代思考與修正功能
• 假設生成和驗證

task_done - 任務完成訊號

• 標記任務成功完成
• 提供最終結果和摘要

軌跡記錄

Trae Agent 自動記錄詳細的執行軌跡用於偵錯和分析：

# 自動生成軌跡檔案
trae-cli run "Debug the authentication module"
# 儲存到：trajectory_20250612_220546.json

# 自訂軌跡檔案
trae-cli run "Optimize the database queries" --trajectory-file optimization_debug.json

軌跡檔案內容

• LLM互動： 所有訊息、回應和工具呼叫
• 代理步驟： 狀態轉換和決策點
• 工具使用： 呼叫的工具及其結果
• 元資料： 時間戳、令牌使用量和執行指標

貢獻指南

貢獻流程

1. Fork 儲存庫
2. 建立特性分支 (git checkout -b feature/amazing-feature)
3. 進行更改
4. 為新功能添加測試
5. 提交更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 提交 Pull Request

開發規範

• 遵循 PEP 8 樣式指南
• 為新功能添加測試
• 根據需要更新文件
• 適當使用類型提示
• 確保所有測試通過後再提交

系統要求

• Python 3.12+
• OpenAI API key（用於OpenAI模型）
• Anthropic API key（用於Anthropic模型）

故障排除

導入錯誤

# 嘗試設定PYTHONPATH
PYTHONPATH=. trae-cli run "your task"

API Key問題

# 驗證API keys是否設定
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

# 檢查配置
trae show-config

權限錯誤

# 確保檔案操作的適當權限
chmod +x /path/to/your/project