@lynx-js/genui

面向 Lynx 应用的 Generative UI 基础组件。

@lynx-js/genui 是 GenUI 工具链统一的 npm 包，提供 A2UI 渲染、OpenUI 渲染、 A2UI Prompt/Catalog 工具、Lynx XML 工具、ReactLynx 生成与构建工具和 CLI，各实现目录保留为此 monorepo 的内部组织。

Installation

pnpm add @lynx-js/genui @lynx-js/react

@lynx-js/react 是一个 peer dependency。部分内置的 A2UI 组件和默认的 OpenUI Library 也会用到 @lynx-js/lynx-ui；当你的应用用到这些界面时，请安装它。

Entry Points

import {
  A2UI,
  createMessageStore,
  createOpenUiLibrary,
  createStreamingParser,
  buildA2UISystemPrompt,
  extractCatalogComponents,
} from '@lynx-js/genui';

根入口导出了大多数应用和工具所需的稳定 API：

A2UI ReactLynx 渲染器和数据存储辅助函数。
OpenUI 解析器、组件库和渲染器 API。
A2UI Prompt 构建器。
A2UI Catalog 提取工具。
ReactLynx 生成 Prompt、源码校验和 Node.js 编译。

也可以使用聚焦子路径：

import { A2UI, Text, Button } from '@lynx-js/genui/a2ui';
import { createMessageStore } from '@lynx-js/genui/a2ui/store';
import { createOpenUiLibrary } from '@lynx-js/genui/openui';
import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
import { extractCatalogComponents } from '@lynx-js/genui/a2ui-catalog-extractor';
import { normalizeLynxXmlArtifact } from '@lynx-js/genui/lynx-xml';
import {
  buildReactLynx,
  parseReactLynxSource,
  REACTLYNX_SYSTEM_PROMPT,
} from '@lynx-js/genui/reactlynx';

@lynx-js/genui/lynx-xml 提供系统提示词、确定性产物装配，以及用于文档规范化和校验的 normalizeLynxXmlArtifact。这些能力不依赖 agent 或渲染器。

Catalog manifest 通过单一的公共 catalog 入口导出：

import { Text, Button } from '@lynx-js/genui/a2ui/catalog';

A2UI

A2UI 用于渲染遵循 A2UI v0.9 协议的、由 agent 生成的 UI 消息。创建一个消息存储（message store），从你的传输层将协议消息推送进去，然后使用 <A2UI> 渲染最新的 surface。

import { A2UI, Button, Text, createMessageStore } from '@lynx-js/genui/a2ui';

const messageStore = createMessageStore();

export function GenUIScreen() {
  return (
    <A2UI
      messageStore={messageStore}
      catalogs={[Text, Button]}
      onAction={(action) => {
        // Send the action back to your agent, then push response messages
        // into the same messageStore.
      }}
    />
  );
}

需要打包好的组件样式时，使用 A2UI 样式入口：

import '@lynx-js/genui/a2ui/styles/theme.css';

关于 catalog 组合与自定义组件的详情，请参见 a2ui/README.md。

OpenUI

OpenUI 通过一个可配置的组件库来渲染 OpenUI Lang v0.5 的响应。

import { OpenUiRenderer, createOpenUiLibrary } from '@lynx-js/genui/openui';

const library = createOpenUiLibrary();
const response = 'root = Stack([TextContent("Hello")])';

export function OpenUIScreen() {
  return <OpenUiRenderer response={response} library={library} />;
}

模型流式输出时，传入累计全文和生成状态：

<OpenUiRenderer
  response={accumulatedText}
  isStreaming={isGenerating}
  library={library}
/>;

把每个 delta 追加到业务状态；收到完整快照时替换文本。renderer 会缓存已完成的语句并预览未完成的尾部。成功完成前保持 isStreaming 为 true，然后一起更新最终文本和 false 标记，即使文本未变也要更新。失败或取消时清空未完成的 response。transport 回调与会话生命周期见流式接入指南。

在你的应用中导入一次可选的 OpenUI 主题 token：

import '@lynx-js/genui/openui/styles/theme.css';

渲染器和组件样式由各自的模块导入。

要退出默认组件集，请使用显式入口，并从其组件子路径中导入 Library 仍需要的每个内置定义：

import { createOpenUiLibrary } from '@lynx-js/genui/openui/explicit';
import { Stack } from '@lynx-js/genui/openui/catalog/Stack';
import { TextContent } from '@lynx-js/genui/openui/catalog/TextContent';

const library = createOpenUiLibrary({
  includeDefaultComponents: false,
  components: [Stack, TextContent],
});

该标志控制哪些 definition 和 group 属于该 Library。主要的 openui 入口仍然对默认 catalog 具有静态依赖；当被省略的内置项必须留在静态依赖图之外时，请使用 openui/explicit 搭配各个 catalog 子路径。

关于流式输出与自定义库的示例，请参见 openui/README.md。

ReactLynx

使用 REACTLYNX_SYSTEM_PROMPT 生成完整的 App.tsx 与 App.css，通过 parseReactLynxSource 校验响应，在 Node.js 中使用 buildReactLynx 编译。在宿主中加载 Web 或 Native bundle 前发布全部返回产物。服务端打包时将 @lynx-js/genui/reactlynx 保持为 external，确保编译 worker 仍位于入口文件旁边。

参见 ReactLynx 指南。

CLI

该包会安装 GenUI CLI 以及底层的 catalog extractor 二进制文件：

genui --help
genui-cli --help
a2ui-catalog-extractor --help

a2ui-cli 仍作为兼容性别名保留，以支持现有的 A2UI 脚本。新脚本应优先使用以命名空间开头的 genui a2ui ... 或 genui openui ... 形式。

生成 catalog artifact：

genui a2ui generate catalog \
  --catalog-dir src/catalog \
  --source src/functions \
  --out-dir dist/catalog

生成一个 A2UI system prompt：

genui a2ui generate prompt \
  --catalog-dir dist/catalog \
  --out dist/a2ui-system-prompt.txt

生成一个 OpenUI system prompt：

genui openui generate prompt --out dist/openui-system-prompt.txt

Published Package Layout

只有 @lynx-js/genui 才打算被发布。该包在 dist/ 目录下包含编译后的 JavaScript 和声明文件，此外还有 CLI 入口、 README 文件、样式以及提取器 skill。

根目录的 index.ts 会在构建时编译。请勿手写 dist/index.js 或 dist/index.d.ts，而是运行：

pnpm -C packages/genui build

在发布之前，请验证包的内容：

pnpm -C packages/genui pack --dry-run

License

Apache-2.0

可选的 OpenUI Chat 组件库使用官方 Chat 位置参数约定，并提供可在服务端使用的 schema 入口。

#@lynx-js/genui

#Installation

#Entry Points

#A2UI

#OpenUI

#ReactLynx

#CLI

#Published Package Layout

#License

#包