🚀 Quick Start
- Dependency Management
- Three-step Integration
🧩 Core Concepts
- Technology Stack Architecture
- Data Model
🔧 Core Function Details
📋 Prerequisites and Dependencies
🚨 Development Rules
🔗 Reference Resources

🚀 Quick Start

1. Dependency Management

🎯 Automatic Dependency Handling

📋 System Requirements

@antdv-next/x-sdk: latest version (automatically installed)
@antdv-next/x: latest version (UI components, automatically installed)

⚠️ Version Issue Auto-fix

If version mismatch is detected, the skill will automatically:

✅ Prompt current version status
✅ Provide fix suggestions
✅ Use relative paths to ensure compatibility

🎯 Built-in Version Check

The use-x-chat skill has built-in version checking functionality, automatically checking version compatibility on startup:

🔍 Auto-check Function The skill will automatically check if the @antdv-next/x-sdk version meets requirements on startup:

📋 Check Contents:

✅ Currently installed version
✅ Whether it meets minimum requirements
✅ Automatically provide fix suggestions
✅ Friendly error prompts

🛠️ Version Issue Fix If version mismatch is detected, the skill will provide specific fix commands:

# Auto-prompted fix commands
npm install @antdv-next/x-sdk@latest

2. Three-step Integration

Step 1: Prepare Provider

This part is handled by the x-chat-provider skill

import { MyChatProvider } from "./MyChatProvider";
import { XRequest } from "@antdv-next/x-sdk";

// Recommended to use XRequest as the default request method
const provider = new MyChatProvider({
  // Default use XRequest, no need for custom fetch
  request: XRequest("https://your-api.com/chat"),
  // When requestPlaceholder is set, placeholder message will be displayed before request starts
  requestPlaceholder: {
    content: "Thinking...",
    role: "assistant",
    timestamp: Date.now(),
  },
  // When requestFallback is set, fallback message will be displayed when request fails
  requestFallback: (_, { error, errorInfo, messageInfo }) => {
    if (error.name === "AbortError") {
      return {
        content: messageInfo?.message?.content || "Reply cancelled",
        role: "assistant" as const,
        timestamp: Date.now(),
      };
    }
    return {
      content:
        errorInfo?.error?.message || "Network error, please try again later",
      role: "assistant" as const,
      timestamp: Date.now(),
    };
  },
});

Step 2: Basic Usage

import { defineComponent } from "vue";
import { useXChat } from "@antdv-next/x-sdk";

const ChatComponent = defineComponent(() => {
  const { messages, onRequest, isRequesting } = useXChat({ provider });

  return () => (
    <div>
      {messages.value.map(msg => (
        <div key={msg.id}>
          {msg.message.role}: {msg.message.content}
        </div>
      ))}
      <button onClick={() => onRequest({ query: "Hello" })}>Send</button>
    </div>
  );
});

Step 3: UI Integration

import { defineComponent } from "vue";
import { Bubble, Sender } from "@antdv-next/x";
import { useXChat } from "@antdv-next/x-sdk";

const ChatUI = defineComponent(() => {
  const { messages, onRequest, isRequesting, abort } = useXChat({ provider });

  return () => (
    <div style={{ height: "600px" }}>
      <Bubble.List items={messages.value} />
      <Sender
        loading={isRequesting.value}
        onSubmit={content => onRequest({ query: content })}
        onCancel={abort}
      />
    </div>
  );
});

🧩 Core Concepts

Technology Stack Architecture

graph TD
    A[useXChat Hook] --> B[Chat Provider]
    B --> C[XRequest]
    A --> D[Antdv Next X UI]
    D --> E[Bubble Component]
    D --> F[Sender Component]

Data Model

⚠️ Important Reminder: messages type is Ref<MessageInfo<MessageType>[]>, not direct MessageType. Access via messages.value.

interface MessageInfo<Message> {
  id: number | string; // Message unique identifier
  message: Message; // Actual message content
  status: MessageStatus; // Sending status
  extraInfo?: AnyObject; // Extended information
}

// Message status enum
type MessageStatus =
  | "local"
  | "loading"
  | "updating"
  | "success"
  | "error"
  | "abort";

🔧 Core Function Details

💡 Tip: API may update with versions, it is recommended to check official documentation for the latest information

Core functionality reference content CORE.md

📋 Prerequisites and Dependencies

⚠️ Important Dependencies

use-x-chat must depend on one of the following skills:

Dependency Type	Skill	Description	Required
Core Dependency	x-chat-provider	Provides custom Provider instance, default uses XRequest, must be used with use-x-chat	Required
Or	Built-in Provider	OpenAI/DeepSeek and other built-in Providers, default uses XRequest	Required
Recommended Dependency	x-request	Configure request parameters and authentication, as the default request method	Recommended

🎯 Usage Scenario Comparison Table

Usage Scenario	Required Skill Combination	Usage Order
Private API Adaptation	x-chat-provider → use-x-chat	Create Provider first, then use
Standard API Usage	use-x-chat (built-in Provider)	Direct use
Authentication Configuration Needed	x-request → use-x-chat	Configure request first, then use
Complete Customization	x-chat-provider → x-request → use-x-chat	Complete workflow

🚨 Development Rules

Before using use-x-chat, must confirm:

Has Provider source (choose one of the following):
- Has created custom Provider with x-chat-provider
- Decided to use built-in Provider (OpenAI/DeepSeek)
@antdv-next/x-sdk is installed
Understand MessageInfo data structure
UI components are ready

Test Case Rules

If the user does not explicitly need test cases, do not add test files
Only create test cases when the user explicitly requests them

Code Quality Rules

After completion, must check types: Run tsc --noEmit to ensure no type errors
Keep code clean: Remove all unused variables and imports

use-x-chat

🎯 Skill Positioning

Table of Contents

More from antdv-next/x

x-markdown

x-request

x-chat-provider