A2UI 1.0 稳定版落地实操：Genkit 中间件、Lit 渲染器、双向 action 与 v0.9/1.0 版本口径核验

# 查当前 registry 版本（不安装，只读）
npm view @genkit-ai/a2ui version
npm view @a2ui/lit version
npm view @a2ui/web_core version

# 建练习工程
mkdir a2ui-demo && cd a2ui-demo
npm init -y

# 可选：让编码 Agent 先读 Genkit JS 官方技能，减少旧 API 误用
npx skills add genkit-ai/skills --skill developing-genkit-js

# Genkit 侧：A2UI 中间件
npm i @genkit-ai/a2ui

# 浏览器侧：Lit 渲染器 + 共享内核 + Markdown 渲染
npm i @a2ui/lit @a2ui/web_core @a2ui/markdown-it

# 字体在页面里引入（官方要求 basic catalog 的 Icon 靠字体连字渲染）
# https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined

# 装完复核实际版本与导出路径是否匹配
npm ls @genkit-ai/a2ui @a2ui/lit @a2ui/web_core

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

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

// 目录能力默认注入 system；默认目录 id 是 'basic'
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()],
});

// 一次性生成也可以挂同一个中间件
const res = await ai.generate({
  prompt: 'Show me the weather in Tokyo',
  use: [a2ui()],
});

import { MessageProcessor } from '@a2ui/web_core/v0_9';
import { basicCatalog } from '@a2ui/lit/v0_9';
import '@a2ui/lit/v0_9'; // 注册 a2ui-surface 与基础组件
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);
}

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

const processor = new MessageProcessor([basicCatalog], (action) => {
  const turn = chat.sendStream({ message: actionToMessage(action) });
  // 接着按上一步的方式消费 turn.stream
});

// 表单取值要在两处对齐（README 给出的规则）：
// 1. 输入组件的 value 绑定到数据模型路径，例如 {"path":"/email"}
// 2. 提交按钮的 action.event.context 里回显同样的路径
// 少了任意一处，动作到达时 context 是空的。

// my-catalog.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."
    }
  ]
}

// 服务端注册
import { loadCatalog } from '@genkit-ai/a2ui';
await loadCatalog(ai, { id: 'my-catalog', file: './my-catalog.json' });

// 引用时按 id 取
export const uiAgent = ai.defineAgent({
  name: 'uiAgent',
  model: 'googleai/gemini-flash-latest',
  use: [a2ui({ catalog: 'my-catalog' })],
});