koishi-plugin-kkk 1.0.0

package/lib/karin/module/utils/amagiClient.js

@@ -0,0 +1,338 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reloadAmagiConfig = exports.getAmagiClient = exports.xiaohongshuFetcher = exports.kuaishouFetcher = exports.douyinFetcher = exports.bilibiliFetcher = exports.registerAmagiReloadListener = exports.isSoftFailure = exports.softFetch = exports.SOFT_ERROR_CODES = exports.AmagiBase = exports.AmagiError = void 0;
+const amagi_1 = __importStar(require("@ikenxuan/amagi"));
+const node_karin_1 = require("../../../compat/node-karin.js");
+const Config_1 = require("./Config");
+const loginSession_1 = require("./loginSession");
+/**
+ * 平台业务码。v7 的三种码各归各位：平台业务码 `error.platform.code`、HTTP 状态 `error.http.status`、
+ * amagi 自己的码 `error.code`（字符串）。按平台码分流的地方（B站 `-352` 风控、`-111` csrf 失效、
+ * `12061` 关闭评论区）要的是第一种；平台没给就退 HTTP 状态，再退 0。
+ */
+const legacyCode = (error, envelope) => {
+    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;
+    if (typeof anyError.responseCode === 'number')
+        return anyError.responseCode;
+    if (typeof envelope?.code === 'number')
+        return envelope.code;
+    return error.http?.status ?? 0;
+};
+/**
+ * 一行说清一次失败：`[大类/码] 平台原文 (端点 平台码 HTTP requestId attempts)`。
+ * `message` 会被 `logger.warn(...)` 直接拼进日志行，塞整个信封的转储会把日志顶成一屏 ANSI。
+ */
+const describeFailure = (envelope) => {
+    const error = envelope.error ?? {};
+    const meta = envelope.meta;
+    const kind = error.kind ?? (error.requestType ? 'api' : 'unknown');
+    const code = error.code ?? envelope.code;
+    const reason = error.errorDescription ?? error.message ?? envelope.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) => typeof part === 'string' && part !== '');
+    return `[${kind}/${code ?? '-'}] ${reason}${facts.length > 0 ? ` (${facts.join(' ')})` : ''}`;
+};
+/** Amagi 失败异常：`message` 是一行摘要，结构化字段各有属性，完整信封在 {@link AmagiError.envelope} */
+class AmagiError extends Error {
+    /** 平台业务码，见 {@link legacyCode} */
+    code;
+    /** 平台原始响应体。v7 只在 `debug: true` 下填 `error.raw`（B站风控要读里面的 `v_voucher`） */
+    data;
+    /** v7 错误契约本体，等价于失败信封的 `error` */
+    rawError;
+    /** 错误大类 */
+    kind;
+    /** amagi 自己的字符串错误码 */
+    amagiCode;
+    /** 平台返回的原文，不带前缀与归因 */
+    reason;
+    /** 是否值得重试 */
+    retryable;
+    /** 真实发生的 HTTP 状态 */
+    httpStatus;
+    /** 参数校验的字段级错误，仅 `kind === 'validation'` 时有 */
+    issues;
+    /** 整条失败信封，`meta.requestId` / `attempts` / `durationMs` 在里面 */
+    envelope;
+    constructor(envelope) {
+        const error = envelope.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.data;
+        this.rawError = error;
+        this.kind = (error.kind ?? 'api');
+        this.amagiCode = error.code ?? envelope.code;
+        this.reason = error.errorDescription ?? error.message ?? envelope.message ?? '未知错误';
+        this.retryable = typeof error.retryable === 'boolean' ? error.retryable : false;
+        this.httpStatus = error.http?.status;
+        this.issues = error.issues;
+        this.envelope = envelope;
+    }
+}
+exports.AmagiError = AmagiError;
+/**
+ * 判断一个值是不是失败信封。**只认 `success`**：v7 信封顶层没有 `code`（三种码各归各位），
+ * 拿 `code` 当特征判别恒假 —— 失败被原样透传、`try/catch` 全失效、取数失败但流程继续，且零编译错误。
+ */
+const isFailureEnvelope = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const envelope = value;
+    return envelope.success === false && typeof envelope.message === 'string' && !!envelope.error;
+};
+/** 判断是不是 thenable，用来只包装异步方法 */
+const isThenable = (value) => !!value && (typeof value === 'object' || typeof value === 'function') && typeof value.then === 'function';
+/**
+ * 递归代理一个 fetcher 对象，把失败信封转成 `throw AmagiError`。返回类型与入参同形 ——
+ * 「只保留成功分支」是**类型层**由 {@link ThrowingClient} 声明的，这里只管运行时行为。
+ */
+const throwOnFailure = (target) => new Proxy(target, {
+    get(obj, prop) {
+        const value = obj[prop];
+        if (typeof value === 'function') {
+            return (...args) => {
+                const returned = value.apply(obj, args);
+                // 同步方法原样放行：包成 async 会把返回值套一层 Promise，破坏语义
+                if (!isThenable(returned))
+                    return returned;
+                return returned.then((result) => {
+                    if (isFailureEnvelope(result))
+                        throw new AmagiError(result);
+                    return result;
+                });
+            };
+        }
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return throwOnFailure(value);
+        }
+        return value;
+    }
+});
+/** 解析库基类 */
+class AmagiBase {
+    /**
+     * 原始 v7 客户端。
+     *
+     * `events` / `on` / `once` / `login` / `startServer` 从这里取 —— 它们不是 fetcher，
+     * 不该被「失败必抛」的代理碰（`on` 返回退订函数，包成 async 就废了）。
+     */
+    rawAmagi;
+    /** 解析库实例，四个平台的 fetcher 失败即抛 */
+    amagi;
+    /** 当前客户端使用的配置快照，用于避免文件监听与显式重载造成重复初始化 */
+    configSignature;
+    constructor() {
+        const client = this.createAmagiClient();
+        this.rawAmagi = client;
+        this.amagi = this.wrapAmagiClient(client);
+        this.configSignature = this.getConfigSignature();
+    }
+    /** 获取会影响 Amagi 运行状态的配置快照 */
+    getConfigSignature = () => JSON.stringify(Config_1.Config.amagi);
+    /** 创建解析库实例 */
+    createAmagiClient = () => {
+        const amagi = Config_1.Config.amagi;
+        return (0, amagi_1.default)({
+            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) {
+            node_karin_1.logger.debug('[AmagiClient] 配置未变化，跳过重复重载');
+            return false;
+        }
+        node_karin_1.logger.debug('[AmagiClient] 检测到配置变化，正在重载...');
+        const client = this.createAmagiClient();
+        this.rawAmagi = client;
+        this.amagi = this.wrapAmagiClient(client);
+        this.configSignature = nextConfigSignature;
+        node_karin_1.logger.debug('[AmagiClient] 配置重载完成');
+        return true;
+    }
+    /** 只把四个平台的 fetcher 换成失败必抛形态，client 的其余键原样带过去 */
+    wrapAmagiClient = (client) => ({
+        ...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) }
+    });
+}
+exports.AmagiBase = AmagiBase;
+/** 软错误码：命中这些平台业务码时不抛异常，按失败信封返回。Bilibili `12061` - UP主已关闭评论区 */
+exports.SOFT_ERROR_CODES = {
+    BILIBILI_COMMENTS_DISABLED: 12061
+};
+/**
+ * 调用 amagi fetcher 方法，允许特定平台业务码以失败信封返回而不是抛异常。
+ * @param fn - 经过代理包装的 amagi 方法调用
+ * @param allowedCodes - 不应抛出异常的平台业务码列表
+ * @returns 成功信封，或命中 `allowedCodes` 的软失败
+ */
+const softFetch = async (fn, allowedCodes) => {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof AmagiError && allowedCodes.includes(err.code)) {
+            return { ...err.envelope, code: err.code };
+        }
+        throw err;
+    }
+};
+exports.softFetch = softFetch;
+/**
+ * {@link softFetch} 的结果是否命中某个软错误码。
+ *
+ * 是类型守卫而不是 `result.code === x`：`code` 的类型是 `number` 不是字面量，
+ * 直接比较不会收窄联合，`else` 分支里的 `data` 仍是 `T | undefined`。
+ */
+const isSoftFailure = (result, ...codes) => !result.success && codes.includes(result.code);
+exports.isSoftFailure = isSoftFailure;
+const amagiClientInstance = new AmagiBase();
+/** 需要随 Amagi Client 一同刷新的运行时资源，例如已经挂载的 HTTP Router */
+const amagiReloadListeners = new Set();
+/**
+ * 注册 Amagi 配置重载监听器。
+ * @param listener - 重载后要执行的回调
+ * @returns 注销当前监听器的函数
+ */
+const registerAmagiReloadListener = (listener) => {
+    amagiReloadListeners.add(listener);
+    return () => amagiReloadListeners.delete(listener);
+};
+exports.registerAmagiReloadListener = registerAmagiReloadListener;
+/**
+ * 四个平台的「失败必抛」fetcher。
+ *
+ * 类型必须显式标注：不标的话 TS 要在声明产物里展开 fetcher 的结构，而响应类型桶只导出
+ * `BilibiliVideoInfoResponse` 这样的具名别名、不导出底层的 `*_V0`，展开时叫不出名来报 TS2883。
+ */
+exports.bilibiliFetcher = amagiClientInstance.amagi.bilibili.fetcher;
+exports.douyinFetcher = amagiClientInstance.amagi.douyin.fetcher;
+exports.kuaishouFetcher = amagiClientInstance.amagi.kuaishou.fetcher;
+exports.xiaohongshuFetcher = 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();
+const getAmagiClient = () => {
+    const raw = amagiClientInstance.rawAmagi;
+    const cached = clientWrapperCache.get(raw);
+    if (cached)
+        return cached;
+    // 登录相关接口在**模块级 fetcher** 上（client.douyin.fetcher 是绑定过的精简版，没有 passport 方法）；
+    // 这里用惰性代理，保证 reloadAmagiConfig() 重建 client 后拿到的仍是新实例。
+    const lazyFetcher = (get) => new Proxy({}, {
+        get: (_target, prop) => Reflect.get(get(), prop)
+    });
+    const wrapped = new Proxy(raw, {
+        get(target, prop) {
+            if (prop === 'bilibili') {
+                return { ...target.bilibili, login: (0, loginSession_1.createBilibiliLoginSession)(lazyFetcher(() => exports.bilibiliFetcher)) };
+            }
+            if (prop === 'douyin') {
+                return { ...target.douyin, login: (0, loginSession_1.createDouyinLoginSession)(lazyFetcher(() => amagi_1.douyinFetcher)) };
+            }
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        }
+    });
+    clientWrapperCache.set(raw, wrapped);
+    return wrapped;
+};
+exports.getAmagiClient = getAmagiClient;
+const reloadAmagiConfig = () => {
+    if (!amagiClientInstance.reloadConfig())
+        return false;
+    // ESM 的 `export let` 是实时绑定：Client 重建后要同步替换，否则调用方还持有旧实例截取的引用
+    exports.bilibiliFetcher = amagiClientInstance.amagi.bilibili.fetcher;
+    exports.douyinFetcher = amagiClientInstance.amagi.douyin.fetcher;
+    exports.kuaishouFetcher = amagiClientInstance.amagi.kuaishou.fetcher;
+    exports.xiaohongshuFetcher = amagiClientInstance.amagi.xiaohongshu.fetcher;
+    for (const listener of amagiReloadListeners) {
+        try {
+            listener();
+        }
+        catch (error) {
+            node_karin_1.logger.error(`[AmagiClient] 运行时资源重载失败: ${error}`);
+        }
+    }
+    return true;
+};
+exports.reloadAmagiConfig = reloadAmagiConfig;

package/lib/karin/module/utils/avatar.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAvatar = exports.buildDitherAvatar = void 0;
+const node_zlib_1 = require("node:zlib");
+const avatars_1 = require("@outpacelabs/avatars");
+const node_karin_1 = require("../../../compat/node-karin.js");
+/**
+ * 头像解析：优先用平台给的真实头像，拿不到就**实时生成**一个 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();
+/**
+ * 跑一遍库的 dither 绘制，把方块录下来。
+ *
+ * 传进去的 context 只需满足 `GradientContext`：dither 路径只用 `fillStyle` + `fillRect`，
+ * `createRadialGradient` 是 mesh 路径才需要的，这里直接抛错 —— 真被调到说明库的用法变了。
+ */
+const recordDither = (seed, size) => {
+    const rects = [];
+    const context = {
+        fillStyle: '#000000',
+        fillRect(x, y, w, h) {
+            rects.push({ x, y, w, h, color: context.fillStyle });
+        },
+        createRadialGradient() {
+            throw new Error('dither 路径不应调用 createRadialGradient');
+        }
+    };
+    (0, avatars_1.drawDither)(context, seed, size);
+    return rects;
+};
+/** 把录到的方块画进一张 RGBA 位图，并裁成圆形 */
+const rasterize = (rects, size) => {
+    // 起点全透明，圆形之外的部分自然留空
+    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) => {
+    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, data) => {
+    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, size) => {
+    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', (0, node_zlib_1.deflateSync)(raw, { level: 9 })),
+        pngChunk('IEND', Buffer.alloc(0))
+    ]);
+};
+/**
+ * 生成一个确定性头像（dither 类型）
+ * @param seed 种子，传群号或用户ID，保证同一实体每次得到的图案一致
+ */
+const buildDitherAvatar = (seed) => `data:image/png;base64,${encodePng(rasterize(recordDither(seed, RENDER_SIZE), RENDER_SIZE), RENDER_SIZE).toString('base64')}`;
+exports.buildDitherAvatar = buildDitherAvatar;
+/**
+ * 把真实头像包成一张圆形裁切的 SVG。
+ *
+ * 圆角只能在包装层做：ECharts 富文本的 `backgroundColor.image` 不支持 `borderRadius`
+ * （实测不会生成 clipPath），不包的话头像在图里是方的。
+ * 这里**不重新编码图片**，只是套一层带 clipPath 的 SVG 外壳。
+ */
+const buildRemoteAvatar = (bytes, mime, size) => {
+    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），只影响真实头像那条路径
+ */
+const resolveAvatar = async (seed, url, size = 48) => {
+    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) {
+            node_karin_1.logger.debug('[统计] 获取头像失败，改用生成头像:', error);
+        }
+    }
+    return (0, exports.buildDitherAvatar)(seed);
+};
+exports.resolveAvatar = resolveAvatar;

package/lib/karin/module/utils/bot.js

@@ -0,0 +1,141 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTriggerAvatarUrl = exports.resolveUsableBot = exports.getReachableMasterBots = void 0;
+const node_karin_1 = __importStar(require("../../../compat/node-karin.js"));
+const Config_1 = require("../../module/utils/Config");
+const Base_1 = require("./Base");
+/**
+ * 获取候选机器人
+ * @returns
+ */
+const getCandidateBots = () => {
+    return node_karin_1.default
+        .getAllBotList()
+        .map((item) => item.bot)
+        .filter((bot) => bot.account.name !== 'console');
+};
+/**
+ * 获取非console主机器人ID列表
+ * @param masters - 主机器人ID列表
+ * @returns
+ */
+const getNonConsoleMasters = (masters = node_karin_1.config.master()) => {
+    return masters.filter((id) => id !== 'console');
+};
+/**
+ * 获取可访问的主机器人
+ * @param masters - 主机器人ID列表
+ * @returns
+ */
+const getReachableMasterBots = async (masters = node_karin_1.config.master()) => {
+    const owners = getNonConsoleMasters(masters);
+    if (owners.length === 0)
+        return [];
+    const bots = getCandidateBots();
+    if (bots.length === 0)
+        return [];
+    const friendsMap = new Map();
+    await Promise.all(bots.map(async (bot) => {
+        try {
+            const list = await bot.getFriendList();
+            friendsMap.set(bot.account.selfId, Array.isArray(list) ? list : []);
+        }
+        catch {
+            friendsMap.set(bot.account.selfId, []);
+        }
+    }));
+    const result = [];
+    for (const master of owners) {
+        const matchedBot = bots.find((bot) => {
+            return (friendsMap.get(bot.account.selfId) || []).some((friend) => friend.userId === master);
+        });
+        if (matchedBot) {
+            result.push({ master, bot: matchedBot });
+        }
+    }
+    return result;
+};
+exports.getReachableMasterBots = getReachableMasterBots;
+/**
+ * 获取一个最少能用的机器人实例，优先级：1. selfId 参数指定的机器人 2. 可访问主人机器人中的第一个 3. pushlist 中活跃的机器人 4. 任意一个在线机器人
+ * @param selfId - 机器人ID
+ * @returns
+ */
+const resolveUsableBot = async (selfId) => {
+    if (selfId) {
+        const matchedBot = node_karin_1.default.getBot(selfId);
+        if (matchedBot)
+            return matchedBot;
+    }
+    const reachable = await (0, exports.getReachableMasterBots)();
+    if (reachable.length > 0)
+        return reachable[0].bot;
+    const { douyin, bilibili } = (0, Base_1.statBotId)(Config_1.Config.pushlist);
+    const preferredBotId = douyin.botId || bilibili.botId;
+    if (preferredBotId) {
+        const matchedBot = node_karin_1.default.getBot(preferredBotId);
+        if (matchedBot)
+            return matchedBot;
+    }
+    const fallbackBotId = node_karin_1.default.getAllBotID()[0];
+    if (!fallbackBotId)
+        return undefined;
+    return node_karin_1.default.getBot(fallbackBotId);
+};
+exports.resolveUsableBot = resolveUsableBot;
+/**
+ * 取触发者头像 URL，用于嵌到登录二维码中心当 logo。
+ *
+ * 适配器（如 console）可能不实现 getAvatarUrl 或返回空串，模板侧 avatarUrl 缺省即退化为普通二维码，
+ * 所以这里任何失败都只记 debug 日志并返回 undefined，不影响登录流程。
+ *
+ * @param e - 触发登录的消息事件
+ * @returns 头像 URL，取不到时为 undefined
+ */
+const resolveTriggerAvatarUrl = async (e) => {
+    const userId = e.sender?.userId || e.userId;
+    if (!userId)
+        return undefined;
+    try {
+        const url = await e.bot.getAvatarUrl(userId);
+        return url || undefined;
+    }
+    catch (error) {
+        node_karin_1.logger.debug('[koishi-plugin-kkk] 获取触发者头像失败，二维码将不嵌入头像:', error);
+        return undefined;
+    }
+};
+exports.resolveTriggerAvatarUrl = resolveTriggerAvatarUrl;