vercel/eve：把 Agent 状态写进文件系统的 TypeScript 框架

它解决什么问题：Agent 配置的黑盒困境

多数 Agent 框架把系统提示词、工具定义、模型参数散落在代码和配置文件里，调试时要翻遍整个项目。eve 的核心主张是 filesystem-first，即把 Agent 的核心能力放在固定目录结构中，让项目「更容易检查、扩展和运维」。它面向的是需要长期维护 Agent 的工程团队，而不是只想跑一次 demo 的爱好者。对工程师来说，最大的收益是约定优于配置，你看到 `agent/instructions.md` 就知道这是系统提示词，看到 `agent/tools/` 就知道工具放哪。这种设计降低了新成员的上手成本，也方便用常规文件工具做 diff 和审查。

目录即接口：eve 的项目布局如何约束行为

eve 的典型项目结构在 README 中明确给出：`agent/` 目录下必须有 `instructions.md`（始终生效的系统提示词），可选的有 `agent.ts`（模型和运行时配置）、`tools/`（模型可调用的类型化函数）、`skills/`（按需加载的流程）、`channels/`（消息频道，如 HTTP、Slack、Discord）、`schedules/`（定时 cron 任务）。这不是随意摆放，每个目录都有明确语义。例如 `skills/` 里的 Markdown 文件是「按需加载」的，意味着模型不会一开始就拿到全部技能，而是根据任务需要读取，这能节省上下文窗口。`channels/` 的存在说明 eve 不只是命令行工具，它可以接入外部消息平台。这种布局把 Agent 的「大脑」和「感官」都物化为文件，让状态持久化变得自然，因为文件系统本身就是存储。

快速启动：从 npx 到第一个可用 Agent

上手 eve 只需一条命令：`npx eve@latest init my-agent`。它会创建目录、安装依赖、初始化 Git，并启动交互式终端 UI。如果你已有项目，可以传路径：`npx eve@latest init .`。想换模型，用 `--model` 参数指定 AI Gateway 的模型 ID，例如 `npx eve@latest init my-agent --model openai/gpt-5.6-terra`。生成的项目里，你只需替换 `agent/instructions.md` 为一段提示词，比如「你是一个简洁的天气演示助手，告诉用户天气数据是模拟的」，再在 `agent/tools/get_weather.ts` 里用 `defineTool` 导出一个带 Zod schema 的工具函数，最后在 `agent/agent.ts` 里用 `defineAgent` 指定模型，运行 `npm run dev` 就能得到一个可交互的 Agent。整个过程不需要手写任何胶水代码，工具的类型安全由 `zod` 保证。

工具定义与模型调用：类型安全如何落地

eve 的工具函数通过 `defineTool` 定义，输入 schema 使用 Zod，例如 `z.object({ city: z.string().min(1) })`。这意味着模型调用工具时，参数会经过运行时校验，不符合 schema 的调用会被拒绝。`execute` 函数接收解析后的参数，返回结果给模型。这种设计把工具接口变成了可验证的契约，而不是自由格式的 JSON。模型配置在 `agent/agent.ts` 中，通过 `defineAgent` 指定 `model` 字段，例如 `openai/gpt-5.6-luna-fast`。注意模型 ID 是 AI Gateway 的格式，不是裸的 OpenAI 模型名，这意味着你大概率需要 Vercel 的 AI Gateway 服务来解析这些 ID。README 提到「要使用其他 AI Gateway 模型，传入其模型 ID」，这暗示框架与 Vercel 的网关深度绑定，自托管或使用其他 LLM 提供商时需要额外适配。

文档内嵌与 beta 状态：两个值得注意的约束

eve 的 npm 包包含了完整文档，位于 `node_modules/eve/docs`。README 特意说明「编码 Agent 可以本地读取它」，这是为 AI 辅助开发设计的，让代码生成工具能直接参考官方文档，减少幻觉。这个细节说明 eve 的定位是面向 AI 原生开发流程。但项目明确处于 beta 阶段，受 Vercel beta 条款约束，README 写道「框架、API、文档和行为可能在正式版之前改变」。这意味着你现在写的代码，升级到 0.48 或 1.0 时可能不兼容。发布频率上，最近 24 小时内就有 0.47.3 和 0.47.2 两个版本，迭代速度极快，对于追求稳定的生产环境是风险，但对于尝鲜者反而是活跃的信号。

限制与失败模式：什么时候不该用 eve

最明显的限制是模型配置依赖 AI Gateway 的 ID 格式，如果你不使用 Vercel 的网关，就得自己处理模型路由，而 README 没有提供替代方案。其次，`instructions.md` 是「始终在线」的系统提示词，这意味着它会被注入到每次对话中，如果提示词很长，会占用大量上下文。虽然 `skills/` 可以按需加载，但基础提示词无法懒加载，这是设计上的取舍。另外，`channels/` 支持 Slack、Discord，但 README 没有给出具体配置示例，实际接入时可能需要查阅文档或源码。最后，eve 是框架而不是运行时，它不负责 Agent 的持久化状态管理，如果你的 Agent 需要跨会话保存复杂状态，文件系统可能不够用，需要外部数据库。

替代方案：与 LangGraph 和 CrewAI 的差异

与 eve 最接近的替代品是 LangGraph（LangChain 旗下的 Agent 框架）和 CrewAI。LangGraph 采用图结构定义 Agent 流程，节点和边显式控制状态转换，状态存在内存或检查点中，适合复杂工作流，但配置分散在代码里，没有统一的文件约定。CrewAI 则强调「角色扮演」，用 `Crew` 和 `Agent` 类组织多智能体协作，配置同样以 Python 代码为主。eve 的独特之处在于把文件系统当作一等公民，`agent/` 目录本身就是配置，这让项目可以用普通文件工具进行审查和版本控制。如果你需要细粒度的流程控制，LangGraph 的图模型更合适；如果你要 Python 生态，CrewAI 更顺手。eve 的优势是 TypeScript 原生和 Vercel 集成，但代价是生态成熟度远不如前两者。

维护成本与许可证：Apache-2.0 下的长期考量

eve 使用 Apache-2.0 许可证，允许商用、修改和再分发，但要保留版权声明，并且如果修改了代码，需要明确标注。这比 MIT 更严格，但对大多数企业来说没有障碍。维护方面，项目由 Vercel 主导，最近提交活跃，版本号 0.47.x 说明 API 仍在快速演进。升级成本是主要担忧：beta 期间的破坏性变更可能频繁，你需要跟踪每个版本的 changelog。好消息是文档内嵌在包中，升级后可以对比 `node_modules/eve/docs` 的变化。社区支持通过 GitHub Discussions，没有独立的论坛或企业支持渠道，这限制了故障排查速度。如果你计划长期使用，建议在 CI 中锁定版本，并定期测试升级路径。

编辑结论

eve 适合那些希望 Agent 配置可读、可审计、可版本控制的团队，尤其是已经使用 TypeScript 和 Vercel 生态的开发者。它把系统提示词、工具、技能、频道和定时任务都摊在文件系统里，降低了黑盒感，但代价是 beta 阶段 API 不稳定，并且模型配置依赖 AI Gateway 的模型 ID 格式。如果你需要生产级稳定性，或者你的 Agent 必须深度集成非文件型状态存储（如数据库事务），现在引入 eve 可能为时过早。在决定采用前，先确认 eve.dev/docs 上的文档是否覆盖了你需要的频道类型（如 Slack、Discord 的具体配置），并检查 `eve@0.47.3` 的 changelog 中是否有破坏性变更。若只是实验性原型，npx eve@latest init 能让你在十分钟内跑通一个带工具调用的 Agent，这个体验值得一试。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes