内容
# NevoFlux 代理
AI 驱动的浏览器助手，具备原生计算机控制能力。
## 功能
- **浏览器自动化**：通过扩展程序实现浏览器完全控制 - 导航、点击、输入、填充、截图、JavaScript 执行、辅助功能树快照
- **计算机控制**：Linux（X11）、macOS 和 Windows 的截图、鼠标、键盘支持
- **MCP 集成**：通过模型上下文协议（stdio 传输）与 Claude Code 协同工作
- **MCP 管理器**：连接外部 MCP 服务器，具备自动重新连接和健康监测功能
- **原生消息传递**：通过 ZeroMQ 在浏览器扩展程序和守护进程之间建立安全桥梁
- **LLM 集成**：Anthropic、OpenAI、OpenRouter、DeepSeek、Qwen、Gemini、Groq、Ollama、Mistral、xAI、Cohere、Perplexity、Together - 以及子进程/ACP 代理（Claude Code、Gemini CLI、OpenClaw）
- **WASM 技能**：使用 WebAssembly 模块的可扩展技能系统，支持主机函数
- **会话管理**：使用 SQLite 的持久化会话存储，具备自动清理策略
- **热配置加载**：配置文件监听，支持自动更新
- **工具搜索**：跨注册表发现工具的 BM25 文本搜索
- **API 密钥管理**：分层查找（环境、密钥环、配置文件）
## 安装
### 前提条件
- Rust 1.91.0（通过 `rust-toolchain.toml` 固定）
- Linux：X11 显示服务器（Wayland 暂不支持）
- macOS：计算机控制需要辅助功能权限
- Windows：原生消息主机安装需要管理员权限
### 从源码构建
```bash
git clone https://github.com/nevoflux-browser/nevoflux-agent
cd nevoflux-agent
cargo build --release
```
可执行文件将在 `target/release/nevoflux-agent` 处可用。
> 可执行文件名为 **`nevoflux-agent`**。下面的示例使用 `nevoflux` 作为简写 - 可以为其设置别名（`alias nevoflux=nevoflux-agent`），或直接输入完整名称。
### 使用 justfile
开发任务通过 `just` 自动化：
```bash
just build # 构建所有 crate
just release # 构建发布版本
just test # 运行所有测试
just ci # 完整的 CI（格式检查 + clippy + 测试）
just daemon # 运行守护进程，启用详细日志
just mcp # 运行 MCP 服务器
just status # 检查守护进程状态
just stop # 停止运行的守护进程
just fmt # 格式化代码
just lint # 运行 clippy
just doc # 生成文档
just clean # 清理构建产物
```
### 安装原生消息主机
```bash
# Linux/macOS
./install/native-host/setup.sh $(pwd)/target/release/nevoflux YOUR_EXTENSION_ID chrome
# Windows（以管理员身份运行 PowerShell）
.\install\native-host\setup.ps1 -BinaryPath "$PWD\target\release\nevoflux.exe" -ExtensionId "YOUR_EXTENSION_ID" -Browser chrome
```
## 使用
### 启动守护进程
```bash
nevoflux --daemon # 启动守护进程
nevoflux --daemon --verbose # 启用详细日志
```
### 检查状态
```bash
nevoflux --status
```
### 停止守护进程
```bash
nevoflux --stop
```
### MCP 模式（适用于 Claude Code）
```bash
nevoflux --mcp
```
将以下内容添加到您的 Claude Code MCP 配置中：
```json
{
"mcpServers": {
"nevoflux": {
"command": "/path/to/nevoflux",
"args": ["--mcp"]
}
}
}
```
### 配置管理
```bash
nevoflux config init # 创建默认配置
nevoflux config show # 显示当前配置
nevoflux config get llm.provider # 获取特定值
nevoflux config set llm.provider qwen # 设置值
nevoflux config list daemon. # 按前缀列出
nevoflux config delete key # 删除值
```
### 交互式设置
```bash
nevoflux setup
```
### 其他命令
```bash
nevoflux pack list # 管理能力包（验证/检查/安装/…）
nevoflux completions bash # 生成 shell 补全
```
服务器/部署标志 - `--headless`、 `--http-addr`、 `--openai-addr`、 `--mcp-addr`、`--acp-addr` - 在 [无头部署](#无头部署docker) 中涵盖。
## 无头部署（Docker）
以 **容器化服务** 运行 NevoFlux 代理 - 无需 GUI。`nevoflux/agent` 镜像包含守护进程和无头浏览器，并提供 HTTP **任务 API**、**OpenAI 兼容的** `/v1/chat/completions` 端点和可选的 **MCP** / **ACP** 接口。每个任务驱动一个真实的浏览器（自动化 + 计算机使用 + shell/fs 工具），并带有内置的知识库 - 因此“无头”仅是部署模式，而不是它执行的操作范围。
该镜像从 `deploy/headless/` 构建，并从 **GitHub 下载预构建的版本** - 无需本地编译：
```bash
docker build -t nevoflux/agent:latest deploy/headless # amd64 或 arm64
cd deploy/headless && docker compose up -d # 长时间运行的服务
# 提交浏览器任务
curl -s localhost:8080/tasks -H 'Content-Type: application/json' \
-d '{"task":"open example.com and report the title","mode":"browser"}'
# OpenAI 兼容的端点：POST localhost:8080/v1/chat/completions
```
值得注意的模式（完整指南见 [`deploy/headless/README.md`](deploy/headless/README.md)）：
- **会话模式** (`NEVOFLUX_SESSION_MODE=1`)：在任务流程中重用一个温暖的浏览器 + 配置文件克隆（任务之间软重置）；以任务中的 `{"end_session":true}` 或 `POST /session/close` 结束。 将配置文件保存回基础配置文件，带有 `save_profile` 标志 / `POST /session/close {"save":true}`。
- **固定脚本模式** (`NEVOFLUX_HEADLESS_SCRIPT=…`)：运行确定性的 Python 流而不是 LLM 代理循环（参见 `deploy/headless/examples/`）。
- **每个容器一个任务** （不信任的工作负载）：`docker compose --profile oneshot run …`。
- **实时查看**：`http://localhost:6080/vnc.html` 处的 noVNC，启用 `NEVOFLUX_VNC=1`。
版本默认为最新版本；使用 `--build-arg AGENT_VERSION=vX.Y.Z --build-arg BROWSER_VERSION=X.Y.Z` 固定版本。 要从本地/未发布的二进制文件构建，请使用 `deploy/headless/Dockerfile.local` （基于 COPY）。 任务 API 和会话模式的帮助脚本位于 `deploy/headless/examples/`。
## 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ NevoFlux 代理 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────────────────┐ │
│ │ Claude │ │ 浏览器 │ │ 主二进制文件 │ │
│ │ Code │ │ 扩展程序 │ │ (nevoflux) │ │
│ └─────┬─────┘ └─────┬─────┘ └───────────┬───────────┘ │
│ │ │ │ │
│ │ stdio │ 原生 │ │
│ │ │ 消息传递 │ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────────────────┐ │
│ │ MCP │ │ 桥梁 │ │ 守护进程 │ │
│ │ 服务器 │◄──►│ (ZeroMQ) │◄──►│ (核心引擎) │ │
│ └───────────┘ └───────────┘ └───────────┬───────────┘ │
│ │ │
│ ┌───────────┴───────────┐ │
│ │ │ │
│ ┌─────▼─────┐ ┌─────────────┐ │
│ │ WASM │ │ 计算机 │ │
│ │ 技能 │ │ 控制 │ │
│ └───────────┘ └─────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 共享 crate │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │
│ │ │协议 │ │ 存储 │ │ LLM │ │ 测试 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────┘
```
### Crate 结构
| Crate | 描述 |
|-------|-------------|
| `nevoflux` | 带有 CLI 接口的主二进制文件 |
| `nevoflux-daemon` | 核心守护进程：会话、WASM 运行时、代理运行器、权限 |
| `nevoflux-mcp` | MCP 服务器/客户端、工具、外部服务器管理器 |
| `nevoflux-bridge` | 浏览器和守护进程之间的原生消息传递桥梁 |
| `nevoflux-protocol` | 共享消息类型和序列化（JSON/MessagePack） |
| `nevoflux-storage` | 基于 SQLite 的持久化存储 |
| `nevoflux-llm` | LLM 提供商抽象（Anthropic、OpenAI、Gemini、DeepSeek、Qwen、… + ACP/CLI 代理） |
| `nevoflux-computer` | 跨平台计算机控制（截图、鼠标、键盘） |
| `nevoflux-skills` | WASM 技能加载和管理 |
| `nevoflux-builtin-wasm` | 内置 WASM 技能模块 |
| `nevoflux-testing` | 测试工具、模拟器和夹具 |
| `nevoflux-brain` | 知识/记忆引擎 |
| `nevoflux-llm-gateway` | 进程内 OpenAI 兼容的 LLM + 嵌入网关 |
| `nevoflux-pack` | 包（能力包）安装 + 生命周期 |
## MCP 工具
### 浏览器工具
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| `browser_navigate` | 导航到 URL | `url` |
| `browser_click` | 按选择器点击元素 | `selector` |
| `browser_type` | 在元素中输入文本 | `selector`, `text`, `clear?` |
| `browser_fill` | 填充表单字段（先清除） | `selector`, `value` |
| `browser_screenshot` | 捕获页面截图 | `full_page?` |
| `browser_get_content` | 获取页面/元素文本 | `selector?` |
| `browser_eval_js` | 执行 JavaScript | `script` |
| `browser_wait_for` | 等待元素 | `selector`, `timeout_ms?` |
| `browser_scroll` | 滚动页面 | `direction`, `amount?` |
| `browser_get_element` | 获取元素信息 | `selector` |
| `browser_query_all` | 查询所有匹配的元素 | `selector` |
| `browser_get_elements` | 获取所有匹配的元素信息 | `selector` |
| `browser_click_by_id` | 按快照 ID 点击 | `element_id` |
| `browser_fill_by_id` | 按快照 ID 填充 | `element_id`, `value` |
| `browser_type_by_id` | 按快照 ID 输入 | `element_id`, `text` |
| `browser_get_markdown` | 提取页面为 Markdown | - |
### 计算机工具
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| `computer_screenshot` | 捕获屏幕 | `monitor?` |
| `computer_mouse_move` | 移动光标（无点击） | `x`, `y` |
| `computer_click` | 在位置点击 | `x`, `y`, `button?`, `click_type?` |
| `computer_type_text` | 输入文本 | `text`, `delay_ms?` |
| `computer_key` | 按键盘键 | `key`, `modifiers?`, `repeat?` |
| `computer_scroll` | 在位置滚动 | `x`, `y`, `direction`, `amount?` |
| `computer_drag` | 在位置之间拖动 | `start_x`, `start_y`, `end_x`, `end_y`, `button?` |
| `computer_cursor_position` | 获取光标位置 | - |
| `computer_mouse_down` | 按住按钮 | `x`, `y`, `button?` |
| `computer_mouse_up` | 释放按钮 | `x`, `y`, `button?` |
| `computer_hold_key` | 按住键一段时间 | `key`, `duration_ms`, `modifiers?` |
| `computer_wait` | 等待一段时间 | `ms` |
### 代理工具
| 工具 | 描述 | 参数 |
|------|-------------|------------|
| `agent_chat` | 向 AI 发送消息 | `message`, `context?` |
### 内置代理工具
| 工具 | 描述 |
|------|-------------|
| `read_file` | 读取文件内容 |
| `write_file` | 写入文件内容 |
| `list_files` | 列出目录内容 |
## 配置
配置文件：`~/.config/nevoflux/config.toml`
### 示例配置
```toml
[daemon]
port_range_start = 19500
port_range_end = 19600
idle_timeout_secs = 1800
heartbeat_timeout_secs = 30
heartbeat_interval_secs = 10
max_concurrent_requests = 100
keep_alive_for_mcp = true
[daemon.session]
max_sessions = 500
inactive_days = 90
max_storage_mb = 500
auto_create = true
[daemon.context]
system_prompt_reserve = 2000
safety_margin = 500
max_history_messages = 50
include_memory = true
include_current_page = true
[llm]
default_provider = "anthropic"
default_model = "claude-sonnet-4-20250514"
max_tokens = 32768
temperature = 0.7
timeout_secs = 120
max_retries = 3
[storage]
max_size_mb = 1024
wal_mode = true
vacuum_on_startup = false
[logging]
level = "info"
stdout = true
json_format = false
```
### 环境变量
```bash
# LLM 提供商 API 密钥
ANTHROPIC_API_KEY # Anthropic Claude
OPENAI_API_KEY # OpenAI GPT
DASHSCOPE_API_KEY # Qwen (Alibaba)
DEEPSEEK_API_KEY # DeepSeek
OPENROUTER_API_KEY # OpenRouter
# NevoFlux 设置
NEVOFLUX_DATA_DIR # 覆盖数据目录
RUST_LOG # 日志级别/过滤器（例如 info, debug, nevoflux_daemon=trace）
NEVOFLUX_SESSION_MODE # 无头：重用一个浏览器跨任务流（参见无头部署）
ORT_DYLIB_PATH # libonnxruntime 的路径（嵌入式功能，动态加载构建）
```
## 开发
### 运行测试
```bash
just test # 所有测试
cargo test -p nevoflux-daemon # 单个 crate
cargo test test_name -- --nocapture # 特定测试
```
### 测试基础设施
`nevoflux-testing` crate 提供：
- `MockLlmProvider` - 虚假 LLM 响应用于测试
- `MockMcpClient` - 虚假 MCP 服务器用于测试
- `MockPermissionChecker` - 可配置的权限响应
- `TestDaemonBuilder` - 构建测试守护进程实例
- 使用 `proptest` 的属性测试协议层
### 校验和格式化
```bash
just lint # 运行 clippy
just fmt # 格式化代码
just ci # 完整的 CI 检查
```
### 生成文档
```bash
just doc # 生成并打开文档
```
### 构建发布版本
```bash
just release
```
## 平台说明
### Linux
- 需要 X11 显示服务器用于计算机控制
- Wayland 支持尚未实现
- 安装 `xdotool` 以增强输入模拟（可选）
### macOS
- 需要辅助功能权限用于鼠标/键盘控制
- 通过系统偏好设置 > 安全和隐私 > 隐私 > 辅助功能授予
### Windows
- 需要管理员权限进行原生消息主机注册
- 使用 Windows API 进行屏幕捕获和输入模拟
## 故障排除
### 守护进程问题
```bash
nevoflux --status # 检查当前状态
nevoflux --stop # 清理陈旧文件
```
### WASM 错误
确保 wasmtime 兼容性（需要版本 27）。
### Linux 显示问题
计算机控制需要 X11。检查：
```bash
echo $XDG_SESSION_TYPE # 应该是 "x11"
```
## 许可证
AGPL-3.0
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器