ai-helper-core 1.0.0

package/src/config.ts

@@ -0,0 +1,75 @@
+import type { AiHelperConfig, AiHelperOptions } from './types'
+
+const DEFAULT_ICON = `data:image/svg+xml,<svg viewBox=%220 0 1051 1024%22 xmlns=%22http://www.w3.org/2000/svg%22><path d=%22M451.99 1005.12a369.77 369.77 0 0 1-369.81-369.81 369.81 369.81 0 0 1 369.81-369.81h147.93a369.81 369.81 0 0 1 369.81 369.81 369.77 369.77 0 0 1-369.81 369.81zM208.96 709.25a197.25 197.25 0 0 0 197.25 197.25h239.48a197.25 197.25 0 0 0 197.25-197.25 197.22 197.22 0 0 0-197.25-197.22h-239.48a197.22 197.22 0 0 0-197.25 197.18z m475.86 98.65a31.99 31.99 0 0 1-31.99-31.99v-133.28a31.99 31.99 0 0 1 31.99-31.99h6.46a31.99 31.99 0 0 1 31.99 31.99v133.28a31.99 31.99 0 0 1-31.99 31.99z m-324.07 0a31.99 31.99 0 0 1-31.99-31.99v-133.28a31.99 31.99 0 0 1 31.99-31.99h6.5a31.99 31.99 0 0 1 31.99 31.99v133.28a31.99 31.99 0 0 1-31.99 31.99z m91.92-624.2a20.73 20.73 0 0 1-13.37-26.17 88 88 0 0 1 87.39-49.59 91.85 91.85 0 0 1 85.09 43.7 20.77 20.77 0 0 1-10.12 27.57 20.81 20.81 0 0 1-27.65-10.16 53.48 53.48 0 0 0-47.32-19.56 51.32 51.32 0 0 0-47.85 20.77 20.77 20.77 0 0 1-19.79 14.43 20.54 20.54 0 0 1-6.42-0.98z m-69.41-78.78a20.77 20.77 0 0 1-2.34-29.27 194.08 194.08 0 0 1 145.74-56.65 193.52 193.52 0 0 1 144.12 54.91 20.81 20.81 0 0 1-1.78 29.38 20.85 20.85 0 0 1-29.38-1.78 154.39 154.39 0 0 0-112.96-40.94 154.5 154.5 0 0 0-114.09 42.11 20.58 20.58 0 0 1-15.82 7.29 20.88 20.88 0 0 1-13.52-5.02z%22 fill=%22%23fff%22 p-id=%223539%22/><path d=%22M0.04 643.54a115.04 115.04 0 0 0 115.04 115.04v-230.11A115.04 115.04 0 0 0 0.04 643.54z%22 fill=%22%23fff%22 opacity=%22.74%22 p-id=%223540%22/><path d=%22M936.87 528.5v230.11a115.04 115.04 0 0 0 115.04-115.04 115.04 115.04 0 0 0-115.04-115.07z%22 fill=%22%23fff%22 opacity=%22.74%22 p-id=%223541%22/></svg>`
+
+const defaultConfig: AiHelperConfig = {
+  apiBase: '/api/ai-chat',
+  branding: {
+    name: '坤土智脑',
+    icon: DEFAULT_ICON,
+    welcomeTitle: '你好，我是坤土智脑',
+    welcomeDesc: '我可以帮你查询数据、分析趋势、生成图表'
+  },
+  theme: 'auto',
+  showQuickQuestions: true,
+  endpoints: {
+    chat: '/chat',
+    history: '/history',
+    prompts: '/prompts'
+  },
+  closeOnRouteChange: true
+}
+
+export class AiHelperConfigManager {
+  private config: AiHelperConfig
+
+  constructor(options?: AiHelperOptions) {
+    this.config = this.buildConfig(options)
+  }
+
+  set(options: AiHelperOptions): void {
+    this.config = this.buildConfig(options)
+  }
+
+  merge(options: AiHelperOptions): void {
+    this.config = this.buildConfig(options)
+  }
+
+  get(): AiHelperConfig {
+    return { ...this.config }
+  }
+
+  getApiUrl(path: string): string {
+    const base = this.config.apiBase.replace(/\/$/, '')
+    const p = path.startsWith('/') ? path : `/${path}`
+    return `${base}${p}`
+  }
+
+  private buildConfig(options?: AiHelperOptions): AiHelperConfig {
+    if (!options) return { ...defaultConfig }
+    return {
+      apiBase: options.apiBase ?? defaultConfig.apiBase,
+      branding: {
+        name: options.branding?.name ?? defaultConfig.branding.name,
+        icon: options.branding?.icon ?? defaultConfig.branding.icon,
+        welcomeTitle: options.branding?.welcomeTitle ?? defaultConfig.branding.welcomeTitle,
+        welcomeDesc: options.branding?.welcomeDesc ?? defaultConfig.branding.welcomeDesc
+      },
+      theme: options.theme ?? defaultConfig.theme,
+      getHeaders: options.getHeaders,
+      showQuickQuestions: options.showQuickQuestions ?? defaultConfig.showQuickQuestions,
+      endpoints: {
+        chat: options.endpoints?.chat ?? defaultConfig.endpoints.chat,
+        history: options.endpoints?.history ?? defaultConfig.endpoints.history,
+        prompts: options.endpoints?.prompts ?? defaultConfig.endpoints.prompts
+      },
+      closeOnRouteChange: options.closeOnRouteChange ?? defaultConfig.closeOnRouteChange,
+      buildChatBody: options.buildChatBody,
+      parseChatChunk: options.parseChatChunk,
+      parseHistoryResponse: options.parseHistoryResponse,
+      parsePromptResponse: options.parsePromptResponse
+    }
+  }
+}
+
+export const configManager = new AiHelperConfigManager()

package/src/index.ts

@@ -0,0 +1,21 @@
+export { AiHelperConfigManager, configManager } from './config'
+export { AiHelperApiClient } from './api/client'
+export { AiHelperStateManager } from './state/manager'
+export { detectTheme, onThemeChange } from './theme/detector'
+export { renderMarkdown } from './markdown/renderer'
+export type {
+  AiHelperOptions,
+  AiHelperConfig,
+  AiHelperBranding,
+  AiHelperEndpoints,
+  ChatParseResult,
+  ChatRequestParams,
+  Message,
+  AiHelperState,
+  PromptRow,
+  PromptListResponse,
+  PromptQueryParams,
+  HistoryMessage,
+  HistoryResponse,
+  HistoryParams
+} from './types'

package/src/markdown/renderer.ts

@@ -0,0 +1,5 @@
+import { marked } from 'marked'
+
+export function renderMarkdown(content: string, theme?: 'light' | 'dark'): string {
+  return marked.parse(content, { breaks: true, gfm: true }) as string
+}

package/src/state/manager.ts

@@ -0,0 +1,115 @@
+import type { AiHelperState, Message } from '../types'
+
+type StateListener = (state: Readonly<AiHelperState>) => void
+
+export class AiHelperStateManager {
+  private state: AiHelperState = {
+    messages: [],
+    isVisible: false,
+    isLoading: false,
+    isInitial: true
+  }
+
+  private listeners = new Map<string, Set<StateListener>>()
+
+  on(event: 'stateChange' | 'messageChange', listener: StateListener): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set())
+    }
+    this.listeners.get(event)!.add(listener)
+    return () => this.off(event, listener)
+  }
+
+  off(event: string, listener: StateListener): void {
+    this.listeners.get(event)?.delete(listener)
+  }
+
+  private emit(event: string): void {
+    const listeners = this.listeners.get(event)
+    if (listeners) {
+      for (const listener of listeners) {
+        listener(this.state)
+      }
+    }
+    // Also emit stateChange for all state mutations
+    if (event !== 'stateChange') {
+      const stateListeners = this.listeners.get('stateChange')
+      if (stateListeners) {
+        for (const listener of stateListeners) {
+          listener(this.state)
+        }
+      }
+    }
+  }
+
+  getState(): Readonly<AiHelperState> {
+    return this.state
+  }
+
+  show(): void {
+    this.state.isVisible = true
+    this.emit('stateChange')
+  }
+
+  hide(): void {
+    this.state.isVisible = false
+    this.emit('stateChange')
+  }
+
+  toggleVisibility(): void {
+    this.state.isVisible = !this.state.isVisible
+    this.emit('stateChange')
+  }
+
+  addUserMessage(content: string): Message {
+    const msg: Message = { id: Date.now(), role: 'user', content }
+    this.state.messages = [...this.state.messages, msg]
+    this.state.isInitial = false
+    this.emit('messageChange')
+    return msg
+  }
+
+  startAssistantMessage(): Message {
+    const msg: Message = { id: Date.now() + 1, role: 'assistant', content: '', isStreaming: true }
+    this.state.messages = [...this.state.messages, msg]
+    this.state.isLoading = true
+    this.emit('messageChange')
+    return msg
+  }
+
+  appendToAssistantMessage(chunk: string): void {
+    const lastMsg = this.state.messages[this.state.messages.length - 1]
+    if (lastMsg && lastMsg.role === 'assistant') {
+      const newContent = lastMsg.content + chunk
+      const updated: Message = { ...lastMsg, content: newContent }
+      this.state.messages = [...this.state.messages.slice(0, -1), updated]
+      this.emit('messageChange')
+    }
+  }
+
+  finishAssistantMessage(): void {
+    const lastMsg = this.state.messages[this.state.messages.length - 1]
+    if (lastMsg && lastMsg.role === 'assistant') {
+      lastMsg.isStreaming = false
+    }
+    this.state.isLoading = false
+    this.emit('messageChange')
+  }
+
+  setMessages(messages: Message[]): void {
+    this.state.messages = messages
+    this.state.isInitial = messages.length === 0
+    this.emit('messageChange')
+  }
+
+  clearMessages(): void {
+    this.state.messages = []
+    this.state.isInitial = true
+    this.emit('messageChange')
+  }
+
+  setLoading(loading: boolean): void {
+    this.state.isLoading = loading
+    this.emit('stateChange')
+  }
+}

package/src/theme/detector.ts

@@ -0,0 +1,25 @@
+export function detectTheme(): 'light' | 'dark' {
+  if (typeof document === 'undefined') return 'light'
+  return document.documentElement.classList.contains('dark') ? 'dark' : 'light'
+}
+
+export function onThemeChange(callback: (theme: 'light' | 'dark') => void): () => void {
+  if (typeof document === 'undefined' || typeof window === 'undefined') {
+    return () => {}
+  }
+
+  const observer = new MutationObserver(() => {
+    callback(detectTheme())
+  })
+
+  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
+
+  const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+  const mediaHandler = () => callback(detectTheme())
+  mediaQuery.addEventListener('change', mediaHandler)
+
+  return () => {
+    observer.disconnect()
+    mediaQuery.removeEventListener('change', mediaHandler)
+  }
+}

package/src/types.ts

@@ -0,0 +1,136 @@
+// 品牌配置
+export interface AiHelperBranding {
+  name?: string
+  icon?: string
+  welcomeTitle?: string
+  welcomeDesc?: string
+}
+
+// API 端点配置
+export interface AiHelperEndpoints {
+  chat?: string
+  history?: string
+  prompts?: string
+}
+
+/**
+ * 流式聊天响应解析结果
+ * content: 从当前 chunk 中提取的文本（追加到 assistant 消息）
+ * done:    是否已结束（设为 true 时终止流，不再调用 onChunk）
+ */
+export interface ChatParseResult {
+  content: string
+  done?: boolean
+}
+
+/**
+ * 聊天请求构建参数
+ */
+export interface ChatRequestParams {
+  message: string
+}
+
+// 初始化选项
+export interface AiHelperOptions {
+  apiBase?: string
+  branding?: AiHelperBranding
+  theme?: 'light' | 'dark' | 'auto'
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>
+  showQuickQuestions?: boolean
+  endpoints?: AiHelperEndpoints
+  closeOnRouteChange?: boolean
+  /**
+   * 自定义聊天请求体构建函数
+   * 返回将作为 POST body 发送的字符串
+   * 默认: JSON.stringify({ message })
+   */
+  buildChatBody?: (params: ChatRequestParams) => string
+  /**
+   * 自定义流式响应解析函数
+   * 每个 SSE chunk（或 NDJSON 行）调用一次
+   * 返回 { content, done }
+   * 默认: 解析为 { content: string } 格式
+   */
+  parseChatChunk?: (rawChunk: string) => ChatParseResult
+  /**
+   * 自定义历史响应解析函数
+   * 接收 fetch().json() 的原始结果，返回 HistoryResponse
+   * 默认: 期望原始结果为 { messages: [{role, content}], total }
+   */
+  parseHistoryResponse?: (raw: unknown) => HistoryResponse
+  /**
+   * 自定义提示词响应解析函数
+   * 接收 fetch().json() 的原始结果，返回 PromptListResponse
+   * 默认: 期望原始结果为 { items: [{id, name, content}], total }
+   */
+  parsePromptResponse?: (raw: unknown) => PromptListResponse
+}
+
+// 解析后的完整配置
+export interface AiHelperConfig {
+  apiBase: string
+  branding: Required<AiHelperBranding>
+  theme: 'light' | 'dark' | 'auto'
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>
+  showQuickQuestions: boolean
+  endpoints: Required<AiHelperEndpoints>
+  closeOnRouteChange: boolean
+  buildChatBody?: (params: ChatRequestParams) => string
+  parseChatChunk?: (rawChunk: string) => ChatParseResult
+  parseHistoryResponse?: (raw: unknown) => HistoryResponse
+  parsePromptResponse?: (raw: unknown) => PromptListResponse
+}
+
+// 聊天消息
+export interface Message {
+  id: number
+  role: 'user' | 'assistant'
+  content: string
+  isStreaming?: boolean
+}
+
+// 快捷问题
+export interface PromptRow {
+  id: number
+  name: string
+  content: string
+  description?: string
+  created_at: string
+  updated_at: string
+}
+
+export interface PromptListResponse {
+  items: PromptRow[]
+  total: number
+}
+
+export interface PromptQueryParams {
+  keyword?: string
+  limit?: number
+  offset?: number
+}
+
+// 历史记录
+export interface HistoryMessage {
+  role: 'user' | 'assistant'
+  content: string
+  timestamp: string
+}
+
+export interface HistoryResponse {
+  messages: HistoryMessage[]
+  total: number
+}
+
+export interface HistoryParams {
+  limit?: number
+  offset?: number
+}
+
+// 内部状态
+export interface AiHelperState {
+  messages: Message[]
+  isVisible: boolean
+  isLoading: boolean
+  isInitial: boolean
+}