# @cognicloud/sdk 中文文档

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

版本：0\.18\.0
npm 元数据更新时间：2026-10-31T19:35:39.358Z
中文译文更新时间：2026-10-31T21:09:48.339Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：84.5 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-20T10:57:55.134Z
- 最新版本发布：2026-10-31T19:35:39.030Z
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

CogniCloud SDK：调用AI网关端点并管理它们。

## 安装

```sh
npm install @cognicloud/sdk
```

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

## README

# @cognicloud / sdk

调用CogniCloud AI网关端点并从Node.js, Bun， Deno和edge运行时管理它们。

> 预览。第一个版本涵盖了AI网关端点。包括浏览器会话；代理，抓取，保险库和活动还不包括在内。

## 安装

```bash
npm install @cognicloud/sdk
```

键入ESM使用平台 `fetch`，没有运行时依赖。

## 调用端点

```ts
import { EndpointClient } from "@cognicloud/sdk"

const endpoint = new EndpointClient({
  endpointId: process.env.COGNICLOUD_ENDPOINT_ID!,
  credential: process.env.COGNICLOUD_KEY!,
})

const { output, finishReason, usage } = await endpoint.invoke({
  input: [
    { role: "system", content: "Answer in one sentence." },
    { role: "user", content: "Summarise this ticket." },
  ],
  max_output_tokens: 256,
})
```

调用地址为 `<baseUrl>/invoke/<tenant>/<endpointId>`． 端点属于平台租户， `cognicloud`除非你通过 `tenant`． 您还可以传递为端点(`endpoint.url`), `url` 而不是 `endpointId`.

在没有请求映射的情况下，消息体会按原样返回给提供商，并且只接受纯文本消息：

-   没有部署的端点使用响应API： `input` (一串或 `system`/`developer`/`user`/`assistant` 消息), `max_output_tokens`， `temperature`， `top_p`.
-   Azure部署的端点使用聊天完成： `messages`， `max_completion_tokens` (或 `max_tokens`)， `temperature`， `top_p`.

`store` 和 `text.format` （结构化输出）被拒绝使用 `400 invalid_request`． 为 `instructions`， MCP工具和链条的使用 `responses`;用于流媒体使用 `stream`． 有些模特拒绝 `temperature`;然后网关回答 `502 provider_refused`． 端点总是选择模型。

每个模型的答案都是一样的： `output` (文本), `finishReason` （`stop`， `length`， `content_filter`， `other`，或者 `null`), `usage` (令牌数)。

`invoke` 永远不会重试，因为重试的呼叫可以被计费两次。

## 工具响应

`responses` 接受一个带有optional的响应体 `instructions`， MCP工具和 `previous_response_id`． MCP工具将其服务器命名为 `server_url` 和它的信物 `headers`,因为 `{ Authorization: "Bearer <token>" }`． 网关检查地址（https，没有凭据或片段），将批准设置为 `never`，并将两者传递给提供程序。一个只有 `server_label` 指定网关配置的服务器名称。

```ts
const answer = await endpoint.responses({
  input: "Is this invoice valid?",
  instructions: "Check invoices.",
  tools: [{ type: "mcp", server_label: "ksef", allowed_tools: ["validate_invoice_xml"] }],
  tool_choice: "required",
})

const next = await endpoint.responses({ input: "And this one?", previous_response_id: answer.responseId })
```

答案是 `responseId` （用于在同一端点上链接）和 `outputItems` （工具调用和提供者返回的消息）。

## 嵌入的

```ts
const { data } = await endpoint.embeddings({ input: ["first text", "second text"], dimensions: 256 })
const first = data[0].embedding
```

端点必须指向嵌入部署。 `data` 按输入顺序，每个输入有一个项，并且每个调用都作为提示令牌计费。

## 流式传输响应

`stream` 集合 `stream: true` 并在答案被写入时生成事件：

```ts
for await (const event of await endpoint.stream({ messages: [{ role: "user", content: "Write a haiku." }] })) {
  if (event.type === "delta") process.stdout.write(event.text)
  if (event.type === "done") console.log(`\n${event.answer.usage.totalTokens} tokens`)
  if (event.type === "error") console.error(`${event.code}: ${event.message}`)
}
```

每个事件都是 `delta` （`text`)，然后一个 `done` （`answer`与…形状相同 `invoke`)，或一个 `error` （`code`， `message`）. 被拒绝的呼叫用A拒绝 `CogniCloudError` 在任何事件发生之前。流不会重试，也没有总超时；入口在五分钟后结束。提前停止 `break` 关闭连接，网关仍然处理呼叫。

## 发送PDF或图像

```ts
import { EndpointClient, pdfPart, textPart } from "@cognicloud/sdk"
import { readFile } from "node:fs/promises"

const endpoint = new EndpointClient({ url: process.env.COGNICLOUD_ENDPOINT_URL!, credential: process.env.COGNICLOUD_KEY! })
const cv = await readFile("cv.pdf")

const { output } = await endpoint.invoke({
  messages: [{ role: "user", content: [textPart("Match this CV to the job."), pdfPart(cv, "cv.pdf")] }],
})
```

文件的最大容量为10mb。网关在呼叫之前以令牌形式保留文件大小的四分之一，因此端点的月限制必须覆盖它。

## 管理端点

电话作为帐户 `token`，登录者的Amadeus会话令牌或浏览器调用的浏览器密钥，作为 `Authorization: Bearer`． 抛出一个缺失、空或空白的标记 `CogniCloudError` 使用代码 `missing_token` 创建客户端时。工作空间(`tenant`、默认 `cognicloud`)作为 `tenant_id` 头。

```ts
import { CogniCloud } from "@cognicloud/sdk"

const cc = new CogniCloud({ token: amadeusToken, locale: "en" })

const { endpoint, credential } = await cc.endpoints.create({
  name: "Support bot",
  providerId: "azure-openai",
  model: "gpt-5-mini",
  tokenLimit: 1_000_000,
})

await cc.endpoints.update(endpoint.id, { tokenLimit: 2_000_000 })
await cc.endpoints.update(endpoint.id, { status: "paused" })
const usage = await cc.endpoints.usage(endpoint.id)
const days = await cc.endpoints.dailyUsage(endpoint.id, { from: "2026-10-01", to: "2026-10-20" })
const { secret } = await cc.endpoints.rotateCredential(endpoint.id)
await cc.endpoints.delete(endpoint.id)
```

也可用: `cc.endpoints.list()` 和 `cc.endpoints.get(id)`.

## 浏览器会话

浏览器调用接受登录人员的令牌或浏览器密钥。在仪表板中创建一个密钥 **浏览器→API密钥** 并将其作为令牌传递。密钥在其所有者注销后仍然有效。不能通过SDK或API创建密钥。

仅使用浏览器密钥即可使用浏览器产品。该密钥命名其工作空间，因此不需要Amadeus令牌或租户：

```ts
import { CogniCloudBrowser } from "@cognicloud/sdk"

const browser = new CogniCloudBrowser({ key: process.env.COGNICLOUD_BROWSER_KEY! })
const session = await browser.browser.sessions.create({ timeoutMinutes: 15 })
```

上传一个配置文件文件夹 `.tar.gz` （请参阅应用文档了解如何打包它），然后从它开始一个会话：

```ts
import { readFile } from "node:fs/promises"

const profile = await browser.browser.importProfile("Shop account", await readFile("shop-profile.tar.gz"))
const session = await browser.browser.sessions.create({ profileId: profile.id })
```

浏览器会话是您的代理通过Chrome DevTools协议驱动的Chrome浏览器。启动一个，将您的自动化库连接到它的 `cdpUrl`，并在完成时停止它。

```ts
import { CogniCloud } from "@cognicloud/sdk"
import { chromium } from "playwright"

const cc = new CogniCloud({ token: amadeusToken })

const session = await cc.browser.sessions.create({ timeoutMinutes: 15 })
const browser = await chromium.connectOverCDP(session.cdpUrl!)
const page = browser.contexts()[0].pages()[0] ?? (await browser.contexts()[0].newPage())
await page.goto("https://example.com")

await browser.close()
await cc.browser.sessions.stop(session.id)
```

-   `timeoutMinutes` 取值范围为1 ~ 240，默认为15。当超时时间过去时，会话将自行停止。
-   关闭CDP连接不会停止会话。呼叫 `stop` 如上所述。
-   `status` 是 `active` 或者 `stopped`. `cdpUrl` 和 `liveUrl` 是 `null` 一旦会话停止。 `liveUrl` 是一个页面，一个人可以观看和接管浏览器。
-   `sessions.list()` 返回工作区的会话，最新的优先，使用 `concurrency: { active, limit }`． 超出极限的起跑失败了 `429` 和代码 `concurrency_limit`.
-   代理国家、个人资料、屏幕尺寸、验证码解决和记录尚未提供。 `countries()` 和 `profiles()` 返回空列表，并且请求这些选项之一的start失败 `422`.

## 邮件

Flippico邮件服务器上的邮箱。 `token` 是已登录人员的令牌或邮件密钥(`cgm_...`）. 密码返回一次；储存它。

```ts
const { mailbox, password } = await cc.mail.create("support")
const settings = await cc.mail.connectionSettings() // IMAP and SMTP hosts, and defaultDomain

// Your own domain: add it, publish domain.records at your DNS provider, then verify.
const domain = await cc.mail.domains.add("yourcompany.com")
await cc.mail.domains.verify(domain.id)
await cc.mail.create("ceo", { domain: "yourcompany.com" })
```

`mail.list`， `get`， `rotatePassword` 和 `delete` 管理邮箱; `mail.domains.list`， `get` 和 `delete` 管理域。添加、验证和删除域需要登录人员的令牌。

## 数据库

托管Postgres。一个登录的人创建数据库；数据库键(`cgd_...`)从仪表板查询其中一个，不需要其他任何东西。一个 `read` 按键只能读取。一个 `write` 键作为数据库所有者运行。

```ts
import { CogniCloud, CogniCloudDatabase } from "@cognicloud/sdk"

const cc = new CogniCloud({ token: sessionToken })
const database = await cc.database.create("Orders")

const db = new CogniCloudDatabase({ key: process.env.COGNICLOUD_DATABASE_KEY! })

await db.query("CREATE TABLE orders (id serial PRIMARY KEY, email text, total numeric)")
const { rows } = await db.query("SELECT * FROM orders WHERE total > $1", [100])

await db.table("orders").insert({ email: "a@example.com", total: "19.90" })
const paid = await db.table("orders").select("id", "email").gt("total", 10).order("id", { desc: true }).limit(20)
await db.table("orders").update({ total: "0" }).eq("id", 1)
await db.table("orders").delete().eq("id", 1)

await db.transaction([
  { sql: "UPDATE accounts SET balance = balance - $1 WHERE id = $2", params: [10, 1] },
  { sql: "UPDATE accounts SET balance = balance + $1 WHERE id = $2", params: [10, 2] },
])
const tables = await db.tables()
```

-   过滤器是 `eq`， `neq`， `gt`， `gte`， `lt`， `lte`， `like`， `ilike`， `is` 和 `in`. `update` 和 `delete` 至少需要一个；要更改每一行，请使用 `query`.
-   `select`， `update` 和 `delete` 等待时运行。 `insert` 马上就跑。
-   结果是 `rows`， `columns`， `rowCount` 和 `truncated`． 一个请求在15秒后停止，并返回最多1,000行和5mb。
-   `numeric` 值, `bigint` 超过2^53的值会以字符串形式返回，所以不会四舍五入。 `bytea` 返回base64。
-   失败的语句将抛出 `CogniCloudError` 与 `code` `query_failed` 和 `queryCode`：一个Postgres SQLSTATE，例如 `23505`，或者 `query_timeout`.
-   `query` 和 `transaction`、插入、更新和删除永远不会重试，因为它们可能会更改数据。

将值传递为 `params`，而不是在SQL中。它们不需要引号，也不能中断语句：

```ts
await db.query("INSERT INTO members (id, user_id) VALUES ($1, $2)", [id, userId])
```

一个登录的人可以在自己的数据库中运行SQL而不需要key： `cc.database.query(database.id, sql, params)` 和 `cc.database.tables(database.id)`.

`cc.database.list`， `get` 和 `delete` 管理数据库, `cc.database.keys.list` 和 `revoke` 管理密钥，以及 `cc.database.actions` 列出已完成的工作。在仪表板中创建密钥。

## 错误

```ts
import { CogniCloudError } from "@cognicloud/sdk"

try {
  await endpoint.invoke({ input: "Hi" })
} catch (error) {
  if (error instanceof CogniCloudError && error.code === "credits_exhausted") {
    // top up credits
  }
  throw error
}
```

`status` 为HTTP状态(`0` 当请求没有得到答复时)； `code` 是CogniCloud的稳定错误代码。

## 配置

| 选项 | 默认的 |  |
| --- | --- | --- |
| `baseUrl` | `https://cognicloud.dev/api/v1/ai-gateway` | 指向另一个环境。 |
| `locale` | `"en"` | `Accept-Language` 对于局部反应。 |
| `timeoutMs` | `30000` | 每个请求。 |
| `maxRetries` | `2` | 为 `429` 和 `5xx`，这些电话可以安全地重复。 |
| `fetch` | `globalThis.fetch` | 提供您自己的，例如代理或测试。 |

这个 `CogniCloud` 客户端也需要 `token` （登录者的Amadeus会话令牌）， `tenant` (工作空间，作为 `tenant_id` 头;默认的 `"cognicloud"`（平台工作空间）； `browserBaseUrl` (默认 `https://cognicloud.dev/api/v1/browser`） `mailBaseUrl` (默认 `https://cognicloud.dev/api/v1/mail`), `databaseBaseUrl` (默认 `https://cognicloud.dev/api/v1/database`）。

## 变化

看到 [CHANGELOG.md](https://npmcn.com/package/%40cognicloud/sdk/CHANGELOG.md)． 代理、抓取、保险库和活动计划在以后的版本中使用。

来源: [https://github.com/Flippico/cognicloud-js-sdk](https://github.com/Flippico/cognicloud-js-sdk)

## 开发

```bash
npm install
npm test
npm run build
```

## 常见问题

### @cognicloud/sdk 是什么？

CogniCloud SDK：调用AI网关端点并管理它们。

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

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

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

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

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

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

### @cognicloud/sdk 需要什么版本的 Node\.js？

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

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

@cognicloud/sdk 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

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

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