V-Core

The Bare Metal of Agentic AI.

---

📖 项目简介

V-Core (Virtual Von-Neumann Core) 是一种基于冯·诺依曼计算机体系结构的大模型 Agent 系统架构。

核心创新

将 LLM 系统从"软件/操作系统"层面下沉到"硬件体系结构"层面进行设计：

• LLM 作为 CPU：将大模型降级为纯粹的执行单元，而非决策者
• 文件系统作为内存：RAM Disk 提供微秒级访问速度
• 工具作为外设：通过标准化驱动模型接入系统
• CISC 宏指令：应对 API 调用的"速度倒挂"问题

与传统 Agent 框架的区别

维度	传统 Agent 框架	V-Core
隐喻层级	软件层 / OS 层	硬件体系结构层
LLM 角色	内核 / 决策者	CPU / 执行者
控制权	LLM 控制一切	调度器控制 LLM
可替换性	LLM 深度耦合	LLM 可随时替换

---

✨ 核心特性

• 🎯 精确控制：通过指令集精确控制 LLM 行为
• ⚡ 高性能：异步设计、多核并发、DMA 机制
• 🔌 可扩展：驱动模型支持动态添加外设
• 🔄 可替换：支持多种 LLM API 后端
• 🛡️ 健壮性：完善的中断和错误恢复机制

---

🏗️ 架构概览

┌─────────────────────────────────────────────────────────────┐
│                        CPU (LLM API)                        │
│                      [秒级延迟，最慢]                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ System Bus (HTTP)
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   主板 (Rust + tokio)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   调度器    │  │ 总线控制器  │  │ 中断控制器  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    北桥 (高速组件)                    │    │
│  │  内存控制器 │     MMU      │   L1 Cache   │          │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ Peripheral Bus (gRPC)
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                 南桥 (Python Daemon)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │    ALU     │  │  工具管理器  │  │  RAG 模块   │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    外设驱动                           │    │
│  │  网络搜索  │  网页爬虫  │  代码执行  │  文件I/O      │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ DMA Bus
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      存储层次                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  L1 Cache   │  │  RAM Disk   │  │  Vector DB  │          │
│  │  (语义缓存)  │  │   (tmpfs)   │  │  + SQLite   │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘

---

📁 项目目录结构

v-core/
├── README.md                   # 项目说明（本文件）
├── LICENSE                     # MIT 许可证
│
├── docs/                       # 📚 架构文档
│   ├── docs_plan.md            # 文档规划
│   ├── RFC-00-项目总览与文档索引.md
│   ├── RFC-01-设计哲学与架构原理.md
│   ├── RFC-02-计算核心架构.md
│   ├── RFC-03-指令集架构.md
│   ├── RFC-04-存储体系结构.md
│   ├── RFC-05-系统总线协议.md
│   ├── RFC-06-主板与芯片组架构.md
│   ├── RFC-07-流水线与执行引擎.md
│   ├── RFC-08-进程与调度模型.md
│   ├── RFC-09-中断系统.md
│   ├── RFC-10-ALU与协处理器.md
│   ├── RFC-11-外设与IO子系统.md
│   ├── RFC-12-工程规范与部署.md
│   ├── RFC-13-用户指南.md
│   ├── RFC-14-建设与维护指南.md
│   └── RFC-15-术语表与参考映射.md
│
├── config/                     # ⚙️ 配置文件
│   ├── default.yaml            # 默认配置
│   ├── development.yaml        # 开发环境配置
│   └── production.yaml         # 生产环境配置
│
├── crates/                     # 🦀 Rust Crates
│   ├── vcore-motherboard/      # 主板核心
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── main.rs
│   │       ├── scheduler/      # 调度器
│   │       ├── bus_controller/ # 总线控制器
│   │       ├── interrupt/      # 中断控制器
│   │       └── process_manager/# 进程管理器
│   │
│   ├── vcore-northbridge/      # 北桥模块
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── memory_controller/
│   │       ├── mmu/
│   │       └── cache/
│   │
│   ├── vcore-scheduler/        # 调度器
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── algorithm.rs    # 调度算法
│   │       └── context_switch.rs
│   │
│   ├── vcore-bus/              # 总线协议
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── message.rs      # 消息定义
│   │       ├── arbiter.rs      # 仲裁器
│   │       └── error.rs        # 错误处理
│   │
│   ├── vcore-memory/           # 内存管理
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── ramdisk.rs      # RAM Disk 接口
│   │       ├── allocator.rs    # 内存分配器
│   │       └── gc.rs           # 垃圾回收
│   │
│   ├── vcore-interrupt/        # 中断控制器
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── handler.rs      # 中断处理
│   │       └── vector_table.rs # 中断向量表
│   │
│   └── vcore-proto/            # Protocol Buffers
│       ├── Cargo.toml
│       └── src/
│           ├── lib.rs
│           └── generated/      # 生成的代码
│
├── python/                     # 🐍 Python 模块
│   └── vcore/
│       ├── __init__.py
│       ├── py.typed            # 类型标记
│       │
│       ├── southbridge/        # 南桥模块
│       │   ├── __init__.py
│       │   ├── daemon.py       # 守护进程
│       │   ├── grpc_server.py  # gRPC 服务
│       │   └── config.py       # 配置
│       │
│       ├── alu/                # ALU 模块
│       │   ├── __init__.py
│       │   ├── calculator.py   # 计算器
│       │   ├── executor.py     # 代码执行器
│       │   └── sandbox.py      # 沙盒环境
│       │
│       ├── peripherals/        # 外设驱动
│       │   ├── __init__.py
│       │   ├── base.py         # 基类
│       │   ├── web_search.py   # 网络搜索
│       │   ├── web_crawler.py  # 网页爬虫
│       │   ├── file_io.py      # 文件 I/O
│       │   └── code_exec.py    # 代码执行
│       │
│       ├── tools/              # 工具模块
│       │   ├── __init__.py
│       │   ├── rag.py          # RAG 模块
│       │   ├── decoder.py      # 译码器
│       │   └── compressor.py   # 压缩器
│       │
│       └── proto/              # 生成的 Proto 代码
│           ├── __init__.py
│           └── generated/
│
├── proto/                      # 📦 Protocol Buffers 定义
│   ├── bus.proto               # 总线消息
│   ├── alu.proto               # ALU 服务
│   └── peripheral.proto        # 外设服务
│
├── tests/                      # 🧪 测试
│   ├── integration/            # 集成测试
│   │   ├── test_process.rs
│   │   └── test_peripheral.py
│   └── e2e/                    # 端到端测试
│       └── test_full_flow.py
│
├── scripts/                    # 🔧 脚本
│   ├── setup.sh                # 环境设置
│   ├── build.sh                # 构建脚本
│   ├── test.sh                 # 测试脚本
│   └── deploy.sh               # 部署脚本
│
├── docker/                     # 🐳 Docker 配置
│   ├── Dockerfile.motherboard  # 主板镜像
│   ├── Dockerfile.southbridge  # 南桥镜像
│   └── docker-compose.yaml     # 编排配置
│
├── Cargo.toml                  # Rust 工作空间配置
├── Cargo.lock                  # Rust 依赖锁定
├── pyproject.toml              # Python 项目配置
└── .gitignore                  # Git 忽略配置

---

🚀 快速开始

环境要求

组件	版本要求
Rust	1.70+
Python	3.10+
Docker	24.0+
Docker Compose	2.20+

安装步骤

# 1. 克隆仓库
git clone https://github.com/vcore/v-core.git
cd v-core

# 2. 安装 Rust 依赖
cargo build

# 3. 安装 Python 依赖
pip install -e ".[dev]"

# 4. 启动服务
docker-compose up -d

# 5. 验证服务
curl http://localhost:8080/health

第一个任务

from vcore import VCoreClient

# 创建客户端
client = VCoreClient("http://localhost:8080")

# 创建进程
process = client.create_process(
    name="hello-world",
    description="我的第一个 V-Core 任务"
)

# 执行指令
result = process.execute("""
# INSTRUCTION: COMPUTE

## TASK
计算 1 到 100 的和

## OUTPUT_FORMAT
{
    "sum": "number"
}
""")

print(result)  # {"sum": 5050}

---

📖 文档导航

架构文档 (RFC)

文档	描述
RFC-00	项目总览与文档索引
RFC-01	设计哲学与架构原理
RFC-02	计算核心架构
RFC-03	指令集架构 (ISA)
RFC-04	存储体系结构
RFC-05	系统总线协议
RFC-06	主板与芯片组架构
RFC-07	流水线与执行引擎
RFC-08	进程与调度模型
RFC-09	中断系统
RFC-10	ALU 与协处理器
RFC-11	外设与 I/O 子系统
RFC-12	工程规范与部署
RFC-13	用户指南
RFC-14	建设与维护指南
RFC-15	术语表与参考映射

推荐阅读顺序

用户入门：RFC-00 → RFC-13 (用户指南) → RFC-03 (指令集)

开发者入门：RFC-00 → RFC-14 (建设与维护指南) → RFC-06 (主板架构)

完整理解：RFC-01 → RFC-15 顺序阅读

---

🛠️ 开发指南

构建项目

# 构建 Rust 组件
cargo build --release

# 构建 Python 组件
pip install -e ".[dev]"

# 生成 Protocol Buffers 代码
./scripts/build-proto.sh

# 构建所有
./scripts/build.sh

运行测试

# Rust 测试
cargo test

# Python 测试
pytest

# 所有测试
./scripts/test.sh

代码规范

• Rust: 使用 rustfmt 和 clippy
• Python: 使用 ruff 和 mypy
• Commit: 遵循 Conventional Commits

---

🤝 贡献指南

我们欢迎所有形式的贡献！

贡献方式

方式	描述
代码贡献	提交 PR 修复 bug 或添加功能
文档贡献	改进文档、添加示例
问题反馈	提交 Issue 报告 bug 或建议
讨论参与	参与 GitHub Discussions

开发流程

1. Fork 仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

---

📄 许可证

本项目采用 MIT 许可证。

---

🙏 致谢

V-Core 的设计受到以下工作的启发：

• CoALA - 认知架构框架
• MemGPT - 虚拟内存概念
• AIOS - LLM Agent 操作系统

---

V-Core: The Bare Metal of Agentic AI