feat(chatengine): doc refine

Author: carolin913

packages/pro-components/chat/chat-engine/_example/agui-comprehensive.tsx

@@ -9,9 +9,9 @@ import {
   ToolCallRenderer,
   useAgentToolcall,
   useChat,
-  AgentStateProvider,
+  useAgentState,
 } from '@tdesign-react/chat';
-import { CheckCircleFilledIcon, TimeFilledIcon, ErrorCircleFilledIcon } from 'tdesign-icons-react';
+import { CheckCircleFilledIcon, TimeFilledIcon, ErrorCircleFilledIcon, LoadingIcon } from 'tdesign-icons-react';
 import type {
   TdChatMessageConfig,
   TdChatSenderParams,
@@ -89,10 +89,9 @@ const PlanningSteps: React.FC<ToolcallComponentProps<PlanningArgs>> = ({
   respond,
   agentState,
 }) => {
-  // 直接使用注入的 agentState，无需额外 Hook
-  const planningState = agentState?.[args?.taskId] || {};
-  const items = planningState?.items || [];
-
+  // 因为配置了 subscribeKey，agentState 已经是 taskId 对应的状态对象
+  const planningState = agentState || {};
+  
   const isComplete = status === 'complete';
 
   React.useEffect(() => {
@@ -101,49 +100,21 @@ const PlanningSteps: React.FC<ToolcallComponentProps<PlanningArgs>> = ({
     }
   }, [isComplete, respond]);
 
-  const getStatusIcon = (itemStatus: string) => {
-    switch (itemStatus) {
-      case 'completed':
-        return <CheckCircleFilledIcon style={{ color: '#00a870' }} />;
-      case 'running':
-        return <TimeFilledIcon style={{ color: '#0052d9' }} />;
-      case 'failed':
-        return <ErrorCircleFilledIcon style={{ color: '#e34d59' }} />;
-      default:
-        return <TimeFilledIcon style={{ color: '#bbbbbb' }} />;
-    }
-  };
-
   return (
     <Card bordered style={{ marginTop: 8 }}>
       <div style={{ fontSize: 14, fontWeight: 600, marginBottom: 12 }}>
         正在为您规划 {args?.destination} {args?.days}日游
       </div>
 
-      {/* 进度条 */}
+      {/* 只保留进度条 */}
       {planningState?.progress !== undefined && (
-        <div style={{ marginBottom: 16 }}>
+        <div>
           <Progress percentage={planningState.progress} />
           <div style={{ fontSize: 12, color: '#888', marginTop: 4 }}>
             {planningState.message || '规划中...'}
           </div>
         </div>
       )}
-
-      {/* 步骤列表 */}
-      {items.length > 0 && (
-        <Space direction="vertical" size="small" style={{ width: '100%' }}>
-          {items.map((item: any, index: number) => (
-            <div key={index} style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
-              {getStatusIcon(item.status)}
-              <span style={{ flex: 1 }}>{item.label}</span>
-              <Tag theme={item.status === 'completed' ? 'success' : 'default'} size="small">
-                {item.status}
-              </Tag>
-            </div>
-          ))}
-        </Space>
-      )}
     </Card>
   );
 };
@@ -152,6 +123,7 @@ const PlanningSteps: React.FC<ToolcallComponentProps<PlanningArgs>> = ({
 const UserPreferencesForm: React.FC<ToolcallComponentProps<UserPreferencesArgs, any, UserPreferencesResponse>> = ({
   status,
   respond,
+  result,
 }) => {
   const [budget, setBudget] = useState(5000);
   const [interests, setInterests] = useState<string[]>(['美食', '文化']);
@@ -165,10 +137,23 @@ const UserPreferencesForm: React.FC<ToolcallComponentProps<UserPreferencesArgs,
     });
   };
 
-  if (status === 'complete') {
+  if (status === 'complete' && result) {
     return (
       <Card bordered style={{ marginTop: 8 }}>
-        <div style={{ color: '#00a870' }}>✓ 已收到您的偏好设置</div>
+        <div style={{ fontSize: 14, fontWeight: 600, marginBottom: 8, color: '#00a870' }}>
+          ✓ 已收到您的偏好设置
+        </div>
+        <Space direction="vertical" size="small">
+          <div style={{ fontSize: 12, color: '#666' }}>
+            预算：¥{result.budget}
+          </div>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            兴趣：{result.interests.join('、')}
+          </div>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            住宿：{result.accommodation}
+          </div>
+        </Space>
       </Card>
     );
   }
@@ -222,14 +207,118 @@ const UserPreferencesForm: React.FC<ToolcallComponentProps<UserPreferencesArgs,
   );
 };
 
+// ==================== 外部进度面板组件 ====================
+
+/**
+ * 右侧进度面板组件
+ * 演示如何在对话组件外部使用 useAgentState 获取状态
+ * 
+ * 💡 使用场景：展示规划行程的详细子步骤（从后端 STATE_DELTA 事件推送）
+ * 
+ * 实现方式：
+ * 1. 使用 useAgentState 订阅状态更新
+ * 2. 从 stateMap 中获取规划步骤的详细进度
+ */
+const ProgressPanel: React.FC = () => {
+  // 使用 useAgentState 订阅状态更新
+  const { stateMap, currentStateKey } = useAgentState();
+  
+  // 获取规划状态
+  const planningState = useMemo(() => {
+    if (!currentStateKey || !stateMap[currentStateKey]) {
+      return null;
+    }
+    return stateMap[currentStateKey];
+  }, [stateMap, currentStateKey]);
+
+  // 如果没有规划状态，不显示面板
+  if (!planningState || !planningState.items || planningState.items.length === 0) {
+    return null;
+  }
+
+  const items = planningState.items || [];
+  const completedCount = items.filter((item: any) => item.status === 'completed').length;
+  const totalCount = items.length;
+
+  // 如果所有步骤都完成了，隐藏面板
+  if (completedCount === totalCount && totalCount > 0) {
+    return null;
+  }
+
+  const getStatusIcon = (itemStatus: string) => {
+    switch (itemStatus) {
+      case 'completed':
+        return <CheckCircleFilledIcon style={{ color: '#00a870', fontSize: '14px' }} />;
+      case 'running':
+        return <LoadingIcon style={{ color: '#0052d9', fontSize: '14px' }} />;
+      case 'failed':
+        return <ErrorCircleFilledIcon style={{ color: '#e34d59', fontSize: '14px' }} />;
+      default:
+        return <TimeFilledIcon style={{ color: '#bbbbbb', fontSize: '14px' }} />;
+    }
+  };
+
+  return (
+    <div style={{ 
+      position: 'fixed',
+      right: '200px',
+      top: '50%',
+      transform: 'translateY(-50%)',
+      width: '200px',
+      background: '#fff', 
+      padding: '16px',
+      borderRadius: '8px',
+      boxShadow: '0 2px 12px rgba(0, 0, 0, 0.1)',
+      border: '1px solid #e7e7e7',
+      zIndex: 1000,
+    }}>
+      <div style={{ 
+        marginBottom: '12px',
+        paddingBottom: '8px',
+        borderBottom: '1px solid #e7e7e7'
+      }}>
+        <div style={{ fontSize: '14px', fontWeight: 600, color: '#000', marginBottom: '4px' }}>
+          规划进度
+        </div>
+        <Tag theme="primary" variant="light" size="small">
+          {completedCount}/{totalCount}
+        </Tag>
+      </div>
+      
+      {/* 步骤列表 */}
+      <Space direction="vertical" size="small" style={{ width: '100%' }}>
+        {items.map((item: any, index: number) => (
+          <div key={index} style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+            {getStatusIcon(item.status)}
+            <span style={{ 
+              flex: 1, 
+              fontSize: '12px',
+              color: item.status === 'completed' ? '#00a870' : (item.status === 'running' ? '#0052d9' : '#666'),
+              fontWeight: item.status === 'running' ? 600 : 400,
+            }}>
+              {item.label}
+            </span>
+          </div>
+        ))}
+      </Space>
+    </div>
+  );
+};
+
 // ==================== 主组件 ====================
 const TravelPlannerContent: React.FC = () => {
-  const listRef = useRef<TdChatListApi>(null);
-  const inputRef = useRef<TdChatSenderApi>(null);
+  const listRef = useRef<TdChatListApi & HTMLElement>(null);
+  const inputRef = useRef<TdChatSenderApi & HTMLElement>(null);
   const [inputValue, setInputValue] = useState<string>('请为我规划一个北京3日游行程');
 
-  // 注册工具配置（利用 agentState 注入）
+  // 注册工具配置
   useAgentToolcall([
+    {
+      name: 'collect_user_preferences',
+      description: '收集用户偏好',
+      parameters: [{ name: 'destination', type: 'string', required: true }],
+      component: UserPreferencesForm as any,
+    },
     {
       name: 'query_weather',
       description: '查询目的地天气',
@@ -245,12 +334,8 @@ const TravelPlannerContent: React.FC = () => {
         { name: 'taskId', type: 'string', required: true },
       ],
       component: PlanningSteps as any,
-    },
-    {
-      name: 'collect_user_preferences',
-      description: '收集用户偏好',
-      parameters: [{ name: 'destination', type: 'string', required: true }],
-      component: UserPreferencesForm as any,
+      // 配置 subscribeKey，让组件订阅对应 taskId 的状态
+      subscribeKey: (props) => props.args?.taskId,
     },
   ]);
 
@@ -290,17 +375,20 @@ const TravelPlannerContent: React.FC = () => {
   // 处理工具调用响应
   const handleToolCallRespond = useCallback(
     async (toolcall: ToolCall, response: any) => {
-      const tools = chatEngine.getToolcallByName(toolcall.toolCallName) || {};
-      await chatEngine.sendAIMessage({
-        params: {
-          toolCallMessage: {
-            ...tools,
-            result: JSON.stringify(response),
+      // 判断如果是手机用户偏好的响应，则使用 toolcall 中的信息来构建新的请求
+      if (toolcall.toolCallName === 'collect_user_preferences') {
+        await chatEngine.sendAIMessage({
+          params: {
+            toolCallMessage: {
+              toolCallId: toolcall.toolCallId,
+              toolCallName: toolcall.toolCallName,
+              result: JSON.stringify(response),
+            },
           },
-        },
-        sendRequest: true,
-      });
-      listRef.current?.scrollList({ to: 'bottom' });
+          sendRequest: true,
+        });
+        listRef.current?.scrollList({ to: 'bottom' });
+      }
     },
     [chatEngine],
   );
@@ -320,17 +408,6 @@ const TravelPlannerContent: React.FC = () => {
     [handleToolCallRespond],
   );
 
-  // 操作栏
-  const actionHandler = (name: string) => {
-    switch (name) {
-      case 'replay':
-        chatEngine.regenerateAIMessage();
-        break;
-      default:
-        console.log('触发操作', name);
-    }
-  };
-
   const renderMsgContents = (message: ChatMessagesData) => (
     <>
       {message.content?.map((item: any, index: number) => renderMessageContent(item, index))}
@@ -344,10 +421,13 @@ const TravelPlannerContent: React.FC = () => {
   };
 
   return (
-    <div style={{ height: '400px', display: 'flex', flexDirection: 'column' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100%', position: 'relative' }}>
+      {/* 右侧进度面板：使用 useAgentState 订阅状态 */}
+      <ProgressPanel />
+      
       <div style={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
         <ChatList ref={listRef}>
-          {messages.map((message, idx) => (
+          {messages.map((message) => (
             <ChatMessage key={message.id} {...messageProps[message.role]} message={message}>
               {renderMsgContents(message)}
             </ChatMessage>
@@ -367,11 +447,5 @@ const TravelPlannerContent: React.FC = () => {
   );
 };
 
-// 使用 Provider 包裹
-export default function TravelPlannerChat() {
-  return (
-    <AgentStateProvider initialState={{}}>
-      <TravelPlannerContent />
-    </AgentStateProvider>
-  );
-}
+// 导出主组件（不需要 Provider，因为 useAgentState 内部已处理）
+export default TravelPlannerContent;