# @calmlens/sdk 中文文档

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

版本：0\.22\.0
npm 元数据更新时间：2026-11-08T21:29:12.421Z
中文译文更新时间：2026-11-09T00:15:43.176Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40calmlens/sdk
原文对照：https://npmcn.com/package/%40calmlens/sdk/?lang=original
项目主页：https://calmlens.com/docs/sdk/javascript
源码仓库：https://github.com/CalmLens/sdks

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

- 包体积（解压后）：8.6 MB，111 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- peer 依赖：vue \>=3\.3，react \>=19，svelte \>=5，react-native \>=0\.79
- 首次发布：2026-10-10T10:03:48.613Z
- 最新版本发布：2026-11-08T21:29:12.088Z
- 近 30 天下载量：2939（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

JavaScript和TypeScript的官方 CalmLens SDK:内容节制,资产存储和CDN交付.

## 安装

```sh
npm install @calmlens/sdk
```

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

## README

# CalmLens Java 脚本 SDK

JavaScript 和 TypeScript SDK 的官方版本 [冷静](https://calmlens.com/):内容中和文本、图像、文件和网站的分类,加上可选存储和CDN发送.

## 安装

```bash
npm install calmlens
```

同一软件包也作为 `@calmlens/sdk`,在同一版本中。 从您安装的名称导入 : `calmlens/server` 与 `calmlens`,或 `@calmlens/sdk/server` 与 `@calmlens/sdk`。 。 。 .

该软件包有2个客户端,每个客户端都有自己的导入功能:

| 导入 | 客户端 | 运行 | 认证 |
| --- | --- | --- | --- |
| `calmlens/server` | `CalmLensServerClient` | 在您的服务器上: Node.js 22 或以后, Bun, Deno, Cloudflare 工人 | 项目 API 密钥 |
| `calmlens/app` | `CalmLensAppClient` | 在浏览器和回放原生应用程序中 | 上传预设, 可选从服务器上传令牌 |

API 密钥,所以 `CalmLensServerClient` 拒绝在网页或应用程序中开始 。 从浏览器和应用程序上传 `CalmLensAppClient`,并用签名的URL向他们提供私人内容。 包装了ES模块和带有类型声明的CommonJS. 主语, `/server` 财务报告和审定财务报表 `/app` 切入点运行时没有装入其他包. 软件包取决于 `zod`,其类型声明和测试助手使用,以及 `pdfjs-dist` 财务报告和审定财务报表 `hls.js`,而 UI 查看者只在显示文档或流时才会加载.

版本遵循语义版本:参见 [版本和支持](https://calmlens.com/docs/sdk#versioning-and-support)。 。 。 .

## 快开始

在下面创建 API 密钥 **开发者 — API 密钥** 在CalmLens门户。 同一页显示你 **项目标识**保留在服务器上 .

```typescript
import { CalmLensServerClient } from "calmlens/server";

const client = new CalmLensServerClient({
  apiKey: process.env.CALMLENS_API_KEY!,
  projectId: process.env.CALMLENS_PROJECT_ID!,
});

// Text (comments, captions, bios): waits for the decision
const comment = await client.text.classify({ text: "Great photo!", externalId: "comment-42" });

const { status } = comment.classification.moderation;
if (status === "allowed" || status === "limited") {
  // publish it; keep "limited" out of recommendations, trending and notifications
} else {
  // "age-restricted": show it only behind your own age check; "blocked" or "purged": don't publish it
}

// Images and documents: queued, resolved by webhook or assets.retrieve()
const image = await client.assets.create({
  name: "photo.jpg",
  content: { data: file, type: "image/jpeg" },
  externalId: "post-7",
});
console.log(image.classification.status, image.classification.moderation.status); // "processing" "pending"
```

| `classification.status` | `classification.moderation.status` | 含义 |
| --- | --- | --- |
| `completed` | `allowed` | 安全显示. |
| `completed` | `limited` | 送来了一样 `allowed`; 缩小其范围,如不建议. |
| `completed` | `age-restricted` | 仅交付 `viewerClaims.ageConfirmed=true`。仅向年龄检查的观众展示. |
| `completed` | `blocked` | 你的政策阻止了它;CDN不提供. 别显. |
| `completed` | `purged` | 你的政策阻止了它 并删除了它的内容。 别显. |
| `queued` 或者说 `processing` | `pending` | 仍在接收或保密. |
| `failed` | `pending` | 处理失败; 参见 `assets.retry`。 。 。 . |

最新应用审查 `classification.moderation.manualReviews` 优先于自动决定。 处理一个你不承认的状态 见 [如何冷静Lens的工作](https://calmlens.com/docs/how-it-works)。 。 。 .

## 尽你所能

-   [中度文本](https://calmlens.com/docs/sdk/javascript#text-moderation),包括: [谈话中的答复](https://calmlens.com/docs/guides/threaded-moderation),以及 [对图像、文件、音频、视频和网站进行分类](https://calmlens.com/docs/guides/classifying-assets)。 。 。 .
-   [读取分类结果](https://calmlens.com/docs/guides/classification-results) 按类别和修饰语 [要求提供完整的政策证据](https://calmlens.com/docs/guides/classification-results#complete-policy-evidence) 背后的决定.
-   发送 [多段上传](https://calmlens.com/docs/sdk/javascript/reference#multipart-uploads) 对于大文件, 从任意 [内容有效载荷](https://calmlens.com/docs/sdk/javascript/reference#content-payloads),与 [安全重试和一能键](https://calmlens.com/docs/sdk/javascript/reference#retries-and-idempotency)。 。 。 .
-   [从浏览器和应用程序上传](https://calmlens.com/docs/sdk/javascript/reference#app-client) 结束 [上传预设](https://calmlens.com/docs/guides/upload-presets) 并在当地签名 [上传符号](https://calmlens.com/docs/sdk/javascript/reference#upload-tokens)。 。 。 .
-   掉进去 [上传部件和媒体组件](https://calmlens.com/docs/widgets) 用于反应、反应原生、Vue、Svelte或自定义元素.
-   [从CDN交付资产](https://calmlens.com/docs/guides/delivering-assets) 与 [镜头和变相](https://calmlens.com/docs/guides/lenses), (中文(简体) ), [已签名的 URL](https://calmlens.com/docs/guides/delivering-assets#signed-urls) 财务报告和审定财务报表 [观众索赔](https://calmlens.com/docs/api/cdn#viewer-claims)。 。 。 .
-   记录 [审查者的决定](https://calmlens.com/docs/guides/human-review), (中文(简体) ), [重试失败的处理](https://calmlens.com/docs/guides/asset-lifecycle#recover-from-processing-failure),以及 [在文件夹中组织资产](https://calmlens.com/docs/sdk/javascript/reference#folders)。 。 。 .
-   [校验和解析webhooks](https://calmlens.com/docs/sdk/javascript#webhooks),或调查 [事件种子](https://calmlens.com/docs/sdk/javascript/reference#events-feed)。 。 。 .
-   [处理错误](https://calmlens.com/docs/sdk/javascript/reference#errors) 根据稳定代码,并设置 [暂停和请求预算](https://calmlens.com/docs/sdk/javascript/reference#request-budgets)。 。 。 .
-   [在代码中管理配置](https://calmlens.com/docs/guides/configuration-as-code)数字 : `uploadPresets.ensure`, (中文(简体) ), `projectSettings.get`编号 :`update` 财务报告和审定财务报表 `metadataFields.ensure`,每个修改所保护的,或宣布项目在 `calmlens.config.json` 运行 `calmlens plan` 财务报告和审定财务报表 `calmlens apply` 在中央情报局.
-   将事件转发给带捆绑的本地处理者 [`calmlens` 国 际](https://calmlens.com/docs/guides/local-development)数字 : `npx calmlens listen --forward-to http://localhost:3000/api/webhooks/calmlens`。 。 。 .

每个公共SDK操作都接受一个选项对象,因此随着可选字段被添加,呼叫站点保持稳定. 这个 [SDK 参考](https://calmlens.com/docs/sdk/javascript/reference) 列出每个选项和方法.

## 测试

`calmlens/testing` 在模拟 CalmLens API 和 CDN 中运行真实的客户端, 并取得适度的结果, 记录请求, 注入失败并签名 Webhook 交付 。 见 [Java 脚本测试](https://calmlens.com/docs/sdk/javascript/testing)。 。 。 .

`calmlens/test-inputs` 制作签名的测试代码和图像,这些代码和图像是按您选择的情景为温和派签名的。 一个代码只算整个文本,一个图像只算整个上传. 见 [生成测试输入](https://calmlens.com/docs/sdk/javascript/testing#generate-test-inputs)。 。 。 .

## 链接

-   [文档](https://calmlens.com/docs/sdk/javascript)
-   [SDK 参考](https://calmlens.com/docs/sdk/javascript/reference)
-   [HTTP API 参考文献](https://calmlens.com/docs/api)
-   [更改日志](https://github.com/CalmLens/sdks/blob/main/javascript/CHANGELOG.md)
-   [许可证](https://github.com/CalmLens/sdks/blob/main/javascript/LICENSE)

## 常见问题

### @calmlens/sdk 是什么？

JavaScript和TypeScript的官方 CalmLens SDK:内容节制,资产存储和CDN交付\.

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

在项目目录运行 npm install @calmlens/sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 calmlens，可以用 npx calmlens 直接运行。

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

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

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

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

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

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

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

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

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

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

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

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