内容
# 🦁 Hercules-MCP: 由大脑设计，由图形驱动，由双手锻造
一种超高效、高度协作的智能编码框架，使用 **模型上下文协议（MCP）** 构建。该系统在规划、结构代码理解和执行之间建立分工，优化性能并降低成本。
## 📐 系统架构
```mermaid
---
config:
themeVariables:
fontFamily: "system-ui, -apple-system, sans-serif"
---
flowchart TD
subgraph Host ["💻 主机（本地工作空间）"]
Brain["🧠 IDE 聊天代理（大脑）"]
Proxy(["🌉 LLM 本地代理（桥梁）"])
Graph[("🧩 代码审查图（图形）")]
end
subgraph Sandbox ["🛡️ Docker 沙盒（执行）"]
Hands["⚙️ OpenHands 沙盒（双手）"]
end
Brain -->|"1. 查询上下文"| Graph
Brain -->|"2. 委托任务"| Hands
Hands -->|"3. 拦截 API 调用（端口 9999）"| Proxy
Proxy -->|"4. 返回本地响应"| Brain
style Brain fill:#1e293b,stroke:#38bdf8,stroke-width:1.5px,color:#f8fafc,font-family:system-ui
style Graph fill:#1e293b,stroke:#2dd4bf,stroke-width:1.5px,color:#f8fafc,font-family:system-ui
style Proxy fill:#1e293b,stroke:#818cf8,stroke-width:1.5px,color:#f8fafc,font-family:system-ui
style Hands fill:#1e293b,stroke:#fb7185,stroke-width:1.5px,color:#f8fafc,font-family:system-ui
style Host fill:none,stroke:#475569,stroke-width:1.5px
style Sandbox fill:none,stroke:#fb7185,stroke-width:1.5px,stroke-dasharray: 5 5
linkStyle 0 stroke:#2dd4bf,stroke-width:3px;
linkStyle 1 stroke:#fb7185,stroke-width:3px;
linkStyle 2 stroke:#818cf8,stroke-width:3px;
linkStyle 3 stroke:#38bdf8,stroke-width:3px;
```
---
## 🏷️ 推荐的 GitHub 仓库主题
为了最大化可发现性，请在 GitHub 仓库设置中的 **主题** 下复制并粘贴这些标签：
`mcp` `模型上下文协议` `openhands` `人工智能代理` `智能工作流` `llm-代理` `开发者工具` `沙盒` `沙盒安全` `代码索引`
---
## 💻 支持的客户端和 IDE
由于该系统完全基于开放标准的 **模型上下文协议（MCP）** 构建，因此它与任何支持 MCP 的智能环境兼容，包括：
* **Antigravity IDE**
* **Claude Code（命令行界面）**
* **Cursor**
* **VS Code** （使用 [Cline](https://github.com/cline/cline) 或 [Roo Code](https://github.com/RooVetGit/Roo-Code) 等扩展）
* **Windsurf**
* 任何其他支持 MCP 的代理。
## ⚡ 核心优势和主要功能
该框架使用与企业级软件工程架构相同的设计原则构建：
* **🔑 100% 无 API 密钥 LLM 执行：** 消除了使用个人 OpenAI、Anthropic 或 Gemini API 密钥驱动 OpenHands 任务执行的需要。该系统直接通过 IDE 中内置的活跃模型路由所有执行请求，从而节省了大量的 API 成本。
* **🌉 模型无关的 LLM 代理桥：** 利用轻量级 HTTP 服务器（[llm_proxy.py](file:///d:/AI%20workspace/hercules-mcp/infrastructure/llm_proxy.py)）（默认端口 `9999`，动态回退到下一个可用端口，并可通过 `LLM_PROXY_PORT` 环境变量完全自定义），拦截 OpenHands 的标准 OpenAI 聊天完成调用，并将它们翻译成本地文件（`llm_request.json` / `llm_response.json`）。这允许 IDE 聊天中活跃的任何模型（Claude、Gemini、GPT 等）在无需修改的情况下驱动执行循环。
* **🧩 真正的关注点分离：** 解耦推理和执行。
* **大脑（协调器）：** IDE LLM（Gemini/Claude）纯粹作为架构师，专注于需求、规划和代码设计。
* **图形（代码智能）：** `code-review-graph` 提供代码库分析、语义索引和依赖树。
* **双手（执行）：** `openhands` 作为隔离的执行层，在那里安全地编译和测试更改。
* **📉 90% 代币成本降低：** 传统工具将整个文件和目录转储到上下文窗口中，浪费代币并导致模型混淆。通过首先查询 `code-review-graph`，协调器检索理解更改所需的最小目标行范围。
* **🛡️ 隔离的“左移”沙盒安全：** 在本地系统上直接运行 AI 生成的代码是一个主要的安全风险。该系统隔离所有写入、编译和运行在安全的 **Docker 容器沙盒**（`openhands`）中。在写入回之前，通过沙盒中的单元测试自动验证更改，以保持主机系统安全。
* **📋 持久工作空间和会话内存：** 在对话工件目录中自动维护标准任务清单（`task.md`）和项目上下文指南（`AGENTS.md`）在工作空间中，确保模型在 IDE 重启之间永远不会忘记任务状态。
* **🧹 安全的沙盒清洁和验证：** 在 Docker 沙盒中自动运行和验证所有代码更改的单元测试，并在执行后自动清理临时文件。支持安全的 Docker 系统修剪快捷方式，删除构建缓存和停止的容器，而不影响数据库数据卷。
* **🔄 100% 环境可复制性：** 通过使用 Docker 容器化，开发环境、编译器和依赖项对于团队中的每个开发人员都是相同的，从而消除了本地版本不匹配和“在我的机器上运行”的问题。
* **🔌 IDE 和客户端无关性：** 完全基于开放标准的 **模型上下文协议（MCP）** 构建，该系统在 **Cursor**、**VS Code** （Cline/Roo Code）、**Antigravity IDE**、**Claude Code（命令行界面）** 或任何其他支持 MCP 的接口上开箱即用。
---
## 🔄 独立的核心更新
为了确保您的环境始终保持与最新功能同步，核心工具 **不会** 在此仓库中冻结。您可以直接从其官方源下载和更新它们：
1. **OpenHands：** 您直接从 [官方 OpenHands GitHub 仓库](https://github.com/All-Hands-AI/OpenHands) 克隆和更新。
2. **代码审查图：** 您使用其官方包管理器全局安装和升级。
此仓库严格用作您的自定义集成、路由规则（`AGENTS.md`）和 FastMCP 连接层。
---
## 🌍 跨平台和环境鲁棒性
该系统设计为在任何开发者机器上可靠地工作，无论在什么条件下：
* **💻 跨平台路径标准化（Windows、macOS、Linux）：** 集成脚本 `openhands_mcp.py` 动态规范路径分隔符（将 Windows 反斜杠 `\` 映射到标准 Unix 斜杠 `/` 进入沙盒）。它使用环境变量或相对回退动态解析本地工作空间路径。
* **🔌 IDE 和客户端独立性：** 由于该系统完全基于标准 **模型上下文协议（MCP）** 构建，因此它在 **Cursor**、**VS Code** （Cline/Roo Code）、**Antigravity IDE**、**Claude Code（命令行界面）** 或任何其他支持 MCP 的接口上开箱即用。 onboarding 系统自动引导活跃的 LLM 将配置写入根据正在使用的编辑器写入正确路径。
* **📁 自定义工作空间和文件夹命名支持：** 两层架构将系统配置（系统根目录）与代码库项目（项目文件夹）分开。文件夹可以命名为 **任意名称** （例如 `Projects`、`my-software`、`src`）。在 onboarding 过程中，LLM 检测或询问用户的目录名称，动态链接它们，并在它们尚不存在时创建它们。文件监视器自动拾取以后添加到该目录中的任何新项目。
* **🛡️ Git 清洁：** `.gitignore` 防止特定于机器的配置文件（例如 `.DS_Store`、本地 `.venv/`、`.gemini/` 凭证或您的活跃 `mcp_config.json` 包含个人 API 密钥）被跟踪，确保在推送或拉取时不会发生冲突。
---
## ⚙️ 设置指南
### 1. 先决条件
确保您的机器上已安装以下内容：
* [Docker Desktop](https://www.docker.com/products/docker-desktop/) （运行 OpenHands 和 GitHub MCP 服务器所需）
* [Python 3.10+](https://www.python.org/) 和 [uv](https://github.com/astral-sh/uv) （运行 python MCP 服务）
* [Node.js](https://nodejs.org/) （运行 Stitch / NPX 命令）
### 2. 核心设置
#### 步骤 A：设置代码审查图
在您的系统上全局安装 `code-review-graph`。按照您所在操作系统的官方安装说明，确保 `code-review-graph` 命令行界面在您的系统路径上可访问。
#### 步骤 B：设置 OpenHands
1. 克隆官方 OpenHands 仓库：
```bash
git clone https://github.com/All-Hands-AI/OpenHands.git
```
2. 按照他们的 [开发指南](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md) 构建并运行 OpenHands 本地容器/实例。
3. 记录本地 URL（通常为 `http://localhost:8000`）和 API 令牌。
---
## 🚀 轻松 onboarding（LLM 引导）
此工作空间包含运行系统所需的配置文件和自定义规则。当您在此工作空间中打开智能环境时，请将以下提示复制并粘贴到代理的聊天窗口中。
代理将自动检测您的设置并为您配置 MCP 服务器。
### 📋 复制粘贴 onboarding 提示：
```markdown
请帮助我引导我的本地 Hercules-MCP 系统。请按照以下步骤配置环境：
1. 检测此工作空间在计算机上的绝对路径。
2. 检测我们当前正在哪个 IDE 或代理扩展中运行（例如，Antigravity IDE、VS Code with Cline/Roo Code、Claude Desktop 或 Cursor）。
3. 要求我粘贴我的 GitHub 个人访问令牌（PAT）。
4. 配置以下 MCP 设置：
- **如果在 Claude Code CLI 中运行：** 将配置写入 `~/.claude.json`（或使用 `claude mcp add` 命令行命令添加每个服务器）。
- **如果在 Antigravity IDE 中运行：** 将以下 JSON 配置写入：
`C:\Users\<username>\.gemini\antigravity-ide\mcp_config.json`
- **如果在 VS Code（Cline/Roo Code）中运行：** 将以下 JSON 配置写入：
Windows： `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
macOS： `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- **如果在 Cursor 中运行：** 由于 Cursor 使用设置 GUI，请打印出确切的值（名称、类型、命令、参数、环境变量），并提供如何手动输入它们的逐步说明。
### 要应用/生成的配置模板：
（确保用工作空间的实际绝对路径 `<DETECTED_WORKSPACE_PATH>` 和我提供的令牌 `<USER_GITHUB_TOKEN>` 替换。)
{
"mcpServers": {
"github-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "<USER_GITHUB_TOKEN>"
}
},
"code-review-graph": {
"command": "code-review-graph",
"args": [
"serve",
"--auto-watch"
]
},
"openhands": {
"command": "uv",
"args": [
"run",
"<DETECTED_WORKSPACE_PATH>/infrastructure/openhands_mcp.py"
]
}
}
}
完成后请验证配置并确认我们准备好构建！
```
---
## 🧪 验证您的安装
完成 onboarding 设置后，您可以通过以下验证挑战来测试整个系统（大脑 + 图形 + 双手）是否正确协同工作。
> [!NOTE]
> 验证挑战应仅在每次安装时运行 **一次**。如果 `verification_test` 目录已经存在于工作空间中，并且已成功解析，代理将检测到它，通知您验证已经完成，并跳过再次运行以节省代币并防止冗余执行。
### 验证挑战提示：
将此提示复制并粘贴到您的智能聊天窗口中：
```markdown
让我们运行一个验证测试，检查我们的 Hercules-MCP 系统。请执行以下步骤：
1. 在我们的工作空间中创建一个名为 `verification_test` 的新目录。
2. 在其中创建一个带有故意逻辑错误的 Python 脚本（例如，一个本应计算斐波那契数但具有不正确递归基准的函数）。
3. 使用 `code-review-graph` 工具索引新目录并定位代码。
4. 将修复错误和运行单元测试验证的任务委托给 `openhands` 服务器。
5. 一旦修复并测试完毕，请输出一份摘要报告，显示：
- 原始损坏代码与修复后的代码。
- 验证测试状态。
- 估计通过使用图形目标查找而不是将整个文件/目录放入上下文窗口而节省的代币上下文。
6. 删除 `verification_test` 目录（或清理其 Python 文件），以保持仓库在服务器成功通过测试后保持干净。
```
### 预期结果：
如果设置完全正常，您的代理将：
1. 自动编写损坏的脚本。
2. 查询图形以注册/索引它。
3. 调用 `openhands.run_task` 以启动沙盒执行，纠正逻辑并编写验证测试。
4. 输出一份摘要报告，显示修复并演示系统的代币效率优势（通常比标准、全文件读取节省 80% 至 95% 的上下文窗口代币）。
