# @cueframe/api-contract 中文文档

规范地址：https://npmcn.com/package/%40cueframe/api-contract/

版本：7\.0\.2
npm 元数据更新时间：2026-11-05T00:21:29.657Z
中文译文更新时间：2026-11-11T10:01:25.309Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cueframe/api-contract
原文对照：https://npmcn.com/package/%40cueframe/api-contract/?lang=original
项目主页：https://cueframe.ai/api
源码仓库：https://github.com/cueframe-ai/cueframe-mcp

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

- 包体积（解压后）：24.4 MB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-10-07T17:06:53.703Z
- 最新版本发布：2026-11-05T00:21:29.203Z
- 近 30 天下载量：2295（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

CueFrame视频编辑和渲染API的版本OpenAPI合同和组成方案.

## 安装

```sh
npm install @cueframe/api-contract
```

也可以使用：`pnpm add @cueframe/api-contract`、`yarn add @cueframe/api-contract`、`bun add @cueframe/api-contract`

## README

# @ cueframe/ api- 合同

已消毒,为CueFrame公开API版本的OpenAPI合同. 这是 仅支持生成的 SDK 、 CLI 和 MCP 客户端的输入, 以及唯一的副本 任何消费者均应改为:.

软件包包含公开的 OpenAPI 文档, 其审查过的操作 清单 现场拍摄 JSON Schema 及其例子 和两份清单 这个 故意排除后端来源、存储标识符、提供者 姓名和内部成本数据.

```js
import { contractVersion, openApiSha256, operationCount } from "@cueframe/api-contract";
import openApi from "@cueframe/api-contract/openapi.json" with { type: "json" };
```

## 使用合同

```bash
npm install @cueframe/api-contract
```

需要为 JavaScript 出口提供更新的节点.js 24 。 其他语言和生成器可以读取 [公开 OpenAPI JSON](https://github.com/cueframe-ai/cueframe-mcp/blob/main/api/openapi.json) 直接说 需要再生成时使用已版本 npm 软件包 .

合同中描述了托管的API: `https://api.cueframe.ai`; 安装它不会运行服务器。 开始于 [API 参考](https://docs.cueframe.ai/docs/api), (中文(简体) ), [API 走过](https://cueframe.ai/api),或 [类型脚本 SDK](https://npmcn.com/package/%40cueframe/sdk)。 。 。 .

## 一个合同链

```
private CueFrame API ──sync──▶ cueframe-ai/cueframe-mcp: api/*.json ──build──▶ @cueframe/api-contract@x.y.z ──▶ consumers
```

1.  私人API预测其公众面并写道: `api/openapi.json`, (中文(简体) ), `api/scene-schema.json`, (中文(简体) ), `api/scene-examples.json` 财务报告和审定财务报表 `api/contract-manifest.json` 从一个内核构建进入此寄存器. 清单记录了内核版本、私人承诺和sha256 每个文件的文字.
2.  `openapi.json` 携带内核本身的 OpenAPI 组件(`Composition`, (中文(简体) ), `CompositionOp`, (中文(简体) ), `SceneShotSpecV2` 及其递归部分,.)逐字记录. 这个寄存器从中再生出SDK并同时承担. `api/public-surface.json`经审查的业务清单得到维护 在这里.
3.  `pnpm --filter @cueframe/api-contract build` 复制 5 `api/*.json` 文件输入 `dist/` 他们确是犯罪,确是写作的 `manifest.json`, (中文(简体) ), `index.js` 财务报告和审定财务报表 `index.d.ts`。 。 。 .
4.  其他所有读取 npm 包: 应用程序仓库的 MCP 工具、组件操作和现场承包发电机及其测试,以及任何 第三方。 没有读 `api/` 第二次离职.

## 内容和出口

| 子路径 | 文件 | 这是什么 |
| --- | --- | --- |
| `.` | `dist/index.js`, (中文(简体) ), `dist/index.d.ts` | 实际出口: `contractVersion`, (中文(简体) ), `openApiSha256`, (中文(简体) ), `operationCount`, (中文(简体) ), `pathCount`, (中文(简体) ), `componentCount`, (中文(简体) ), `kernelVersion`, (中文(简体) ), `privateCommit`, (中文(简体) ), `syncedFiles`。 。 。 . |
| `./openapi.json` | `dist/openapi.json` | 公共OpenAPI 3.1文档,场景计划销售商. |
| `./public-surface.json` | `dist/public-surface.json` | 经审查的运行清单;当文档添加或删除清单未列出的运行时,构建失败. |
| `./scene-schema.json` | `dist/scene-schema.json` | 警犬场景拍摄 JSON Schema(`SceneShotSpecV2`),随着内核生成. |
| `./scene-examples.json` | `dist/scene-examples.json` | 工作场景拍摄实例 验证与计划. |
| `./contract-manifest.json` | `dist/contract-manifest.json` | 如私人API所写的同步表(`kernelVersion`, (中文(简体) ), `privateCommit`外加 `contractVersion`。 。 。 . |
| `./manifest.json` | `dist/manifest.json` | 建筑物的明细: `contractVersion`,运输的sha256 `openapi.json`,操作/路径/组件数,同步字段数. |
| `./package.json` | `package.json` | 一揽子清单;解决它`require.resolve("@cueframe/api-contract/package.json")`)定位已安装的软件包并读取其版本. |

`contractVersion` 是软件包版本。 两个安装了同样的报告 `contractVersion` 带有相同的字节; 并列记录的消费者 `privateCommit` 在其生成物(应用程序)的标题中 一旦他们读取了这个软件包而不是一个 local copy)可以从再生树上分辨出被撞出接针.

## 版本政策

-   **版本随合同而移动.** 任何字节更改为五字节之一 已运出 `api/*.json` 文件是这个软件包的新版本, 因为每个 消费者从npm读取合同,npm版本不可改变. `pnpm check:contract-version` (单位:千美元) `pnpm check` 和CI) 犯规, 拉请求或工作树 `api/*.json` 根据基准变化 财务报告和审定财务报表 `packages/api-contract/package.json` 没有 : `main` 基线为: 前一次犯罪(`HEAD`(a) 当变化尚未承诺时) 分支是合并基数 `origin/main`CI通过牵引请求 基础或推力 `before` 承诺.
-   **由消费者的影响决定.** 补丁:描述、实例、清单、, 添加剂不可破解计划细节. 次要:新操作,新可选 字段,新的 schema 组件。 主要: 已删除的操作或字段或 重新命名, 缩小类型, 添加必要的字段, 或场景方案更改 无相相相相. 审评的清单`public-surface.json`这是 核对表:添加或删除的操作至少有未成年人.
-   **内容不变的再同步不移动版本.** `contract-manifest.json` 携带 `privateCommit`,但私人同步 比较三个内容文件,他们的散列, `kernelVersion` 财务报告和审定财务报表 `contractVersion` 攻击目标,当他们不写 相等, 因此同步运行于内容相同的新私人任务 将《古兰经》抛出 `privateCommit`)未发. 只有合同 更改会移动版本;当它移动时,同步会以 新的印章和上述规则适用.
-   **私人同步可能会给版本盖章.** 何时 `api/contract-manifest.json` 携带 `contractVersion`,它命名软件包 版本同步被对质; 检查和构建都失败 与 `package.json`,因此一个已失效的同步无法发布 .
-   更改记录在仓库中 `CHANGELOG.md` 下级 `@cueframe/api-contract <version>`。 。 。 .

## 许可证

阿帕奇2.0 (英语). 该文件是托管的API已经为每个呼叫者服务的内容.

## 常见问题

### @cueframe/api-contract 是什么？

CueFrame视频编辑和渲染API的版本OpenAPI合同和组成方案\.

### 如何安装 @cueframe/api-contract？

在项目目录运行 npm install @cueframe/api-contract，或使用 pnpm add / yarn add / bun add。

### @cueframe/api-contract 支持 TypeScript 吗？

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

### @cueframe/api-contract 支持 ESM 还是 CommonJS？

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

### @cueframe/api-contract 需要什么版本的 Node\.js？

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

### @cueframe/api-contract 可以商用吗？

@cueframe/api-contract 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cueframe/api-contract 的下载量有多少？

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

### @cueframe/api-contract 还在维护吗？

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