内容
# 智能代理
<p align="center">
<strong>开源 AI 编程代理 — 终端 · 桌面 · 网页</strong>
<br>
<a href="https://github.com/wjb12387767/nexus-agent">github.com/wjb12387767/nexus-agent</a>
<br><br>
<em>English</em> · <a href="./README.zh-CN.md">简体中文</a>
</p>
<p align="center">
<a href="https://github.com/wjb12387767/nexus-agent/blob/main/LICENSE"><img src="https://img.shields.io/github/license/wjb12387767/nexus-agent?style=flat&colorA=222222&colorB=58A6FF" alt="License"></a>
<a href="https://github.com/wjb12387767/nexus-agent/releases"><img src="https://img.shields.io/github/v/release/wjb12387767/nexus-agent?include_prereleases&style=flat&colorA=222222&colorB=58A6FF" alt="Release"></a>
<a href="https://github.com/wjb12387767/nexus-agent/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/wjb12387767/nexus-agent/ci.yml?branch=main&style=flat&colorA=222222&colorB=58A6FF" alt="CI"></a>
<a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&colorA=222222&logo=typescript&logoColor=white" alt="TypeScript"></a>
<a href="https://www.rust-lang.org"><img src="https://img.shields.io/badge/Rust-DEA584?style=flat&colorA=222222&logo=rust&logoColor=white" alt="Rust"></a>
<a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f472b6&style=flat&colorA=222222" alt="Bun"></a>
<a href="https://ghcr.io/wjb12387767/nexus-agent"><img src="https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat&colorA=222222&logo=docker&logoColor=white" alt="Docker"></a>
</p>
<p align="center">
<em>Forked from <a href="https://github.com/can1357/oh-my-pi">Oh My Pi (omp)</a> · absorbs capabilities from <a href="https://github.com/xai-org/grok-build">Grok Build</a>, <a href="https://github.com/Gitlawb/openclaude">OpenClaude</a> & hermes-agent</em>
</p>
---
## 概述
智能代理是一个开源的 AI 编程代理，它融合了四个旗舰开源编程代理 — **omp**、**Grok Build**、**OpenClaude**、**hermes-agent** — 到一个单一的工程基线。目标不是“又一个代理”，而是保留每个项目不可或缺的能力层，同时消除它们各自的缺点。
| 来源 | 角色 | 不可或缺的能力 |
|---|---|---|
| **omp** | 基础 | 60+ 工具 · Hashline 编辑协议 · 50+ 提供商 · Mnemopi 内存 · LSP+DAP · 多语言评估 · 协作 |
| **Grok Build** | 移植 | 操作系统级沙盒 (Landlock / Seatbelt) · 检查点回滚 · 多级压缩 |
| **OpenClaude** | 移植 | gRPC 服务器 · VS Code 扩展 · 每个代理的模型路由 · Bash AST 安全遍历 |
| **hermes-agent** | 移植 | 自我改进循环（后台审查 + 审查者 + 学习 + 学习图） |
结果是一个单一的 CLI 入口点 `nexus`，在 MIT 许可下发布，结合了工业级安全、服务部署和广泛的模型/工具覆盖。
## 三种形式，一个内核
智能代理有三种形式，它们都共享相同的 **代理内核**，具有相同的能力：
| 形式 | 入口 | 目标用户 |
|---|---|---|
| **终端** | `nexus` CLI | 开发人员（完全权力，可脚本化） |
| **桌面** | WorkAny 应用（Tauri + React） | 非技术用户（图形用户界面，通过子进程桥接相同内核） |
| **网页** | collab-web（浏览器） | 快速预览，协作会话 |
桌面应用 **不** 减少任何能力 — 它将 `nexus` CLI 作为子进程启动，并将 JSON 事件桥接到用户界面。所有工具、沙盒、检查点、MCP、技能和自我改进功能在所有三种形式中都可用。
## 架构
智能代理使用 **TS + Rust NAPI 混合架构**：
| 层 | 语言 | 角色 |
|---|---|---|
| 应用 | TypeScript 7.0 | 代理循环 · 工具编排 · TUI · 协议适配 · 业务逻辑 |
| 性能 | Rust（稳定版） | 文件遍历 · grep/glob · AST 解析 · 令牌计数 · Shell · PTY · 沙盒 · 检查点 |
| 绑定 | napi-rs 3.0 | Rust ↔ JS 跨语言调用（`.node` 本地模块） |
运行时：[Bun](https://bun.sh) ≥ 1.3.14。Rust 工具链：稳定版 ≥ 1.92.0（**不支持 nightly** — 导致 NAPI 兼容性问题）。
### 硬化层
在四重融合的基础上添加了五个功能，解决了所有上游代理的已知缺点：
| 能力 | 效果 | 位置 |
|---|---|---|
| **Bash AST 安全** | tree-sitter-bash AST 白名单，带有 `varScope` 跟踪和 `declare -n` nameref 检测，层叠在正则表达式批准器之前。失败关闭。 | [`packages/nexus-bash-ast/`](./packages/nexus-bash-ast) · [`crates/pi-natives/src/bash_ast.rs`](./crates/pi-natives/src/bash_ast.rs) |
| **Doom 环检测** | 重复 `(tool, args)` 调用跨回合的滑动窗口检测器。 | [`packages/agent/src/doom-loop-detector.ts`](./packages/agent/src/doom-loop-detector.ts) |
| **破坏性回归套件** | E2E 测试：沙盒拒绝越界写入，检查点恢复，reflink CoW 隔离。 | [`packages/coding-agent/test/integration/destructive-regression.test.ts`](./packages/coding-agent/test/integration/destructive-regression.test.ts) |
| **工具防护** | 失败跟踪防护层叠在 doom-loop 检测器上：分类精确/相同工具/无进展模式。 | [`packages/agent/src/doom-loop-detector.ts`](./packages/agent/src/doom-loop-detector.ts) |
| **文件安全** | 凭证路径保护（`.ssh` / `.aws` / `.gnupg` / `.kube` / `.docker` / `.azure` / `.env` / `.netrc` / `.pgpass` / `.git-credentials`）和 `.env` 读取拦截。 | [`packages/coding-agent/src/tools/file-safety.ts`](./packages/coding-agent/src/tools/file-safety.ts) |
### 自我改进层
融合自 **hermes-agent**。四个功能形成一个 **自我改进循环**：`learn`（引导式技能创作）→ `background review`（每回合自动评估）→ `curator`（生命周期管理）→ `learning graph`（可视化）。所有 **可选**（默认关闭）。
## 安装
### A. Docker（推荐，无工具链）
```sh
docker pull ghcr.io/wjb12387767/nexus-agent:1.0.0-beta
docker run --rm -it -v "$PWD":/work ghcr.io/wjb12387767/nexus-agent:1.0.0-beta cli
```
全栈模式（代理 + Qdrant + Docling + LightRAG 通过 docker compose）：
```sh
git clone https://github.com/wjb12387767/nexus-agent.git
cd nexus-agent
cp .env.example .env # 填写 LLM 凭证
docker compose up -d
docker compose exec nexus cli
```
### B. 源代码构建（macOS / Linux）
**前提条件**：Bun ≥ 1.3.14，Rust ≥ 1.92.0 稳定版
```sh
git clone https://github.com/wjb12387767/nexus-agent.git
cd nexus-agent
curl -fsSL https://bun.sh/install | bash # 如果 Bun 未安装
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 如果 Rust 未安装
rustup default stable # 不要使用 nightly
bun setup # 安装依赖 + 构建本地附加组件 + 链接 CLI
nexus # 启动
```
首次构建编译 Rust NAPI 模块（~10–20 分钟）。后续启动是即时的。
### C. Windows 启动器
```powershell
.\start.ps1 # 自动安装工具链 + 构建 + 启动
.\start.ps1 -CheckOnly # 检查 Bun / Rust 可用性
.\start.ps1 -SkipBuild # 跳过本地模块编译
```
`start.ps1` 是 UTF-8 with BOM 编码的，以确保在 Windows 上正确显示中文。对于 Windows 上的完整 Linux 功能（Landlock 沙盒，reflink 检查点，原生 bash），请使用 WSL2：
```bash
nexus wsl status # 检测 WSL2 可用性
nexus wsl launch # 在 WSL2 中启动代理
nexus wsl install # 打印 WSL 安装说明
```
### D. 桌面应用（WorkAny）
桌面应用是 [`workany-dev/`](./workany-dev/workany-dev/) 中的 Tauri + React 应用。它将 `nexus` CLI 作为子进程启动 — **无能力减少** 与终端相比。
**当前状态**：预构建的安装程序（`.dmg` / `.msi` / `.exe` / `.deb` / `.rpm`）尚未发布到 GitHub Releases。从源代码构建：
```sh
cd workany-dev/workany-dev
bun install
pnpm install
# 为当前平台构建（捆绑 nexus CLI + workany-api 边车 + Tauri 应用）
pnpm build:nexus
# 或针对特定平台：
pnpm build:nexus:mac-arm
pnpm build:nexus:linux
pnpm build:nexus:windows
```
前提条件：Bun，Rust 稳定版，Node.js 20+，pnpm 9+。在 Linux 上：`libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf libfuse2`。
### E. 网页（collab-web）
网页客户端提供基于浏览器的 nexus 协作会话视图 — 流式传输记录、工具调用卡、子代理面板和合成器：
```sh
bun run collab:web:dev # 开发服务器，位于 http://localhost:3000
```
参见 [`packages/collab-web/README.md`](./packages/collab-web/README.md) 获取详细信息。
## 配置
智能代理从三个层读取配置（后者覆盖前者）：
1. **默认值** — 编译到 [`settings-schema.ts`](./packages/coding-agent/src/config/settings-schema.ts)
2. **用户配置** — `~/.nexus/agent/config.yml`（通过 `nexus config` 编辑）
3. **项目配置** — 项目根目录中的 `.nexus/` 目录
关键默认值（所有 **开启** 默认）：
| 选项 | 效果 | 默认值 |
|---|---|---|
| `sandbox.enabled` | 操作系统级 bash 隔离（Landlock / Seatbelt / ISO FS） | `true` |
| `checkpoint.enabled` | 会话检查点 / 回滚 | `true` |
| `checkpoint.autoEnabled` | 在 `bash` / `edit` / `write` 之前自动文件级检查点 | `true` |
| `bash.astSecurity` | Bash AST 白名单，层叠在正则表达式批准器之前 | `true` |
| `astGrep.enabled` | AST 结构化代码搜索 | `true` |
| `bashInterceptor.enabled` | 拦截 `cat`/`grep`/`find`/`sed`，路由到专用工具 | `true` |
## MCP 集成（可选）
智能代理支持深度 MCP（模型上下文协议）集成。这些是 **可选** 的 — 每个都需要外部服务（Docker，Python，uvx），并且必须通过 `~/.nexus/agent/mcp.json` 配置。代理在没有它们的情况下也能正常工作。
| 集成 | 能力 | 来源 |
|---|---|---|
| **Playwright MCP** | 通过可访问性快照的 20+ 浏览器工具 | [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) |
| **Docling MCP** | PDF / Word / PPT / Excel / EPUB → 带有 OCR 的 Markdown | [docling-project/docling-mcp](https://github.com/docling-project/docling-mcp) |
| **Qdrant MCP** | 用于长期知识的生产向量数据库 | [qdrant/mcp-server-qdrant](https://github.com/qdrant/mcp-server-qdrant) |
| **LightRAG MCP** | 具有 5 种检索模式的知识图 RAG | [HKUDS/LightRAG](https://github.com/HKUDS/LightRAG) |
模板：[`mcp.json.example`](./mcp.json.example)。完整参考：[`docs/mcp-config.md`](./docs/mcp-config.md)。
## 项目结构
```
nexus-agent/
├── packages/
│ ├── agent/ # 代理内核（代理循环 + 事件系统）
│ ├── ai/ # LLM 提供商抽象（50+ 提供商）
│ ├── coding-agent/ # CLI + SDK + 60+ 工具
│ ├── collab-web/ # 网页客户端（浏览器会话）
│ ├── nexus-grpc/ # gRPC 服务器
│ ├── nexus-routing/ # 每个代理的模型路由
│ └── ...
├── crates/
│ ├── nexus-sandbox/ # 操作系统沙盒（Landlock / Seatbelt）
│ ├── nexus-checkpoint/ # 文件检查点（reflink CoW）
│ ├── pi-natives/ # Rust 本地模块（grep，glob，AST，PTY...）
│ └── ...
├── workany-dev/ # 桌面应用（Tauri + React）
│ └── workany-dev/
│ ├── src/ # 前端（React + TailwindCSS）
│ ├── src-api/ # 后端 API（Hono + Bun，边车）
│ └── src-tauri/ # Tauri shell（Rust）
├── vscode-extension/ # VS Code 扩展
└── docs/ # 文档（80,000 字工程手册 + 用户指南）
```
## 文档
### 用户文档
- [用户指南](./docs/user-guide.md) — 安装，配置，CLI 参考，基础知识
- [集成指南](./docs/integration-guide.md) — gRPC 客户端，VS Code 扩展，每个代理的路由，沙盒调整
- [迁移指南](./docs/migration-guide.md) — omp → 智能代理（`~/.omp/` → `~/.nexus/`)
- [MCP 配置](./docs/mcp-config.md) — 完整的 MCP 服务器配置
- [设置参考](./docs/settings.md) — 所有配置选项
### 工程文档
- [**工程手册**](./docs/NEXUS-AGENT-GUIDE.md) — ~80,000 字深入探讨（24 章 + 4 附录）
- [DESIGN.md](./DESIGN.md) — 愿景，架构，能力映射
- [ROADMAP.md](./ROADMAP.md) — M1–M9 里程碑，验收标准
- [CHANGELOG.md](./CHANGELOG.md) — 发布历史
- [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md) — 上游归属
## 已知限制
这是一个 **源代码可用测试版**，而非生产版本：
- **无 npm 分发**：通过 Docker（推荐）或源代码构建（Bun + Rust）安装。
- **无独立二进制文件**：运行时是 Bun 上的 TypeScript，而非单个 Rust 可执行文件。
- **Docker 镜像仅 amd64**：arm64 交叉编译超过 GitHub 运行器磁盘限制。
- **桌面安装程序尚未发布**：从源代码构建 WorkAny（参见 [桌面应用](#d-桌面应用-workany)）。
- **Windows 沙盒限制**：使用 ISO FS（无内核级拒绝）。使用 WSL2 或 Docker 获取完整沙盒。
- **MCP 集成是可选的**：需要外部服务（Docker / Python / uvx）。
- **包范围**：内部包仍使用 `@oh-my-pi/*` 范围（计划迁移到 `@nexus-agent/*`）。
## 开发
```sh
bun install # 安装根依赖
bun run dev # 终端开发模式
bun run collab:web:dev # 网页客户端开发模式（http://localhost:3000）
cd workany-dev/workany-dev
bun install
pnpm install
pnpm dev:all # 桌面开发模式（API + Tauri 应用）
```
## 许可证
MIT。参见 [LICENSE](./LICENSE) 和 [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md)。
智能代理是一个独立的社区项目，与 SpaceXAI、Anthropic 或任何上游项目无关、未获得其认可或赞助。“Claude”和“Claude Code”是 Anthropic PBC 的商标。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器