# ribo-pi-agent

**Repository Path**: zeronehost/ribo-pi-agent

## Basic Information

- **Project Name**: ribo-pi-agent
- **Description**: ribo-pi-agent 是一个基于 Rust 的 LLM Agent 框架，内置多 Provider 适配、流式响应、工具调用、上下文压缩与会话持久化能力
- **Primary Language**: Rust
- **License**: MulanPSL-2.0
- **Default Branch**: dev-01
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ribo-pi-agent

[English](./README.en.md) | 简体中文

> 基于 Rust 编写的 LLM Agent 框架，内置多 Provider 适配、流式响应、工具调用、上下文压缩与会话持久化能力。

## 特性

- **多 Provider 支持**：内置 10 种 LLM 服务商适配器（智谱、OpenAI、Anthropic、Gemini、DeepSeek、通义千问、Moonshot、Mistral、MiniMax、OpenRouter）+ 1 个 Mock 测试适配器，并支持 OpenAI 兼容协议接入任意服务商
- **流式响应**：基于 SSE 解析与双通道事件流（`mpsc` + `oneshot`），实时输出 LLM 生成内容
- **工具调用**：工具注册、权限预检与实时校验、并行执行与超时控制
- **上下文压缩**：提供四种压缩策略（None / Truncate / SlidingWindow / Summarize），避免上下文窗口溢出
- **会话持久化**：内存存储与文件存储两种方式，支持跨进程恢复对话
- **多源配置合并**：全局配置文件、项目配置文件、环境变量、CLI 参数四层配置按优先级自动合并
- **可取消**：通过 `CancelHandle` 在检查点优雅终止任务

## 架构

```
┌─────────────────────────────────────────────┐
│  CLI (ra-cli)                                │
│  参数解析 → 配置加载 → 日志初始化 → 运行    │
├─────────────────────────────────────────────┤
│  Config (ra-config)                          │
│  多源合并 → Provider 工厂 → 构建 Agent      │
├─────────────────────────────────────────────┤
│  Agent (ra-agent)                            │
│  运行循环 → 上下文压缩 → 事件分发           │
├──────────────┬──────────────┬───────────────┤
│ Provider     │ Tools        │ Session       │
│ (ra-provider)│ (ra-tools)   │ (ra-session)  │
│ HTTP 适配    │ 工具执行     │ 会话持久化    │
├──────────────┴──────────────┴───────────────┤
│  Core (ra-core)                              │
│  Trait 抽象 + 类型定义 + 流式处理            │
└─────────────────────────────────────────────┘
```

依赖方向自上而下：上层依赖定义在 `ra-core` 的 trait 抽象，下层实现通过 trait 注入，实现依赖反转。

### Crate 一览

| Crate | 说明 |
|-------|------|
| `ra-core` | 核心 trait 抽象与类型定义（消息、事件、Provider、Tools、Session、Stream） |
| `ra-provider` | LLM 服务商适配器实现与 Provider 管理器 |
| `ra-tools` | 工具管理器、权限校验、并发执行 |
| `ra-agent` | Agent 运行循环、上下文压缩、事件分发 |
| `ra-session` | 会话存储（内存 / 文件） |
| `ra-config` | 多源配置加载、Provider 工厂 |
| `ra-cli` | 命令行入口（`ribo-agent` 二进制） |

## 安装

### 环境要求

- Rust 工具链（stable，建议 1.85+，edition 2024）
- Cargo 包管理器

### 构建

```bash
# 克隆仓库
git clone https://gitee.com/zeronehost/ribo-pi-agent.git
cd ribo-pi-agent

# Debug 构建
cargo build

# Release 构建
cargo build --release
```

构建产物为 `ribo-agent` 可执行文件：

- Debug：`target/debug/ribo-agent`
- Release：`target/release/ribo-agent`

## 快速开始

### 1. 配置 API Key

通过环境变量配置（推荐）：

```bash
# Linux/macOS
export ZHIPU_API_KEY="your-api-key"

# Windows PowerShell
$env:ZHIPU_API_KEY="your-api-key"
```

### 2. 创建配置文件

在项目根目录创建 `.ribo/config.toml`：

```toml
[provider]
default = "zhipu"

[provider.adapters.zhipu]
type = "zhipu"
api_key_env = "ZHIPU_API_KEY"
default_model = "glm-4.5-flash"
```

### 3. 运行

```bash
# 单次问答
ribo-agent prompt "你好，请介绍一下自己"

# 交互模式（多轮对话）
ribo-agent prompt

# 指定会话 ID 恢复历史对话
ribo-agent prompt -s my-session

# 以长驻服务模式启动
ribo-agent serve

# 查看帮助
ribo-agent --help

# 查看版本
ribo-agent -V
```

## 命令行

CLI 采用「全局参数 + 子命令」结构，子命令不可省略。`-h/--help` 与 `-V/--version` 由 clap 自动提供。

### 子命令

| 子命令 | 别名 | 说明 |
|--------|------|------|
| `prompt [TEXT]` | `p` | 执行对话任务；省略 TEXT 进入交互 REPL 模式 |
| `serve` | `s` | 以长驻服务模式运行 |

### 常用全局参数

| 参数 | 说明 |
|------|------|
| `-p, --provider <NAME>` | 指定默认 Provider |
| `-m, --model <MODEL>` | 指定默认模型 |
| `-c, --config <PATH>` | 自定义配置文件路径 |
| `--ribo-home <PATH>` | 自定义 RIBO_HOME 路径 |
| `--max-turns <N>` | 最大对话轮数 |
| `--permission-mode <MODE>` | 权限模式（read-only / confirm-mutations / trusted-workspace / plan） |
| `--session-store-type <TYPE>` | 会话存储类型（memory / file） |
| `--stream` / `--no-stream` | 启用 / 禁用流式输出 |
| `--log-level <LEVEL>` | 日志级别（trace/debug/info/warn/error/off，默认 info） |
| `--log-dir <PATH>` | 日志文件保存目录（启用文件日志，每日轮转） |
| `--log-file-limit <N>` | 日志文件保留数量上限（默认 7，0 不限制） |
| `--show-config` | 打印最终生效的配置后退出 |

更多参数说明详见 [命令行文档](./internals/docs/guide/cli.md)。

## 支持的 Provider

| Provider | type 值 | 协议 |
|----------|---------|------|
| 智谱 AI | `zhipu` | OpenAI 兼容 |
| OpenAI | `openai` | OpenAI 兼容 |
| Anthropic Claude | `anthropic` | 独立 Messages API |
| Google Gemini | `gemini` | 独立 generateContent API |
| DeepSeek | `deepseek` | OpenAI 兼容 |
| 通义千问 | `qwen` | OpenAI 兼容 |
| Moonshot 月之暗面 | `moonshot` | OpenAI 兼容 |
| Mistral | `mistral` | OpenAI 兼容 |
| MiniMax | `minimax` | OpenAI 兼容 |
| OpenRouter | `openrouter` | OpenAI 兼容 |
| Mock（测试用） | `mock` | — |

## 文档

完整使用指南位于 [`internals/docs/guide`](./internals/docs/guide/README.md)，包含：

- [快速开始](./internals/docs/guide/getting-started.md)
- [命令行参数](./internals/docs/guide/cli.md)
- [配置体系](./internals/docs/guide/config.md)
- [Provider 配置](./internals/docs/guide/providers.md)
- [运行模式](./internals/docs/guide/modes.md)
- [会话管理](./internals/docs/guide/session.md)
- [上下文压缩](./internals/docs/guide/compression.md)
- [工具系统](./internals/docs/guide/tools.md)
- [日志系统](./internals/docs/guide/logging.md)
- [Agent 运行机制](./internals/docs/guide/agent-runtime.md)
- [完整配置示例](./internals/docs/guide/examples.md)

事件流架构设计文档：[event_stream.md](./internals/docs/design/event_stream.md)

## 开发

```bash
# 运行测试
cargo test --workspace

# 代码检查
cargo clippy --all-targets --workspace -- -D warnings

# 格式化
cargo fmt --all

# 格式检查
cargo fmt --all -- --check
```

## 贡献

1. Fork 本仓库
2. 新建 `feat_xxx` 分支
3. 提交代码（遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范）
4. 新建 Pull Request

## 许可证

[木兰宽松许可证，第2版（MulanPSL-2.0）](./LICENSE)