Eve 项目研究：文件约定、Durable Agent 与部署边界

项目仓库：vercel/eve

AI 参与说明（Agent：Codex）：本文由 Codex 根据 Eve 官方文档、Context7 检索材料与固定提交源码协助调研、撰写和校验，整理日期为 2026-10-08。源码基线为 0b5bb5b，该提交的 eve package 版本为 0.73.0。本文未执行真实模型对话、云部署或进程崩溃恢复测试；持久性与云服务行为按官方说明及源码分析表述。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，运行记录中的 CLI 版本 0.162.0-alpha.2（不代表桌面 App 版本）。

Eve 把 Agent 的定义、执行和接入组织到一个 TypeScript 项目里。理解它时，先分清“用文件编写能力”“让任务持久执行”和“部署到哪里”这三个问题。

核心判断：它把 Agent 项目约定与持久运行时一起交付

Eve is a filesystem-first framework for durable AI agents. 开发者编写 instructions、tools、skills 与 channels，框架负责发现能力、运行 Agent loop、管理 Session，并连接持久执行与 Sandbox。它的价值在于减少这些能力之间需要手写的装配代码。官方 README

从工程角度看，Eve 更适合需要多轮任务、人工输入、文件处理或多渠道接入的 Agent。只做一次模型问答时，应先判断是否需要这一整套运行时。这个适用性判断是本文的分析，并非官方性能结论。

项目采用 Apache-2.0 license，当前仍处于 beta。开源 license 不代表相关托管服务免费，也不代表 API 已稳定；README 明确说明框架、API、文档和行为在正式发布前可能变化。License Beta terms

文件目录怎样成为 Agent 的编写接口

一个单 Agent 项目可以从下面的结构开始。除必要的 instructions 外，其他能力按需添加；实际支持的路径与发现规则以 Agent Files reference 为准。

project/
├── package.json
├── agent/
│   ├── instructions.md
│   ├── agent.ts
│   ├── tools/
│   │   └── sum_numbers.ts
│   ├── skills/
│   ├── channels/
│   ├── connections/
│   ├── schedules/
│   └── subagents/
└── evals/

这个结构可以直接进入 Git review：新增工具是新增代码文件，调整操作方法是改写 skill，修改默认行为是编辑 instructions。可读性来自能力有固定位置；是否安全、是否有效仍取决于文件内容和运行配置。Agent Files reference

一个 root agent 可以声明多个 Subagents。它们拥有独立上下文和持久 Session；声明式 Subagent 还拥有自己的 Sandbox、skills 与 state，不自动继承父 Agent 的编写能力。只需要可选操作步骤时，skill 通常更轻。多个能独立接收请求的 root agents 则使用 agents/<name>/agent/；这种 Eve workspace 共享根 package 与部署，不等于每个成员拥有独立依赖和版本。Project Structure Subagents

源码阅读地图：发现、编译与运行分层

仓库根目录使用 pnpm workspace 与 Turborepo，包含框架 packages、文档与示例 apps、测试 fixtures。普通使用者安装的是 eve package，不需要把整个 monorepo 当作应用模板。源码基线要求 Node.js 24+，根开发包管理器为 pnpm 12.7.0；应用脚手架可以使用 npm。根 package.json Workspace 配置

核心代码可按下面的顺序阅读，而不是先把所有 CLI 和 UI 代码读完：

1. 发现能力：discoverAgent 读取约定目录并构造 source manifest，不在发现阶段 import 开发者模块。这把“识别项目结构”与“执行用户代码”分开，也让诊断有独立入口。discover-agent.ts
2. 编译产物：compileAgent 将 compiler-owned artifacts 写入 .eve/，保留诊断后再根据 error severity 决定是否抛错。目录约定由此变成可消费的运行配置。compile-agent.ts
3. 管理 Session：execution/session/program.ts 组织 inbox、Session state 和 Turn execution，等待输入后继续执行。持久 Session 的控制逻辑位于这一层。program.ts
4. 调用模型：harness/model-call/call.ts 使用 AI SDK 的 ToolLoopAgent，设置 stopWhen: isStepCount(1)。Eve 在外层推进自己的 loop 和状态机，底层每次模型步骤由 AI SDK 执行；这解释了它与 AI SDK 的职责分工。call.ts

安全边界也有具体实现：Connection 授权信号走独立路径，模型只获得可展示的结果，OAuth URL、user code 等信息不会直接混入工具历史；token cache 使用 virtual context，避免把原始 token 放进 durable Step payload。它们减少凭据进入模型上下文和持久记录的机会，但不能替开发者审查自定义工具是否泄露数据。工具授权处理 authorization-tokens.ts

执行架构：Workflow 与 Sandbox 各自负责什么

Each Session runs as one durable Workflow. 默认一个 Step 包含一次模型调用及其后的 inline tool calls。Workflow SDK 保存进度，Nitro 承载 HTTP routes 和 Workflow entrypoints；Nitro 自身不负责 Workflow state store，也不提供 Sandbox runtime。Execution Model and Durability

flowchart TD
  C["Channel / Client"] --> A["Route auth"]
  A --> S["Session / Workflow SDK"]
  S --> M["Agent loop / AI SDK"]
  M --> T["Tool executor / Node.js"]
  T --> E["Connection / 外部服务"]
  T -->|"ctx.getSandbox()"| B["Sandbox provider"]
  B --> F["文件与命令执行"]
  F -->|"返回结果"| T
  T -->|"结果进入历史"| M
  S --> W["Workflow state store"]

这里有两个执行环境。模型调用、tool executors、hooks 和 Connection clients 在可信的 app runtime 中运行，能访问 Node.js 和服务端环境变量。默认 bash、read_file、write_file 工具通过 ctx.getSandbox() 操作 Sandbox。自己编写的工具如果直接调用 Node.js 或外部 API，就仍在 app runtime 中执行，不能因为它属于 Agent 就视为已经隔离。Security Model

Workflow 可以在等待人工输入时挂起，Sandbox 则按需打开或复用。模型和工具凭据留在 app runtime；需要在 Sandbox 中访问带认证的网络服务时，使用适用后端的 credential brokering。这个设计把可信集成代码与模型控制的命令环境分开，但自定义工具仍须遵守这一边界。Execution Model and Durability

默认 Sandbox 在 Vercel 环境选择 Vercel Sandbox，其他环境按 Docker、microsandbox、just-bash 的顺序寻找可用后端。just-bash 使用 JavaScript shell 与虚拟文件系统，没有 native process isolation。因此，评估隔离能力时必须先确认实际选中的 provider，不能只看工具名字叫 Sandbox。Default Sandbox Sandbox

默认配置也不保证断网：当前 just-bash 的创建代码开启完整互联网访问。需要网络限制时，应显式选择支持所需 policy 的 provider 并验证其配置。JustBash runtime

Durability 的实际保证与限制

完成的 Step 使用已记录结果恢复，执行中断的 Step 会重新运行。因此，Durability 并不自动让“发邮件”“扣款”“创建外部记录”只发生一次：外部系统可能已经完成操作，而本地 Step 尚未提交。此类工具应使用可复用的幂等键，或查询外部操作状态后再决定是否重试；人工批准解决授权问题，不能代替幂等设计。Crash recovery

等待 tool approval、OAuth 或持久输入时，Turn 可以 park，Workflow 挂起并在输入到达后继续。普通 defineTool 在发起它的 Step 内执行；自己的工具需要持久等待时，使用 defineWorkflowTool。进度上报和持久等待也是两件事：generator 的 yield 报告进度，await 的 Workflow operation 才提供持久等待。Workflow tools

Tool approval 是需要配置的策略。源码中工具未定义 approval 时不会自动要求人工批准；具有外部写入权限的工具，应显式决定何时允许、拒绝或请求批准。框架提供机制，应用决定权限规则。Approval policy

还应核对两个运行边界：

• experimental.workflow.modelCallsPerStep 能把多个模型与工具循环合并为一个 Step，但整个 batch 也成为恢复单位，失败后可能重复更多工作。
• steer 与 queue 是 Session 输入的交付策略。官方明确 Eve 不维护通用的 durable FIFO 用户消息队列；不能把 Session inbox 当成消息代理。

这两项直接影响恢复成本和输入语义。Execution Model and Durability

在 Vercel 上，新的输入可以让已经空闲、状态兼容且没有待处理工作的 Session 转交给接收请求的新部署。运行中的 Turn、等待中的人工输入、活跃任务和 Subagents 不会直接迁走；新版 checkpoint 也不能由旧版读取。升级方案应覆盖长期 Session 和回滚，而不只检查新 Session 能否启动。Deployment handoff

用一个确定性工具理解使用流程

前置条件是 Node.js 24+、npm 和所选模型的凭据。为固定本文示例的 package 版本，使用 0.73.0 初始化；命令会创建项目、安装依赖、初始化 Git，并进入交互式 TUI。按 TUI 的 /login 完成模型连接，本地起步不要求先创建 Vercel project。Getting Started

npx eve@0.73.0 init eve-demo
cd eve-demo

创建或改写 agent/instructions.md：

你是一个简洁的计算助手。
计算两个数之和时调用 sum_numbers，并根据工具结果回答。
说明计算来自确定性工具，不虚构外部数据来源。

在 agent/tools/sum_numbers.ts 写入下面的 TypeScript 工具。它只计算输入，不需要额外业务 API 或数据集。

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

export default defineTool({
  description: "Add two numbers deterministically.",
  inputSchema: z.object({
    left: z.number(),
    right: z.number(),
  }),
  async execute({ left, right }) {
    return { sum: left + right };
  },
});

defineTool 描述模型可以执行的能力；Zod schema 描述工具输入。它不是“让 LLM 在 prompt 里心算”，而是让模型选择调用，再由代码计算结果。Tools

如需显式设置模型，可编辑 agent/agent.ts：

import { defineAgent } from "eve";

export default defineAgent({
  model: "openai/gpt-6-luna-fast",
  reasoning: "high",
});

这个 string model ID 使用 AI Gateway 路径，需要相应凭据；也可以按官方文档选择直接 provider。ChatGPT subscription 的 chatgpt() 只支持本地开发，部署时不能沿用这一登录方式，须配置可用于服务端的模型访问方式。Agent Configuration

退出初始化时打开的 TUI 后，用下面的命令重新进入；也可以在运行时编辑文件，Eve 会重载变更。

npm run dev

输入“调用 sum_numbers 计算 17 与 25 的和”，预期工具结果为 { "sum": 42 }，随后形成答案。验收时应看到真实工具调用，而不仅是模型输出了 42；再用 -3 与 8 检查结果为 5。模型是否遵循工具指令需要真实对话验证，不能用直接执行工具函数来替代。

部署与认证：先确定面向谁，再选择托管方式

eve deploy 执行生产部署，不能把它当成只生成本地预览的命令。Eve 同时支持自托管，但默认 local Workflow world 的数据位于 .eve/.workflow-data，容器替换后继续执行需要保留这份状态；反向代理还要同时转发 /eve/ 与 /.well-known/workflow/。只转发用户 API，可能让 Session 创建成功却无法继续执行回调。Vercel deployment Self-hosting

自托管可选择其他 Workflow world，当前属于实验配置，需匹配 Eve 所用 Workflow runtime 协议。Sandbox 状态恢复也依赖所选 provider 和其原生资源。所谓可移植，应理解为定义与适配接口可复用，迁移时仍须落实存储、计算和身份配置。Self-hosting Sandbox

认证至少要分成三个问题：

1. Route auth：谁可以请求 Channel 的 HTTP 入口。生产默认 fail closed，显式开放匿名是另一项配置。
2. Connection auth：工具代表谁访问外部服务。用户 OAuth grant 需要可识别的用户身份，不能从匿名请求自动得到。
3. Session authorization：请求者可以访问哪个用户、租户或 Session。官方明确 Route auth 不自动实现 Session ownership，应用须补上所需授权。

“请求已经登录”只回答第一项，不能据此允许读取任意 Session ID。Authentication

默认 Web Chat 安装流程使用 Sign in with Vercel，面向关联 Project 的 team members。它适合团队内部使用；面向任意消费者的产品要选择并接入自己的认证及 Session 授权。生成了聊天界面，不代表这些业务权限已经完成。Web Chat setup

值得借鉴的设计与选型方法

本文最看重三个设计：能力目录可以直接 review，持久执行与 HTTP 请求寿命解耦，可信工具与模型控制的文件环境分开。它们分别改善可维护性、长任务恢复与执行边界；这些优势能否转化为项目收益，还需要实际场景验证。

建议先验证一个完整、范围有限的任务：初始化 → 工具调用 → 人工输入 → 恢复 → 权限拒绝 → 升级后的 Session。通过条件应包括正确结果、可观察轨迹、失败后继续与越权访问被拒绝。本文建议的验证路径不代表这些能力已在本次调研中全部实测。

对于核心生产系统，beta 状态、Step 重执行、Sandbox provider 差异和 Session 授权责任，是比 README 示例更需要提前处理的四个条件。完成原型后，再根据实际运行成本和迁移成本决定是否采用。

Self-Modification：改写能力如何进入可审查流程

本地 eve dev 支持编辑并重载 instructions、tools 和 skills，也可以让 Agent 帮助修改自己的能力。这里应把工具执行的文件环境与开发者项目的修改权限分别配置；不能因为开发方便，就默认所有生产会话都能改写运行代码。Self-Modification

在本文固定提交中，远程 Self-Modification 已有 GitHub Draft PR 的发布实现。它需要显式配置 source、target branch、credentials 与 authorize()，并只向通过主体授权的会话提供相应 Subagent。Remote 配置 主体授权

发布时先从隔离 checkout 捕获修改并形成固定 Git tree，校验受保护路径及文件规模等条件，再取得发布凭据、检查目标基线并创建 Draft PR。流程还会对同一操作的已有分支做 reconcile，减少恢复或竞态时重复创建的机会。proposal.ts github-publisher.ts

这个实现把 Agent 提出的改动送入后续 review 流程，并没有在上述发布函数中自动 merge 或 deploy。受保护路径检查也不是通用 secret scan，不能由此推断 PR 内容已通过完整安全或质量检查。值得借鉴的是：先固定待审查成果，再把发布权限赋给明确的操作；代码是否合并仍由独立流程决定。

验证范围与关联阅读

本次通过 Context7 解析 /vercel/eve，分别查询持久执行与起步流程，并将结论回溯到官方页面。源码读取使用固定提交，避免把可变的 main 或 research/ 设计稿直接当成已发布实现。真实模型调用、生产部署、外部 OAuth 和崩溃恢复未在本轮执行。

最小示例在 Node.js 26.0.0、Eve 0.73.0、AI SDK 7.0.133、Zod 4.6.5 下完成了工具模块导入、正负数与小数计算、非法字符串输入拒绝，以及 TypeScript 6.0.3 的 strict typecheck；CLI 的 --help、--version 和 init --help 也已实际运行。上述检查验证 API 与工具代码，未验证模型是否选择工具、完整 Session 持久性或云服务配置。

非交互初始化只验证到文件生成，依赖安装阶段主动取消，未把完整 scaffold 记为成功；类型检查只覆盖示例模块，并启用 skipLibCheck，不代表 Eve 整个 package 的声明均通过校验。

• Agents 栏目导航：其他 Agent runtime、工具与工作流研究。
• Agent 开发中的测试方法：Specification、Test Oracle 与验证证据：区分工具单元检查、行为评估与真实运行证据。
• 从两个 Grok Build Demo 学习 Agent Harness：从交互与能力复用角度继续阅读。