@xuanyue202/shared 2026.3.21

package/src/file/file-utils.ts

@@ -0,0 +1,284 @@
+/**
+ * File utilities for categorizing and resolving file extensions
+ * @module @xuanyue202/shared/file
+ */
+
+/**
+ * File category for processing strategy
+ */
+export type FileCategory =
+  | "image"
+  | "audio"
+  | "video"
+  | "document"
+  | "archive"
+  | "code"
+  | "other";
+
+/**
+ * MIME type to extension mapping
+ */
+const MIME_TO_EXTENSION: Record<string, string> = {
+  // Images
+  "image/jpeg": ".jpg",
+  "image/png": ".png",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/bmp": ".bmp",
+
+  // Audio
+  "audio/mpeg": ".mp3",
+  "audio/wav": ".wav",
+  "audio/ogg": ".ogg",
+  "audio/amr": ".amr",
+  "audio/x-m4a": ".m4a",
+
+  // Video
+  "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
+  "video/x-msvideo": ".avi",
+  "video/webm": ".webm",
+
+  // Documents
+  "application/pdf": ".pdf",
+  "application/msword": ".doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+    ".docx",
+  "application/vnd.ms-excel": ".xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+  "application/vnd.ms-powerpoint": ".ppt",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation":
+    ".pptx",
+  "application/rtf": ".rtf",
+  "application/vnd.oasis.opendocument.text": ".odt",
+  "application/vnd.oasis.opendocument.spreadsheet": ".ods",
+  "text/plain": ".txt",
+  "text/markdown": ".md",
+  "text/csv": ".csv",
+
+  // Archives
+  "application/zip": ".zip",
+  "application/x-rar-compressed": ".rar",
+  "application/vnd.rar": ".rar",
+  "application/x-7z-compressed": ".7z",
+  "application/x-tar": ".tar",
+  "application/gzip": ".gz",
+  "application/x-gzip": ".gz",
+  "application/x-bzip2": ".bz2",
+
+  // Code
+  "application/json": ".json",
+  "application/xml": ".xml",
+  "text/xml": ".xml",
+  "text/html": ".html",
+  "text/css": ".css",
+  "text/javascript": ".js",
+  "application/javascript": ".js",
+  "text/x-python": ".py",
+  "text/x-java-source": ".java",
+  "text/x-c": ".c",
+  "text/x-yaml": ".yaml",
+  "application/x-yaml": ".yaml",
+};
+
+/**
+ * MIME type to category mapping for non-prefix-based types
+ */
+const CATEGORY_BY_MIME: Record<string, FileCategory> = {
+  // Documents
+  "application/pdf": "document",
+  "application/msword": "document",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document":
+    "document",
+  "application/vnd.ms-excel": "document",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":
+    "document",
+  "application/vnd.ms-powerpoint": "document",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation":
+    "document",
+  "application/rtf": "document",
+  "application/vnd.oasis.opendocument.text": "document",
+  "application/vnd.oasis.opendocument.spreadsheet": "document",
+  "text/plain": "document",
+  "text/markdown": "document",
+  "text/csv": "document",
+  // Archives
+  "application/zip": "archive",
+  "application/x-rar-compressed": "archive",
+  "application/vnd.rar": "archive",
+  "application/x-7z-compressed": "archive",
+  "application/x-tar": "archive",
+  "application/gzip": "archive",
+  "application/x-gzip": "archive",
+  "application/x-bzip2": "archive",
+  // Code
+  "application/json": "code",
+  "application/xml": "code",
+  "text/xml": "code",
+  "text/html": "code",
+  "text/css": "code",
+  "text/javascript": "code",
+  "application/javascript": "code",
+  "text/x-python": "code",
+  "text/x-java-source": "code",
+  "text/x-c": "code",
+  "text/x-yaml": "code",
+  "application/x-yaml": "code",
+};
+
+/**
+ * Extension to category mapping
+ */
+const CATEGORY_BY_EXTENSION: Record<string, FileCategory> = {
+  // Images
+  ".jpg": "image",
+  ".jpeg": "image",
+  ".png": "image",
+  ".gif": "image",
+  ".webp": "image",
+  ".bmp": "image",
+  // Audio
+  ".mp3": "audio",
+  ".wav": "audio",
+  ".ogg": "audio",
+  ".m4a": "audio",
+  ".amr": "audio",
+  // Video
+  ".mp4": "video",
+  ".mov": "video",
+  ".avi": "video",
+  ".mkv": "video",
+  ".webm": "video",
+  // Documents
+  ".pdf": "document",
+  ".doc": "document",
+  ".docx": "document",
+  ".txt": "document",
+  ".md": "document",
+  ".rtf": "document",
+  ".odt": "document",
+  ".xls": "document",
+  ".xlsx": "document",
+  ".csv": "document",
+  ".ods": "document",
+  ".ppt": "document",
+  ".pptx": "document",
+  // Archives
+  ".zip": "archive",
+  ".rar": "archive",
+  ".7z": "archive",
+  ".tar": "archive",
+  ".gz": "archive",
+  ".bz2": "archive",
+  // Code
+  ".py": "code",
+  ".js": "code",
+  ".ts": "code",
+  ".jsx": "code",
+  ".tsx": "code",
+  ".java": "code",
+  ".cpp": "code",
+  ".c": "code",
+  ".go": "code",
+  ".rs": "code",
+  ".json": "code",
+  ".xml": "code",
+  ".yaml": "code",
+  ".yml": "code",
+  ".html": "code",
+  ".css": "code",
+};
+
+/**
+ * Extract file extension from a file name
+ * @param fileName - The file name to extract extension from
+ * @returns The extension with leading dot (e.g., ".jpg") or empty string if none
+ */
+function extractExtension(fileName: string): string {
+  const lastDot = fileName.lastIndexOf(".");
+  if (lastDot === -1 || lastDot === fileName.length - 1) {
+    return "";
+  }
+  return fileName.slice(lastDot).toLowerCase();
+}
+
+/**
+ * Categorize a file based on MIME type and extension
+ *
+ * Priority:
+ * 1. Check MIME type prefix (image/, audio/, video/)
+ * 2. Check exact MIME type mapping (document, archive, code)
+ * 3. Check file extension from fileName
+ * 4. Return 'other' if no match
+ *
+ * @param contentType - MIME type string
+ * @param fileName - Optional file name for extension-based fallback
+ * @returns File category
+ */
+export function resolveFileCategory(
+  contentType: string,
+  fileName?: string
+): FileCategory {
+  // Normalize content type (remove parameters like charset)
+  const mimeType = contentType.split(";")[0].trim().toLowerCase();
+
+  // Check MIME type prefix first (image/, audio/, video/)
+  if (mimeType.startsWith("image/")) {
+    return "image";
+  }
+  if (mimeType.startsWith("audio/")) {
+    return "audio";
+  }
+  if (mimeType.startsWith("video/")) {
+    return "video";
+  }
+
+  // Check exact MIME type mapping (document, archive, code)
+  if (mimeType in CATEGORY_BY_MIME) {
+    return CATEGORY_BY_MIME[mimeType];
+  }
+
+  // Check file extension if fileName is provided
+  if (fileName) {
+    const ext = extractExtension(fileName);
+    if (ext && ext in CATEGORY_BY_EXTENSION) {
+      return CATEGORY_BY_EXTENSION[ext];
+    }
+  }
+
+  return "other";
+}
+
+/**
+ * Resolve file extension from MIME type or fileName
+ *
+ * Priority:
+ * 1. fileName extension (if provided and has extension)
+ * 2. MIME type mapping
+ * 3. ".bin" default
+ *
+ * @param contentType - MIME type string
+ * @param fileName - Optional file name to extract extension from (takes precedence)
+ * @returns Extension with leading dot (e.g., ".jpg") or ".bin" if unknown
+ */
+export function resolveExtension(
+  contentType: string,
+  fileName?: string
+): string {
+  // Priority 1: fileName extension
+  if (fileName) {
+    const ext = extractExtension(fileName);
+    if (ext) {
+      return ext;
+    }
+  }
+
+  // Priority 2: MIME type mapping
+  const mimeType = contentType.split(";")[0].trim().toLowerCase();
+  if (mimeType in MIME_TO_EXTENSION) {
+    return MIME_TO_EXTENSION[mimeType];
+  }
+
+  // Priority 3: Default
+  return ".bin";
+}

package/src/file/index.ts

@@ -0,0 +1,10 @@
+/**
+ * File utilities module
+ * @module @xuanyue202/shared/file
+ */
+
+export {
+  type FileCategory,
+  resolveFileCategory,
+  resolveExtension,
+} from "./file-utils.js";

package/src/http/client.ts

@@ -0,0 +1,141 @@
+/**
+ * 通用 HTTP 客户端封装
+ *
+ * 提供带超时和错误处理的 HTTP 请求功能
+ */
+
+/**
+ * HTTP 请求选项
+ */
+export interface HttpRequestOptions {
+  /** 请求超时时间（毫秒），默认 30000 */
+  timeout?: number;
+  /** 请求头 */
+  headers?: Record<string, string>;
+}
+
+/**
+ * HTTP 错误
+ */
+export class HttpError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body?: string
+  ) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+/**
+ * 超时错误
+ */
+export class TimeoutError extends Error {
+  constructor(message: string, public readonly timeoutMs: number) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+
+/**
+ * 发送 HTTP POST 请求
+ *
+ * @param url 请求 URL
+ * @param body 请求体
+ * @param options 请求选项
+ * @returns 响应数据
+ *
+ * @example
+ * ```ts
+ * const data = await httpPost("https://api.example.com/token", { key: "value" }, { timeout: 10000 });
+ * ```
+ */
+export async function httpPost<T = unknown>(
+  url: string,
+  body: unknown,
+  options?: HttpRequestOptions
+): Promise<T> {
+  const { timeout = 30000, headers = {} } = options ?? {};
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...headers,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const responseBody = await response.text().catch(() => "");
+      throw new HttpError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status,
+        responseBody
+      );
+    }
+
+    return (await response.json()) as T;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new TimeoutError(`Request timeout after ${timeout}ms`, timeout);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * 发送 HTTP GET 请求
+ *
+ * @param url 请求 URL
+ * @param options 请求选项
+ * @returns 响应数据
+ *
+ * @example
+ * ```ts
+ * const data = await httpGet("https://api.example.com/data", { timeout: 10000 });
+ * ```
+ */
+export async function httpGet<T = unknown>(
+  url: string,
+  options?: HttpRequestOptions
+): Promise<T> {
+  const { timeout = 30000, headers = {} } = options ?? {};
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const responseBody = await response.text().catch(() => "");
+      throw new HttpError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status,
+        responseBody
+      );
+    }
+
+    return (await response.json()) as T;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new TimeoutError(`Request timeout after ${timeout}ms`, timeout);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/http/index.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export * from "./retry.js";

package/src/http/retry.ts

@@ -0,0 +1,110 @@
+/**
+ * HTTP 重试策略
+ *
+ * 提供可配置的重试逻辑
+ */
+
+/**
+ * 重试选项
+ */
+export interface RetryOptions {
+  /** 最大重试次数，默认 3 */
+  maxRetries?: number;
+  /** 初始延迟时间（毫秒），默认 1000 */
+  initialDelay?: number;
+  /** 最大延迟时间（毫秒），默认 10000 */
+  maxDelay?: number;
+  /** 延迟倍数（指数退避），默认 2 */
+  backoffMultiplier?: number;
+  /** 判断是否应该重试的函数 */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+
+/**
+ * 默认的重试判断函数
+ * 对于网络错误和 5xx 错误进行重试
+ */
+export function defaultShouldRetry(error: unknown): boolean {
+  if (error instanceof Error) {
+    // 网络错误
+    if (error.name === "TypeError" || error.name === "TimeoutError") {
+      return true;
+    }
+    // HTTP 5xx 错误
+    if ("status" in error && typeof (error as { status: number }).status === "number") {
+      const status = (error as { status: number }).status;
+      return status >= 500 && status < 600;
+    }
+  }
+  return false;
+}
+
+/**
+ * 计算延迟时间（指数退避）
+ */
+function calculateDelay(
+  attempt: number,
+  initialDelay: number,
+  maxDelay: number,
+  backoffMultiplier: number
+): number {
+  const delay = initialDelay * Math.pow(backoffMultiplier, attempt - 1);
+  return Math.min(delay, maxDelay);
+}
+
+/**
+ * 延迟执行
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 带重试的异步函数执行器
+ *
+ * @param fn 要执行的异步函数
+ * @param options 重试选项
+ * @returns 函数执行结果
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => httpPost(url, body),
+ *   { maxRetries: 3, initialDelay: 1000 }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options?: RetryOptions
+): Promise<T> {
+  const {
+    maxRetries = 3,
+    initialDelay = 1000,
+    maxDelay = 10000,
+    backoffMultiplier = 2,
+    shouldRetry = defaultShouldRetry,
+  } = options ?? {};
+
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      // 如果是最后一次尝试或不应该重试，直接抛出错误
+      if (attempt > maxRetries || !shouldRetry(error, attempt)) {
+        throw error;
+      }
+
+      // 计算延迟并等待
+      const delay = calculateDelay(attempt, initialDelay, maxDelay, backoffMultiplier);
+      await sleep(delay);
+    }
+  }
+
+  // 理论上不会到达这里，但为了类型安全
+  throw lastError;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// @xuanyue202/shared
+// 共享工具模块
+
+export * from "./logger/index.js";
+export * from "./policy/index.js";
+export * from "./http/index.js";
+export * from "./types/common.js";
+export * from "./file/index.js";
+export * from "./media/index.js";
+export * from "./cron/index.js";
+export * from "./asr/index.js";
+export * from "./cli/index.js";

package/src/logger/index.ts

@@ -0,0 +1 @@
+export * from "./logger.js";

package/src/logger/logger.ts

@@ -0,0 +1,51 @@
+/**
+ * 通用日志工具
+ *
+ * 提供分级日志功能:
+ * - info: 关键业务日志（默认显示）
+ * - debug: 调试日志（带 [DEBUG] 标记）
+ * - error: 错误日志
+ * - warn: 警告日志
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+  debug: (msg: string) => void;
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+}
+
+export interface LoggerOptions {
+  log?: (msg: string) => void;
+  error?: (msg: string) => void;
+}
+
+/**
+ * 创建带前缀的日志器
+ *
+ * @param prefix 日志前缀（如 "dingtalk", "feishu"）
+ * @param opts 可选的日志输出函数
+ * @returns Logger 实例
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger("dingtalk");
+ * logger.debug("connecting..."); // [dingtalk] [DEBUG] connecting...
+ * logger.info("connected");      // [dingtalk] connected
+ * logger.warn("slow response");  // [dingtalk] [WARN] slow response
+ * logger.error("failed");        // [dingtalk] [ERROR] failed
+ * ```
+ */
+export function createLogger(prefix: string, opts?: LoggerOptions): Logger {
+  const logFn = opts?.log ?? console.log;
+  const errorFn = opts?.error ?? console.error;
+
+  return {
+    debug: (msg: string) => logFn(`[${prefix}] [DEBUG] ${msg}`),
+    info: (msg: string) => logFn(`[${prefix}] ${msg}`),
+    warn: (msg: string) => logFn(`[${prefix}] [WARN] ${msg}`),
+    error: (msg: string) => errorFn(`[${prefix}] [ERROR] ${msg}`),
+  };
+}

package/src/media/index.ts

@@ -0,0 +1,65 @@
+/**
+ * 媒体处理模块
+ *
+ * 提供统一的媒体解析、路径处理和文件读取功能
+ *
+ * @module @xuanyue202/shared/media
+ */
+
+// 媒体解析
+export {
+  // 类型
+  type MediaType,
+  type ExtractedMedia,
+  type MediaParseResult,
+  type MediaParseOptions,
+  // 常量
+  IMAGE_EXTENSIONS,
+  AUDIO_EXTENSIONS,
+  VIDEO_EXTENSIONS,
+  NON_IMAGE_EXTENSIONS,
+  // 路径处理函数
+  isHttpUrl,
+  isFileUrl,
+  isLocalReference,
+  normalizeLocalPath,
+  stripTitleFromUrl,
+  getExtension,
+  isImagePath,
+  isNonImageFilePath,
+  detectMediaType,
+  // 媒体提取函数
+  extractMediaFromText,
+  extractImagesFromText,
+  extractFilesFromText,
+} from "./media-parser.js";
+
+// 媒体 IO
+export {
+  // 类型
+  type MediaReadResult,
+  type MediaReadOptions,
+  type DownloadToTempFileResult,
+  type DownloadToTempFileOptions,
+  type FinalizeInboundMediaOptions,
+  type PruneInboundMediaDirOptions,
+  type PathSecurityOptions,
+  // 错误类
+  FileSizeLimitError,
+  MediaTimeoutError,
+  PathSecurityError,
+  // 路径安全
+  validatePathSecurity,
+  getDefaultAllowedPrefixes,
+  // MIME 类型
+  getMimeType,
+  // 媒体读取函数
+  fetchMediaFromUrl,
+  readMediaFromLocal,
+  readMedia,
+  readMediaBatch,
+  downloadToTempFile,
+  finalizeInboundMediaFile,
+  pruneInboundMediaDir,
+  cleanupFileSafe,
+} from "./media-io.js";