内容
# Brainwires 框架
[](https://github.com/Brainwires/brainwires-framework/actions/workflows/ci.yml)
[](https://crates.io/crates/brainwires)
[](https://docs.rs/brainwires)
[](#testing)
[](#)
[](https://github.com/Brainwires/brainwires-framework/blob/main/LICENSE-MIT)
[](https://www.rust-lang.org/)
一个用于构建 AI 代理的模块化 Rust 框架，具有多提供者支持、工具编排、MCP 集成和可插拔的代理网络。
**警告：** 这是一个早期阶段的项目，正在积极开发中。预计会有破坏性更改和快速迭代，以构建 1.0 版本。
## 概述
Brainwires 框架是一个由 32 个框架 crate 和 18 个额外 crate（包括 7 个 crate 的 `brainclaw` 集）组成的 workspace，提供构建、训练、部署和协调 AI 代理所需的一切。每个框架 crate 都可以独立发布到 crates.io 并单独使用，但它们通过 `brainwires` facade crate 组合在一起，提供一个包含所有功能的体验。
**[完整功能列表](FEATURES.md)** | **关键功能：**
- **多提供者 AI** — Anthropic、OpenAI、Google、Ollama 和本地 LLM，支持统一的 `Provider` 特质
- **代理编排** — 分层任务分解、多代理协调、文件锁、MDAP 投票
- **MCP 协议** — 通过 `rmcp` 完整的客户端和服务端支持，暴露代理作为 MCP 工具
- **代理网络** — 5 层协议栈（IPC、TCP、A2A、Pub/Sub）支持可插拔的传输、路由和发现
- **训练管道** — 云端微调（6 个提供者）和本地 LoRA/QLoRA/DoRA 通过 Burn
- **RAG 和代码搜索** — AST 感知分块、混合向量 + 关键词搜索、Git 感知索引
- **音频** — 语音转文本、文本转语音、硬件捕获/播放
- **安全** — 加密存储（ChaCha20-Poly1305）、权限策略、内容信任标记
## Crate 地图
```text
┌─────────────────────────────────────────────────────────────────┐
│ brainwires │
│ （facade crate） │
│ │
│ ┌────────────┐ ┌─────────────┐ ┌────────────┐ ┌─────────────┐ │
│ │ agent │ │ provider │ │ storage │ │ mcp-client │ │
│ │ tool-runtime│ │ speech │ │ stores │ │ mcp-server │ │
│ │tool-builtins│ │ │ │ memory │ │ network │ │
│ └─────┬──────┘ └──────┬──────┘ └──────┬─────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ └───────────────┴───────────────┴──────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ core │ │
│ │ permission │ │
│ │ call-policy │ │
│ └─────────────┘ │
│ │
│ ┌────────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ knowledge │ │ reasoning │ │telemetry │ │ hardware │ │
│ │ rag │ │ sandbox │ │ a2a │ │ finetune │ │
│ │ prompting │ │ │ │ │ │finetune-local│ │
│ └────────────┘ └─────────────┘ └──────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 框架 Crate
| Crate | 描述 |
|-------|-------------|
| [**brainwires**](crates/brainwires/README.md) | Facade crate — 将所有其他框架 crate 在功能标志后重新导出 |
| [**brainwires-core**](crates/brainwires-core/README.md) | 所有 crate 共享的核心类型、特质和错误处理 |
| [**brainwires-provider**](crates/brainwires-provider/README.md) | 多提供者 LLM 接口（Anthropic、OpenAI、Google、Ollama、Bedrock、Vertex AI、本地 llama.cpp / Candle） |
| [**brainwires-provider-speech**](crates/brainwires-provider-speech/README.md) | 语音（TTS / STT）提供者（Azure、Cartesia、Deepgram、ElevenLabs、Fish、Google、Murf、浏览器 web-speech） |
| [**brainwires-tool-runtime**](crates/brainwires-tool-runtime/README.md) | 工具框架 — `ToolExecutor`、`ToolRegistry`、验证、智能路由器、沙盒/编排器/会话/oauth/openapi |
| [**brainwires-tool-builtins**](crates/brainwires-tool-builtins/README.md) | 内置工具实现：bash、file_ops、git、web、search、code_exec、browser、email、calendar、system、semantic_search |
| [**brainwires-agent**](crates/brainwires-agent/README.md) | 代理协调原语 + 多代理模式 — 通信、锁、队列、git 协调、合同网络、Saga、乐观并发、市场分配、工作流图 |
| [**brainwires-inference**](crates/brainwires-inference/README.md) | LLM 驱动的工作马 — `ChatAgent`、`TaskAgent`、规划器/裁判/验证器助手、循环编排器、验证循环、摘要、系统提示注册 |
| [**brainwires-mdap**](crates/brainwires-mdap/README.md) | 多维自适应规划（MAKER 投票框架） |
| [**brainwires-seal**](crates/brainwires-seal/README.md) | 自我演化代理学习 — 核心参考查询、学习模式存储、反射 |
| [**brainwires-skills**](crates/brainwires-skills/README.md) | SKILL.md 技能系统 — 清单解析、注册、智能路由、沙盒执行 |
| [**brainwires-eval**](crates/brainwires-eval/README.md) | 评估工具 — 固定装置、回归套件、稳定性测试、对抗性案例、NDCG / MRR / precision@k |
| [**brainwires-knowledge**](crates/brainwires-knowledge/README.md) | 知识层 — BKS / PKS、BrainClient、实体图 |
| [**brainwires-rag**](crates/brainwires-rag/README.md) | 代码库索引 + 混合检索（向量 + BM25）、AST 感知分块通过 tree-sitter、Git 历史搜索 |
| [**brainwires-prompting**](crates/brainwires-prompting/README.md) | 自适应提示 — 技术库、K-means 任务聚类、BKS/PKS 感知生成器、SEAL 反馈钩子 |
| [**brainwires-storage**](crates/brainwires-storage/README.md) | 衬底 — `StorageBackend` 特质、9 个后端、嵌入、BM25 关键词搜索、文件上下文原语 |
| [**brainwires-stores**](crates/brainwires-stores/README.md) | 模式 + CRUD 用于有偏见的最小存储集：会话、对话、任务、计划、锁、图像、模板 + 分层模式存储 |
| [**brainwires-memory**](crates/brainwires-memory/README.md) | 分层内存 **编排** — `TieredMemory` 多因素自适应搜索 + 离线 `dream` 巩固引擎。基于 `brainwires-stores`。 |
| [**brainwires-permission**](crates/brainwires-permission/README.md) | 工具执行的权限策略（自动、询问、拒绝） |
| [**brainwires-mcp-client**](crates/brainwires-mcp-client/README.md) | MCP 客户端 — 连接到外部 MCP 服务器并使用他们的工具 |
| [**brainwires-mcp-server**](crates/brainwires-mcp-server/README.md) | MCP 服务器框架，具有可组合的中间件；`http` 功能添加无状态 HTTP+SSE 传输、服务器卡（SEP-1649）、RFC9728 和任务（SEP-1686）；`oauth` 功能添加 JWT 验证中间件 |
| [**brainwires-network**](crates/brainwires-network/README.md) | 代理网络 — IPC、远程桥、网格、WebRTC、LAN 发现 |
| [**brainwires-reasoning**](crates/brainwires-reasoning/README.md) | 推理评分器 — 复杂度、实体增强器、相关性、检索分类器、路由器、策略选择器、摘要器、验证器 |
| [**brainwires-call-policy**](crates/brainwires-call-policy/README.md) | 出站提供者调用的策略 — 重试和回退、断路器、预算上限、响应缓存、错误分类 |
| [**brainwires-hardware**](crates/brainwires-hardware/README.md) | 硬件 I/O — 音频（STT/TTS）、GPIO、蓝牙、摄像头/网络摄像头、原始 USB |
| [**brainwires-finetune**](crates/brainwires-finetune/README.md) | 云端微调 API（OpenAI、Anthropic、Together、Fireworks、Anyscale、Bedrock、Vertex AI）+ 数据集管道。本地 PEFT（LoRA / QLoRA / DoRA）、从头开始训练和纯-wgpu Gemma 4 引擎都生活在 sibling `rullama` 工作空间中。 |
| [**brainwires-telemetry**](crates/brainwires-telemetry/README.md) | OutcomeMetrics、Prometheus 导出、异常检测、计费钩子特质 |
| [**brainwires-a2a**](crates/brainwires-a2a/README.md) | 代理到代理协议 — JSON-RPC 2.0、HTTP/REST 和 gRPC 绑定 |
| [**brainwires-sandbox**](crates/brainwires-sandbox/README.md) | 容器支持的沙盒执行器，用于不受信任的工具代码 |
| [**brainwires-sandbox-proxy**](crates/brainwires-sandbox-proxy/README.md) | 进程外沙盒执行器代理，用于隔离不受信任的代码 |
### 额外
| Crate | 描述 |
|-------|-------------|
| [**brainwires-proxy**](extras/brainwires-proxy/README.md) | AI API 请求路由的 HTTP 代理 |
| [**brainwires-brain-server**](extras/brainwires-brain-server/README.md) | MCP 服务器二进制文件，暴露 `brainwires-knowledge::knowledge` 子系统（BKS/PKS、思想、实体图） |
| [**brainwires-rag-server**](extras/brainwires-rag-server/README.md) | MCP 服务器二进制文件，暴露 `brainwires-knowledge::rag` 子系统（代码库索引 + 混合搜索） |
| [**agent-chat**](extras/agent-chat/README.md) | 简化的 AI 聊天客户端，具有 TUI 和纯模式 |
| [**reload-daemon**](extras/reload-daemon/README.md) | 用于杀死和重启 AI 编码客户端的 MCP 服务器 |
| [**audio-demo-ffi**](extras/audio-demo-ffi/README.md) | UniFFI 绑定（cdylib）将 brainwires-hardware（音频）暴露给 C#、Kotlin、Swift、Python |
| [**audio-demo**](extras/audio-demo/README.md) | 跨平台 Avalonia GUI，用于所有音频提供者的 TTS/STT 演示 |
| [**brainclaw**](extras/brainclaw/daemon/README.md) | 自托管的个人 AI 助手守护进程 — 多提供者、每个用户会话、安全网关 |
| [**brainwires-gateway**](extras/brainclaw/gateway/README.md) | WebSocket/HTTP 通道中心 — 将通道适配器路由到 AI 代理会话 |
| [**brainwires-discord-channel**](extras/brainclaw/mcp-discord/README.md) | Discord 通道适配器 — 参考 `Channel` 特质实现，可选的 MCP 服务器模式 |
| [**brainwires-telegram-channel**](extras/brainclaw/mcp-telegram/README.md) | Telegram 通道适配器 — teloxide-based，可选的 MCP 服务器模式 |
| [**brainwires-slack-channel**](extras/brainclaw/mcp-slack/README.md) | Slack 通道适配器 — Socket 模式（无公共 URL），可选的 MCP 服务器模式 |
| [**brainwires-skill-registry**](extras/brainclaw/mcp-skill-registry/README.md) | 技能注册 HTTP 服务器 — SQLite FTS5、发布/搜索/下载端点 |
| [**brainclaw-mcp-github**](extras/brainclaw/mcp-github/README.md) | GitHub 通道适配器 — webhook 接收器、REST API、MCP 服务器模式 |
| [**brainwires-memory-server**](extras/brainwires-memory-server/README.md) | Mem0 兼容的内存 REST API 支持 Brainwires 知识 |
| [**claude-brain**](extras/claude-brain/README.md) | Brainwires 上下文管理用于 Claude Code — 持久上下文压缩 |
| [**brainwires-cli**](extras/brainwires-cli/README.md) | AI 驱动的 agentic CLI 工具，用于自主编码协助 |
| [**brainwires-issues**](extras/brainwires-issues/README.md) | MCP-native 问题跟踪服务器 |
| [**brainwires-scheduler**](extras/brainwires-scheduler/README.md) | 用于 cron 调度的 MCP 服务器 |
| [**brainwires-autonomy**](extras/brainwires-autonomy/README.md) | 自主代理人协议 — JSON-RPC 2.0、HTTP/REST 和 gRPC 绑定 |
| [**brainwires-wasm**](extras/brainwires-wasm/README.md) | WASM 浏览器绑定 |
| [**brainwires-billing**](extras/brainwires-billing/README.md) | 代理遥测的计费和成本核算钩子 |
| [**brainwires-docs**](extras/brainwires-docs/README.md) | 文档工具和参考站点生成 |
| [**voice-assistant**](extras/voice-assistant/README.md) | 使用 `brainwires-hardware` 管道的端到端语音助手二进制文件 |
### 工作空间布局
- **`crates/`** — 框架。连贯的、可独立发布的库。
- **`extras/`** — 消费框架的应用和库：二进制文件、演示、MCP 服务器和集成助手。
**允许的依赖箭头：** `crates/ → crates/` 和 `extras/ → crates/`。
**禁止：** `crates/ → extras/`（框架不能依赖其消费者）和 `extras/ → extras/`（extras 是平等且独立的，而不是层次结构）。如果一个 `extras/` 库开始被另一个 `extras/` 条目依赖，这是一个信号，表明它属于 `crates/`。
执行：`cargo xtask lint-deps` 遍历每个 `Cargo.toml` 并拒绝禁止的箭头。参见 [`docs/adr/ADR-0004-framework-extras-boundary.md`](docs/adr/ADR-0004-framework-extras-boundary.md) 获取理由。
已弃用的目录 `deprecated/` 包含已合并或已退休的历史 crate；活动工作空间中没有任何内容依赖于它。
## 快速入门
### 要求
- **Rust 1.91+** （版本 2024）
- **Cargo** （随 Rust 随附）
> **注意：** 该框架使用 `edition = "2024"`，需要 Rust 1.91 或更新版本。请使用 `rustc --version` 检查您的版本，并在需要时使用 `rustup update stable` 更新。
### 使用 Facade Crate
使用 `brainwires` facade crate 的最简单方法是，它在功能标志后重新导出所有内容：
```toml
[dependencies]
brainwires = "0.11" # 默认：工具 + 代理
```
仅启用您需要的功能：
```toml
[dependencies]
brainwires = { version = "0.11", features = ["provider", "rag"] }
```
### 使用独立 Crate
每个 crate 都可以独立发布和使用：
```toml
[dependencies]
brainwires-core = "0.11"
brainwires-provider = "0.11"
brainwires-agent = "0.11"
```
### 最小示例
```rust
use brainwires::prelude::*;
use brainwires::providers::{ChatProviderFactory, ProviderConfig, ProviderType};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// 通过工厂创建提供者
let config = ProviderConfig {
provider: ProviderType::Anthropic,
model: "claude-sonnet-4-6".into(),
api_key: Some("your-api-key".into()),
base_url: None,
};
let provider = ChatProviderFactory::create(&config)?;
// 发送消息
let messages = vec![Message::user("Hello, what can you do?")];
let options = ChatOptions::default();
let response = provider.chat(&messages, None, &options).await?;
println!("{}", response.message.content);
Ok(())
}
```
## 功能标志
`brainwires` facade crate 暴露了对应于每个子 crate 的功能标志：
| 功能 | 默认 | 启用功能 |
|---------|---------|-----------------|
| `core` | 始终 | 核心类型和特质（非功能门控） |
| `tools` | 是 | 工具定义、执行和解释器 (`brainwires-tool-runtime` + `brainwires-tool-builtins`) |
| `agents` | 是 | 多代理编排、通信中心、文件/资源锁 (`brainwires-agent`) |
| `inference` | 是 | 由 LLM 驱动的工作马 — ChatAgent、PlannerAgent、JudgeAgent、TaskAgent、CycleOrchestrator (`brainwires-inference`) |
| `providers` | 否 | AI 提供者集成 |
| `storage` | 否 | 向量存储和语义搜索 |
| `mcp` | 否 | MCP 客户端支持 |
| `agent-network` | 否 | 代理网络 — IPC、远程桥、通道、5 层协议栈 (`brainwires-network`) |
| `mcp-server-framework` | 否 | MCP 服务器构建块（McpServer、McpHandler、中间件管道） |
| `rag` | 否 | 带有代码搜索的 RAG 引擎 |
| `audio` | 否 | 音频捕获、STT、TTS |
| `training` | 否 | 云端微调（本地 PEFT 位于 `rullama-finetune`） |
| `datasets` | 否 | 训练数据管道（委托给 `brainwires-finetune`） |
| `telemetry` | 否 | OutcomeMetrics、Prometheus 导出、计费钩子 |
| `reasoning` | 否 | 推理策略（从核心导出） |
| `mesh` | 否 | 网格网络（通过 `agent-network` 网格功能） |
| `a2a` | 否 | 代理到代理协议 |
| `wasm` | 否 | WASM 核心绑定 |
| `researcher` | 否 | 包：提供者 + 代理 + 存储 + rag + 训练 + 数据集 |
## 构建
```bash
# 构建所有 crate（调试）
cargo build
# 构建所有 crate（发布）
cargo build --release
# 构建特定 crate
cargo build -p brainwires-agent
# 运行所有测试
cargo test
# 运行特定 crate 的测试
cargo test -p brainwires-core
```
## 依赖 DAG
```text
brainwires (facade)
├── brainwires-agent
│ ├── brainwires-core
│ ├── brainwires-call-policy
│ ├── brainwires-tool-runtime
│ ├── brainwires-tool-builtins
│ ├── brainwires-storage (seal 功能 — 用于 PatternStore)
│ ├── brainwires-knowledge (seal-knowledge 功能)
│ └── brainwires-permission (seal-feedback 功能)
├── brainwires-knowledge
│ ├── brainwires-core
│ └── brainwires-storage
├── brainwires-rag
│ ├── brainwires-core
│ └── brainwires-storage
├── brainwires-prompting
│ ├── brainwires-core
│ └── brainwires-knowledge (knowledge 功能)
├── brainwires-storage
│ └── brainwires-core
├── brainwires-stores
│ ├── brainwires-core
│ └── brainwires-storage
├── brainwires-memory
│ ├── brainwires-core
│ ├── brainwires-storage
│ └── brainwires-stores (memory 功能)
├── brainwires-tool-runtime
│ ├── brainwires-core
│ ├── brainwires-stores (sessions 功能 — SessionBroker)
│ ├── brainwires-rag (rag 功能)
│ └── brainwires-sandbox (sandbox 功能)
├── brainwires-tool-builtins
│ ├── brainwires-tool-runtime
│ └── brainwires-rag (rag 功能)
├── brainwires-mcp-client
│ └── brainwires-core
├── brainwires-mcp-server
│ ├── brainwires-core
│ └── brainwires-mcp-client
├── brainwires-network
│ ├── brainwires-core
│ ├── brainwires-mcp-client
│ └── brainwires-a2a (a2a-transport 功能)
├── brainwires-finetune （仅限云端 — 本地 PEFT + wgpu Gemma 4 位于 rullama）
│ ├── brainwires-core
│ └── brainwires-provider (cloud 功能)
├── brainwires-telemetry
│ └── brainwires-core
└── brainwires-hardware
├── brainwires-provider (audio 功能)
└── brainwires-provider-speech (audio 功能)
```
## 许可
根据以下许可之一授权：
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) 或 <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT License ([LICENSE-MIT](LICENSE-MIT) 或 <http://opensource.org/licenses/MIT>)
在您的选项中。
连接信息
猜你喜欢
暂无推荐服务器