admin 管理员组

文章数量: 1086761

文章目录

    • 一、项目概览
      • 相关资源
      • 核心特性
      • 架构设计
        • 核心组件
    • 二、快速开始
      • 使用示例
        • 代码分析模式
        • 自动化重构
        • 交互式开发
    • 三、安装详解
      • 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（六）

本文标签： 助手 自主 软件 RA AID

版权声明：本文标题：RA.Aid - 自主软件开发助手 内容由网友自发贡献，该文观点仅代表作者本人， 转载请联系作者并注明出处：http://roclinux.cn/b/1747679485a2570265.html， 本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容，一经查实，本站将立刻删除。