x-chat-provider

name	x-chat-provider
version	0.0.1
description	Focus on implementing custom Chat Provider, helping to adapt any streaming interface to Antdv Next X standard format

🎯 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

Layer	Package Name	Core Purpose	Typical Usage Scenarios
UI Layer	@antdv-next/x	Vue 3 UI component library	Build chat interfaces, bubbles, input boxes
Logic Layer	@antdv-next/x-sdk	Development toolkit	Data flow management, Provider, Hook
Render Layer	@antdv-next/x-markdown	Markdown renderer	Content display, code highlighting

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

// ✅ 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

Concept	Role Positioning	Core Responsibility	Usage Scenario
Chat Provider	🔄 Data Adapter	Convert any interface format to Antdv Next X standard format	Private API adaptation, format conversion
useXChat	🧩 Vue 3 Composable	Manage conversation state, message flow, request control	Build AI conversation interface
XRequest	🌐 Request Tool	Handle all network communication, authentication, error handling	Unified request management

🚀 Quick Start

📋 Environment Preparation

System Requirements

Package	Version Requirement	Auto Install	Purpose
@antdv-next/x-sdk	≥0.0.1	✅	Core SDK, includes Provider and Hook
@antdv-next/x	Latest version	✅	UI component library, build chat interface

🛠️ 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

SDK Version	Supported Features	Compatibility
≥0.0.1	Full Provider functionality	✅ Recommended

🎯 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

Provider Type	Applicable Scenario	Usage Method
OpenAI Provider	Standard OpenAI API	Direct import use
DeepSeek Provider	Standard DeepSeek API	Direct import use

Quick Decision Guide

Scenario	Recommended Solution	Example
Call official OpenAI	Built-in OpenAI Provider	new OpenAIProvider()
Call official DeepSeek	Built-in DeepSeek Provider	new DeepSeekProvider()
Company internal API	Custom Provider	See four-step implementation
Third-party non-standard API	Custom Provider	See four-step implementation

📋 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

Information Type	Example Value	Your Interface
Interface URL	https://your-api.com/chat	_____________
Request Method	POST	_____________
Request Format	JSON	_____________
Response Format	Server-Sent Events	_____________
Authentication Method	Bearer Token	_____________

🔍 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

Check Item	Status	Description
Correct class name	⏳	MyChatProvider → Your class name
Type matching	⏳	Interface types match actual API
Complete methods	⏳	All 3 methods implemented
No request method	⏳	Confirm no request method implemented
Type check passed	⏳	tsc --noEmit no errors

🔍 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

Scenario Type	Difficulty	Example Link	Description
Standard OpenAI	🟢 Simple	Built-in Provider Example	Direct use of built-in Provider
Standard DeepSeek	🟢 Simple	Built-in Provider Example	Direct use of built-in Provider
Private API	🟡 Medium	Custom Provider Details	Need four-step implementation

📖 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

Skill Role	Skill Name	Prerequisites	Core Responsibility	Usage Scenario
🏗️ Creator	x-chat-provider	None	Create custom Provider	Adapt private/non-standard APIs
🧩 User	use-x-chat	Needs Provider	Build AI conversation interface	Vue 3 component development
🔧 Configurer	x-request	None	Configure request parameters authentication	Unified network request management

🎯 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