koishi-plugin-kkk 1.0.0

package/src/karin/module/utils/amagiClient.ts

@@ -0,0 +1,368 @@
+import Client, {
+  type AmagiError as AmagiErrorContract,
+  type AmagiFailure,
+  type AmagiSuccess,
+  type SuccessBilibiliFetcher,
+  type SuccessDouyinFetcher,
+  type SuccessKuaishouFetcher,
+  type SuccessXiaohongshuFetcher,
+  // 包级 fetcher：抖音的 passport（扫码登录）只在它上面，client 上绑定过的精简版没有这些方法
+  douyinFetcher as amagiDouyinFetcher
+} from '@ikenxuan/amagi'
+import { logger } from 'node-karin'
+
+import { Config } from './Config'
+import { createBilibiliLoginSession, createDouyinLoginSession } from './loginSession'
+
+/** v7 客户端实例 */
+export type AmagiClient = ReturnType<typeof Client>
+
+/** 四个平台的键，用来在类型层重建 client 形状 */
+type PlatformKey = 'bilibili' | 'douyin' | 'kuaishou' | 'xiaohongshu'
+
+/** 把一个平台模块的 `fetcher` 换成「只保留成功分支」的那份类型 */
+type WithSuccessFetcher<M, F> = Omit<M, 'fetcher'> & { fetcher: F }
+
+/**
+ * 失败必抛的 client：四个平台的 `fetcher` 换成成功信封形态，其余键原样。
+ *
+ * 运行时由 {@link throwOnFailure} 保证「失败一律抛」，类型上必须同步声明成成功分支 —— 否则
+ * 未收窄的 `AmagiResult` 让每一处 `.data` 都带 `| undefined`。`Success*Fetcher` 只能用 amagi
+ * 提供的那份：fetcher 方法是泛型签名，自己 infer 会按约束实例化类型参数，默认值丢失，`data` 退化成 `unknown`。
+ */
+type ThrowingClient = Omit<AmagiClient, PlatformKey> & {
+  bilibili: WithSuccessFetcher<AmagiClient['bilibili'], SuccessBilibiliFetcher>
+  douyin: WithSuccessFetcher<AmagiClient['douyin'], SuccessDouyinFetcher>
+  kuaishou: WithSuccessFetcher<AmagiClient['kuaishou'], SuccessKuaishouFetcher>
+  xiaohongshu: WithSuccessFetcher<AmagiClient['xiaohongshu'], SuccessXiaohongshuFetcher>
+}
+
+/**
+ * 平台业务码。v7 的三种码各归各位：平台业务码 `error.platform.code`、HTTP 状态 `error.http.status`、
+ * amagi 自己的码 `error.code`（字符串）。按平台码分流的地方（B站 `-352` 风控、`-111` csrf 失效、
+ * `12061` 关闭评论区）要的是第一种；平台没给就退 HTTP 状态，再退 0。
+ */
+const legacyCode = (error: AmagiErrorContract, envelope?: AmagiFailure): number => {
+  const platformCode = error.platform?.code
+  if (typeof platformCode === 'number') return platformCode
+  if (typeof platformCode === 'string' && platformCode.trim() !== '' && Number.isFinite(Number(platformCode))) {
+    return Number(platformCode)
+  }
+  // Koishi 移植补充：已发布的 amagi 6.6.0 失败信封是
+  // { success:false, error:{ errorDescription, requestType, requestUrl, responseCode }, message, code, data }
+  // —— 平台业务码在 error.responseCode / 顶层 code 上，没有 v7 的 kind/platform/http 字段。
+  const anyError = error as any
+  if (typeof anyError.responseCode === 'number') return anyError.responseCode
+  if (typeof (envelope as any)?.code === 'number') return (envelope as any).code
+  return error.http?.status ?? 0
+}
+
+/**
+ * 一行说清一次失败：`[大类/码] 平台原文 (端点 平台码 HTTP requestId attempts)`。
+ * `message` 会被 `logger.warn(...)` 直接拼进日志行，塞整个信封的转储会把日志顶成一屏 ANSI。
+ */
+const describeFailure = (envelope: AmagiFailure): string => {
+  const error: any = envelope.error ?? {}
+  const meta: any = (envelope as any).meta
+  const kind = error.kind ?? (error.requestType ? 'api' : 'unknown')
+  const code = error.code ?? (envelope as any).code
+  const reason = error.errorDescription ?? error.message ?? (envelope as any).message ?? '未知错误'
+  const facts = [
+    error.requestType ?? meta?.endpoint,
+    error.requestUrl ? String(error.requestUrl).split('?')[0].slice(0, 80) : undefined,
+    error.responseCode === undefined ? undefined : `平台码 ${error.responseCode}`,
+    error.platform?.code === undefined ? undefined : `平台码 ${error.platform.code}`,
+    error.http?.status === undefined ? undefined : `HTTP ${error.http.status}`,
+    meta?.requestId === undefined ? undefined : `requestId=${meta.requestId}`,
+    meta?.attempts === undefined ? undefined : `attempts=${meta.attempts}`
+  ].filter((part): part is string => typeof part === 'string' && part !== '')
+
+  return `[${kind}/${code ?? '-'}] ${reason}${facts.length > 0 ? ` (${facts.join(' ')})` : ''}`
+}
+
+/** Amagi 失败异常：`message` 是一行摘要，结构化字段各有属性，完整信封在 {@link AmagiError.envelope} */
+export class AmagiError extends Error {
+  /** 平台业务码，见 {@link legacyCode} */
+  code: number
+  /** 平台原始响应体。v7 只在 `debug: true` 下填 `error.raw`（B站风控要读里面的 `v_voucher`） */
+  data: any
+  /** v7 错误契约本体，等价于失败信封的 `error` */
+  rawError: AmagiErrorContract
+  /** 错误大类 */
+  kind: AmagiErrorContract['kind']
+  /** amagi 自己的字符串错误码 */
+  amagiCode: AmagiErrorContract['code']
+  /** 平台返回的原文，不带前缀与归因 */
+  reason: string
+  /** 是否值得重试 */
+  retryable: boolean
+  /** 真实发生的 HTTP 状态 */
+  httpStatus?: number
+  /** 参数校验的字段级错误，仅 `kind === 'validation'` 时有 */
+  issues?: AmagiErrorContract['issues']
+  /** 整条失败信封，`meta.requestId` / `attempts` / `durationMs` 在里面 */
+  envelope: AmagiFailure
+
+  constructor(envelope: AmagiFailure) {
+    const error: any = (envelope as any).error ?? {}
+    super(describeFailure(envelope))
+    this.name = 'AmagiError'
+    this.code = legacyCode(error, envelope)
+    // 平台原始响应体：v7 在 error.raw，6.6.0 在信封顶层 data（B站风控要读里面的 v_voucher）
+    this.data = error.raw ?? (envelope as any).data
+    this.rawError = error
+    this.kind = (error.kind ?? 'api') as AmagiErrorContract['kind']
+    this.amagiCode = error.code ?? (envelope as any).code
+    this.reason = error.errorDescription ?? error.message ?? (envelope as any).message ?? '未知错误'
+    this.retryable = typeof error.retryable === 'boolean' ? error.retryable : false
+    this.httpStatus = error.http?.status
+    this.issues = error.issues
+    this.envelope = envelope
+  }
+}
+
+/**
+ * 判断一个值是不是失败信封。**只认 `success`**：v7 信封顶层没有 `code`（三种码各归各位），
+ * 拿 `code` 当特征判别恒假 —— 失败被原样透传、`try/catch` 全失效、取数失败但流程继续，且零编译错误。
+ */
+const isFailureEnvelope = (value: unknown): value is AmagiFailure => {
+  if (!value || typeof value !== 'object') return false
+  const envelope = value as Partial<AmagiFailure>
+  return envelope.success === false && typeof envelope.message === 'string' && !!envelope.error
+}
+
+/** 判断是不是 thenable，用来只包装异步方法 */
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  !!value && (typeof value === 'object' || typeof value === 'function') && typeof (value as PromiseLike<unknown>).then === 'function'
+
+/**
+ * 递归代理一个 fetcher 对象，把失败信封转成 `throw AmagiError`。返回类型与入参同形 ——
+ * 「只保留成功分支」是**类型层**由 {@link ThrowingClient} 声明的，这里只管运行时行为。
+ */
+const throwOnFailure = <T extends object>(target: T): T =>
+  new Proxy(target, {
+    get(obj: any, prop: string | symbol) {
+      const value = obj[prop]
+
+      if (typeof value === 'function') {
+        return (...args: unknown[]) => {
+          const returned = value.apply(obj, args)
+          // 同步方法原样放行：包成 async 会把返回值套一层 Promise，破坏语义
+          if (!isThenable(returned)) return returned
+          return returned.then((result: unknown) => {
+            if (isFailureEnvelope(result)) throw new AmagiError(result)
+            return result
+          })
+        }
+      }
+
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return throwOnFailure(value)
+      }
+
+      return value
+    }
+  })
+
+/** 解析库基类 */
+export class AmagiBase {
+  /**
+   * 原始 v7 客户端。
+   *
+   * `events` / `on` / `once` / `login` / `startServer` 从这里取 —— 它们不是 fetcher，
+   * 不该被「失败必抛」的代理碰（`on` 返回退订函数，包成 async 就废了）。
+   */
+  rawAmagi: AmagiClient
+  /** 解析库实例，四个平台的 fetcher 失败即抛 */
+  amagi: ThrowingClient
+  /** 当前客户端使用的配置快照，用于避免文件监听与显式重载造成重复初始化 */
+  private configSignature: string
+
+  constructor() {
+    const client = this.createAmagiClient()
+    this.rawAmagi = client
+    this.amagi = this.wrapAmagiClient(client)
+    this.configSignature = this.getConfigSignature()
+  }
+
+  /** 获取会影响 Amagi 运行状态的配置快照 */
+  private getConfigSignature = () => JSON.stringify(Config.amagi)
+
+  /** 创建解析库实例 */
+  protected createAmagiClient = (): AmagiClient => {
+    const amagi = Config.amagi
+    return Client({
+      cookies: amagi.cookies || {},
+      request: {
+        timeout: amagi.timeout,
+        headers: { 'User-Agent': amagi['User-Agent'] },
+        proxy: amagi.proxy?.switch ? amagi.proxy : false
+      },
+      // B站风控要读失败响应里的 `v_voucher`，而 v7 只在 debug 下才填 `error.raw`
+      // —— 不开的话 `AmagiError.data` 连键都没有，整条风控验证流程静默失效
+      debug: true
+    })
+  }
+
+  /**
+   * 重载配置 - 重新创建 Amagi Client 实例
+   * @returns 配置发生变化并完成重载时返回 true
+   */
+  reloadConfig() {
+    const nextConfigSignature = this.getConfigSignature()
+    if (nextConfigSignature === this.configSignature) {
+      logger.debug('[AmagiClient] 配置未变化，跳过重复重载')
+      return false
+    }
+
+    logger.debug('[AmagiClient] 检测到配置变化，正在重载...')
+    const client = this.createAmagiClient()
+    this.rawAmagi = client
+    this.amagi = this.wrapAmagiClient(client)
+    this.configSignature = nextConfigSignature
+    logger.debug('[AmagiClient] 配置重载完成')
+    return true
+  }
+
+  /** 只把四个平台的 fetcher 换成失败必抛形态，client 的其余键原样带过去 */
+  protected wrapAmagiClient = (client: AmagiClient): ThrowingClient =>
+    ({
+      ...client,
+      bilibili: { ...client.bilibili, fetcher: throwOnFailure(client.bilibili.fetcher) },
+      douyin: { ...client.douyin, fetcher: throwOnFailure(client.douyin.fetcher) },
+      kuaishou: { ...client.kuaishou, fetcher: throwOnFailure(client.kuaishou.fetcher) },
+      xiaohongshu: { ...client.xiaohongshu, fetcher: throwOnFailure(client.xiaohongshu.fetcher) }
+    }) as ThrowingClient
+}
+
+/** 软错误码：命中这些平台业务码时不抛异常，按失败信封返回。Bilibili `12061` - UP主已关闭评论区 */
+export const SOFT_ERROR_CODES = {
+  BILIBILI_COMMENTS_DISABLED: 12061
+} as const
+
+/** 被 {@link softFetch} 放行的软失败：失败信封 + 压平后的平台业务码 */
+export type SoftFailure = AmagiFailure & { code: number }
+
+/** {@link softFetch} 的返回：要么成功信封，要么被放行的软失败 */
+export type SoftResult<T> = AmagiSuccess<T> | SoftFailure
+
+/**
+ * 调用 amagi fetcher 方法，允许特定平台业务码以失败信封返回而不是抛异常。
+ * @param fn - 经过代理包装的 amagi 方法调用
+ * @param allowedCodes - 不应抛出异常的平台业务码列表
+ * @returns 成功信封，或命中 `allowedCodes` 的软失败
+ */
+export const softFetch = async <T>(fn: () => Promise<AmagiSuccess<T>>, allowedCodes: number[]): Promise<SoftResult<T>> => {
+  try {
+    return await fn()
+  } catch (err) {
+    if (err instanceof AmagiError && allowedCodes.includes(err.code)) {
+      return { ...err.envelope, code: err.code }
+    }
+    throw err
+  }
+}
+
+/**
+ * {@link softFetch} 的结果是否命中某个软错误码。
+ *
+ * 是类型守卫而不是 `result.code === x`：`code` 的类型是 `number` 不是字面量，
+ * 直接比较不会收窄联合，`else` 分支里的 `data` 仍是 `T | undefined`。
+ */
+export const isSoftFailure = <T>(result: SoftResult<T>, ...codes: number[]): result is SoftFailure =>
+  !result.success && codes.includes(result.code)
+
+const amagiClientInstance = new AmagiBase()
+
+type AmagiReloadListener = () => void
+
+/** 需要随 Amagi Client 一同刷新的运行时资源，例如已经挂载的 HTTP Router */
+const amagiReloadListeners = new Set<AmagiReloadListener>()
+
+/**
+ * 注册 Amagi 配置重载监听器。
+ * @param listener - 重载后要执行的回调
+ * @returns 注销当前监听器的函数
+ */
+export const registerAmagiReloadListener = (listener: AmagiReloadListener) => {
+  amagiReloadListeners.add(listener)
+  return () => amagiReloadListeners.delete(listener)
+}
+
+/**
+ * 四个平台的「失败必抛」fetcher。
+ *
+ * 类型必须显式标注：不标的话 TS 要在声明产物里展开 fetcher 的结构，而响应类型桶只导出
+ * `BilibiliVideoInfoResponse` 这样的具名别名、不导出底层的 `*_V0`，展开时叫不出名来报 TS2883。
+ */
+export let bilibiliFetcher: SuccessBilibiliFetcher = amagiClientInstance.amagi.bilibili.fetcher
+
+export let douyinFetcher: SuccessDouyinFetcher = amagiClientInstance.amagi.douyin.fetcher
+
+export let kuaishouFetcher: SuccessKuaishouFetcher = amagiClientInstance.amagi.kuaishou.fetcher
+
+export let xiaohongshuFetcher: SuccessXiaohongshuFetcher = amagiClientInstance.amagi.xiaohongshu.fetcher
+
+/**
+ * 原始 v7 客户端。扫码登录会话（`douyin.login` / `bilibili.login`）、实例级事件总线
+ * （`events` / `on` / `once`）与 `startServer` 都从这里取。
+ *
+ * 返回类型显式写成 {@link AmagiClient}：不写的话 TS 要在声明产物里展开这个结构，
+ * 会碰到 amagi 内部才叫得出名字的类型（如 `SearchNoteType`），报 TS4023。
+ */
+/**
+ * 原始 v7 客户端，并补上 v7 才有的登录会话命名空间（`bilibili.login` / `douyin.login`）。
+ *
+ * 已发布的 amagi 6.6.0 的 client 上没有 `login`，上游登录代码会直接读崩，
+ * 因此这里用 Proxy 在读取 `bilibili` / `douyin` 时挂上本地实现的会话（见 ./loginSession）。
+ * 其余属性原样转发，并对函数做 bind，保证 `events` / `on` / `once` / `startServer` 行为不变。
+ */
+const clientWrapperCache = new WeakMap<object, AmagiClient>()
+
+export const getAmagiClient = (): AmagiClient => {
+  const raw = amagiClientInstance.rawAmagi as unknown as object
+  const cached = clientWrapperCache.get(raw)
+  if (cached) return cached
+
+  // 登录相关接口在**模块级 fetcher** 上（client.douyin.fetcher 是绑定过的精简版，没有 passport 方法）；
+  // 这里用惰性代理，保证 reloadAmagiConfig() 重建 client 后拿到的仍是新实例。
+  const lazyFetcher = (get: () => any) => new Proxy({}, {
+    get: (_target, prop) => Reflect.get(get(), prop)
+  })
+
+  const wrapped = new Proxy(raw, {
+    get (target: any, prop: string | symbol) {
+      if (prop === 'bilibili') {
+        return { ...target.bilibili, login: createBilibiliLoginSession(lazyFetcher(() => bilibiliFetcher)) }
+      }
+      if (prop === 'douyin') {
+        return { ...target.douyin, login: createDouyinLoginSession(lazyFetcher(() => amagiDouyinFetcher)) }
+      }
+      const value = Reflect.get(target, prop, target)
+      return typeof value === 'function' ? value.bind(target) : value
+    }
+  }) as unknown as AmagiClient
+
+  clientWrapperCache.set(raw, wrapped)
+  return wrapped
+}
+
+export const reloadAmagiConfig = () => {
+  if (!amagiClientInstance.reloadConfig()) return false
+
+  // ESM 的 `export let` 是实时绑定：Client 重建后要同步替换，否则调用方还持有旧实例截取的引用
+  bilibiliFetcher = amagiClientInstance.amagi.bilibili.fetcher
+  douyinFetcher = amagiClientInstance.amagi.douyin.fetcher
+  kuaishouFetcher = amagiClientInstance.amagi.kuaishou.fetcher
+  xiaohongshuFetcher = amagiClientInstance.amagi.xiaohongshu.fetcher
+
+  for (const listener of amagiReloadListeners) {
+    try {
+      listener()
+    } catch (error) {
+      logger.error(`[AmagiClient] 运行时资源重载失败: ${error}`)
+    }
+  }
+
+  return true
+}

package/src/karin/module/utils/avatar.ts

@@ -0,0 +1,220 @@
+import { deflateSync } from 'node:zlib'
+
+import { drawDither } from '@outpacelabs/avatars'
+import { logger } from 'node-karin'
+
+/**
+ * 头像解析：优先用平台给的真实头像，拿不到就**实时生成**一个 dither 头像。
+ *
+ * 为什么需要它：部分适配器（比如 QQBot）有概率拿不到群头像，
+ * 榜单里就会空出一排位置，看起来像数据缺了。生成头像保证**每一行都一定有个头像**，
+ * 而且种子取自群号/用户ID，同一个人每次渲染出的图案是稳定的，不会刷一次变一个样。
+ *
+ * ## 为什么不用库自带的 `<GradientAvatar>` 组件
+ *
+ * 那是个 `<canvas>` + effect 绘制的 React 组件，库自己也标了 "Browser only"。
+ * 而海报产物是**纯静态 HTML、不含任何 `<script>`**（ktr 模板链路的硬约束），
+ * 浏览器加载后没有任何 JS 去执行那个 effect，canvas 里会是一片空白。
+ *
+ * 所以这里走库的底层 API `drawDither`：它只用到 `fillStyle` 和 `fillRect`
+ * （纯格子填充，没有渐变也没有合成），而库把绘制接口抽象成了 `GradientContext`
+ * —— 注释里写明「HTMLCanvasElement 和 OffscreenCanvas 的 2D context 都满足它」，
+ * 也就是说这是个公开的扩展点。用一个只记录矩形的小对象驱动它即可，
+ * 不必为了画个头像往 Node 里塞一整个 Canvas 实现。
+ */
+
+/**
+ * 生成头像时喂给库的尺寸。
+ *
+ * **这个值直接决定图案的精细度**，不是"画多大"：库内部按 `clamp(floor(size/3), 8, 64)` 算格数，
+ * 按 `log2(size/16)/log2(160/16)` 算用几种颜色 —— 传 40 只会得到 13×13 格、**3 种颜色**，
+ * 看起来就是一块粗糙的马赛克；160 才是它调色板拉满（4 色、53 格）的档位。
+ * 海报上头像是缩放着显示的，所以这里按满细节渲染，由显示端缩到 40~48px。
+ */
+const RENDER_SIZE = 160
+/** 拉取真实头像的超时 */
+const FETCH_TIMEOUT_MS = 4000
+/** 解析结果缓存条数上限，防止长时间运行把内存吃满 */
+const CACHE_LIMIT = 200
+
+/** 已解析过的头像（URL → data URI），避免反复打同一个 CDN */
+const cache = new Map<string, string>()
+
+/** 记录下来的一个填充矩形 */
+interface RecordedRect {
+  x: number
+  y: number
+  w: number
+  h: number
+  /** `#RRGGBB` 或 `#RRGGBBAA` */
+  color: string
+}
+
+/**
+ * 跑一遍库的 dither 绘制，把方块录下来。
+ *
+ * 传进去的 context 只需满足 `GradientContext`：dither 路径只用 `fillStyle` + `fillRect`，
+ * `createRadialGradient` 是 mesh 路径才需要的，这里直接抛错 —— 真被调到说明库的用法变了。
+ */
+const recordDither = (seed: string, size: number): RecordedRect[] => {
+  const rects: RecordedRect[] = []
+  const context = {
+    fillStyle: '#000000',
+    fillRect(x: number, y: number, w: number, h: number) {
+      rects.push({ x, y, w, h, color: context.fillStyle })
+    },
+    createRadialGradient(): never {
+      throw new Error('dither 路径不应调用 createRadialGradient')
+    }
+  }
+  drawDither(context as unknown as Parameters<typeof drawDither>[0], seed, size)
+  return rects
+}
+
+/** 把录到的方块画进一张 RGBA 位图，并裁成圆形 */
+const rasterize = (rects: RecordedRect[], size: number): Buffer => {
+  // 起点全透明，圆形之外的部分自然留空
+  const rgba = Buffer.alloc(size * size * 4)
+  for (const rect of rects) {
+    const raw = rect.color.replace('#', '')
+    const r = parseInt(raw.slice(0, 2), 16)
+    const g = parseInt(raw.slice(2, 4), 16)
+    const b = parseInt(raw.slice(4, 6), 16)
+    const a = raw.length >= 8 ? parseInt(raw.slice(6, 8), 16) : 255
+    for (let y = rect.y; y < rect.y + rect.h && y < size; y++) {
+      for (let x = rect.x; x < rect.x + rect.w && x < size; x++) {
+        const offset = (y * size + x) * 4
+        rgba[offset] = r
+        rgba[offset + 1] = g
+        rgba[offset + 2] = b
+        rgba[offset + 3] = a
+      }
+    }
+  }
+
+  // 圆形裁切。边缘不做抗锯齿 —— 海报里头像是缩小显示的，降采样本身就会把边缘磨平
+  const half = size / 2
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const dx = x + 0.5 - half
+      const dy = y + 0.5 - half
+      if (dx * dx + dy * dy > half * half) rgba[(y * size + x) * 4 + 3] = 0
+    }
+  }
+  return rgba
+}
+
+/** PNG 的 CRC32 查表 */
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    table[n] = c >>> 0
+  }
+  return table
+})()
+
+/** 算一段字节的 CRC32 */
+const crc32 = (buffer: Buffer): number => {
+  let c = 0xffffffff
+  for (const byte of buffer) c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+/** 拼一个 PNG 数据块：长度 + 类型 + 内容 + CRC */
+const pngChunk = (type: string, data: Buffer): Buffer => {
+  const length = Buffer.alloc(4)
+  length.writeUInt32BE(data.length)
+  const typeBuffer = Buffer.from(type, 'ascii')
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])))
+  return Buffer.concat([length, typeBuffer, data, crc])
+}
+
+/**
+ * 把 RGBA 位图编码成 PNG。
+ *
+ * 手写而不引依赖：这里只需要最朴素的 8 位真彩 + 无滤波，格式本身很短，
+ * 压缩交给 Node 自带的 zlib。**是无损的** —— 不存在因为"图太大"而掉画质的问题。
+ */
+const encodePng = (rgba: Buffer, size: number): Buffer => {
+  const header = Buffer.alloc(13)
+  header.writeUInt32BE(size, 0)
+  header.writeUInt32BE(size, 4)
+  header[8] = 8 // 位深
+  header[9] = 6 // 颜色类型：真彩 + alpha
+  // 剩下三个字节保持 0：deflate 压缩、自适应滤波、非隔行
+
+  // 每一行前面要加一个滤波类型字节（0 = 不滤波）
+  const stride = size * 4
+  const raw = Buffer.alloc((stride + 1) * size)
+  for (let y = 0; y < size; y++) {
+    raw[y * (stride + 1)] = 0
+    rgba.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride)
+  }
+
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', header),
+    pngChunk('IDAT', deflateSync(raw, { level: 9 })),
+    pngChunk('IEND', Buffer.alloc(0))
+  ])
+}
+
+/**
+ * 生成一个确定性头像（dither 类型）
+ * @param seed 种子，传群号或用户ID，保证同一实体每次得到的图案一致
+ */
+export const buildDitherAvatar = (seed: string): string =>
+  `data:image/png;base64,${encodePng(rasterize(recordDither(seed, RENDER_SIZE), RENDER_SIZE), RENDER_SIZE).toString('base64')}`
+
+/**
+ * 把真实头像包成一张圆形裁切的 SVG。
+ *
+ * 圆角只能在包装层做：ECharts 富文本的 `backgroundColor.image` 不支持 `borderRadius`
+ * （实测不会生成 clipPath），不包的话头像在图里是方的。
+ * 这里**不重新编码图片**，只是套一层带 clipPath 的 SVG 外壳。
+ */
+const buildRemoteAvatar = (bytes: Buffer, mime: string, size: number): string => {
+  const half = size / 2
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">` +
+    `<defs><clipPath id="c"><circle cx="${half}" cy="${half}" r="${half}"/></clipPath></defs>` +
+    `<g clip-path="url(#c)"><image href="data:${mime};base64,${bytes.toString('base64')}" width="${size}" height="${size}" preserveAspectRatio="xMidYMid slice"/></g>` +
+    `</svg>`
+  return `data:image/svg+xml;base64,${Buffer.from(svg).toString('base64')}`
+}
+
+/**
+ * 解析一个头像：有 URL 就拉下来，任何一步失败都回落到生成头像。
+ *
+ * **绝不抛错** —— 统计海报是锦上添花的功能，不能因为某个 CDN 抽风就整张渲染不出来。
+ * @param seed 种子（群号 / 用户ID），决定生成头像的图案
+ * @param url 平台给的头像地址；拿不到时传 undefined
+ * @param size 圆形包装的边长（px），只影响真实头像那条路径
+ */
+export const resolveAvatar = async (seed: string, url?: string, size = 48): Promise<string> => {
+  if (url) {
+    const cached = cache.get(url)
+    if (cached) return cached
+
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+      if (response.ok) {
+        const bytes = Buffer.from(await response.arrayBuffer())
+        if (bytes.byteLength > 0) {
+          // 原样内联，不重新编码也不缩放 —— 尺寸由 `getAvatarUrl(id, size)` 那头定好了
+          const dataUri = buildRemoteAvatar(bytes, response.headers.get('content-type')?.split(';')[0] || 'image/png', size)
+          if (cache.size >= CACHE_LIMIT) cache.delete(cache.keys().next().value!)
+          cache.set(url, dataUri)
+          return dataUri
+        }
+      }
+    } catch (error) {
+      logger.debug('[统计] 获取头像失败，改用生成头像:', error)
+    }
+  }
+
+  return buildDitherAvatar(seed)
+}