# @formio/uag-sdk 中文文档

规范地址：https://npmcn.com/package/%40formio/uag-sdk/

版本：2\.0\.0
npm 元数据更新时间：2026-11-13T11:26:19.086Z
中文译文更新时间：2026-11-15T10:20:29.119Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：98.5 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- 首次发布：2026-10-29T17:11:51.641Z
- 最新版本发布：2026-11-13T11:26:18.663Z
- 近 30 天下载量：2884（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

为 Form.io Universal Agent Gateway(UAG)构建引擎包:引擎合同,定义Engine,设置和实例解析,引擎加载器,以及符合性检查.

## 安装

```sh
npm install @formio/uag-sdk
```

也可以使用：`pnpm add @formio/uag-sdk`、`yarn add @formio/uag-sdk`、`bun add @formio/uag-sdk`

## README

# @formio/uag-sdk (英语)

[表格.io UAG](https://ai.form.io/developers) › [发动机](https://ai.form.io/developers/engines) › 此页

为 Form.io Universal Agent Gateway (UAG) 构建引擎包. 此套件包含:

-   发动机合同的类型,以及 `ENGINE_API_VERSION`· ;
-   `defineEngine`,以声明引擎类型及其设置;
-   `EngineError`,用于向API呼叫者显示安全的信息;
-   装货机,即UAG, `uag-eval` 和引擎服务器用于查找、配置和创建引擎;
-   共享具有结构化产出的模型API的助手;
-   任何试跑者都要检查是否合格.

一个引擎包只依赖于这个包. 它从不需要 `@formio/uag`。 。 。 .

```bash
npm install @formio/uag-sdk
```

SDK需要节点.js 22或更后,没有依赖性. 完全参考了两个完整的引擎及其测试 [引擎 SDK](https://ai.form.io/developers/engine-sdk)。 。 。 .

## 一个引擎包

命名软件包 `@formio/uag-<type>` (官方发动机)或 `uag-engine-<type>` (谁的). 导出一个引擎类型定义 。 它是类型插件 `"engine"`数字 : `name` 是所使用的类型名称 `UAG_ENGINES`, (中文(简体) ), `title` (默认 : `name`向人们展示, `description` 是运算符的可选摘要,并且 `version` 默认您的软件包的版本 :

```js
const { defineEngine, EngineError, ENGINE_API_VERSION, requiredSchema } = require('@formio/uag-sdk');

module.exports = defineEngine({
    type: 'engine',
    name: 'acme',
    title: 'Acme',
    kinds: ['agent'],
    apiVersion: ENGINE_API_VERSION,
    description: 'Acme models: structured extraction.',
    settings: {
        apiKey: { env: 'ACME_API_KEY', required: true, secret: true },
        model: { env: 'ACME_MODEL', default: 'acme-large-2026-09-01' },
        maxTokens: { env: 'ACME_MAX_TOKENS', type: 'number', default: 4000 },
    },
    create({ name, settings, options }) {
        const client = options.client || new AcmeClient({ apiKey: settings.apiKey });
        return {
            name,
            kind: 'agent',
            apiVersion: ENGINE_API_VERSION,
            model: settings.model,
            async extract(request) {
                request.signal?.throwIfAborted();
                const { schema, decode } = requiredSchema(request.schema);
                const answer = await client.complete({ schema, signal: request.signal /* ... */ });
                if (answer.quotaExceeded) throw new EngineError('Quota exceeded for this API key.');
                return { model: answer.model, values: decode(answer.json) };
            },
        };
    },
});
```

引擎必须使用实例 `name` 它被授予, 和其中之一 `kinds` 它声明。 一个决策引擎 `decide` 财务报告和审定财务报表 `maxOptions`; 代理引擎已经 `extract`设置 `toolUse: true` 何时 `extract` 接受只读研究工具。 见 `contract.d.ts` 每一份请求和答复.

以2.0发布候选人的外形定义,引擎名称包含在内 `type` (单位:千美元)`{ type: 'acme', kinds, ... }`),以显示上方形状的信息拒绝.

### 在文档上生成文本

代理引擎也可以执行 `generate(request)`,哪个文档插件会调用在上传文档上写入免费文本,并声明 `accepts`,文档的本地读取类型(默认) `['text']`; 列表 `'pdf'` 只有当您的模型将 PDF 读取为文档时 :

```js
accepts: ['text', 'pdf'],
async generate({ instructions, system, attachments, format, maxTokens, signal, onProgress }) {
    // attachments: { kind: 'pdf', data: Buffer, label, pages? } or { kind: 'text', text, label, textFormat? }
    // Put the documents before the instructions; report progress as the answer streams.
    return { text, model, stopReason: 'end' /* or 'max_tokens' when cut off */, usage };
},
```

`generate` 必须尊重 `signal`中,从不记录文档,并报告一个简短的答案为 `stopReason: 'max_tokens'` 而不是失败.

`create` 接收 `{ name, settings, options, config, requireSetting }`数字 :

-   `settings`: 实例对每个已声明设置的值为 1.
-   `options`:实例的选项如配置中给出的,包括非设置的选项。 在此接受测试双倍( E)`options.client`,如上例),所以测试,以及下面的符合性检查,从不叫真正的API.
-   `config`: 主机的配置, 例如只读 `routing.timeouts[name]`。 。 。 .
-   `requireSetting(key)`:一个设置的值,或标准"需要它的设置"出错,对于一个只是有时需要的设置.

`create` 可能会是同步的.

## 设置

每个设置从其中第一个设置中解析:

1.  实例的配置选项;
2.  `UAG_ENGINE_<NAME>_<SETTING>`,从实例名称和设置名称(`fast` 财务报告和审定财务报表 `apiKey` 给 `UAG_ENGINE_FAST_API_KEY`(三);
3.  设置列表中的变量 `env`,顺序;
4.  联合国 `default`。 。 。 .

| 密钥 | 含义 |
| --- | --- |
| `env` | 该类型本身的变量,作为名称或列表. |
| `required` | 没有值的启动失败 。 错误命名实例、类型、设置和设置的每个变量. |
| `secret` | 该值不被启动错误和能力发现所忽略. 引擎运行时所抛出的错误按原样记录, 因此从不将设置值放入其中 . |
| `type` | `string` (默认), `number` 或者说 `boolean`. 环境值被转换. |
| `default` | 当没有其他设置时使用. |
| `description` | 运算符文档. |

## 实例

主机启用引擎为一类命名实例 :

```
UAG_ENGINES=jev,fast:claude,deep:claude,x:@acme/uag-engine-x
```

-   裸入( A)`jev`)在实例类型后命名.
-   `<name>:<type>` 自己命名它,所以一个类型可以作为多个不同设置的例运行.
-   开始的类型 `@` 或者说 `uag-engine-`,或包含 `/`,是一个软件包名称。 空包项取出包的类型名.
-   名称使用小写字母、数字和 `-`,从字母开始,最多为63个字符。 在装入任何物品之前,任何其它东西,包括任何路径,都会被拒绝.

在配置中,条目是这样的字符串,或者 `{ name, type, options }`时 `type` 也可能是一个引擎类型定义.

## 正在装入

```js
const { engineInstances } = require('@formio/uag-sdk');
const { enginePaths, loadEngines } = require('@formio/uag-sdk/loader');

const engines = await loadEngines(engineInstances(config, process.env), {
    types: { remote: RemoteEngine },        // built-in and embedded types, tried first
    paths: enginePaths(__dirname, process.env),
    env: process.env,
    config,
});
```

查找类型名称 `types`,然后作为 `@formio/uag-<type>`,然后作为 `uag-engine-<type>`。软件包在 `node_modules` ,然后在 `<dir>/node_modules` 每个绝对目录中 `UAG_ENGINE_PATH`。在工作目录中从来没有, `NODE_PATH` 或节点的全局文件夹,以及一个其入口在自己的目录外解决的软件包被拒绝. 无所安设. 装入引擎包 `require()`: commonJS,或指节点22.12上或后期的ES模块. 每个结果都是 `{ engine, type, title, kinds, typeVersion, package, version }` (单位:千美元)`typeVersion` 当定义设定时 `version`· ; `package` 财务报告和审定财务报表 `version` 当类型来自一个软件包时),这就是什么 `Formflow.engineRegistry` 拿着.

`planEngines(instances, options)` 使用相同的参数并进行相同的解析和检查,但不会产生任何结果:对于每个实例,它返回结果的字段,而不返回 `engine`附加时 `name`, (中文(简体) ), `definition`, (中文(简体) ), `args` (如何将定义传递给 `create`和 `failure(err)`,该词与加载器一样不能开始,而忽略了秘密值。 它是一个主机 创建引擎本身. `createEngine(definition, { name, options, env, config })` 解析设置并创建一个实例,就像 UAG 所做的那样.

每个定义都被从结构上检查过,所以一个用这个SDK的另一个拷贝所建的包,或者没有,负载也一样. 为另一个引擎合同版本所构建的软件包被拒绝,而错误名称为两个版本.

## 错误

掷出 `EngineError` 对于被调用者可能看到的消息的失败,例如"这个API密钥超过了配额". 向API调用者报告的任何其他出错仅作为"引擎失败(请参见X请求日志)"(在引擎服务器上,"引擎失败(请参见引擎服务器日志)"),因为供应商SDK出错可以携带URL和账户细节.

## 帮助者

-   `requiredSchema(schema)`:每个字段的提取计划,用于严格的结构化产出,以及 `decode(answer)` 将答案映射回来。 空值表示"未声明"而被忽略. 数字和是/否字段作为字符串出行,保留字段的标题和描述;数字作为数量(`$4,250`)解码为4250,其他非数字的则被忽略. 一个被键入的enum保留其值,而其外的答案被丢弃.
-   `parseJsonObject(text)`:文本答案中的第一个 JSON 对象,或 `EngineError`。 。 。 .
-   `toolResultText(result)`:一个工具调用的结果作为模型的文本.

## 遵约

```js
const { checkEngine } = require('@formio/uag-sdk/conformance');

it('meets the engine contract', async () => {
    const report = await checkEngine(require('..'), { options: { client: fakeClient } });
    assert.deepStrictEqual(report.failures, []);
});
```

支票创造了一个实例并称它。 传递选项,如假客户端,或让其回答的环境变量. 它检查:

-   定义和引擎具有合同形状;
-   引擎使用实例名称和 `model` 选项;
-   `extract` 只返回所询问的字段,或 `decide` 只问过它的问题;
-   `accepts`,设定时仅列出列表 `text` 财务报告和审定财务报表 `pdf`· ; `generate`,当存在时,返回文本、其模式和有效 `stopReason`· ;
-   研究停止时间 `maxIterations`,并报告每一个工具称之为它制作的;
-   中止的信号停止引擎,包括在研究期间 `generate`。 。 。 .

一个研究回合是模型一起发出的呼叫;一个接一个地发出的呼叫作为单独的回合计算.

驾照:麻省理工.

## 常见问题

### @formio/uag-sdk 是什么？

为 Form\.io Universal Agent Gateway\(UAG\)构建引擎包:引擎合同,定义Engine,设置和实例解析,引擎加载器,以及符合性检查\.

### 如何安装 @formio/uag-sdk？

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

### @formio/uag-sdk 支持 TypeScript 吗？

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

### @formio/uag-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

### @formio/uag-sdk 可以商用吗？

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

### @formio/uag-sdk 的下载量有多少？

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

### @formio/uag-sdk 还在维护吗？

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