docs: add agents.md and llm.txt for chatengine

carolin913 · carolin913 · commit eb967bb89f1e · 2026-02-05T16:27:28.000+08:00
diff --git a/packages/pro-components/chat/chat-engine/AGENTS.md b/packages/pro-components/chat/chat-engine/AGENTS.md
@@ -0,0 +1,221 @@
+# AGENTS.md (TDesign ChatEngine)
+
+> **SYSTEM PROMPT / INSTRUCTIONS**
+> This file contains the foundational rules, architectural context, and coding standards for the TDesign ChatEngine SDK.
+> As an AI Agent (Cursor, Copilot, Windsurf), you MUST read and follow these instructions before generating any code using this SDK.
+
+## 1. Project Context & Identity
+- **Name**: TDesign ChatEngine (React)
+- **Type**: React Component Library / Headless SDK
+- **Goal**: Provide a complete, production-ready solution for building AI chat applications, supporting standard protocols (AG-UI) and Generative UI.
+- **Package**: `@tdesign-react/chat`
+- **Key Features**:
+  - Headless `ChatEngine` for logic reuse.
+  - `ChatBot` component for out-of-the-box usage.
+  - Native support for **AG-UI Protocol** (Agent-User Interaction).
+  - **Generative UI** engine (json-render & A2UI support).
+
+## 2. Core Concepts
+
+### 2.1 ChatEngine (Headless Core)
+The `ChatEngine` is the logic core that handles:
+- **Message Management**: Send, receive, update, delete, and history management.
+- **Stream Processing**: Built-in SSE (Server-Sent Events) and fetch stream handling.
+- **Protocol Adaptation**: Adapts backend data to frontend message formats (AG-UI or Custom).
+- **Event Bus**: Pub/Sub system for cross-component communication and side effects.
+
+### 2.2 ChatBot (UI Component)
+`ChatBot` is a high-level component built on top of `ChatEngine` that provides:
+- **Complete UI**: Message list, input area, action bar, and auto-scroll.
+- **Built-in Rendering**: Markdown (Cherry Markdown), Thinking process, Tool calls, Suggestions.
+- **Slot Customization**: `headerSlot`, `messageSlot`, `senderSlot`, `footerSlot`.
+
+### 2.3 AG-UI Protocol
+A standard protocol for AI Agent interaction.
+- **Events**:
+  - `TEXT_MESSAGE_*`: Streaming text responses.
+  - `THINKING_*`: AI thought process visibility.
+  - `TOOL_CALL_*`: Agent tool usage (Start -> Args -> End -> Result).
+  - `ACTIVITY_*`: Dynamic content (Charts, Forms) via Snapshots & Deltas.
+  - `STATE_*`: Shared agent state synchronization.
+- **Flow**: Stream-based, event-driven architecture.
+
+### 2.4 Generative UI
+Dynamic UI generation based on AI output, adopting the **json-render** (Vercel Labs) philosophy with a dual-layer architecture:
+- **Catalog (Constraint Layer)**: Defines what components AI can use (Zod Schema).
+- **Registry (Render Layer)**: Defines how components are rendered (React implementation).
+- **Protocols**:
+  - `json-render`: Native adjacency-list schema (flat structure), details [here](https://json-render.dev/docs).
+  - `A2UI`: Google's adjacency-list schema (supported via built-in adapter)，details [here](https://a2ui.org/specification/v0.9-a2ui/).
+
+> **Note**: The ChatEngine Generative UI engine is optimized for and exclusively supports these flat adjacency-list schemas for efficient streaming and updates.
+
+## 3. Key APIs & Hooks
+
+### 3.1 `useChat`
+The main hook for initializing and managing chat state.
+
+```typescript
+const { chatEngine, messages, status } = useChat({
+  chatServiceConfig: {
+    endpoint: '/api/chat',
+    protocol: 'agui', // Recommended: 'agui' for standard agents
+    stream: true,
+    // Optional: Custom headers or body
+    onRequest: (params) => ({ ...params, headers: { Authorization: '...' } })
+  },
+  defaultMessages: [] // Optional initial messages
+});
+```
+
+### 3.2 `useAgentToolcall`
+Registers custom UI components for AI tool calls.
+
+```typescript
+useAgentToolcall({
+  name: 'weather_query', // Must match backend tool name
+  component: WeatherCard, // React Component receiving { args, result, status }
+  // Optional: Subscribe to specific state keys during execution
+  subscribeKey: (props) => props.args?.taskId 
+});
+```
+
+### 3.3 `useAgentActivity`
+Registers components for dynamic content (Generative UI).
+
+```typescript
+useAgentActivity({
+  activityType: 'stock-chart', // Must match backend activity type
+  component: StockChart // React Component receiving { content }
+});
+```
+
+### 3.4 `useAgentState`
+Subscribes to shared agent state (AG-UI `STATE_*` events).
+
+```typescript
+const { stateMap, currentStateKey } = useAgentState();
+// Access state: stateMap['task_1']
+```
+
+### 3.5 Generative UI Helpers
+- `generateCatalogPrompt`: Generates system prompt for LLM.
+- `createCustomRegistry`: Creates component registry.
+- `createJsonRenderActivityConfig`: Configures json-render activity.
+
+## 4. Coding Standards & Best Practices
+
+- **Prefer Hooks**: Use `useChat`, `useAgentToolcall`, etc., over direct class instantiation when in React components.
+- **Protocol First**: Prefer `protocol: 'agui'` for standard AI agent integration. It handles streaming, tool calls, and state automatically.
+- **Generative UI Safety**: Always use `Catalog` to constrain AI output. Never allow AI to generate arbitrary HTML/JS.
+- **State Management**: Use `useAgentState` for cross-component state sharing instead of prop drilling or external stores when dealing with Agent state.
+- **Customization**: 
+  - Use `ChatBot` slots (`messageSlot`, `headerSlot`) for minor tweaks.
+  - Use `useChat` + atomic components (`ChatList`, `ChatSender`) for full custom layouts.
+
+## 5. Anti-Patterns (What NOT to do)
+
+- ❌ **Do not** manually parse SSE streams if using `protocol: 'agui'`. The SDK handles this.
+- ❌ **Do not** modify `messages` state directly; use `chatEngine` methods (`sendUserMessage`, `setMessages`).
+- ❌ **Do not** use `dangerouslySetInnerHTML` for AI content; use built-in Markdown or Generative UI components.
+- ❌ **Do not** mix `protocol: 'agui'` with custom `onMessage` parsers unless you strictly need to override specific event handling.
+
+## 6. Scenario Guide & Examples
+
+This section maps common development scenarios to specific implementation patterns and example files found in `packages/pro-components/chat/chat-engine/_example`，and you can also refer to the `packages/pro-components/chat/chat-engine.md`for more details.
+
+### 6.1 Basic Usage Scenarios
+
+#### 6.1.1 Quick Start (Basic Chat)
+- **Goal**: Create a simple chat interface with minimal configuration.
+- **Key Pattern**: `useChat` + `ChatBot` or `ChatList/ChatSender`.
+- **Example**: `basic.tsx`
+```tsx
+// Minimal setup
+const { chatEngine, messages } = useChat({
+  chatServiceConfig: { endpoint: '/api/chat', stream: true }
+});
+```
+
+#### 6.1.2 Managing History (Initial Messages)
+- **Goal**: Load chat history or set a welcome message.
+- **Key Pattern**: `defaultMessages` prop or `chatEngine.setMessages()`.
+- **Example**: `initial-messages.tsx`
+```tsx
+// Load history
+<ChatBot defaultMessages={historyMessages} />
+// Or dynamic load
+useEffect(() => {
+  fetchHistory().then(msgs => chatEngine.setMessages(msgs));
+}, []);
+```
+
+#### 6.1.3 Controlling the Engine (Instance Methods)
+- **Goal**: Programmatically send messages, stop generation, or clear chat.
+- **Key Pattern**: `chatEngine.sendUserMessage()`, `chatEngine.abort()`, `chatEngine.clearMessages()`.
+- **Example**: `instance-methods.tsx`
+
+#### 6.1.4 Custom UI Rendering
+- **Goal**: Customize message bubbles, action bars, or input areas.
+- **Key Pattern**: Slots (`messageSlot`, `headerSlot`) or Custom Components in `onMessage`.
+- **Example**: `custom-content.tsx`
+```tsx
+// Custom message rendering via slot
+<ChatBot
+  messageSlot={(msg) => msg.type === 'custom' ? <MyComponent data={msg.content} /> : null}
+/>
+```
+
+### 6.2 AG-UI Protocol Scenarios (Agent Integration)
+
+#### 6.2.1 Standard Agent Integration
+- **Goal**: Connect to an AG-UI compliant backend (supports streaming, tools, thinking).
+- **Key Pattern**: `protocol: 'agui'`.
+- **Example**: `agui-basic.tsx`
+
+#### 6.2.2 Tool Calling (Human-in-the-Loop)
+- **Goal**: Render UI for agent tool calls (e.g., weather widget, forms) and handle user interaction.
+- **Key Pattern**: `useAgentToolcall` + `ToolCallRenderer`.
+- **Example**: `agui-toolcall.tsx`
+```tsx
+useAgentToolcall({
+  name: 'search_flight',
+  component: ({ args, respond }) => (
+    <FlightForm 
+      defaultCity={args.city} 
+      onSubmit={(data) => respond(data)} // Return user input to agent
+    />
+  )
+});
+```
+
+#### 6.2.3 Real-time Status Subscription
+- **Goal**: Display agent progress (e.g., "Scanning database...") outside the chat flow.
+- **Key Pattern**: `useAgentState` subscribing to `STATE_SNAPSHOT/DELTA` events.
+- **Example**: `agui-comprehensive.tsx` (See `GlobalProgressBar` component)
+```tsx
+const { stateMap } = useAgentState();
+const progress = stateMap['current_task']?.percent || 0;
+```
+
+#### 6.2.4 Dynamic Content (Activity)
+- **Goal**: Display live-updating charts or dashboards driven by the agent.
+- **Key Pattern**: `useAgentActivity` + `ACTIVITY_SNAPSHOT/DELTA` events.
+- **Example**: `agui-activity.tsx`
+
+### 6.3 Advanced / Headless Scenarios
+
+#### 6.3.1 Headless Event Bus
+- **Goal**: Handle side effects (logging, analytics) without UI coupling.
+- **Key Pattern**: `chatEngine.eventBus.on()`.
+- **Example**: `headless-eventbus.tsx`
+```tsx
+chatEngine.eventBus.on(ChatEngineEventType.REQUEST_COMPLETE, (payload) => {
+  logAnalytics(payload);
+});
+```
+
+#### 6.3.2 Complex Multi-Step Agent
+- **Goal**: Build a complex agent with planning, tools, and dynamic UI.
+- **Key Pattern**: Combining `useAgentToolcall`, `useAgentActivity`, and `useAgentState`.
+- **Example**: `agui-comprehensive.tsx` (Travel Planner Agent)
diff --git a/packages/pro-components/chat/chat-engine/llms.txt b/packages/pro-components/chat/chat-engine/llms.txt
@@ -0,0 +1,140 @@
+# TDesign ChatEngine SDK
+
+## Documentation Index
+- [Quick Start](https://tdesign.tencent.com/react-chat/getting-started): Get started with TDesign ChatEngine.
+- [AG-UI Integration](https://tdesign.tencent.com/react-chat/agui): Learn how to integrate with AG-UI protocol.
+- [Generative UI](https://tdesign.tencent.com/react-chat/genui): Explore Generative UI capabilities.
+
+## Project Identity
+A React SDK for building production-ready AI chat applications. It features a headless `ChatEngine` for logic reuse, a `ChatBot` component for rapid development, and native support for the **AG-UI Protocol** and **Generative UI**.
+
+## Core Concepts
+- **ChatEngine**: Headless logic core handling message state, SSE streaming, and event bus.
+- **ChatBot**: All-in-one UI component with built-in rendering for Markdown, Thinking, and Tools.
+- **AG-UI**: Standard protocol for Agent-UI interaction (Tool calls, State sync, Activity).
+- **Generative UI**: AI-generated UI based on **json-render** architecture (Catalog + Registry), supporting both native adjacency-list schema and **A2UI** protocol via adapter.
+
+## Key APIs
+
+### Hooks
+- `useChat(config)`: Initialize chat engine and state. Returns `{ chatEngine, messages, status }`.
+- `useAgentToolcall(config)`: Register custom UI components for AI tool calls.
+- `useAgentActivity(config)`: Register components for dynamic content (Generative UI).
+- `useAgentState(options)`: Subscribe to shared agent state updates.
+
+### Components
+- `<ChatBot />`: Main UI component. Props: `chatServiceConfig`, `headerSlot`, `messageSlot`, etc.
+- `<ChatList />`, `<ChatMessage />`, `<ChatSender />`: Atomic components for custom layouts.
+- `<ToolCallRenderer />`: Renders tool calls based on registered configuration.
+- `<ActivityRenderer />`: Renders generative UI based on registered configuration.
+
+### Configuration Types
+- `ChatServiceConfig`: `{ endpoint: string, protocol: 'agui' | 'custom', stream: boolean, onRequest?, onMessage? }`
+- `AgentToolcallConfig`: `{ name: string, component: ReactComponent, subscribeKey?: fn }`
+- `ActivityConfig`: `{ activityType: string, component: ReactComponent }`
+
+## Minimal Perfect Snippets
+
+### 1. Basic AG-UI Chat
+```tsx
+import { ChatBot } from '@tdesign-react/chat';
+
+export default function App() {
+  return (
+    <ChatBot
+      chatServiceConfig={{
+        endpoint: '/api/chat',
+        protocol: 'agui', // Enables standard agent features
+        stream: true
+      }}
+    />
+  );
+}
+```
+
+### 2. Custom Tool Call Registration
+```tsx
+import { ChatBot, useAgentToolcall } from '@tdesign-react/chat';
+
+// Component receives: args (input), result (output), status (idle/executing/complete/error)
+const WeatherCard = ({ args, result, status }) => (
+  <div className="weather-card">
+    <h4>Weather in {args.city}</h4>
+    {status === 'executing' && <p>Loading...</p>}
+    {result && <p>{result.temp}°C</p>}
+  </div>
+);
+
+export default function App() {
+  // Register tool to match backend tool name
+  useAgentToolcall({ name: 'get_weather', component: WeatherCard });
+  
+  return <ChatBot chatServiceConfig={{ protocol: 'agui', endpoint: '/api/chat' }} />;
+}
+```
+
+### 3. Custom Layout (Headless Mode)
+```tsx
+import { useChat, ChatList, ChatSender } from '@tdesign-react/chat';
+
+export default function CustomChat() {
+  const { chatEngine, messages, status } = useChat({
+    chatServiceConfig: { endpoint: '/api/chat', protocol: 'agui' }
+  });
+
+  return (
+    <div className="flex flex-col h-full">
+      <ChatList>{/* Renders messages automatically */}</ChatList>
+      <ChatSender 
+        loading={status === 'streaming'}
+        onSend={(e) => chatEngine.sendUserMessage({ params: { prompt: e.detail.value } })} 
+      />
+    </div>
+  );
+}
+```
+
+### 4. External State Subscription (Progress Bar)
+```tsx
+import { useAgentState } from '@tdesign-react/chat';
+
+// Renders outside the chat window
+export function GlobalProgress() {
+  // Subscribe to AG-UI STATE_* events
+  const { stateMap } = useAgentState();
+  const taskState = stateMap['current_task']; // Key defined by backend
+
+  if (!taskState) return null;
+  return <ProgressBar value={taskState.progress} label={taskState.status} />;
+}
+```
+
+### 6. Side-Panel Generative UI
+```tsx
+import { useChat, ChatEngineEventType, ActivityRenderer } from '@tdesign-react/chat';
+
+export function SplitViewChat() {
+  const { chatEngine } = useChat({ /* config */ });
+  const [sideContent, setSideContent] = useState(null);
+
+  useEffect(() => {
+    // Listen for specific activity events to render in side panel
+    return chatEngine.eventBus.on(ChatEngineEventType.AGUI_ACTIVITY, (event) => {
+      if (event.activityType === 'dashboard') {
+        setSideContent(event);
+      }
+    });
+  }, [chatEngine]);
+
+  return (
+    <div className="flex">
+      <ChatBot className="flex-1" />
+      {sideContent && (
+        <div className="w-1/3 border-l">
+          <ActivityRenderer activity={sideContent} />
+        </div>
+      )}
+    </div>
+  );
+}
+```
