文章目录

• • 一、项目概览
  • • 相关资源
    • 核心特性
    • 架构设计
    • • 核心组件
  • 二、快速开始
  • • 使用示例
    • • 代码分析模式
      • 自动化重构
      • 交互式开发
  • 三、安装详解
  • • 1、Windows 安装指南
    • 2、Unix/Linux 安装
    • 3、通过 Homebrew 在 macOS 上安装
    • 4、前提条件
  • 四、使用说明
  • • 1、使用方法
    • 2、命令行选项
    • 3、示例任务
    • 4、人机协同模式
    • 5、网络调研
    • 6、聊天模式
    • 7、带网页界面的服务器
    • 8、命令中断与反馈
    • 9、使用牛仔模式 🏇 实现 Shell 命令自动化
    • 10、模型配置
    • • 环境变量
    • 11、自定义模型示例
  • 五、依赖项
  • • 核心依赖项
    • 开发依赖项
  • 六、开发环境配置
  • 七、注意事项

一、项目概览

RA.Aid （发音同"raid"）是基于 LangGraph 任务执行框架构建的自主编程代理工具，可协助完成多步骤开发任务的研究、规划和实施工作。通过与 aider 工具集成，可实现接近完全自主的软件开发流程。

相关资源

• 源码：https://github/ai-christianson/RA.Aid
• 文档：https://docs.ra-aid.ai
• 社区：https://discord.gg/f6wYbzHYxV
• 演示：<assets/demo-ra-aid-task-1.gif>
• Python版本：https://img.shields.io/badge/python-3.8%2B-blue
• 许可证：https://img.shields.io/badge/license-Apache 2.0-blue
• 状态：https://img.shields.io/badge/status-Beta-yellow

核心特性

1、多阶段任务处理

• 研究阶段：分析代码库并收集上下文
• 规划阶段：将任务分解为可执行步骤
• 实施阶段：顺序执行每个规划步骤

2、智能工具集成

• 支持 Shell 命令自动执行
• 集成 Web 研究能力（Tavily API）
• 可调用专家推理模型处理复杂问题
• 可选 aider 代码编辑功能集成

3、安全控制机制

• 交互式命令确认（可跳过进入牛仔模式）
• 版本控制集成
• 人工干预模式（–hil）

架构设计

RA.Aid 采用三阶段架构来处理开发和研究任务：

1、研究阶段：

• 收集信息和上下文
• 分析需求
• 识别关键组件和依赖项

2、规划阶段：

• 制定详细的实施计划
• 将任务分解为可管理的步骤
• 识别潜在挑战及解决方案

3、实施阶段：

• 执行计划任务
• 生成代码或文档
• 执行必要的系统操作

核心组件

• 控制台模块 (console/): 负责控制台输出格式化和用户交互处理
• 处理模块 (proc/): 管理交互式处理和工作流控制
• 文本模块 (text/): 提供文本处理和操作工具集
• 工具模块 (tools/): 包含文件操作、搜索等多种实用工具

二、快速开始

# 基础安装
pip install ra-aid

# 环境变量配置（示例）
export ANTHROPIC_API_KEY=your_anthropic_key
export OPENAI_API_KEY=your_openai_key
export TAVILY_API_KEY=your_tavily_key

# 基础使用
ra-aid -m "您的开发任务描述"

使用示例

代码分析模式

ra-aid -m "解释认证中间件工作原理" --research-only

自动化重构

ra-aid -m "重构数据库连接代码使用连接池" --cowboy-mode

交互式开发

ra-aid -m "实现新功能" --hil

三、安装详解

1、Windows 安装指南

1、从 python 安装 Python 3.8 或更高版本

2、安装必要的系统依赖项：

# 如果尚未安装 Chocolatey，请先安装（在管理员权限的 PowerShell 中运行）
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey/install.ps1'))

# 使用 Chocolatey 安装 ripgrep
choco install ripgrep

3、安装 RA.Aid：

pip install ra-aid

4、安装 Windows 专用依赖项：

pip install pywin32

5、在 .env 文件中配置您的 API 密钥：

ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key

2、Unix/Linux 安装

RA.Aid 可以直接使用 pip 安装：

pip install ra-aid

3、通过 Homebrew 在 macOS 上安装

brew tap ai-christianson/homebrew-ra-aid
brew install ra-aid

注意： 也可以通过上述 pip 方式在 macOS 上安装。

4、前提条件

在使用 RA.Aid 之前，您需要获取所需 AI 服务的 API 密钥：

# Set up API keys based on your preferred provider:

# For Anthropic Claude models (recommended)
export ANTHROPIC_API_KEY=your_api_key_here

# For OpenAI models (optional)
export OPENAI_API_KEY=your_api_key_here

# For OpenRouter provider (optional)
export OPENROUTER_API_KEY=your_api_key_here

# For OpenAI-compatible providers (optional)
export OPENAI_API_BASE=your_api_base_url

# For Gemini provider (optional)
export GEMINI_API_KEY=your_api_key_here

# For web research capabilities
export TAVILY_API_KEY=your_api_key_here

注意：当使用 --use-aider 标志时，程序员工具 (aider) 会根据你现有的 API 密钥自动选择其模型：

• 如果设置了 ANTHROPIC_API_KEY 环境变量，系统将使用 Claude 模型
• 如果仅设置了 OPENAI_API_KEY，系统将使用 OpenAI 模型
• 您可以设置多个 API 密钥以启用不同功能

您可以从以下位置获取API密钥：

• Anthropic API密钥：https://console.anthropic/
• OpenAI API密钥：https://platform.openai/api-keys
• OpenRouter API密钥：https://openrouter.ai/keys
• Gemini API 密钥：https://aistudio.google/app/apikey

注意：aider 需要单独安装，因为它不包含在 RA.Aid 包中。更多详情请参阅 aider-chat。

完整安装文档请参阅我们的安装指南。

四、使用说明

RA.Aid 设计简洁而功能强大。以下是使用方法：

1、使用方法

# Basic usage
ra-aid -m "Your task or query here"

# Research-only mode (no implementation)
ra-aid -m "Explain the authentication flow" --research-only

# File logging with console warnings (default mode)
ra-aid -m "Add new feature" --log-mode file

# Console-only logging with detailed output
ra-aid -m "Add new feature" --log-mode console --log-level debug

更多信息请参阅我们的使用示例、日志系统和内存管理文档。

2、命令行选项

• -m, --message: 要执行的任务或查询（聊天模式外必填，不可与–msg-file同时使用）
• --msg-file: 包含任务/消息的文本文件路径（不可与–message同时使用）
• --research-only: 仅执行研究不进行实现
• --provider: 指定使用的LLM提供商（可选：anthropic, openai, openrouter, openai-compatible, gemini）
• --model: 指定使用的模型名称（非Anthropic提供商必填）
• --use-aider: 启用aider集成进行代码编辑。启用后，RA.Aid将使用aider的专业代码编辑功能替代原生文件修改工具。当需要aider特定编辑功能或偏好其代码修改方式时，此选项非常有用。该功能默认禁用。
• --research-provider: 专门用于研究任务的提供商（未指定时回退到–provider）
• --research-model: 专门用于研究任务的模型（未指定时回退到–model）
• --planner-provider: 专门用于规划任务的提供商（未指定时回退到–provider）
• --planner-model: 专门用于规划任务的模型（未指定时回退到–model）
• --cowboy-mode: 跳过shell命令的交互式确认
• --expert-provider: 专家知识查询使用的LLM提供商（可选：anthropic, openai, openrouter, openai-compatible, gemini）
• --expert-model: 专家知识查询使用的模型名称（非OpenAI提供商必填）
• --hil, -H: 启用人工介入模式，在任务执行期间提供交互式协助
• --chat: 启用直接人工交互的聊天模式（隐含–hil）
• --log-mode: 日志记录模式（可选：file, console）
  • file（默认）：同时记录到文件和控制台（控制台仅显示警告和错误）
  • console: 仅在控制台按指定日志级别记录，不保存文件
• --log-level: 设置特定日志级别（debug, info, warning, error, critical）
  • 配合--log-mode=file：控制文件记录级别（控制台仍仅显示警告及以上）
  • 配合--log-mode=console：直接控制控制台记录级别
  • 默认值：warning
• --experimental-fallback-handler: 启用实验性回退处理器，当同一工具连续失败3次时尝试修复调用（推荐配置OPENAI_API_KEY，因openai拥有前5名的工具调用模型）。详见ra_aid/tool_leaderboard.py。
• --pretty-logger: 启用彩色面板式格式化日志输出，提升可读性
• --temperature: 控制响应随机性的LLM温度值（0.0-2.0）
• --disable-limit-tokens: 禁用Anthropic Claude反应代理的token限制
• --recursion-limit: 代理操作的最大递归深度（默认：100）
• --test-cmd: 自定义测试命令。设置后系统会询问用户是否运行该命令
• --auto-test: 每次代码变更后自动运行测试
• --max-test-cmd-retries: 测试命令最大重试次数（默认：3）
• --test-cmd-timeout: 测试命令执行超时时间（秒，默认：300）
• --show-cost: 实时显示代理工作时的成本信息 - 目前仅支持claude模型代理
• --track-cost: 跟踪token使用量和成本（默认：False）
• --no-track-cost: 禁用token使用量和成本跟踪
• --version: 显示程序版本号并退出
• --server: 启动带Web界面的服务器（Alpha功能）
• --server-host: 服务器监听主机（默认：0.0.0.0）（Alpha功能）
• --server-port: 服务器监听端口（默认：1818）（Alpha功能）

3、示例任务

1、代码分析：

ra-aid -m "Explain how the authentication middleware works" --research-only

2、复杂变更：

ra-aid -m "Refactor the database connection code to use connection pooling" --cowboy-mode

3、自动化更新：

ra-aid -m "Update deprecated API calls across the entire codebase" --cowboy-mode

4、代码研究：

ra-aid -m "Analyze the current error handling patterns" --research-only

5、代码研究：

ra-aid -m "Explain how the authentication middleware works" --research-only

6、重构：

ra-aid -m "Refactor the database connection code to use connection pooling" --cowboy-mode

4、人机协同模式

启用交互模式，允许代理在执行任务过程中向您提问：

ra-aid -m "Implement a new feature" --hil
# or
ra-aid -m "Implement a new feature" -H

此模式特别适用于：

• 需要人工判断的复杂任务
• 澄清模糊的需求
• 制定架构决策
• 验证关键变更
• 提供领域专业知识

5、网络调研

https://github/ai-christianson/RA.Aid/blob/master/assets/demo-web-research-1.gif

该智能体具备由Tavily API驱动的自主网络调研能力，能够将现实世界信息无缝整合到其问题解决流程中。当智能体判断需要额外上下文时，会自动触发网络调研——无需显式配置。

例如，在研究现代身份验证实践或调查新API需求时，智能体会自主执行以下操作：

• 搜索当前最佳实践和安全建议
• 查找相关文档和技术规范
• 收集实际实现案例
• 持续跟踪最新行业标准

虽然网络调研会根据需要自动触发，但您也可以明确下达以调研为核心的任务指令：

# Focused research task with web search capabilities
ra-aid -m "Research current best practices for API rate limiting" --research-only

请确保设置 TAVILY_API_KEY 环境变量以启用此功能。

6、聊天模式

https://github/ai-christianson/RA.Aid/blob/master/assets/demo-chat-mode-1.gif

使用 --chat 参数启用该模式，将 ra-aid 转换为一个交互式助手，引导您完成研究和实施任务。您可以自然地讨论想要构建的内容，共同探索选项并分配工作，同时保持对话的上下文。当您希望以协作方式思考问题而不仅仅是执行命令时，这是理想的选择。

7、带网页界面的服务器

RA.Aid 包含一个现代化的服务器，提供以下网页界面功能：

• 美观的深色主题聊天界面
• 实时流式传输智能体轨迹
• 响应式设计，适配所有设备

要启动带网页界面的服务器：

# Start with default settings (0.0.0.0:1818)
ra-aid --server

# Specify custom host and port
ra-aid --server --server-host 127.0.0.1 --server-port 3000

带Web界面的服务器命令行选项：

• --server: 启动带有网页界面的服务器
• --server-host: 监听的主机地址（默认值：0.0.0.0）
• --server-port: 监听端口（默认值：1818）

启动服务器后，在网页浏览器中打开显示的URL（例如：http://localhost:1818）。

8、命令中断与反馈

你可以随时通过按下Ctrl-C来中断代理程序。这会暂停代理，让你能够提供反馈、调整指令或引导执行转向新方向。如果想完全退出程序，请再次按下Ctrl-C。

9、使用牛仔模式 🏇 实现 Shell 命令自动化

--cowboy-mode 标志允许无需确认提示即可自动执行 Shell 命令，适用于以下场景：

• CI/CD 流水线
• 自动化测试环境
• 批量处理操作
• 脚本化工作流

ra-aid -m "Update all deprecated API calls" --cowboy-mode

⚠️ 重要安全注意事项：

• Cowboy 模式会跳过 shell 命令的确认提示
• 始终在版本控制仓库中使用
• 在运行前请确保工作区是干净的
• 在提交前检查 git diff 中的变更

10、模型配置

RA.Aid 支持多种 AI 提供商和模型。默认模型为 Anthropic 的 Claude 3 Sonnet (claude-3-7-sonnet-20250219)。

当使用 --use-aider 标志时，编程工具 (aider) 会根据您可用的 API 密钥自动选择模型。如果设置了 ANTHROPIC_API_KEY，它将使用 Claude 模型；如果只有 OPENAI_API_KEY 可用，则会回退到 OpenAI 模型。

注意：专家工具可通过 --expert-provider 标志配置使用不同的提供商（OpenAI、Anthropic、OpenRouter、Gemini），同时需要设置对应的 EXPERT_*API_KEY 环境变量。每个提供商都需要通过相应的环境变量设置自己的 API 密钥。

环境变量

RA.Aid 通过环境变量支持多种服务提供商：

• ANTHROPIC_API_KEY：默认 Anthropic 提供商所需
• OPENAI_API_KEY：OpenAI 提供商所需
• OPENROUTER_API_KEY：OpenRouter 提供商所需
• DEEPSEEK_API_KEY：DeepSeek 提供商所需
• OPENAI_API_BASE：与 OPENAI_API_KEY 配合使用，为 OpenAI 兼容提供商所需
• GEMINI_API_KEY：Gemini 提供商所需

专家工具环境变量：

• EXPERT_OPENAI_API_KEY：专家工具使用 OpenAI 提供商的 API 密钥
• EXPERT_ANTHROPIC_API_KEY：专家工具使用 Anthropic 提供商的 API 密钥
• EXPERT_OPENROUTER_API_KEY：专家工具使用 OpenRouter 提供商的 API 密钥
• EXPERT_OPENAI_API_BASE：专家工具使用 OpenAI 兼容提供商的基础 URL
• EXPERT_GEMINI_API_KEY：专家工具使用 Gemini 提供商的 API 密钥
• EXPERT_DEEPSEEK_API_KEY：专家工具使用 DeepSeek 提供商的 API 密钥

您可以在 shell 的配置文件中永久设置这些变量（例如 ~/.bashrc 或 ~/.zshrc）：

# Default provider (Anthropic)
export ANTHROPIC_API_KEY=your_api_key_here

# For OpenAI features and expert tool
export OPENAI_API_KEY=your_api_key_here

# For OpenRouter provider
export OPENROUTER_API_KEY=your_api_key_here

# For OpenAI-compatible providers
export OPENAI_API_BASE=your_api_base_url

# For Gemini provider
export GEMINI_API_KEY=your_api_key_here

11、自定义模型示例

1、使用 Anthropic（默认）

# 使用默认模型 (claude-3-7-sonnet-20250219)
ra-aid -m "您的任务"

# 或显式指定：
ra-aid -m "您的任务" --provider anthropic --model claude-3-5-sonnet-20241022

2、使用 OpenAI

ra-aid -m "您的任务" --provider openai --model gpt-4o

3、使用 OpenRouter

ra-aid -m "您的任务" --provider openrouter --model mistralai/mistral-large-2411

4、使用 DeepSeek

   # 直接使用 DeepSeek 提供商（需要 DEEPSEEK_API_KEY）
   ra-aid -m "您的任务" --provider deepseek --model deepseek-reasoner
   
   # 通过 OpenRouter 使用 DeepSeek
   ra-aid -m "您的任务" --provider openrouter --model deepseek/deepseek-r1

5、配置专家提供商

专家工具由代理用于处理复杂逻辑和调试任务。可以通过 --expert-provider 标志配合相应的 EXPERT_*API_KEY 环境变量来配置不同的提供商（OpenAI、Anthropic、OpenRouter、Gemini、openai-compatible）。

# 为专家工具使用 Anthropic
export EXPERT_ANTHROPIC_API_KEY=您的_anthropic_api密钥
ra-aid -m "您的任务" --expert-provider anthropic --expert-model claude-3-5-sonnet-20241022

# 为专家工具使用 OpenRouter
export OPENROUTER_API_KEY=您的_openrouter_api密钥
ra-aid -m "您的任务" --expert-provider openrouter --expert-model mistralai/mistral-large-2411

# 为专家工具使用 DeepSeek
export DEEPSEEK_API_KEY=您的_deepseek_api密钥
ra-aid -m "您的任务" --expert-provider deepseek --expert-model deepseek-reasoner

# 为专家工具使用默认的 OpenAI
export EXPERT_OPENAI_API_KEY=您的_openai_api密钥
ra-aid -m "您的任务" --expert-provider openai --expert-model o1

# 为专家工具使用 Gemini
export EXPERT_GEMINI_API_KEY=您的_gemini_api密钥
ra-aid -m "您的任务" --expert-provider gemini --expert-model gemini-2.0-flash-thinking-exp-1219

可添加的 Aider 特定环境变量：

• AIDER_FLAGS：可选，以逗号分隔的标志列表，传递给底层的 aider 工具（例如 “yes-always,dark-mode”）

# Optional: Configure aider behavior
export AIDER_FLAGS="yes-always,dark-mode,no-auto-commits"

注意：对于 AIDER_FLAGS，指定标志时带或不带前导的 -- 均可。多个标志应当用逗号分隔，标志周围的空格会自动处理。例如，"yes-always,dark-mode" 和 "--yes-always, --dark-mode" 都是有效的写法。

重要提示：

• 不同模型之间的性能存在差异。目前默认的Claude 3 Sonnet模型能提供最佳且最可靠的结果。
• 模型配置通过命令行参数完成：--provider 和 --model
• 除Anthropic外（默认使用claude-3-7-sonnet-20250219），所有服务商都必须提供--model参数

更多信息请参阅我们的开放模型设置指南。

五、依赖项

核心依赖项

• langchain-anthropic: LangChain 与 Anthropic Claude 的集成
• tavily-python: 用于网络研究的 Tavily API 客户端
• langgraph: 基于图的工作流管理
• rich>=13.0.0: 终端格式化和输出
• GitPython==3.1.41: Git 仓库管理
• fuzzywuzzy==0.18.0: 模糊字符串匹配
• python-Levenshtein==0.23.0: 快速字符串匹配
• pathspec>=0.11.0: 路径规范工具

开发依赖项

• pytest>=7.0.0: 测试框架
• pytest-timeout>=2.2.0: 测试超时管理

六、开发环境配置

1、克隆代码仓库：

git clone https://github/ai-christianson/RA.Aid.git
cd RA.Aid

2、创建并激活虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3、安装开发依赖项：

pip install -e ".[dev]"

4、运行测试：

python -m pytest

七、注意事项

1、需配置有效的 API 密钥：

• Anthropic: https://console.anthropic/
• OpenAI: https://platform.openai/api-keys
• Tavily: https://tavily/

2、安全建议：

• 始终在版本控制环境下使用
• 谨慎使用牛仔模式
• 重要修改前进行代码备份

伊织 xAI 2025-05-03（六）