koishi-plugin-kkk 1.0.0

package/src/karin/module/utils/ErrorHandler/handler.ts

@@ -0,0 +1,124 @@
+import type { ApiErrorData } from '@template/template/other/handlerError/components/types'
+import { logger, type Message } from 'node-karin'
+
+import { getBuildMetadata } from '@/module'
+import { EmojiReactionManager } from '@/module/utils/EmojiReaction'
+
+import { sliceImageToMarkdown } from '../ImageSlice'
+import { renderErrorImage } from './render'
+import { sendErrorToAdmins, sendErrorToAllMasters, sendErrorToMaster, sendErrorToTrigger } from './sender'
+import { getStrategies } from './strategy'
+import type { ErrorContext, ErrorHandlerOptions } from './types'
+import { injectBotToEventForPushTask, isPushTask, parseLogsToStructured } from './utils'
+
+export const handleBusinessError = async (
+  error: Error,
+  options: ErrorHandlerOptions,
+  logs: ApiErrorData['logs'],
+  event: Message
+): Promise<'handled' | undefined> => {
+  try {
+    logger.debug(`[ErrorHandler] 开始处理业务错误: ${options.businessName}`)
+
+    const buildMetadata = getBuildMetadata()
+    const adapterInfo = event.bot?.adapter ? event.bot.adapter : undefined
+
+    const ctx: ErrorContext = {
+      error,
+      options,
+      logs,
+      event,
+      buildMetadata,
+      adapterInfo
+    }
+
+    for (const strategy of getStrategies()) {
+      if (strategy.match(ctx)) {
+        logger.debug(`[ErrorHandler] 匹配策略: ${strategy.name}`)
+        const result = await strategy.handle(ctx)
+        if (result === 'handled') return 'handled'
+      }
+    }
+
+    let img = await renderErrorImage(ctx)
+    /**
+     * 错误卡片也会超长（实测 2880×40000 / 45MB），直接发必被 QQ 拒收 ——
+     * 统一切成 markdown（分片拼接），失败就退回原图。
+     */
+    try {
+      const sliced = await sliceImageToMarkdown(img)
+      if (sliced) img = [sliced]
+    } catch (sliceError: any) {
+      logger.debug('[ErrorHandler] 错误卡片切片失败，按原图发送: ' + String(sliceError?.message ?? sliceError))
+    }
+    await sendErrorToTrigger(ctx, img)
+    await sendErrorToMaster(ctx, img)
+    await sendErrorToAllMasters(ctx, img)
+    // 「管理员」= 权限等级 > 4（Koishi 的主人档）
+    await sendErrorToAdmins(ctx, img).catch((err) => logger.warn('[ErrorHandler] 发送给管理员失败: ' + String(err)))
+
+    if (options.customErrorHandler) {
+      try {
+        await options.customErrorHandler(error, logs)
+      } catch (err) {
+        logger.error(`[ErrorHandler] 自定义错误处理失败: ${err}`)
+      }
+    }
+  } catch (handlerError) {
+    logger.error(`[ErrorHandler] 错误处理器本身发生错误: ${handlerError}`)
+    throw handlerError
+  }
+  return undefined
+}
+
+export const wrapWithErrorHandler = <R>(fn: (e: Message, next: () => unknown) => R | Promise<R>, options: ErrorHandlerOptions) => {
+  return async (e?: Message, next?: () => unknown): Promise<R> => {
+    const rawEvent = e
+    const normalizedEvent = await injectBotToEventForPushTask(rawEvent, options.businessName)
+    const normalizedNext = next ?? (() => undefined)
+    const shouldHandleEmoji = Boolean(rawEvent) && !isPushTask(rawEvent, options.businessName)
+    const emojiManager = shouldHandleEmoji ? new EmojiReactionManager(rawEvent as Message) : undefined
+    let processingTimer: NodeJS.Timeout | null = null
+    let successTimer: NodeJS.Timeout | null = null
+
+    if (emojiManager) {
+      await emojiManager.add('EYES')
+      processingTimer = setTimeout(() => {
+        emojiManager.add('PROCESSING').catch(() => {})
+      }, 1500)
+    }
+
+    const ctx = logger.runContext(async () => fn(normalizedEvent, normalizedNext))
+
+    try {
+      const result = await ctx.run()
+
+      if (emojiManager) {
+        successTimer = setTimeout(() => {
+          emojiManager.replace('PROCESSING', 'SUCCESS').catch(() => {})
+        }, 1500)
+      }
+
+      return result
+    } catch (error) {
+      if (processingTimer) clearTimeout(processingTimer)
+      if (successTimer) clearTimeout(successTimer)
+
+      if (emojiManager) {
+        const processingEmojiId = emojiManager['getPlatformEmojiId']('PROCESSING')
+        if (emojiManager.has(processingEmojiId)) {
+          await emojiManager.remove('PROCESSING')
+        }
+        await emojiManager.add('ERROR')
+      }
+
+      logger.debug('[ErrorHandler] 原始错误: ' + ((error as any)?.stack ?? String(error)))
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      const structuredLogs = parseLogsToStructured(ctx.logs())
+
+      const result = await handleBusinessError(error as Error, options, structuredLogs, normalizedEvent)
+      if (result === 'handled') return undefined as R
+      throw error
+    }
+  }
+}

package/src/karin/module/utils/ErrorHandler/index.ts

@@ -0,0 +1,48 @@
+/**
+ * 错误处理模块
+ *
+ * @remarks
+ * 提供统一的错误处理机制，支持：
+ * - 策略模式：注册自定义错误处理策略
+ * - 错误图片渲染：生成包含详细信息的错误报告图片
+ * - 多目标发送：支持发送给触发者、单个主人或所有主人
+ * - 函数包装器：自动捕获并处理业务函数中的错误
+ *
+ * @example
+ * ```ts
+ * import { wrapWithErrorHandler, registerErrorStrategy } from '@/module/utils/ErrorHandler'
+ *
+ * // 使用包装器
+ * const handler = wrapWithErrorHandler(
+ *   async (e) => await doSomething(e),
+ *   { businessName: '我的业务' }
+ * )
+ *
+ * // 注册自定义策略
+ * registerErrorStrategy({
+ *   name: 'MyStrategy',
+ *   match: (ctx) => ctx.error instanceof MyError,
+ *   handle: async (ctx) => 'handled'
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// 类型导出
+export type { ErrorContext, ErrorHandlerOptions, ErrorStrategy, RenderErrorOptions } from './types'
+
+// 策略注册
+export { getStrategies, registerErrorStrategy } from './strategy'
+
+// 渲染
+export { renderErrorImage } from './render'
+
+// 发送
+export { sendErrorToAllMasters, sendErrorToMaster, sendErrorToTrigger } from './sender'
+
+// 核心处理
+export { handleBusinessError, wrapWithErrorHandler } from './handler'
+
+// 工具函数
+export { getPushTaskBotId, isPushTask, parseLogsToStructured, statBotId } from './utils'

package/src/karin/module/utils/ErrorHandler/render.ts

@@ -0,0 +1,180 @@
+import util from 'node:util'
+import { resolveFrameLogo } from '@/module/utils/Render'
+
+import { formatBuildTime, Render, Root } from '@/module'
+import { AmagiError } from '@/module/utils/amagiClient'
+
+import type { ErrorContext, RenderErrorOptions } from './types'
+
+/**
+ * 把 amagi 的 v7 错误摊成模板能直接印的一块。
+ *
+ * 非 amagi 异常返回 `undefined` —— 模板据此整块不渲染，而不是印一排空值。
+ * @param error - 捕获的异常
+ * @returns v7 分层错误信息，或 `undefined`
+ */
+const amagiDetailOf = (error: Error) => {
+  if (!(error instanceof AmagiError)) return undefined
+  const { meta } = error.envelope
+  return {
+    kind: error.kind,
+    code: error.amagiCode,
+    reason: error.reason,
+    retryable: error.retryable,
+    platformCode: error.rawError.platform?.code,
+    httpStatus: error.httpStatus,
+    requestId: meta?.requestId,
+    attempts: meta?.attempts,
+    durationMs: meta?.durationMs,
+    issues: error.issues,
+    // 逐个请求的明细。amagi 只在 debug: true 时填，封装层常开着
+    trace: meta?.trace
+  }
+}
+
+/**
+ * 取 amagi 失败信封里记的平台名。
+ * @param error - 捕获的异常
+ * @returns 平台名，非 amagi 异常时为 `undefined`
+ */
+const amagiPlatformOf = (error: Error): RenderErrorOptions['platform'] | undefined => {
+  if (!(error instanceof AmagiError)) return undefined
+  return error.envelope.meta?.platform
+}
+
+/**
+ * 自有属性的转储（`util.inspect`，带 ANSI）。
+ *
+ * 三样东西不进转储：`stack`（调用帧在上面的「错误堆栈」一节已经有结构高亮的那份）、
+ * `message` 与 `name`（栈首行就是 `名字: message`）。剩下的是调用点或上游挂上的
+ * 数据：Node 的 `errno` / `syscall`、三方库的响应体、OneBot 的 `cause`（`retcode`
+ * / `wording`）—— 这些堆栈里一个字都没有，是转储存在的全部理由。
+ *
+ * 一个都不剩就返回 `undefined`：引擎抛的 `TypeError: Cannot read properties of
+ * null` 只有 message，再来一块空转储没有意义。
+ *
+ * `cause` 链原样保留 —— 它的帧在上层栈里恰好被 `... N lines matching cause stack
+ * trace ...` 省略掉了，属于补充而非重复。
+ * @param error - 捕获的异常
+ * @returns 供模板渲染的转储文本，没有额外信息时为 `undefined`
+ */
+const dumpOf = (error: Error): string | undefined => {
+  const source = error as unknown as Record<string, unknown>
+  const skip = new Set(['stack', 'message', 'name'])
+  const own: Record<string, unknown> = {}
+  for (const key of Object.getOwnPropertyNames(error)) {
+    if (skip.has(key)) continue
+    try {
+      own[key] = source[key]
+    } catch {
+      // 取值就抛的 getter（罕见）跳过，别让转储把渲染带崩
+    }
+  }
+  if (Object.keys(own).length === 0) return undefined
+  return (
+    util
+      .inspect(own, { depth: 10, colors: true, breakLength: 120, showHidden: true })
+      // oxlint-disable-next-line no-control-regex
+      .replace(/\x1b\[90m/g, '\x1b[90;2m')
+      // oxlint-disable-next-line no-control-regex
+      .replace(/\x1b\[32m/g, '\x1b[31m')
+  )
+}
+
+/**
+ * 错误堆栈与对象转储：调用帧一律走纯文本，交给模板按结构上色。
+ *
+ * 对 `AmagiError` 做 `util.inspect(error, { depth: 10, showHidden: true })` 会把
+ * 同一份数据打印四遍 —— message 一遍、`showHidden` 把 message 当自有属性再打一遍
+ * （连 ANSI 转义都成了字面量）、`rawError` 一遍、`envelope` 又一遍，实测 118 行里
+ * 只有 7 行是调用帧，`trace` 里那条上百字符的签名 URL 出现两次。这些字段现在由
+ * 「解析库错误诊断」那一节单独渲染，堆栈只需要回答「从哪儿抛的」。
+ *
+ * 非 amagi 异常同样只把帧交给堆栈一节：`error.stack` 本身就是纯文本，模板据此按
+ * 结构上色（整对象转储一并塞进去的话，那些帧会掉进 ANSI 解析器里渲染成一片单色），
+ * 自有属性另走 {@link dumpOf} —— 上游协议实现那一层（OneBot 的 retcode/wording、
+ * Node 的 errno/syscall）没有调用栈，只能靠它呈现。
+ * @param error - 捕获的异常
+ * @param override - 调用方显式指定的堆栈文本
+ * @returns 纯文本堆栈；非 amagi 异常且确有 message / name 之外的自有属性时，附带转储
+ */
+/**
+ * 堆栈和转储都**截断**。
+ *
+ * 实测：不截断时错误卡片能渲染成 2880×40000（45MB）—— 光渲染要 20 秒，
+ * 而这么大的图 QQ 必然拒收，等于「报错本身也发不出来」，用户什么都看不到。
+ * 卡片只需要让人一眼看出错在哪，前几千字符足够，完整内容仍在日志里。
+ */
+const MAX_STACK_CHARS = 4000
+const MAX_DUMP_CHARS = 4000
+
+const truncateText = (text: string | undefined, limit: number): string => {
+  const value = String(text ?? '')
+  if (value.length <= limit) return value
+  return value.slice(0, limit) + '\n…（已截断，完整内容见日志；原文共 ' + value.length + ' 字符）'
+}
+
+const stackPartsOf = (error: Error, override?: string): { stack: string; dump?: string } => {
+  if (override) return { stack: truncateText(override, MAX_STACK_CHARS) }
+  if (error instanceof AmagiError) return { stack: truncateText(error.stack ?? error.message, MAX_STACK_CHARS) }
+  return { stack: truncateText(error.stack ?? error.message, MAX_STACK_CHARS), dump: truncateText(dumpOf(error), MAX_DUMP_CHARS) }
+}
+
+/**
+ * 渲染错误图片
+ *
+ * @param ctx - 错误处理上下文
+ * @param opts - 渲染选项，可覆盖默认值
+ * @returns 渲染后的图片元素数组
+ *
+ * @remarks
+ * 使用 `other/handlerError` 模板渲染错误信息图片，
+ * 包含错误详情、日志、触发命令、版本信息等
+ *
+ * @example
+ * ```ts
+ * const img = await renderErrorImage(ctx, {
+ *   platform: 'bilibili',
+ *   errorName: 'RiskControl',
+ *   errorMessage: '风控验证'
+ * })
+ * await event.reply(img)
+ * ```
+ */
+export const renderErrorImage = async (ctx: ErrorContext, opts: RenderErrorOptions = {}) => {
+  const { error, options, logs, event, buildMetadata, adapterInfo } = ctx
+  const amagi = amagiDetailOf(error)
+  const { stack, dump } = stackPartsOf(error, opts.stack)
+
+  return Render(event, 'other/handlerError', {
+    type: 'business_error',
+    // amagi 的失败信封自带 meta.platform，比调用点顺手传的更准；
+    // 小红书的报错原先一律落到 system，就是因为这里没人传
+    platform: opts.platform ?? amagiPlatformOf(error) ?? 'system',
+    error: {
+      // 这几个字段模板里会直接做字符串处理（例如 version.startsWith），
+      // 取不到值时给空串，避免错误卡片自己再崩一次
+      message: String(opts.errorMessage || error?.message || '未知错误'),
+      name: String(opts.errorName || error?.name || 'Error'),
+      stack: stack ?? '',
+      dump: dump ?? '',
+      businessName: options?.businessName ?? ''
+    },
+    amagi,
+    method: options.businessName,
+    timestamp: new Date().toISOString(),
+    logs: logs?.slice().reverse(),
+    triggerCommand: event?.msg || '未知命令或处于非消息环境',
+    frameworkVersion: Root.karinVersion,
+    // 和主布局用同一份 logo（跨模块导入以免又出现「旧头像」）
+    frameworkLogo: resolveFrameLogo(),
+    pluginVersion: Root.pluginVersion,
+    buildTime: buildMetadata?.buildTime ? formatBuildTime(buildMetadata.buildTime) : undefined,
+    commitHash: buildMetadata?.commitHash,
+    // 之前这里可能传 undefined，模板读 adapterInfo.version.startsWith 直接 SSR 崩掉
+    adapterInfo: adapterInfo ?? { name: '未知适配器', version: '' },
+    isVerification: opts.isVerification,
+    verificationUrl: opts.verificationUrl,
+    share_url: opts.share_url
+  })
+}

package/src/karin/module/utils/ErrorHandler/sender.ts

@@ -0,0 +1,192 @@
+import karin, { config, logger, segment } from 'node-karin'
+
+import { getReachableMasterBots } from '../bot'
+import { Config } from '../Config'
+import type { renderErrorImage } from './render'
+import type { ErrorContext } from './types'
+import { isPushTask } from './utils'
+
+/**
+ * 发送错误图片给触发者
+ *
+ * @param ctx - 错误处理上下文
+ * @param img - 渲染后的错误图片
+ *
+ * @remarks
+ * 仅当配置 `errorLogSendTo` 包含 `'trigger'` 且存在 event 时发送
+ */
+export const sendErrorToTrigger = async (ctx: ErrorContext, img: Awaited<ReturnType<typeof renderErrorImage>>) => {
+  const { event, options } = ctx
+
+  if (!event) return
+  if (isPushTask(event, options.businessName)) return
+  if (!Config.app.errorLogSendTo.some((item) => item === 'trigger')) return
+
+  try {
+    await event.reply(img)
+  } catch (err) {
+    logger.error(`[ErrorHandler] 发送错误消息给触发者失败: ${err}`)
+  }
+}
+
+/**
+ * 发送错误图片给单个主人
+ *
+ * @param ctx - 错误处理上下文
+ * @param img - 渲染后的错误图片
+ * @param customPrefix - 自定义消息前缀（可选）
+ *
+ * @remarks
+ * 发送给除 `'console'` 外的第一个主人，
+ * 仅当配置 `errorLogSendTo` 包含 `'master'` 时发送
+ *
+ * @example
+ * ```ts
+ * const img = await renderErrorImage(ctx)
+ * await sendErrorToMaster(ctx, img, '自定义前缀消息')
+ * ```
+ */
+export const sendErrorToMaster = async (ctx: ErrorContext, img: Awaited<ReturnType<typeof renderErrorImage>>, customPrefix?: string) => {
+  const { options, event } = ctx
+
+  if (!Config.app.errorLogSendTo.some((item) => item === 'master')) return
+
+  const isPush = isPushTask(event, options.businessName)
+  const target = await resolveSingleMasterTarget(event, isPush)
+  if (!target) return
+
+  try {
+    const prefix = customPrefix || (await buildErrorPrefix(ctx, isPush, target.botId))
+    await karin.sendMaster(target.botId, target.master, [segment.text(prefix), ...img])
+  } catch (err) {
+    logger.error(`[ErrorHandler] 发送错误消息给主人失败: ${err}`)
+  }
+}
+
+/**
+ * 发送错误图片给所有主人
+ *
+ * @param ctx - 错误处理上下文
+ * @param img - 渲染后的错误图片
+ * @param customPrefix - 自定义消息前缀（可选）
+ *
+ * @remarks
+ * 发送给所有主人（排除 `'console'`），
+ * 仅当配置 `errorLogSendTo` 包含 `'allMasters'` 时发送，
+ * 内部会去重避免重复发送
+ *
+ * @example
+ * ```ts
+ * const img = await renderErrorImage(ctx)
+ * await sendErrorToAllMasters(ctx, img)
+ * ```
+ */
+export const sendErrorToAllMasters = async (
+  ctx: ErrorContext,
+  img: Awaited<ReturnType<typeof renderErrorImage>>,
+  customPrefix?: string
+) => {
+  const { options, event } = ctx
+
+  if (!Config.app.errorLogSendTo.some((item) => item === 'allMasters')) return
+
+  const isPush = isPushTask(event, options.businessName)
+  const targets = await resolveAllMasterTargets(event, isPush)
+  if (targets.length === 0) return
+
+  const prefix = customPrefix || (await buildErrorPrefix(ctx, isPush, targets[0].botId))
+  const notifiedSet = new Set<string>()
+
+  for (const target of targets) {
+    const key = `${target.botId}:${target.master}`
+    if (notifiedSet.has(key)) continue
+
+    try {
+      await karin.sendMaster(target.botId, target.master, [segment.text(prefix), ...img])
+      notifiedSet.add(key)
+      logger.debug(`[ErrorHandler] 已发送错误消息给主人: ${target.master} (via ${target.botId})`)
+    } catch (err) {
+      logger.error(`[ErrorHandler] 发送错误消息给主人 (${target.master}) 失败: ${err}`)
+    }
+  }
+}
+
+/**
+ * 发送错误图片给**管理员**（权限等级 > 4）。
+ *
+ * Koishi 这边「权限 > 4」就是主人（master）这一档，所以实现上直接复用「发给所有主人」，
+ * 只是配置取值叫 `'admin'`、面板上显示「管理员（权限等级 > 4）」；旧的 `'allMasters'` 仍然兼容。
+ */
+export const sendErrorToAdmins = async (
+  ctx: ErrorContext,
+  img: Awaited<ReturnType<typeof renderErrorImage>>,
+  customPrefix?: string
+) => {
+  const list: any = Config.app.errorLogSendTo
+  if (!list.some((item: string) => item === 'admin' || item === 'allMasters')) return
+  return await sendErrorToAllMasters(ctx, img, customPrefix)
+}
+
+/**
+ * 解析单个主人目标
+ *
+ * @param event - 错误事件上下文
+ * @param isPush - 是否为推送任务
+ *
+ * @returns
+ */
+const resolveSingleMasterTarget = async (
+  event: ErrorContext['event'],
+  isPush: boolean
+): Promise<{ master: string; botId: string } | undefined> => {
+  if (isPush) {
+    const bindings = await getReachableMasterBots()
+    const matched = bindings[0]
+    if (!matched) return undefined
+    return {
+      master: matched.master,
+      botId: matched.bot.account.selfId
+    }
+  }
+
+  const master = config.master().find((item) => item !== 'console')
+  const botId = event?.bot?.account.selfId ?? event?.selfId
+  if (!master || !botId) return undefined
+
+  return { master, botId }
+}
+
+const resolveAllMasterTargets = async (
+  event: ErrorContext['event'],
+  isPush: boolean
+): Promise<Array<{ master: string; botId: string }>> => {
+  const masters = config.master().filter((item) => item !== 'console')
+  if (masters.length === 0) return []
+
+  if (isPush) {
+    const bindings = await getReachableMasterBots(masters)
+    return bindings.map((item) => ({
+      master: item.master,
+      botId: item.bot.account.selfId
+    }))
+  }
+
+  const botId = event?.bot?.account.selfId ?? event?.selfId
+  if (!botId) return []
+
+  return masters.map((master) => ({ master, botId }))
+}
+
+const buildErrorPrefix = async (ctx: ErrorContext, isPush: boolean, botId: string): Promise<string> => {
+  const { options, event } = ctx
+
+  if (isPush) {
+    return `${options.businessName} 任务执行出错\n请尽快解决以消除警告`
+  }
+
+  const groupId = event && 'groupId' in event ? event.groupId : ''
+  const groupInfo = await karin.getBot(botId)?.getGroupInfo(groupId)
+  const groupName = groupInfo?.groupName || '未知'
+
+  return `群：${groupName}(${groupId})\n${options.businessName} 任务执行出错\n请尽快解决以消除警告`
+}

package/src/karin/module/utils/ErrorHandler/strategy.ts

@@ -0,0 +1,41 @@
+import { logger } from 'node-karin'
+
+import type { ErrorStrategy } from './types'
+
+/**
+ * 策略注册表
+ * @internal
+ */
+const strategies: ErrorStrategy[] = []
+
+/**
+ * 注册错误处理策略
+ *
+ * @param strategy - 要注册的错误处理策略
+ *
+ * @remarks
+ * 策略按注册顺序依次匹配，匹配成功后执行对应的处理函数
+ *
+ * @example
+ * ```ts
+ * registerErrorStrategy({
+ *   name: 'MyStrategy',
+ *   match: (ctx) => ctx.error instanceof MyError,
+ *   handle: async (ctx) => {
+ *     // 处理逻辑
+ *     return 'handled'
+ *   }
+ * })
+ * ```
+ */
+export const registerErrorStrategy = (strategy: ErrorStrategy) => {
+  strategies.push(strategy)
+  logger.debug(`[ErrorHandler] 注册策略: ${strategy.name}`)
+}
+
+/**
+ * 获取所有已注册的策略
+ *
+ * @returns 只读的策略数组
+ */
+export const getStrategies = (): readonly ErrorStrategy[] => strategies