# @coval/sdk 中文文档

规范地址：https://npmcn.com/package/%40coval/sdk/

版本：0\.9\.34
npm 元数据更新时间：2026-11-10T20:28:03.280Z
中文译文更新时间：2026-11-10T20:59:37.943Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40coval/sdk
原文对照：https://npmcn.com/package/%40coval/sdk/?lang=original
项目主页：https://docs.coval.dev/api-reference
源码仓库：https://github.com/coval-ai/coval-sdk

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

- 包体积（解压后）：10.2 MB，3260 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-05-12T17:27:22.143Z
- 最新版本发布：2026-11-10T20:28:02.929Z
- 近 30 天下载量：7788（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

为Coval评价平台API所打入的TypeScript客户端.

## 安装

```sh
npm install @coval/sdk
```

也可以使用：`pnpm add @coval/sdk`、`yarn add @coval/sdk`、`bun add @coval/sdk`

## README

# @coval/ sdk (英语)

输入的脚本客户端 [科瓦尔](https://coval.dev/) 评估平台API.

这个SDK大部分是 **生成** 从 Coval 的公开 OpenAPI 规格( 同样的力量 [文件.coval.dev/参考](https://docs.coval.dev/api-reference)) (中文(简体) ). 一个小的手写图层会添加认证, 带有后退的重试, pagination 迭代,和打出错误,所以生成的客户端是 ergonotic for 生产用途.

## 安装

```bash
npm install @coval/sdk
```

需要节点18+.

## 快开始

```ts
import { CovalClient } from '@coval/sdk';

const coval = new CovalClient({ apiKey: process.env.COVAL_API_KEY! });

// List agents
const { agents } = await coval.agents.listAgents({ pageSize: 25 });

// Submit a production conversation for evaluation
await coval.conversations.submitConversation({
  covalConversationsAPISubmitConversationRequest: {
    agent_id: 'my-agent-id',
    external_conversation_id: 'call-2026-05-11-abc',
    occurred_at: new Date(),
    transcript: [
      { role: 'agent', content: 'Hi, thanks for calling.' },
      { role: 'user', content: "I'd like to update my account." },
    ],
  },
});
```

## 包装纸加上什么

### 奥特 - `x-api-key` (减)

Coval的网关对API-键头头的大小写敏感. 大写 `X-API-Key` 返回时 `Missing API Key`编辑 `CovalClient` 总是发送 小写 `x-api-key`,所以你不用考虑.

### 以指数回转进行回转

给天花板 `GET`, (中文(简体) ), `HEAD`,以及 `OPTIONS` 请求,客户端重试 自动打开 `408`, (中文(简体) ), `429`,以及 `5xx` 回应,加上网络错误. 默认:3次尝试,200ms碱性延迟与焦急,5s盖. `Retry-After` 信头(包括秒和HTTP-date)均被尊重. 更改请求不是 重审,除非你明确添加他们的方法 `retryableMethods`。 。 。 .

```ts
const coval = new CovalClient({
  apiKey: process.env.COVAL_API_KEY!,
  retry: { maxAttempts: 5, baseDelayMs: 500, maxDelayMs: 10_000 },
});

// Disable retries entirely:
const coval2 = new CovalClient({ apiKey, retry: false });
```

### 输入错误

每个非-2xxHTTP响应都变成一个 `CovalApiError` 复试后为 筋疲力尽了 网络失败变成 `CovalNetworkError`。两者都延伸 `Error`, (中文(简体) ), 这么平淡 `try/catch` 工作时.

```ts
import { CovalApiError } from '@coval/sdk';

try {
  await coval.agents.getAgent({ agentId: 'unknown' });
} catch (err) {
  if (err instanceof CovalApiError) {
    console.error(err.status, err.code, err.message, err.requestId);
  }
}
```

### 延展器

列表端点返回一页加一页 `next_page_token`编辑 `paginate` 帮助者将它变成一个同步执行器,这样你就不用管理符号了.

```ts
import { paginate, collectAll } from '@coval/sdk';

for await (const agent of paginate({
  fetchPage: (pageToken) => coval.agents.listAgents({ pageToken, pageSize: 50 }),
  items: (page) => page.agents,
  nextToken: (page) => page.next_page_token,
})) {
  console.log(agent.id, agent.display_name);
}

// Or collect everything into an array:
const all = await collectAll({
  fetchPage: (pageToken) => coval.simulations.listSimulations({ pageToken }),
  items: (p) => p.simulations,
  nextToken: (p) => p.next_page_token,
});
```

### 断断续续的故障诊断

在途中死亡的请求从未到达API,所以没有 服务器侧跟踪它。 客户端保留直播计数器:

```ts
coval.stats;
// { calls: 12, requests: 14, retries: 2, networkErrors: 1 }
```

`calls` 是逻辑 API 调用, `requests` 计数 `fetch` 包括 重复,以及 `networkErrors` 在没有回复的情况下计算失败 都说吧 在报告零星超时时包括这些内容。 每次重试的行和 每一次过境故障 :

```ts
const coval = new CovalClient({ apiKey, onDebug: console.debug });
```

### 连接再使用

在节点上,客户端使用全局 `fetch` (unidici),闲置期满 大约4秒后保持动态连接。 这一点很重要: 网络路径默默地不关闭闲置连接并重用 将请求拖到超时, 因为它从未到达服务器 .

在该窗口内提出的要求仍然可以重新使用集合连接。 狦 不经常地提交,或者你看见没有解释的暂停,你应当明白地传达: 调度器 :

```ts
import { Agent, fetch as undiciFetch } from 'undici';

const coval = new CovalClient({
  apiKey,
  fetch: ((input, init) =>
    undiciFetch(input as never, { ...init, dispatcher: new Agent({ keepAliveTimeout: 1_000 }) })) as typeof fetch,
});
```

Python SDK 直接暴露出与 `max_idle_seconds`。 。 。 .

## 自定义

### 覆盖基础 URL( stage,自主机)

```ts
const coval = new CovalClient({
  apiKey,
  baseUrl: 'https://staging.api.coval.dev/v1',
});
```

### 插入自定义中间软件

```ts
const coval = new CovalClient({
  apiKey,
  middleware: [
    {
      async pre({ url, init }) {
        console.log('→', init.method, url);
        return undefined;
      },
    },
  ],
});
```

### 覆盖取取取( 例如, 无保留- 保留)

```ts
import { fetch as undiciFetch } from 'undici';

const coval = new CovalClient({ apiKey, fetch: undiciFetch });
```

## 实例

可在这回购中运行。 设定 `COVAL_API_KEY` (和 `COVAL_AGENT_ID` 联 合 国 并运行 :

```bash
npm run example:list-agents
npm run example:submit-conversation
```

## 版本

生成的地表跟踪了基本的Coval API. 光谱改变 打破生成的客户端递增 **小声** 版本。 手写 折断公共类型Script API的包装更改也会递增 **小声** 版本。 错误修正增量 **补丁** 版本.

## 重新生成

如果您想要在当地重生客户端 :

```bash
# From the repo root, with the docs repo checked out as a sibling:
node scripts/bundle-spec.mjs
bash scripts/generate-sdks.sh
```

见 [捐款](https://github.com/coval-ai/coval-sdk/blob/main/CONTRIBUTING.md) 供当地一代人使用 [发布指南](https://github.com/coval-ai/coval-sdk/blob/main/docs/releasing.md) 用于预定的再生设置.

## 许可证

麻省理工学院.

## 常见问题

### @coval/sdk 是什么？

为Coval评价平台API所打入的TypeScript客户端\.

### 如何安装 @coval/sdk？

在项目目录运行 npm install @coval/sdk，或使用 pnpm add / yarn add / bun add。

### @coval/sdk 支持 TypeScript 吗？

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

### @coval/sdk 支持 ESM 还是 CommonJS？

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

### @coval/sdk 需要什么版本的 Node\.js？

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

### @coval/sdk 可以商用吗？

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

### @coval/sdk 的下载量有多少？

根据 npm 官方下载统计，@coval/sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 7,788 次，日均约 260 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @coval/sdk 还在维护吗？

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