rails agent server

Rails代理服务器

用于AI代理的持久Rails服务器，避免了重复查询的启动开销。适用于像Claude Code这样的AI代理，它们需要快速访问Rails运行器，而无需在每次请求时等待Rails启动。

为什么是这颗宝石？

当在Rails应用程序中使用AI编码助手或自动化工具时，代理通常需要通过以下方式运行许多小查询 bin/rails runner 了解运行时行为或状态。使用 bin/rails runner 每次查询意味着每次启动Rails，每次查询通常需要5-10秒。

Rails代理服务器启动一个持久的后台服务器，将Rails加载到内存中。第一个请求需要正常的Rails启动时间，但后续请求几乎是即时的。

为什么不 bin/rails console?

AI代理无法轻松与 bin/rails console 因为：

• 交互式TTY要求：Rails控制台需要一个交互式终端（TTY），不会接受来自标准管道的输入
• 无请求/响应协议：没有简单的方法可以发送命令并仅接收其结果
• 会话复杂性：管理交互式控制台会话需要处理读线、提示检测和终端控制序列
• 输出解析：控制台输出包括提示、格式和难以通过编程解析的IRB元数据

Rails代理服务器通过Unix套接字提供了一个简单的请求/响应接口，使AI代理执行代码并获得干净的结果变得轻而易举。

为什么不是春天？

Spring是Rails的官方应用程序预加载程序，但它是为不同的用例设计的。

它们是如何工作的

春天 将预加载的Rails应用程序保存在内存中并使用 fork() 为每个命令创建一个新进程。当你奔跑时 bin/spring rails runner，它分叉预加载的进程，独立运行代码，然后退出。每次调用都是 无状态 有一个干净的石板。这也意味着Spring可以安全地处理 并发请求 来自多个代理或并行进程。

Rails代理服务器 启动Rails一次，并保持单个持久会话运行。它通过Unix套接字接受代码，并在同一个长时间运行的进程中对其进行评估。变量和状态在请求之间保持不变，例如 rails console，不 rails runner这意味着它是为 单一代理使用 -并发请求将不可预测地共享状态。

两者都解决了“Rails启动缓慢”的问题。Spring为每个命令分叉一个新的进程，而Rails代理服务器在单个持久会话中运行代码。

Rails代理服务器的工作原理（伪代码）

# Server process (runs in background)
def run
  load_rails_environment        # Boot Rails once
  create_unix_socket           # Create socket file for communication
  
  loop do
    client = accept_connection  # Wait for code to execute
    code = client.read          # Read the code string
    output = capture_output do  # Capture stdout/stderr
      eval(code, TOPLEVEL_BINDING)  # Execute in persistent session
    end
    client.write(output)        # Send output back
    client.close
  end
end

# Client (called by rails_agent_server command)
def execute(code)
  start_server unless server_running?  # Auto-start if needed
  
  socket = connect_to_server
  socket.write(code)              # Send code to evaluate
  response = socket.read          # Get output back
  socket.close
  
  puts response                   # Display to user
end

关键见解：代码在 TOPLEVEL_BINDING 在持久化进程中，变量和状态在请求之间传递，就像在 rails console.

如果Spring对你的团队很有效，它是一个可行的选择。Rails代理服务器适用于不喜欢使用Spring的团队。

为什么不使用MCP（模型上下文协议）？

MCP服务器为AI代理提供了一种结构化的方式，通过定义的工具和资源与系统进行交互。虽然MCP非常适合复杂、多步骤的工作流程和标准化的接口，但在以下情况下，Rails Agent Server更可取：

• 简洁：您只需要快速运行Rails代码，而无需定义MCP工具和模式
• 灵活性：AI代理可以执行任意Rails代码，而不限于预定义的工具操作
• 设置：无需配置MCP服务器定义、传输层或客户端-服务器通信
• 演出：直接命令执行比MCP的请求/响应协议开销更快
• 代币效率：MCP可以为结构化工具模式和响应消耗许多令牌
• 现有工作流：与已经知道如何运行shell命令的代理配合使用

Rails代理服务器是一种轻量级的替代方案，它让AI代理将您的Rails应用程序视为快速的REPL，而MCP更适合构建具有特定功能的正式集成。

安装

选项1：全局安装（建议用于AI代理）

全局安装gem，这样它就可以在不修改Gemfiles的情况下与任何Rails应用程序一起工作：

gem install rails_agent_server

这允许AI代理在任何Rails项目上立即使用该工具。

选项2：添加到Gemfile

或者，将其添加到应用程序的Gemfile中：

gem 'rails_agent_server', group: :development

然后执行：

bundle install

代理设置

将此部分添加到项目的 CLAUDE.md 或同等产品：

## Rails Console Access

This project uses `rails_agent_server` for fast Rails runner access without boot overhead.

When you need to query the database or run Rails code:
- Use `rails_agent_server 'YourCode.here'` instead of `bin/rails runner`
- First request auto-starts a persistent server (takes ~5 seconds)
- Subsequent requests are almost instant (no Rails boot time)
- Server stays running in background until you run `rails_agent_server stop`

Examples:
  rails_agent_server 'puts User.count'
  rails_agent_server 'puts Post.where(published: true).count'
  rails_agent_server 'puts User.find_by(email: "test@example.com")&.name'

Note: Use `bundle exec rails_agent_server` if the gem is in your Gemfile, or just `rails_agent_server` if installed globally.

用法

基本命令

这些命令旨在供AI代理（如Claude Code）或自动化工具使用，而不是手动使用。

# Run a Ruby expression (auto-starts server if needed)
rails_agent_server 'puts User.count'

# Run code that prints output
rails_agent_server 'puts User.pluck(:email).join(", ")'

# Run a script file
rails_agent_server /path/to/script.rb

# Server management
rails_agent_server status                    # Check if server is running
rails_agent_server stop                      # Stop the background server
rails_agent_server restart                   # Restart the background server

示例

# Database queries
rails_agent_server 'puts User.count'
rails_agent_server 'puts Post.where(published: true).pluck(:title)'
rails_agent_server 'puts User.find_by(email: "test@example.com")&.name'

# Inspect schema
rails_agent_server 'puts ActiveRecord::Base.connection.tables'
rails_agent_server 'puts User.column_names'

# Complex operations
rails_agent_server 'Rails.cache.clear; puts "Cache cleared"'

运作原理

1. 首次请求：当你跑步时 rails_agent_server 这是第一次：

- 生成后台服务器进程 - 加载Rails环境一次 - 创建用于通信的Unix套接字 - 存储PID以供管理

1. 后续请求：每个请求：

- 连接到现有的Unix套接字 - 发送要执行的代码 - 立即接收结果 - 无需Rails启动时间

1. 服务器管理：服务器：

- 在后台运行，直到明确停止 - 捕获打印输出和表达式结果 - 优雅地处理错误 - 退出时清理套接字和PID文件

文件位置

默认情况下，服务器在Rails应用程序中创建这些文件：

• 套接字: tmp/rails_agent_server.sock -用于通信的Unix套接字
• PID文件: tmp/pids/rails_agent_server.pid -管理流程ID
• 日志文件: log/rails_agent_server.log -服务器输出和错误

如果不在Rails目录中，则在以下位置创建文件 /tmp/.

演出

• 第一个请求：~5-10秒（Rails启动时间）
• 后续请求：几乎即时（无启动开销）
• 记忆：一个Rails进程在后台运行（约200-500MB，具体取决于您的应用程序）

何时重新启动

在以下情况下，您应该重新启动服务器：

• 您已更改模型文件或架构
• 您已更新初始化器
• 您已修改环境配置
• 服务器正在返回过时的数据

rails_agent_server restart

局限性

• 仅限单一代理：服务器一次处理一个请求。由于持久会话中的共享状态，多个代理或并发请求将是不可预测的。Spring的基于fork的方法通过将每个请求隔离在自己的进程中来安全地处理并发请求。
• 可能需要重新启动服务器以获取一些代码更改
• 每个Rails应用程序只运行一个服务器（共享套接字文件）
• 需要Unix套接字（macOS、Linux、WSL）

发展

签出repo后，运行 bin/setup 安装依赖项。然后，跑 rake test 运行测试。你也可以跑步 bin/console 获取一个交互式提示，让您可以进行实验。

要将此gem安装到本地计算机上，请运行 bundle exec rake install.

测试

测试套件包括单元测试（快速，在CI中运行）和集成测试（较慢，需要流程分叉）。默认情况下， rake test 只运行单元测试。看 测试.md 有关在本地运行集成测试的详细信息。

贡献

欢迎在GitHub上提交Bug报告和拉取请求，网址为https://github.com/andyw8/rails_agent_server.

许可证

根据以下条款，gem可作为开源软件使用 MIT许可证.