XEIII Agent SDK

XEIII Agent SDK 是一个用于构建智能应用的 React 组件库和开发工具包。它提供了一套完整的工具来帮助开发者快速构建基于 LLM 的智能应用。

安装

npm install @xeiii/agent-sdk

核心功能

• 🤖 智能对话：内置聊天组件和状态管理
• 📚 知识库管理：文档上传、检索和管理
• 🔐 用户认证：集成 Supabase 认证系统
• 💾 数据存储：集成 Supabase 数据库和存储
• 🎨 UI 组件：一套美观的 React 组件

快速开始

import { ChatPanel, useChat } from '@xeiii/agent-sdk';

function App() {
  const handleMessage = async (message: string) => {
    // 处理用户消息
  };

  return (
    <ChatPanel 
      onSend={handleMessage}
      placeholder="输入消息..."
    />
  );
}

组件

ChatPanel

聊天面板组件，用于展示对话界面。

import { ChatPanel } from '@xeiii/agent-sdk';

<ChatPanel
  onSend={(message: string) => void}  // 发送消息回调
  placeholder?: string                 // 输入框占位文本
  className?: string                  // 自定义样式类
/>

ChatMessage

单条消息组件，用于展示对话消息。

import { ChatMessage } from '@xeiii/agent-sdk';

<ChatMessage
  message={{
    id: string;                      // 消息 ID
    role: 'user' | 'assistant';      // 消息角色
    content: string;                 // 消息内容
    timestamp: number;               // 时间戳
    status?: 'loading' | 'success' | 'error';  // 消息状态
    metadata?: {                     // 元数据
      type?: string;
      section?: {
        id: string;
        title: string;
      };
    };
  }}
/>

PageLayout

页面布局组件。

import { PageLayout } from '@xeiii/agent-sdk';

<PageLayout>
  {children}
</PageLayout>

LoadingSpinner

加载状态组件。

import { LoadingSpinner } from '@xeiii/agent-sdk';

<LoadingSpinner />

ErrorMessage

错误提示组件。

import { ErrorMessage } from '@xeiii/agent-sdk';

<ErrorMessage message="错误信息" />

Hooks

useChat

聊天状态管理 Hook。

import { useChat } from '@xeiii/agent-sdk';

const {
  messages,              // 消息列表
  isTyping,             // 是否正在输入
  addMessage,           // 添加消息
  updateMessage,        // 更新消息
  deleteMessage,        // 删除消息
  clearMessages,        // 清空消息
  startTyping,          // 开始输入
  endTyping            // 结束输入
} = useChat();

useAuth

用户认证 Hook。

import { useAuth } from '@xeiii/agent-sdk';

const {
  user,                 // 当前用户
  loading,             // 加载状态
  error                // 错误信息
} = useAuth();

useKnowledge

知识库管理 Hook。

import { useKnowledge } from '@xeiii/agent-sdk';

const {
  folders,             // 知识库文件夹列表
  loading,            // 加载状态
  error               // 错误信息
} = useKnowledge();

useDocuments

文档管理 Hook。

import { useDocuments } from '@xeiii/agent-sdk';

const {
  documents,           // 文档列表
  loading,            // 加载状态
  error,              // 错误信息
  uploadDocument,     // 上传文档
  deleteDocument      // 删除文档
} = useDocuments(folderId);

useMCP

消息通信协议 Hook。

import { useMCP } from '@xeiii/agent-sdk';

const {
  status,             // 连接状态
  error,              // 错误信息
  send,               // 发送消息
  disconnect          // 断开连接
} = useMCP(url, options);

平台服务

创建平台实例

import { createPlatform } from '@xeiii/agent-sdk';

const platform = createPlatform(
  'SUPABASE_URL',
  'SUPABASE_ANON_KEY'
);

认证服务

// 获取当前用户
const user = await platform.auth.getUser();

// 获取用户配置
const config = await platform.auth.getUserConfig();

知识库服务

// 获取知识库列表
const folders = await platform.knowledge.getFolders();

// 获取文档列表
const documents = await platform.knowledge.getDocuments(folderId);

// 上传文档
const doc = await platform.knowledge.uploadDocument(folderId, file);

// 删除文档
await platform.knowledge.deleteDocument(docId);

存储服务

// 上传文件
const path = await platform.storage.upload(file, 'path/to/file');

// 下载文件
const blob = await platform.storage.download('path/to/file');

// 删除文件
await platform.storage.delete('path/to/file');

数据库服务

// 查询数据
const results = await platform.db.query('SELECT * FROM table');

// 获取单条数据
const item = await platform.db.get('SELECT * FROM table WHERE id = ?', [id]);

// 插入数据
const id = await platform.db.insert('table', { field: 'value' });

// 更新数据
await platform.db.update('table', { field: 'new value' }, { id: 1 });

// 删除数据
await platform.db.delete('table', { id: 1 });

类型定义

User

interface User {
  id: string;
  email: string;
  name: string;
  avatar_url?: string;
  role?: 'admin' | 'user';
  created_at?: string;
  theme?: 'light' | 'dark' | 'system';
  primary_color?: string;
  language?: string;
  knowledge_apikey?: string;
}

Folder

interface Folder {
  id: string;
  name: string;
  description: string;
  document_count: number;
  word_count: number;
  created_at: number;
  updated_at: number;
  app_count: number;
  tags: string[];
  doc_form: string;
}

Document

interface Document {
  id: string;
  title: string;
  file_name: string;
  file_type: string;
  file_size: number;
  file_url: string;
  created_at: string;
  status: string;
  word_count?: number;
  segment_count?: number;
  tokens?: number;
  pages?: number;
  enabled?: boolean;
  created_by?: string;
  created_from?: string;
}

示例

创建聊天应用

import React, { useState } from 'react';
import { ChatPanel, useChat } from '@xeiii/agent-sdk';

function ChatApp() {
  const [loading, setLoading] = useState(false);
  const { addMessage, updateMessage } = useChat();

  const handleMessage = async (message: string) => {
    try {
      setLoading(true);
      
      // 添加用户消息
      addMessage({
        role: 'user',
        content: message
      });

      // 添加系统响应
      const responseId = Math.random().toString(36).slice(2);
      addMessage({
        id: responseId,
        role: 'assistant',
        content: '正在处理...',
        status: 'loading'
      });

      // 调用 API 处理消息
      const response = await fetch('/api/chat', {
        method: 'POST',
        body: JSON.stringify({ message })
      });
      
      const result = await response.json();

      // 更新响应消息
      updateMessage(responseId, {
        content: result.response,
        status: 'success'
      });
    } catch (error) {
      console.error('Error:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="h-screen">
      <ChatPanel
        onSend={handleMessage}
        placeholder="输入消息..."
      />
    </div>
  );
}

知识库管理

import React from 'react';
import { useKnowledge, useDocuments } from '@xeiii/agent-sdk';

function KnowledgeManager() {
  const { folders, loading: foldersLoading } = useKnowledge();
  const [selectedFolder, setSelectedFolder] = useState<string | null>(null);
  
  const {
    documents,
    loading: documentsLoading,
    uploadDocument,
    deleteDocument
  } = useDocuments(selectedFolder || '');

  const handleFileUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (file && selectedFolder) {
      await uploadDocument(file);
    }
  };

  return (
    <div className="p-4">
      {/* 文件夹列表 */}
      <div className="mb-4">
        {folders.map(folder => (
          <button
            key={folder.id}
            onClick={() => setSelectedFolder(folder.id)}
            className="block w-full text-left p-2 hover:bg-gray-100"
          >
            {folder.name}
          </button>
        ))}
      </div>

      {/* 文档列表 */}
      {selectedFolder && (
        <div>
          <input
            type="file"
            onChange={handleFileUpload}
            className="mb-4"
          />
          
          <div className="space-y-2">
            {documents.map(doc => (
              <div
                key={doc.id}
                className="flex items-center justify-between p-2 border rounded"
              >
                <span>{doc.file_name}</span>
                <button
                  onClick={() => deleteDocument(doc.id)}
                  className="text-red-500"
                >
                  删除
                </button>
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT