# @contextvm/sdk 中文文档

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

版本：0\.14\.3
npm 元数据更新时间：2026-09-28T14:36:55.883Z
中文译文更新时间：2026-11-10T16:57:41.453Z
软件包许可：LGPL-3\.0-1

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

原始 npm 页面：https://www.npmjs.com/package/%40contextvm/sdk
原文对照：https://npmcn.com/package/%40contextvm/sdk/?lang=original
源码仓库：https://github.com/ContextVM/sdk

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

- 包体积（解压后）：1.3 MB，388 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2025-07-15T09:23:26.854Z
- 最新版本发布：2026-09-28T14:36:55.662Z
- 近 30 天下载量：18565（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：144（近 12 个月 102 个）

## 中文简介

JavaScript/ TypeScript 的背景VM SDK

## 安装

```sh
npm install @contextvm/sdk
```

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

## README

# 上下文VM SDK

一个JavaScript/TypeScript SDK,它执行上下文Vending Machine协议,连接诺斯特和模型上下文协议(MCP),以便分散访问和曝光计算服务.

## 概览

ContextVM协议定义了诺斯特和模型上下文机如何可以用来曝光MCP服务器能力,从而能够通过分散的,加密的安全通信系统,实现这些资源的标准化使用.

SDK提供了与上下文VM协议互动的必要组件:

-   **核心单元**:包含基本定义,常数,接口,以及公用设施(如加密,串行等).
-   **运输**:通信的关键,提供 `NostrClientTransport` 财务报告和审定财务报表 `NostrServerTransport` 执行使MCP超越诺斯特.
-   **代理服务器**:一个客户端-侧MCP服务器,通过诺斯特连接到其他服务器,在本地暴露服务器能力. 对不本土支持诺斯特运输的客户特别有用.
-   **网关**:执行诺斯特服务器传输,绑定在另一个MCP服务器上,并通过诺斯特网络暴露其能力.
-   **中继**:用于管理诺斯特继电器,抽象继电器相互作用的功能.
-   **签名**:提供诺斯特事件所需的加密签名能力.

代理和Gateway都以诺斯特运输为杠杆,使得现有的MCP服务器在获得诺斯特互操作性的同时能够保持常规运输.

## 安装

```bash
npm install @contextvm/sdk
```

**说明:** 您可以使用您的首选软件包管理器安装 SDK .

## 软件包结构

SDK支持两种导入模式:

### 主入口( 建议)

为方便从根导入 :

```typescript
import { NostrClientTransport, createLogger } from '@contextvm/sdk';
```

### 子路径导入( Tree- 抖动)

对于更小的捆绑,直接从特定模块导入:

```typescript
// Core utilities
import { createLogger } from '@contextvm/sdk/core';

// Transport implementations
import { NostrClientTransport } from '@contextvm/sdk/transport';

// Relay management
import { RelayPool } from '@contextvm/sdk/relay';

// Cryptographic signing
import { NostrSigner } from '@contextvm/sdk/signer';

// Gateway and Proxy
import { Gateway } from '@contextvm/sdk/gateway';
import { Proxy } from '@contextvm/sdk/proxy';
```

**说明:** 子路径导入帮助捆绑者消除未使用的代码 。 当捆绑大小重要时使用它们.

## 使用量

访问 [背景VM 文档](https://contextvm.org/) 用于了解如何使用上下文VM.

### 日志

SDK使用皮诺来进行高性能记录,并带有结构化的JSON输出. 默认情况下,会将日志写入 stderr,以符合MCP协议的预期.

#### 基本用途

```typescript
import { createLogger } from '@contextvm/sdk/core';

// Create a logger for your module
const logger = createLogger('my-module');

logger.info('Application started');
logger.error('An error occurred', { error: 'details' });
```

#### 配置选项

您可以使用各种选项配置日志 :

```typescript
import { createLogger, LoggerConfig } from '@contextvm/sdk/core';

const config: LoggerConfig = {
  level: 'debug', // Minimum log level (debug, info, warn, error)
  file: 'app.log', // Optional: log to a file instead of stderr
};

const logger = createLogger('my-module', config);
```

**说明:** 当日志被写成 stderr/stdout(不是文件),以便在开发期间更好的可读性时,会自动启用漂亮的打印.

#### 配置环境变量

日志可以使用环境变量进行配置,这对调整日志输出而不改变代码是有用的.

-   **`LOG_LEVEL`**: 设置最小日志级别.
    -   **数值**数字 : `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`。 。 。 .
    -   **默认**数字 : `info`。 。 。 .
-   **`LOG_DESTINATION`**:设置日志输出目的地.
    -   **数值**数字 : `stderr` (违约), `stdout`,或 `file`。 。 。 .
-   **`LOG_FILE`**: 指定文件路径时 `LOG_DESTINATION` 实值 `file`。 。 。 .
-   **`LOG_ENABLED`**: 启用或禁用日志.
    -   **数值**数字 : `true` (违约)或 `false`。 。 。 .

##### 在节点.js中的配置

在运行应用程序前设定您 shell 中的变量 :

```bash
# Set log level to debug
LOG_LEVEL=debug node app.js

# Log to a file instead of the console
LOG_DESTINATION=file LOG_FILE=./app.log node app.js

# Disable logging entirely
LOG_ENABLED=false node app.js
```

##### 浏览器中的配置

在浏览器环境中,您可以通过设置全局配置日志级别 `LOG_LEVEL` 变量在 `window` 对象 **在此之前** sDK是导入或使用的.

```javascript
// Set this in a <script> tag in your HTML or at the top of your entry point
window.LOG_LEVEL = 'debug';

// Now, when you import and use the SDK, it will use the 'debug' log level.
import { logger } from '@contextvm/sdk';
logger.debug('This is a debug message.');
```

#### 模块特定 Loggers

为不同的模块创建儿童日志以添加上下文 :

```typescript
const baseLogger = createLogger('my-app');
const authLogger = baseLogger.withModule('auth');
const dbLogger = baseLogger.withModule('database');

authLogger.info('User login attempt');
dbLogger.debug('Query executed', { query: 'SELECT * FROM users' });
```

## 发展

这个项目需要 [阿宝](https://bun.sh/) (版本1.2.0或以上).

1.  清除仓库 :

```bash
git clone https://github.com/ContextVM/sdk.git
cd sdk
```

2.  安装依赖性 :

```bash
bun install
```

### 运行测试

要运行测试套房,请使用 Bun:

```bash
bun test
```

## 常见问题

### @contextvm/sdk 是什么？

JavaScript/ TypeScript 的背景VM SDK

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

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

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

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

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

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

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

@contextvm/sdk 使用 LGPL-3\.0-1 许可。声明的许可为 LGPL-3\.0-1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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