eve 贡献指南:本地开发、签名提交与 Agent 驱动的协作工作流
eve 贡献指南:本地开发、签名提交与 Agent 驱动的协作工作流
本篇指南围绕 eve 开源仓库的 CONTRIBUTING.md 展开,系统讲解从环境准备、本地开发、测试矩阵、代码质量门禁,到扩展能力契约、集成注册表、PR 与 DCO 合规的完整贡献路径。读完你可以独立完成一次 eve 的代码贡献:跑通本地开发环境,通过全部质量检查,按仓库规则提交签名且签署 DCO 的补丁,并理解 eve 用自家 coding agent 实现提案的特殊协作方式。
贡献入口:Issue 优先,Prompt 也是贡献
eve 的贡献流程有一个鲜明特点:外部贡献者应先从 issue 开始,而不是直接提交 pull request。仓库维护者使用自己的编码 Agent 来实现已接受的提案,这让他们能够控制 Agent 使用的模型、技能以及变更的验证方式。因此:
- 贡献者不需要写代码、也不需要开 PR——一份高质量的调查、Prompt 或实现计划本身就是有效的贡献;
- 提出变更前,先搜索现有的 issues、discussions 和 PR,避免重复正在进行的活跃工作;
- 描述问题时,说明期望的行为并给出具体的用户故事或复现步骤;如果你已想好变更方向,附上一段简短 Prompt 或实现计划,维护者可以用自己的 Agent 来执行。
为了让提案更容易被评估,原文档明确列出了几条约束:
- 不要提议大范围重写、纯样式改动、仅格式化的变更,或生成产物的无意义刷新(除非维护者明确要求);
- 每个 issue 只聚焦一个问题;
- 不要在没有具体需求的情况下引入运行时依赖——优先使用 eve 自有的封装、vendored 代码或生成产物,且
eve包应保持最小的运行时依赖; - 不要仅基于假设的用例提议公共行为变更,必须附带具体的用户故事或 bug 复现;
- 开发 Prompt 或计划前先检查 issue 线程,避免与他人撞车。
环境准备:Node.js 24+ 与 pnpm 工作区
贡献 eve 需要以下环境:
- Node.js 24+——仓库根目录的 .nvmrc 固定为
24,使用nvm use或fnm use切换; - pnpm——版本由根 package.json 的
packageManager字段钉住为pnpm@12.7.0,corepack enable会自动处理版本切换。
仓库本身是一个由 Turborepo 编排的 pnpm workspace(见 pnpm-workspace.yaml 的 packages 声明),核心目录包括:
| 目录 | 职责 |
|---|---|
| packages/eve | 框架本体与 eve CLI |
| packages/eve-catalog | 内部(未发布)集成目录 |
| apps/fixtures | e2e 测试、TUI 冒烟测试、本地开发与打包分析共用的 agent fixtures |
| apps/frameworks | Next.js、Nuxt、SvelteKit、TanStack Start 等框架集成应用 |
| apps/templates | 生成模板的源应用 |
| docs | 已发布的文档内容 |
| e2e | fixture 拥有的 eve eval 端到端测试 |
克隆并完成首次构建:
git clone https://github.com/vercel/eve.git
cd eve
pnpm install
pnpm build
其中根 package.json 的 build 脚本是 turbo run build --filter='./packages/*',只构建 packages 目录下的包。
本地开发:watch 模式与自动分配端口
pnpm dev
这条命令由 scripts/dev.mjs 驱动,同时拉起两个进程:
eve包的构建 watch 模式(pnpm --filter eve run dev,即tsc -p tsconfig.dev.json --watch);- apps/fixtures/weather-agent fixture 的 dev 服务。
值得注意的细节是:weather-agent 以 --no-ui --port 0 启动,端口 0 表示让操作系统原子地分配一个可用端口(见 scripts/dev.mjs 的注释),因此不会与本地其他服务冲突;fixture 启动后会打印选中的 URL。
scripts/dev.mjs 还体现了对进程树的管理:每个命令以独立的进程组(detached: true)启动,收到 SIGINT/SIGTERM 时向整个进程组发信号,避免 pnpm → shell → tsc/eve 的进程树被孤儿化;若某个子进程异常退出,编排器会终止其余进程并以非零码退出。
测试矩阵:从单元测试到 fixture 拥有的 e2e
仓库将测试分层组织,根 package.json 提供了完整脚本:
pnpm test # 单元 + 集成测试
pnpm test:unit # 单元测试
pnpm test:integration # 集成测试
pnpm test:scenario # 场景测试(需先 pnpm build)
pnpm test:framework-fixtures # apps/frameworks 冒烟构建(需先 pnpm build)
pnpm test:e2e # fixture 拥有的 eve eval 套件
pnpm test:tui # TUI 冒烟脚本(非 e2e)
从 packages/eve/package.json 可以看到底层实现:test:unit 与 test:scenario 都先运行 build:compiled(vendor 编译产物),再以对应的 vitest 配置执行;test:tui 则先对 tsconfig.tui.json 做 --noEmit 类型检查,再运行 test/tui-client/run-all.mjs。
E2E 测试是 fixture 拥有的 evals,需要进入 fixture 目录执行:
cd e2e/fixtures/agent-basic-runtime
pnpm exec eve eval --strict
例如 e2e/fixtures/agent-basic-runtime/package.json 就把 test:e2e 定义成了 eve eval --strict。由于 fixture agents 与 judge 运行在真实模型(如 openai/gpt-5.5)之上,环境必须提供对应模型提供商的凭据。Vercel 的 e2e 则以 VERCEL=1 构建同一 fixture 目录、部署其预构建的 Vercel 输出,再对不可变部署 URL 运行 evals;所有 fixture 部署都链接到同一个 Vercel 项目,共享项目的 Preview 环境需提供同样的模型凭据。
另外有一条 CI 强制的红线:不要提交 packages/eve/test/fixtures/ 下的 fixture 树。场景应用的内容以内联的 ScenarioAppDescriptor 对象定义在 packages/eve/src/internal/testing/scenario-apps(如 weather-agent.ts、extension-agent.ts、sandbox-workspaces.ts 等),而不是作为文件树提交。
测试打包构建
pkg.eve.dev 会为 main 分支和同仓库 PR 构建产物(不服务 fork PR 或直接分支部署)。PR 的 Vercel eve-pkg 部署成功后即可使用:
pnpm dlx https://pkg.eve.dev/pr/<pull-request-id>/eve.tgz dev
注意 pnpm dlx 可能对同一个 PR URL 复用缓存;要测试更新的 commit,请使用完整 SHA 的 URL:https://pkg.eve.dev/<full-sha>/eve.tgz。
代码质量门禁:lint、格式化与不变式守卫
提交前请先本地跑一遍以下命令,它们全部在 CI 中执行,本地通过可以省去一轮往返:
pnpm lint # oxlint(自动修复)
pnpm fmt # oxfmt(pre-commit hook 也会对暂存文件执行)
pnpm typecheck # 整个工作区的 TypeScript 检查
pnpm check:deps # syncpack —— 依赖版本必须保持同步
pnpm guard:invariants # 机械代码不变式 lint(CI 运行)
pnpm docs:check # docs frontmatter 与导航校验
Pre-commit hook 与格式化安全边界
安装依赖时的 prepare 脚本 scripts/install-git-hooks.mjs 会把 core.hooksPath 指向 .githooks,其中的 .githooks/pre-commit 实际执行 scripts/pre-commit-fmt.mjs:对暂存区中 Added/Copied/Modified/Renamed 的文件运行 oxfmt 并重新 git add。该脚本刻意做了两个安全处理:
- 部分暂存(partially-staged)的文件不会格式化——文件同时存在暂存与未暂存改动时,原地格式化再 add 会把未暂存内容悄悄带进提交,因此直接跳过并告警;
- 全部文件均无 oxfmt 支持的后缀时以退出码 2 视为无操作,从而自动跟随 oxfmt 支持的格式集合(JS/TS/JSX、JSON、Markdown/MDX、YAML、HTML/Vue、CSS、GraphQL 等)。
不变式守卫
scripts/guard-invariants.mjs 是框架代码不变式的机械执行器,每个守卫都输出“为什么存在该不变式 + 如何修复”的说明,让贡献者无需 reviewer 复述规则即可自行纠正。其中的规则 ID 是稳定标识,例如:
- 规则 9:仓库中不允许任何符号链接(symlink);
- 规则 13:禁止
...(c ? {} : { k: v })形式的展开三元对象组合; - 规则 19:除两个白名单文件外,禁止新建
new AsyncLocalStorage(),所有环境运行时状态经单一EveContext流转; - 规则 21:在 authored agent 树中,
defineMcpClientConnection、defineTool、defineSkill等调用禁止手写name:/id:字段——身份必须从文件路径(或根 agent 的包名)派生,避免双份真实来源漂移; - 规则 29:changeset 包名必须匹配 workspace 包名,避免坏 changeset 到发布流程才暴露;
- 规则 32:
research/下的每个 Markdown 文件必须含非空的issue/statusfrontmatter 与 ISO 格式的last_updated日期。
扩展能力契约:不可变的 epoch 报告
eve 对扩展公开 API 采用按 epoch 键控的不可变契约机制,这是贡献者改动扩展相关代码时最容易踩坑的环节。
契约表定义在 packages/eve/src/compiler/extension-compatibility.ts,形如:
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
current: 86,
supported: [/* 历次支持的 epoch */],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
// ...
},
},
// channel / connection / dynamicTool / schedule / ...
};
每个 capability 记录 current(当前 epoch)、supported(仍然支持的历次 epoch)和 dropped(已放弃的 epoch 及其原因)。只要扩展面向的类型或签名发生变化,CI 就会报出受影响的 capability。分类新变更是否保留前一个 epoch 并自动 bump:
pnpm update:extension-contracts --update hook
从 scripts/extension-capability-contracts.mjs 的实现看,该命令会:
- 读取契约表并校验配置合法性;
- 用 API Extractor 对比新旧 API 报告,调用
classifyStructuralBackwardCompatibility判断变更是否在结构上向后兼容; - 兼容则自动保留前 epoch 并 bump 到
current + 1,同时脚手架生成所需的 fixture 到packages/eve/extension-contracts/compatibility/<capability>/v<N>.ts——贡献者需要把脚手架替换为保留期 authoring 契约的代表性示例,再重跑一次pnpm update:extension-contracts生成新 epoch 报告; - 无法自动分类时,验证运行时兼容后传
--retain; - 若不再接受旧契约,传
--drop "旧契约为何无法运行的原因",这会 bump capability 并记录原因。
仓库中 packages/eve/extension-contracts 目录印证了这一设计:entrypoints/ 下每个 capability 一个入口(channel.ts、tool.ts、connection.ts、hook.ts 等),compatibility/<capability>/v<N>.ts 存放各历史 epoch 的兼容 fixture,reports/<capability>/v<N>.json 存放紧凑的 API 报告元数据。
三条铁律需要牢记:
- 每个历史 epoch 必须被恰好分类一次为 supported 或 dropped;supported 的历史 epoch 必须配套可编译的 fixture;
- 每个 epoch 保留可读的
vN.api.md声明报告与紧凑的vN.json元数据,合并后不得编辑或删除(scripts/extension-capability-contracts.mjs 的immutableContractHistoryIssues会用 git diff 检查这些受保护路径,改动只能以新增文件 + bump epoch 的方式出现); - 报告与 fixture 只覆盖结构兼容性,行为变化仍需专门的兼容性测试。
此外,scripts/extension-contracts/configuration.mjs 中的 PUBLIC_SURFACES 将 src/public/* 下的每个公共 authoring 导出都映射到一个 capability,校验机制会确保每个公共导出都被分配给某个 capability、且契约入口的导出集合与公共表面完全一致,防止导出漂移。
向注册表添加集成
集成注册表源文件位于 apps/docs/registry,按集合目录存放项目自有的源文件,例如 apps/docs/registry/connections/linear.ts 或 registry/extensions/browserbase.ts。条目名称使用单数的集成 kind(如 connection/linear)。之后在 apps/docs/registry.json 中注册条目,例如 Linear:
{
"name": "connection/linear",
"type": "registry:item",
"title": "Linear",
"description": "Connect an eve agent to Linear.",
"dependencies": ["@vercel/connect"],
"files": [
{
"path": "registry/connections/linear.ts",
"type": "registry:file",
"target": "agent/connections/linear.ts"
}
]
}
字段语义:path 指向相对于 apps/docs 的手写源文件;target 是 eve add 写入消费 agent 的位置;dependencies 声明依赖包;envVars 声明必需的环境变量。实际仓库中的 apps/docs/registry.json 条目还会带上 meta.eve.setup(如 eve integration connect linear mcp.linear.app linear)与 requires 版本约束,供 eve add 的交互式安装流程使用。
校验命令:
pnpm --filter eve-docs registry:check
从 apps/docs/package.json 看,该命令依次执行:注册表发布要求的测试与校验(validate-public-registry-requirements 等)、registry:build(tsx scripts/prepare-registry-output.ts && shadcn build)、以及 channel/connection/instrumentation/memory 四个校验脚本和 registry 源文件的 tsc。shadcn build 会读取每个被引用的源文件,把其内容转义后内嵌为 apps/docs/public/r/<kind>/<slug>.json 的 content 字段,同时重建 apps/docs/public/r/registry.json。apps/docs/public/r/ 下的产物是 gitignored 的,每次 docs 构建都会重新生成;只有 apps/docs/registry/ 下的源文件和 apps/docs/registry.json 会被提交。
扩展类集成的要求
注册表与集成画廊只收录经过审查、已发布的扩展。提交注册表条目之前,先开 issue 并取得维护者同意。硬性门槛包括:
- 包必须能从 npm 公开安装;
- 与当前发布的
eve版本兼容; - 附带配置、认证及任何安全敏感行为的文档。
PR 中需要完成:
- 把包添加为
apps/docs的 dev dependency(仓库现有条目如@browserbasehq/eve、@jetty/eve等即如此处理); - 把包加入 pnpm-workspace.yaml 中受审查的例外列表;
- 在 apps/docs/registry/extensions 添加 mount 示例;
- 以
extension/<slug>名称(含 dependencies、title、description)注册到 apps/docs/registry.json; - 把扩展身份加入 packages/eve-catalog/src/index.ts(例如其中
slug: "browserbase"的条目); - 把画廊展示与 setup 说明写入 apps/docs/lib/integrations/data.ts(含
install/quickStart/configure片段),把 logo 加入 apps/docs/lib/integrations/logos.tsx; - 为集成页添加或更新聚焦测试。
文档维护
用户面向的文档在 docs 目录,它们随 eve npm 包一起发布,并由 apps/docs 中的文档站点渲染。如果你的变更改变了公共行为,请在同一个 PR 内更新相关文档,并运行 pnpm docs:check(该脚本实际链式执行 check-docs.mjs、check-doc-snippets.mjs 与 check-doc-mdx.mjs,校验 frontmatter、代码片段与 MDX 有效性)。
提案与 Pull Request 流程
提案(Proposing a change)
如文章开头所述,外部贡献走 issue 而非未征询的 PR。提案内容建议包含:
- 期望的行为 + 具体的用户故事或复现;
- 相关的代码或文档位置,以及你建议的改动;
- 约束、权衡,以及任何公共 API 或依赖变更;
- 如何验证结果(相关测试与文档更新)。
即使提案不完整也没关系——可以只报告 bug 或请求功能,不一定要知道如何实现。维护者同意方向后可能要求补充细节。
提交 PR
只有团队成员和明确受邀实现变更的贡献者才能开 PR。流程如下:
-
Fork 仓库并从
main创建分支; -
完成变更,包含相关的测试和文档;
-
用
git commit -s为每个提交签名(sign off); -
如果变更影响已发布的
eve包,添加 changeset:pnpm changeset -
确保
pnpm lint、pnpm typecheck、pnpm test全部通过; -
打开 PR,用简短的描述先解释问题、用户需求或决策背后的原因,再描述解决方案。
版本发布由维护者通过 Changesets 管理(根 package.json 中的 changeset、version-packages、release 脚本即为此服务)。
签名提交与 DCO:双重合规要求
这是 eve 仓库最容易被忽略、也最容易导致 PR 被拒的一环——签名提交(verified signatures)与 DCO 是两套独立的合规要求,缺一不可。
签名提交(Signed commits)
受保护分支要求已验证的提交签名。提交前请配置 Git 使用 GitHub 已验证的 GPG、SSH 或 S/MIME 密钥;未签名的提交会被仓库规则拒绝,必须重写为签名提交才能合并。如果 PR 包含未签名提交,重新签名并 force-push 分支,确保签名密钥已添加到 GitHub 账号且提交显示为 Verified。
DCO(Developer Certificate of Origin)
仓库不需要 CLA,所有贡献基于 DCO.txt 的 Developer Certificate of Origin——一种轻量级的一行声明,证明你有权按项目许可证提交该贡献,无需签署任何协议或创建账号。但每个提交必须包含匹配提交者姓名与邮箱的 Signed-off-by 行:
Signed-off-by: Jane Doe <jane.doe@example.com>
自动添加方式:
git commit -s -m "your commit message"
忘记时的补救:
git commit --amend -s --no-edit # 修改最近一个提交
git rebase --signoff main # 对一系列提交补签
该要求适用于所有贡献者(包括 Vercel 员工),且有一个 required check 会阻塞包含无效 sign-off 提交的 PR。
需要特别强调的是:Signed-off-by 行不满足签名提交的要求,已验证的提交签名也不满足 DCO——两者必须同时满足。
报告 Bug、安全披露与行为准则
- 报告 bug 与请求功能请使用 issue 模板;
- 安全问题不要开公开 issue,请遵循 SECURITY.md 的披露流程;
- 参与项目即表示遵守 CODE_OF_CONDUCT.md;
eve以 Apache License 2.0 许可发布,贡献即表示你的贡献将按同一许可证授权(inbound = outbound)。
小结:一次贡献的完整检查清单
- 先搜索现有 issue/discussion/PR,避免重复;
- 通过 issue 提出带用户故事或复现的提案(或一段 Prompt/实现计划),与维护者对齐方向;
- 配置 Node.js 24+ 与 pnpm(
corepack enable),pnpm install && pnpm build; pnpm dev本地调试,必要时运行pnpm test:scenario、pnpm test:e2e等分层测试;- 提交前过一遍
pnpm lint、pnpm fmt、pnpm typecheck、pnpm check:deps、pnpm guard:invariants、pnpm docs:check; - 若涉及扩展公开 API,按
pnpm update:extension-contracts --update <capability>流程处理 epoch 契约与 fixture; - 每个提交同时满足签名提交(
Verified)与 DCO(Signed-off-by); - 影响发布包时
pnpm changeset添加 changeset; - 提交 PR,先说明问题与决策,再描述方案。