用途
RubyLLM 是一个用于构建和维护 Ruby 或 Rails 应用的 AI 框架技能。它面向需要在现有 Ruby/Rails 项目中加入 AI 功能的开发者，覆盖聊天、智能体、工具、MCP 服务器、结构化输出、判断与评估等场景。该技能要求使用应用已安装的 RubyLLM 版本和既有约定，并说明其描述的是 2.x API，标记为 2.1 的功能需要 RubyLLM 2.1 或更高版本。
主要能力
RubyLLM 提供两套公开 API：
- 对话式 API：使用 chats、messages、tools、agents、结构化输出、流式传输和循环控制。
- 单项操作 API：使用 paint、animate、speak、transcribe、ocr、moderate、embed、rerank、judge、tokenize 和 research。单项操作返回类型化结果，无需聊天；部分操作支持流式或异步生命周期。
Provider 提供服务端点、认证、目录和协议选择；Protocol 负责转换请求与响应。两套 API 都使用这一集成层以及用于模型选择、配置、计费和插桩的共享服务。Rails 集成在同一 Ruby API 之上增加持久化、附件、流式 UI 支持、作业和生成器。
使用方式
技能建议先确认已安装版本：
bundle exec ruby -rruby_llm -e 'puts RubyLLM::VERSION'
bundle show ruby_llm
对于 1.x 应用，应使用其版本文档，除非用户要求升级，否则保持请求的变更在 1.x 上。添加 AI 功能不需要升级应用框架。
文档按任务组织，例如 overview/、configuration/、chat/、streaming/、attachments/、tools/、mcp/、structured-output/、agents/、image-generation/、embeddings/、judgments/、evaluations/、rails/、durable-agents/、cost-and-usage-tracking/、instrumentation/、batches/、agentic-workflows/、upgrading/ 等。Markdown 指南使用同名 .md 文件，API 参考从 api/RubyLLM.md 开始。
配置凭据通过 RubyLLM.configure 完成，并遵循应用的密钥存储方式。选择已配置的 Provider，使用 RubyLLM.models.find(id, provider: ...) 验证显式模型 ID，不要编造 ID 或用 assume_model_exists 掩盖拼写错误。
对话从 RubyLLM.chat 开始，用链式 with_* 方法设置选项；当指令、工具或选项需要复用时使用 RubyLLM::Agent。普通 Ruby 方法和作业可组合工作流。媒体、文档处理、审核、嵌入和重排等使用单项操作，读取其类型化结果，生成图像、视频和语音时使用 save。
ask 运行对话并返回消息；ask_later 暂存输入并返回 chat。显式循环控制使用 generate、run_tools、step 和 complete?。审批可在完成前暂停循环，检查 awaiting_approval? 并在 approve 或 deny 后恢复。queue 在循环运行时添加用户消息。
文本通过 message.content 读取，结构化输出通过 message.parsed 读取。工具通过继承 RubyLLM::Tool 实现，使用 description、parameter 或 parameters 块，并在 execute 上使用关键字参数；用 with_tools 注册，用 with_tool_options 配置 choice 和 concurrency。大型工具集可传 defer: true 让模型搜索工具。
MCP 服务器通过继承 RubyLLM::MCP 连接，并用 chat.with_mcp(...) 或 agent 的 mcp 宏附加。判断使用 RubyLLM::Judge 子类并调用 .judge(input)。
适用场景
适用于在 Ruby 或 Rails 应用中集成 AI 聊天、智能体、工具调用、MCP、结构化输出、图像与视频生成、语音与转录、OCR、内容审核、嵌入与重排、判断与评估、成本追踪、可观测性以及升级迁移等任务。
限制
该技能强调使用已安装版本和既有约定，不编造模型 ID，不添加 RubyLLM 已提供的第二个 Provider SDK。模型评分每次运行都会产生费用，除非应用记录请求，否则应避免将评分评估放入默认测试运行。RubyLLM 不会配置 OpenTelemetry SDK 或导出器，也不导出提示或响应。升级需逐版本进行，2.0 切换需要准备、回填、完成和应用特定对账。关于具体收费、价格、平台支持范围等细节，资料中暂未提供。