# @zackbart/connecta-eve 中文文档

规范地址：https://npmcn.com/package/%40zackbart/connecta-eve/

版本：0\.40\.0
npm 元数据更新时间：2026-11-02T23:08:54.592Z
中文译文更新时间：2026-11-02T23:51:55.723Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40zackbart/connecta-eve
原文对照：https://npmcn.com/package/%40zackbart/connecta-eve/?lang=original
项目主页：https://github.com/zackbart/connecta#readme
源码仓库：https://github.com/zackbart/connecta

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：24 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：eve 1\.0\.0-rc\.1
- 首次发布：2026-10-26T18:09:10.720Z
- 最新版本发布：2026-11-02T23:08:54.282Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

用于Connecta代理端点的Eve连接和指令帮助程序。

## 安装

```sh
npm install @zackbart/connecta-eve
```

也可以使用：`pnpm add @zackbart/connecta-eve`、`yarn add @zackbart/connecta-eve`、`bun add @zackbart/connecta-eve`

## README

# @zackbart / connecta-eve

将Eve代理连接到Connecta代理池并加载其端点指令 每回合一次。助手运行在《Eve》应用中；Connecta服务器 单独运行。否 `@zackbart/connecta` 依赖项由这个包安装。

需要 **节点24 +** 和 **夏娃1.0.0-rc.1**。开发和消费者 检查使用确切的发布候选版本。在RC期间对端保持固定状态 期;以后的候选版本和稳定版1.0需要进行兼容性检查。助手 版本共享Connecta的版本和标签；选择helper版本匹配 您的服务器版本。

## 安装并添加两个文件

```sh
npm install @zackbart/connecta-eve eve@1.0.0-rc.1
```

服务器必须声明您的代理，将其承认到指定池并发出其 代理牌。看到Connecta [代理令牌设置](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#issue-rotate-or-revoke-an-agent-token).

在Eve应用的环境中设置这些：

```sh
CONNECTA_URL=https://connecta.example.com
CONNECTA_ACCESS_TOKEN=cta_your_agent_token
```

创建 `agent/connections/connecta.ts`：

```ts
import { connectaConnection } from "@zackbart/connecta-eve";

export default connectaConnection({
  pool: "assistant",
  description: "Shared CRM and tickets for the assistant.",
});
```

创建 `agent/instructions/connecta.ts`：

```ts
import { connectaInstructions } from "@zackbart/connecta-eve";

export default connectaInstructions({ pool: "assistant" });
```

两家工厂都接受 `url` 覆盖 `CONNECTA_URL`． 与 `pool`， URL为 `<url>/agent/<pool>`； 没有 `pool`，提供完整的端点URL。池 名称必须匹配 `[a-z0-9_-]+`. `connectaEndpoint({ url, pool })` 返回相同的值 其他客户端的URL。保持两个文件指向相同的端点和令牌 源。

Auth是应用程序所有的。默认令牌来自 `CONNECTA_ACCESS_TOKEN`,读 同样针对每个请求，因此旋转不需要重新启动进程。一个 `getToken` Callback可以返回一个字符串或一个promise；它凌驾于环境之上。 不转发用户的身份信息。

## 在运行时选择池

当池依赖于聊天器时，将相同的选择器传递给两个工厂。 例如，一个应用程序设置信任 `direct` 通道元数据可以保留其 选择固定为一个回合：

```ts
import type { DynamicContext } from "eve/connections";

export const selectPool = (ctx: DynamicContext) =>
  ctx.memo(["connecta-pool", ctx.turn?.id ?? null], () =>
    ctx.channel.metadata.direct === true && ctx.session.auth.current?.principalId === "alice"
      ? "notes_alice"
      : "assistant",
  );
```

使用 `pool: selectPool` 在这两个 `connectaConnection` 和 `connectaInstructions`. Eve在每次模型调用之前评估动态连接；所选 游泳池是它的。 `instanceKey`，因此暂停的呼叫不能对已更改的呼叫进行重放 池。字符串仍然创建相同的静态连接。

两个工厂都独立调用选择器。帮助者从不记住它 结果。记忆选择器I/O `ctx.memo` 对你的保单终生有效 连接和说明一致，重复评估避免重复 查找。每个定义都有一个作用域备忘录，因此两个工厂各自执行 它们的第一次查找。转向键固定了该回合的每个选择；省略备忘录 每次评估都要重新选择。确保两个查找都使用一致的 应用程序拥有的策略数据。

每个选定的名称必须匹配 `[a-z0-9_-]+`。抛出选择器或无效选择器 即使在缓存指南时，Name也会失败。处理查找失败 您的选择器，如果它应该返回到最低特权池。

## 升级到Eve 1.0 RC

更新应用程序到 `eve@1.0.0-rc.1` 并重新安装以刷新其锁定文件。 helper的连接、动态池、指令和审批api都使用Eve的api 稳定的入口点，并且不需要对这个RC进行创作更改。夏娃的 [1.0稳定性策略](https://eve.dev/docs/reference/typescript-api#stability-policy) 不包括 `experimental` 字段或内部模块。

从0.90开始，回顾介入 [发布说明](https://github.com/vercel/eve/blob/eve%401.0.0-rc.1/packages/eve/CHANGELOG.md)： `session.clear()` 现在取消运行的回合和任务，以及对象形式的连接 现在在运行时保留批准。RC.1也要求 `@vercel/connect` `^2.7.0` 当安装了可选集成时；旧版本的Connect 拒绝预发布的Eve peer。

对于旧的应用程序，请遵循Eve的 [升级到1.0](https://eve.dev/docs/guides/upgrade) 事件消费者指南、保存的历史记录、扩展和客户端api。 在部署应用程序之前构建并测试它。helper不迁移这些 app-owned表面。

## 从Eve 0.86升级

Eve 0.88.1和之后的版本pin undici 8.12.3，所以应用程序不再需要自己的undici 覆盖。删除 `"eve": { "undici": "8.12.3" }` 从一个NPM应用的 `overrides`，或者 `"eve@0.86.0>undici": "8.12.3"` 从一个PNPM应用的 `pnpm-workspace.yaml`,然后 重新安装，提交锁文件并审计应用程序。服务器的可选undici 6.29.1 peer是一个单独的依赖，并保持其确切的pin。

《Eve》0.87到0.90也改变了助手不拥有的应用代码。审查每一个 中间释放 [Eve 0.90.0的更新日志](https://raw.githubusercontent.com/vercel/eve/refs/tags/eve%400.90.0/packages/eve/CHANGELOG.md)； 《星战前夜》0.84或0.85版本的应用也必须审查这些版本。显著的变化:

-   构建拒绝非Eve自己的工厂创建的连接定义，并且 `defineDynamic()` 值是不透明的（0.87）。 `connectaConnection()` 和 `connectaInstructions()` 已经返回由夏娃的工厂制造的值。
-   几个客户端、工作流和通道api发生了变化（0.87）。
-   Grant-bearing `vercelOidc` 身份验证就 `eveVercelOidc`， auth回调那个 返回 `allowToolStubs` 成为 `EveAuthFn`, `/info` 访问受限 (0.90)。Identity-only `vercelOidc()` 调用不需要重命名。

在部署应用之前，在新的Eve上构建和测试应用。

## 批准和写作

默认策略是Eve的 `never()`：授权写无人值守。使用一个 read-only连接池时，代理必须永远不写。对于交互式的 剂,添加 `gateWrites: true` 要在连接前请求用户批准 任何工具 `readOnlyHint` 不是 `true`，包括可写的 `execute_code`. `gateConnectaWrites` 导出该策略以进行组合。明确的夏娃 `approval`策略或审批配置优先于 `gateWrites`.

gate使用主机缓存的注释。如果读变成写之前 调度时，Connecta采用当前的分类；可写池可以 在没有新的批准的情况下执行写入。只读池拒绝。

## 端点指令

说明使用 `server/discover` （MCP 2026-07-28），退回到传统 `initialize` 当发现返回没有指导的响应时，包括 非ok状态或不支持的方法响应。网络错误和超时 永远不要触发初始化。JSON和SSE回复都可以接受。每个请求 有5秒的暂停时间。每次成功的引导被缓存10分钟 每个解析器中的端点； `ttlMs` 覆盖该持续时间。夏娃评估 每次模型调用前的说明；帮助器为每个端点保留一个结果 然后提交Eve的备忘录，最多刷新一次端点 备忘录被保留。交换池选择端点的指导，而不是 前池的。刷新失败将保留该端点的最后一个副本或添加 如果没有成功，则不执行任何操作，并等待30秒后重试。其他 端点保留自己的TTL和后退。Eve只保留了玩家使用的备忘键 最新的评估;如果缓存过期，返回到池可以再次刷新。 当Eve取消一次求值时，helper会重新抛出取消的消息，而不是 将其视为失败：没有为该回合保留任何内容，也没有等待开始。 工具仍然可用。指令不授予访问权限。 集 `clientName` 在 `connectaInstructions` 在服务器中识别其请求 日志;默认值为 `connecta-eve-instructions`.

## Vercel OIDC令牌源

这种变体需要 **connecta0.35.0或更高版本** 使用Vercel进行部署 为此代理配置的工作负载准入。添加了工作量准入 [\# 975](https://github.com/zackbart/connecta/pull/975) 并且从0.35.0开始可用。 早期版本需要代理令牌。 配置后，使用Vercel的令牌解析器 **两个** 文件:

```ts
import { getVercelOidcToken } from "@vercel/oidc";
import { connectaConnection } from "@zackbart/connecta-eve";

export default connectaConnection({
  pool: "assistant",
  description: "Shared CRM and tickets for the assistant.",
  getToken: getVercelOidcToken,
});
```

```ts
import { getVercelOidcToken } from "@vercel/oidc";
import { connectaInstructions } from "@zackbart/connecta-eve";

export default connectaInstructions({ pool: "assistant", getToken: getVercelOidcToken });
```

安装 `@vercel/oidc` 在《星战前夜》应用中使用这种变体时。帮手没有 依赖于它，并且永远不会自动切换凭证类型。 使用默认的工作负载受众：Connecta拒绝为a交换令牌 即使维塞尔签下了他们。

## 贡献者的验证

在安装了依赖项并构建了两个包的源代码签出中，运行 `pnpm --filter @zackbart/connecta-eve run probe:catalog --output /absolute/path/outside/checkout` 在节点24上。这启动真正的Eve 1.0.0-rc。1 .用一个打包好的，安装好的助手对抗 的40、100、250、500和1000个下游工具的种子本地目录 元、本机和本机加代码界面。本地列表包括三个 连接超出下游数量的工具。必须有一个包含1001个工具的本地目录 拒绝清单。 `--counts 40,1000` 选择一个较小的矩阵。

该探针使用带有确定性局部的Eve的公共语言模型接口 运输，没有型号证书或付费电话。它测量建筑， 冷发现和热发现、模式和结果字节、调用计数、并发调用 隔离、有界结果分页和进程内存。新子进程 分离每个基质细胞；Eve启动与回合延迟是分开的。报告 保留实际的Eve事件和传输输入。令牌使用和模型任务 质量仍然无法衡量；这些结果建立了局部运行时契约， 不是实时Vercel工作负载准入或生产模型性能。

对于一次性工作负载检查，请使用 [贡献者夹具配方](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/scripts/workload-fixture/README.md) 从一个来源 结账。它的准备命令打包并安装当前的核心/助手， 检查本地签名控件和取消，并且不创建活动资源。 实时执行需要单独的所有者对具体账户进行授权， 项目、界限、成本上限和清理。把证据放在收银台外。

## 常见问题

### @zackbart/connecta-eve 是什么？

用于Connecta代理端点的Eve连接和指令帮助程序。

### 如何安装 @zackbart/connecta-eve？

在项目目录运行 npm install @zackbart/connecta-eve，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：eve（1\.0\.0-rc\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @zackbart/connecta-eve 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @zackbart/connecta-eve 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @zackbart/connecta-eve 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @zackbart/connecta-eve 可以商用吗？

@zackbart/connecta-eve 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @zackbart/connecta-eve 还在维护吗？

最新版本 0\.40\.0 发布于 2026/11/03（今天）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。