@talknote/create-talknote-h5 0.1.4 → 0.1.5

package/template/packages/xiaozhi-chat/hooks/useRealtimeTranscription.ts

@@ -0,0 +1,226 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Toast } from 'antd-mobile';
+import TalkNoteH5Bridge from '@talknote/h5-bridge';
+import {
+  getVibeNoteBridge,
+  isVibeNoteBridgeAvailable,
+  resolveAsrWsUrl,
+  vibeNoteCanIUse,
+  type TranscriptionErrorData,
+  type TranscriptionResultData,
+} from '../utils/bridge';
+
+const MAX_INPUT_LENGTH = 500;
+
+const getErrorHint = (error: unknown): string => {
+  const code =
+    error && typeof error === 'object' && 'code' in error
+      ? String((error as { code?: string }).code || '')
+      : '';
+
+  if (code === 'permission_denied') return '需要麦克风权限才能使用语音输入';
+  if (code === 'cannot_voice_input') return '当前不可录音，请稍后再试';
+  if (code === 'start_failed' || code === 'invalid_url') return '启动转写失败，请稍后再试';
+  return '语音输入失败，请改用键盘输入';
+};
+
+const joinTranscript = (base: string, extra: string) => {
+  const next = extra.trim();
+  if (!next) return base;
+  if (!base) return next;
+  const needSpace = /[A-Za-z0-9]$/.test(base) && /^[A-Za-z0-9]/.test(next);
+  return needSpace ? `${base} ${next}` : `${base}${next}`;
+};
+
+const clipText = (text: string) =>
+  text.length > MAX_INPUT_LENGTH ? text.slice(0, MAX_INPUT_LENGTH) : text;
+
+type UseRealtimeTranscriptionOptions = {
+  value: string;
+  onChange: (value: string) => void;
+};
+
+type UseRealtimeTranscriptionResult = {
+  transcribing: boolean;
+  start: () => Promise<boolean>;
+  stop: (options?: { silent?: boolean }) => Promise<string>;
+  toggle: () => Promise<void>;
+};
+
+export const useRealtimeTranscription = ({
+  value,
+  onChange,
+}: UseRealtimeTranscriptionOptions): UseRealtimeTranscriptionResult => {
+  const [transcribing, setTranscribing] = useState(false);
+  const valueRef = useRef(value);
+  const committedRef = useRef('');
+  const transcribingRef = useRef(false);
+  const recordingRef = useRef(false);
+  const channelRef = useRef(false);
+  const busyRef = useRef(false);
+  const unsubscribersRef = useRef<Array<() => void>>([]);
+  const onChangeRef = useRef(onChange);
+
+  valueRef.current = value;
+  onChangeRef.current = onChange;
+
+  const teardownListeners = useCallback(() => {
+    unsubscribersRef.current.forEach((off) => off());
+    unsubscribersRef.current = [];
+  }, []);
+
+  const applyTranscript = useCallback((text: string, isFinal: boolean) => {
+    const merged = clipText(joinTranscript(committedRef.current, text));
+    if (isFinal) {
+      committedRef.current = merged;
+    }
+    onChangeRef.current(merged);
+    return merged;
+  }, []);
+
+  const stop = useCallback(async (options?: { silent?: boolean }) => {
+    if (!transcribingRef.current && !recordingRef.current && !channelRef.current) {
+      setTranscribing(false);
+      return valueRef.current;
+    }
+
+    const bridge = getVibeNoteBridge();
+    const hadChannel = channelRef.current;
+    const hadRecording = recordingRef.current;
+    transcribingRef.current = false;
+    setTranscribing(false);
+
+    try {
+      if (hadChannel) {
+        await bridge?.stopRealtimeTranscription?.();
+      }
+    } catch (error) {
+      if (!options?.silent) {
+        console.warn('stopRealtimeTranscription failed:', error);
+      }
+    } finally {
+      channelRef.current = false;
+    }
+
+    try {
+      if (hadRecording) {
+        if (hadChannel) {
+          await bridge?.cancelVoiceRecording?.();
+        } else {
+          const result = await bridge?.stopVoiceRecording?.();
+          const text = String(result?.text || '').trim();
+          if (text) {
+            applyTranscript(text, true);
+          } else if (!options?.silent) {
+            Toast.show({ content: '未识别到内容，请重试' });
+          }
+        }
+      }
+    } catch (error) {
+      if (!options?.silent) {
+        Toast.show({ content: getErrorHint(error) });
+      }
+    } finally {
+      recordingRef.current = false;
+    }
+
+    teardownListeners();
+    return valueRef.current;
+  }, [applyTranscript, teardownListeners]);
+
+  const stopRef = useRef(stop);
+  stopRef.current = stop;
+
+  const start = useCallback(async () => {
+    if (busyRef.current || transcribingRef.current) return false;
+    if (!isVibeNoteBridgeAvailable()) {
+      Toast.show({ content: '请在 TalkNote App 内使用语音输入' });
+      return false;
+    }
+    if (!vibeNoteCanIUse('startVoiceRecording')) {
+      Toast.show({ content: '当前 App 版本不支持语音输入，请升级后重试' });
+      return false;
+    }
+
+    const bridge = getVibeNoteBridge();
+    if (!bridge?.canVoiceInput || !bridge.startVoiceRecording) {
+      Toast.show({ content: '请在 TalkNote App 内使用语音输入' });
+      return false;
+    }
+
+    const realtimeSupported = vibeNoteCanIUse('startRealtimeTranscription');
+    busyRef.current = true;
+    committedRef.current = valueRef.current.trimEnd();
+
+    try {
+      const check = await bridge.canVoiceInput();
+      if (!check?.canVoiceInput) {
+        Toast.show({ content: '当前不可录音，请稍后再试' });
+        return false;
+      }
+
+      if (realtimeSupported) {
+        teardownListeners();
+        const offResult = bridge.addListener?.('onTranscriptionResult', (event) => {
+          const data = (event?.data || {}) as TranscriptionResultData;
+          applyTranscript(String(data.text || ''), Boolean(data.isFinal));
+        });
+        const offError = bridge.addListener?.('onTranscriptionError', (event) => {
+          const data = (event?.data || {}) as TranscriptionErrorData;
+          Toast.show({ content: data.message || '转写失败，请重试' });
+          void stopRef.current({ silent: true });
+        });
+        if (offResult) unsubscribersRef.current.push(offResult);
+        if (offError) unsubscribersRef.current.push(offError);
+      }
+
+      await bridge.startVoiceRecording();
+      recordingRef.current = true;
+      transcribingRef.current = true;
+      setTranscribing(true);
+
+      if (realtimeSupported && bridge.startRealtimeTranscription) {
+        let info: { baseUrl?: string; env?: string } | null = null;
+        try {
+          info =
+            (await bridge.getRequestBaseInfo?.()) || (await TalkNoteH5Bridge.getRequestBaseInfo());
+        } catch {
+          info = null;
+        }
+        const wsUrl = resolveAsrWsUrl(info?.baseUrl, info?.env);
+        await bridge.startRealtimeTranscription({ wsUrl });
+        channelRef.current = true;
+      }
+
+      return true;
+    } catch (error) {
+      Toast.show({ content: getErrorHint(error) });
+      await stopRef.current({ silent: true });
+      return false;
+    } finally {
+      busyRef.current = false;
+    }
+  }, [applyTranscript, teardownListeners]);
+
+  const toggle = useCallback(async () => {
+    if (transcribingRef.current) {
+      await stop();
+      return;
+    }
+    await start();
+  }, [start, stop]);
+
+  useEffect(
+    () => () => {
+      void stopRef.current({ silent: true });
+    },
+    [],
+  );
+
+  return {
+    transcribing,
+    start,
+    stop,
+    toggle,
+  };
+};

package/template/packages/xiaozhi-chat/hooks/useTypewriter.ts

@@ -0,0 +1,215 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  computeTypewriterPacing,
+  resolveTypewriterDisplayLength,
+  TYPEWRITER_DEFAULTS,
+} from '../utils/typewriter';
+
+type Timer = ReturnType<typeof setTimeout>;
+
+export type UseTypewriterOptions = {
+  atomicTokens?: string[];
+  atomicClosedTags?: string[];
+};
+
+export const useTypewriter = (options: UseTypewriterOptions = {}) => {
+  const {
+    atomicTokens = [],
+    atomicClosedTags = [],
+  } = options;
+
+  const atomicTokensRef = useRef(atomicTokens);
+  const atomicClosedTagsRef = useRef(atomicClosedTags);
+  atomicTokensRef.current = atomicTokens;
+  atomicClosedTagsRef.current = atomicClosedTags;
+
+  const [displayedContent, setDisplayedContent] = useState('');
+  const [isTyping, setIsTyping] = useState(false);
+  const [streamComplete, setStreamComplete] = useState(false);
+
+  const receivedContentRef = useRef('');
+  const displayedContentRef = useRef('');
+  const streamCompleteRef = useRef(false);
+  const finishPhaseDeadlineRef = useRef<number | null>(null);
+  const pumpTimerRef = useRef<Timer | null>(null);
+  const pumpRunningRef = useRef(false);
+  const pumpTickRef = useRef<() => void>(() => {});
+
+  const isOutputComplete =
+    streamComplete && !isTyping && displayedContent === receivedContentRef.current;
+
+  const clearPumpTimer = useCallback(() => {
+    if (pumpTimerRef.current) {
+      clearTimeout(pumpTimerRef.current);
+      pumpTimerRef.current = null;
+    }
+  }, []);
+
+  const stopPump = useCallback(() => {
+    pumpRunningRef.current = false;
+    clearPumpTimer();
+    setIsTyping(false);
+  }, [clearPumpTimer]);
+
+  const getPacing = useCallback((lag: number) => {
+    const finishRemainingMs = finishPhaseDeadlineRef.current !== null
+      ? finishPhaseDeadlineRef.current - Date.now()
+      : TYPEWRITER_DEFAULTS.finishTargetMs;
+
+    return computeTypewriterPacing({
+      lag,
+      ...TYPEWRITER_DEFAULTS,
+      isStreamFinished: streamCompleteRef.current,
+      finishRemainingMs,
+    });
+  }, []);
+
+  const advanceDisplayedBy = useCallback((advanceSize: number): boolean => {
+    const currentReceived = receivedContentRef.current;
+    const currentDisplayed = displayedContentRef.current;
+    if (!currentReceived || currentDisplayed.length >= currentReceived.length) {
+      return false;
+    }
+
+    const lag = currentReceived.length - currentDisplayed.length;
+    const nextLength = resolveTypewriterDisplayLength(
+      currentDisplayed.length,
+      currentReceived,
+      Math.min(lag, Math.max(1, advanceSize)),
+      atomicTokensRef.current,
+      atomicClosedTagsRef.current,
+    );
+
+    if (nextLength <= currentDisplayed.length) {
+      return false;
+    }
+
+    const nextContent = currentReceived.substring(0, nextLength);
+    displayedContentRef.current = nextContent;
+    setDisplayedContent((prev) => (prev.length >= nextLength ? prev : nextContent));
+    return true;
+  }, []);
+
+  const scheduleNextPumpTick = useCallback((delayMs: number) => {
+    clearPumpTimer();
+    pumpTimerRef.current = setTimeout(() => {
+      pumpTimerRef.current = null;
+      if (pumpRunningRef.current) {
+        pumpTickRef.current();
+      }
+    }, delayMs);
+  }, [clearPumpTimer]);
+
+  const pumpTick = useCallback(() => {
+    if (!pumpRunningRef.current) {
+      return;
+    }
+
+    const lag = receivedContentRef.current.length - displayedContentRef.current.length;
+    if (lag <= 0) {
+      if (streamCompleteRef.current) {
+        stopPump();
+        return;
+      }
+      scheduleNextPumpTick(TYPEWRITER_DEFAULTS.typingSpeed);
+      return;
+    }
+
+    setIsTyping(true);
+    const { advanceSize, delayMs } = getPacing(lag);
+    if (advanceSize > 0) {
+      const moved = advanceDisplayedBy(advanceSize);
+      if (!moved && streamCompleteRef.current) {
+        displayedContentRef.current = receivedContentRef.current;
+        setDisplayedContent(receivedContentRef.current);
+        stopPump();
+        return;
+      }
+    }
+
+    const nextLag = receivedContentRef.current.length - displayedContentRef.current.length;
+    if (nextLag <= 0 && streamCompleteRef.current) {
+      stopPump();
+      return;
+    }
+
+    const nextDelay = nextLag > 0 ? getPacing(nextLag).delayMs : TYPEWRITER_DEFAULTS.typingSpeed;
+    scheduleNextPumpTick(nextDelay || delayMs);
+  }, [advanceDisplayedBy, getPacing, scheduleNextPumpTick, stopPump]);
+
+  pumpTickRef.current = pumpTick;
+
+  const ensurePumpRunning = useCallback(() => {
+    if (pumpRunningRef.current) {
+      return;
+    }
+    if (
+      streamCompleteRef.current
+      && displayedContentRef.current.length >= receivedContentRef.current.length
+    ) {
+      return;
+    }
+    if (!receivedContentRef.current) {
+      return;
+    }
+    pumpRunningRef.current = true;
+    pumpTick();
+  }, [pumpTick]);
+
+  const append = useCallback((text: string) => {
+    if (!text) return;
+    const next = receivedContentRef.current + text;
+    receivedContentRef.current = next;
+    ensurePumpRunning();
+  }, [ensurePumpRunning]);
+
+  const markStreamComplete = useCallback(() => {
+    if (streamCompleteRef.current) return;
+    streamCompleteRef.current = true;
+    setStreamComplete(true);
+
+    const lag = receivedContentRef.current.length - displayedContentRef.current.length;
+    if (lag <= 0) {
+      stopPump();
+      return;
+    }
+
+    const targetMs = Math.min(
+      TYPEWRITER_DEFAULTS.finishMaxMs,
+      Math.max(TYPEWRITER_DEFAULTS.finishMinMs, TYPEWRITER_DEFAULTS.finishTargetMs),
+    );
+    finishPhaseDeadlineRef.current = Date.now() + targetMs;
+    ensurePumpRunning();
+  }, [ensurePumpRunning, stopPump]);
+
+  const reset = useCallback(() => {
+    stopPump();
+    receivedContentRef.current = '';
+    displayedContentRef.current = '';
+    streamCompleteRef.current = false;
+    finishPhaseDeadlineRef.current = null;
+    setDisplayedContent('');
+    setStreamComplete(false);
+  }, [stopPump]);
+
+  const skip = useCallback(() => {
+    stopPump();
+    displayedContentRef.current = receivedContentRef.current;
+    setDisplayedContent(receivedContentRef.current);
+  }, [stopPump]);
+
+  useEffect(() => () => {
+    stopPump();
+  }, [stopPump]);
+
+  return {
+    displayedContent,
+    isTyping,
+    isOutputComplete,
+    append,
+    markStreamComplete,
+    reset,
+    skip,
+    stop: stopPump,
+  };
+};

package/template/packages/xiaozhi-chat/hooks/useViewportHeight.ts

@@ -0,0 +1,43 @@
+import { useCallback, useEffect, useState } from 'react';
+
+type UseViewportHeightOptions = {
+  enabled?: boolean;
+};
+
+/**
+ * 跟随 visualViewport 高度，键盘弹出时只压缩中间可滚动区域，头部/底部保持在视口内。
+ * 客户端已用 setKeyboardAvoidMode('resize') 压缩 WebView 时请关闭，避免与原生高度叠加。
+ */
+export const useViewportHeight = (cssVarName = '--xiaozhi-vh', options?: UseViewportHeightOptions) => {
+  const enabled = options?.enabled !== false;
+  const [height, setHeight] = useState<number | null>(null);
+
+  const sync = useCallback(() => {
+    const vv = window.visualViewport;
+    const next = Math.round(vv?.height ?? window.innerHeight);
+    setHeight(next);
+    document.documentElement.style.setProperty(cssVarName, `${next}px`);
+  }, [cssVarName]);
+
+  useEffect(() => {
+    if (!enabled) {
+      document.documentElement.style.removeProperty(cssVarName);
+      setHeight(null);
+      return;
+    }
+    sync();
+    const vv = window.visualViewport;
+    vv?.addEventListener('resize', sync);
+    vv?.addEventListener('scroll', sync);
+    window.addEventListener('resize', sync);
+    // eslint-disable-next-line consistent-return
+    return () => {
+      vv?.removeEventListener('resize', sync);
+      vv?.removeEventListener('scroll', sync);
+      window.removeEventListener('resize', sync);
+      document.documentElement.style.removeProperty(cssVarName);
+    };
+  }, [cssVarName, enabled, sync]);
+
+  return height;
+};

package/template/packages/xiaozhi-chat/hooks/useVoiceRecording.ts

@@ -0,0 +1,128 @@
+import { useCallback, useRef, useState } from 'react';
+import { Toast } from 'antd-mobile';
+import {
+  getVibeNoteBridge,
+  isVibeNoteBridgeAvailable,
+  vibeNoteCanIUse,
+} from '../utils/bridge';
+
+export type VoiceRecordingPhase = 'idle' | 'recording' | 'canceling';
+
+const getErrorHint = (error: unknown): string => {
+  const code =
+    error && typeof error === 'object' && 'code' in error
+      ? String((error as { code?: string }).code || '')
+      : '';
+
+  if (code === 'permission_denied') {
+    return '需要麦克风权限才能使用语音输入';
+  }
+  if (code === 'cannot_voice_input') {
+    return '当前不可录音，请稍后再试';
+  }
+  if (code === 'start_failed') {
+    return '启动录音失败，请稍后再试';
+  }
+
+  return '语音输入失败，请改用键盘输入';
+};
+
+export const useVoiceRecording = () => {
+  const [phase, setPhase] = useState<VoiceRecordingPhase>('idle');
+  const startedRef = useRef(false);
+  const busyRef = useRef(false);
+
+  const ensureSupported = useCallback(() => {
+    if (!isVibeNoteBridgeAvailable()) {
+      Toast.show({ content: '请在 TalkNote App 内使用语音输入' });
+      return false;
+    }
+    if (!vibeNoteCanIUse('startVoiceRecording')) {
+      Toast.show({ content: '当前 App 版本不支持语音输入，请升级后重试' });
+      return false;
+    }
+    return true;
+  }, []);
+
+  const start = useCallback(async () => {
+    if (busyRef.current || startedRef.current) return false;
+    if (!ensureSupported()) return false;
+
+    const bridge = getVibeNoteBridge();
+    if (!bridge?.canVoiceInput || !bridge.startVoiceRecording) {
+      Toast.show({ content: '请在 TalkNote App 内使用语音输入' });
+      return false;
+    }
+
+    busyRef.current = true;
+    try {
+      const check = await bridge.canVoiceInput();
+      if (!check?.canVoiceInput) {
+        Toast.show({ content: '当前不可录音，请稍后再试' });
+        return false;
+      }
+
+      await bridge.startVoiceRecording();
+      startedRef.current = true;
+      setPhase('recording');
+      return true;
+    } catch (error) {
+      Toast.show({ content: getErrorHint(error) });
+      startedRef.current = false;
+      setPhase('idle');
+      return false;
+    } finally {
+      busyRef.current = false;
+    }
+  }, [ensureSupported]);
+
+  const cancel = useCallback(async () => {
+    if (!startedRef.current) {
+      setPhase('idle');
+      return;
+    }
+
+    const bridge = getVibeNoteBridge();
+    busyRef.current = true;
+    setPhase('canceling');
+    try {
+      await bridge?.cancelVoiceRecording?.();
+    } catch (error) {
+      console.warn('cancelVoiceRecording failed:', error);
+    } finally {
+      startedRef.current = false;
+      busyRef.current = false;
+      setPhase('idle');
+    }
+  }, []);
+
+  const stop = useCallback(async (): Promise<string> => {
+    if (!startedRef.current) {
+      setPhase('idle');
+      return '';
+    }
+
+    const bridge = getVibeNoteBridge();
+    busyRef.current = true;
+    try {
+      const result = await bridge?.stopVoiceRecording?.();
+      return (result?.text || '').trim();
+    } catch (error) {
+      Toast.show({ content: getErrorHint(error) });
+      return '';
+    } finally {
+      startedRef.current = false;
+      busyRef.current = false;
+      setPhase('idle');
+    }
+  }, []);
+
+  return {
+    phase,
+    isRecording: phase === 'recording',
+    start,
+    cancel,
+    stop,
+    ensureSupported,
+  };
+};

package/template/packages/xiaozhi-chat/index.ts

@@ -0,0 +1,11 @@
+export { default as XiaozhiChatPage } from './XiaozhiChatPage';
+export { default } from './XiaozhiChatPage';
+export type {
+  XiaozhiChatPageProps,
+  ChatMessage,
+  ChatSession,
+  ChatVersion,
+  CreateSessionParams,
+  StreamChatParams,
+} from './types';
+export { DEFAULT_CHAT_VERSION } from './types';

package/template/packages/xiaozhi-chat/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@talknote/xiaozhi-chat",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Ask AI H5 问答模块，供主工程引入",
+  "main": "index.ts",
+  "module": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts",
+      "require": "./index.ts",
+      "default": "./index.ts"
+    }
+  },
+  "files": [
+    "**/*"
+  ],
+  "sideEffects": [
+    "**/*.less",
+    "**/*.css"
+  ],
+  "dependencies": {
+    "react-markdown": "^8.0.7",
+    "remark-gfm": "^3.0.1"
+  },
+  "peerDependencies": {
+    "@talknote/h5-bridge": "^0.0.5",
+    "antd-mobile": "^5.15.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}