Veyllo-Labs/VAF
GitHub: Veyllo-Labs/VAF
VAF 是一个跨平台自主智能体框架，将本地/云端 LLM 与丰富工具链、持久记忆和自动化能力整合在一起，解决用户在日常任务中需要多步推理与工具协作的问题。
Stars: 5 | Forks: 0
# VAF — Veyllo Agentic Framework
```
O)) O)) O))))))))
O)) O)))) O))
O)) O)) O)) O))
O)) O)) O)) O))))))
O)) O)) )))) O)) O))
O)))) O)) O))
O)) O))O)) (OO )
```
一个基于本地和云端 LLM 构建的自主智能体框架。VAF 可以作为桌面应用、无头服务器或终端界面运行——支持 Windows、macOS 和 Linux。
[](https://github.com/Veyllo-Labs/VAF/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) [](COMMERCIAL.md)
**双重许可：** 基于 [GNU AGPL-3.0](LICENSE) 免费开源，或者获取[商业许可](COMMERCIAL.md)以用于无 copyleft 限制的专有/SaaS 用途 — `legal@veyllo.io`。
**前置要求：** 需要 Git 进行克隆，以及一个 container runtime —— VAF 将用户、认证、设置和内存保留在 PostgreSQL/pgvector 容器中，因此必须安装一个才能完成设置并登录。这三个安装程序都会为您配置好引擎：Windows 会安装免费的 Rancher Desktop，macOS 会自动安装免费的 Colima（如果存在 Docker Desktop 则直接使用），Linux 会自动安装您发行版的 Docker（systemd + `docker` 用户组）。安装程序还会自动配置 Python 和 Node 本身。
## 从这里开始
选择您的路径：
| 您想要… | 前往 |
|---|---|
| 将 **VAF 作为**桌面应用、服务器或终端**运行** | 下方的[安装说明](#installation) |
| 将 **VAF 作为**库**进行构建**（将 agent 嵌入您的应用） | [docs/EMBEDDING.md](docs/EMBEDDING.md) · [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| **编写工具**（扩展 agent，并将其打包为 pip 包发布） | [vaf/tools/README.md](vaf/tools/README.md) · [docs/EMBEDDING.md](docs/EMBEDDING.md) |
| **为引擎做贡献**（核心 agent 循环） | [vaf/core/README.md](vaf/core/README.md) · [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
## 安装说明
**Windows:**
```
git clone https://github.com/Veyllo-Labs/VAF.git
cd VAF
.\install.bat
```
**macOS / Linux:**
```
git clone https://github.com/Veyllo-Labs/VAF.git && cd VAF
chmod +x install.sh && ./install.sh
```
安装程序会设置一个 Python venv，安装所有依赖项，准备 Web UI（在首次启动时构建），为您设置 container 引擎（Windows 上的 Rancher Desktop，macOS 上的 Colima，Linux 上发行版的 Docker —— 或者如果已存在则直接使用），并将 `vaf` 命令添加到您的 shell 中。
**安装模式** — 在 **Linux** 上，安装程序会询问一次（macOS 和 Windows 始终安装桌面模式）：
```
[1] Desktop — personal use, local only, system tray (default)
[2] Server — always-on service, LAN accessible via HTTPS, starts at boot
```
对于家庭服务器、NAS 设备，或任何需要从其他设备访问的无头机器，请选择 **[2] Server**。详情请参阅 [docs/setup/SERVER_MODE.md](docs/setup/SERVER_MODE.md)。
## 快速开始
使用单次 prompt 确认安装是否成功：
```
vaf prompt "Hello"
```
然后使用 `vaf tray` 启动桌面应用（系统托盘 + 位于 `http://localhost:3000` 的 Web UI），或者使用 `vaf run` 启动交互式终端聊天。有关运行 VAF 的所有方式，请参见[运行模式](#modes)。
## 更新
VAF 会就地更新到最新发布的版本：
```
vaf update # Stop, fetch the latest release, reinstall, migrate, restart
vaf update check # Check whether a newer version is available
```
`vaf update` 仅在干净的工作区中执行，会记录回滚点，如果任何步骤失败则会自动回滚。启动时会出现一行“有可用更新”的提示（可通过 `config.json` 中的 `update_check_on_start` 禁用）。发布版本的维护者：请参见 [docs/setup/RELEASING.md](docs/setup/RELEASING.md)。
## 运行模式
VAF 根据您的使用场景分为三种模式运行。
### 桌面模式（推荐个人使用）
桌面应用 —— 系统托盘图标 + agent 窗口，Web UI 位于 `http://localhost:3000`。最简单的启动方式：双击安装程序创建的 **VAF Agent** 快捷方式，或者运行：
```
vaf tray # Start the desktop app (tray + web UI)
```
或者将其作为后台服务进行管理：
```
vaf start # Start in background
vaf stop # Stop cleanly
vaf restart # Restart
vaf status # Show status
```
**局域网访问**（您网络上的其他设备）：
```
vaf server on # Bind to 0.0.0.0 with HTTPS
vaf server off # Back to localhost only
vaf server status # Show active URLs
```
### 服务器模式（常驻运行，开机自启）
通过 **[2] Server** 选项安装。VAF 作为 systemd 用户服务运行 —— 使用相同的命令：
```
vaf start # systemctl --user start vaf
vaf stop # systemctl --user stop vaf
vaf restart # systemctl --user restart vaf
vaf status # systemctl --user status vaf
```
局域网访问（端口 8443 上的 HTTPS）始终启用并在服务器模式下锁定。请参见 [docs/setup/SERVER_MODE.md](docs/setup/SERVER_MODE.md)。
### 终端模式 (CLI)
在终端中进行交互式聊天，支持主题、会话管理和流式输出。
```
vaf run # Start interactive chat
vaf run --session # Resume a saved session
vaf run --classic # Minimal interface (SSH / low-bandwidth)
vaf run --no-web # Skip starting the web UI
```
单次执行（非交互式）：
```
vaf prompt "Explain async/await in Python"
vaf prompt "List modified files" --output-format json
```
### 仅 Web UI
如果您只需要 Web 界面而不需要托盘：
```
vaf run --web
```
## 模型
VAF 支持**本地 GGUF 模型**和**云端 API**。首次启动时，它会自动下载默认模型和 llama-server 后端。
**本地（隐私优先）：**
- 任何 GGUF 模型（Llama 3、Mistral、Qwen、DeepSeek 等）
- GPU 加速：Windows 上的 CUDA，Linux 上的 Vulkan，macOS 上的 Metal
- 最小上下文：32 768 tokens（强制执行；使用工具时必需）
**云端 API：**
- Veyllo
- OpenAI
- Anthropic
- Google
- DeepSeek
- OpenRouter（100 多种模型）
在运行时切换 provider 或模型：在聊天中按 `C`，或使用 `/model `。
## 功能
**Agent 与工具**
- 100 多种内置工具：网页搜索、文件系统、bash、Python 执行、日历、电子邮件、GitHub 等
- 用于长时间运行任务的子 agent：Coder、Researcher、Librarian
- 用于执行不受信任代码的 Docker 沙箱
- 定时自动化（每日新闻、提醒事项、报告）
**记忆**
- 具备语义搜索的持久长期记忆（pgvector + Redis）
- 上下文填满时自动压缩；完整历史记录已归档且可恢复
- Web UI 中的记忆图谱可视化
**会话与历史**
- 命名会话，可保存且可搜索
- 基于代码更改的 Git 快照/撤销
- 将会话导出为 Markdown
**集成**
- Telegram、Discord、WhatsApp（桥接模式）
- Google Calendar、Gmail、Google Drive
- GitHub
**开发者**
- 插件系统：将 `BaseTool` 子类放入 `vaf/tools/` —— 启动时自动发现
- 自定义 workflow：将 `WORKFLOW` 字典放在 `~/.vaf/workflows/*.py` 中 —— 自动加载
- 支持 MCP (Model Context Protocol) 客户端
## CLI 参考
```
vaf start # Start background service (or: systemctl in server mode)
vaf stop # Stop background service
vaf restart # Restart background service
vaf status # Show service status
vaf run # Interactive chat (TUI)
vaf prompt "..." # One-shot prompt
vaf tray # Background service + web UI (foreground)
vaf server on|off|status
vaf update # Update to the latest release
vaf update check # Check if a newer release is available
vaf session list|load|delete|export|search
vaf snapshot create|list|restore|undo
vaf automation list|create|run|enable|disable|delete
vaf scaffold new # Project templates
vaf generate api|function|class|test|component
vaf automate test|build|lint|format|check
vaf debug explain|trace|fix
vaf git commit --auto
vaf models list|set
vaf theme
vaf install-gpu # Re-detect and install GPU backend
vaf info # System info
vaf --version
```
## 配置
所有用户数据都位于 `~/.vaf/` 中：
```
~/.vaf/
├── config.json # Settings (provider, model, n_ctx, ...)
├── sessions/ # Saved conversations
├── context_archive/ # Compressed conversation history
├── snapshots/ # Code undo history
├── automations/ # Scheduled tasks
└── workflows/ # Custom workflow plugins (*.py)
```
核心配置项（`config.json`）：
| 键 | 默认值 | 描述 |
|-----|---------|-------------|
| `provider` | `local` | `local`, `veyllo`, `openai`, `anthropic`, `google`, `deepseek`, `openrouter` |
| `n_ctx` | `32768` | 上下文窗口（工具使用最低需 32 768） |
| `gpu_layers` | `99` | 卸载到 GPU 的层数（`0` = 仅使用 CPU） |
| `web_ui_enabled` | `true` | 与 agent 一起启动 Web UI |
| `persist_server` | `false` | 在 VAF 退出后保持 llama-server 运行 |
## 扩展 VAF
**自定义工具** — 创建 `vaf/tools/my_tool.py`：
```
from vaf.tools.base import BaseTool
class MyTool(BaseTool):
name = "my_tool"
description = "One-line description the agent uses to decide when to call this."
parameters = {
"type": "object",
"properties": {
"query": {"type": "string"}
},
"required": ["query"]
}
def run(self, **kwargs) -> str:
return f"result for {kwargs['query']}"
```
**自定义 workflow** — 创建 `~/.vaf/workflows/my_workflow.py`：
```
WORKFLOW = {
"name": "My Workflow",
"triggers": ["my keyword"],
"variables": {"topic": "What to process"},
"steps": [
{"tool": "web_search", "input": "{topic}", "output": "results"},
{"tool": "coding_agent", "input": "Based on {results}, write code for {topic}", "output": "code"},
],
}
```
两者都会在启动时自动发现 —— 无需注册。
## 平台说明
| | Windows | macOS | Linux |
|---|---|---|---|
| 桌面模式 | 托盘图标 | 菜单栏图标 | 无头模式（无图标） |
| GPU 后端 | CUDA | Metal | Vulkan |
| Web UI | `localhost:3000` | `localhost:3000` | `localhost:3000` |
| 安装 | `install.bat` | `install.sh` | `install.sh` |
Linux 无头模式不需要显示服务器。详情请参见 [docs/setup/LINUX_SETUP.md](docs/setup/LINUX_SETUP.md)。
## 文档
| 主题 | 文档 |
|---|---|
| 基于 VAF 构建（作为库嵌入） | [docs/EMBEDDING.md](docs/EMBEDDING.md) |
| 架构（框架与外壳） | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| 配置参考（所有配置项） | [docs/setup/CONFIG_SCHEMA.md](docs/setup/CONFIG_SCHEMA.md) |
| 编写工具（BaseTool，pip 打包） | [vaf/tools/README.md](vaf/tools/README.md) |
| 服务器模式（局域网，自启动） | [docs/setup/SERVER_MODE.md](docs/setup/SERVER_MODE.md) |
| Linux 设置与 GPU | [docs/setup/LINUX_SETUP.md](docs/setup/LINUX_SETUP.md) |
| LLM 后端（本地对比 API） | [docs/llm/LLM_BACKEND_FACTS.md](docs/llm/LLM_BACKEND_FACTS.md) |
| 记忆系统 | [docs/memory/MEMORY_SYSTEM.md](docs/memory/MEMORY_SYSTEM.md) |
| Web UI 与 API 参考 | [docs/web-ui/WEB_UI.md](docs/web-ui/WEB_UI.md) |
| 上下文管理 | [docs/memory/CONTEXT_MANAGEMENT.md](docs/memory/CONTEXT_MANAGEMENT.md) |
| 自动化任务 | [docs/platform/AUTOMATIONS.md](docs/platform/AUTOMATIONS.md) |
| Docker 服务 | [docs/setup/DOCKER_SERVICES.md](docs/setup/DOCKER_SERVICES.md) |
| Telegram / Discord / WhatsApp | [docs/integrations/TELEGRAM_INTEGRATION.md](docs/integrations/TELEGRAM_INTEGRATION.md) |
| Workflows | [vaf/workflows/README.md](vaf/workflows/README.md) |
## 许可证
[](LICENSE) [](COMMERCIAL.md)
VAF 是**双重许可**的：
- **开源 — [GNU AGPL-3.0-or-later](LICENSE)**：可免费使用、修改和分发。如果您将 VAF 作为网络服务 (SaaS) 分发或运行**修改过**的版本，您必须根据 AGPL 公开您的源代码。未经修改的内部使用 —— 即使是商业用途 —— 也不会触发披露机制。在 VAF 之上构建插件、工具和 Workflows 被明确允许（第 7 条附加许可）。
- **商业许可**：用于将 VAF 嵌入闭源产品或运行无 AGPL copyleft 限制的专有 SaaS。请参见 **[COMMERCIAL.md](COMMERCIAL.md)**。
有关完整的双重许可说明（英语和德语）以及如何选择，请参见 **[LICENSING.md](LICENSING.md)**。
**商标与品牌：** “VAF”、“Veyllo”、VAF 徽标以及 agent 头像（动态点视觉标识及其动画状态）是 Veyllo GmbH 的商标和品牌资产，**不受**代码许可证的约束。请参见 [LICENSING.md](LICENSING.md) 中的“商标与品牌资产”部分。
如需商业和 OEM 许可，请联系 **legal@veyllo.io** · **https://veyllo.io**。
标签：AI智能体, DLL 劫持, MITM代理, PostgreSQL, Python, 大语言模型, 实时告警, 搜索引擎查询, 无后门, 测试用例, 自主代理框架, 请求拦截, 跨平台桌面应用, 逆向工具