pacifio/cersei
GitHub: pacifio/cersei
一个用于构建可嵌入应用的编程 Agent 的 Rust SDK，提供完整的工具执行、记忆管理、多 Provider 支持等核心能力。
Stars: 158 | Forks: 42
# Cersei
构建编程 Agent 的完整 Rust SDK。
Cersei 为您提供了生产级编程 Agent 的所有构建模块 —— 工具执行、LLM 流式传输、Sub-Agent 编排、持久化 Memory、Skills、MCP 集成 —— 均以可组合的库函数形式提供。构建 Claude Code 的替代品、将 Agent 嵌入您的应用程序，或创造全新的东西。
```
use cersei::prelude::*;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let output = Agent::builder()
.provider(Anthropic::from_env()?)
.tools(cersei::tools::coding())
.permission_policy(AllowAll)
.run_with("Fix the failing tests in src/")
.await?;
println!("{}", output.text());
Ok(())
}
```
**MIT License** | 由 [Adib Mohsin](https://github.com/pacifio) 构建 | [文档](https://cersei.pacifio.dev/docs) | [GitHub](https://github.com/pacifio/cersei)
## 为什么选择 Cersei
| | Claude Code | OpenCode | **Cersei SDK** | **Abstract CLI** |
|---|---|---|---|---|
| 形态 | CLI 应用 | CLI 应用 | **库** | **CLI 应用** |
| 可嵌入 | 否 | 否 | **是** | 否 (使用 SDK) |
| Provider | 仅 Anthropic | 多 Provider | **多 Provider** | **多 Provider** |
| 语言 | TypeScript | TypeScript | **Rust** | **Rust** |
| 自定义工具 | 插件 | 插件 | **`impl Tool` / `#[derive(Tool)]`** | 通过 SDK |
| 启动时间 | ~269ms | ~300ms | N/A (库) | **~34ms** |
| 二进制大小 / RSS | 174MB / 330MB | — | N/A | **5.8MB / 4.9MB** |
| Memory | 基于文件 | SQLite | **File + Graph** | **File + Graph** |
| Skills | `.claude/commands/` | `.claude/skills/` | **两种格式均支持** | **两种格式均支持** |
Cersei 基于 Claude Code 的架构构建（逆向工程的 Rust 移植版本），旨在让任何人都能通过库调用的方式，构建 Claude Code、OpenCode 或任何编程 Agent 的完整替代品。
## Abstract — CLI
**Abstract** 是一个基于 Cersei 构建的完整 CLI 编程 Agent。单一二进制文件，零运行时依赖，默认启用 Graph Memory。
```
# 安装
cargo install --path crates/abstract-cli
# 使用
abstract # Interactive REPL
abstract "fix the failing tests" # Single-shot
abstract --resume # Resume last session
abstract --model opus --max # Opus with max thinking
abstract --no-permissions --json # CI mode with NDJSON output
```
### Abstract vs Claude Code
所有数据均来自 `run_tool_bench.sh --full`。
| 指标 | Abstract | Claude Code | 胜者 |
|--------|----------|-------------|--------|
| 启动 (热启动) | **32ms** | 266ms | Abstract (8.2倍) |
| 二进制大小 | **6.0 MB** | 174 MB | Abstract (29倍) |
| 内存 (RSS) | **4.9 MB** | 333 MB | Abstract (68倍) |
| Tool 分发 | **0.02-17ms** | 5-265ms+ | Abstract |
| Memory 召回 | **98us** (graph) | 7,545ms (LLM) | Abstract (77,000倍) |
| Memory 写入 | **30us** (graph) | 20,687ms (agent) | Abstract (689,000倍) |
| MEMORY.md 加载 | **9.6us** | 17.1ms | Abstract (1,781倍) |
| 顺序吞吐量 | **906ms/req** | 12,079ms/req | Abstract (13.3倍) |
| System Prompt Token | **~2,200** | ~8,000+ | Abstract (减少 3.6倍) |
| 用于召回的 LLM 调用 | **不需要** | 需要 (Sonnet) | Abstract |
完整基准测试：[`crates/abstract-cli/benchmarks/REPORT.md`](crates/abstract-cli/benchmarks/REPORT.md)
### 功能特性
- 34 个内置工具（文件、Shell、Web、规划、编排、调度）
- 多 Provider：Anthropic + OpenAI（+ Ollama, Azure, vLLM）
- Graph Memory (Grafeo) 默认开启
- 自动压缩、自动 Dream、Effort 级别（Low/Medium/High/Max）
- MCP Server 支持
- Session 持久化（兼容 Claude Code 的 JSONL）
- 交互式权限与 Session 缓存
- 12 个斜杠命令（`/help`, `/commit`, `/review`, `/memory`, `/model`, `/diff` 等）
- 流式 Markdown 渲染，支持语法高亮
- TOML 配置：`~/.abstract/config.toml` + `.abstract/config.toml`
- 用于管道操作的 JSON 输出模式（`--json`）
## 安装
```
[dependencies]
cersei = { git = "https://github.com/pacifio/cersei" }
tokio = { version = "1", features = ["full"] }
anyhow = "1"
```
用于 Graph 支持的 Memory（可选）：
```
cersei-memory = { git = "https://github.com/pacifio/cersei", features = ["graph"] }
```
## 架构
```
cersei Facade crate — use cersei::prelude::*;
cersei-types Provider-agnostic messages, errors, stream events
cersei-provider Provider trait + Anthropic/OpenAI implementations
cersei-tools 30+ tools, permissions, bash classifier, skills, git utils
cersei-tools-derive #[derive(Tool)] proc macro
cersei-agent Agent builder, agentic loop, compact, coordinator, effort
cersei-memory Memory trait, memdir, CLAUDE.md, sessions, Grafeo graph
cersei-hooks Hook/middleware system
cersei-mcp MCP client (JSON-RPC 2.0, stdio transport)
abstract-cli CLI coding agent ("abstract") — REPL, commands, config, permissions
```
## 核心概念
### Provider
任何 LLM 后端。内置：Anthropic（支持 OAuth）、OpenAI（兼容 Ollama, Azure, vLLM）。
```
Agent::builder().provider(Anthropic::from_env()?) // Anthropic API key
Agent::builder().provider(OpenAi::builder()
.base_url("http://localhost:11434/v1") // Ollama
.model("llama3.1:70b").api_key("ollama").build()?)
Agent::builder().provider(MyCustomProvider) // impl Provider
```
### Tools (30+)
编程 Agent 所需的每一个工具，已组织成集合：
```
cersei::tools::all() // 30+ tools
cersei::tools::coding() // filesystem + shell + web
cersei::tools::filesystem() // Read, Write, Edit, Glob, Grep, NotebookEdit
cersei::tools::shell() // Bash, PowerShell
cersei::tools::web() // WebFetch, WebSearch
cersei::tools::planning() // EnterPlanMode, ExitPlanMode, TodoWrite
cersei::tools::scheduling() // CronCreate/List/Delete, Sleep, RemoteTrigger
cersei::tools::orchestration() // SendMessage, Tasks (6 tools), Worktree
```
10 行代码实现自定义工具：
```
#[derive(Tool)]
#[tool(name = "search", description = "Search docs", permission = "read_only")]
struct SearchTool;
#[async_trait]
impl ToolExecute for SearchTool {
type Input = SearchInput; // derives Deserialize + JsonSchema
async fn run(&self, input: SearchInput, ctx: &ToolContext) -> ToolResult {
ToolResult::success(format!("Found: {}", input.query))
}
}
```
### Sub-Agent 编排
生成并行 Worker、协调任务、在 Agent 之间传递消息：
```
// AgentTool — model spawns sub-agents autonomously
Agent::builder()
.tool(AgentTool::new(|| Box::new(Anthropic::from_env()?), cersei::tools::coding()))
// Coordinator mode — orchestrate parallel workers
Agent::builder()
.tools(cersei::tools::all()) // includes Agent, Tasks, SendMessage
// Workers get filtered tools (no Agent — prevents recursion)
// Task system
// TaskCreate → TaskUpdate → TaskGet → TaskList → TaskStop → TaskOutput
```
### Memory (三层)
```
use cersei::memory::manager::MemoryManager;
let mm = MemoryManager::new(project_root)
.with_graph(Path::new("./memory.grafeo"))?; // optional graph layer
// Tier 1: Flat files (~/.claude/projects//memory/)
let metas = mm.scan(); // scan .md files with frontmatter
let content = mm.build_context(); // build system prompt injection
// Tier 2: CLAUDE.md hierarchy (managed > user > project > local)
// Automatically merged into build_context()
// Tier 3: Graph memory (Grafeo, optional)
let id = mm.store_memory("User prefers Rust", MemoryType::User, 0.9)?;
mm.tag_memory(&id, "preferences");
let results = mm.recall("Rust", 5); // graph query with fallback to text match
// Session persistence (JSONL, append-only, tombstone soft-delete)
mm.write_user_message("session-1", Message::user("Hello"))?;
let messages = mm.load_session_messages("session-1")?;
```
### Skills (兼容 Claude Code + OpenCode)
```
// Auto-discovers skills from:
// .claude/commands/*.md (Claude Code format)
// .claude/skills/*/SKILL.md (OpenCode format)
// ~/.claude/commands/*.md (user-level)
// Bundled skills (simplify, debug, commit, verify, stuck, remember, loop)
let skill_tool = SkillTool::new().with_project_root(".");
// skill="list" → lists all available skills
// skill="debug" args="tests are flaky" → expands $ARGUMENTS template
```
### 实时事件
三种观察机制：
```
// 1. Callback
Agent::builder().on_event(|e| match e {
AgentEvent::TextDelta(t) => print!("{}", t),
AgentEvent::ToolStart { name, .. } => eprintln!("[{}]", name),
_ => {}
})
// 2. Broadcast (multi-consumer)
let agent = Agent::builder().enable_broadcast(256).build()?;
let mut rx = agent.subscribe().unwrap();
tokio::spawn(async move { while let Ok(e) = rx.recv().await { /* ... */ } });
// 3. Stream (bidirectional control)
let mut stream = agent.run_stream("Deploy");
while let Some(e) = stream.next().await {
if let AgentEvent::PermissionRequired(req) = e {
stream.respond_permission(req.id, PermissionDecision::Allow);
}
}
```
### Context 管理
```
Agent::builder()
.auto_compact(true) // summarize old messages at 90% context usage
.compact_threshold(0.9) // trigger threshold
.tool_result_budget(50_000) // truncate oldest tool results above 50K chars
.thinking_budget(8192) // extended thinking tokens
.effort(EffortLevel::High) // Low/Medium/High/Max
```
### MCP (Model Context Protocol)
```
let mcp = McpManager::connect(&[
McpServerConfig::stdio("db", "npx", &["-y", "@my/db-mcp"]),
McpServerConfig::sse("docs", "https://mcp.example.com"),
]).await?;
Agent::builder().tools(mcp.tool_definitions().await)
```
### OAuth (Anthropic 原生)
```
// Opens browser, PKCE flow, token storage, refresh
cargo run --example oauth_login
```
## Agent Builder — 完整 API
```
Agent::builder()
// Provider (required)
.provider(Anthropic::from_env()?)
// Tools
.tool(MyTool)
.tools(cersei::tools::coding())
// Model & generation
.model("claude-sonnet-4-6")
.max_turns(10)
.max_tokens(16384)
.temperature(0.7)
.thinking_budget(8192)
// Prompt
.system_prompt("You are a helpful assistant.")
.append_system_prompt("Extra context.")
// Environment
.working_dir("./my-project")
.permission_policy(AllowAll) // or AllowReadOnly, DenyAll, RuleBased, Interactive
// Memory
.memory(JsonlMemory::new("./sessions"))
.session_id("my-session")
// Hooks & events
.hook(CostGuard { max_usd: 5.0 })
.on_event(|e| { /* ... */ })
.enable_broadcast(256)
.reporter(ConsoleReporter { verbose: true })
// Context management
.auto_compact(true)
.compact_threshold(0.9)
.tool_result_budget(50_000)
// Execute
.build()? // -> Agent
.run_with("Fix the tests") // -> AgentOutput (shorthand)
```
## 基准测试
在 Apple Silicon 上测量，Release 构建，100 次迭代，3 次预热。
### Tool I/O
| Tool | 平均 | 最小 | 最大 |
|------|-----|-----|-----|
| Edit | 0.04ms | 0.02ms | 0.05ms |
| Glob | 0.05ms | 0.05ms | 0.07ms |
| Write | 0.09ms | 0.07ms | 0.11ms |
| Read | 0.09ms | 0.08ms | 0.11ms |
| Grep | 5.85ms | 5.34ms | 8.51ms |
| Bash | 15.64ms | 14.50ms | 16.19ms |
### vs Claude Code CLI
| 指标 | Cersei (SDK) | Claude Code (CLI) | 备注 |
|--------|-------------|-------------------|-------|
| Tool 分发 (Read) | 0.09ms | ~5-15ms (估算) | 进程内 vs Node.js fs |
| CLI 启动 | N/A (库) | 269ms | Claude `--version` 热启动平均值 |
| Sub-Agent 生成 | ~1ms (进程内) | ~300ms (fork) | Agent Tool 开销 |
如需同类 CLI 对比，请参阅 [Abstract CLI 基准测试](crates/abstract-cli/benchmarks/REPORT.md)。
### Memory I/O
| 操作 | Abstract (Cersei) | Claude Code (实测) | 比率 |
|-----------|------------------|----------------------|-------|
| 扫描 100 个文件 | **1.2ms** | 26.6ms (`find`) | 22倍 |
| 加载 MEMORY.md | **9.6μs** | 17.1ms | 1,781倍 |
| Memory 召回 | **98μs** | 7,545ms (LLM 调用) | 77,000倍 |
| Memory 召回 | **1.3ms** | 17.5ms (`grep`) | 13倍 |
| Session 写入 | **27μs/条** | N/A | — |
| Session 加载 (100) | **268μs** | N/A | — |
| Graph 存储 | **30μs/节点** | N/A (无 Graph) | — |
| Topic 查询 | **77μs** | N/A (无 Graph) | — |
### 运行基准测试
```
# Tool I/O 基准测试
cargo run --example benchmark_io --release
# Memory 架构基准测试 (graph ON vs OFF + Claude Code 对比)
cargo run --release -p abstract-cli --example memory_bench
# 完整 CLI 对比 (abstract vs claude, 所有类别)
./run_tool_bench.sh --iterations 20 --full
# 独立基准测试套件 (带 Markdown 输出)
cd examples/benchmark && cargo run --release
```
## 压力测试
```
cargo run --example stress_core_infrastructure --release # system prompt, compact, context, bash classifier
cargo run --example stress_tools --release # all 30+ tools, registry, performance
cargo run --example stress_orchestration --release # sub-agents, coordinator, tasks, messaging
cargo run --example stress_skills --release # bundled + disk skills, Claude Code + OpenCode format
cargo run --example stress_memory --release # memdir, CLAUDE.md, sessions, extraction, auto-dream
```
## 示例
| 示例 | 描述 |
|---------|-------------|
| [`simple_agent`](examples/simple_agent.rs) | 3 行代码实现最小化 Agent |
| [`custom_tools`](examples/custom_tools.rs) | 定义并注册自定义 Tool |
| [`streaming_events`](examples/streaming_events.rs) | 带彩色输出的实时 `run_stream()` |
| [`multi_listener`](examples/multi_listener.rs) | 具有多个消费者的广播 Channel |
| [`resumable_session`](examples/resumable_session.rs) | 使用 `JsonlMemory` 持久化并恢复 |
| [`custom_provider`](examples/custom_provider.rs) | Echo Provider + 兼容 OpenAI 的 Endpoint |
| [`hooks_middleware`](examples/hooks_middleware.rs) | 成本守卫 + 审计日志 + Tool 拦截器 |
| [`benchmark_io`](examples/benchmark_io.rs) | 完整 I/O 基准测试套件 |
| [`usage_report`](examples/usage_report.rs) | Token/成本跟踪和账单估算 |
| [`coding_agent`](examples/coding_agent.rs) | 构建 Python Todo CLI（端到端） |
| [`oauth_login`](examples/oauth_login.rs) | Anthropic OAuth PKCE 登录流程 |
```
cargo run --example simple_agent --release
```
## 测试套件
```
# 运行所有 160 个单元测试
cargo test --workspace
# 使用 graph memory 运行 (需要 grafeo)
cargo test --workspace --features graph
# 运行特定 crate
cargo test -p cersei-tools
cargo test -p cersei-agent
cargo test -p cersei-memory
cargo test -p cersei-mcp
```
**160 个单元测试** | **262 项压力检查** | **0 次失败** | **零 I/O 回归**
## 扩展点
| 内容 | 方式 | 示例 |
|------|-----|---------|
| 自定义 Provider | `impl Provider` | Local LLM, Azure, Bedrock |
| 自定义 Tool | `#[derive(Tool)]` 或 `impl Tool` | 数据库查询、部署、搜索 |
| 自定义权限 | `impl PermissionPolicy` | RBAC, OAuth-scoped |
| 自定义 Memory | `impl Memory` | PostgreSQL, Redis, S3 |
| 自定义 Hook | `impl Hook` | 成本控制、审计日志 |
| 自定义 Reporter | `impl Reporter` | Dashboard, WebSocket Relay |
| MCP Server | 通过 Builder 配置 `McpServerConfig` | 任何兼容 MCP 的 Server |
| Skills | `.claude/commands/*.md` | 自定义 Prompt 模板 |
| Graph Memory | `features = ["graph"]` | Grafeo 关系跟踪 |
## 文档
**[cersei.pacifio.dev/docs](https://cersei.pacifio.dev/docs)** — 完整文档，包含 API 参考、架构、Cookbook、基准测试和 llms.txt 支持。
| 章节 | 内容 |
|---------|---------|
| [快速开始](https://cersei.pacifio.dev/docs/quick-start) | 10 行代码实现第一个 Agent |
| [API 参考](https://cersei.pacifio.dev/docs/api-agent) | Agent, Provider, Tools, Memory, Hooks, MCP |
| [架构](https://cersei.pacifio.dev/docs/architecture) | Crate Map、数据流、设计原则 |
| [Cookbook](https://cersei.pacifio.dev/docs/cookbook-custom-tools) | 自定义 Tool、部署、嵌入 |
| [Abstract CLI](https://cersei.pacifio.dev/docs/abstract) | 基于 Cersei 构建的参考 CLI |
| [基准测试](https://cersei.pacifio.dev/docs/bench-vs-claude-code) | vs Claude Code vs Codex |
## 许可证
MIT License
Copyright (c) 2025 Adib Mohsin
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
标签：Abstract CLI, AI编程助手, Anthropic API, Claude Code替代, LLM应用开发, LLM流式处理, MCP集成, Petitpotam, Rust SDK, Rust库, 企业级Agent, 低延迟, 函数调用, 可视化界面, 图记忆, 多模型支持, 威胁情报, 子代理编排, 工具执行, 开发者工具, 编码智能体, 自动化代码修复, 通知系统