visualknowledge 0.1.0 → 0.1.2

package/frontend/src/components/widgets/WidgetContainer.jsx

@@ -0,0 +1,32 @@
+/**
+ * WidgetContainer - 通用 Widget 外壳
+ *
+ * 渲染 header（badge + typeLabel + zoom 按钮）+ body（children）
+ */
+
+import { html } from 'htm/react';
+
+export function WidgetContainer({ badge, typeLabel, status = 'done', children, onZoom }) {
+  const uid = `wc_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+
+  return html`
+    <div class="widget-container">
+      <div class="widget-header">
+        <div class="left">
+          <span class="badge">${badge}</span>
+          <span class="widget-type">${typeLabel}</span>
+        </div>
+        ${onZoom ? html`
+          <button class="btn" id="zoom-${uid}" onClick=${onZoom}>⛶ 放大</button>
+        ` : ''}
+      </div>
+      <div class="widget-body">
+        ${status === 'loading' ? html`
+          <div class="widget-loading">
+            <div class="spinner"></div> 渲染中...
+          </div>
+        ` : children}
+      </div>
+    </div>
+  `;
+}

package/frontend/src/context/AppContext.jsx

@@ -0,0 +1,151 @@
+/**
+ * AppContext - 全局状态管理
+ *
+ * 基于 React Context + useReducer 的单一数据源。
+ * 管理对话消息、流式状态、主题、模型选择、全屏 Widget。
+ */
+
+import { createContext, useContext, useReducer } from 'react';
+
+// ====== Action Types ======
+
+export const ActionTypes = {
+  ADD_USER_MESSAGE: 'ADD_USER_MESSAGE',
+  START_ASSISTANT_MESSAGE: 'START_ASSISTANT_MESSAGE',
+  APPEND_TO_SEGMENT: 'APPEND_TO_SEGMENT',
+  FINALIZE_SEGMENTS: 'FINALIZE_SEGMENTS',
+  SET_STREAMING_ERROR: 'SET_STREAMING_ERROR',
+  SET_MODELS: 'SET_MODELS',
+  SET_THEME: 'SET_THEME',
+  SET_FULLSCREEN_WIDGET: 'SET_FULLSCREEN_WIDGET',
+};
+
+// ====== Initial State ======
+
+const initialState = {
+  messages: [],
+  isStreaming: false,
+  currentModel: '',
+  availableModels: [],
+  theme: (() => {
+    try { return localStorage.getItem('claude-chat-theme') || 'dark'; }
+    catch { return 'dark'; }
+  })(),
+  fullscreenWidget: null,
+};
+
+// ====== Reducer ======
+
+function appReducer(state, action) {
+  switch (action.type) {
+
+    case ActionTypes.ADD_USER_MESSAGE:
+      return {
+        ...state,
+        messages: [...state.messages, {
+          id: `msg_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`,
+          role: 'user',
+          content: action.content,
+          segments: [{ id: `seg_txt_user_${Date.now()}`, type: 'text', content: action.content, renderedContent: null, renderStatus: 'done', renderError: null }],
+          status: 'complete',
+          error: null,
+          timestamp: Date.now(),
+        }],
+      };
+
+    case ActionTypes.START_ASSISTANT_MESSAGE:
+      return {
+        ...state,
+        isStreaming: true,
+        messages: [...state.messages, {
+          id: action.messageId,
+          role: 'assistant',
+          content: '',
+          segments: [],
+          status: 'streaming',
+          error: null,
+          timestamp: Date.now(),
+        }],
+      };
+
+    case ActionTypes.FINALIZE_SEGMENTS:
+      return {
+        ...state,
+        messages: state.messages.map(msg =>
+          msg.id === action.messageId
+            ? { ...msg, segments: action.segments, content: _extractTextFromSegments(action.segments) }
+            : msg
+        ),
+      };
+
+    case ActionTypes.SET_STREAMING_ERROR:
+      return {
+        ...state,
+        isStreaming: false,
+        messages: state.messages.map(msg =>
+          msg.id === action.messageId
+            ? { ...msg, status: 'error', error: action.error }
+            : msg
+        ),
+      };
+
+    // 流结束，标记消息完成
+    case 'COMPLETE_STREAM':
+      return {
+        ...state,
+        isStreaming: false,
+        messages: state.messages.map(msg =>
+          msg.id === action.messageId && msg.status === 'streaming'
+            ? { ...msg, status: 'complete' }
+            : msg
+        ),
+      };
+
+    case ActionTypes.SET_MODELS:
+      return {
+        ...state,
+        availableModels: action.models,
+        currentModel: action.current || state.currentModel,
+      };
+
+    case ActionTypes.SET_THEME:
+      return { ...state, theme: action.theme };
+
+    case ActionTypes.SET_FULLSCREEN_WIDGET:
+      return { ...state, fullscreenWidget: action.widget };
+
+    default:
+      return state;
+  }
+}
+
+// 从 segments 中提取纯文本（用于 conversationHistory）
+function _extractTextFromSegments(segments) {
+  return segments
+    .filter(s => s.type === 'text')
+    .map(s => s.content)
+    .join('');
+}
+
+// ====== Context ======
+
+export const AppContext = createContext(null);
+
+export function AppProvider({ children }) {
+  const [state, dispatch] = useReducer(appReducer, initialState);
+
+  return (
+    AppContext.Provider value={{ state, dispatch }}>
+      {children}
+    </AppContext.Provider>
+  );
+}
+
+/**
+ * 便捷 Hook：获取全局 state 和 dispatch
+ */
+export function useAppState() {
+  const ctx = useContext(AppContext);
+  if (!ctx) throw new Error('useAppState must be used within AppProvider');
+  return ctx;
+}

package/frontend/src/hooks/useChat.js

@@ -0,0 +1,160 @@
+/**
+ * useChat - 核心对话 Hook
+ *
+ * 封装 SSE 流式连接和 StreamProcessor 协调逻辑。
+ * 管理消息发送、流式接收、状态更新全生命周期。
+ *
+ * 返回: { messages, isStreaming, sendMessage }
+ */
+
+import { useState, useCallback, useRef } from 'react';
+import { useAppState, ActionTypes } from '../context/AppContext.jsx';
+import { StreamProcessor } from '../lib/streamProcessor.js';
+
+export function useChat() {
+  const { state, dispatch } = useAppState();
+  const processorRef = useRef(null);
+  const [localMessages, setLocalMessages] = useState([]);
+  const [localStreaming, setLocalStreaming] = useState(false);
+
+  /**
+   * 发送消息并启动流式接收
+   */
+  const sendMessage = useCallback(async (text) => {
+    if (!text.trim() || localStreaming) return;
+
+    // 1. 添加用户消息
+    const userMsg = {
+      id: `msg_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`,
+      role: 'user',
+      content: text,
+      segments: [{ id: `seg_txt_user_${Date.now()}`, type: 'text', content: text, renderedContent: null, renderStatus: 'done', renderError: null }],
+      status: 'complete',
+      error: null,
+      timestamp: Date.now(),
+    };
+    dispatch({ type: ActionTypes.ADD_USER_MESSAGE, content: text });
+    setLocalMessages(prev => [...prev, userMsg]);
+
+    // 2. 创建 AI 消息占位
+    const assistantId = `msg_ast_${Date.now()}`;
+    dispatch({ type: ActionTypes.START_ASSISTANT_MESSAGE, messageId: assistantId });
+    setLocalStreaming(true);
+
+    // 3. 初始化 StreamProcessor
+    const processor = new StreamProcessor();
+    processorRef.current = processor;
+
+    // 4. 节流：限制 segments 更新频率（每 100ms 最多一次）
+    let lastUpdate = 0;
+    const THROTTLE_MS = 100;
+
+    const scheduleUpdate = () => {
+      const now = Date.now();
+      if (now - lastUpdate < THROTTLE_MS) return;
+      lastUpdate = now;
+      const segments = processor.getSegments();
+      dispatch({
+        type: ActionTypes.FINALIZE_SEGMENTS,
+        messageId: assistantId,
+        segments: JSON.parse(JSON.stringify(segments)), // deep clone for React re-render
+      });
+    };
+
+    try {
+      // 5. 发起 SSE 请求
+      const conversationHistory = [...localMessages, userMsg].map(m => ({
+        role: m.role,
+        content: m.content,
+      }));
+
+      const response = await fetch('/api/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          messages: conversationHistory,
+          model: state.currentModel || undefined,
+        }),
+      });
+
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      // 6. 读取 SSE 流
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          if (!line.startsWith('data: ')) continue;
+          const data = line.slice(6);
+          if (data === '[DONE]') continue;
+
+          let event;
+          try { event = JSON.parse(data); } catch { continue; }
+
+          if (event.type === 'text') {
+            processor.feed(event.content);
+            scheduleUpdate();
+          } else if (event.type === 'error') {
+            dispatch({
+              type: ActionTypes.SET_STREAMING_ERROR,
+              messageId: assistantId,
+              error: event.message || 'Unknown error',
+            });
+            setLocalStreaming(false);
+            return;
+          }
+        }
+      }
+
+      // 7. 流结束，finalize
+      const finalSegments = processor.finalize();
+      dispatch({
+        type: ActionTypes.FINALIZE_SEGMENTS,
+        messageId: assistantId,
+        segments: finalSegments,
+      });
+      dispatch({ type: 'COMPLETE_STREAM', messageId: assistantId });
+
+      // 更新本地 messages 列表
+      const finalText = finalSegments
+        .filter(s => s.type === 'text')
+        .map(s => s.content)
+        .join('');
+      setLocalMessages(prev => [...prev, {
+        id: assistantId,
+        role: 'assistant',
+        content: finalText,
+        segments: finalSegments,
+        status: 'complete',
+        error: null,
+        timestamp: Date.now(),
+      }]);
+
+    } catch (err) {
+      console.error('Chat error:', err);
+      dispatch({
+        type: ActionTypes.SET_STREAMING_ERROR,
+        messageId: assistantId,
+        error: err.message || String(err),
+      });
+    }
+
+    setLocalStreaming(false);
+    processorRef.current = null;
+  }, [localStreaming, state.currentModel, localMessages, dispatch]);
+
+  return {
+    messages: localMessages,
+    isStreaming: localStreaming,
+    sendMessage,
+  };
+}

package/frontend/src/hooks/useModels.js

@@ -0,0 +1,52 @@
+/**
+ * useModels - 模型加载 Hook
+ *
+ * useEffect 中 fetch GET /api/models，
+ * 解析响应后 dispatch SET_MODELS。
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { useAppState, ActionTypes } from '../context/AppContext.jsx';
+
+export function useModels() {
+  const { state, dispatch } = useAppState();
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function load() {
+      try {
+        const res = await fetch('/api/models');
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const data = await res.json();
+        if (!cancelled) {
+          const models = [...new Set(data.available || [data.current])];
+          dispatch({
+            type: ActionTypes.SET_MODELS,
+            models,
+            current: data.current,
+          });
+        }
+      } catch (e) {
+        console.error('Failed to load models:', e);
+      } finally {
+        if (!cancelled) setIsLoading(false);
+      }
+    }
+
+    load();
+    return () => { cancelled = true; };
+  }, [dispatch]);
+
+  const setModel = useCallback((model) => {
+    dispatch({ type: ActionTypes.SET_MODELS, models: state.availableModels, current: model });
+  }, [state.availableModels, dispatch]);
+
+  return {
+    currentModel: state.currentModel,
+    models: state.availableModels,
+    setModel,
+    isLoading,
+  };
+}

package/frontend/src/hooks/useTheme.js

@@ -0,0 +1,31 @@
+/**
+ * useTheme - 主题切换 Hook
+ *
+ * 读取/写入 localStorage('claude-chat-theme')，
+ * 切换时更新 document.documentElement.dataset.theme。
+ */
+
+import { useState, useCallback } from 'react';
+
+const STORAGE_KEY = 'claude-chat-theme';
+
+export function useTheme() {
+  const [theme, setThemeState] = useState(() => {
+    try { return localStorage.getItem(STORAGE_KEY) || 'dark'; }
+    catch { return 'dark'; }
+  });
+
+  const toggleTheme = useCallback(() => {
+    const next = theme === 'light' ? 'dark' : 'light';
+    setThemeState(next);
+    document.documentElement.setAttribute('data-theme', next);
+    try { localStorage.setItem(STORAGE_KEY, next); } catch {}
+  }, [theme]);
+
+  // 初始化：设置 DOM 主题
+  useState(() => {
+    document.documentElement.setAttribute('data-theme', theme);
+  });
+
+  return { theme, toggleTheme };
+}

package/frontend/src/lib/markdownRenderer.js

@@ -0,0 +1,80 @@
+/**
+ * Markdown + KaTeX Renderer
+ *
+ * 封装 marked.parse 和 katex 渲染逻辑。
+ * 依赖全局变量: marked, katex（通过 CDN <script> 加载）
+ */
+
+/**
+ * 将原始文本渲染为 HTML
+ * 处理：[VISUALIZE:] 标签移除、代码块过滤、marked 解析、KaTeX 公式渲染
+ *
+ * @param {string} text - 原始 Markdown 文本
+ * @returns {string} 渲染后的 HTML 字符串
+ */
+export function renderMarkdown(text) {
+  let cleaned = text;
+
+  // 移除可视化标签
+  cleaned = cleaned.replace(/^\[VISUALIZE:\s*(yes|no)\]\s*\n?/m, '');
+
+  // 移除可视化代码块（由独立 Widget 渲染器处理）
+  cleaned = cleaned.replace(/```mermaid\s*\n[\s\S]*?```/g, '');
+  cleaned = cleaned.replace(/```mermaid[\s\S]*$/g, '');
+  cleaned = cleaned.replace(/```html\s*\n[\s\S]*?```/g, '');
+  cleaned = cleaned.replace(/```html[\s\S]*$/g, '');
+  cleaned = cleaned.replace(/```svg\s*\n[\s\S]*?```/g, '');
+  cleaned = cleaned.replace(/```svg[\s\S]*$/g, '');
+
+  // 移除 visualization placeholder 注释
+  const phRegex = new RegExp('<' + '!-- visualization placeholder -->\\s*', 'g');
+  cleaned = cleaned.replace(phRegex, '');
+
+  try {
+    const html = marked.parse(cleaned);
+    return renderMath(html);
+  } catch (e) {
+    // fallback: 转义后返回纯文本
+    if (typeof escapeHtml !== 'undefined') {
+      return escapeHtml(cleaned);
+    }
+    return cleaned
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+}
+
+/**
+ * 在 HTML 中渲染 KaTeX 数学公式
+ *
+ * @param {string} html - 包含 $...$ / $$...$$ 标记的 HTML
+ * @returns {string} 渲染后的 HTML
+ */
+export function renderMath(html) {
+  if (typeof katex === 'undefined') return html;
+
+  try {
+    // 块级公式 $$...$$
+    let result = html.replace(/\$\$([\s\S]+?)\$\$/g, (_, tex) => {
+      try {
+        return katex.renderToString(tex.trim(), { displayMode: true, throwOnError: false });
+      } catch {
+        return `$$${tex}$$`;
+      }
+    });
+
+    // 行内公式 $...$
+    result = result.replace(/\$([^\$\n]+?)\$/g, (_, tex) => {
+      try {
+        return katex.renderToString(tex.trim(), { displayMode: false, throwOnError: false });
+      } catch {
+        return `$${tex}$`;
+      }
+    });
+
+    return result;
+  } catch (e) {
+    return html;
+  }
+}

package/frontend/src/lib/mermaidRenderer.js

@@ -0,0 +1,99 @@
+/**
+ * Mermaid Renderer
+ *
+ * 封装 Mermaid 初始化和图表渲染逻辑。
+ * 依赖 ESM 模块: mermaid（通过 importmap 加载）
+ */
+
+const darkConfig = {
+  startOnLoad: false,
+  theme: 'dark',
+  themeVariables: {
+    primaryColor: '#78350f',
+    primaryTextColor: '#fafaf9',
+    primaryBorderColor: '#d97706',
+    lineColor: '#60a5fa',
+    secondaryColor: '#292524',
+    tertiaryColor: '#1c1917',
+    fontFamily: '-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,sans-serif',
+    fontSize: '14px',
+    nodeTextColor: '#fafaf9',
+  },
+  flowchart: { htmlLabels: true, curve: 'basis' },
+  sequence: { mirrorActors: false },
+  mindmap: { padding: 20 },
+};
+
+const lightConfig = {
+  startOnLoad: false,
+  theme: 'base',
+  themeVariables: {
+    primaryColor: '#fef3c7',
+    primaryTextColor: '#1c1917',
+    primaryBorderColor: '#d97706',
+    lineColor: '#2563eb',
+    secondaryColor: '#f5f5f4',
+    tertiaryColor: '#fafaf9',
+    fontFamily: '-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,sans-serif',
+    fontSize: '14px',
+    nodeTextColor: '#1c1917',
+  },
+  flowchart: { htmlLabels: true, curve: 'basis' },
+  sequence: { mirrorActors: false },
+  mindmap: { padding: 20 },
+};
+
+let _mermaidModule = null;
+
+/**
+ * 动态加载 Mermaid ESM 模块（懒加载）
+ * @returns {Promise<object>} Mermaid 模块
+ */
+async function _getMermaid() {
+  if (_mermaidModule) return _mermaidModule;
+  _mermaidModule = await import('https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs');
+  return _mermaidModule;
+}
+
+/**
+ * 根据 Mermaid 代码首行判断图表类型
+ * @param {string} code - Mermaid 源代码
+ * @returns {string} 中文类型名称
+ */
+export function getChartType(code) {
+  const first = code.trim().split('\n')[0].trim().toLowerCase();
+  const map = {
+    graph: '流程图', flowchart: '流程图',
+    sequence: '序列图', class: '类图', state: '状态图',
+    er: 'ER图', gantt: '甘特图', pie: '饼图',
+    journey: '用户旅程图', mindmap: '思维导图', timeline: '时间线',
+    gitgraph: 'Git图', sankey: '桑基图', xychart: 'XY图表',
+    block: '块图',
+  };
+  for (const [key, label] of Object.entries(map)) {
+    if (first.startsWith(key)) return label;
+  }
+  return '图表';
+}
+
+/**
+ * 渲染 Mermaid 图表为 SVG
+ *
+ * @param {string} code - Mermaid 源代码
+ * @param {boolean} isLight - 是否浅色主题
+ * @returns {Promise<{svg: string|null, error: string|null}>}
+ */
+export async function renderMermaid(code, isLight = false) {
+  const id = 'm_' + Math.random().toString(36).substr(2, 9);
+
+  try {
+    const mermaid = await _getMermaid();
+
+    // 每次渲染前用正确的主题重新初始化
+    mermaid.initialize(isLight ? lightConfig : darkConfig);
+    const { svg } = await mermaid.render(id, code);
+    return { svg, error: null };
+  } catch (e) {
+    return { svg: null, error: e.message || String(e) };
+  }
+}