技术架构核心

技术研究 Rust架构模块化设计

OpenFang的模块化内核架构、14个Rust crate设计原理与技术实现

架构总览：模块化内核设计

设计哲学：单二进制、全功能集成

OpenFang采用了一种独特的架构理念：将完整的Agent操作系统编译为单个~32MB的二进制文件。这与传统的微服务或插件架构形成鲜明对比。

这一设计决策背后有几个关键考量：

部署简化。用户无需配置Docker、无需pip install、无需处理依赖冲突。一条curl命令即可完成安装，这对于企业级部署和边缘设备部署都极为有利。

性能优化。所有模块在编译时链接，避免了运行时加载的开销。Rust的零成本抽象确保模块化设计不会带来性能损失。

安全审计。单二进制意味着所有代码都经过编译时验证，不存在运行时注入或动态加载的安全风险。

14 Crate架构解析

OpenFang将系统划分为14个Rust crate，每个crate负责一个独立的能力域：

┌─────────────────────────────────────────────────────────────────┐
│                        OpenFang System                          │
├─────────────────────────────────────────────────────────────────┤
│  openfang-desktop (Tauri 2.0 GUI)                               │
│  openfang-cli (命令行界面 + TUI + MCP Server模式)               │
│  openfang-api (140+ REST/WS/SSE端点 + OpenAI兼容API)            │
├─────────────────────────────────────────────────────────────────┤
│  openfang-kernel (核心编排引擎)                                  │
│    ├── 工作流调度、RBAC、预算追踪                                │
│    └── 任务编排、计量系统                                        │
├─────────────────────────────────────────────────────────────────┤
│  openfang-runtime (Agent运行时)                                  │
│    ├── 3个LLM驱动 (Anthropic/Gemini/OpenAI-Compatible)          │
│    ├── 53个内置工具 + WASM沙箱                                   │
│    └── MCP + A2A协议支持                                         │
├─────────────────────────────────────────────────────────────────┤
│  openfang-hands (自主Agent包)                                    │
│    ├── 7个内置Hands (Clip/Lead/Collector/等)                    │
│    └── HAND.toml解析 + 生命周期管理                              │
├─────────────────────────────────────────────────────────────────┤
│  openfang-memory (持久化层)                                      │
│    ├── SQLite存储 + 向量嵌入                                     │
│    └── 会话管理 + 数据压缩                                        │
├─────────────────────────────────────────────────────────────────┤
│  支撑模块:                                                       │
│  openfang-types (核心类型 + 污点追踪 + Ed25519签名)              │
│  openfang-channels (40个消息适配器)                              │
│  openfang-skills (60个内置技能 + SKILL.md解析)                   │
│  openfang-extensions (25个MCP模板 + 凭证保险库)                  │
│  openfang-wire (OFP P2P协议 + HMAC-SHA256认证)                   │
│  openfang-migrate (迁移引擎)                                     │
└─────────────────────────────────────────────────────────────────┘

核心模块深度解析

openfang-kernel：编排引擎的心脏

Kernel是整个系统的调度中心，负责：

工作流编排。基于有向无环图(DAG)的任务调度，支持条件分支、并行执行、错误重试。工作流定义采用声明式配置，而非硬编码逻辑。

资源计量。双计量机制——燃料(fuel)计量控制计算资源，轮次(epoch)中断控制时间资源。一个独立的watchdog线程监控执行状态，一旦超限立即终止。

RBAC权限控制。基于角色的访问控制，Agent必须声明所需工具，Kernel在运行时强制执行权限边界。这确保了即使Agent被恶意指令劫持，也无法超出其权限范围。

openfang-runtime：Agent执行环境

Runtime提供Agent运行的完整上下文：

LLM驱动抽象。统一的三层驱动架构：

Anthropic Driver：原生支持Claude系列模型
Gemini Driver：原生支持Google Gemini系列
OpenAI-Compatible Driver：兼容27个供应商的123+模型

工具系统。53个内置工具覆盖文件操作、网络请求、代码执行、数据处理等场景。每个工具都在WASM沙箱中执行，确保不会影响宿主系统。

MCP集成。作为MCP协议的实现者，OpenFang可以暴露工具供其他MCP客户端调用，也可以连接外部MCP服务器扩展能力。

openfang-hands：自主Agent的核心创新

Hands是OpenFang区别于传统Agent框架的关键特性：

声明式Agent定义。每个Hand包含：

HAND.toml：声明工具依赖、配置参数、Dashboard指标
System Prompt：500+字的专家级操作流程（非简单的一句话prompt）
SKILL.md：领域知识参考文档，运行时注入上下文
Guardrails：敏感操作的审批门控

预编译打包。所有Hand在编译时打包进二进制，无需下载、无需pip install。用户通过openfang hand activate researcher即可启动。

生命周期管理。支持启动、暂停、恢复、状态查询等操作。Hand的状态持久化到SQLite，支持断点续传。

Hands系统：真正自主的Agent

七大内置Hands详解

Hand	核心能力	自主性体现	典型用例
Researcher	深度研究、多源验证、引用追踪	按计划自主调研，生成带APA格式的报告	竞品分析、技术调研
Lead	线索发现、ICP匹配、自动评分	每日自动扫描、去重、评分	销售线索挖掘
Collector	目标监控、变化检测、知识图谱构建	7x24持续监控，关键变化触发告警	品牌/人物/公司监控
Predictor	多源信号收集、预测建模、准确率追踪	自主收集信息，建立预测模型并自评	市场预测、事件预测
Clip	视频下载、精彩片段识别、多平台发布	完整8阶段流水线，自动产出内容	短视频内容创作
Twitter	内容创作、排期优化、互动管理	7种内容格式轮换，自动排期发布	社交媒体运营
Browser	网页自动化、表单填写、多步骤流程	复杂工作流自动化，敏感操作需人工确认	自动化测试、数据采集

HAND.toml规范示例

# Researcher Hand配置示例
[hand]
name = "researcher"
version = "0.1.0"
description = "Deep autonomous research agent"

[dependencies]
tools = ["web_search", "web_fetch", "document_parser", "citation_manager"]
llm = "claude-3-opus"  # 推荐模型

[settings]
max_sources = 20
credibility_threshold = 0.7  # CRAAP标准
output_format = "markdown"   # 支持 markdown/json/pdf

[metrics]
sources_consulted = { type = "counter", label = "Sources Consulted" }
credibility_score = { type = "gauge", label = "Avg Credibility" }
report_length = { type = "histogram", label = "Report Length" }

[guardrails]
# 无敏感操作，无需审批门控

自主性实现机制

Hands的自主性通过以下机制实现：

调度器集成。Hand可以绑定到调度器，按cron表达式或事件触发。例如Lead Hand默认每日凌晨执行。

状态机驱动。每个Hand有明确定义的状态转换图：

Idle → Starting → Running → Paused → Running
                ↓
              Completed
                ↓
               Failed

结果交付。Hand执行完成后，通过配置的Channel（Telegram、Email等）交付结果。用户无需主动查看Dashboard。

内存与持久化架构

SQLite + 向量嵌入混合存储

OpenFang采用混合存储策略：

关系数据：Agent配置、对话历史、工具调用记录存储在SQLite表中。这保证了ACID特性和查询效率。

向量数据：文档嵌入、语义索引存储在SQLite的vector扩展中。支持相似度搜索、RAG检索。

会话压缩：长期运行会产生大量对话数据。系统支持自动压缩策略，将低价值的交互记录归档，保留关键上下文。

Canonical Session机制

为确保Agent状态一致性，OpenFang实现了Canonical Session机制：

消息历史验证。7阶段验证流程确保消息历史的完整性和一致性。

自动修复。检测到损坏时，自动尝试从最近的检查点恢复。

跨重启持久化。Agent重启后能够恢复到之前的状态，包括对话上下文、工具调用历史、中间结果。

扩展性设计

MCP协议集成

OpenFang作为MCP协议的第一方实现者：

MCP Server模式。通过openfang mcp serve启动MCP服务器，暴露工具供外部调用。这使得OpenFang可以与任何MCP兼容的客户端（如Claude Desktop）集成。

MCP Client模式。连接外部MCP服务器，扩展工具能力。用户可以接入私有工具、企业内部API等。

FangHub生态

OpenFang计划构建FangHub——Hands和Skills的市场place：

发布流程。开发者创建HAND.toml或SKILL.md，推送到FangHub仓库，经过审核后发布。

版本管理。支持语义化版本，用户可以锁定特定版本确保稳定性。

社区贡献。兼容ClawHub市场（OpenClaw的生态系统），支持迁移现有Skills。

架构优势总结

OpenFang的架构设计体现了几个核心优势：

性能极致：Rust原生编译 + 单二进制 + 零成本抽象，实现<200ms冷启动
安全内生：16层安全机制深度嵌入架构，而非外挂式防护
部署简单：一条命令安装，无依赖管理噩梦
真正自主：Hands系统实现7x24自主运行，无需人工干预
高度可扩展：MCP协议 + FangHub生态，支持无限扩展