X Chat Provider

🎯 Skill Positioning

This skill focuses on solving one problem: How to quickly adapt your streaming interface to Antdv Next X's Chat Provider.

Not involved: useXChat usage tutorial (that's another skill).

Table of Contents

• 📦 Technology Stack Overview
• Antdv Next X Ecosystem
• Core Concepts
• 🚀 Quick Start
• Dependency Management
• Built-in Provider
• When to Use Custom Provider
• 📋 Four Steps to Implement Custom Provider
• Step1: Analyze Interface Format
• Step2: Create Provider Class
• Step3: Check Files
• Step4: Use Provider
• 🔧 Common Scenario Adaptation
• 📋 Joint Skill Usage
• Scenario1: Complete AI Conversation Application
• Scenario2: Only Create Provider
• Scenario3: Use Built-in Provider
• ⚠️ Important Reminders
• Mandatory Rule: Prohibit Writing request Method
• ⚡ Quick Checklist
• 🚨 Development Rules
• 🔗 Reference Resources
• 📚 Core Reference Documentation
• 🌐 SDK Official Documentation
• 💻 Example Code

📦 Technology Stack Overview

🏗️ Antdv Next X Ecosystem Architecture

⚠️ Important Reminder: These three packages have different functional positioning, please import required features from the correct package

>

```ts

// ✅ Correct import examples

import { Bubble } from "@antdv-next/x"; // UI component

import { AbstractChatProvider } from "@antdv-next/x-sdk"; // Provider base class

import { XRequest } from "@antdv-next/x-sdk"; // Request tool

```

🔑 Core Concept Analysis

graph LR
    A[Original API Interface] -->|Adapt| B[Chat Provider]
    B -->|Provide Data| C[useXChat Hook]
    C -->|Render| D[Antdv Next X UI]
    E[XRequest] -->|Network Request| B

🚀 Quick Start

📋 Environment Preparation

System Requirements

🛠️ One-click Environment Check

# Auto check and fix version
npm ls @antdv-next/x-sdk
# If version doesn't match, auto prompt:
npm install @antdv-next/x-sdk@latest

📊 Version Compatibility Matrix

🎯 Provider Selection Decision Tree

graph TD
    A[Start] --> B{Use Standard API?}
    B -->|Yes| C[Use Built-in Provider]
    B -->|No| D{Private API?}
    D -->|Yes| E[Custom Provider]
    D -->|No| F{Special Format?}
    F -->|Yes| E
    F -->|No| C

    C --> G[OpenAI/DeepSeek Provider]
    E --> H[Four Steps to Create Custom Provider]

🏭 Built-in Provider Overview

Out-of-the-box Providers

Quick Decision Guide

📋 Four Steps to Implement Custom Provider

🎯 Implementation Path Overview

journey
    title Custom Provider Implementation Path
    section Analysis Phase
      Interface Analysis: 2: User
    section Development Phase
      Create Class: 5: User
      Check Validation: 1: User
    section Integration Phase
      Configure Usage: 1: User

Step1: Analyze Interface Format ⏱️ 2 minutes

📋 Interface Information Collection Table

🔍 Interface Format Template

✅ Request Format Example

// Your actual request format
interface MyAPIRequest {
  query: string; // User question
  context?: string; // Conversation history (optional)
  model?: string; // Model selection (optional)
  stream?: boolean; // Whether streaming (optional)
}

✅ Response Format Example

// Streaming response format
// Actual response: data: {"content": "answer content"}
interface MyAPIResponse {
  content: string; // Answer fragment
  finish_reason?: string; // End marker
}

// End marker: data: [DONE]

Step2: Create Provider Class ⏱️ 5 minutes

🏗️ Code Template (Copy and Use)

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

// ====== 1st modification: Define your interface types ======
interface MyInput {
  query: string;
  context?: string;
  model?: string;
  stream?: boolean;
}

interface MyOutput {
  content: string;
  finish_reason?: string;
}

interface MyMessage {
  content: string;
  role: "user" | "assistant";
  timestamp: number;
}

// ====== 2nd modification: Modify class name ======
export class MyChatProvider extends AbstractChatProvider<
  MyMessage,
  MyInput,
  MyOutput
> {
  // Parameter conversion: convert useXChat parameters to your API parameters
  transformParams(
    requestParams: Partial<MyInput>,
    options: XRequestOptions<MyInput, MyOutput, MyMessage>,
  ): MyInput {
    if (typeof requestParams !== "object") {
      throw new Error("requestParams must be an object");
    }

    return {
      query: requestParams.query || "",
      context: requestParams.context,
      model: "gpt-3.5-turbo", // Adjust according to your API
      stream: true,
      ...(options?.params || {}),
    };
  }

  // Local message: user sent message format
  transformLocalMessage(requestParams: Partial<MyInput>): MyMessage {
    return {
      content: requestParams.query || "",
      role: "user",
      timestamp: Date.now(),
    };
  }

  // ====== 3rd modification: Response data conversion ======
  transformMessage(info: {
    originMessage: MyMessage;
    chunk: MyOutput;
  }): MyMessage {
    const { originMessage, chunk } = info;

    // Handle end marker
    if (!chunk?.content || chunk.content === "[DONE]") {
      return { ...originMessage, status: "success" as const };
    }

    // Accumulate response content
    return {
      ...originMessage,
      content: `${originMessage.content || ""}${chunk.content || ""}`,
      role: "assistant" as const,
      status: "loading" as const,
    };
  }
}

🚨 Development Notes

• ✅ Only change 3 places: interface types, class name, response conversion logic
• ✅ Prohibit implementing request method: Network requests handled by XRequest
• ✅ Maintain type safety: Use TypeScript strict mode

Step3: Check Validation ⏱️ 1 minute

✅ Quick Checklist

🔍 Validation Code

# Run type check
npx tsc --noEmit MyChatProvider.ts

# Expected result: no error output

Step4: Configure Usage ⏱️ 1 minute

🔧 Complete Integration Example

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

// 2. Configure XRequest (handled by x-request skill)
const request = XRequest("https://your-api.com/chat", {
  // Authentication configuration
  headers: {
    Authorization: "Bearer your-token-here",
    "Content-Type": "application/json",
  },

  // Default parameters
  params: {
    model: "gpt-3.5-turbo",
    max_tokens: 1000,
    temperature: 0.7,
  },

  // Streaming configuration
  manual: true,
});

// 3. Create Provider instance
const provider = new MyChatProvider({
  request, // Must pass XRequest instance
});

// 4. Now can be used with useXChat
// This part is handled by use-x-chat skill
export { provider };

🎉 Usage Advantages

• Zero network code: XRequest handles all network details
• Type safety: Complete TypeScript support
• Easy testing: Can mock XRequest for unit testing
• Unified configuration: Authentication, parameters, error handling centralized management

🔧 Common Scenario Adaptation

📚 Scenario Adaptation Guide

📖 Complete Examples: EXAMPLES.md contains complete code for all actual scenarios

📋 Joint Skill Usage Guide

🎯 Skill Relationship Diagram

graph TD
    User[Developer] --> A{Choose Solution}

    A -->|Standard API| B[Built-in Provider]
    A -->|Private API| C[Custom Provider]

    B --> D[use-x-chat]
    C --> E[x-chat-provider]
    E --> D

    D --> F[x-request]
    F --> G[Final Application]

📊 Skill Comparison Table

🎯 Combined Usage Scenarios

🚀 Scenario1: Complete AI Conversation Application

Applicable: Build complete AI conversation product from scratch

sequenceDiagram
    participant Dev as Developer
    participant CP as x-chat-provider
    participant UX as use-x-chat
    participant XR as x-request

    Dev->>CP: 1. Create custom Provider
    CP->>Dev: Return adapted Provider
    Dev->>XR: 2. Configure XRequest parameters
    XR->>Dev: Return configured request
    Dev->>UX: 3. Use Provider to build interface
    UX->>Dev: Complete AI conversation application

Implementation Steps:

1. x-chat-provider → Create custom Provider (four-step implementation) 2. x-request → Configure authentication, parameters, error handling 3. use-x-chat → Build Vue 3 chat interface

🎯 Scenario2: Only Create Provider

Applicable: Provide Provider for other frameworks or teams

graph LR
    A[Private API] -->|Adapt| B[Custom Provider]
    B -->|Export| C[Other Framework Usage]
    B -->|Publish| D[NPM Package]

Core Value:

• 🔧 Decoupling: Provider separated from UI framework
• 📦 Reusability: Can be used by multiple projects
• 🚀 Efficiency: Develop once, use everywhere

⚡ Scenario3: Use Built-in Provider

Applicable: Quick prototype development or standard API calls

graph LR
    A[Standard API] -->|Built-in| B[OpenAI/DeepSeek Provider]
    B -->|Direct Use| C[use-x-chat]
    C -->|Configure| D[x-request]
    D --> E[Quick Launch]

Advantages:

• ⚡ Zero Development: No need for custom Provider
• 🎯 Zero Configuration: Built-in best practices
• 🚀 Ultra-fast Launch: Complete in 5 minutes

⚠️ Important Reminders

🚨 Mandatory Rule: Prohibit Writing request Method!

Mandatory Requirements:

• 🚫 Absolutely prohibit implementing request method in Provider
• ✅ Must use XRequest to handle all network requests
• ✅ Only focus on data conversion logic (transformParams, transformLocalMessage, transformMessage)

❌ Serious Error (Absolutely Prohibited):

// ❌ Serious error: implement request method yourself
class MyProvider extends AbstractChatProvider {
  async request(params: any) {
    // Prohibit writing network request logic!
    const response = await fetch(this.url, { ... });
    return response;
  }
}

✅ Mandatory Requirement (Only Correct Way):

// ✅ Mandatory requirement: use XRequest, prohibit implementing request method
class MyProvider extends AbstractChatProvider {
  // Prohibit implementing request method!
  transformParams(params) {
    /* ... */
  }
  transformLocalMessage(params) {
    /* ... */
  }
  transformMessage(info) {
    /* ... */
  }
}

// Mandatory use of XRequest:
const provider = new MyProvider({
  request: XRequest("https://your-api.com/chat"),
});

⚡ Quick Checklist

Before creating Provider, confirm:

• [ ] Interface documentation obtained
• [ ] Request/response format confirmed
• [ ] Message structure defined
• [ ] Interface availability tested
• [ ] Decided to use XRequest (avoid writing request method yourself!)

After completion:

• [ ] Provider class can be instantiated normally
• [ ] Only implemented three required methods (transformParams, transformLocalMessage, transformMessage)
• [ ] Absolutely prohibit implementing request method (mandatory use XRequest for network requests)
• [ ] Edge cases handled (empty data, error responses)
• [ ] Type check passed (ensure all TypeScript types are correct)
• [ ] Remove unused exports (clean up unused export items)

🚨 Development Rules

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

• EXAMPLES.md - Practical example code

🌐 SDK Official Documentation

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

💻 Example Code

• custom-provider-width-ui.tsx - Complete example of custom Provider

Scenario1: OpenAI Format

OpenAI format uses built-in Provider, use OpenAIProvider:

import { OpenAIProvider } from "@antdv-next/x-sdk";

const provider = new OpenAIProvider({
  request: XRequest("https://api.openai.com/v1/chat/completions"),
});

Scenario2 DeepSeek Format

DeepSeek format uses built-in Provider, use DeepSeekProvider:

import { DeepSeekProvider } from "@antdv-next/x-sdk";

const provider = new DeepSeekProvider({
  request: XRequest("https://api.deepseek.com/v1/chat/completions"),
});

Scenario3: Custom Provider

1. Custom Error Format

transformMessage(info) {
  const { originMessage, chunk } = info || {};
  const data = JSON.parse(chunk.data);
  try {
   if (data.error) {
    return {
      ...originMessage,
      content: data.error.message,
      status: 'error',
    };
  }
  // Other normal processing logic
  } catch (error) {
  return {
      ...originMessage,
      status: 'error',
    };
  }
}

2. Multi-field Response

interface MyOutput {
  content: string;
  metadata?: {
    confidence: number;
    source: string;
  };
}

transformMessage(info) {
  const { originMessage, chunk } = info || {};

  return {
    ...originMessage,
    content: chunk.content,
    metadata: chunk.metadata, // Can extend MyMessage type
  };
}