内容
# 代理桥
> **所有 AI 代理工具的统一入口。** 统一认证、速率限制和可观察性。
> 双协议：HTTP REST + MCP stdio。
AI 代理失败不是因为它们无法推理 — 而是因为工具集成是混乱的：5 个 API、5 种认证方法、5 种格式。AgentBridge 将其统一为一个单一的代理，让您的代理专注于推理，而网关处理底层逻辑。
## 快速开始
```bash
npm install
cp .env.example .env # 填写您的 API 密钥
# HTTP 模式（仪表板位于 http://localhost:3100）
npm run dev
# MCP 模式（适用于 Codex、Hermes、Claude Desktop）
npm run mcp
```
## 双协议
| 模式 | 命令 | 协议 | 用例 |
|------|---------|----------|----------|
| HTTP | `npm run dev` | REST API | 独立代理；仪表板位于 :3100 |
| MCP | `npm run mcp` | MCP stdio | 与 Codex、Hermes、Claude 原生集成 |
两种模式共享相同的工具注册表和网关逻辑。只需定义一次工具，即可在任何地方使用。
## 与 Codex 结合使用
已经配置。如果需要重新添加：
```toml
# ~/.codex/config.toml
[mcp_servers.agentbridge]
command = "/Users/lybang/Documents/赚钱/agentbridge/node_modules/.bin/tsx"
args = ["/Users/lybang/Documents/赚钱/agentbridge/src/mcp.ts"]
startup_timeout_sec = 30
```
重启 Codex，然后询问：“在 GitHub 上搜索 'mcp gateway'” — 代理将通过网关发现并使用 `github-search` 工具。
参见 [config-snippets.md](config-snippets.md) 了解 Hermes 和 Claude Desktop 配置。
## 工作原理
```
AI 代理 → tools/call (MCP) → AgentBridge → 上游 API
或
AI 代理 → POST /gateway/:toolName (HTTP) → 网关服务器 → 上游 API
↓
统一认证 / 速率限制 / 日志记录
```
## 注册工具
工具定义为 `/tools/` 目录下的 JSON 文件。示例：
```json
{
"name": "github-search",
"label": "GitHub 代码搜索",
"description": "搜索 GitHub 仓库",
"base_url": "https://api.github.com",
"endpoint": "/search/repositories?q=:query",
"method": "GET",
"auth": {
"type": "bearer",
"header_name": "Authorization",
"prefix": "Bearer ",
"source": "passthrough"
},
"rate_limit_rpm": 30,
"enabled": true,
"category": "开发者工具"
}
```
### 认证模式
- **env** — 服务器端在 `.env` 中存储凭证。适合共享 API 密钥。
- **passthrough** — 调用者提供每个请求的凭证。适合用户特定令牌。
## API 参考
| 端点 | 描述 |
|----------|-------------|
| `POST /gateway/:toolName` | HTTP：代理工具调用 |
| `GET /health` | 健康检查 |
| `GET /api/tools` | 列出所有注册的工具及其指标 |
| `GET /api/stats` | 聚合统计信息（成功率、P99 等） |
| `GET /api/logs` | 最近的调用日志 |
## 变现杠杆
一旦代理通过网关路由，您就拥有了控制平面：
1. **基于使用的计费** — 按调用次数收费（0.001–0.01 美元），收入随客户增长而扩大
2. **分层计划** — 免费（3 个工具，100 次调用/天）→ 专业版（29 美元/月，无限制）→ 企业版（499 美元/月）
3. **可观察性增值服务** — 基础日志记录免费；高级跟踪、警报和仪表板需付费
4. **托管认证** — 服务器端存储凭证作为高级安全功能
5. **工具市场** — 为垂直领域提供精选工具包，30% 收入分成
## 架构
```
src/
index.ts — Fastify HTTP 服务器入口
mcp.ts — MCP stdio 服务器入口（适用于 Codex/Hermes/Claude）
gateway-core.ts — 共享工具执行逻辑（由两种协议使用）
gateway.ts — HTTP 路由处理程序（核心周围的薄包装）
registry.ts — 工具注册表 + 指标 + 速率限制
auth.ts — 认证解析器（env / passthrough / 自定义）
logger.ts — 环形缓冲区日志记录器 + 统计信息
api.ts — 仪表板数据 API 路由
tools/ — 工具定义 JSON 文件
public/ — 管理仪表板（单页 HTML，实时）
```
## 下一步（MVP 后）
- [ ] 持久存储（SQLite）用于工具配置和日志记录
- [ ] OAuth 2.0 流支持
- [ ] 异步工具结果的 Webhook 回调
- [ ] 基于使用的计费集成（Stripe）
- [ ] 具有一键安装的工具市场
- [ ] 每工具自定义 `input_schema` 验证
