use-x-chat

name	use-x-chat
version	0.0.1
description	Focus on explaining how to use the useXChat Hook, including custom Provider integration, message management, error handling, etc.

🎯 Skill Positioning

Core Positioning: Use the useXChat Hook to build professional AI conversation applications Prerequisites: Already have a custom Chat Provider (refer to x-chat-provider skill)

Table of Contents

• 🚀 Quick Start
  • Dependency Management
  • Three-step Integration
• 🧩 Core Concepts
  • Technology Stack Architecture
  • Data Model
• 🔧 Core Function Details
  • Message Management
  • Request Control
  • Error Handling
  • Complete Example Project
• 📋 Prerequisites and Dependencies
• 🚨 Development Rules
• 🔗 Reference Resources
  • 📚 Core Reference Documentation
  • 🌐 SDK Official Documentation
  • 💻 Example Code

🚀 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

🔗 Reference Resources

📚 Core Reference Documentation

• API.md - Complete API reference documentation
• EXAMPLES.md - All practical example code

🌐 SDK Official Documentation

• useXChat Official Documentation
• XRequest Official Documentation
• Chat Provider Official Documentation

💻 Example Code

• useXChat demos - Complete example demos