[RFC] X SDK

[hylin]

Summary

X SDK提供可以独立使用的辅助工具，帮忙开发者在构建AI应用时，更加方便的和大模型进行数据请求交互，以及处理UI组件渲染使用的数据。

Motivation

主要进行工具集能力增强：

• 优化1.0中使用时容易混淆的概念和逻辑
• 增加请求工具的能力
• 增加会话管理工具

Detailed Design

API

UI Helper

useXChat
对话数据管理，2.0移除了useXAgent，避免概念混淆，直接传入XRequest进行数据请求的处理。原本useXChat上的部分请求数据处理也统一在XRequest进行配置。

interface XChatConfig<
  AgentMessage extends SimpleType = string,
  BubbleMessage extends SimpleType = AgentMessage,
  Input = AgentMessage,
  Output = AgentMessage,
> {
  request: XRequestClass;
  defaultMessages?: DefaultMessageInfo<AgentMessage>[];
  parser?: (message: AgentMessage) => BubbleMessage | BubbleMessage[];
  requestPlaceholder?: AgentMessage | RequestPlaceholderFn<AgentMessage>;
  requestFallback?: AgentMessage | RequestFallbackFn<AgentMessage>;
  transformMessage?: TransformMessageFn<AgentMessage, Output>;
  conversationKey?: string;
}
function useXChat(config: XChatConfig): {
    onRequest: (requestParams: AgentMessage | RequestParams) => void;
    messages: AgentMessages[];
    parsedMessages: ParsedMessages[];
    setMessages: (messages: { message, status }[]) => void;
    setMessage: (id: string, message: AgentMessage) => void;
    reload: async (id: string) => void;
    conversationKey: string;
}

useXConversations
新增多会话数据管理，可以和useXChat结合,Conversation和Chat数据通过conversationKey关联

// ConversationUI组件类型
interface ConversationData {
    key: string;
    label: string;
    [prop: string]: any;
}

interface XConversationConfig {
    defaultConversations?: ConversationData[];
}

function useXConversations(config: XConversationConfig): {
    conversations: ConversationData[];
    add: (conversation: ConversationData) => boolean;
    remove: (string) => boolean;
    set: (key: string, config: Omit<ConversationData, 'key'>) => boolean;
}

Tools

XStream
保持1.0版本基本不变，做Stream转换用

interface XStreamOptions<Output> {
  readableStream: ReadableStream<Uint8Array>;
  transformStream?: TransformStream<string, Output>;
}

type XReadableStream<R = SSEOutput> = ReadableStream<R> & AsyncGenerator<R>;

function XStream<Output = SSEOutput>(options: XStreamOptions<Output>);

XRequest
定义为请求工具，不带llm属性，如果需要和llm(OpenAI Compatible)交互，使用XModel
新增能力：

• 自定义请求Headers
• 全局配置能力
• reload能力
• 超时配置
• 中间件

interface XRequestCallbacks<Output> {
  onSuccess: (chunks: Output[]) => void;
  onError: (error: Error) => void;
  onUpdate: (chunk: Output) => void;
}

interface XRequestOptions<Input, Output> {
  dangerouslyApiKey?: string;
  callbacks?: XRequestCallbacks<Output>;
  params?: Input;
  headers?: Record<string, string>;
  timeout?: number;
  streamTimeout?: number;
  fetch?: XFetchOptions['fetch'];
  middlewares?: {
    onRequest(params: Input)?: Input | boolean;
    onResponse(response: Response)?: Response | boolean;
  };
  transformStream?: XStreamOptions<Output>['transformStream'];
}

type XRequestGlobalOptions = Pick<XRequestOptions, 'headers' | 'timeout' | 'streamTimeout' | 'middlewares' | 'fetch' | 'transformStream'>;

function XRequest<Input = AnyObject, Output = SSEOutput>(baseURL: string, options: XRequestOptions<Input, Output>): {
    abort(): void;
};

// 设置全局配置
function setXRequestGlobalOptions(options: XRequestGlobalOptions): void;

XModel
基于XRequest封装的OpenAI Compatible的大模型数据交互工具

type XModelMessageContent = string | AnyObject;

interface XModelMessage extends AnyObject {
  role?: string;
  content?: XModelMessageContent;
}

interface XModelTool {
    type: 'function';
    function: {
        name: string;
        description?: string;
        parameters?: {};
        strict?: boolean;
    }
}

interface XModelParams extends AnyObject {
    model: string;
    messages: XModelMessage[];
    
    frequency_penalty?: number;
    logit_bias?: AnyObject;
    logprobs?: boolean;
    max_completion_tokens?: number;
    metadata?: AnyObject;
    modalities?: string[];
    n?: number;
    parallel_tool_calls?: boolean;
    prediction?: {
        content: string;
        type: string;
    };
    presence_penalty?: number;
    reasoning_effort?: string;
    response_format?: 'text' | {
        type: 'json_object';
    } | {
        type: 'json_schema';
        json_schema: {
            name: string;
            description?: string;
            schema?: {};
            strict?: boolean;
        }
    };
    seed?: number;
    service_tier?: string;
    stop?: string | string[];
    store?: boolean;
    stream?: boolean;
    stream_options?: {
        include_usage?: boolean;
    };
    temperature?: number;
    tool_choice?: string | {
        type: 'function';
        function: {
            name: string;
        }
    };
    tools?: XModelTool[];
    top_logprobs?: number;
    top_p?: number;
    user?: string;
    web_search_options?: {
        search_context_size?: string;
        user_location?: {
            type: 'approximate';
            approximate: {
                city?: string;
                country?: string;
                region?: string;
                timezone?: string;
            }
        }
    };
}

function XModel<Input = AnyObject, Output = SSEOutput>(baseURL: string, params: XModelParams, options?: XRequestOptions): {
    abort(): void;
};

XMCPClient
MCP客户端类，tools获取部分?

interface XMCPTool {
  name: string;
  description?: string;
  inputSchema: {
    type: "object",
    properties: {}
  },
  annotations?: {
    title?: string;
    readOnlyHint?: boolean;
    destructiveHint?: boolean;
    idempotentHint?: boolean;
    openWorldHint?: boolean;
  }
}
interface XMCPClientConfig {
    baseURL: string;
}
interface XMCPClientClass {
    constructor(config: MCPClientConfig): MCPClient;
    tools: () => XMCPTool[];
}
function XMCPClient(options: XMCPClientOptions): XMCPClientClass;

[kimteayon]

good

[kimteayon]

useXConversations 处理很可以 #209
message也可以进行单条的修改这个能力需要增加

[hylin]

可以，我加上

[kimteayon]

XMCPClientConfig 只支持 request应该不够用 如果是node runtime可以读文件配置

[kimteayon]

reload 这块可能会导致message变成数组