LibreFang 架构

                              ┌─────────────────────┐
                              │     用户 / 客户端     │
                              └──────────┬──────────┘
                       ┌─────────────────┼─────────────────┐
                       │                 │                 │
                  ┌────▼────┐     ┌──────▼──────┐   ┌─────▼─────┐
                  │   CLI   │     │  REST API   │   │   桌面应用  │
                  │  (TUI)  │     │  (Axum)     │   │  (Tauri)  │
                  └────┬────┘     └──────┬──────┘   └─────┬─────┘
                       └─────────────────┼─────────────────┘
                                         │
                              ┌──────────▼──────────┐
                              │       Kernel        │
                              │  AgentRegistry      │
                              │  WorkflowEngine     │
                              │  TriggerEngine      │
                              │  ModelCatalog       │
                              │  CapabilityManager  │
                              │  MeteringEngine     │
                              └──────────┬──────────┘
                 ┌───────────┬───────────┼───────────┬───────────┐
                 │           │           │           │           │
          ┌──────▼──────┐ ┌──▼───┐ ┌─────▼─────┐ ┌──▼───┐ ┌────▼────┐
          │   Runtime   │ │Memory│ │  Channels  │ │Skills│ │  Hands  │
          │ LLM Drivers │ │SQLite│ │ 44 适配器   │ │  60  │ │   15    │
          │ 60 Tools    │ │向量   │ │ Formatter  │ │内置   │ │Registry │
          │ WASM Sandbox│ │搜索   │ │ RateLimiter│ │      │ │         │
          └──────┬──────┘ └──────┘ └────────────┘ └──────┘ └─────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
┌───▼───┐  ┌────▼────┐  ┌────▼────┐
│  LLM  │  │   MCP   │  │   A2A   │
│49 驱动 │  │ Servers │  │  (OFP)  │
└───────┘  └─────────┘  └─────────┘

librefang/
├── crates/                    # Rust 工作空间（15 个 crate）
│   ├── librefang-types/       #   共享类型、配置、错误定义
│   ├── librefang-memory/      #   SQLite 内存、向量搜索
│   ├── librefang-runtime/     #   Agent 循环、LLM 驱动、工具
│   ├── librefang-kernel/      #   内核编排器
│   ├── librefang-api/         #   REST/WS API 服务 + 仪表板
│   ├── librefang-cli/         #   CLI + TUI
│   ├── librefang-channels/    #   44 个通道适配器
│   ├── librefang-skills/      #   技能系统 + FangHub
│   ├── librefang-hands/       #   自主 Hands
│   ├── librefang-wire/        #   OFP P2P 协议
│   ├── librefang-extensions/  #   OAuth、凭证金库、MCP 设置
│   ├── librefang-migrate/     #   迁移引擎
│   ├── librefang-desktop/     #   Tauri 桌面应用
│   ├── librefang-telemetry/   #   OpenTelemetry 指标和追踪
│   └── librefang-testing/     #   测试工具
├── agents/                    # Pipeline runner Agent 模板
├── sdk/                       # 客户端 SDK
│   ├── javascript/            #   @librefang/sdk (npm)
│   ├── python/                #   librefang-sdk (PyPI)
│   ├── rust/                  #   librefang (crates.io)
│   └── go/                    #   Go module
├── packages/                  # 分发包
│   └── cli-npm/               #   @librefang/cli (npm 包装器)
├── deploy/                    # 部署配置
│   ├── Dockerfile             #   Docker 镜像
│   ├── docker-entrypoint.sh   #   容器启动脚本
│   ├── docker-compose.yml     #   Docker Compose
│   ├── docker-compose.observability.yml  # 可观测性栈
│   ├── OBSERVABILITY.md       #   可观测性栈使用指南
│   ├── fly/                   #   Fly.io (fly.toml + deploy.sh)
│   ├── railway/               #   Railway (railway.json)
│   ├── render.yaml            #   Render
│   ├── gcp/                   #   GCP Terraform
│   ├── librefang.service      #   systemd 服务单元
│   ├── worker/                #   Worker 部署配置
│   ├── otel-collector/        #   OpenTelemetry Collector 配置
│   ├── tempo/                 #   Grafana Tempo（trace 存储）
│   ├── loki/                  #   Grafana Loki（log 存储）
│   ├── alloy/                 #   Grafana Alloy（log 收集器）
│   ├── grafana/               #   Grafana 仪表板
│   └── prometheus/            #   Prometheus 配置
├── docs/                      # 文档站（Next.js）
├── web/                       # 官网
│   └── public/
│       ├── install.sh          #  Linux/macOS 安装脚本
│       └── install.ps1         #  Windows 安装脚本
├── i18n/                      # Fluent 翻译文件
├── examples/                  # 使用示例
├── scripts/                   # 构建和 CI 脚本
├── xtask/                     # cargo-xtask 构建任务
├── Cargo.toml                 # 工作空间根配置
└── CLAUDE.md                  # Agent 指令

~/.librefang/
├── config.toml                # 主配置文件
├── aliases.toml               # 模型和命令别名
├── data/
│   ├── librefang.db           #   SQLite 数据库（内存、会话、知识图谱）
│   └── state.db               #   守护进程状态持久化
├── registry/                  # 从 librefang-registry 同步
│   ├── agents/                #   32 个 Agent 模板（每个含 agent.toml）
│   ├── hands/                 #   15 个 Hand 定义（HAND.toml + SKILL.md）
│   ├── providers/             #   49 个提供商配置（*.toml）
│   ├── skills/                #   技能定义
│   ├── workflows/             #   工作流模板
│   ├── plugins/               #   插件定义
│   └── integrations/          #   集成配置
├── workspaces/
│   ├── agents/                #   活跃 Agent 工作目录
│   │   └── <name>/            #     每个 Agent 的私有 home
│   │       ├── .identity/     #       Identity 文件（SOUL.md、IDENTITY.md …）
│   │       ├── sessions/      #       对话历史
│   │       ├── memory/        #       每日记忆日志
│   │       ├── data/          #       Agent 专属数据
│   │       ├── output/        #       生成的输出文件
│   │       ├── skills/        #       Agent 专属技能
│   │       └── logs/          #       Agent 日志
│   ├── hands/                 #   活跃 Hand 工作目录
│   └── shared/                #   命名共享工作区（用户声明）
├── skills/                    # 用户安装的技能
├── plugins/                   # 用户安装的插件
├── integrations.toml          # 已配置的集成
├── vault.enc                  # 加密凭证金库
├── cron_jobs.json             # 定时任务配置
├── webhooks.json              # Webhook 配置
├── hand_state.json            # Hand 激活状态
├── custom_models.json         # 用户自定义模型
├── logs/                      # 应用日志
├── cache/                     # 临时缓存
└── bin/                       # CLI 二进制（脚本安装时）

librefang-cli            CLI 接口、守护进程自动检测、MCP 服务器
    |
librefang-desktop        Tauri 2.0 桌面应用 (WebView + 系统托盘)
    |
librefang-api            REST/WS/SSE API 服务器 (Axum 0.8), 230+ 个端点
    |
librefang-kernel         内核: 组装所有子系统、工作流引擎、RBAC、计量
    |
    +-- librefang-runtime      Agent 循环、3 个 LLM 驱动、60 个工具、WASM 沙箱、MCP、A2A
    +-- librefang-channels     44 个通道适配器、桥接器、格式化器、速率限制器
    +-- librefang-wire         OFP 点对点网络，HMAC-SHA256 认证
    +-- librefang-migrate      迁移引擎 (OpenClaw YAML->TOML)
    +-- librefang-skills       60 个内置技能、FangHub 市场、ClawHub 客户端
    +-- librefang-extensions   扩展与集成系统（凭证保险库、OAuth2 PKCE、一键 MCP 配置）
    +-- librefang-hands        自主 Hands 系统（注册表中的 15 个 hand agent）
    |
librefang-memory         SQLite 内存子系统、会话、语义搜索、使用追踪
    |
librefang-types          共享类型: Agent、Capability、Event、Memory、Message、Tool、Config、
                        Taint、ManifestSigning、ModelCatalog、MCP/A2A 配置、Web 配置

1. 加载配置
   - 读取 ~/.librefang/config.toml（或指定路径）
   - 对缺失字段应用 #[serde(default)] 默认值
   - 验证配置并记录警告（缺失 API 密钥等）

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

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

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

5. 初始化模型目录
   - 构建包含 130+ 个内置模型、20+ 别名、49 个提供商的 ModelCatalog
   - 从 ~/.librefang/providers/*.toml 加载提供商定义（注册表预装 + 用户自定义）
   - 运行 detect_auth() 检查环境变量存在（从不读取密钥内容）
   - 存储为 kernel.model_catalog

6. 初始化计量引擎
   - 创建带有成本目录的 MeteringEngine（28+ 个模型系列）
   - 接入模型目录作为定价来源

7. 初始化模型路由器
   - 创建带有 TaskComplexity 评分的 ModelRouter
   - 验证已配置的模型并解析别名

8. 初始化核心子系统
   - AgentRegistry（基于 DashMap 的并发 Agent 存储）
   - CapabilityManager（基于 DashMap 的能力授予）
   - EventBus（异步广播频道）
   - AgentScheduler（每个 Agent 的配额追踪，按小时窗口重置）
   - Supervisor（健康监控，panic/重启计数器）
   - WorkflowEngine（工作流注册和执行，运行驱逐上限 200）
   - TriggerEngine（事件模式匹配）
   - BackgroundExecutor（持续/周期性 Agent 循环）
   - WasmSandbox（Wasmtime 引擎，双燃料+epoch 计量）

9. 初始化 RBAC 认证管理器
   - 创建带有 UserRole 层次结构的 AuthManager
   - 设置通道身份解析

10. 初始化技能注册表
    - 通过 parse_bundled() 加载 60 个内置技能
    - 从磁盘加载用户安装的技能
    - 将技能工具接入 tool_runner 回退链
    - 将 PromptOnly 技能上下文注入系统提示

11. 初始化 Web 工具上下文
    - 创建 WebSearchEngine（4 提供商级联：Tavily->Brave->Perplexity->DDG）
    - 创建 WebFetchEngine（SSRF 保护）
    - 打包为 WebToolsContext

12. 恢复持久化的 Agent
    - 从 SQLite 加载所有 Agent
    - 在内存中重新注册（注册表、能力、调度器）
    - 设置状态为 Running

13. 发布 KernelStarted 事件

14. 返回内核实例

15. 设置自引用句柄（用于触发器分发的弱 Arc 引用）

16. 连接 MCP 服务器
    - 后台连接已配置的 MCP 服务器（stdio/SSE）
    - 将工具命名为 mcp_{server}_{tool}
    - 将连接存储在 kernel.mcp_connections

17. 启动心跳监控器
    - 后台 tokio 任务用于 Agent 健康检查
    - 异常时发布 HealthCheckFailed 事件

18. 启动后台 Agent 循环（持续型、周期型、主动型）

    spawn                    message/tick              kill
      |                         |                       |
      v                         v                       v
  [Running] <------------> [Running] ---------> [Terminated]
      |                                              ^
      |          shutdown                            |
      +----------> [Suspended] ---------------------+
                      |          reboot/restore
                      +------> [Running]

agent_id | key         | value
---------|-------------|------------------
uuid-a   | preferences | {"theme": "dark"}
uuid-b   | state       | {"step": 3}
shared   | project     | {"name": "foo"}

#[async_trait]
pub trait LlmDriver: Send + Sync {
    async fn send_message(
        &self,
        model: &str,
        system_prompt: &str,
        messages: &[Message],
        tools: &[ToolDefinition],
    ) -> Result<LlmResponse, LibreFangError>;

    async fn send_message_streaming(
        &self,
        model: &str,
        system_prompt: &str,
        messages: &[Message],
        tools: &[ToolDefinition],
        tx: mpsc::Sender<StreamEvent>,
    ) -> Result<LlmResponse, LibreFangError>;

    fn key_required(&self) -> bool;
}

[model]
provider = "openai"                   # 不同于内核默认值
model = "gpt-4o"
api_key_env = "OPENAI_API_KEY"        # 自定义密钥环境变量
base_url = "https://custom.api.com"   # 可选的自定义端点

pub enum Capability {
    // 工具访问
    ToolInvoke(String),       // 访问特定工具（例如 "file_read"）
    ToolAll,                  // 访问所有工具

    // 内存访问
    MemoryRead(String),       // 读取范围（例如 "*"、"self.*"）
    MemoryWrite(String),      // 写入范围

    // 网络访问
    NetConnect(String),       // 连接到主机（例如 "api.example.com"、"*"）

    // Agent 操作
    AgentSpawn,               // 可以创建新 Agent
    AgentMessage(String),     // 可以向匹配模式的 Agent 发送消息
    AgentKill(String),        // 可以终止匹配模式的 Agent

    // Shell 访问
    ShellExec(String),        // 可以执行匹配模式的 shell 命令

    // OFP 网络
    OfpDiscover,              // 可以发现远程节点
    OfpConnect(String),       // 可以连接到特定节点
    OfpAdvertise,             // 可以向节点广播

    // 网络监听
    NetListen(u16),           // 可以绑定并监听端口

    // LLM 访问
    LlmQuery(String),         // 可以查询特定模型/提供商
    LlmMaxTokens(u64),        // 每次 LLM 调用的最大 token 数

    // 环境变量访问
    EnvRead(String),          // 可以读取特定环境变量

    // 经济/计量
    EconSpend(f64),           // 美元消费上限
    EconEarn,                 // 可以赚取积分（收入型 Agent）
    EconTransfer(String),     // 可以向另一个 Agent 转移积分
}

[capabilities]
tools = ["file_read", "file_list", "web_fetch"]
memory_read = ["*"]
memory_write = ["self.*"]
network = ["api.anthropic.com"]
shell = []
agent_spawn = false
agent_message = ["coder", "researcher"]
agent_kill = []
ofp_discover = false
ofp_connect = []

工具调用请求
    |
    v
CapabilityManager.check(agent_id, ToolInvoke("file_read"))
    |
    +-- 已授予 --> 验证路径（遍历检查） --> 执行工具
    |
    +-- 已拒绝 --> 向 LLM 返回"权限被拒绝"错误

Machine A                          Machine B
+-----------+                      +-----------+
| PeerNode  | ---TCP (JSON)------> | PeerNode  |
| port 4545 | <---TCP (JSON)------ | port 4545 |
+-----------+                      +-----------+
| PeerRegistry |                   | PeerRegistry |
| - Known peers |                  | - Known peers |
| - Remote agents |                | - Remote agents |
+---------------+                  +---------------+

WireMessage {
    id: UUID,
    sender: PeerId,
    payload: WireRequest | WireResponse
}

pub struct PeerEntry {
    pub id: PeerId,
    pub addr: SocketAddr,
    pub agents: Vec<RemoteAgent>,
    pub last_seen: Instant,
}

pub struct RemoteAgent {
    pub agent_id: String,
    pub name: String,
    pub description: String,
    pub tags: Vec<String>,
}

+-------------------------------------------+
| Tauri 2.0 Shell                           |
| +---------------------------------------+ |
| | WebView (WebKit/WebView2)             | |
| | -> http://127.0.0.1:{random_port}     | |
| +---------------------------------------+ |
| +---------------------------------------+ |
| | System Tray                           | |
| | Show | Browser | Status | Quit        | |
| +---------------------------------------+ |
| +---------------------------------------+ |
| | Background Thread                     | |
| | +- Own Tokio Runtime                  | |
| |    +- LibreFangKernel (in-process)     | |
| |    +- Axum Server (build_router())    | |
| |    +- ServerHandle { port, shutdown } | |
| +---------------------------------------+ |
+-------------------------------------------+

+-------------------------------------------------------------------+
|                         librefang-cli                                |
|  [init] [start] [agent] [workflow] [trigger] [skill] [channel]     |
|  [migrate] [config] [chat] [status] [doctor] [mcp]                 |
+-------------------------------------------------------------------+
         |                    |
         | (HTTP/守护进程)     | (进程内)
         v                    v
+-------------------------------------------------------------------+
|                         librefang-api                                |
|  +-------------+  +----------+  +--------+  +------------------+   |
|  | REST 路由   |  | WS 聊天  |  | SSE    |  | OpenAI /v1/      |   |
|  | (230+ 端点) |  +----------+  +--------+  +------------------+   |
|  +-------------+  +------------------+  +-----------------------+   |
|  | 认证+RBAC   |  | 安全头           |  | GCRA 速率限制器       |   |
|  +-------------+  +------------------+  +-----------------------+   |
|  +---------------------+  +------------------------------------+   |
|  | A2A 端点             |  | 健康信息脱敏                      |   |
|  +---------------------+  +------------------------------------+   |
+-------------------------------------------------------------------+
         |
         v
+-------------------------------------------------------------------+
|                       librefang-kernel                               |
|  +----------------+  +------------------+  +-------------------+   |
|  | AgentRegistry  |  | AgentScheduler   |  | CapabilityManager |   |
|  | (DashMap)      |  | (配额+计量)      |  | (DashMap+继承)    |   |
|  +----------------+  +------------------+  +-------------------+   |
|  +----------------+  +------------------+  +-------------------+   |
|  | EventBus       |  | Supervisor       |  | AuthManager       |   |
|  | (广播)         |  | (健康监控)        |  | (RBAC 多用户)     |   |
|  +----------------+  +------------------+  +-------------------+   |
|  +----------------+  +------------------+  +-------------------+   |
|  | WorkflowEngine |  | TriggerEngine    |  | BackgroundExec    |   |
|  | (管线)         |  | (事件模式)        |  | (持续/定时)       |   |
|  +----------------+  +------------------+  +-------------------+   |
|  +----------------+  +------------------+  +-------------------+   |
|  | ModelCatalog   |  | MeteringEngine   |  | ModelRouter       |   |
|  | (130+ 模型)    |  | (成本追踪)        |  | (自动选择)        |   |
|  +----------------+  +------------------+  +-------------------+   |
|  +----------------+  +------------------+  +-------------------+   |
|  | HeartbeatMon   |  | SetupWizard      |  | SkillRegistry     |   |
|  | (Agent 健康)   |  | (NL Agent 配置)   |  | (60 个内置)       |   |
|  +----------------+  +------------------+  +-------------------+   |
|  +----------------+  +------------------+                          |
|  | MCP 连接       |  | WebToolsContext  |                          |
|  | (stdio/SSE)   |  | (搜索+抓取)       |                          |
|  +----------------+  +------------------+                          |
+-------------------------------------------------------------------+
         |
    +----+-------------------+------------------+---------+
    |                        |                   |         |
    v                        v                   v         v
+------------------+  +--------------+  +--------+  +-----------+
| librefang-runtime |  | librefang-    |  | open-  |  | librefang- |
|                  |  | channels     |  | fang-  |  | skills    |
| +------------+   |  |              |  | wire   |  |           |
| | Agent 循环  |   |  | +----------+|  |        |  | +-------+ |
| | +循环守卫   |   |  | | 44 通道  ||  | +----+ |  | |60 内置| |
| | +会话修复   |   |  | | 适配器   ||  | |OFP | |  | |技能   | |
| +------------+   |  | +----------+|  | |HMAC| |  | +-------+ |
| +------------+   |  | +----------+|  | +----+ |  | +-------+ |
| | 3 LLM 驱动 |   |  | |格式化器  ||  | +----+ |  | |FangHub| |
| | (28 提供商) |   |  | |速率限制  ||  | |Peer| |  | |ClawHub| |
| +------------+   |  | |私聊/群聊  ||  | |Reg | |  | +-------+ |
| +------------+   |  | +----------+|  | +----+ |  | +-------+ |
| | 60 个工具   |   |  | +----------+|  +--------+  | |验证   | |
| +------------+   |  | |AgentRouter|               | |注入   | |
| +------------+   |  | +----------+|               | |扫描   | |
| | WASM 沙箱   |   |  +--------------+              | +-------+ |
| | (双重计量)  |  |                                +-----------+
| +------------+   |
| +------------+   |
| | MCP 客户端  |   |
| | MCP 服务器  |   |
| +------------+   |
| +------------+   |
| | A2A 协议    |   |
| +------------+   |
| +------------+   |
| | Web 搜索    |   |  4 引擎: Tavily/Brave/Perplexity/DDG
| | Web 抓取    |   |  SSRF 保护 + TTL 缓存
| +------------+   |
| +------------+   |
| | 审计追踪    |   |  Merkle 哈希链
| | 压缩器      |   |  块感知会话压缩
| +------------+   |
| +------------+   |
| | KernelHandl|   |  (此处定义 trait，
| | (trait)    |   |   在 kernel 中实现)
| +------------+   |
+------------------+
         |
         v
+------------------+
| librefang-memory  |
| +------------+   |
| | KV 存储    |   |  每 Agent + 共享命名空间
| +------------+   |
| +------------+   |
| | 语义搜索    |   |  向量嵌入 + 余弦相似度
| +------------+   |
| +------------+   |
| | 知识图谱    |   |  实体-关系图
| |            |   |
| +------------+   |
| +------------+   |
| | 会话        |   |  对话历史 + token 追踪
| +------------+   |
| +------------+   |
| | 任务板      |   |  协作用共享任务队列
| +------------+   |
| +------------+   |
| | 使用存储    |   |  Token 计数、成本、模型使用
| +------------+   |
| +------------+   |
| | 规范会话    |   |  跨通道会话记忆
| |            |   |
| +------------+   |
| +------------+   |
| | SQLite v5  |   |  Arc<Mutex<Connection>> + spawn_blocking
| +------------+   |
+------------------+
         |
         v
+------------------+
| librefang-types   |
| Agent, Capability|
| Event, Memory    |
| Message, Tool    |
| Config, Error    |
| Taint, Signing   |
| ModelCatalog     |
| MCP/A2A Config   |
| Web Config       |
+------------------+