# @chalk-ai/client 中文文档

规范地址：https://npmcn.com/package/%40chalk-ai/client/

版本：1\.31\.13
npm 元数据更新时间：2026-08-06T13:37:53.713Z
中文译文更新时间：2026-11-09T09:59:18.857Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：4.2 MB，247 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2022-11-10T20:07:14.637Z
- 最新版本发布：2026-08-06T13:37:53.320Z
- 近 30 天下载量：10335（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 2 个）

## 中文简介

Chark 的脚本客户端

## 安装

```sh
npm install @chalk-ai/client
```

也可以使用：`pnpm add @chalk-ai/client`、`yarn add @chalk-ai/client`、`bun add @chalk-ai/client`

## README

# @ chalk-ai/ 客户端

[![npm version](https://img.shields.io/npm/v/@chalk-ai/client?label=%40chalk-ai%2Fclient&logo=npm)](https://www.npmjs.com/package/@chalk-ai/client) ![CI](https://img.shields.io/github/actions/workflow/status/chalk-ai/chalk-ts/check.yml?branch=main)

Chalk的TypeScript客户端.

## 安装

```sh
$ yarn add @chalk-ai/client
```

## 生成类型

从您的 Chark 项目目录开始, 运行 :

```sh
$ chalk codegen typescript --out=generated_types.ts
```

## 使用量

### 现代 JavaScript ES6

```ts
import { ChalkGRPCClient } from "@chalk-ai/client"
// import { ChalkClient } from "@chalk-ai/client";

// Import your generated types (recommended)
import { FeaturesType } from "local/generated_types";

// Alternatively, define features you want to pull using the client
// as an interface with the feature type and feature name.
interface FeaturesType {
  "user.id": string;
  "user.fraud_score": number;
}

const client = new ChalkGRPCClient<FeaturesType>();

const result = await client.query({
  inputs: {
    "user.id": "1",
  },
  outputs: ["user.fraud_score"],
});

// The property `.data` has auto-complete based on the
// list provided in `output` above. So if you try to pull
// a feature that wasn't requested, you will see an error
// in type checking.
console.log(result.data["user.fraud_score"].value);
```

### 常见JS

```ts
var ChalkGRPCClient = require("@chalk-ai/client").ChalkGRPCClient;
// var ChalkClient = require("@chalk-ai/client").ChalkClient; 

interface FeaturesType {
  "user.id": string;
  "user.fraud_score": number;
}

var client = new ChalkGRPCClient<FeaturesType>();

client
  .query({
    inputs: {
      "user.id": "1",
    },
    outputs: ["user.fraud_score"],
  })
  .then((result) => {
    console.log(result.data["user.fraud_score"].value);
  });
```

## 构造器选项( gRPC)

见 [hTTP 选项](https://npmcn.com/package/%40chalk-ai/client/#readme-constructor-options-legacy) 如果您正在使用 HTTP 客户端, 但我们鼓励 读取 [移徙指南](https://npmcn.com/package/%40chalk-ai/client/#readme-migrating-to-the-grpc-client)。 。 。 .

```ts
import { ChalkGRPCClient } from "@chalk-ai/client"

const options: ChalkGRPCClientOpts = {/* ... */ };
const chalkClient = new ChalkGRPCClient(options);

export interface ChalkGRPCClientOpts {
  /**
   * Your Chalk Client ID. This value will be read from the _CHALK_CLIENT_ID environment variable if not set explicitly.
   *
   * If not specified and unset by your environment, an error will be thrown on client creation
   */
  clientId?: string;

  /**
   * Your Chalk Client Secret. This value will be read from the _CHALK_CLIENT_SECRET environment variable if not set explicitly.
   *
   * If not specified and unset by your environment, an error will be thrown on client creation
   */
  clientSecret?: string;

  /**
   * The URL of your chalk API server. Defaults to https://api.chalk.ai
   */
  apiServer?: string;

  /**
   * The environment that your client will run against. This value will be read from the _CHALK_ACTIVE_ENVIRONMENT environment variable if not set explicitly.
   *
   * If not specified and unset by your environment, an error will be thrown on client creation
   */
  activeEnvironment?: string;

  /**
   * A custom fetch client that will replace the fetch polyfill used by default. Used by both the HTTP and gRPC
   * clients - the HTTP client for all calls, and the gRPC client for fetching credentials from the API server.
   *
   * If not provided, the client will use the default fetch polyfill (native fetch with node-fetch as a fallback).
   */
  fetch?: CustomFetchClient;

  /**
   * A custom fetch headers object that will replace the fetch Headers polyfill used by default. This is primarily for use
   * with a custom fetch client, and is not the preferred way to add additional headers to requests.
   *
   * If not provided, the client will use the default fetch Headers polyfill (native fetch with node-fetch as a fallback).
   */
  fetchHeaders?: typeof Headers;

  /**
   * The format to use for date-type data.
   *
   * Defaults to "ISO_8601" (in UTC), also supports "EPOCH_MILLIS" as number of milliseconds since epoch
   */
  timestampFormat?: TimestampFormat.ISO_8601 | TimestampFormat.EPOCH_MILLIS;

  /**
   * By default, the client will try to directly connect to the query client using the metadata provided during
   * credentials exchange, which returns a mapping between environment and query server. If this option is
   * truthy, the client will skip this step.
   *
   * The queryServer option will take precedence over this option (i.e. this option is essentially useless).
   * *
   * Defaults to false.
   */
  skipQueryServerFromCredentialExchange?: boolean;

  /**
   * Passed to the internal grpc client upon initialization. Under the hood, Chalk uses the @grpc/grpc-js library
   * and this allows users finer control of their gRPC usage.
   *
   * See https://grpc.github.io/grpc/node/grpc.Client.html for more information on what is supported here.
   */
  grpcClientOptions?: Partial<ClientOptions>;
}
```

## 迁移到 gRPC 客户端

Chalk既支持HTTP客户端,也支持gRPC客户端与Chark接口,但我们大力鼓励用户使用 gRPC 客户端, 以更好的性能, 因为它的目标是一个更能表现的 gRPC 查询服务器 。 成立GRPC后 在您的 Chark 环境中查询服务器, 更改为 gRPC 客户端可以在几个步骤中完成 :

-   使用导入 `ChalkGRPCClient` 改为 `ChalkClient`
-   检查是否需要更改以下初始化选项 :
    -   选项 `useQueryServerFromCredentialExchange` 已改为 `skipQueryServerFromCredentialExchange` 财务报告和审定财务报表 _已否定_ 要更好地反映gRPC查询服务器的默认行为.
    -   检查您的 Chark 环境, 查看任何自定义的路由规则 。 如果您不确定, 请向 Chalk 求救 .
        -   如果您的前一个 SDK 客户端明确设置 `engine-type: engine` 请求时的标题, 需要更改 改为 `engine-grpc` (或省略,gRPC客户端会自动设置此头但会尊重所有覆盖).
        -   很可能没有必要更改规定 `QueryServer` 因为大多数路由是通过 SDK 设置头来完成的,但是 取决于您的设置, 如果使用非标准端口, 这可能需要直接指定 - gRPC 查询服务器监听 在端口时 `443` 默认.
    -   没错 **没有** 需要删除 `fetch` 或者说 `fetchHeaders` 因为这些仍在一些 HTTP 常规中使用 例如获取证书.

初始化修改后,无需更改实际呼叫 - gRPC 客户端使用 相同的函数签名.

此时此刻 `query()`, (中文(简体) ), `queryBulk()`,以及 `multiQuery()` 支持 - 如果您的用法需要其中之一 函数`whoami()`, (中文(简体) ), `triggerResolverRun()`, (中文(简体) ), `uploadSingle()`, (中文(简体) ), `getRunStatus()`),遗产 `ChalkClient` 应使用 我们仍强烈建议将部分查询电话转移到gRPC客户端.

### 支持的环境变量

| 变量 | 仁爱 | 说明 |
| --- | --- | --- |
| `process.env._CHALK_CLIENT_ID` | **需求** | 你的粉笔客户身份证 您必须指定此环境变量或通过一个明确 `clientId` 构建 CharkClient 时的值 |
| `process.env._CHALK_CLIENT_SECRET` | **需求** | 你的粉笔客户秘密 您必须指定此环境变量或通过一个明确 `clientSecret` 构建 CharkClient 时的值 |
| `process.env._CHALK_ACTIVE_ENVIRONMENT` | 可选 | 您的客户端应该连接到的环境 。 如果未指定, 客户端会查询您的项目的默认环境 |
| `process.env._CHALK_API_SERVER` | 可选 | 客户端将与之通信的API服务器. 此默认为 [https://api.calk.ai (英语)](https://api.chalk.ai/) 对大多数消费者来说都足够 |

您可以通过 Chark 客户端找到要使用的相关变量 运行 `chalk config` 带有 Chark 命令行工具.

```sh
$ chalk config

Path:          ~~~
Name:          Organization Token
Client Id:     <client-id>
Client Secret: <client-secret>
Environment:   <active-environment>
API Server:    https://api.chalk.ai
Valid Until:   2023-11-10T06:11:17.516000
```

## 构造器选项( Legacy)

```ts
import { ChalkCLient } from "@chalk-ai/client"

const options: ChalkClientOpts = {/* ... */};
const chalkClient = new ChalkClient(opts);

export interface ChalkClientOpts {
  /**
   * Your Chalk Client ID. This value will be read from the _CHALK_CLIENT_ID environment variable if not set explicitly.
   *
   * If not specified and unset by your environment, an error will be thrown on client creation
   */
  clientId?: string;

  /**
   * Your Chalk Client Secret. This value will be read from the _CHALK_CLIENT_SECRET environment variable if not set explicitly.
   *
   * If not specified and unset by your environment, an error will be thrown on client creation
   */
  clientSecret?: string;

  /**
   * The URL of your chalk API server. Defaults to https://api.chalk.ai
   */
  apiServer?: string;

  /**
   * The environment that your client will run against. This value will be read from the _CHALK_ACTIVE_ENVIRONMENT environment variable if not set explicitly.
   *
   * If not specified and unset by your environment, an error will be thrown on client creation
   */
  activeEnvironment?: string;

  /**
   * A custom fetch client that will replace the fetch polyfill used by default.
   *
   * If not provided, the client will use the default fetch polyfill (native fetch with node-fetch as a fallback).
   */
  fetch?: CustomFetchClient;

  /**
   * A custom fetch headers object that will replace the fetch Headers polyfill used by default.
   *
   * If not provided, the client will use the default fetch Headers polyfill (native fetch with node-fetch as a fallback).
   */
  fetchHeaders?: typeof Headers;

  /**
   * The format to use for date-type data.
   *
   * Defaults to "ISO_8601" (in UTC), also supports "EPOCH_MILLIS" as number of milliseconds since epoch
   */
  timestampFormat?: TimestampFormat.ISO_8601 | TimestampFormat.EPOCH_MILLIS;

  /**
   * If true, will try to directly connect to the query client using the metadata provided during
   * credentials exchange, which returns a mapping between environment and query server.
   *
   * The queryServer option will take precedence over this option (i.e. this option is essentially useless).
   *
   * Defaults to false, the legacy behavior of this client. This will change at the next major release.
   */
  useQueryServerFromCredentialExchange?: boolean;
}
```

## 常见问题

### @chalk-ai/client 是什么？

Chark 的脚本客户端

### 如何安装 @chalk-ai/client？

在项目目录运行 npm install @chalk-ai/client，或使用 pnpm add / yarn add / bun add。

### @chalk-ai/client 支持 TypeScript 吗？

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

### @chalk-ai/client 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @chalk-ai/client 可以商用吗？

@chalk-ai/client 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @chalk-ai/client 的下载量有多少？

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

### @chalk-ai/client 还在维护吗？

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