# @particle-academy/prism 中文文档

规范地址：https://npmcn.com/package/%40particle-academy/prism/

版本：0\.7\.0
npm 元数据更新时间：2026-11-02T03:01:29.537Z
中文译文更新时间：2026-11-02T03:54:28.115Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：860 kB，471 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-09-06T05:07:09.166Z
- 最新版本发布：2026-11-02T03:01:29.059Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Prism的TypeScript端口——LLM提供商之上的统一API层。

## 安装

```sh
npm install @particle-academy/prism
```

也可以使用：`pnpm add @particle-academy/prism`、`yarn add @particle-academy/prism`、`bun add @particle-academy/prism`

## README

# @particle-academy /棱镜

的TypeScript端口 [棱镜](https://github.com/Particle-Academy/prism), PHP/Laravel统一API层的LLM提供商。

真正的TypeScript：承诺、有区别的联合、严格的null检查。是什么 是 _不_ 是音译-习语是这种语言的。的语料库 记录提供者行为的一致和不同之处。

> **在做这个包吗？** 读 **[`AGENTS.md`](https://npmcn.com/package/%40particle-academy/prism/AGENTS.md)** 第一，边界 这个包裹必须牢固，门必须是绿色的，陷阱必须是绿色的 已经抓到人了。 `@link AGENTS.md`

## 范围

存储的助手消息保留提供程序重播状态 `additionalContent`： OpenAI响应使用 `output_items`;人为用途已定 `content_blocks`， 与 `thinking_blocks` 作为退路。在发送历史记录时保留该元数据 回来。签名，编辑的思想和加密的推理仍然是不透明的 不变;避免记录这些值。遗留思想/签名对仍然 当没有完整的重放元数据时工作。

在0.5.0之前，Anthropic EOF `message_stop` 发出不可恢复的 `incomplete_stream` 和终端错误事件。提供程序错误关闭未完成 文本，仍然以Error结束；以后的停止/使用事件不能擦除错误。 终端使用量保持为空，除非到达最终使用量增量。消费者应该 处理这些新的可观察终端事件。本地事件词汇和 有效载荷差异分别在 [流比较合同](https://github.com/Particle-Academy/prism-parity/blob/main/docs/streaming-conformance.md).

**引用的每个功能**以及18家供应商中的3家。 这就是剩余漂移的形状：一个轴，而不是两个轴。

-   **所有的能力。** `text`， `structured`， `stream`， `embeddings`， `images`， `moderation`， `audio` （`textToSpeech` 和 `speechToText`)， `files`， `batch`， `fim`． 用户消息携带图像、文档和每个提供者 用自己的方式拼写它们。
-   **供应商- - - - - - `anthropic`， `mistral`， `openai`.** OpenAI供应商发言 这个 **反应API**;Mistral带来了聊天完成形状，这是一个 不同的连线格式，而不是它的变体。

未包括在内的： **工具执行循环** -一个回应 完成的工具呼叫被拒绝 `tool_loop_not_supported` 而不是 执行了一半——引用有15个提供者，这个端口也有 不是。要一个失败了 `unsupported_provider_action` 代码,而 而不是返回一些可信的东西。

不是每个功能都能达到每个提供者，因为不是每个提供者都有。 `images`， `moderation`， `textToSpeech`， `files` 和 `batch` 是OpenAI-only 在这里, `fim` 米斯特拉尔是唯一的，因为米斯特拉尔是唯一的供应商 在引用中也实现了它。查看信封的端口间隙 记录下哪些是某人可以做的工作哪些是事实 提供者。

每个值对象都序列化 **和重建** - - - - - - `toObject()` 静态的 `fromObject()`． PHP包只有前半部分，留给每个消费者 发明第二种；其中一项发明有缺陷，会损坏 存储助手信息。两半都在这里，重建方向是 用固定装置固定。

失败带来稳定 `code` （`PrismError.code`）. 散文不属于 合同和将改变；代码不会。

结构化反应保留 `structured`， `steps`， `raw`、工具架 序列化时的数组 `toObject()`． 每一个出口 `StructuredStep` 也 保留其已完成的 `messages` 和每一步解析的值。保存, 继续对话时的对话状态。Anthropic使用原生模式 默认输出： `text` 是空的，而原始JSON仍然在 助理的信息。显式结构化工具模式目前被拒绝 `unsupported_provider_action` 在HTTP;它不运行工具。

## 安装

```sh
npm install @particle-academy/prism
```

Node 22或更新版本。

## 使用

```ts
import { Prism } from '@particle-academy/prism';

const response = await Prism.text()
  .using('openai', 'gpt-4o')
  .withSystemPrompt('You are terse.')
  .withPrompt('Who are you?')
  .asText();

console.log(response.text);
console.log(response.usage.promptTokens, response.usage.completionTokens);
```

首先是显式配置，其次是环境 `OPENAI_API_KEY`， `OPENAI_URL`， `OPENAI_ORGANIZATION`， `OPENAI_PROJECT`：

```ts
Prism.text().using('openai', 'gpt-4o', { apiKey: 'sk-…', transport });
```

`transport` 是提供者和网络之间的接缝。第一次和第二次 Test从未接触过套接字：

```ts
import type { HttpTransport } from '@particle-academy/prism';

const transport: HttpTransport = async (request) => ({
  status: 200,
  headers: {},
  body: recordedPayload,
  rawBody: JSON.stringify(recordedPayload),
});
```

构建一个请求而不发送它，或者在没有HTTP的情况下解析存储的有效负载：

```ts
import { buildRequestBody, canonicalJson, parseTextResponse } from '@particle-academy/prism';

const request = Prism.text().using('openai', 'gpt-4o').withPrompt('hi').toRequest();

canonicalJson(buildRequestBody(request)); // exactly the bytes that would be POSTed
parseTextResponse(request, recordedPayload); // the same parse a live call performs
```

## 奇偶校验

该端口的行为不是由它自己的测试定义的。它被钉住了 [**prism-parity**](https://github.com/Particle-Academy/prism-parity) ——一个 通过执行PHP生成的与语言无关的一致性语料库 引用，它一次声明规则，因此三个实现不能同时执行 漂移到他们自己的阅读。

语料库及其加载程序安装为 `@particle-academy/prism-conformance`。这个 跑步者住在 [`conformance/runner.mjs`](https://npmcn.com/package/%40particle-academy/prism/conformance/runner.mjs) 并实现了 Prism-parity的子进程契约，所以 `scripts/cross-check.mjs` 可以运行这个 港口与其他港口并排并要求 **相同的判决** -更强 声称超过三间套房都是绿色的。

```sh
git clone https://github.com/Particle-Academy/prism-parity .parity
npm install ./.parity/loaders/ts
npm run conformance                       # every suite
node conformance/runner.mjs --suite openai-text-request
node conformance/runner.mjs --probe omit-null-keys
```

有两行故意偏离引用，语料库说which和 原因: `trq-0021` 和 `trq-0022`的提示符 `""` 或者 `"0"` 这个端口发送它。阅读语料库的其余部分-重申其规则 这里只会给他们一个漂流的地方。

### 探针

`--probe` 运行端口时故意注入一个缺陷，从语料库中 `probes/probes.json`． 每个探测声明一组它必须失败的case id， 和 [`tests/probes.test.ts`](https://npmcn.com/package/%40particle-academy/prism/tests/probes.test.ts) 断言观察集 _\=_ 并不是说它是非空的。一个表列出了每个可行的实现 通行证不算什么。

变种人住在 [`conformance/mutations.mjs`](https://npmcn.com/package/%40particle-academy/prism/conformance/mutations.mjs)， 外 `src/`你可以在生产中打开的缺陷就是缺陷。

## 开发

```sh
npm run build       # tsc → dist/
npm run typecheck
npm run lint
npm test
npm run conformance
```

## 许可证

麻省理工学院。看到 [许可证](https://npmcn.com/package/%40particle-academy/prism/LICENSE).

## 常见问题

### @particle-academy/prism 是什么？

Prism的TypeScript端口——LLM提供商之上的统一API层。

### 如何安装 @particle-academy/prism？

在项目目录运行 npm install @particle-academy/prism，或使用 pnpm add / yarn add / bun add。

### @particle-academy/prism 支持 TypeScript 吗？

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

### @particle-academy/prism 支持 ESM 还是 CommonJS？

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

### @particle-academy/prism 需要什么版本的 Node\.js？

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

### @particle-academy/prism 可以商用吗？

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

### @particle-academy/prism 还在维护吗？

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