# @axiom-lattice/client-sdk 中文文档

规范地址：https://npmcn.com/package/%40axiom-lattice/client-sdk/

版本：8\.0\.2
npm 元数据更新时间：2026-11-03T01:39:57.628Z
中文译文更新时间：2026-11-07T19:08:16.050Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40axiom-lattice/client-sdk
原文对照：https://npmcn.com/package/%40axiom-lattice/client-sdk/?lang=original

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

- 包体积（解压后）：7.5 MB，213 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.10\.0
- 运行依赖：2 个
- 首次发布：2025-09-01T09:24:53.034Z
- 最新版本发布：2026-11-03T01:39:57.452Z
- 近 30 天下载量：3062（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：145（近 12 个月 116 个）

## 中文简介

与代理服务 API 互动的 SDK 类型脚本客户端

## 安装

```sh
npm install @axiom-lattice/client-sdk
```

也可以使用：`pnpm add @axiom-lattice/client-sdk`、`yarn add @axiom-lattice/client-sdk`、`bun add @axiom-lattice/client-sdk`

## README

# Axiom Lattice 客户端 SDK

Axiom Lattice代理服务API的TypeScript客户端.

## 概览

客户端SDK为与Axiom Lattice Agent Service API的交互提供了简单的接口. 它处理认证、请求/答复格式化和错误处理.

## 运行时间和范围

此软件包是运行时中立的: 它针对浏览器, 节点 18+, Deno, Bun 和类似 现代JS运行时间. 它只包含HTTP/SSE客户端和协议类型; 反应钩, UI组件和服务器侧业务逻辑存在于其他软件包中.

公共API使用跨运行时间Web标准类型. 文件/存档输入使用 `Blob` (浏览器) `File` 是一个 `Blob` 子类); SDK 不要求只使用 DOM `File` 或者说 只节点 `node:*` 类型。 建构中的节点类型用于测试/工具,而不是 公共合同。 见 `docs/architecture/decisions/ADR-260-client-sdk-runtime-neutral.md`。 。 。 .

## 特征

-   创建和管理线索
-   发送信息和接收回复
-   以事件为基础的回调流响应
-   注册客户端工具
-   处理工具呼叫和回复
-   用 ChunkMessageMerger 处理流媒体消息块
-   HTTP 客户端标准化, 对所有 API 调用使用 axios
-   通过认证代理 Web App 发布管理 `client.webApps`

## 代理网络应用管理

`client.webApps` 是认证的控制台管理 API,而不是匿名的外部运行时间客户端 。 它规定 `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `enable`, (中文(简体) ), `disable`,以及 `delete`。 。 。 .

```typescript
import { Client, type CreateAgentWebAppInput } from "@axiom-lattice/client-sdk";

const client = new Client({
  baseURL: "http://localhost:4001",
  apiKey: "console-session-token",
  assistantId: "support-agent",
  transport: "sse",
});

const input: CreateAgentWebAppInput = {
  assistantId: "support-agent",
  name: "Support",
  integration: { type: "react_sdk" },
  scope: { defaultProjectId: "support", allowedProjectIds: ["support"] },
  features: {
    projectSelector: false,
    modelSelector: false,
    threadManagement: true,
    attachments: false,
    hitl: false,
    genUI: false,
  },
  appearance: { title: "Support assistant" },
};

const publication = await client.webApps.create(input);
await client.webApps.enable(publication.id);
```

使用 `@axiom-lattice/react-sdk/web-app` 在外部反应应用程序中。 默认/本地的 SQLite 设置目前使用一个内存的Web App商店,因此发布定义无法从网关重启中幸存; 为持续性配置 PostgreSQL 商店. 见 [管理指南](https://npmcn.com/package/docs/guides/web-apps/management.md)。 。 。 .

## 安装

```bash
npm install @axiom-lattice/client-sdk
```

## 使用量

```typescript
import { Client, createSimpleMessageMerger } from "@axiom-lattice/client-sdk";

// Create a client
const client = new Client({
  baseURL: "https://api.example.com",
  apiKey: "your-api-key",
  assistantId: "your-assistant-id",
  transport: "sse",
  environment: "web", // Optional: "web" (default) or "wechat-miniprogram"
});

// Create a thread
const threadId = await client.createThread({
  metadata: { user: "user123" },
});

// Send a message
const response = await client.chat.send({
  threadId,
  messages: [
    {
      role: "user",
      content: "Hello, how can you help me?",
      id: "msg-1",
    },
  ],
});

// Stream a message
const stopStreaming = client.chat.stream(
  {
    threadId,
    messages: [
      {
        role: "user",
        content: "Tell me a story",
        id: "msg-2",
      },
    ],
  },
  (event) => {
    console.log("Event:", event);
  },
  () => {
    console.log("Stream completed");
  },
  (error) => {
    console.error("Stream error:", error);
  }
);

// Stop streaming if needed
// stopStreaming();

// Use ChunkMessageMerger to process streaming chunks
const merger = createSimpleMessageMerger();

// Process user message
merger.push({
  type: "human",
  data: {
    id: "user-1",
    content: "Hello",
  },
});

// Process AI message with tool calls
merger.push({
  type: "ai",
  data: {
    id: "ai-1",
    content: "I need to search for that.",
    tool_calls: [
      {
        name: "search",
        args: { query: "typescript" },
        id: "search-1",
      },
    ],
  },
});

// Process tool response
merger.push({
  type: "tool",
  data: {
    id: "tool-1",
    content: "Search results: ...",
    tool_call_id: "search-1",
  },
});

// Get merged messages
const messages = merger.getMessages();
```

## 移徙说明

### 运行时环境支持

截至1.0.13版本,客户端SDK现在通过该版本支持不同的运行时环境 `environment` 配置选项。 目前得到支持的环境有:

-   `"web"` (默认):所有HTTP请求都使用axios,包括流式响应
-   `"wechat-miniprogram"`: 使用自定义 WeChat Mini 程序 HTTP 客户端执行来兼容 WeChat Mini 程序

具体说明环境:

```typescript
const client = new Client({
  // ... other options
  environment: "wechat-miniprogram", // For WeChat Mini Program environments
});
```

WeChat Mini 程序环境对流化响应使用不同的方法,因为真正的流化在此环境中得不到支持. 它使用投票机制.

### HTTP 客户端标准化

截至1.0.12版本,客户端SDK现在只对所有HTTP请求使用axios,包括流回. 此前,SDK使用Axios组合来进行常规请求,而原生取API来进行流取. 这一变化使整个SDK的HTTP客户端实施标准化.

福利:

-   一致的错误处理
-   统一请求/答复拦截器
-   简化维护和调试
-   更好地兼容不同的 JavaScript 环境

### 春克麦斯墨尔格Name

这个 `ChunkMessageMerger` 模块已从网络项目移至客户端-sdk软件包。 它提供了处理流媒体消息块并将其合并为完整消息的功能.

用来:

```typescript
import { createSimpleMessageMerger } from "@axiom-lattice/client-sdk";

const merger = createSimpleMessageMerger();
// Use merger methods: push, getMessages, reset, etc.
```

### 未来的移徙计划

目前的网络项目使用自身的执行 `useChat` 与网络应用程序的 API 和信件格式紧密结合。 未来,我们计划迁移网络项目 使用反应-sdk's `useChat` hook,为聊天互动提供了更标准化的界面.

今后移徙的步骤:

1.  更新网络项目的信息类型, 以与响应- sdk 的信息格式保持一致
2.  用客户端- sdk 方法取代直接 API 调用
3.  整合反应- sdk 使用 Chat 钩
4.  更新用户界面组件以使用新信件格式

## API 参考

### 客户端

与Axiom Lattice代理服务API互动的主要客户类.

### WeChat 客户端

使用本地软件的 WeChat Mini 程序的专门客户端 `wx` 网络请求的API.

```typescript
import { WeChatClient } from "@axiom-lattice/client-sdk";

// Create a WeChat client
const client = new WeChatClient({
  baseURL: "https://api.example.com",
  apiKey: "your-api-key",
  assistantId: "your-assistant-id",
  transport: "sse",
});

// Use the same API methods as the standard Client
const threadId = await client.createThread({
  metadata: { user: "user123" },
});

// Send a message
const response = await client.chat.send({
  threadId,
  messages: [
    {
      role: "user",
      content: "Hello, how can you help me?",
      id: "msg-1",
    },
  ],
});
```

### 春克麦斯墨尔格Name

用于处理流媒体消息块并将其合并为完整消息的功能 .

-   `createSimpleMessageMerger()`: 创建新消息合并实例
    -   `push(chunk)`: 处理信件块
    -   `getMessages()`: 合并所有使用工具调用的信息
    -   `getMessagesWithoutToolCalls()`: 获取没有工具调用的信息
    -   `initialMessages(msgs)`: 以现有信件初始化
    -   `reset()`: 重置合并状态

## 常见问题

### @axiom-lattice/client-sdk 是什么？

与代理服务 API 互动的 SDK 类型脚本客户端

### 如何安装 @axiom-lattice/client-sdk？

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

### @axiom-lattice/client-sdk 支持 TypeScript 吗？

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

### @axiom-lattice/client-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @axiom-lattice/client-sdk 需要什么版本的 Node\.js？

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

### @axiom-lattice/client-sdk 可以商用吗？

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

### @axiom-lattice/client-sdk 的下载量有多少？

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

### @axiom-lattice/client-sdk 还在维护吗？

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