• 人工智能
• AI Agent
• Agent 框架
• 后端
• 工具调用

eve/extensions/code是 eve 框架内置的编码扩展包（其源码位于 packages/eve-code），专门面向 CLI 场景下的智能体编码工作，贡献了apply_patch补丁编辑原语、沙箱化grep搜索、PR 监控（prwatch）共享原语、调查与代码审查技能、指令片段、只读 worker 子代理，以及基于 Connect 的认证钩子。本文将以 packages/eve-code/AGENTS.md 为骨架，结合扩展包的 extension/ 源码与三层测试结构，完整讲解该扩展的职责边界、构建发布流程、挂载配置、凭证代理机制、补丁引擎内部实现与安全模型。读完本文，你将掌握如何在 eve 应用中挂载并配置该扩展、如何通过沙箱引导安装 CLI 工具链、如何理解apply_patch的验证与回滚机制，以及如何用只读 worker 子代理安全地并行执行调查类任务。

扩展包定位：@eve/code是eve/extensions/code的源码

在 eve 仓库中，packages/eve-code/package.json 声明的@eve/code是一个private: true的工作区包，它是 eve 运行时内置的eve/extensions/code扩展的唯一事实来源。其描述准确概括了职责：

Source of theeve/extensions/codeextension: CLI-based coding work with credential brokering, safe patches, coding skills, and a read-only worker subagent.

也就是说，这个扩展完整覆盖了 CLI 编码工作的四个核心能力：

• 凭证代理（credential brokering）：在每一轮对话开始前，通过 Connect 认证钩子解析 Vercel 应用令牌（app token），并以防火墙（firewall）或命令（command）两种方式注入沙箱；
• 安全补丁（safe patches）：apply_patch作为扩展唯一自有的文件编辑原语，提供解析、验证、原子写入、回滚与事后诊断的完整闭环；
• 编码技能（coding skills）：investigate、review、lookup-agent-run等证据驱动的调查与审查技能；
• 只读 worker 子代理：一个不拥有写入权限的协作者，用于在隔离上下文中并行处理"某一小片"任务。

扩展随eve包一起分发（随包发布，而不是作为独立 npm 包发布），其公共入口点在 packages/eve/package.json 中声明为四个导出路径：

• eve/extensions/code：扩展本体（extension/extension.ts 经构建映射到packages/eve/src/extensions/code/extension/extension.js）；
• eve/extensions/code/sandbox：沙箱引导（bootstrap）与凭证辅助函数（extension/lib/sandbox.ts）；
• eve/extensions/code/tools：apply_patch与grep工具（gh是废弃的再导出）；
• eve/extensions/code/prwatch：供消费者自建 workflow 工具使用的 PR 监控原语。

职责边界：哪些内容属于这里，哪些必须划走

packages/eve-code/AGENTS.md 用一整节 "Boundaries" 明确了扩展的职责边界，这是理解该包架构的关键。核心规则如下：

1. Connector UID 通过扩展配置进入。认证钩子在每一轮（turn）开始前解析 Vercel 应用令牌——对应实现见 extension/hooks/authenticate.ts 与 extension/lib/connect-authentication.ts。
2. GitHub 相关内容属于@eve/git。GitHub 指令、pr技能和gh工具全部归 packages/eve-git（eve/extensions/git）所有。本扩展中只有"废弃兼容层"code({ github })会通过 extension/lib/github-compat.ts（内部导入eve/extensions/git/sandbox）继续贡献code__gh、code__pr与 GitHub 指令；除此之外，严禁在此扩展中添加任何其他 GitHub 或 Pull Request 内容。
3. 非 Connect 凭证消费者可以绕过扩展配置，直接从自己的沙箱生命周期中调用authenticateGitHub或authenticateVercel（见 extension/lib/credentials.ts）。
4. 凭证代理安全：broker 的凭证不得出现在模型编写的 URL 或参数中（防止令牌泄露到日志与对话上下文）。
5. 使用真实 CLI：优先使用真实的git、gh、vcCLI，而不是自建的仓库生命周期工具。
6. apply_patch是唯一的文件编辑原语，其余写操作应交给格式化器与生成器自己输出。
7. 共享实现放在extension/lib/下，文件系统路径即贡献命名空间（例如extension/tools/apply_patch.ts贡献名为apply_patch的工具）。
8. 计算机使用（computer use）属于@eve/computer-use。本扩展的 extension/lib/sandbox.ts 中保留的installComputerUse、startComputerUse、COMPUTER_USE_REVALIDATION_KEY再导出均标记为@deprecated，且不得在此添加新代码。

从源码结构看，这些边界通过"文件系统路径决定贡献名"被强制执行：tools/目录下的每个文件即一个工具，skills/目录下的每个目录即一个技能，subagents/下的每个目录即一个子代理。

构建与发布：如何从源码进入 eve 运行时

AGENTS.md 明确了构建与发布约束：

• eve 的构建流程会把本工作区的extension/目录复制到packages/eve/src/extensions/code/extension并编译进eve包。从 packages/eve/src/extensions/code/tools.ts 的入口映射可以看到，公共入口声明位于 packages/eve/package.json 与packages/eve/src/extensions/code/下。
• 不要发布@eve/code这个包，也不要把它加入 eve 的依赖——因为它本身依赖eve（"eve": "workspace:*"），属于随主包编译的分发形态。
• 扩展代码只允许导入公共的eve/*API（如eve/extension、eve/tools、eve/hooks、eve/sandbox）；第三方依赖（如@vercel/connect、zod）会被打包进 eve 的 dist。
• 测试必须放在test/unit/、test/integration/、test/scenario/三个目录中，位于被发现的扩展树之外，从而避免测试文件被误编译进扩展。

完成任何改动前，必须依次通过：类型检查（typecheck）、三层测试（unit、integration、scenario）、eve 本体构建（pnpm --filter eve build）、lint 与包级格式化（oxlint / oxfmt）。对应命令在 packages/eve-code/README.md 中给出：

pnpm --filter eve build pnpm --filter @eve/code typecheck pnpm --filter @eve/code test pnpm --filter @eve/code test:scenario pnpm exec oxlint packages/eve-code pnpm exec oxfmt --check packages/eve-code

值得注意的是，packages/eve-code/package.json 中三个测试脚本分别使用 Node 原生node --test运行test/unit/*.test.ts、test/integration/*.test.ts与test/scenario/*.test.ts，且engines.node要求>=24（scenario 测试会创建临时文件、本地 Git 仓库并启动子进程）。

挂载与配置：最小可用的编码扩展

挂载方式非常轻量。在 agent 的扩展文件中（例如本仓库自带的 packages/eve-code/agent/extensions/code.ts）导入扩展工厂并传入配置：

// agent/extensions/code.ts import code from "eve/extensions/code"; export default code({ // Optional; omit to mount without Connect-backed Vercel authentication. vercel: { connector: "vercel/acme-bot" }, });

从 extension/extension.ts 的 zod 配置 schema 可以看到全部可选配置项及其类型约束：

reasoning的合法取值枚举为["provider-default", "none", "minimal", "low", "medium", "high", "xhigh"]，openaiReasoningEffort为["none", "minimal", "low", "medium", "high", "xhigh", "max"]。注意：两个连接器都是可选的，code({})可以不带任何认证挂载；worker 的openaiReasoningEffort会被透传给 OpenAI 模型的reasoningEffortprovider option（见 extension/subagents/worker/agent.ts 中providerOptions.openai.reasoningEffort的组装逻辑）。

凭证投递方式的选择

README 给出了两条投递路径的取舍：

• firewall（默认）：令牌不进入沙箱进程，而是通过沙箱提供方的setNetworkPolicy()在网络层注入授权头。若消费者的沙箱提供方不暴露setNetworkPolicy()且未提供顶层broker回调，则认证会失败（credentials.ts 会抛出明确错误：eve-code firewall credential delivery requires a sandbox provider with mutable network policy...）。
• command：把令牌写入 git config 或 CLI 环境文件（GH_TOKEN/VERCEL_TOKEN），适用于没有可变网络策略的后端。

沙箱引导：安装 CLI 工具链与 TypeScript 诊断

消费者需要在沙箱的prepare回调中调用installCodeTooling来安装工具链，packages/eve-code/README.md 给出了完整示例：

// agent/sandbox.ts import { defineSandbox } from "eve/sandbox"; import { VercelSandbox } from "eve/sandbox/vercel"; import { installCodeTooling } from "eve/extensions/code/sandbox"; export const environment = VercelSandbox.environment({ prepare: async (sandbox) => { await installCodeTooling(sandbox, { vercel: true }); }, }); export default defineSandbox(() => environment.open());

installCodeTooling的实现见 extension/lib/sandbox.ts，它一次性完成：

1. 写入gh包装脚本、gh-signed-commit（签名提交包装）、vercel/vc包装脚本（vercel: true时）与 TypeScript 诊断 worker 脚本；
2. 若沙箱中没有gh，则尝试通过apt-get（必要时sudo -n apt-get）安装；
3. 将真实gh安装到受信路径（/usr/local/lib/eve-code等），再把包装脚本安装到/usr/local/bin/gh、/usr/local/bin/gh-signed-commit、/usr/local/bin/vercel、/usr/local/bin/vc；
4. 以隔离环境（/usr/bin/env -i HOME=/root、空 npm 配置）安装固定版本的typescript@6.0.3，供诊断 worker 使用（见 extension/lib/tooling.ts 中的typescriptInstallCommand）。

工具链根目录为沙箱内的.eve-code/，受信工具根目录为/usr/local/lib/eve-code。凭证以chmod 600权限写入.eve-code/env，由包装脚本在启动时 source——ghWrapperSource还会为未注入的令牌设置占位默认值（ghp_000...），确保在防火墙模式下gh命令不会因空令牌报错。

一个重要的工程细节：eve 从沙箱文件与环境选项推导 prepared 环境代（generation），而不是从导入的辅助函数推导，因此仅升级 eve 不会自动重建已存在的 prepared 工件。这也是 extension/lib/sandbox.ts 导出CODE_TOOLING_REVALIDATION_KEY = "eve-code-tooling:3:{GH_SIGNED_COMMIT_VERSION}:{TYPESCRIPT_VERSION}"的原因——消费者应把它纳入自己的沙箱revalidationKey，使缓存模板在工具链版本变化时能够重建。

非 Connect 逃生通道

对于持有 PAT、基准测试令牌或其他凭证提供方的消费者，可以不配置对应连接器，直接在自己的沙箱生命周期中调用从eve/extensions/code/sandbox导出的authenticateGitHub或authenticateVercel。这两个辅助函数（见 extension/lib/credentials.ts）支持firewall、command与broker三种选项，但不会配置扩展的gh工具本身。

认证钩子：每轮开始前的令牌解析

extension/hooks/authenticate.ts 通过 eve 的 hook 机制订阅turn.started事件：

import { defineHook } from "eve/hooks"; import extension from "../extension.ts"; import { authenticateTurn } from "../lib/connect-authentication.ts"; export default defineHook({ events: { async "turn.started"(_event, ctx) { await authenticateTurn(extension.config, () => ctx.getSandbox()); }, }, });

authenticateTurn（extension/lib/connect-authentication.ts）的逻辑是：若配置了vercel，先通过getToken(connector, { subject: { type: "app" } })从 Connect 获取 app-subject 令牌，再调用authenticateVercel(sandbox, { token, delivery, broker })注入沙箱。令牌解析失败时会区分三种原因并抛出带cause的包装错误：

• ConnectorInstallationRequiredError→ "connector installation is required"（连接器未安装）；
• 其他ConnectError→ "Connect rejected the token request"；
• 其余错误 → "Connect token request failed"。

authenticateVercel在firewall模式下会把Bearer头通过网络策略注入api.vercel.com与vercel.com两个主机（authenticateGitHub则注入github.com与api.github.com的Basic x-access-token头）。凭证按沙箱会话对象缓存于WeakMap，网络策略的更新通过 Promise 队列串行化，避免并发覆盖。

apply_patch：唯一的文件编辑原语

apply_patch（extension/tools/apply_patch.ts）是本扩展贡献的核心工具，approval: never()表明它不需要人工审批。它的设计目标在工具描述中非常明确：针对当前文件内容写小块 hunk，而不是重写整个文件或通过 bash 写入。

补丁格式

工具支持四种文件操作，格式如下：

*** Begin Patch *** Add File: path (every content line starts with +) *** Update File: path (optional *** Move to: new-path, followed by @@ chunks) *** Delete File: path *** End Patch

• 路径相对于root（默认工作区根目录），不得逃逸根目录；
• 生成文件（lockfile、dist/、vendor-compiled/等）会被拒绝——必须通过产生它们的命令来修改，而不是通过补丁；
• 输入patchText上限 500,000 字符。

解析器与匹配引擎

解析与匹配逻辑全部位于 extension/lib/patch.ts，其中几个关键实现细节值得注意：

• 严格格式校验：parsePatch要求存在*** Begin Patch/*** End Patch标记，Begin 之前只允许*** Environment ID:行，End 之后不允许任何非空内容，否则整个补丁被拒绝。
• hunk 匹配的容错性：deriveUpdatedContent会先归一化换行（\r\n/\r→\n）并保留 BOM 与行尾风格；匹配器对每一块依次尝试四种比较策略：完全相等 → 忽略行尾空白 → 忽略首尾空白 → 归一化排版字符（弯引号、省略号、不间断空格等），显著提高模型生成 hunk 的命中率。
• unified-diff 兼容：@@ -118,8 +118,8 @@ fn形式的 range 头会被解析，数字部分不作为可搜索文本，而尾部的函数上下文作为"前缀提示"（contextHint）帮助区分完全相同的代码块——因为 git 会截断该上下文，所以它只是提示而非精确锚点。
• 歧义拒绝：若 hunk 在没有上下文提示时能匹配多个位置（occurrences() !== 1），会拒绝应用，避免猜错目标。
• 友好的失败信息：匹配失败时返回当前文件最近内容的摘录（带行号），并给出"重新读取该文件、只重写失败的 hunk"的引导。
• 上限保护：单次补丁最多 100 个文件操作（MAX_PATCH_FILES = 100），每个会话 + patchRoot 通过patchLocks串行化，防止同一会话内并发补丁互相踩踏。

全量验证后再写入

applyPatchToSandbox的核心流程是先规划（plan）→ 全量验证 → 逐文件提交 → 失败回滚：

1. planChanges解析所有 hunk 并生成变更计划；对每个路径执行realpath校验，禁止路径穿越符号链接或仓库边界（assertRealPath），并拒绝同一路径的重复操作（claimPath）。
2. 对update操作，先记录所有待更新文件的previousContent，并运行 TypeScript 基线诊断（beforeCommit回调）。
3. 逐文件提交前再次revalidateChange，检查文件在验证与写入之间是否被并发修改（"stale write" 检测）。
4. 写入使用原子写（atomicWrite）：先写同目录下的随机临时文件（.{name}.eve-code-{uuid}.tmp），恢复原文件模式（stat -c %a/chmod），再用mv -n（新增文件不覆盖）原子移动。
5. 任一步失败时按逆序回滚已提交的变更，且回滚同样拒绝覆盖"已被并发修改"的文件；回滚失败会附加在错误信息中。

事后诊断：只返回补丁引入的问题

apply_patch的execute在提交完成后运行 extension/lib/diagnostics.ts 的runPostEditDiagnostics，执行四类受控检查（check字段枚举git-diff | syntax | typescript | whitespace）：

• git-diff：在 git 工作树内运行git diff --check，检测冲突标记与尾随空白错误；
• whitespace：对新增文件（或非 git 树中的变更文件）逐行检查尾随空白等格式问题；
• syntax与typescript：通过独立的诊断 worker 进程（extension/lib/tooling.ts 中的DIAGNOSTICS_WORKER_SOURCE，以EVE_CODE_DIAGNOSTICS_REQUEST环境变量传入 base64 请求）加载沙箱中固定版本的 TypeScript 编译器，对最近 tsconfig/jsconfig 做语言服务诊断，最多报告 50 条、每条消息截断 1000 字符。

关键设计是onlyNewTypeDiagnostics(baseline, after)：工具先取补丁前的基线诊断，再取补丁后的诊断，只返回补丁引入的新问题，避免把存量错误算到这次编辑头上。输出 schema 同时返回files数组（含operation: add | delete | move | update与path/previousPath），方便调用方了解本次补丁的影响面。

grep：沙箱内容搜索

grep工具（extension/tools/grep.ts）是快速内容搜索工具，底层优先使用 ripgrep，无 ripgrep 时回退到 POSIXgrep（extension/lib/grep-search.ts）。其输入参数与语义如下：

工具描述中强调的用法节奏是：先files_with_matches+ 收窄path/glob（每文件首个命中即停），确认哪些文件相关后再用content，用count衡量模式命中规模后再去读。

实现层面的安全与工程细节：

• 路径安全：assertNoParentSegments拒绝含..的路径；真实路径通过resolveInWorkspace解析并强制包含在工作区内。
• 命令构造：buildRipgrepCommand使用--hidden并排除!.git/*，且遵守.gitignore；POSIX 回退不读.gitignore，但同样排除.git、包含隐藏文件。
• 资源边界：命令输出最多截断 256 KiB（MAX_GREP_COMMAND_BYTES），单行最多 8 KiB，最终返回内容预算 64 KiB（MAX_GREP_RETURN_BYTES）；超出时返回[Output truncated. Narrow path or glob, or lower context.]提示并置truncated: true。
• 退出码语义：ripgrep 的 exit 1 表示"无匹配"，因此只有exitCode非 0 且非 1、或 exit 1 但 stderr 非空时才视为失败；被字节上限中断的管道（141）按成功处理。

只读 worker 子代理：并行调查的正确姿势

扩展贡献了一个只读的 worker 子代理（extension/subagents/worker/）。它的定位在 agent.ts 的描述中非常清楚："Another mind for one scoped slice"。关键特征：

• 默认只读工具集：defaultTools: false，工具仅有glob、grep、read_file、write_file、web_fetch、web_search——其中read_file直接复用eve/tools/read_file，write_file存在于工具清单中但父沙箱为只读（sandbox.ts 使用defineParentSandbox()，由父级代理持有写权限）。
• 模型动态配置：通过defineDynamic在session.started时读取扩展配置的worker项；默认openai/gpt-5.6-terra-fast+xhigh推理，openaiReasoningEffort透传为 OpenAI 的reasoningEffortprovider option。
• 明确的身份边界：instructions.md 规定 worker "可以搜索、阅读、比较证据、运行非变更命令，但不得编辑工作区或产生外部副作用"；"证据不在乎你的期望"——每个非显然的结论都必须锚定在路径、行号、diff hunk 或命令结果上；调用方保留裁决权（arbiter）与全部写操作。

这种设计支持两种生命周期：持有式（keep 它并持续发送 delta，让它端到端拥有某一小片）与一次性（spawn 后问一次就结束）。隔离上下文是重点，委托不能有损。

技能：证据驱动的调查、审查与运行查找

extension/skills/下提供三个技能目录与一个动态技能：

investigate（调查）

skills/investigate/SKILL.md 要求"严格、证据驱动的诊断"：先确认问题真实且可复现，若不可复现则暂停并报告；从观察到的现象出发逐层向上追踪调用帧、进程、网络跳数与持久化边界；在每一分支保持显式假设并尝试证伪；区分观察、推断与未知；证据缺失时停止，而不是用猜测填补。

review（深度审查）

skills/review/SKILL.md 是安全性与正确性审计技能（触发词包括 "review / deep review / thermo nuclear" 等）：把自包含的审计指令交给 worker 子代理，root agent 评估结论并拥有最终裁决。必查项包括跨包与运行时副作用的全链路追踪、授权/不可信输入/凭证披露/破坏性行为/有界工作、本地构建与运行流程、feature-gate 泄漏等。所有发现必须有仓库证据；在阅读 PR 讨论之前先独立审计，避免被已有评论锚定。

lookup-agent-run（运行查找）

skills/lookup-agent-run/SKILL.md 强调这是"查找而非诊断"：仅使用消费者提供的 Agent Run API、Vercel 或其他可观测性连接、仪表盘链接权限等授权证据；本扩展自身不提供这些能力；优先精确匹配 run ID，其次关联项目/环境/标题/请求属性/创建时间；无 trace 访问时必须至少两个独立信号交叉验证；无法确定时问一个聚焦的问题而不是猜。

pr 技能（废弃）

skills/pr.ts 是动态技能：仅当废弃的github配置存在时才贡献code__pr（签名提交 PR 技能），否则返回null。它从eve/extensions/git/sandbox复用prSkillDescription/prSkillMarkdown，与 extension/tools/gh.ts 的动态gh工具同属一个兼容策略——code({})不贡献任何 GitHub 工具、指令或 PR 技能。

指令片段：编码智能体的行为守则

extension/instructions.md 是注入给使用该扩展的 agent 的指令片段，其中体现的设计原则与工具设计高度一致：

• 极简与行动优先：简单语言、无仪式感；只有"丢线索的代价大于写计划"时才用todo；有界任务直接开始，不花费模型轮次维护计划。
• 并发执行：多个只读调用相互独立时应同一响应内并发发出（eve 会并发执行同一响应的调用）；依赖结果的工作才串行。
• 委派：识别可并行的小片交给 worker，给每个 worker 自包含的问题（仓库、路径/ref、约束、期望输出），"树是共享的，所以不要复制完整源码"；写操作留在主代理，避免 worker 竞争变更共享工作区。
• 仓库礼仪：进入 checkout 后先读根AGENTS.md；默认不 rebase；用apply_patch做编写编辑；用grep做搜索；保留既有修改；禁用git reset --hard/git checkout --等破坏性命令。
• 安全红线：绝不打印凭证/令牌/.env内容；不在公共环境暴露公司私有引用；面向用户文本不使用 em dash。

PR-watch 共享原语

AGENTS.md 提到扩展"共享 PR-watch 原语"，并指出一个架构约束：eve workflow 指令是 application-only 的，因此持久的prwatch/prwatch_delete包装目前位于消费者（e0 消费者挂载）一侧，而不在本扩展内。本扩展通过eve/extensions/code/prwatch入口导出可复用的底层原语（extension/lib/prwatch.ts）：

• GitHub 侧：PullRequestWatchInputSchema、PrwatchDeleteInputSchema、pullRequestWatchSnapshot、initialPullRequestWatchNotificationState、advancePullRequestWatchNotification、framePullRequestWatchWake、isRetryablePullRequestWatchError、shouldRefreshPullRequestWatchToken等（源自 extension/lib/prwatch-github.ts）；
• 注册表侧：registerPrwatchInState、completePrwatchInState、cancelPrwatchInState、deletePrwatch、prwatchKey等（源自 extension/lib/prwatch-registry.ts）。

消费者在自己拥有的 workflow 工具中组合这些原语，即可实现 PR 状态快照、通知推进、唤醒帧与令牌刷新的完整生命周期，而不必在扩展内重复实现。

测试分层与本地开发

测试结构遵循"测试不进入分发树"的约束，分三层覆盖不同范围（对应 packages/eve-code/test）：

• unit（如generated-paths.test.ts、guidelines.test.ts）：纯逻辑单元测试；
• integration（如connect-authentication.test.ts、credentials.test.ts、patch.test.ts、sandbox.test.ts、github-compat.test.ts、diagnostics.test.ts、prwatch-registry.test.ts、repository-root.test.ts、extension-config.test.ts）：验证扩展配置、凭证注入与补丁引擎与 eve 运行时集成；包级集成任务只依赖 eve 的构建产物；
• scenario（如code-query-worker.test.ts、grep-search.test.ts、instructions-policy.test.ts、prwatch-github.test.ts、tool-input-schemas.test.ts、tooling-sources.test.ts、worker-manifest.test.ts）：创建临时文件、本地 Git 仓库并启动子进程，需要 Node.js 24+、Git 与 Bash，但不需要模型或服务凭证。

仓库根目录的集成命令会先跑框架套件（因为它会重建其他包导入的运行时文件），再跑其余包。另外typescript-compiler开发别名专门提供诊断 worker 测试所需的 JavaScript 编译器 API，而工作区的 TypeScript 7 CLI 仍是包的类型检查器；prepack会先构建扩展，安装时不会在本地框架构建完成前运行扩展 CLI。

结语

eve/extensions/code展示了 eve 扩展体系的几个关键工程范式：职责边界用文件系统路径固化（tools/skills/subagents 目录即贡献名）、认证与凭证通过 Connect 钩子在每轮注入且尽量不落盘（firewall 网络策略优先）、写入操作收敛到单一、经过全量验证与回滚保护的apply_patch原语、调查类工作交给只读 worker 并行委派而写权限始终留在主代理。无论是搭建一个带 Vercel 认证的编码 agent，还是为自定义沙箱提供方适配凭证投递，理解 packages/eve-code/AGENTS.md 与其 extension/ 源码，都能让你在复用这套能力时既安全又高效。

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 工具调用