# @codespar/types 中文文档

规范地址：https://npmcn.com/package/%40codespar/types/

版本：0\.11\.7
npm 元数据更新时间：2026-10-30T12:22:11.856Z
中文译文更新时间：2026-11-10T08:03:23.343Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40codespar/types
原文对照：https://npmcn.com/package/%40codespar/types/?lang=original
项目主页：https://codespar.dev/
源码仓库：https://github.com/codespar/codespar-core

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

- 包体积（解压后）：511 kB，114 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-04-22T00:27:23.540Z
- 最新版本发布：2026-10-30T12:22:11.423Z
- 近 30 天下载量：5042（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

密码par运行时间共享会话接口合同

## 安装

```sh
npm install @codespar/types
```

也可以使用：`pnpm add @codespar/types`、`yarn add @codespar/types`、`bun add @codespar/types`

## README

# @ codespar/ 类型

零依赖性 TypeScript 包定义了 CodeSpar 运行时间的共享会话接口等级.

任何执行的运行时间 `SessionBase` ——所管理的CodeSpar后端,Anthropic管理代理,自托管服务器,或测试双人——是SDK生态系统中的一等公民. 该合同是运行时间和运行在它们上方的工具之间唯一的接合.

## 安装

```bash
npm install @codespar/types
```

## 接口

### `SessionBase`

任何运行时间都必须执行最小接口 .

```typescript
import type { SessionBase } from "@codespar/types";

interface SessionBase {
  readonly id: string;
  readonly status: "active" | "closed" | "error";

  execute(toolName: string, params: Record<string, unknown>): Promise<ToolResult>;
  send(message: string): Promise<SendResult>;
  sendStream(message: string): AsyncIterable<StreamEvent>;
  connections(): Promise<BaseConnection[]>;
  close(): Promise<void>;
}
```

### `Session`

编码的特有扩展 `SessionBase`,用于通过管理的代码Spar API创建会话.

```typescript
import type { Session } from "@codespar/types";

interface Session extends SessionBase {
  proxyExecute(request: ProxyRequest): Promise<ProxyResult>;
  authorize(serverId: string, config: AuthConfig): Promise<AuthResult>;

  // Tool discovery + connection wizard (codespar_discover / codespar_manage_connections)
  discover(useCase: string, options?: DiscoverOptions): Promise<DiscoverResult>;
  connectionWizard(options: ConnectionWizardOptions): Promise<ConnectionWizardResult>;

  // Meta-tool wrappers — typed payloads, same wire as session.execute(...)
  charge(args: ChargeArgs): Promise<ChargeResult>;
  ship(args: ShipArgs): Promise<ShipResult>;
  shop(args: ShopArgs): Promise<ShopResult>;

  // Async settlement (codespar_charge / codespar_pay)
  paymentStatus(toolCallId: string): Promise<PaymentStatusResult>;
  paymentStatusStream(
    toolCallId: string,
    options: PaymentStatusStreamOptions,
  ): Promise<PaymentStatusResult>;

  // Async verification (codespar_kyc)
  verificationStatus(toolCallId: string): Promise<VerificationStatusResult>;
  verificationStatusStream(
    toolCallId: string,
    options: VerificationStatusStreamOptions,
  ): Promise<VerificationStatusResult>;

  mcp?: {
    url: string;
    headers: Record<string, string>;
  };
}
```

### `isCodesparSession`

将护卫类型缩小a `SessionBase` 改为 `Session` 当您需要特定代码的方法时.

```typescript
import { isCodesparSession } from "@codespar/types";

function useSession(session: SessionBase) {
  if (isCodesparSession(session)) {
    // session is Session here — proxyExecute, authorize, mcp available
    const config = session.mcp;
  }
}
```

## 电线类型

| 类型 | 说明 |
| --- | --- |
| `ToolResult` | 返回价值 `execute()` —— 说 `success`, (中文(简体) ), `data`, (中文(简体) ), `error`, (中文(简体) ), `duration`, (中文(简体) ), `server`, (中文(简体) ), `tool` |
| `SendResult` | 返回价值 `send()` —— 说 `message`, (中文(简体) ), `tool_calls`, (中文(简体) ), `iterations` |
| `StreamEvent` | 联合活动 `sendStream()` —— 说 `user_message`, (中文(简体) ), `assistant_text`, (中文(简体) ), `tool_use`, (中文(简体) ), `tool_result`, (中文(简体) ), `done`, (中文(简体) ), `error` |
| `BaseConnection` | 从 `connections()` —— 说 `id`, (中文(简体) ), `connected` |
| `ServerConnection` | 扩展与名称和提供者元数据的联系 |
| `ProxyRequest` | 输入到 `proxyExecute()` —— 说 `server`, (中文(简体) ), `endpoint`, (中文(简体) ), `method`, (中文(简体) ), `body`, (中文(简体) ), `headers` |
| `ProxyResult` | 返回价值 `proxyExecute()` —— 说 `status`, (中文(简体) ), `data`, (中文(简体) ), `headers`, (中文(简体) ), `duration`, (中文(简体) ), `proxy_call_id` |
| `AuthConfig` | 输入到 `authorize()` —— 说 `redirectUri`, (中文(简体) ), `scopes?` |
| `AuthResult` | 返回价值 `authorize()` —— 说 `linkToken`, (中文(简体) ), `authorizeUrl`, (中文(简体) ), `expiresAt` |
| `DiscoverOptions` 编号 : `DiscoverResult` 编号 : `DiscoverToolMatch` 编号 : `DiscoverPlanStep` | 线形 `session.discover(...)` (单位:千美元)`codespar_discover`(中文(简体) ) |
| `ConnectionWizardOptions` 编号 : `ConnectionWizardResult` 编号 : `ConnectionStatusRow` | 线形 `session.connectionWizard(...)` (单位:千美元)`codespar_manage_connections`(中文(简体) ) |
| `ChargeArgs` 编号 : `ChargeBuyer` 编号 : `ChargeResult` | 线形 `session.charge(...)` (单位:千美元)`codespar_charge`,输入) |
| `ShipArgs` 编号 : `ShipAddress` 编号 : `ShipItem` 编号 : `ShipResult` | 线形 `session.ship(...)` (单位:千美元)`codespar_ship`(中文(简体) ) |
| `ShopArgs` 编号 : `ShopSearchArgs` 编号 : `ShopCheckoutArgs` 编号 : `ShopStatusArgs` 编号 : `ShopOffer` 编号 : `ShopVariant` 编号 : `ShopResult` 编号 : `ShopSearchResult` 编号 : `ShopCheckoutResult` 编号 : `ShopStatusResult` 编号 : `ShopCheckoutStatus` | 线形 `session.shop(...)` (单位:千美元)`codespar_shop`()——受到歧视 `action`. 光谱: [`docs/codespar-shop-contract.md`](https://npmcn.com/package/docs/codespar-shop-contract.md) |
| `PaymentStatus` 编号 : `PaymentStatusResult` 编号 : `PaymentStatusEvent` | 线形 `session.paymentStatus(toolCallId)` ——同声网络浏览关联 |
| `PaymentStatusStreamOptions` | 备选方案 `session.paymentStatusStream(...)` —— 说 `onUpdate?`, (中文(简体) ), `signal?` |
| `VerificationStatus` 编号 : `VerificationStatusResult` 编号 : `VerificationStatusEvent` | 线形 `session.verificationStatus(toolCallId)` ——同步KYC民意调查 |
| `VerificationStatusStreamOptions` | 备选方案 `session.verificationStatusStream(...)` —— 说 `onUpdate?`, (中文(简体) ), `signal?` |

> **已输入的元工具外观( T)`shop()`, (中文(简体) ), `charge()`, (中文(简体) ), `ship()`,.)需要运行时间来执行元工具.** 这些电线类型是合同 `@codespar/sdk` 是一个客户端结束 `execute("codespar_<tool>", args)`。在自办的运行时间没有登记该元工具的执行的情况下,调用返回 `Tool not registered`。 + 外观类型为 MIT 和可自宿; 执行时间为 SDK 点的运行时间.

## 符合性测试

`@codespar/types` 船舶a `runContractSuite` 帮助者 a `/testing` 子路径导出 。 它登记一个测试套件 用来锻炼五个 `SessionBase` 方法对抗活的 HTTP 端点.

```typescript
// my-runtime.test.ts
import { runContractSuite } from "@codespar/types/testing";

// Skip unless the env vars are present
const apiKey = process.env["MY_RUNTIME_API_KEY"];
const baseUrl = process.env["MY_RUNTIME_BASE_URL"] ?? "http://localhost:3000";

if (apiKey) {
  runContractSuite(baseUrl, apiKey);
}
```

该套间开放会话通过 `POST /v1/sessions` 与 `Authorization: Bearer <apiKey>` 和身体状况 `{ servers: [], user_id: "contract-suite" }`每条腿都说 `201` 载体 `id`, (中文(简体) ), `status: "active"`,所贴 `user_id`, (中文(简体) ), `servers` 联合国 `string[]` 包括每个张贴的id)和可解析 `created_at` ——田园 `@codespar/sdk` 建立会议基础。 然后验证:

-   `execute()` 调用注册工具并返回 a `ToolResult`
-   `send()` 返回 a `SendResult` 带有 `message` 字段
-   `sendStream()` 产量类型良好 `StreamEvent`包括一个 `done` 事件
-   `connections()` 回答 2xx 为 `{ servers }`,每个条目 `id` 财务报告和审定财务报表 `connected` (单位:千美元)`tools`,当存在时,必须是数组)
-   `close()` 过渡 `session.status` 改为 `"closed"`

见 [文件/海关会议-运行时间](https://npmcn.com/package/docs/custom-session-runtime.md) 为一份全面实施指南.

## 还需要吗?

需要治理、预算限制和代理付款的审计线索? **[代码Spar 企业](https://codespar.dev/enterprise)** 在这些MCP服务器上添加了政策引擎,支付路由,以及合规模板.

## 许可证

麻省理工学院 - [代码.dev](https://codespar.dev/)

## 常见问题

### @codespar/types 是什么？

密码par运行时间共享会话接口合同

### 如何安装 @codespar/types？

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

### @codespar/types 支持 TypeScript 吗？

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

### @codespar/types 支持 ESM 还是 CommonJS？

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

### @codespar/types 需要什么版本的 Node\.js？

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

### @codespar/types 可以商用吗？

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

### @codespar/types 的下载量有多少？

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

### @codespar/types 还在维护吗？

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