koishi-plugin-kkk 1.0.0

package/src/karin/module/index.ts

@@ -0,0 +1,37 @@
+/**
+ * \`@/module\` 桶文件。
+ *
+ * Koishi 移植说明：**不要只依赖 \`export *\`**。
+ * tsc 对 CJS 的 \`export *\` 是「运行时枚举源模块的键名再绑定」，一旦存在环形依赖
+ * （utils → Render → coverTheme → \`@/module\` → utils），barrel 被要求时 utils 可能还没加载完，
+ * 于是只绑到前半截导出 —— 表现为 \`@/module\` 上缺少 \`Render\` / \`Common\`，
+ * 消费方直接 \`not a function\`（抖音登录、推送等模块会中招）。
+ *
+ * 这里保留 \`export *\`（类型与新增导出照旧可用），同时对**运行时确实存在的值**显式再导出一次：
+ * 显式再导出的绑定与加载顺序无关（tsc 会生成惰性 getter），从此不再受环形依赖影响。
+ */
+export * from './db'
+export * from './utils'
+
+// —— 显式兜底（值导出） ——
+export {
+  BilibiliDBBase, DouyinDBBase, METRIC_BUCKETS, StatisticsDBBase,
+  bilibiliDB, bilibiliDBInstance, bootstrapDatabases, cleanOldDynamicCache,
+  douyinDB, douyinDBInstance, getBilibiliDB, getDouyinDB,
+  getStatisticsDB, initAllDatabases, resolveMetricBucket, statisticsDB,
+  statisticsDBInstance,
+} from './db'
+
+export {
+  BASE_HEADERS, Base, Common, Count,
+  DEFAULT_THROTTLE_CONFIG, Downloader, EMOJI_IDS, EmojiReactionManager,
+  Network, Networks, Render, Root,
+  ThrottleStream, baseHeaders, buildFallbackHtml, buildGoogleMotionPhoto,
+  compressVideo, downloadFile, downloadVideo, extractTotalBytesFromHeaders,
+  fixM4sFile, formatBuildTime, formatBytes, getBuildMetadata,
+  getEmojiId, getErrorDescription, getImageDownloader, getImageMetadata,
+  getMediaDuration, getMediaFrameRate, isRecoverableNetworkError, isThrottlingError,
+  loopVideo, loopVideoWithTransition, mergeVideoAudio, processImageUrl,
+  processImageUrls, processLocalImageFile, sanitizeHeaders, setEmojiReaction,
+  statBotId, uploadFile,
+} from './utils'

package/src/karin/module/server/constants/routes.ts

@@ -0,0 +1,53 @@
+/**
+ * 路由常量定义
+ */
+
+// 主路由前缀
+export const KKK_PREFIX = '/kkk'
+
+// 子路由前缀
+/** 静态文件 */
+export const ASSETS_PREFIX = '/assets'
+/** SSR 页面 */
+export const SSR_PREFIX = '/ssr'
+/** API v1 */
+export const API_V1_PREFIX = '/v1'
+
+// 完整路径
+/** 静态文件完整路径 */
+export const FULL_ASSETS_PREFIX = `${KKK_PREFIX}${ASSETS_PREFIX}`
+/** SSR 页面完整路径 */
+export const FULL_SSR_PREFIX = `${KKK_PREFIX}${SSR_PREFIX}`
+/** API v1 完整路径 */
+export const FULL_API_V1_PREFIX = `${KKK_PREFIX}${API_V1_PREFIX}`
+
+// API 路由
+export const ROUTES = {
+  // Bot 管理
+  /** 获取所有 Bot */
+  BOTS: '/bots',
+  /** 获取指定 Bot 信息 */
+  BOT_INFO: '/bots/:botId',
+  /** 获取指定 Bot 的群列表 */
+  BOT_GROUPS: '/bots/:botId/groups',
+  /** 获取指定 Bot 群信息 */
+  BOT_GROUP_INFO: '/bots/:botId/groups/:groupId',
+
+  // 群组管理
+  /** 获取所有群组 */
+  GROUPS_BATCH: '/groups/batch',
+
+  // 配置管理
+  /** 获取插件所有配置 */
+  CONFIG: '/config',
+
+  // 视频流
+  /** 获取视频流 */
+  VIDEO_STREAM: '/stream/:filename',
+  /** 获取视频事件 */
+  VIDEO_EVENTS: '/video/:filename/events',
+
+  // SSR 页面
+  /** 视频播放页面 */
+  VIDEO_PAGE: '/video/:filename'
+} as const

package/src/karin/module/server/controllers/bots.ts

@@ -0,0 +1,289 @@
+/**
+ * Bot 管理 API
+ */
+import { createServerErrorResponse, createSuccessResponse, karin, logger } from 'node-karin'
+import type { RequestHandler } from 'node-karin/express'
+
+/**
+ * Bot 信息接口
+ */
+export interface BotInfo {
+  id: string
+  name: string
+  avatar: string
+  isOnline: boolean
+}
+
+/**
+ * 群组简要信息接口
+ */
+export interface GroupBriefInfo {
+  id: string
+  name: string
+  avatar: string
+}
+
+/**
+ * 群组详情接口
+ */
+export interface GroupDetailInfo extends GroupBriefInfo {
+  botId: string
+  botName: string
+  botAvatar: string
+  memberCount?: number
+  isOnline: boolean
+}
+
+const getOnlineBotById = (botId: string) => {
+  return karin.getAllBotList().find((item) => item.bot.account.selfId === botId)?.bot
+}
+
+const getBotAvatar = async (bot: ReturnType<typeof getOnlineBotById>, botId: string) => {
+  if (!bot) return ''
+
+  try {
+    return (await bot.getAvatarUrl(botId)) || ''
+  } catch (e) {
+    logger.warn(`[BotsAPI] 获取 Bot 头像失败 ${botId}:`, e)
+    return ''
+  }
+}
+
+/**
+ * 获取所有在线 Bot 列表
+ * GET /api/v1/bots
+ */
+export const getBots: RequestHandler = async (_req, res) => {
+  try {
+    const botList = karin.getAllBotList()
+    const bots: BotInfo[] = []
+
+    for (const item of botList) {
+      const bot = item.bot
+      // 跳过 console bot
+      if (bot.account.name === 'console') continue
+
+      let avatar = ''
+      try {
+        avatar = (await bot.getAvatarUrl(bot.account.selfId)) || ''
+      } catch (e) {
+        logger.warn(`[BotsAPI] 获取 Bot 头像失败 ${bot.account.selfId}:`, e)
+      }
+
+      bots.push({
+        id: bot.account.selfId,
+        name: bot.account.name || bot.account.selfId,
+        avatar,
+        isOnline: true
+      })
+    }
+
+    return createSuccessResponse(res, bots)
+  } catch (error) {
+    logger.error('[BotsAPI] 获取 Bot 列表失败:', error)
+    return createServerErrorResponse(res, '获取 Bot 列表失败')
+  }
+}
+
+/**
+ * 获取指定 Bot 信息
+ * GET /api/v1/bots/:botId
+ */
+export const getBotInfo: RequestHandler = async (req, res) => {
+  try {
+    const botId = Array.isArray(req.params.botId) ? req.params.botId[0] : req.params.botId
+
+    if (!botId) {
+      return createServerErrorResponse(res, '缺少 botId 参数')
+    }
+
+    const bot = getOnlineBotById(botId)
+
+    if (!bot || bot.account.name === 'console') {
+      return createServerErrorResponse(res, 'Bot 不存在或不在线')
+    }
+
+    const botInfo: BotInfo = {
+      id: bot.account.selfId,
+      name: bot.account.name || bot.account.selfId,
+      avatar: await getBotAvatar(bot, bot.account.selfId),
+      isOnline: true
+    }
+
+    return createSuccessResponse(res, botInfo)
+  } catch (error) {
+    logger.error('[BotsAPI] 获取 Bot 信息失败:', error)
+    return createServerErrorResponse(res, '获取 Bot 信息失败')
+  }
+}
+
+/**
+ * 获取指定 Bot 的群列表
+ * GET /api/v1/bots/:botId/groups
+ */
+export const getBotGroups: RequestHandler = async (req, res) => {
+  try {
+    const botId = Array.isArray(req.params.botId) ? req.params.botId[0] : req.params.botId
+
+    if (!botId) {
+      return createServerErrorResponse(res, '缺少 botId 参数')
+    }
+
+    const botList = karin.getAllBotList()
+    const botItem = botList.find((item) => item.bot.account.selfId === botId)
+
+    if (!botItem) {
+      return createServerErrorResponse(res, 'Bot 不存在或不在线')
+    }
+
+    const bot = botItem.bot
+    const groupList = await bot.getGroupList()
+    const groups: GroupBriefInfo[] = []
+
+    for (const group of groupList) {
+      let avatar = ''
+      try {
+        avatar = (await bot.getGroupAvatarUrl(group.groupId)) || ''
+      } catch {
+        // 忽略头像获取失败
+      }
+
+      groups.push({
+        id: group.groupId,
+        name: group.groupName || group.groupId,
+        avatar
+      })
+    }
+
+    return createSuccessResponse(res, groups)
+  } catch (error) {
+    logger.error('[BotsAPI] 获取 Bot 群列表失败:', error)
+    return createServerErrorResponse(res, '获取群列表失败')
+  }
+}
+
+/**
+ * 获取指定 Bot 下的群信息
+ * GET /api/v1/bots/:botId/groups/:groupId
+ */
+export const getBotGroupInfo: RequestHandler = async (req, res) => {
+  try {
+    const botId = Array.isArray(req.params.botId) ? req.params.botId[0] : req.params.botId
+    const groupId = Array.isArray(req.params.groupId) ? req.params.groupId[0] : req.params.groupId
+
+    if (!botId || !groupId) {
+      return createServerErrorResponse(res, '缺少 botId 或 groupId 参数')
+    }
+
+    const bot = getOnlineBotById(botId)
+
+    if (!bot) {
+      return createServerErrorResponse(res, 'Bot 不存在或不在线')
+    }
+
+    let groupName = groupId
+    let groupAvatar = ''
+    let memberCount: number | undefined
+
+    try {
+      const groupInfo = await bot.getGroupInfo(groupId)
+      groupName = groupInfo?.groupName || groupName
+      memberCount = groupInfo?.memberCount
+      groupAvatar = (await bot.getGroupAvatarUrl(groupId)) || ''
+    } catch (e) {
+      logger.warn(`[BotsAPI] 获取群组信息失败 ${groupId}:`, e)
+    }
+
+    const groupDetail: GroupDetailInfo = {
+      id: groupId,
+      name: groupName,
+      avatar: groupAvatar,
+      botId: bot.account.selfId,
+      botName: bot.account.name || bot.account.selfId,
+      botAvatar: await getBotAvatar(bot, bot.account.selfId),
+      memberCount,
+      isOnline: true
+    }
+
+    return createSuccessResponse(res, groupDetail)
+  } catch (error) {
+    logger.error('[BotsAPI] 获取 Bot 群信息失败:', error)
+    return createServerErrorResponse(res, '获取群信息失败')
+  }
+}
+
+/**
+ * 批量获取群组信息
+ * POST /api/v1/groups/batch
+ * Body: { groups: [{ groupId: string, botId: string }] }
+ */
+export const getGroupsBatch: RequestHandler = async (req, res) => {
+  try {
+    const { groups } = req.body as { groups: { groupId: string; botId: string }[] }
+
+    if (!groups || !Array.isArray(groups)) {
+      return createServerErrorResponse(res, '缺少 groups 参数')
+    }
+
+    const result: Array<{
+      groupId: string
+      botId: string
+      groupName: string
+      groupAvatar: string
+      botName: string
+      botAvatar: string
+      isOnline: boolean
+    }> = []
+
+    const botList = karin.getAllBotList()
+
+    for (const item of groups) {
+      const botItem = botList.find((b) => b.bot.account.selfId === item.botId)
+
+      if (!botItem) {
+        result.push({
+          groupId: item.groupId,
+          botId: item.botId,
+          groupName: item.groupId,
+          groupAvatar: '',
+          botName: item.botId,
+          botAvatar: '',
+          isOnline: false
+        })
+        continue
+      }
+
+      const bot = botItem.bot
+      let groupName = item.groupId
+      let groupAvatar = ''
+      let botName = bot.account.name || item.botId
+      let botAvatar = ''
+
+      try {
+        const groupInfo = await bot.getGroupInfo(item.groupId)
+        if (groupInfo) {
+          groupName = groupInfo.groupName || groupName
+        }
+        groupAvatar = (await bot.getGroupAvatarUrl(item.groupId)) || ''
+        botAvatar = (await bot.getAvatarUrl(item.botId)) || ''
+      } catch (e) {
+        logger.warn(`[BotsAPI] 获取群组信息失败 ${item.groupId}:`, e)
+      }
+
+      result.push({
+        groupId: item.groupId,
+        botId: item.botId,
+        groupName,
+        groupAvatar,
+        botName,
+        botAvatar,
+        isOnline: true
+      })
+    }
+
+    return createSuccessResponse(res, result)
+  } catch (error) {
+    logger.error('[BotsAPI] 批量获取群组信息失败:', error)
+    return createServerErrorResponse(res, '批量获取群组信息失败')
+  }
+}

package/src/karin/module/server/controllers/config.ts

@@ -0,0 +1,85 @@
+/**
+ * 配置管理 API
+ * 提供配置的增删改查接口，供 APP 端使用
+ */
+import { createBadRequestResponse, createServerErrorResponse, createSuccessResponse } from 'node-karin'
+import type { Request, Response } from 'node-karin/express'
+
+import { reloadAmagiConfig } from '@/module/utils/amagiClient'
+import { Config } from '@/module/utils/Config'
+import type { ConfigType } from '@/types'
+
+/**
+ * 获取所有配置
+ * GET /kkk/web/v1/config
+ */
+export const getAllConfig = async (_req: Request, res: Response) => {
+  try {
+    const config = await Config.All()
+    return createSuccessResponse(res, config)
+  } catch (error: any) {
+    return createServerErrorResponse(res, `获取配置失败: ${error.message}`)
+  }
+}
+
+/**
+ * 批量更新配置
+ * POST /kkk/web/v1/config
+ * Body: Partial<ConfigType>
+ */
+export const updateAllConfig = async (req: Request, res: Response) => {
+  try {
+    const newConfig = req.body as Partial<ConfigType>
+
+    if (!newConfig || typeof newConfig !== 'object') {
+      return createBadRequestResponse(res, '请求体必须是有效的配置对象')
+    }
+
+    const oldConfig = await Config.All()
+    const results: { module: string; success: boolean; error?: string }[] = []
+    let needReloadAmagi = false
+
+    for (const [module, config] of Object.entries(newConfig)) {
+      try {
+        if (!(module in oldConfig)) {
+          results.push({ module, success: false, error: `配置模块 "${module}" 不存在` })
+          continue
+        }
+
+        const moduleName = module as keyof ConfigType
+        const success = await Config.ModifyPro(moduleName, config)
+        results.push({ module, success })
+
+        // amagi 配置变化需要重载客户端
+        if (success && moduleName === 'amagi') {
+          needReloadAmagi = true
+        }
+      } catch (error: any) {
+        results.push({ module, success: false, error: error.message })
+      }
+    }
+
+    // 同步数据库
+    if ('pushlist' in newConfig) {
+      await Config.syncConfigToDatabase()
+    }
+
+    if (needReloadAmagi) {
+      reloadAmagiConfig()
+    }
+
+    const allSuccess = results.every((r) => r.success)
+    const updatedConfig = await Config.All()
+
+    return createSuccessResponse(
+      res,
+      {
+        config: updatedConfig,
+        results
+      },
+      allSuccess ? '所有配置更新成功' : '部分配置更新失败'
+    )
+  } catch (error: any) {
+    return createServerErrorResponse(res, `配置更新失败: ${error.message}`)
+  }
+}

package/src/karin/module/server/controllers/video.ts

@@ -0,0 +1,212 @@
+/**
+ * 视频控制器
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { renderVideoPreviewPage } from '@template/template/_preview/render'
+import { createNotFoundResponse, logger } from 'node-karin'
+import type { RequestHandler } from 'node-karin/express'
+
+import { Common } from '@/module/utils'
+import { Config } from '@/module/utils/Config'
+
+/**
+ * 视频文件流传输
+ */
+export const getVideoStream: RequestHandler = (req, res) => {
+  const filenameParam = req.params.filename
+  const filename = Array.isArray(filenameParam) ? filenameParam[0] : filenameParam
+  if (!filename) {
+    createNotFoundResponse(res, '无效的文件名')
+    return
+  }
+  const videoPath = Common.validateVideoRequest(filename, res)
+
+  if (!videoPath) {
+    return
+  }
+
+  try {
+    const stats = fs.statSync(videoPath)
+    const fileSize = stats.size
+    const range = req.headers.range
+
+    if (range) {
+      const parts = range.replace(/bytes=/, '').split('-')
+      const start = parseInt(parts[0], 10)
+      const end = parts[1] ? parseInt(parts[1], 10) : fileSize - 1
+
+      if (start >= fileSize || end >= fileSize || start > end) {
+        res.status(416).send('请求范围不满足')
+        return
+      }
+
+      const chunksize = end - start + 1
+      const file = fs.createReadStream(videoPath, { start, end })
+      const head = {
+        'Content-Range': `bytes ${start}-${end}/${fileSize}`,
+        'Accept-Ranges': 'bytes',
+        'Content-Length': chunksize,
+        'Content-Type': 'video/mp4'
+      }
+
+      res.writeHead(206, head)
+      file.pipe(res)
+      file.on('error', (err) => {
+        logger.error(`读取视频文件流时出错 (Range: ${start}-${end}): ${err.message}`)
+        if (!res.writableEnded) {
+          res.end()
+        }
+      })
+    } else {
+      const head = {
+        'Content-Length': fileSize,
+        'Content-Type': 'video/mp4',
+        'Accept-Ranges': 'bytes'
+      }
+      res.writeHead(200, head)
+      const file = fs.createReadStream(videoPath)
+      file.pipe(res)
+      file.on('error', (err) => {
+        logger.error(`读取视频文件流时出错 (Full): ${err.message}`)
+        if (!res.headersSent) {
+          try {
+            createNotFoundResponse(res, '读取视频文件失败')
+          } catch (e) {
+            logger.error('发送读取错误响应失败:', e)
+            if (!res.writableEnded) {
+              res.end()
+            }
+          }
+        } else if (!res.writableEnded) {
+          res.end()
+        }
+      })
+    }
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      if (!res.headersSent) createNotFoundResponse(res, '视频文件未找到')
+      else if (!res.writableEnded) res.end()
+    } else {
+      logger.error(`处理视频数据请求时发生错误: ${error.message}`)
+      if (!res.headersSent) {
+        createNotFoundResponse(res, '服务器错误')
+      } else if (!res.writableEnded) {
+        res.end()
+      }
+    }
+  }
+}
+
+/**
+ * 视频播放页面（SSR）
+ */
+export const getVideoPage: RequestHandler = (req, res) => {
+  const filenameParam = req.params.filename
+  const filename = Array.isArray(filenameParam) ? filenameParam[0] : filenameParam
+  if (!filename) {
+    createNotFoundResponse(res, '无效的文件名')
+    return
+  }
+  const videoPath = Common.validateVideoRequest(filename, res)
+
+  if (!videoPath) {
+    return
+  }
+
+  const videoDataUrl = `/kkk/v1/stream/${encodeURIComponent(filename)}`
+  const previewInfo = Common.getVideoPreview(filename)
+  const removeCache = previewInfo?.removeCache ?? Config.app.removeCache
+  const createdAt = previewInfo?.createdAt ?? Date.now()
+  const expireAt = previewInfo?.expireAt ?? (removeCache ? createdAt + 10 * 60 * 1000 : undefined)
+  const htmlContent = renderVideoPreviewPage({
+    filename,
+    filePath: previewInfo?.filePath ?? videoPath,
+    videoUrl: videoDataUrl,
+    removeCache,
+    createdAt,
+    expireAt,
+    eventsUrl: `/kkk/v1/video/${encodeURIComponent(filename)}/events`
+  })
+
+  res.setHeader('Cache-Control', 'no-cache')
+  res.setHeader('Content-Type', 'text/html; charset=utf-8')
+  res.send(htmlContent)
+}
+
+/**
+ * 视频预览状态事件流（SSE）
+ */
+export const getVideoEvents: RequestHandler = (req, res) => {
+  const filenameParam = req.params.filename
+  const filename = Array.isArray(filenameParam) ? filenameParam[0] : filenameParam
+  if (!filename) {
+    createNotFoundResponse(res, '无效的文件名')
+    return
+  }
+  const safeName = path.basename(filename)
+  if (safeName !== filename || filename.includes('/') || filename.includes('\\')) {
+    createNotFoundResponse(res, '无效的文件名')
+    return
+  }
+
+  const previewInfo = Common.getVideoPreview(filename)
+  if (!previewInfo) {
+    createNotFoundResponse(res, '预览信息不存在')
+    return
+  }
+
+  res.setHeader('Content-Type', 'text/event-stream')
+  res.setHeader('Cache-Control', 'no-cache')
+  res.setHeader('Connection', 'keep-alive')
+  res.flushHeaders?.()
+
+  let timer: NodeJS.Timeout | null = null
+  const sendPayload = () => {
+    const currentInfo = Common.getVideoPreview(filename) ?? previewInfo
+    const now = Date.now()
+    const remainingMs = currentInfo.expireAt ? Math.max(currentInfo.expireAt - now, 0) : null
+    const fileMissing = currentInfo.filePath ? !fs.existsSync(currentInfo.filePath) : false
+    const removed = Boolean(currentInfo.removedAt) || (currentInfo.removeCache && remainingMs === 0 && fileMissing)
+    if (removed && !currentInfo.removedAt) {
+      Common.markVideoPreviewRemoved(currentInfo.filename)
+    }
+    const payload = {
+      filename: currentInfo.filename,
+      filePath: currentInfo.filePath,
+      removeCache: currentInfo.removeCache,
+      createdAt: currentInfo.createdAt,
+      expireAt: currentInfo.expireAt,
+      remainingMs,
+      removed,
+      serverNow: now
+    }
+    res.write(`data: ${JSON.stringify(payload)}\n\n`)
+    return removed
+  }
+
+  const shouldCloseImmediately = sendPayload()
+  if (shouldCloseImmediately) {
+    res.end()
+    return
+  }
+
+  timer = setInterval(() => {
+    const removed = sendPayload()
+    if (removed) {
+      if (timer) {
+        clearInterval(timer)
+        timer = null
+      }
+      res.end()
+    }
+  }, 1000)
+
+  res.on('close', () => {
+    if (timer) {
+      clearInterval(timer)
+      timer = null
+    }
+  })
+}

package/src/karin/module/server/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Server 模块导出
+ */
+export * from './constants/routes'
+export * from './controllers/bots'
+export * from './controllers/config'
+export * from './controllers/video'
+export * from './middlewares/auth'
+
+// 初始化路由
+import './routes'