create-pardx-scaffold 0.1.0

package/template/apps/web/lib/audio-buffer-queue.ts

@@ -0,0 +1,273 @@
+/**
+ * @fileoverview 音频缓冲队列
+ *
+ * 用于处理 token refresh 期间的音频数据缓冲
+ * 确保长时间录音场景下不丢失音频数据
+ *
+ * @module lib/audio-buffer-queue
+ */
+
+interface AudioChunk {
+  audioData: string; // base64 encoded
+  sequence: number;
+  timestamp: number;
+}
+
+interface AudioBufferQueueOptions {
+  /** 最大队列长度（默认 100） */
+  maxQueueSize?: number;
+  /** 发送重试次数（默认 3） */
+  maxRetries?: number;
+  /** 重试延迟（毫秒，默认 1000） */
+  retryDelay?: number;
+}
+
+/**
+ * 音频缓冲队列
+ *
+ * @description
+ * 解决 JWT token refresh 导致的音频数据丢失问题：
+ * 1. Token 过期时，自动缓冲音频数据到队列
+ * 2. Token 刷新完成后，按序重新发送队列中的数据
+ * 3. 支持失败重试机制
+ *
+ * @example
+ * ```typescript
+ * const queue = new AudioBufferQueue({
+ *   maxQueueSize: 100,
+ *   maxRetries: 3,
+ *   retryDelay: 1000,
+ * });
+ *
+ * // 发送音频数据（自动处理缓冲和重试）
+ * await queue.send(
+ *   sessionId,
+ *   audioData,
+ *   sequence,
+ *   (sessionId, audioData, sequence) => apiClient.sendAudioChunk({...})
+ * );
+ *
+ * // 手动触发 token refresh
+ * await queue.handleTokenRefresh(async () => {
+ *   await refreshAccessToken();
+ * });
+ * ```
+ */
+export class AudioBufferQueue {
+  private queue: AudioChunk[] = [];
+  private isRefreshing = false;
+  private isSending = false;
+  private readonly options: Required<AudioBufferQueueOptions>;
+
+  constructor(options: AudioBufferQueueOptions = {}) {
+    this.options = {
+      maxQueueSize: options.maxQueueSize ?? 100,
+      maxRetries: options.maxRetries ?? 3,
+      retryDelay: options.retryDelay ?? 1000,
+    };
+  }
+
+  /**
+   * 发送音频数据
+   *
+   * @param sessionId - Session ID
+   * @param audioData - Base64 encoded audio data
+   * @param sequence - Sequence number
+   * @param sendFn - 发送函数
+   * @returns Promise
+   */
+  async send(
+    sessionId: string,
+    audioData: string,
+    sequence: number,
+    sendFn: (
+      sessionId: string,
+      audioData: string,
+      sequence: number,
+    ) => Promise<void>,
+  ): Promise<void> {
+    const chunk: AudioChunk = {
+      audioData,
+      sequence,
+      timestamp: Date.now(),
+    };
+
+    // 如果正在 refresh 或队列中有数据，先缓冲
+    if (this.isRefreshing || this.queue.length > 0) {
+      this.enqueue(chunk);
+      return;
+    }
+
+    // 尝试直接发送
+    try {
+      await sendFn(sessionId, audioData, sequence);
+    } catch (error) {
+      // 检查是否是认证错误
+      if (this.isAuthError(error)) {
+        // 认证错误，缓冲当前数据并触发 refresh
+        this.enqueue(chunk);
+        throw error; // 抛出错误，让调用方知道需要 refresh
+      } else {
+        // 其他错误，直接抛出
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * 处理 token refresh
+   *
+   * @param refreshFn - Token refresh 函数
+   */
+  async handleTokenRefresh(refreshFn: () => Promise<void>): Promise<void> {
+    if (this.isRefreshing) {
+      console.warn('[AudioBufferQueue] Already refreshing, skipping');
+      return;
+    }
+
+    this.isRefreshing = true;
+
+    try {
+      // 执行 token refresh
+      await refreshFn();
+
+      // Refresh 成功，flush 队列
+      await this.flush(async (_chunk) => {
+        // 这里需要调用方传入 sendFn
+        // 所以我们需要调整设计
+      });
+    } catch (error) {
+      console.error('[AudioBufferQueue] Token refresh failed:', error);
+      throw error;
+    } finally {
+      this.isRefreshing = false;
+    }
+  }
+
+  /**
+   * 将音频数据加入缓冲队列
+   */
+  private enqueue(chunk: AudioChunk): void {
+    if (this.queue.length >= this.options.maxQueueSize) {
+      console.warn('[AudioBufferQueue] Queue is full, dropping oldest chunk', {
+        queueSize: this.queue.length,
+        droppedChunk: this.queue[0],
+      });
+      this.queue.shift(); // 移除最旧的数据
+    }
+
+    this.queue.push(chunk);
+    console.log('[AudioBufferQueue] Chunk enqueued', {
+      sequence: chunk.sequence,
+      queueSize: this.queue.length,
+    });
+  }
+
+  /**
+   * Flush 队列：按序发送所有缓冲的音频数据
+   */
+  async flush(
+    sendFn: (
+      sessionId: string,
+      audioData: string,
+      sequence: number,
+    ) => Promise<void>,
+    sessionId: string,
+  ): Promise<void> {
+    if (this.isSending) {
+      console.warn('[AudioBufferQueue] Already flushing, skipping');
+      return;
+    }
+
+    if (this.queue.length === 0) {
+      return;
+    }
+
+    this.isSending = true;
+    console.log('[AudioBufferQueue] Flushing queue', {
+      queueSize: this.queue.length,
+    });
+
+    const chunksToSend = [...this.queue];
+    this.queue = []; // 清空队列
+
+    for (const chunk of chunksToSend) {
+      let retries = 0;
+      while (retries < this.options.maxRetries) {
+        try {
+          await sendFn(sessionId, chunk.audioData, chunk.sequence);
+          break; // 发送成功，跳出重试循环
+        } catch (error) {
+          retries++;
+          console.error(
+            `[AudioBufferQueue] Failed to send chunk (attempt ${retries}/${this.options.maxRetries})`,
+            {
+              sequence: chunk.sequence,
+              error,
+            },
+          );
+
+          if (retries >= this.options.maxRetries) {
+            console.error(
+              '[AudioBufferQueue] Max retries reached, dropping chunk',
+              {
+                sequence: chunk.sequence,
+              },
+            );
+            // TODO: 通知用户数据丢失
+            break;
+          }
+
+          // 等待重试延迟
+          await this.sleep(this.options.retryDelay);
+        }
+      }
+    }
+
+    this.isSending = false;
+    console.log('[AudioBufferQueue] Queue flushed');
+  }
+
+  /**
+   * 检查是否是认证错误
+   */
+  private isAuthError(error: unknown): boolean {
+    if (error && typeof error === 'object') {
+      const err = error as unknown;
+      return (
+        err.status === 401 ||
+        err.statusCode === 401 ||
+        err.code === 'UNAUTHORIZED' ||
+        err.message?.includes('Unauthorized') ||
+        err.message?.includes('token')
+      );
+    }
+    return false;
+  }
+
+  /**
+   * 延迟函数
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * 获取队列状态
+   */
+  getStatus() {
+    return {
+      queueSize: this.queue.length,
+      isRefreshing: this.isRefreshing,
+      isSending: this.isSending,
+    };
+  }
+
+  /**
+   * 清空队列
+   */
+  clear(): void {
+    this.queue = [];
+    console.log('[AudioBufferQueue] Queue cleared');
+  }
+}

package/template/apps/web/lib/config.ts

@@ -0,0 +1,163 @@
+// API 配置
+// API 基础地址从环境变量读取
+// 在 .env.local 文件中设置以下环境变量：
+// - NEXT_PUBLIC_API_BASE_URL: 登录、上传文件、测评等接口的基础地址
+// - NEXT_PUBLIC_AGUI_API_BASE_URL: Agno 相关接口的基础地址
+// - NEXT_PUBLIC_AGUI_API_BASE_URL: AgUI 相关接口的基础地址
+
+/**
+ * 获取 API 基础地址（用于登录、上传文件、测评等）
+ */
+const getApiBaseUrl = (): string => {
+  const baseUrl = process.env.NEXT_PUBLIC_API_BASE_URL;
+
+  if (!baseUrl) {
+    // Use default value during build time or development
+    const defaultUrl = 'http://localhost:3100/api';
+    if (
+      process.env.NODE_ENV === 'development' ||
+      process.env.NEXT_PHASE === 'phase-production-build'
+    ) {
+      return defaultUrl;
+    }
+    // At runtime in production, use default if not set
+    console.warn('NEXT_PUBLIC_API_BASE_URL 未设置，使用默认值', defaultUrl);
+    return defaultUrl;
+  }
+
+  return baseUrl;
+};
+
+/**
+ * 获取 Agno API 基础地址
+ */
+const getAgnoApiBaseUrl = (): string => {
+  const baseUrl = process.env.NEXT_PUBLIC_AGUI_API_BASE_URL;
+
+  if (!baseUrl) {
+    // Use default value during build time or development
+    const defaultUrl = 'http://127.0.0.1:8000/api';
+    // At runtime in production, use default if not set
+    console.warn(
+      'NEXT_PUBLIC_AGUI_API_BASE_URL 未设置，使用默认值',
+      defaultUrl,
+    );
+    return defaultUrl;
+  }
+
+  return baseUrl;
+};
+
+/**
+ * 获取 AgUI 基础地址
+ */
+const getAguiBaseUrl = (): string => {
+  const baseUrl = process.env.NEXT_PUBLIC_AGUI_API_BASE_URL;
+
+  if (!baseUrl) {
+    // Use default value during build time or development
+    const defaultUrl = 'http://127.0.0.1:8000/api/agui';
+    // At runtime in production, use default if not set
+    console.warn(
+      'NEXT_PUBLIC_AGUI_API_BASE_URL 未设置，使用默认值',
+      defaultUrl,
+    );
+    return defaultUrl;
+  }
+
+  return baseUrl + '/agui';
+};
+
+/**
+ * 获取品牌名称
+ */
+const getBrandName = (): string => {
+  const brandName = process.env.NEXT_PUBLIC_BRAND_NAME;
+  return brandName || 'Pardx.AI';
+};
+
+/**
+ * 获取品牌 Logo 路径
+ */
+const getBrandLogo = (): string => {
+  const brandLogo = process.env.NEXT_PUBLIC_BRAND_LOGO;
+  return brandLogo || '/logo.svg';
+};
+
+/**
+ * 获取品牌完整标题（用于页面标题）
+ *
+ * 产品定位：多智能体驱动的内容创作与运营平台
+ * 核心能力：
+ * - AI 内容创作（智能写作、创意生成）
+ * - 知识库管理（进化型知识库、智能提取、质量评估）
+ * - 智能推荐（向量检索、协同过滤）
+ * - 招聘面试（AI 招聘 Agent、简历解析、智能匹配）
+ * - 会议管理（实时转写、知识提取、纪要生成）
+ * - 多智能体协作（AG-UI/Agno）
+ */
+const getBrandTitle = (): string => {
+  const brandTitle = process.env.NEXT_PUBLIC_BRAND_TITLE;
+  return brandTitle || 'PardxAI - Multi-Agent Content Creation ';
+};
+
+/**
+ * 获取品牌描述（用于页面描述）
+ *
+ * 描述应包含：
+ * - 产品定位（多智能体平台）
+ * - 核心功能（内容创作、知识管理、智能推荐、招聘面试）
+ * - 技术优势（AI 驱动、多智能体协作）
+ * - 目标用户（企业团队、内容创作者、HR 团队）
+ */
+const getBrandDescription = (): string => {
+  const brandDescription = process.env.NEXT_PUBLIC_BRAND_DESCRIPTION;
+  return (
+    brandDescription ||
+    'PardxAI is an AI-powered multi-agent platform for content creation.'
+  );
+};
+
+export const API_CONFIG = {
+  // API 基础地址（用于登录、上传文件、测评等）
+  baseUrl: getApiBaseUrl(),
+
+  // Agno API 基础地址
+  agnoApiBaseUrl: getAgnoApiBaseUrl(),
+
+  // AgUI 基础地址
+  aguiBaseUrl: getAguiBaseUrl(),
+
+  // API 端点路径 这些断点是不适用ts-rest-api的，用于登录和校验权限的断点，如果未来需要使用ts-rest-api，则将这些断点迁移到ts-rest-api中
+  endpoints: {
+    // 登录端点
+    login: '/sign/in/mobile/password',
+
+    // Token 刷新端点
+    refreshToken: '/sign/refresh/token',
+  },
+};
+
+/**
+ * 品牌配置
+ * 可通过环境变量覆盖：
+ * - NEXT_PUBLIC_BRAND_NAME: 品牌名称（默认: "Pardx.AI"）
+ * - NEXT_PUBLIC_BRAND_LOGO: Logo 路径（默认: "/logo.svg"）
+ * - NEXT_PUBLIC_BRAND_TITLE: 页面标题（默认: "PardxAI - Multi-Agent Content Creation"）
+ * - NEXT_PUBLIC_BRAND_DESCRIPTION: 页面描述（默认: "PardxAI is an AI-powered multi-agent platform for content creation."）
+ *
+ * 产品定位说明：
+ * PardxAI 是一个多智能体驱动的内容创作与运营平台，提供以下核心能力：
+ * 1. AI 内容创作：智能写作、创意生成、多模态内容创作
+ * 2. 知识库管理：进化型知识库系统、智能知识提取、质量评估、版本控制、相似度检测与合并
+ * 3. 智能推荐：基于向量检索和协同过滤的知识推荐系统
+ * 4. 招聘面试：AI 招聘 Agent、简历解析、JD 分析、人才匹配、智能面试
+ * 5. 会议管理：实时转写、知识提取、智能纪要生成
+ * 6. 多智能体协作：AG-UI/Agno 集成，支持多智能体协同工作
+ */
+export const BRAND_CONFIG = {
+  name: getBrandName(),
+  logo: getBrandLogo(),
+  title: getBrandTitle(),
+  description: getBrandDescription(),
+};