vercel/eve · 上手攻略

仓库：vercel/eve
链接：https://github.com/vercel/eve
分类：agent / framework
作者：Tom
更新：2026-07-11

这是什么

eve 是 Vercel 出品的文件系统优先（filesystem-first）AI Agent 框架，用 TypeScript 编写。它的核心思路是：把 Agent 的每个能力（指令、工具、技能、频道）都映射为项目目录中的固定文件路径，Agent 的行为"由文件结构定义"，而非集中式的巨型配置对象。

这带来的直接好处是：项目结构一目了然，AI 编程助手可以直接读取本地 node_modules/eve/docs 理解框架，无需联网查文档；代码审查、扩展、部署都更简单。

底层依赖 Vercel 开源的 Workflow SDK 实现会话持久化——Agent 可以在执行中暂停等待人工审批，然后从断点恢复，即使服务重启也不会丢失状态。

当前状态：Beta（2026-07-10 最近提交），API 和行为可能在正式版前调整。

解决什么问题

传统 Agent 框架（如 LangChain Agent）的问题是： - 所有配置堆在一个大对象里，工具一多就难以维护 - 工具注册表与代码分离，容易不同步 - 会话状态不持久，重启即丢失

eve 的解决方式： - 文件即接口：工具放 agent/tools/、技能放 agent/skills/、定时任务放 agent/schedules/，文件路径自动命名 - 内置持久化：基于 Workflow SDK，天然支持 pause/resume、human-in-the-loop - 多通道支持：开箱支持 HTTP、Slack、Discord，通过同一套 Agent 逻辑响应不同来源的消息

快速安装

前提

Node.js ≥ 18（建议 20+）
npm / pnpm / yarn

初始化新项目

npx eve@latest init my-agent

这会创建一个 my-agent/ 目录，安装依赖，初始化 Git，并启动交互式终端 UI。

添加到已有项目

cd myapp
npx eve@latest init .

启动开发服务器

npm run dev

注意：eve 包自带完整文档，coding agent 可以直接读 node_modules/eve/docs/ 理解框架，无需联网。

核心用法

1. 最小结构（只保留必要文件）

my-agent/
└── agent/
    ├── agent.ts         # 模型和运行时配置（可选，有默认值）
    └── instructions.md  # 必选：始终开启的系统提示词

agent/instructions.md 示例：

You are a concise weather demo assistant. Tell users that the weather data is mocked.

2. 定义工具（Tools）

agent/tools/get_weather.ts：

import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Return mock weather data for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});

工具文件路径 agent/tools/get_weather.ts 自动命名为 get_weather，无需注册。

3. 选择模型

agent/agent.ts：

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-5",
});

⚠️ 模型名称格式（provider/model-name）需与 eve 支持的 provider 对应。实际支持列表建议读 node_modules/eve/docs/agent-config.md。

4. 定时任务（Schedules）

agent/schedules/weekly_recap.ts：

// 定义周期性任务，eve 会按 cron 表达式触发

5. 通道（Channels）

agent/channels/slack.ts 连接 Slack 频道；agent/channels/discord.ts 连接 Discord。同一套 Agent 逻辑可同时响应多个平台。

典型适用场景

私有 Agent 开发：代码和数据都在本地，coding agent 可直接理解项目结构
多渠道客服：一个 Agent 同时对接 Slack、Discord、Web
需要人工审批的工作流：pause/resume 机制适合审批流、退款判断等需人工介入的场景
定时任务：Cron 驱动的定期报告、监控告警处理
Vercel 生态集成：如果已有 Vercel 部署流水线，eve 可无缝嵌入

坑与注意

Beta 阶段：正式项目使用有风险，API 可能breaking change。建议在 package.json 锁定 minor 版本。
模型配置：目前主要支持 Anthropic 和 OpenAI 系列。如需 Ollama 等本地模型，需查文档确认（文档可能未列出所有 provider）。
TypeScript 强依赖：项目必须是 TypeScript，如已有 JavaScript 项目需迁移。
Zod 依赖：defineTool 的 inputSchema 用 Zod schema validation，需要熟悉 Zod 用法。
调试体验：目前官方推荐的调试方式是 npm run dev 启动交互式终端，本地 Debug 能力（如 VSCode debugger 集成）未在文档中详细说明。
生产部署：Beta 阶段的生产部署文档不完善，Vercel 之外的平台（AWS Lambda、Docker）如何运行需自行探索。
Session 持久化：底层用 Workflow SDK，持久化粒度和重启恢复的可靠性需实际测试验证。

与同类对比

维度	eve	LangChain.js	CrewAI	Microsoft AutoGen
语言	TypeScript	TypeScript	Python	Python
配置方式	文件系统映射	代码配置对象	代码配置对象	代码配置对象
多渠道	HTTP/Slack/Discord	需要自行集成	不支持	不支持
持久化	内置（Workflow SDK）	需额外配置	需额外配置	需额外配置
文档内嵌	✅ node_modules	❌	❌	❌
成熟度	Beta	成熟	成熟	成熟
厂商	Vercel	LangChain	CrewAI	Microsoft

最大差异：eve 的文件系统优先设计是它与其他框架最根本的区别——代码即配置，coding agent 可读性极好。

一句话结论

如果你用 TypeScript 开发私有 Agent、需要 coding agent 高效理解框架、或需要同时对接多个 IM 平台，eve 值得尝试；如果是生产级 Python Agent 平台，LangChain/CrewAI 目前更成熟。

来源

GitHub README：https://github.com/vercel/eve
官方文档：https://eve.dev/docs
Workflow SDK：https://workflow-sdk.dev