自主开发软件。

RA.Aid（发音为"raid"）帮助您自主开发软件。它是一个基于 LangGraph（一种基于图的代理工作流框架）的代理任务执行框架构建的独立编码代理（coding agent）。该工具提供智能助手，可协助研究、规划以及实施多步开发任务。RA.Aid 可通过 --use-aider 标志选择性与 aider（https://aider.chat/，一种代码编辑工具）集成，以利用其专门的代码编辑能力。

结果是近乎全自动的软件开发。

喜欢 RA.Aid 吗？ 在 GitHub 上给我们一颗星 ⭐ 以示支持！

以下是 RA.Aid 为自己添加功能的演示：

文档

完整文档位于 https://docs.ra-aid.ai

主要章节：

• 安装指南
• 推荐配置
• 开放模型设置
• 使用示例
• 日志系统
• 内存管理
• 贡献指南
• 获取帮助

目录

• 功能特性
• 安装
• 用法
• 架构
• 依赖项
• 开发设置
• 贡献
• 许可证
• 联系方式

👋 非常欢迎提交 Pull requests！ 有关于如何改进 RA.Aid 的想法吗？不要害羞——您的帮助能带来真正的改变！

💬 加入我们的 Discord 社区： 点击此处加入

⚠️ 重要提示：风险自担 ⚠️

• 此工具能够且将会自动执行 shell 命令（命令行指令）并进行代码更改
• 可启用 --cowboy-mode 标志以跳过 shell 命令批准提示
• 不提供任何明示或暗示的保证
• 始终在版本控制的仓库中使用
• 在提交之前，请在 git diff（差异对比）中审查提议的更改

主要功能

• 多步任务规划：代理将复杂任务分解为离散的、可管理的步骤，并按顺序执行它们。这种系统化的方法确保了彻底的实施并减少了错误。

• 自动化命令执行：代理可以自动运行 shell 命令以完成任务。虽然这使其功能强大，但也意味着您应该仔细审查其操作。

• 利用专家推理模型的能力：代理可以使用高级推理模型，例如 OpenAI 的 o1，仅在需要时，例如解决复杂的调试问题或规划复杂功能实施。

• 网络研究能力：利用 Tavily API（网络搜索 API）进行智能网络搜索，以增强研究并为开发任务收集现实世界背景

• 三阶段架构：

  1. 研究：分析代码库并收集上下文
  2. 规划：将任务分解为具体的、可操作的步骤
  3. 实施：按顺序执行每个计划的步骤

RA.Aid 的独特之处在于它能够处理超出单次代码编辑的复杂编程任务。通过将研究、战略规划和实施结合到一个连贯的工作流中，RA.Aid 可以：

• 分解并执行多步编程任务
• 研究和分析复杂代码库以回答架构问题
• 规划并实施跨多个文件的重大代码更改
• 提供现有代码结构和功能的详细解释
• 执行具有适当规划的复杂重构操作

功能特性

• 三阶段架构：工作流由三个强大的阶段组成：

  1. 研究 🔍 - 收集和分析信息
  2. 规划 📋 - 制定执行策略
  3. 实施 ⚡ - 在 AI 协助下执行计划

  每个阶段都由专用的 AI 代理和专用工具集提供支持。

• 高级 AI 集成：基于 LangChain（语言模型应用开发框架）构建，并利用最新的 LLMs（大型语言模型）进行自然语言理解和生成。

• 人机交互（Human-in-the-Loop）：可选模式，使代理能够在任务执行期间向您提问，确保更高的准确性并更好地处理可能需要您输入或澄清的复杂任务

• 综合工具集：

  • Shell 命令执行
  • 专家查询系统
  • 文件操作和管理
  • 内存管理
  • 研究和规划工具
  • 代码分析能力

• 交互式 CLI 接口：简单而强大的 CLI（命令行界面）接口，用于无缝交互

• 模块化设计：构建为 Python 包，具有用于控制台输出、处理、文本实用程序和工具的专用模块

• Git 集成：内置支持 Git（版本控制系统）操作和仓库管理

安装

Windows 安装

1. 从 python.org 安装 Python 3.8 或更高版本
2. 安装所需的系统依赖项：

   # Install Chocolatey if not already installed (run in admin 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.org/install.ps1'))
   
   # Install ripgrep using Chocolatey
   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
   

Unix/Linux 安装

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

pip install ra-aid

使用 Homebrew 安装 macOS

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

注意： macOS 也可以使用上述 pip 方式进行安装。

前提条件

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

```bash
# 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 Makehub provider (optional)
export MAKEHUB_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 标志 (flag) 时，编程工具 (aider) 将根据您可用的 API (应用程序接口) 密钥自动选择其模型：

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

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

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

注意： aider 必须单独安装，因为它不包含在 RA.Aid 包中。详见 aider-chat 了解更多详情。

完整的安装文档可在我们的 安装指南 中找到。

使用方法

RA.Aid 旨在简单而强大。使用方法如下：

# 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

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

命令行选项

• -m, --message: 要执行的任务或查询（必需，聊天模式除外，不能与 --msg-file 一起使用）
• --msg-file: 包含任务/消息的文本文件路径（不能与 --message 一起使用）
• --research-only: 仅执行研究而不进行实现
• --provider: 要使用的 LLM (大型语言模型) 提供商（选项：anthropic, openai, openrouter, openai-compatible, makehub, gemini）
• --model: 要使用的模型名称（非 Anthropic 提供商必需）
• --use-aider: 启用 aider 集成以进行代码编辑。启用后，RA.Aid 将使用 aider 的专业代码编辑功能，而不是其原生的文件修改工具。当您需要 aider 的特定编辑功能或更喜欢其代码修改方法时，此选项很有用。此功能是可选的，默认禁用。
• --research-provider: 专门用于研究任务的提供商（如果未指定，则 fallback 到 --provider）
• --research-model: 专门用于研究任务的模型（如果未指定，则 fallback 到 --model）
• --planner-provider: 专门用于规划任务的提供商（如果未指定，则 fallback 到 --provider）
• --planner-model: 专门用于规划任务的模型（如果未指定，则 fallback 到 --model）
• --cowboy-mode: 跳过 Shell 命令的交互式确认
• --expert-provider: 用于专家知识查询的 LLM 提供商（选项：anthropic, openai, openrouter, openai-compatible, makehub, gemini）
• --expert-model: 用于专家知识查询的模型名称（非 OpenAI 提供商必需）
• --hil, -H: 启用人在回路 (Human-in-the-loop) 模式，以便在任务执行期间提供交互式协助
• --chat: 启用具有直接人工交互的聊天模式（隐含 --hil）
• --log-mode: 日志模式（选项：file, console）
  • file（默认）：记录到文件和控制台（控制台仅显示警告和错误）
  • console: 仅记录到控制台，处于指定的日志级别，不进行文件日志记录
• --log-level: 设置特定日志级别（debug, info, warning, error, critical）
  • 使用 --log-mode=file 时：控制文件日志级别（控制台仍仅显示 warning+）
  • 使用 --log-mode=console 时：直接控制控制台日志级别
  • 默认：warning
• --experimental-fallback-handler: 启用实验性回退处理器 (Experimental Fallback Handler)，当同一工具连续失败 3 次时尝试修复工具调用。（推荐使用 OPENAI_API_KEY，因为 openai 拥有前 5 名的工具调用模型。）详见 ra_aid/tool_leaderboard.py 了解更多信息。
• --pretty-logger: 启用彩色面板式格式化日志输出以提高可读性。
• --temperature: LLM 温度 (Temperature)（0.0-2.0），用于控制响应中的随机性
• --disable-limit-tokens: 禁用 Anthropic Claude ReAct 代理 (Agent) 的 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 (词元) 使用量和成本
• --max-cost: 最大成本阈值（美元）（正浮点数）
• --max-tokens: 最大 Token (词元) 阈值（正整数）
• --exit-at-limit: 当达到 --max-cost 或 --max-tokens 限制时立即退出而不提示
• --price-performance-ratio: Makehub API 的性价比（0.0-1.0，其中 0.0 优先考虑速度，1.0 优先考虑成本效率）
• --version: 显示程序版本号并退出
• --server: 启动带有 Web 界面的服务器（Alpha (测试版) 功能）
• --server-host: 服务器监听的主机（默认：0.0.0.0）（Alpha (测试版) 功能）
• --server-port: 服务器监听的端口（默认：1818）（Alpha (测试版) 功能）

示例任务

1. 代码分析 (Code Analysis)：

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

2. 复杂变更 (Complex Changes)：

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

3. 自动更新 (Automated Updates)：

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

4. 代码研究 (Code Research)：

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

5. 代码研究 (Code Research)：

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

6. 重构 (Refactoring)：

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

人机回环模式 (Human-in-the-Loop Mode)

启用交互模式以允许代理 (agent) 在任务执行期间向您提问：

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

此模式特别适用于：

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

网络研究 (Web Research)

该代理 (agent) 具备由 Tavily API (应用程序接口) 驱动的自主网络研究能力，无缝地将现实世界信息集成到其问题解决工作流中。当代理确定需要额外上下文 (context) 时，会自动进行网络研究——无需显式配置。

例如，在研究现代认证实践或调查新的 API 要求时，代理将自主：

• 搜索当前的最佳实践和安全建议
• 查找相关文档和技术规范
• 收集现实世界的实现示例
• 保持对最新行业标准的了解

虽然网络研究会在需要时自动进行，但您也可以显式请求以研究为重点的任务：

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

确保设置您的 TAVILY_API_KEY 环境变量 (Environment variable) 以启用此功能。

聊天模式 (Chat Mode)

使用 --chat 启用，将 ra-aid 转变为交互式助手，指导您完成研究和实施任务。就您想要构建的内容进行自然对话，共同探索选项，并分发工作——同时保持讨论的上下文 (context)。当您希望协作思考问题而不仅仅是执行命令时，此模式非常完美。

带 Web 界面 (Web Interface) 的服务器

RA.Aid 包含一个带有 Web 界面的现代服务器，提供：

• 美观的深色主题聊天界面
• 代理 (agent) 轨迹的实时流式传输 (streaming)
• 适用于所有设备的响应式设计 (Responsive design)

启动带 Web 界面的服务器：

# 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：启动带 Web 界面的服务器
• --server-host：监听的主机 (默认：0.0.0.0)
• --server-port：监听的端口 (默认：1818)

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

命令中断和反馈

您可以随时按 Ctrl-C 中断代理 (agent)。这将暂停代理，允许您提供反馈、调整指令或将执行引导至新方向。如果您想完全退出程序，请再次按 Ctrl-C。

使用 Cowboy 模式自动化 Shell (命令行环境) 命令 🏇

--cowboy-mode 标志启用自动化 Shell 命令执行，无需确认提示。这适用于：

• CI/CD (持续集成/持续部署) 流水线
• 自动化测试环境
• 批量处理操作
• 脚本化工作流

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

⚠️ 重要安全说明：

• Cowboy 模式跳过 Shell 命令的确认提示
• 始终在版本控制仓库 (version-controlled repositories) 中使用
• 确保运行前工作树 (working tree) 干净
• 提交前在 git diff (Git 差异对比) 中审查变更

模型 (Model) 配置

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

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

注意：专家工具可以配置为使用不同的提供商（OpenAI, Anthropic, OpenRouter, Gemini），使用 --expert-provider 标志以及相应的 EXPERT_*API_KEY 环境变量 (Environment variable)。每个提供商都需要通过适当的环境变量设置其自己的 API 密钥。

环境变量 (Environment Variables)

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

• ANTHROPIC_API_KEY：默认 Anthropic 提供商所需
• OPENAI_API_KEY：OpenAI 提供商所需
• OPENROUTER_API_KEY：OpenRouter 提供商所需
• MAKEHUB_API_KEY：Makehub 提供商所需
• DEEPSEEK_API_KEY：DeepSeek 提供商所需
• OPENAI_API_BASE：OpenAI 兼容提供商所需，连同 OPENAI_API_KEY
• GEMINI_API_KEY：Gemini 提供商所需

专家工具环境变量：

• EXPERT_OPENAI_API_KEY：使用 OpenAI 提供商的专家工具 API 密钥
• EXPERT_ANTHROPIC_API_KEY：使用 Anthropic 提供商的专家工具 API 密钥
• EXPERT_OPENROUTER_API_KEY：使用 OpenRouter 提供商的专家工具 API 密钥
• EXPERT_MAKEHUB_API_KEY：使用 Makehub 提供商的专家工具 API 密钥（如果未设置则自动使用 MAKEHUB_API_KEY）
• 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 Makehub provider
export MAKEHUB_API_KEY=your_api_key_here

# For OpenAI-compatible providers
export OPENAI_API_BASE=your_api_base_url

针对 Gemini provider（提供商）

export GEMINI_API_KEY=your_api_key_here

自定义 model（模型）示例

1. 使用 Anthropic（默认）

   # Uses default model (claude-3-7-sonnet-20250219)
   ra-aid -m "Your task"
   
   # Or explicitly specify:
   ra-aid -m "Your task" --provider anthropic --model claude-3-5-sonnet-20241022
   

2. 使用 OpenAI

   ra-aid -m "Your task" --provider openai --model gpt-4o
   

3. 使用 OpenRouter

   ra-aid -m "Your task" --provider openrouter --model mistralai/mistral-large-2411
   

4. 使用 Makehub

   ra-aid -m "Your task" --provider makehub --model openai/gpt-4o
   
   # With price-performance optimization
   ra-aid -m "Your task" --provider makehub --model anthropic/claude-4-sonnet --price-performance-ratio 0.7
   

5. 使用 DeepSeek

   # Direct DeepSeek provider (requires DEEPSEEK_API_KEY)
   ra-aid -m "Your task" --provider deepseek --model deepseek-reasoner
   
   # DeepSeek via OpenRouter
   ra-aid -m "Your task" --provider openrouter --model deepseek/deepseek-r1
   

6. 配置 Expert provider（提供商）

   expert tool（专家工具）由 agent（代理）用于复杂逻辑和调试任务。可以使用 --expert-provider flag（标志）以及相应的 EXPERT_*API_KEY environment variables（环境变量）将其配置为使用不同的 provider（提供商）（OpenAI, Anthropic, OpenRouter, Gemini, openai-compatible）。

   # Use Anthropic for expert tool
   export EXPERT_ANTHROPIC_API_KEY=your_anthropic_api_key
   ra-aid -m "Your task" --expert-provider anthropic --expert-model claude-3-5-sonnet-20241022
   
   # Use OpenRouter for expert tool
   export OPENROUTER_API_KEY=your_openrouter_api_key
   ra-aid -m "Your task" --expert-provider openrouter --expert-model mistralai/mistral-large-2411
   
   # Use DeepSeek for expert tool
   export DEEPSEEK_API_KEY=your_deepseek_api_key
   ra-aid -m "Your task" --expert-provider deepseek --expert-model deepseek-reasoner
   
   # Use Makehub for expert tool (automatically uses MAKEHUB_API_KEY)
   export MAKEHUB_API_KEY=your_makehub_api_key
   ra-aid -m "Your task" --expert-provider makehub --expert-model anthropic/claude-4-sonnet
   
   # Use default OpenAI for expert tool
   export EXPERT_OPENAI_API_KEY=your_openai_api_key
   ra-aid -m "Your task" --expert-provider openai --expert-model o1
   
   # Use Gemini for expert tool
   export EXPERT_GEMINI_API_KEY=your_gemini_api_key
   ra-aid -m "Your task" --expert-provider gemini --expert-model gemini-2.0-flash-thinking-exp-1219
   

您可以添加的 Aider 特定 environment variables（环境变量）：

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

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

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

重要注意事项：

• 性能因 model（模型）而异。默认的 Claude 3 Sonnet model（模型）目前提供最佳且最可靠的结果。
• Model（模型）配置通过命令行参数完成：--provider 和 --model
• 除了 Anthropic（默认为 claude-3-7-sonnet-20250219）之外，所有 provider（提供商）都需要 --model 参数

更多信息请参阅我们的 Open Models Setup（开放模型设置） 指南。

Architecture（架构）

RA.Aid 实现了一个三阶段 architecture（架构），用于处理开发和研发任务：

1. Research Stage（研究阶段）：

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

2. Planning Stage（规划阶段）：

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

3. Implementation Stage（实施阶段）：

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

Core Components（核心组件）

• Console Module（控制台模块） (console/)：处理控制台输出格式化和用户交互
• Processing Module（处理模块） (proc/)：管理交互处理和 workflow（工作流）控制
• Text Module（文本模块） (text/)：提供文本处理和操作 utilities（实用工具）
• Tools Module（工具模块） (tools/)：包含用于文件操作、搜索等的各种 utility tools（实用工具）

Dependencies（依赖项）

Core Dependencies（核心依赖项）

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

Development Dependencies（开发依赖项）

• pytest>=7.0.0：Testing framework（测试框架）
• pytest-timeout>=2.2.0：测试超时管理

Development Setup（开发设置）

1. Clone（克隆）repository（仓库）：

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

2. Create（创建）并 activate（激活）一个 virtual environment（虚拟环境）：

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

3. Install（安装）development dependencies（开发依赖项）：

pip install -e ".[dev]"

4. Run（运行）tests（测试）：

python -m pytest

Contributing（贡献）

欢迎贡献！请遵循以下步骤：

1. Fork（复刻）repository（仓库）
2. Create（创建）一个 feature branch（功能分支）：

git checkout -b feature/your-feature-name

3. 进行更改并 commit（提交）：

git commit -m 'Add some feature'

4. Push（推送）到您的 fork（复刻）：

git push origin feature/your-feature-name

5. Open（开启）一个 Pull Request（拉取请求）

Guidelines（指南）

• 遵循 PEP 8 风格指南
• 为新功能添加 tests（测试）
• 根据需要更新 documentation（文档）
• 保持 commits（提交）专注且 message（消息）清晰
• 在提交 PR 之前确保所有 tests（测试）通过

更多信息请参阅我们的 Contributing Guide（贡献指南）。

License（许可证）

本项目根据 Apache License 2.0 许可 - 详见 LICENSE 文件。

Copyright (c) 2024 AI Christianson

Contact（联系方式）

• Issues（问题）：请在我们的 Issue Tracker（问题追踪器） 上报告 bugs（错误）和 feature requests（功能请求）
• Repository（仓库）：https://github.com/ai-christianson/RA.Aid
• Documentation（文档）：https://github.com/ai-christianson/RA.Aid#readme

RA.Aid 快速上手指南

RA.Aid 是一个自主软件开发代理（Coding Agent），基于 LangGraph 构建。它能够自主进行研究、规划和实施多步骤开发任务，支持近乎全自动的软件开发流程。

环境准备

系统要求

• Python: 3.8 或更高版本
• 操作系统: Windows, Linux, macOS
• 版本控制: 建议在 Git 仓库中使用，以便审查变更

前置依赖与 API 密钥

在使用前，需配置所需 AI 服务的 API 密钥。可以通过环境变量或 .env 文件设置。

必需/推荐密钥：

# Anthropic Claude 模型（推荐）
export ANTHROPIC_API_KEY=your_anthropic_key

# 网络研究能力（可选但推荐）
export TAVILY_API_KEY=your_tavily_key

# 其他可选提供商
export OPENAI_API_KEY=your_openai_key
export OPENROUTER_API_KEY=your_openrouter_key

注意：若使用 --use-aider 功能，需单独安装 aider，RA.Aid 会根据可用的 API 密钥自动选择模型。

安装步骤

Unix / Linux / macOS (pip)

直接使用 pip 安装：

pip install ra-aid

macOS (Homebrew)

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

Windows

1. 安装 Python 3.8+。
2. 安装系统依赖 ripgrep (需管理员权限 PowerShell)：

   # 安装 Chocolatey (如未安装)
   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.org/install.ps1'))
   
   # 安装 ripgrep
   choco install ripgrep
   

3. 安装 RA.Aid 及 Windows 特定依赖：

   pip install ra-aid
   pip install pywin32
   

基本使用

执行任务

最基本的用法是通过 -m 参数指定任务描述：

ra-aid -m "为项目添加用户登录功能"

常用模式

• 仅研究模式（不实施代码更改）：

  ra-aid -m "解释当前的认证流程" --research-only
  

• 详细日志输出：

  ra-aid -m "修复登录 bug" --log-mode console --log-level debug
  

• 人机协作模式（执行过程中询问用户）：

  ra-aid -m "重构数据库模块" --hil
  

⚠️ 安全警告

• 自动执行：RA.Aid 会自动执行 Shell 命令并修改代码。
• 版本控制：务必在 Git 仓库中使用，提交前通过 git diff 审查变更。
• 牛仔模式：--cowboy-mode 会跳过命令确认提示，请谨慎使用。
• 风险自负：工具处于 Beta 阶段，不提供保修。