@choiceform/core-ai-sdk

Core AI SDK

提供了对接 Core AI Service API 的客户端开发包。

安装

需要同时安装两个包：

pnpm add @choiceform/core-ai-sdk pnpm add @choiceform/core-ai-shared-schema

前者是 SDK 本体，后者是客户端与服务端共享的 Schema 和 Types。都需要确保安装最新的版本，以避免类型不匹配。

使用

首先创建一个单独的文件来初始化 SDK Client，例如 /lib/core-ai-sdk.ts

import { createClient } from "@choiceform/core-ai-sdk"

export client = createClient({
  apiHostURL: <Core AI 服务端的地址，不加任何路径>
  accessToken?: <登陆后获得的访问令牌（可选）>
})

- `apiHostURL`：当前提供测试环境地址为 https://core-ai.choiceform.io（建议保存为环境变量）
- `accessToken`：初始化 SDK Client 时可以直接附加访问令牌，但这是可选的，详见下文

更新令牌

由于 SDK Client 只需要实例化一次，而在实例化的时候往往不能保证此时一定会有令牌；又或者在 SPA 应用中登出之后再登陆会刷新令牌且 SDK Client 无需重新初始化——这可能会导致令牌实效。

因此 SDK Client 提供了一个 attachAccessToken 的方法用于在需要的时候更新令牌。建议在应用初始化阶段能确保获得用户 session 数据之后立即调用该方法更新令牌。这样无论是首次初始化还是登出再登陆都可以保障 SDK Client 始终能使用最新的有效令牌来发起网络请求。例如：

// 在应用初始化阶段能获得 session 的时候（意味着 token 是有效的）
client.attachAccessToken(newToken) // <- 新的令牌，是否编码不重要，SDK 会处理重复编码等问题。

调用方法

SDK Client 是分不同模块来调用的，具体有哪些模块请参考附录中提供的文档地址。

例如，如果要调用 Application 模块的获取应用列表方法：

// applications 即返回的应用列表，默认只会查询当前用户创建的应用且不包括 archived
const { data: applications } = await client.application.listByCreator()

// archived 返回当前用户创建且以被软删除的应用列表
const { data: archived } = await client.application.listByCreator({ archived: true })

类型

SDK Client 提供的各种方法已经是类型完备的，包括入参的类型和返回值的类型，具体定义可参见文档内容。

如果需要单独使用某些类型，可以通过 @choiceform/core-ai-shared-schema 来导入，例如：

import type { Application } from "@choiceform/core-ai-shared-schema"
//                ^? -> 此为 Application 的完整类型定义

如果需要单独使用某些 Schema 也照此处理即可，所有的 Schema 都是 zod v4 编写的。

附录

SDK 在线文档：https://core-ai.choiceform.io/public/index.html

API 在线文档：https://core-ai.choiceform.io/openapi 注：SDK 已包含所有可用的 API 接口封装，一般不需要参考 API 文档。API 文档主要供调试问题或者无法使用 SDK 的场景使用。