Skip to main content

Crate rucora

Crate rucora 

Source
Expand description

§rucora

用 Rust 编写的高性能、类型安全的 LLM 应用开发框架

§特性

  • ⚡ 极速性能 - Rust 原生，零成本抽象
  • 🔒 类型安全 - 编译时错误检查，运行时更可靠
  • 💰 成本监控 - 内置 Token 计数和成本管理
  • 🧰 丰富工具 - 12+ 内置工具（Shell/File/HTTP/Git/Memory 等）
  • 🔌 灵活集成 - 支持 10+ LLM Provider（OpenAI、Anthropic、Gemini、Ollama 等）
  • 📊 可观测性 - 完整的日志、指标、追踪支持
  • 🧠 Agent 架构 - 思考与执行分离，支持自定义 Agent

§快速开始

§1. 添加依赖

[dependencies]
rucora = "0.1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"

§2. 设置环境变量

# 使用 OpenAI
export OPENAI_API_KEY=sk-your-key

# 或使用 Ollama（本地）
export OPENAI_BASE_URL=http://localhost:11434

§3. 编写代码

use rucora::provider::OpenAiProvider;
use rucora::agent::DefaultAgent;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let provider = OpenAiProvider::from_env()?;
     
    let agent = DefaultAgent::builder()
        .provider(provider)
        .model("gpt-4o-mini")
        .system_prompt("你是有用的助手")
        .build();
     
    let output = agent.run("你好").await?;
    println!("{}", output.text().unwrap_or("无回复"));
     
    Ok(())
}

§4. 运行

cargo run

§核心概念

§Agent（智能体）

Agent 负责思考和决策。它接收用户输入，分析需求，决定是否需要调用工具。

use rucora::agent::DefaultAgent;

let agent = DefaultAgent::builder()
    .provider(provider)
    .model("gpt-4o-mini")
    .system_prompt("你是有用的助手")
    .build();

let output = agent.run("北京天气怎么样？").await?;

§Tool（工具）

工具提供具体能力，如执行命令、读取文件、HTTP 请求等。

use rucora::tools::{ShellTool, FileReadTool};
use rucora::agent::DefaultAgent;

let agent = DefaultAgent::builder()
    .provider(provider)
    .model("gpt-4o-mini")
    .tool(ShellTool)
    .tool(FileReadTool)
    .build();

§Skill（技能）

技能是可配置的自动化任务，通过配置文件定义。

use rucora::skills::{SkillLoader, skills_to_tools, SkillExecutor};
use std::sync::Arc;

// 加载 Skills
let mut loader = SkillLoader::new("skills/");
let skills = loader.load_from_dir().await?;

// 转换为 Tools
let executor = Arc::new(SkillExecutor::new());
let tools = skills_to_tools(&skills, executor, skills_dir);

// 注册到 Agent
let agent = DefaultAgent::builder()
    .provider(provider)
    .tools(tools)
    .build();

§学习路径

§新手

  1. 运行 Hello World 示例
  2. 阅读 快速开始
  3. 查看 用户指南
  4. 参考 示例集合

§开发者

  1. 阅读 设计文档
  2. 学习 Agent 与 Runtime
  3. 参考 快速参考

§技能开发者

  1. 阅读 Skill 配置规范
  2. 参考 Skill 配置示例

§项目结构

rucora
├── core          - 核心抽象层（重新导出 rucora-core）
├── runtime       - 运行时（重新导出 rucora-runtime，需要 `runtime` feature）
├── agent         - Agent 实现（增强的 DefaultAgent，支持 Tools/MCP/A2A/Skills）
├── provider      - LLM Provider 实现（OpenAI/Ollama/Router）
├── tools         - 工具实现（Shell/File/HTTP/Git/Memory）
├── skills        - 技能实现（Echo/Command）
├── mcp           - MCP 协议集成（需要 `mcp` feature）
├── a2a           - A2A 协议集成（需要 `a2a` feature）
├── memory        - 记忆实现（InMemory/File）
├── retrieval     - 检索实现（Chroma）
├── embed         - Embedding 实现（OpenAI/Ollama）
├── rag           - RAG 管线（Chunking/Indexing/Retrieval）
├── conversation  - 对话历史管理
└── config        - 统一配置系统

§相关文档

Re-exports§

pub use compact::CompressionConfig;
pub use compact::CompressionStrategy;
pub use compact::LayeredCompressor;
pub use rucora_core as core;
pub use rucora_providers as provider;
pub use rucora_tools as tools;
pub use rucora_retrieval as retrieval;
pub use rucora_embed as embed;

Modules§

agent
Agent（智能体）模块
compact
上下文压缩模块
conversation
Conversation（对话历史）管理模块
memory
Memory（记忆）实现模块
middleware
中间件系统
prelude
常用类型和 trait 的快速访问
prompt
Prompt 模板系统
rag
RAG（检索增强生成）管线模块