@alicloud/appflow-chat 0.0.3-beta.1 → 0.0.4-alpha.1

package/dist/types/index.d.ts

@@ -1,5 +1,73 @@
+import { A2UIViewerProps } from '@a2ui/react';
+import { ComponentRegistry } from '@a2ui/react';
 import { default as default_2 } from 'react';
+import { OnActionCallback } from '@a2ui/react';
 import { Provider } from 'react';
+import { ServerToClientMessage } from '@a2ui/react';
+
+/** A2UI 协议消息（v0.8 格式，透传给 @a2ui/react 处理） */
+export declare type A2UIMessage = ServerToClientMessage;
+
+/**
+ * A2UIStaticViewer - A2UI 静态 JSON 渲染组件
+ *
+ * 用于直接从静态的组件定义和数据渲染 UI，无需流式消息。
+ * 适用于已有完整 A2UI 组件树的场景。
+ *
+ * @example
+ * ```tsx
+ * const components = [
+ *   { id: 'root', component: { Card: { child: 'text' } } },
+ *   { id: 'text', component: { Text: { text: { path: '/message' } } } },
+ * ];
+ *
+ * <A2UIStaticViewer
+ *   root="root"
+ *   components={components}
+ *   data={{ message: 'Hello World!' }}
+ *   onAction={(action) => console.log('Action:', action)}
+ * />
+ * ```
+ */
+export declare const A2UIStaticViewer: default_2.FC<A2UIStaticViewerProps>;
+
+/** A2UIViewer 的 Props，用于静态 JSON 渲染场景 */
+export declare type A2UIStaticViewerProps = A2UIViewerProps;
+
+/**
+ * A2UISurface - A2UI 声明式 UI 渲染组件（流式消息场景）
+ *
+ * 接收 Agent 发送的 A2UI 协议消息数组，增量处理并渲染对应的 Surface。
+ * 内部封装了 A2UIProvider，可直接作为 BubbleContent 的 children 使用。
+ *
+ * @example
+ * ```tsx
+ * // 作为 BubbleContent 的 children 使用
+ * <BubbleContent content={content} status={status}>
+ *   <A2UISurface
+ *     messages={a2uiMessages}
+ *     surfaceId="main"
+ *     onAction={(msg) => console.log('用户操作:', msg)}
+ *   />
+ * </BubbleContent>
+ * ```
+ */
+export declare const A2UISurface: default_2.FC<A2UISurfaceProps>;
+
+export declare interface A2UISurfaceProps {
+    /** A2UI JSON 消息数组（来自 Agent 的响应） */
+    messages: A2UIMessage[];
+    /** 渲染的 Surface ID（默认 'main'） */
+    surfaceId?: string;
+    /** 用户在 A2UI 组件上的交互回调 */
+    onAction?: OnActionCallback;
+    /** 自定义组件注册表（可选，默认使用内置组件） */
+    registry?: ComponentRegistry;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: default_2.CSSProperties;
+}
 
 /**
  * AssociationPropertyMetadata 类型定义
@@ -530,14 +598,18 @@ export declare interface MessageBubbleProps {
     onReferenceClick?: (item: DocReferenceItem) => void;
     /** 点击网页搜索结果回调（不传则使用默认实现） */
     onWebSearchClick?: (items: DocReferenceItem[]) => void;
-    /** 事件类型（用于特殊消息如 humanVerify、historyCard） */
-    eventType?: 'humanVerify' | 'historyCard';
+    /** 事件类型（用于特殊消息如 humanVerify、historyCard、a2ui） */
+    eventType?: 'humanVerify' | 'historyCard' | 'a2ui';
     /** HumanVerify 相关数据 */
     humanVerifyData?: HumanVerifyData;
     /** HistoryCard 相关数据（历史对话中的审核卡片） */
     historyCardData?: HistoryCardData;
     /** HumanVerify 提交回调 */
     onHumanVerifySubmit?: (data: HumanVerifySubmitData) => void;
+    /** A2UI 消息数组（Agent 生成的声明式 UI 描述） */
+    a2uiMessages?: A2UIMessage[];
+    /** A2UI 用户交互回调 */
+    onA2UIAction?: (action: any) => void;
 }
 
 export declare interface ModelCapabilities {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alicloud/appflow-chat",
-  "version": "0.0.3-beta.1",
+  "version": "0.0.4-alpha.1",
   "description": "Appflow-Chat AI聊天机器人组件库，提供聊天服务和UI组件",
   "type": "module",
   "main": "./dist/appflow-chat.cjs.js",
@@ -58,6 +58,8 @@
     "vite-plugin-dts": "^4.3.0"
   },
   "peerDependencies": {
+    "@a2ui/react": "^0.8.0",
+    "@a2ui/web_core": "^0.8.0",
     "antd": "^5.0.0",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"

package/src/components/A2UIRenderer/A2UIRenderer.tsx

@@ -0,0 +1,181 @@
+/**
+ * A2UISurface - A2UI 声明式 UI 渲染组件
+ * 
+ * 基于 Google A2UI 协议，将 Agent 生成的声明式 JSON 消息
+ * 渲染为原生 React 组件。支持流式增量更新和自定义组件注册。
+ * 
+ */
+
+import React, { useEffect, useRef, useCallback } from 'react';
+import styled from 'styled-components';
+import {
+  A2UIProvider,
+  A2UIRenderer,
+  A2UIViewer,
+  useA2UI,
+  initializeDefaultCatalog,
+  ComponentRegistry,
+} from '@a2ui/react';
+import type {
+  ServerToClientMessage,
+  OnActionCallback,
+  A2UIViewerProps,
+} from '@a2ui/react';
+
+// 初始化默认组件目录（全局只需执行一次）
+initializeDefaultCatalog();
+
+// ==================== Types ====================
+
+/** A2UI 协议消息（v0.8 格式，透传给 @a2ui/react 处理） */
+export type A2UIMessage = ServerToClientMessage;
+
+export interface A2UISurfaceProps {
+  /** A2UI JSON 消息数组（来自 Agent 的响应） */
+  messages: A2UIMessage[];
+  /** 渲染的 Surface ID（默认 'main'） */
+  surfaceId?: string;
+  /** 用户在 A2UI 组件上的交互回调 */
+  onAction?: OnActionCallback;
+  /** 自定义组件注册表（可选，默认使用内置组件） */
+  registry?: ComponentRegistry;
+  /** 自定义类名 */
+  className?: string;
+  /** 自定义样式 */
+  style?: React.CSSProperties;
+}
+
+/** A2UIViewer 的 Props，用于静态 JSON 渲染场景 */
+export type A2UIStaticViewerProps = A2UIViewerProps;
+
+// ==================== Styled Components ====================
+
+const A2UIContainer = styled.div`
+  margin-top: 12px;
+  width: 100%;
+  max-width: 100%;
+`;
+
+// ==================== Internal Component ====================
+
+/**
+ * 内部组件：负责消息处理和 Surface 渲染
+ * 必须在 A2UIProvider 内部使用，以获取 useA2UI hook 的上下文
+ */
+const A2UISurfaceInner: React.FC<{
+  messages: A2UIMessage[];
+  surfaceId: string;
+  registry?: ComponentRegistry;
+  className?: string;
+  style?: React.CSSProperties;
+}> = ({ messages, surfaceId, registry, className, style }) => {
+  const { processMessages, getSurface } = useA2UI();
+  const processedCountRef = useRef(0);
+
+  // 增量处理新到达的消息（支持流式场景）
+  useEffect(() => {
+    if (messages.length > processedCountRef.current) {
+      const newMessages = messages.slice(processedCountRef.current);
+      processMessages(newMessages);
+      processedCountRef.current = messages.length;
+    }
+  }, [messages, processMessages]);
+
+  // 当消息被清空时重置计数器
+  useEffect(() => {
+    if (messages.length === 0) {
+      processedCountRef.current = 0;
+    }
+  }, [messages.length]);
+
+  const surface = getSurface(surfaceId);
+
+  if (!surface) {
+    return null;
+  }
+
+  return (
+    <A2UIContainer className={className} style={style}>
+      <A2UIRenderer
+        surfaceId={surfaceId}
+        registry={registry}
+      />
+    </A2UIContainer>
+  );
+};
+
+// ==================== Exported Components ====================
+
+/**
+ * A2UISurface - A2UI 声明式 UI 渲染组件（流式消息场景）
+ * 
+ * 接收 Agent 发送的 A2UI 协议消息数组，增量处理并渲染对应的 Surface。
+ * 内部封装了 A2UIProvider，可直接作为 BubbleContent 的 children 使用。
+ * 
+ * @example
+ * ```tsx
+ * // 作为 BubbleContent 的 children 使用
+ * <BubbleContent content={content} status={status}>
+ *   <A2UISurface 
+ *     messages={a2uiMessages} 
+ *     surfaceId="main"
+ *     onAction={(msg) => console.log('用户操作:', msg)} 
+ *   />
+ * </BubbleContent>
+ * ```
+ */
+export const A2UISurface: React.FC<A2UISurfaceProps> = ({
+  messages,
+  surfaceId = 'main',
+  onAction,
+  registry,
+  className,
+  style,
+}) => {
+  const handleAction: OnActionCallback = useCallback((message) => {
+    onAction?.(message);
+  }, [onAction]);
+
+  return (
+    <A2UIProvider onAction={handleAction}>
+      <A2UISurfaceInner
+        messages={messages}
+        surfaceId={surfaceId}
+        registry={registry}
+        className={className}
+        style={style}
+      />
+    </A2UIProvider>
+  );
+};
+
+/**
+ * A2UIStaticViewer - A2UI 静态 JSON 渲染组件
+ * 
+ * 用于直接从静态的组件定义和数据渲染 UI，无需流式消息。
+ * 适用于已有完整 A2UI 组件树的场景。
+ * 
+ * @example
+ * ```tsx
+ * const components = [
+ *   { id: 'root', component: { Card: { child: 'text' } } },
+ *   { id: 'text', component: { Text: { text: { path: '/message' } } } },
+ * ];
+ * 
+ * <A2UIStaticViewer
+ *   root="root"
+ *   components={components}
+ *   data={{ message: 'Hello World!' }}
+ *   onAction={(action) => console.log('Action:', action)}
+ * />
+ * ```
+ */
+export const A2UIStaticViewer: React.FC<A2UIStaticViewerProps> = (props) => {
+  return (
+    <A2UIContainer>
+      <A2UIViewer {...props} />
+    </A2UIContainer>
+  );
+};
+
+export default A2UISurface;

package/src/components/A2UIRenderer/index.ts

@@ -0,0 +1 @@
+export { A2UISurface, A2UIStaticViewer, type A2UISurfaceProps, type A2UIStaticViewerProps, type A2UIMessage } from './A2UIRenderer';

package/src/components/MessageBubble.tsx

@@ -11,6 +11,8 @@ import { loadEchartsScript } from '@/utils/loadEcharts';
 import { DocReferences, DocReferenceItem } from './DocReferences';
 import { WebSearchPanel } from './WebSearchPanel';
 import { HumanVerify, HistoryCard, CustomParamSchema } from './HumanVerify';
+import { A2UISurface } from './A2UIRenderer';
+import type { A2UIMessage } from './A2UIRenderer';
 import { BubbleContent } from '@/core';
 
 /** HumanVerify 提交数据类型 */
@@ -58,14 +60,21 @@ export interface MessageBubbleProps {
   
   // ==================== HumanVerify相关Props ====================
   
-  /** 事件类型（用于特殊消息如 humanVerify、historyCard） */
-  eventType?: 'humanVerify' | 'historyCard';
+  /** 事件类型（用于特殊消息如 humanVerify、historyCard、a2ui） */
+  eventType?: 'humanVerify' | 'historyCard' | 'a2ui';
   /** HumanVerify 相关数据 */
   humanVerifyData?: HumanVerifyData;
   /** HistoryCard 相关数据（历史对话中的审核卡片） */
   historyCardData?: HistoryCardData;
   /** HumanVerify 提交回调 */
   onHumanVerifySubmit?: (data: HumanVerifySubmitData) => void;
+
+  // ==================== A2UI相关Props ====================
+
+  /** A2UI 消息数组（Agent 生成的声明式 UI 描述） */
+  a2uiMessages?: A2UIMessage[];
+  /** A2UI 用户交互回调 */
+  onA2UIAction?: (action: any) => void;
 }
 
 // 样式隔离容器
@@ -270,6 +279,9 @@ export const MessageBubble: React.FC<MessageBubbleProps> = ({
   humanVerifyData,
   historyCardData,
   onHumanVerifySubmit,
+  // A2UI 相关 props
+  a2uiMessages,
+  onA2UIAction,
 }) => {
   const [modal, contextHolder] = Modal.useModal();
   
@@ -362,6 +374,14 @@ export const MessageBubble: React.FC<MessageBubbleProps> = ({
                 data={historyCardData}
               />
             )}
+
+            {/* A2UI 事件 - Agent 声明式 UI 渲染 */}
+            {eventType === 'a2ui' && a2uiMessages && a2uiMessages.length > 0 && (
+              <A2UISurface
+                messages={a2uiMessages}
+                onAction={onA2UIAction}
+              />
+            )}
             
             {/* 参考资料 */}
             {references && references.length > 0 && status === 'Success' && (

package/src/index.ts

@@ -76,6 +76,12 @@ export type {
   ValidationError,
 } from './components/HumanVerify';
 
+// ==================== A2UI 组件导出 ====================
+export { A2UISurface, A2UIStaticViewer } from './components/A2UIRenderer';
+
+// ==================== A2UI 组件类型导出 ====================
+export type { A2UISurfaceProps, A2UIStaticViewerProps, A2UIMessage } from './components/A2UIRenderer';
+
 // ==================== 工具函数导出 ====================
 export { loadEchartsScript } from './utils/loadEcharts';
 export { loadMermaidScript } from './utils/loadMermaid';