eve 贡献指南:本地开发、签名提交与 Agent 驱动的协作工作流

原创2026-10-13 20:39:581,664 阅读
文章标签:人工智能AI AgentAgent 框架工具调用后端MCP ClientsAI 评测可观测性

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 驱动,同时拉起两个进程:

  1. eve 包的构建 watch 模式(pnpm --filter eve run dev,即 tsc -p tsconfig.dev.json --watch);
  2. 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/status frontmatter 与 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 的实现看,该命令会:

  1. 读取契约表并校验配置合法性;
  2. 用 API Extractor 对比新旧 API 报告,调用 classifyStructuralBackwardCompatibility 判断变更是否在结构上向后兼容;
  3. 兼容则自动保留前 epoch 并 bump 到 current + 1,同时脚手架生成所需的 fixture 到 packages/eve/extension-contracts/compatibility/<capability>/v<N>.ts——贡献者需要把脚手架替换为保留期 authoring 契约的代表性示例,再重跑一次 pnpm update:extension-contracts 生成新 epoch 报告;
  4. 无法自动分类时,验证运行时兼容后传 --retain;
  5. 若不再接受旧契约,传 --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 中需要完成:

  1. 把包添加为 apps/docs 的 dev dependency(仓库现有条目如 @browserbasehq/eve、@jetty/eve 等即如此处理);
  2. 把包加入 pnpm-workspace.yaml 中受审查的例外列表;
  3. 在 apps/docs/registry/extensions 添加 mount 示例;
  4. 以 extension/<slug> 名称(含 dependencies、title、description)注册到 apps/docs/registry.json;
  5. 把扩展身份加入 packages/eve-catalog/src/index.ts(例如其中 slug: "browserbase" 的条目);
  6. 把画廊展示与 setup 说明写入 apps/docs/lib/integrations/data.ts(含 install/quickStart/configure 片段),把 logo 加入 apps/docs/lib/integrations/logos.tsx;
  7. 为集成页添加或更新聚焦测试。

文档维护

用户面向的文档在 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。流程如下:

  1. Fork 仓库并从 main 创建分支;

  2. 完成变更,包含相关的测试和文档;

  3. 用 git commit -s 为每个提交签名(sign off);

  4. 如果变更影响已发布的 eve 包,添加 changeset:

    pnpm changeset
    
  5. 确保 pnpm lint、pnpm typecheck、pnpm test 全部通过;

  6. 打开 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)。

小结:一次贡献的完整检查清单

  1. 先搜索现有 issue/discussion/PR,避免重复;
  2. 通过 issue 提出带用户故事或复现的提案(或一段 Prompt/实现计划),与维护者对齐方向;
  3. 配置 Node.js 24+ 与 pnpm(corepack enable),pnpm install && pnpm build;
  4. pnpm dev 本地调试,必要时运行 pnpm test:scenario、pnpm test:e2e 等分层测试;
  5. 提交前过一遍 pnpm lint、pnpm fmt、pnpm typecheck、pnpm check:deps、pnpm guard:invariants、pnpm docs:check;
  6. 若涉及扩展公开 API,按 pnpm update:extension-contracts --update <capability> 流程处理 epoch 契约与 fixture;
  7. 每个提交同时满足签名提交(Verified)与 DCO(Signed-off-by);
  8. 影响发布包时 pnpm changeset 添加 changeset;
  9. 提交 PR,先说明问题与决策,再描述方案。
登录后查看全文
eve