# @genkit-ai/a2ui 中文文档

规范地址：https://npmcn.com/package/%40genkit-ai/a2ui/

版本：0\.7\.0
npm 元数据更新时间：2026-11-03T20:54:53.794Z
中文译文更新时间：2026-11-16T03:48:06.103Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：350 kB，51 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：genkit ^1\.44\.0
- 首次发布：2026-08-28T01:33:29.083Z
- 最新版本发布：2026-11-03T20:54:53.630Z
- 近 30 天下载量：4593（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

一个Genkit插件,通过模型中间软件提供A2UI(Agent-to-UI)流式UI协议支持.

## 安装

```sh
npm install @genkit-ai/a2ui
```

也可以使用：`pnpm add @genkit-ai/a2ui`、`yarn add @genkit-ai/a2ui`、`bun add @genkit-ai/a2ui`

## README

# @genkit-ai/a2ui (英语)

带来 Genkit 插件 [A2UI (英语)](https://a2ui.org/) ("UI代理"), a 运输-不可知,以JSON为主的流式UI协议,去源基特代理.

> **用编码代理? 先安装基因组JS技能.**
> 
> ```bash
> npx skills add genkit-ai/skills --skill developing-genkit-js
> ```
> 
> 它教你的代理人 现任Genkit JS APIs 和普通的gitchas. 其他语言的来源、人工安装和技能: [技能/技能](https://github.com/genkit-ai/skills)。 。 。 .

由A2UI驱动的代理可以流出比流派更多. 它流出丰富,互动的UI **表面** 客户端渐进制作的(卡片、列表、表格、按钮) 正如模型的反应。 整个服务器端集成是一个单一的模型 中间软件: 添加 `a2ui()` 给经纪人的 `use` 数组,没有其它变化.

> 状态:实验性.

## 安装

在您的工程中安装插件 :

```bash
npm i @genkit-ai/a2ui
```

要在浏览器中渲染表面, 您还需要一个渲染器及其 支持软件包。 A2UI 多个框架的船舶渲染器: [`@a2ui/lit`](https://www.npmjs.com/package/@a2ui/lit), (中文(简体) ), [`@a2ui/react`](https://www.npmjs.com/package/@a2ui/react),以及 [`@a2ui/angular`](https://www.npmjs.com/package/@a2ui/angular)。实例 下面使用 Lit 渲染器:

```bash
npm i @a2ui/lit @a2ui/web_core @a2ui/markdown-it
```

您也会装入 **材料符号已大纲** 在客户端上的字体( 基本目录 `Icon` 组件使名称成为字体连接。 见 [渲染器注释](https://npmcn.com/package/%40genkit-ai/a2ui/#readme-renderer-requirements) 见下文.

## 快速启动

### 1\. 在服务器上添加中间软件

添加 `a2ui()` 给你的经纪人 `use` 阵列。 这是整个服务器侧设置.

```ts
import { genkit } from 'genkit/beta';
import { googleAI } from '@genkit-ai/google-genai';
import { a2ui } from '@genkit-ai/a2ui';

const ai = genkit({ plugins: [googleAI()] });

export const uiAgent = ai.defineAgent({
  name: 'uiAgent',
  model: 'googleai/gemini-flash-latest',
  system: 'You help users. Render UI when it is clearer than prose.',
  use: [a2ui()], // <- A2UI support (defaults to the bundled 'basic' catalog)
});
```

一发也一样 `generate`数字 :

```ts
const res = await ai.generate({
  prompt: 'Show me the weather in Tokyo',
  use: [a2ui()],
});
```

### 2\. 客户端表面

`@genkit-ai/a2ui/client` 是浏览器安全( 没有节点依赖)。 假设 代理为 `remoteAgent` 从 `genkit/beta/client`,将 A2UI 信封各取出 块与 `a2uiEnvelopesFromParts`并供给造物主。 实例 以下用途 [`@a2ui/lit`](https://www.npmjs.com/package/@a2ui/lit)但还是一样 方法与 [`@a2ui/react`](https://www.npmjs.com/package/@a2ui/react) 财务报告和审定财务报表 [`@a2ui/angular`](https://www.npmjs.com/package/@a2ui/angular) 渲染器:

```ts
import { MessageProcessor } from '@a2ui/web_core/v0_9';
import { basicCatalog } from '@a2ui/lit/v0_9';
import '@a2ui/lit/v0_9'; // registers <a2ui-surface> + basic components
import { a2uiEnvelopesFromParts } from '@genkit-ai/a2ui/client';
import { remoteAgent } from 'genkit/beta/client';

const processor = new MessageProcessor([basicCatalog]);
processor.onSurfaceCreated((s) => {
  document.querySelector('a2ui-surface').surface = s;
});

const chat = remoteAgent({ url: '/api/uiAgent' }).chat();
const turn = chat.sendStream('weather in Tokyo');
for await (const chunk of turn.stream) {
  if (chunk.text) appendProse(chunk.text);
  const envelopes = a2uiEnvelopesFromParts(chunk.raw.modelChunk?.content);
  if (envelopes.length) processor.processMessages(envelopes);
}
```

如果你没有使用完整的代理客户端, `@genkit-ai/a2ui/client` 船舶a 轻型 `streamA2uiAgent({ url, message, sessionId })` 同步生成器帮助器 产量 `{ type: 'text' }` 财务报告和审定财务报表 `{ type: 'envelopes' }` 事件.

> 见 [`js/testapps/a2ui`](https://npmcn.com/package/testapps/a2ui) 用于完整、可运行的样本 (Express后端外加一维特+Lit前端).

## 选项

将选项传递到 `a2ui()` 控制目录,即时注射,以及 验证 :

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `catalog` | `'basic'` | 描述代理商可能制作的目录的ID. |
| `instructions` | `'system'` | 何处注入目录能力. `'none'` 注射什么也没有. |
| `validate` | `'warn'` | 对照目录验证所发射的信封 . `'warn'` 日志和投放坏块; `'strict'` 投掷; `'off'` 跳过检查. |
| `surfaceId` | 新鲜UUID | 地表id政策. 默认为每个表面新建一个UUID;通过固定字符串来再利用每个表面的一个ID. |
| `version` | `'v0.9'` | 协议版本印在信封上. |

## 处理用户动作

当用户与表面交互时( 例如, 按 a) `Button`页:1 制造器发出一个 `A2uiClientAction`。将其变成代理输入 `actionToMessage` 并把它当作下一个转弯:

```ts
import { actionToMessage, type A2uiClientAction } from '@genkit-ai/a2ui/client';

const processor = new MessageProcessor([basicCatalog], (action) => {
  const turn = chat.sendStream({ message: actionToMessage(action) });
  // …consume turn.stream like above…
});
```

行动 `name` 作为用户信息发送; 全部动作(包括其 `context`)作为a2ui数据部分附后,使剂能与之反应.

### 表单

输入组件`TextField`, (中文(简体) ), `CheckBox`, (中文(简体) ), `Slider`这样做 **没有** 发送他们的值 自动。 要捕捉用户输入的内容,模型必须:

1.  捆绑每个输入的 `value` 用于数据模型路径(`{ "path": "/email" }`) (中文(简体) ).
2.  重复提交中的相同路径 `Button`是因为 `action.event.context`。 。 。 .

输入系统的目录能力已指示 做这个的模型。 没有两步,动作就空了 `context`。 。 。 .

### 招标人要求

这个 `@a2ui/lit` 基本目录需要两个主机侧块才能完全渲染:

-   A 类 **下调渲染器** 通过 上下文(例如,由 `@a2ui/markdown-it`) (中文(简体) ). `Text` 标题变体作为Markdown提供.
-   这个 **材料符号已大纲** 字体。 这个 `Icon` 组件将名称改为 字体连接.

没有它们,标题显示为文字 `##` 图标以字面名称显示。 见 [`js/testapps/a2ui`](https://npmcn.com/package/testapps/a2ui) 为接线.

## 自定义目录

这个 `catalog` 选项是 **目录编号** 由基因组登记册解决。 这个 捆绑 `'basic'` 目录( mirroring) `@a2ui/web_core`基本目录)是 默认且不需要注册.

为了匹配自己的布局元素和设计系统,定义自定义目录, 注册到 `loadCatalog`,并引用代码.

### 目录格式

A2UI目录描述了允许该模型发射的组件:

-   `id`: 全球独一无二的URI 识别目录(作为 `catalogId` 打开 `createSurface`) (中文(简体) ).
-   `components`: 一组组件,每个组件都有:
    -   `name`: 组件类型名称,匹配渲染器类型(例如) `CustomCard`, (中文(简体) ), `Text`) (中文(简体) ).
    -   `description`:该组成部分是什么以及何时构成的明确、一行摘要 用这个.
    -   `props`: 关于其属性的紧凑、模型化文本描述(按 一个简单的,人能读取的字符串,以尽量减少系统即时符号的使用.

### 选项A:从 JSON 文件装入

创建 JSON 文件( 例如) `./my-catalog.json`遵循这一格式:

```json
{
  "id": "https://my-app.org/catalogs/custom.json",
  "components": [
    {
      "name": "Banner",
      "description": "Displays a prominent alert banner at the top of a section.",
      "props": "title: string (required); severity?: info|warning|error."
    },
    {
      "name": "Text",
      "description": "Displays a plain or inline-markdown text run.",
      "props": "text: string (required); variant?: body|caption."
    }
  ]
}
```

然后在查询标识符下注册(例如) `'my-catalog'`) 上 时 间 服务器 :

```ts
import { loadCatalog } from '@genkit-ai/a2ui';

await loadCatalog(ai, { id: 'my-catalog', file: './my-catalog.json' });
```

### 备选案文B:内在定义

您可以构建和注册 `A2uiCatalog` 直接 :

```ts
import { loadCatalog, type A2uiCatalog } from '@genkit-ai/a2ui';

const myCatalog: A2uiCatalog = {
  id: 'https://my-app.org/catalogs/custom.json',
  components: [
    {
      name: 'Banner',
      description: 'Displays a prominent alert banner at the top of a section.',
      props: 'title: string (required); severity?: info|warning|error.',
    },
    {
      name: 'Text',
      description: 'Displays a plain or inline-markdown text run.',
      props: 'text: string (required); variant?: body|caption.',
    },
  ],
};

await loadCatalog(ai, { id: 'my-catalog', catalog: myCatalog });
```

### 使用已注册目录

注册后,请参考您 `a2ui()` 选项:

```ts
export const uiAgent = ai.defineAgent({
  name: 'uiAgent',
  model: 'googleai/gemini-flash-latest',
  use: [a2ui({ catalog: 'my-catalog' })],
});
```

登记簿中的目录(数值类型) `a2ui-catalog`所以中间的软件可以 通过id来解决它们,在未来,工具可以列出它们.

## 安全和信任边界

Generative UI 将模型输出移入 DOM, 所以处理每个表面的代理 输出为 **未信任输入**编辑 `a2ui()` 中间软件 `validate` 选项 (包括 `'strict'`(b) 检查信封结构和组件 _类型名称_ 只反对目录。 没错 **没有** 验证组件道具或数据模型 值:模型控制值,例如 `Image.url` 财务报告和审定财务报表 `Text` (在线马克下, ,而渲染器可能变成HTML)通过未变. `'strict'` 是一个 良好的结构检查,不是安全边界.

因此,一个被迅速注射或直接错误的模型可以释放任意的远程 图像 URL,或 Markdown 即一个渲染器会变成 HTML 。 为了保证安全:

-   **渲染器/目录拥有道具的消毒.** 不管是什么使一个表面 (例如 `@a2ui/lit` 加上你的Markdown渲染器) 在到达DOM之前 逃脱并消毒道具值 如果你运送 自定义目录,其渲染器必须将自己的组件道具进行消毒.
-   **限制主机的远程源 .** 为应用程序提供内容安全 限制的政策 `img-src` 以你们所信任的出身, 因此模型提供的图像或链接 URL 无法过滤数据或加载 意外内容 .
-   **不要在数据模型中隐藏秘密 .** 任何与地表数据相连的东西 模型可以通过动作回放 `context`。 。 。 .

如果您需要服务器端对道具的控制( 例如, 允许列表图像) 主机后, 添加您自己的型号中间软件 `a2ui()` 检查并重写 释放出a2ui部件.

## 如何运作

### 1名代表

A2UI 骑自有部分频道:一款Genkit `data` 带有 mime 类型的部件 `application/a2ui+json` 谁 `data` 是对象 `{ envelopes }` 包装 数组 A2UI 信封信息。 此地图为 A2UI 装订的 A2A 上的 1:1 spec,所以一个A2A或MCP绑定可以稍后免费下放.

-   A 类 **混合** 转动是信息的内容 `[textPart, a2uiPart, …]`。 。 。 .
-   A 类 **纯地表** 转弯是没有文本部分的特例.
-   下游消费者(客户运输、, `@a2ui/web_core`) 只见过a2ui 页:1 "Pure vs mix"是一个提示性的选择,而不是单独的代码路径.

### 中间软件管道

在代理工具循环的每个模型呼叫中, `a2ui()`数字 :

1.  将目录的能力输入系统 提示模型知道 以物配主 `instructions: 'none'`) (中文(简体) ).
2.  截取了模型的输出,既包括流出块,也包括最终块 汇总消息.
3.  摘录 `a2ui` 从模型的文本中取出有栅栏的代码块.
4.  对照目录验证它们(每 `validate` 选项).
5.  把它们重写成 Cononical a2ui 数据部件.

输入的a2ui部分(例如,作为下个转弯返回的表面动作,或 (重播历史)在基础模型看到之前被归纳为纯文本 因此,一个不懂 ai2ui mime 类型的模型 仍然可以解释 关于先前的表面和用户动作.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @genkit-ai/a2ui 是什么？

一个Genkit插件,通过模型中间软件提供A2UI\(Agent-to-UI\)流式UI协议支持\.

### 如何安装 @genkit-ai/a2ui？

在项目目录运行 npm install @genkit-ai/a2ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：genkit（^1\.44\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @genkit-ai/a2ui 支持 TypeScript 吗？

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

### @genkit-ai/a2ui 支持 ESM 还是 CommonJS？

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

### @genkit-ai/a2ui 需要什么版本的 Node\.js？

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

### @genkit-ai/a2ui 可以商用吗？

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

### @genkit-ai/a2ui 的下载量有多少？

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

### @genkit-ai/a2ui 还在维护吗？

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

