内容
# Eyeball
Eyeball 是一个为 AI 代理提供类型化、身份验证的工具 API：代理一次发现规范工具，通过 SDK 或 MCP 执行，并让 Eyeball 处理特定提供商的负载、凭证、重试和审计记录。它提供了 37 个工具包，涵盖电子邮件、消息、语音通话、CRM、商业系统和社交数据等领域，并以单个用户连接账户为基本单位，工具适用于 Anthropic、OpenAI、Vercel AI SDK 或任何 MCP 主机。
Eyeball 是 **开源（MIT）** 的，这是一个赌注：集成是一个问题，通过多人协作解决比单一家公司更快。您可以 fork 它，添加代理所需的工具包，并开启一个 PR - 每个适配器都会加强每个代理可以访问的层。参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
> **状态：** 预发布。工程已完成且受控（构建、测试、类型检查、lint）；当可选的维护者的 `mocks/` 签出存在时，测试门控也运行 493 行的合约矩阵。四个公共包（`@eyeball/core`、`@eyeball/catalog`、`@eyeball/toolkits`、`@eyeball/sdk`）已切割并获得 MIT 许可。npm 发布即将到来，等待 `@eyeball` 组织。托管的云控制面板存在于一个单独的私有仓库中，不属于这个开源项目。提供商适配器针对确定性模拟进行认证；在维护者的套件中，实时提供商认证正在进行中（Notion 和 Google Drive 已被证明是实时有效的）。
## 演示
[▶️ 观看高质量视频](docs/assets/eyeball.mp4)
## 架构
```text
+---------------------+
| 代理 / 应用程序 |
+----------+----------+
|
TypeScript SDK 或 MCP
|
+----------------+----------------+
| |
+--------v---------+ +--------v--------+
| MCP 网关 | | 管理仪表盘 |
+--------+---------+ +--------+--------+
| |
+----------------+----------------+
|
+----------v----------+
| 执行器 |
| 认证 · 记录 · |
| 幂等性 · 队列 |
+----+-----------+----+
| |
目录/工具 凭证提供者
适配器 提供者
| |
+----v-----------v----+
| 本地开发保险库 |
| + 模拟房路线 |
+---------------------+
```
执行器始终解析目录清单和凭证，然后再调度适配器。在默认的本地堆栈中，清单基准 URL 重定向指向 Echo、Gmail、Slack 和 GitHub 的包含的启动模拟房。当存在可选的 `mocks/` 签出时，它提供完整的模拟房。生产部署用真实的提供商端点和托管的凭证保险库替换该边界。
## 安全和信任模型
项目 API 密钥是服务器凭证，默认情况下，授权调用者代表该项目中的每个最终用户。这样是故意的：未固定的 `key:projectId` 条目是项目权限，而提供商连接仍然针对项目和选定的用户进行检查。
当将密钥交给信任度较低的 MCP 主机或其他最终用户范围的客户端时，请使用 `EYEBALL_API_KEYS` 中的 `key:projectId:userId` 固定它。执行器和 MCP 网关拒绝通过执行或连接正文、`X-Eyeball-User-Id`、查询筛选器或 MCP `_meta` 提供的不同用户。网关使用单独的下游执行器凭证配置其入站密钥环；请参见自托管指南。保持远程流量在 TLS 后，并从不将项目密钥嵌入浏览器包中。
MCP 网关支持 JSON 和 SSE 流式 HTTP 响应以及可选的实验性 MCP 任务。状态调用者必须保留服务器颁发的会话 ID；会话记录仅存储单向绑定到入站凭证。浏览器 `Origin` 头在身份验证前进行验证。
## 仓库映射
主 monorepo 和私有 `cloud/` 控制面板是独立的 Git 仓库。`mocks/` 是可选的、只读的维护者模拟仓库签出。
| 路径 | 目的 |
| --- | --- |
| `packages/core` | 规范模式、执行合约、凭证、转换器和本地保险库 |
| `packages/catalog` | 目录 `1.1`、37 个提供商清单、工具发现和身份验证元数据 |
| `packages/toolkits` | 已实现功能系列的提供商适配器 |
| `packages/sdk` | TypeScript 客户端和框架面向的帮助程序 |
| `packages/bridge` | 外部集成引擎的兼容性边界 |
| `apps/executor` | 身份验证执行 API、记录、队列和开发连接 |
| `apps/mcp-gateway` | 状态流式 HTTP MCP 发现、SSE、执行和任务网关 |
| `apps/dashboard` | Next.js 管理面板，默认情况下带有演示数据，项目 webhook 端点管理和投递尝试检查，以及用于登录、组织/项目上下文、托管连接、API 密钥和审计事件的显式云模式 |
| `apps/docs` | 自托管的 Next.js 渲染器，用于作者的公共文档 |
| `apps/landing` | 静态产品登陆页面和交互式转录演示 |
| `apps/voice-worker` | 单独部署的 Python 语音会话控制面板和提供商认证脚手架 |
| `docs/` | 产品合约、RFC、测试策略和认证指南 |
| `docs-site/` | 作者的公共 MDX 内容和导航源 |
| `scripts/` | 文档检查、身份验证 CLI 和集成本地堆栈 |
| `mocks/` | 可选的只读维护者签出：完整的 30 提供商模拟房和 493 行认证矩阵；`dev:stack` 和测试在存在时使用它 |
| `cloud/` | 嵌套的私有控制面板仓库：租户、身份验证保险库/连接流程、密钥生命周期、审计和计费 |
## 快速入门
使用 Node.js 24 或更新版本和 pnpm 11。
```sh
pnpm install
pnpm build
pnpm dev:stack
```
`dev:stack` 启动包含的启动模拟堆栈（Echo、Gmail、Slack 和 GitHub），然后启动：
- `http://127.0.0.1:4010` 处的启动模拟房
- `http://127.0.0.1:3000` 处的执行器
- `http://127.0.0.1:3001/mcp` 处的 MCP 网关
- 使用开发 API 密钥 `eyeball_dev_project` 和用户 `demo_user` 的开发项目
下面的 SDK 示例在启动堆栈上无需更改即可工作。
对于完整的提供商覆盖，维护者使用一个单独的仓库签出到 `mocks/`：它包含完整的 30 提供商模拟房和 493 行认证矩阵。当存在该签出时，`pnpm dev:stack` 和模拟依赖测试自动使用它；如果没有它，`dev:stack` 使用启动堆栈，模拟依赖套件跳过。
在运行堆栈的情况下，将以下 SDK 示例保存为存储库根目录中的 `example.ts`：
```ts
import { Eyeball } from "@eyeball/sdk";
const eyeball = new Eyeball({
apiKey: process.env.EYEBALL_API_KEY!,
baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const tools = await eyeball.tools.get({
toolkits: ["gmail"],
format: "anthropic",
});
const result = await eyeball.tools.run(
"gmail.search_emails",
{ query: "from:reservations@example.com", pageSize: 5 },
{ userId: "demo_user" },
);
console.log({ modelTools: tools.tools.length, result });
```
```sh
EYEBALL_API_KEY=eyeball_dev_project \
EYEBALL_EXECUTOR_URL=http://127.0.0.1:3000 \
node --import tsx example.ts
```
### 从 Claude Code 或任何 MCP 主机连接
在运行堆栈的情况下，注册网关为 MCP 服务器。对于 Claude Code：
```sh
claude mcp add --transport http eyeball http://127.0.0.1:3001/mcp \
--header "Authorization: Bearer eyeball_dev_project"
```
或在 `.mcp.json` / Cursor MCP 配置中：
```json
{
"mcpServers": {
"eyeball": {
"type": "http",
"url": "http://127.0.0.1:3001/mcp",
"headers": { "Authorization": "Bearer eyeball_dev_project" }
}
}
}
```
网关默认搜索发现：代理调用 `eyeball.search_tools` 以查找规范工具，并调用 `eyeball.execute_tool` 以运行它们，因此数百种工具不会淹没模型的上下文。异步工具（例如启动电话呼叫）作为有界同步调用在普通 MCP 主机上运行，或作为可轮询任务在支持 MCP 任务的主机上运行。
监听端口和开发身份可以使用 `EYEBALL_MOCKHOUSE_PORT`、`EYEBALL_EXECUTOR_PORT`、`EYEBALL_MCP_GATEWAY_PORT`、`EYEBALL_DEV_API_KEY`、`EYEBALL_DEV_PROJECT_ID` 和 `EYEBALL_DEV_USER_ID` 进行更改。
## 实时语音代理
语音代理是一流的：组合一个代理（系统提示、LLM、TTS/STT、工具允许列表），然后在网络音频或电话上运行它。从仪表板的语音代理面板，您可以创建一个网络会话并 **直接在浏览器中加入房间** - 麦克风捕获、实时代理音频和带有内联工具调用的运行转录。带有电信工具的代理可以通过 `voice-agents.start_agent_call` 在会话中途进行真正的出站呼叫。完整的实时路径 - LiveKit 网络会话、Deepgram STT、ElevenLabs TTS、Anthropic 工具使用和真正的 Twilio PSTN 呼叫在电话上接听 - 于 2026-07-25 进行了端到端认证。有关部署和仪表板面板的交互流程，请参见 [语音工作器](./docs-site/self-hosting/voice-worker.mdx)。
## 部署持久性
执行器在默认情况下保持零配置和进程本地。 在部署中设置 `EYEBALL_DATABASE_URL` 以使用 Drizzle 支持的 Postgres 存储，用于执行和 24 小时幂等性、租赁隔离执行和 webhook 作业、不可变 webhook 工作快照和投递日志、触发器订阅/游标/去重状态、编辑触发器事件历史、暂存文件元数据和内容、终端使用情况报告等待投递、稳定语音代理头和不可变修订、编号绑定、执行器端会话指针、租赁隔离观察者游标/阶段/重试状态、完整的语音 webhook 源信封和消息收据。MCP 网关使用相同的变量用于其单独的 Postgres 会话/任务存储，同时保留其自己的迁移历史。股票 FileStore 目前使用 Postgres `bytea` 进行内容存储，同时保留一个用于后期对象存储后端的缝隙。每个所有者服务仅在启动时应用其已提交的迁移；根 `pnpm db:migrate` 在协调部署之前应用两个流。`docker compose up -d postgres` 启动可选的本地开发数据库。CI 和合约测试使用嵌入的 PGlite，不需要 Docker。
使用 Postgres，启动恢复会重新创建确定性 ID 作业，在工作者开始声明之前返回过期的租约，将过期的 webhook 重试截止日期和端点顺序保留，将终端 webhook/使用效果协调。 语音观察者的单独传递会声明过期的或无主的观察者，在最后一个持久处理的工人序列之后恢复，并在停机期间变得终端的会话排空。选定的语音事件存储源优先，游标仅在源/工作许可和终端授予处理持久后才推进；终端转录从工作者的完整有序历史重建。暂存文件在执行器重启后存活，直到其 TTL 过期，运行时在有界启动和每分钟一次的在线批次中回收过期行。编辑的触发器事件历史保留七天，形状与有界启动和每分钟一次的清理相同；它仅包含投递元数据，不能重建提供商有效载荷或签名的 webhook 正文。语音代理资源保留不可变的 历史修订，保持绑定和指针在后期更新后固定。网关会话和任务记录在重启后存活；仅当下一个正确身份验证的请求提供下游执行器凭证时，轮询才恢复。没有数据库，所有这些记录，包括触发器事件历史、观察者状态和语音 webhook 源，仍然是进程本地的。正在运行的执行仅在持久调度标记证明提供商调度从未开始时重放；不明确的调度后重启失败并出现 `execution_interrupted` 错误，而不是冒着重复副作用的风险。触发器轮询租约和速率/并发限制器仍然是进程本地的。语音会话状态和有序事件在单独部署的 SQLite 支持的工作器中保持权威。有关配置和重启边界，请参见 [运行执行器](./docs-site/self-hosting/executor.mdx)、[运行 MCP 网关](./docs-site/self-hosting/mcp-gateway.mdx) 和 [语音工作器](./docs-site/self-hosting/voice-worker.mdx)。
## 文档站点
仓库通过其自己的静态 Next.js 应用程序渲染 `docs-site/docs.json` 和所有作者的 MDX；不需要托管的文档平台。在保留的文档端口上启动它：
```sh
pnpm --filter @eyeball/docs dev
```
站点可在 `http://localhost:3003` 访问。使用 `pnpm --filter @eyeball/docs build` 进行生产构建，静态生成所有文档路由。
使用 `pnpm docs:generate` 刷新工具包和 SDK 引用（`pnpm docs:sdk` 仅刷新 SDK），然后在提交文档更改前运行 `pnpm docs:check`、`pnpm docs:snippets` 和 `pnpm docs:typecheck`。
## 演示
```sh
pnpm demo:mcp
pnpm demo:restaurant
ANTHROPIC_API_KEY=... pnpm demo:anthropic
```
- `demo:mcp` 运行一个确定性的 MCP 代理循环，发现并调用 Gmail、GitHub 和 Slack，然后验证提供商侧的效果。
- `demo:restaurant` 运行 RFC 002 餐厅语音代理流程，包括完成的 Pipecat 会话、日历事件、Gmail 确认和转录工件。
- `demo:anthropic` 在保持 Eyeball 及其提供商确定性的情况下，添加一个实时的 Anthropic 工具使用循环；如果 `ANTHROPIC_API_KEY` 消失，则干净地跳过。
## 发布状态
| 表面 | 状态 |
| --- | --- |
| Activepieces 桥接广度峰值 | 作为私有实验完成：五个固定的片段内省，三个动作在进程中执行，决策是每个片段选择性促销，没有批发供应商；生产隔离和认证仍在进行中（[RFC 003](./docs/rfcs/003-bridge-spike-findings.md)） |
| 37 个工具包/提供商清单 | 在目录 `1.1` 中构建，包含规范模式和发现功能 |
| 493 行合约矩阵 | 维护者的可选 `mocks/` 签出：227 烟雾行和 266 个明确的 `not_supported` 行；根测试在存在时运行它 |
| 管理面板 | 作为演示默认的 Next.js 仪表板构建，支持在浏览器中加入语音会话和显式私有云模式 |
| MCP 网关 | JSON/SSE 流式 HTTP、身份验证会话生命周期、目录/搜索发现、执行元数据和实验任务轮询构建；股票执行取消不可用 |
| 文档 | 在 `docs/` 中构建，验证了 112 页的 `docs-site/` 源和自托管的 `apps/docs` 渲染器 |
| 本地凭证保险库 | 使用加密的单租户存储和开发fixtures构建 |
| 托管 OAuth 保险库 | 在私有云仓库中实现，包含加密凭证、托管连接流程和刷新调度；部署和实时提供商认证仍在进行中 |
| 实时提供商认证 | 待提供商凭证和认证运行 |
| 语音工作器控制面板 | 版本化 Python 工作器、执行器桥、SQLite 恢复和账户无关合约套件构建；实时路径于 2026-07-25 认证（Twilio PSTN 呼叫应答，LiveKit 网络会话，Deepgram/ElevenLabs/Anthropic） |
| 计费 | 在私有云仓库中实现，包含版本化计划、使用情况计量和 Stripe 集成；实时目录启动、策略签字和部署仍在进行中 |
## 文档地图
- [产品规格](./SPEC.md)
- [工程和产品文档](./docs/)
- [作者的公共文档源](./docs-site/)
- [公共包发布流程](./docs/RELEASING.md)
- [实时提供商认证指南](./docs/CERTIFICATION.md)
- 模拟房和认证矩阵：单独的维护者仓库，可选签出到 `mocks/`
