LibreFang 架构

本文档描述 LibreFang 内部架构——用 Rust 编写的开源 Agent 操作系统。

Crate 结构

LibreFang 组织为 Cargo 工作空间，包含 14 个 crates（13 个代码 crates + xtask）。

librefang-cli            CLI 接口、守护进程自动检测、MCP 服务器
    |
librefang-desktop        Tauri 2.0 桌面应用 (WebView + 系统托盘)
    |
librefang-api            REST/WS/SSE API 服务器 (Axum 0.8), 76 个端点
    |
librefang-kernel         内核: 组装所有子系统、工作流引擎、RBAC、计量
    |
    +-- librefang-runtime    Agent 循环、3 个 LLM 驱动、23 个工具、WASM 沙箱、MCP、A2A
    +-- librefang-channels   40 个通道适配器、桥接器、格式化器、速率限制器
    +-- librefang-wire       OFP 点对点网络，HMAC-SHA256 认证
    +-- librefang-migrate    迁移引擎 (OpenClaw YAML→TOML)
    +-- librefang-skills     60 个内置技能、FangHub 市场、ClawHub 客户端
    |
librefang-memory         SQLite 内存子系统、会话、语义搜索、使用追踪
    |
librefang-types          共享类型: Agent、Capability、Event、Memory、Message、Tool、Config

Crate 职责

Crate	说明
librefang-types	核心类型定义。定义 `AgentManifest`、`AgentId`、`Capability`、`ToolDefinition`、`KernelConfig`、污点追踪、Ed25519 清单签名、模型目录类型、MCP/A2A 配置类型。
librefang-memory	SQLite 内存子系统（schema v5）。提供结构化 KV 存储、向量嵌入语义搜索、知识图谱、会话管理、任务板、使用事件持久化。5 个 schema 版本。
librefang-runtime	Agent 执行引擎。包含 agent 循环、3 个原生 LLM 驱动（Anthropic、Gemini、OpenAI 兼容）、23 个内置工具、WASM 沙箱（Masmtime 双燃料+epoch 计量）、MCP 客户端/服务器、A2A 协议、Web 搜索引擎、SSRF 保护、循环守卫、会话修复、LLM 会话压缩器、Merkle 哈希链审计追踪。
librefang-kernel	中央协调器。`LibreFangKernel` 组装所有子系统：`AgentRegistry`、`AgentScheduler`、`CapabilityManager`、`EventBus`、`Supervisor`、`WorkflowEngine`、`TriggerEngine`、`BackgroundExecutor`、`WasmSandbox`、`ModelCatalog`、`MeteringEngine`、`ModelRouter`、`AuthManager`、`HeartbeatMonitor`。
librefang-api	基于 Axum 0.8 的 HTTP API 服务器，76 个端点。包含 REST、WebSocket、SSE 端点。OpenAI 兼容端点 (`/v1/chat/completions`)。中间件：Bearer 认证、请求 ID 注入、结构化日志、GCRA 速率限制、安全头。
librefang-channels	通道桥接层，40 个适配器。包括 Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Email 等。功能：消息路由、生命周期协调、速率限制、格式化器、通道覆盖。
librefang-wire	LibreFang 协议 (OFP) 点对点通信。TCP 上的 JSON 帧消息，HMAC-SHA256 双向认证。
librefang-cli	基于 Clap 的 CLI。支持所有命令：`init`、`start`、`status`、`doctor`、`agent spawn/list/chat/kill`、`workflow`、`trigger`、`skill`、`channel`、`config`、`chat`、`mcp`。
librefang-desktop	Tauri 2.0 原生桌面应用。在进程内启动内核，后台线程运行 axum 服务器，系统托盘、桌面通知、单实例强制。
librefang-migrate	迁移引擎。支持 OpenClaw (~/openclaw/)。将 YAML 配置转换为 TOML，映射工具名称，导入 agent 清单。
librefang-skills	可插拔工具捆绑的技能系统。60 个内置技能。技能是 `skill.toml` + Python/WASM/Node.js/PromptOnly 代码。技能注册表管理已安装和捆绑的技能。FangHub 客户端连接到市场。提示注入扫描器检测覆盖尝试。
xtask	构建自动化任务 (cargo-xtask 模式)。

内核启动序列

当调用 LibreFangKernel::boot_with_config() 时，执行以下序列：

1. 加载配置
   - 读取 ~/.librefang/config.toml
   - 应用 #[serde(default)] 默认值
   - 验证配置并记录警告

2. 创建数据目录
   - 确保 ~/.librefang/data/ 存在

3. 初始化内存子系统
   - 打开 SQLite 数据库 (librefang.db)
   - 运行 schema 迁移 (到 v5)
   - 设置记忆衰减率

4. 初始化 LLM 驱动
   - 从环境变量读取 API 密钥
   - 为配置的提供商创建驱动
   - 验证驱动配置

5. 初始化模型目录
   - 构建包含 51 个内置模型、20+ 别名、20 个提供商的 ModelCatalog
   - 运行 detect_auth() 检查环境变量存在（从不读取密钥）

6. 初始化计量引擎
   - 创建带有成本目录的 MeteringEngine

7. 初始化模型路由器
   - 创建带有任务复杂度评分的 ModelRouter

8. 初始化核心子系统
   - AgentRegistry (基于 DashMap 的并发 agent 存储)
   - CapabilityManager (基于 DashMap 的能力授予)
   - EventBus (异步广播频道)
   - AgentScheduler (每个 agent 的配额追踪)
   - Supervisor (健康监控)
   - WorkflowEngine (工作流注册和执行)
   - TriggerEngine (事件模式匹配)
   - BackgroundExecutor (持续/周期性 agent 循环)
   - WasmSandbox (Wasmtime 引擎)

9. 初始化 RBAC 认证管理器
   - 创建带有 UserRole 层次结构的 AuthManager

10. 初始化技能注册表
    - 通过 parse_bundled() 加载 60 个内置技能
    - 从磁盘加载用户安装的技能

11. 初始化 Web 工具上下文
    - 创建 WebSearchEngine (4 提供商级联)
    - 创建 WebFetchEngine (SSRF 保护)

12. 恢复持久化的 agent
    - 从 SQLite 加载所有 agent

13. 发布 KernelStarted 事件

14. 返回内核实例

Agent 生命周期

[Created] → [Initializing] → [Running] → [Paused]
                                  ↓
                              [Stopped]

状态说明

状态	说明
Created	Agent 清单已创建
Initializing	正在加载配置和能力
Running	活跃处理消息
Paused	暂停，可恢复
Stopped	已终止，状态已保存