koishi-plugin-blacklist-online 0.1.0

package/lib/core.d.ts

@@ -0,0 +1,15 @@
+import { Context, Session } from 'koishi';
+import { PluginConfig } from './types';
+export declare const sleep: (ms: number) => Promise<unknown>;
+export declare function isUserAdmin(session: Session, config: PluginConfig, userId: string): Promise<boolean>;
+export declare function syncBlacklist(ctx: Context, config: PluginConfig): Promise<void>;
+export declare function queueRequest(ctx: Context, type: 'ADD' | 'REMOVE' | 'CANCEL', payload: any): Promise<any>;
+export declare function processOfflineQueue(ctx: Context, config: PluginConfig): Promise<void>;
+export declare function checkAndHandleUser(ctx: Context, config: PluginConfig, session: Session, userId: string): Promise<boolean>;
+export declare function parseUserId(input: string): string;
+export declare function scanGuild(ctx: Context, config: PluginConfig, bot: any, // 传入具体的 bot 实例
+guildId: string): Promise<{
+    handled: number;
+    total: number;
+    error?: string;
+}>;

package/lib/core.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = void 0;
+exports.isUserAdmin = isUserAdmin;
+exports.syncBlacklist = syncBlacklist;
+exports.queueRequest = queueRequest;
+exports.processOfflineQueue = processOfflineQueue;
+exports.checkAndHandleUser = checkAndHandleUser;
+exports.parseUserId = parseUserId;
+exports.scanGuild = scanGuild;
+const koishi_1 = require("koishi");
+const node_crypto_1 = require("node:crypto");
+const logger = new koishi_1.Logger('blacklist-online');
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+exports.sleep = sleep;
+// 全局锁：防止队列处理并发重入
+let isProcessingQueue = false;
+// --- 1. 权限判断 ---
+async function isUserAdmin(session, config, userId) {
+    if (!session.guildId)
+        return false;
+    try {
+        const member = await session.bot.getGuildMember(session.guildId, userId);
+        if (!member)
+            return false;
+        // 统一转小写比对
+        const allowedRoles = (config.adminRoles || ['owner', 'admin']).map(r => r.toLowerCase());
+        const userRoles = [...(member.roles || [])].map(r => r.toLowerCase());
+        return userRoles.some(role => allowedRoles.includes(role));
+    }
+    catch (error) {
+        return false; // 报错视为无权限
+    }
+}
+// --- 2. 同步 ---
+async function syncBlacklist(ctx, config) {
+    try {
+        const meta = await ctx.database.get('blacklist_meta', { key: 'sync_revision' });
+        const localRevision = meta[0]?.value || '';
+        const instanceMeta = await ctx.database.get('blacklist_meta', { key: 'instance_uuid' });
+        const instanceId = instanceMeta[0]?.value;
+        logger.debug(`🔄 同步开始 (本地版本: ${localRevision || 'INIT'})`);
+        // 发起同步请求
+        // 强制使用 HTTPS 应该在 config.remoteApiUrl 配置中体现
+        const response = await ctx.http.post(`${config.remoteApiUrl}/sync`, {
+            revision: localRevision,
+            instanceId: instanceId
+        }, {
+            headers: { Authorization: `Bearer ${config.apiToken}` },
+            timeout: 10000
+        });
+        const { strategy, newRevision, data } = response;
+        if (strategy === 'up-to-date') {
+            logger.debug('✅ 黑名单已是最新');
+            return;
+        }
+        if (strategy === 'full_replace') {
+            logger.info(`📥 全量同步 -> ${newRevision} (条数: ${data.length})`);
+            await ctx.database.remove('blacklist_users', {});
+            // 分批写入防报错
+            const batchSize = 100;
+            for (let i = 0; i < data.length; i += batchSize) {
+                await ctx.database.upsert('blacklist_users', data.slice(i, i + batchSize));
+            }
+        }
+        else if (strategy === 'incremental') {
+            logger.info(`📥 增量同步 -> ${newRevision}`);
+            if (data.upserts?.length)
+                await ctx.database.upsert('blacklist_users', data.upserts);
+            if (data.deletes?.length)
+                await ctx.database.remove('blacklist_users', { userId: data.deletes });
+        }
+        await ctx.database.upsert('blacklist_meta', [{ key: 'sync_revision', value: newRevision }]);
+        logger.info('✅ 同步完成');
+    }
+    catch (error) {
+        logger.warn(`❌ 同步失败: ${error.message || error}`);
+    }
+}
+// --- 3. 队列入队 ---
+async function queueRequest(ctx, type, payload) {
+    const requestId = payload.requestId || (0, node_crypto_1.randomUUID)();
+    payload.requestId = requestId;
+    await ctx.database.create('blacklist_request_queue', {
+        id: requestId,
+        type,
+        payload,
+        createdAt: new Date(),
+        retryCount: 0
+    });
+    return requestId;
+}
+// --- 4. 离线队列处理 ---
+async function processOfflineQueue(ctx, config) {
+    if (isProcessingQueue)
+        return; // 锁：防止重入
+    isProcessingQueue = true;
+    try {
+        // 每次处理 10 条，避免堵塞过久
+        const queue = await ctx.database.get('blacklist_request_queue', {}, { limit: 10, sort: { createdAt: 'asc' } });
+        if (queue.length === 0)
+            return;
+        const instanceMeta = await ctx.database.get('blacklist_meta', { key: 'instance_uuid' });
+        const instanceId = instanceMeta[0]?.value;
+        logger.info(`📤 处理离线队列 (积压: ${queue.length})`);
+        for (const item of queue) {
+            // 死信检测：超过 5 次重试失败，移除并记录日志
+            if (item.retryCount > 5) {
+                logger.warn(`🚨 请求 ${item.id} (${item.type}) 成为死信 (Retry > 5)，已丢弃。Payload: ${JSON.stringify(item.payload)}`);
+                await ctx.database.remove('blacklist_request_queue', { id: item.id });
+                continue;
+            }
+            try {
+                await ctx.http.post(`${config.remoteApiUrl}/applications`, {
+                    ...item.payload,
+                    instanceId,
+                    isOfflineRetry: true
+                }, {
+                    headers: { Authorization: `Bearer ${config.apiToken}` },
+                    timeout: 5000
+                });
+                await ctx.database.remove('blacklist_request_queue', { id: item.id });
+                logger.info(`✅ 离线请求 ${item.id} 同步成功`);
+            }
+            catch (error) {
+                const isNetworkError = error.code === 'ECONNABORTED' || error.code === 'ENOTFOUND' || !error.response;
+                if (isNetworkError) {
+                    // 网络问题：单纯保留，不增加死信计数(或者增加得慢一点)，等待网络恢复
+                    logger.debug(`离线请求 ${item.id} 网络失败，等待重连。`);
+                }
+                else {
+                    // 业务错误 (400/500)：增加重试计数
+                    logger.warn(`离线请求 ${item.id} 业务报错: ${error.message}`);
+                    await ctx.database.set('blacklist_request_queue', { id: item.id }, {
+                        retryCount: item.retryCount + 1
+                    });
+                }
+            }
+        }
+    }
+    catch (err) {
+        logger.error(`队列处理发生未知异常: ${err}`);
+    }
+    finally {
+        isProcessingQueue = false; // 释放锁
+    }
+}
+// --- 5. 用户检查核心 ---
+async function checkAndHandleUser(ctx, config, session, userId) {
+    if (!session.guildId)
+        return false;
+    const guildSettings = await ctx.database.get('blacklist_guild_settings', { guildId: session.guildId });
+    const mode = guildSettings[0]?.mode || config.defaultGuildMode;
+    if (mode === 'off')
+        return false;
+    // 1. 本地白名单 (最高优先级)
+    const protectedSet = new Set(config.protectedUsers || []);
+    if (protectedSet.has(userId))
+        return false;
+    // 2. 查库
+    const entries = await ctx.database.get('blacklist_users', { userId, disabled: false });
+    if (entries.length === 0)
+        return false;
+    const entry = entries[0];
+    const reason = entry.reason || 'QQ号黑名单';
+    // 3. 查管理员
+    if (await isUserAdmin(session, config, userId)) {
+        logger.info(`🛡️ 跳过黑名单管理员 ${userId}`);
+        return false;
+    }
+    logger.info(`🎯 [群: ${session.guildId}] 发现黑名单用户: ${userId} - 原因: ${reason}`);
+    // 获取显示名
+    let displayName = userId;
+    try {
+        const member = await session.bot.getGuildMember(session.guildId, userId);
+        displayName = member.nick || member.user?.name || userId;
+    }
+    catch {
+    }
+    // 执行通知
+    if (mode === 'notify' || mode === 'both') {
+        const tpl = mode === 'notify' ? config.adminNotifyMessage : config.kickNotifyMessage;
+        const msg = tpl
+            .replace('{user}', displayName)
+            .replace('{userId}', userId)
+            .replace('{reason}', reason)
+            .replace('{guild}', session.guildId);
+        // 引用回复
+        await session.send(session.messageId ? (0, koishi_1.h)('quote', { id: session.messageId }) + msg : msg);
+    }
+    // 执行踢出
+    let kicked = false;
+    if (mode === 'kick' || mode === 'both') {
+        for (let i = 0; i < config.retryAttempts; i++) {
+            try {
+                await session.bot.kickGuildMember(session.guildId, userId);
+                kicked = true;
+                logger.info(`✅ [群: ${session.guildId}] 成功踢出: ${userId}`);
+                break;
+            }
+            catch (e) {
+                if (i < config.retryAttempts - 1)
+                    await (0, exports.sleep)(config.retryDelay);
+                else {
+                    const failMsg = config.kickFailMessage.replace('{user}', displayName).replace('{reason}', String(e));
+                    await session.send(failMsg);
+                }
+            }
+        }
+        // 踢出后验证 (可选)
+        if (kicked && config.verifyKickResult) {
+            await (0, exports.sleep)(2000);
+            try {
+                await session.bot.getGuildMember(session.guildId, userId);
+                // 如果还能获取到，说明没踢掉
+                logger.warn(`⚠️ [群: ${session.guildId}] 踢出验证失败，用户仍在群内: ${userId}`);
+            }
+            catch {
+                // 获取不到说明踢出成功
+            }
+        }
+    }
+    return kicked;
+}
+function parseUserId(input) {
+    if (!input)
+        return "";
+    const atMatch = input.match(/<at id="([^"]+)"\/>/);
+    if (atMatch)
+        input = atMatch[1];
+    if (input.includes(':'))
+        return input.split(':')[1];
+    return input;
+}
+// 通用的群组扫描函数
+async function scanGuild(ctx, config, bot, // 传入具体的 bot 实例
+guildId) {
+    try {
+        // 1. 获取群成员
+        const members = await bot.getGuildMemberList(guildId);
+        // 2. 获取本地黑名单缓存
+        const blacklist = await ctx.database.get('blacklist_users', { disabled: false });
+        const blacklistSet = new Set(blacklist.map(b => b.userId));
+        // 3. 筛选目标 (内存操作，极快)
+        const targets = members.data.filter((m) => {
+            if (!m.user?.id)
+                return false;
+            if (config.skipBotMembers && m.user.isBot)
+                return false;
+            return blacklistSet.has(m.user.id);
+        });
+        if (targets.length === 0)
+            return { handled: 0, total: 0 };
+        // 4. 构造伪造的 Session 用于复用 checkAndHandleUser 逻辑
+        // 注意：checkAndHandleUser 内部依赖 session.send 发送通知
+        // 全局扫描时可能不需要每踢一个人都发消息，或者需要构造一个静默的 session
+        const fakeSession = bot.session({
+            type: 'message',
+            guildId,
+            user: { id: bot.selfId }, // 模拟机器人自己
+        });
+        let handled = 0;
+        const BATCH_SIZE = 5;
+        // 5. 分批执行
+        for (let i = 0; i < targets.length; i += BATCH_SIZE) {
+            const batch = targets.slice(i, i + BATCH_SIZE);
+            await Promise.all(batch.map(async (m) => {
+                if (m.user?.id) {
+                    // 调用核心处理逻辑
+                    const result = await checkAndHandleUser(ctx, config, fakeSession, m.user.id);
+                    if (result)
+                        handled++;
+                }
+            }));
+        }
+        return { handled, total: targets.length };
+    }
+    catch (error) {
+        return { handled: 0, total: 0, error: String(error) };
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,7 @@
+import { Context, Schema } from 'koishi';
+import { PluginConfig } from './types';
+export declare const name = "blacklist-online";
+export declare const inject: string[];
+export declare const usage = "\n## \u529F\u80FD\u8BF4\u660E\n\u4E00\u4E2A\u5F3A\u5927\u7684\u3001\u57FA\u4E8E\u6570\u636E\u5E93\u7684\u7FA4\u7EC4\u9ED1\u540D\u5355\u7BA1\u7406\u63D2\u4EF6\u3002\n- **\u6570\u636E\u5E93\u9A71\u52A8**: QQ\u53F7\u9ED1\u540D\u5355\u5B58\u50A8\u5728\u6570\u636E\u5E93\u4E2D\uFF0C\u53EF\u901A\u8FC7\u6307\u4EE4\u52A8\u6001\u589E\u5220\uFF0C\u652F\u6301\u64CD\u4F5C\u8FFD\u6EAF\u3002\n- **\u53D7\u4FDD\u62A4\u540D\u5355**: \u914D\u7F6E\u4E2D\u7684\u7528\u6237\u65E0\u6CD5\u88AB\u62C9\u9ED1\u3002\n- **\u7533\u8BF7/\u5BA1\u6279\u6D41\u7A0B**: \u666E\u901A\u7FA4\u7BA1\u7406\u53EF\u63D0\u4EA4\u62C9\u9ED1\u7533\u8BF7\uFF0C\u7531\u673A\u5668\u4EBA\u7BA1\u7406\u5458\u5BA1\u6279\uFF0C\u6240\u6709\u6D41\u7A0B\u81EA\u52A8\u5316\u901A\u77E5\u3002\n- **\u5206\u7FA4\u7BA1\u7406**: \u53EF\u4E3A\u6BCF\u4E2A\u7FA4\u72EC\u7ACB\u8BBE\u7F6E\u9ED1\u540D\u5355\u5904\u7406\u6A21\u5F0F\u3002\n- **\u6635\u79F0\u9ED1\u540D\u5355**: \u652F\u6301\u914D\u7F6E\u9759\u6001\u7684\u6635\u79F0\u5173\u952E\u8BCD\u9ED1\u540D\u5355\uFF0C\u5E76\u6709\u603B\u5F00\u5173\u63A7\u5236\u3002\n- **\u5165\u7FA4\u626B\u63CF**: \u53EF\u914D\u7F6E\u673A\u5668\u4EBA\u5728\u52A0\u5165\u65B0\u7FA4\u7EC4\u65F6\uFF0C\u81EA\u52A8\u626B\u63CF\u7FA4\u5185\u73B0\u6709\u6210\u5458\u3002\n- **\u5EF6\u8FDF\u68C0\u67E5**: \u65B0\u6210\u5458\u52A0\u5165\u540E\uFF0C\u53EF\u914D\u7F6E\u5EF6\u8FDF\u53CA\u5468\u671F\u6027\u6635\u79F0\u68C0\u67E5\uFF0C\u9632\u6B62\u5176\u4FEE\u6539\u6635\u79F0\u7ED5\u8FC7\u68C0\u6D4B\u3002\n- **\u81EA\u52A8\u62D2\u7EDD**: \u81EA\u52A8\u62D2\u7EDD\u6570\u636E\u5E93\u9ED1\u540D\u5355\u7528\u6237\u7684\u52A0\u7FA4\u7533\u8BF7\u3002\n- **\u624B\u52A8\u626B\u63CF**: \u63D0\u4F9B\u6307\u4EE4\u624B\u52A8\u626B\u63CF\u5F53\u524D\u6216\u5168\u90E8\u7FA4\u7EC4\u3002\n- **\u6743\u9650\u63A7\u5236**: \u6240\u6709\u6307\u4EE4\u5747\u6709\u6743\u9650\u7B49\u7EA7\u63A7\u5236\u3002\n";
+export declare const Config: Schema<PluginConfig>;
+export declare function apply(ctx: Context, config: PluginConfig): void;

package/lib/index.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.usage = exports.inject = exports.name = void 0;
+exports.apply = apply;
+const koishi_1 = require("koishi");
+const node_crypto_1 = require("node:crypto"); // 【修复】使用原生 crypto
+const core_1 = require("./core");
+exports.name = 'blacklist-online';
+exports.inject = ['database', 'http'];
+exports.usage = `
+## 功能说明
+一个强大的、基于数据库的群组黑名单管理插件。
+- **数据库驱动**: QQ号黑名单存储在数据库中，可通过指令动态增删，支持操作追溯。
+- **受保护名单**: 配置中的用户无法被拉黑。
+- **申请/审批流程**: 普通群管理可提交拉黑申请，由机器人管理员审批，所有流程自动化通知。
+- **分群管理**: 可为每个群独立设置黑名单处理模式。
+- **昵称黑名单**: 支持配置静态的昵称关键词黑名单，并有总开关控制。
+- **入群扫描**: 可配置机器人在加入新群组时，自动扫描群内现有成员。
+- **延迟检查**: 新成员加入后，可配置延迟及周期性昵称检查，防止其修改昵称绕过检测。
+- **自动拒绝**: 自动拒绝数据库黑名单用户的加群申请。
+- **手动扫描**: 提供指令手动扫描当前或全部群组。
+- **权限控制**: 所有指令均有权限等级控制。
+`;
+// --- Schema 定义 ---
+exports.Config = koishi_1.Schema.intersect([
+    koishi_1.Schema.object({
+        remoteApiUrl: koishi_1.Schema.string().required().description('远程黑名单中心 API 地址 (建议 HTTPS)'),
+        apiToken: koishi_1.Schema.string().role('secret').required().description('API 访问令牌'),
+        adminRoles: koishi_1.Schema.array(String).default(['owner', 'admin']).description('管理员角色名 (不区分大小写)'),
+        protectedUsers: koishi_1.Schema.array(String).role('table').description('本地受保护用户 (白名单)'),
+        defaultGuildMode: koishi_1.Schema.union([
+            koishi_1.Schema.const('off').description('关闭'),
+            koishi_1.Schema.const('notify').description('仅通知'),
+            koishi_1.Schema.const('kick').description('仅踢出'),
+            koishi_1.Schema.const('both').description('通知并踢出'),
+        ]).default('off').description('新群组默认模式'),
+    }).description('核心设置'),
+    koishi_1.Schema.object({
+        enableAutoReject: koishi_1.Schema.boolean().default(true).description("自动拒绝加群申请"),
+        skipBotMembers: koishi_1.Schema.boolean().default(true).description("跳过其他机器人"),
+        retryAttempts: koishi_1.Schema.number().default(3).description("踢人重试次数"),
+        retryDelay: koishi_1.Schema.number().default(2000).description("重试间隔(ms)"),
+        verifyKickResult: koishi_1.Schema.boolean().default(true).description("验证踢出结果"),
+    }).description('高级行为'),
+    koishi_1.Schema.object({
+        rejectionMessage: koishi_1.Schema.string().default('您的账号存在安全风险。').description("拒绝申请理由"),
+        adminNotifyMessage: koishi_1.Schema.string().role('textarea').default('检测到黑名单用户 {user} ({userId})。\n原因: {reason}').description('通知模式模板'),
+        kickNotifyMessage: koishi_1.Schema.string().role('textarea').default('正在移除黑名单用户 {user} ({userId})...\n原因: {reason}').description('踢出模式模板'),
+        kickFailMessage: koishi_1.Schema.string().role('textarea').default('⚠️ 无法踢出用户 {user}。\n错误: {reason}').description('失败通知'),
+        autoRejectNotifyMessage: koishi_1.Schema.string().role('textarea').default('🚫 已自动拒绝黑名单用户 {user} ({userId})。').description('自动拒绝通知'),
+    }).description('消息模板'),
+]);
+function apply(ctx, config) {
+    const logger = ctx.logger('blacklist-online');
+    // 1. 扩展数据库
+    ctx.model.extend('blacklist_users', {
+        userId: 'string', reason: 'string', disabled: { type: 'boolean', initial: false }, updatedAt: 'timestamp'
+    }, { primary: 'userId' });
+    ctx.model.extend('blacklist_request_queue', {
+        id: 'string', type: 'string', payload: 'json', createdAt: 'timestamp', retryCount: 'unsigned'
+    }, { primary: 'id' });
+    ctx.model.extend('blacklist_meta', {
+        key: 'string', value: 'string'
+    }, { primary: 'key' });
+    ctx.model.extend('blacklist_guild_settings', {
+        guildId: 'string', mode: 'string'
+    }, { primary: 'guildId' });
+    // 2. 初始化
+    ctx.on('ready', async () => {
+        // 生成/读取 InstanceUUID
+        const entries = await ctx.database.get('blacklist_meta', { key: 'instance_uuid' });
+        if (entries.length === 0) {
+            const uuid = (0, node_crypto_1.randomUUID)();
+            await ctx.database.create('blacklist_meta', { key: 'instance_uuid', value: uuid });
+            logger.info(`✨ 初始化实例 UUID: ${uuid}`);
+        }
+        else {
+            logger.info(`📱 当前实例 UUID: ${entries[0].value}`);
+        }
+        // 启动时立即同步一次
+        (0, core_1.syncBlacklist)(ctx, config);
+        // 启动时处理积压队列
+        (0, core_1.processOfflineQueue)(ctx, config);
+    });
+    // 3. 定时任务
+    ctx.setInterval(() => (0, core_1.syncBlacklist)(ctx, config), 5 * koishi_1.Time.minute); // 每5分同步
+    ctx.setInterval(() => (0, core_1.processOfflineQueue)(ctx, config), koishi_1.Time.minute); // 每1分处理队列
+    // 4. 事件监听
+    // 监听加群申请 (自动拒绝)
+    ctx.on('guild-member-request', async (session) => {
+        if (!config.enableAutoReject || !session.userId)
+            return;
+        // 先查本地白名单
+        if (config.protectedUsers.includes(session.userId))
+            return;
+        // 查库
+        const entries = await ctx.database.get('blacklist_users', { userId: session.userId, disabled: false });
+        if (entries.length > 0) {
+            try {
+                await session.bot.handleGuildRequest(session.messageId, false, config.rejectionMessage);
+                logger.info(`🚫 自动拒绝: ${session.userId}`);
+                const msg = config.autoRejectNotifyMessage.replace('{user}', session.userId).replace('{userId}', session.userId);
+                await session.send(msg);
+            }
+            catch (e) {
+                logger.warn(`拒绝申请失败: ${e}`);
+            }
+        }
+    });
+    // 监听新成员加入
+    ctx.on('guild-member-added', async (session) => {
+        if (!session.userId || !session.guildId)
+            return;
+        if (config.skipBotMembers && session.author?.isBot)
+            return;
+        await (0, core_1.checkAndHandleUser)(ctx, config, session, session.userId);
+    });
+    // 5. 指令集
+    const cmd = ctx.command('blacklist', '黑名单管理');
+    // 子指令: 申请拉黑
+    cmd.subcommand('.request <user:string> <reason:text>', '申请拉黑', { authority: 2 })
+        .action(async ({ session }, user, reason) => {
+        if (!session?.guildId)
+            return '请在群组中使用。';
+        if (!reason)
+            return '请填写理由。';
+        const userId = (0, core_1.parseUserId)(user);
+        // 本地白名单前置拦截
+        if (config.protectedUsers.includes(userId))
+            return '❌ 该用户在本地白名单中，无法拉黑。';
+        const requestId = (0, node_crypto_1.randomUUID)();
+        const payload = {
+            requestId: requestId,
+            type: 'ADD',
+            applicantId: session.userId,
+            targetUserId: userId,
+            reason,
+            guildId: session.guildId,
+            timestamp: Date.now()
+        };
+        try {
+            await ctx.http.post(`${config.remoteApiUrl}/applications`, payload, {
+                headers: { Authorization: `Bearer ${config.apiToken}` }
+            });
+            return `✅ 申请已提交至云端，请等待审批。\n🆔 申请ID: ${requestId}\n(可使用 blacklist.cancel 指令撤回)`;
+        }
+        catch (e) {
+            // 失败入队
+            await (0, core_1.queueRequest)(ctx, 'ADD', payload);
+            return `⚠️ 无法连接服务器，申请已加入离线队列。\n🆔 申请ID: ${requestId}\n将在网络恢复后自动提交。(可使用 blacklist.cancel 指令撤回)`;
+        }
+    });
+    // 子指令: 申请删除
+    cmd.subcommand('.delete <user:string> <reason:text>', '申请移除', { authority: 2 })
+        .action(async ({ session }, user, reason) => {
+        if (!session)
+            return '无有效session。';
+        if (!reason)
+            return '请填写理由。';
+        const userId = (0, core_1.parseUserId)(user);
+        const requestId = (0, node_crypto_1.randomUUID)();
+        const payload = {
+            requestId: requestId,
+            type: 'REMOVE',
+            applicantId: session.userId,
+            targetUserId: userId,
+            reason,
+            timestamp: Date.now()
+        };
+        try {
+            await ctx.http.post(`${config.remoteApiUrl}/applications`, payload, {
+                headers: { Authorization: `Bearer ${config.apiToken}` }
+            });
+            return `✅ 移除申请已提交。\n🆔 申请ID: ${requestId}`;
+        }
+        catch (e) {
+            await (0, core_1.queueRequest)(ctx, 'REMOVE', payload);
+            return `⚠️ 网络故障，移除申请已加入离线队列。\n🆔 申请ID: ${requestId}`;
+        }
+    });
+    // 子指令: 撤回申请
+    cmd.subcommand('.cancel <uuid:string>', '撤回申请', { authority: 2 })
+        .action(async ({ session }, uuid) => {
+        if (!uuid)
+            return '请输入要撤回的申请 UUID。';
+        const payload = {
+            requestId: (0, node_crypto_1.randomUUID)(),
+            targetRequestId: uuid,
+            applicantId: session?.userId,
+            timestamp: Date.now()
+        };
+        try {
+            await ctx.http.post(`${config.remoteApiUrl}/applications/cancel`, payload, {
+                headers: { Authorization: `Bearer ${config.apiToken}` }
+            });
+            return `✅ 针对申请 ${uuid} 的撤回指令已发送。`;
+        }
+        catch (e) {
+            await (0, core_1.queueRequest)(ctx, 'CANCEL', payload);
+            return `⚠️ 网络故障，针对 ${uuid} 的撤回指令已加入离线队列。`;
+        }
+    });
+    // 子指令: 设置模式
+    cmd.subcommand('.mode <mode:string>', '设置当前群处理模式', { authority: 3 })
+        .action(async ({ session }, mode) => {
+        if (!session?.guildId)
+            return;
+        const valid = ['off', 'notify', 'kick', 'both'];
+        if (!valid.includes(mode))
+            return `无效模式。可用: ${valid.join(', ')}`;
+        await ctx.database.upsert('blacklist_guild_settings', [{
+                guildId: session.guildId,
+                mode: mode
+            }]);
+        return `当前群模式已设置为: ${mode}`;
+    });
+    const scanCmd = cmd.subcommand('.scan', '黑名单扫描', { authority: 3 });
+    // 扫描当前群
+    scanCmd.action(async ({ session }) => {
+        if (!session?.guildId)
+            return '请在群组中使用。';
+        session.send('🔍 开始扫描本群...');
+        const result = await (0, core_1.scanGuild)(ctx, config, session.bot, session.guildId);
+        if (result.error)
+            return `⚠️ 扫描出错: ${result.error}`;
+        return `✅ 扫描结束。发现目标 ${result.total} 人，成功处理 ${result.handled} 人。`;
+    });
+    // 扫描所有群
+    scanCmd.subcommand('.all', '扫描所有群组 (高负载)', { authority: 4 })
+        .action(async ({ session }) => {
+        session?.send('🚀 开始全局扫描，这可能需要一些时间...');
+        const logger = ctx.logger('blacklist-online');
+        let totalGuilds = 0;
+        let totalHandled = 0;
+        let processedGuilds = 0;
+        // 遍历所有机器人实例
+        for (const bot of ctx.bots) {
+            try {
+                const guilds = await bot.getGuildList();
+                totalGuilds += guilds.data.length;
+                for (const guild of guilds.data) {
+                    // 逐个群扫描
+                    const result = await (0, core_1.scanGuild)(ctx, config, bot, guild.id);
+                    if (result.handled > 0) {
+                        logger.info(`[全局扫描] 群 ${guild.id}: 处理 ${result.handled}/${result.total}`);
+                        totalHandled += result.handled;
+                    }
+                    processedGuilds++;
+                }
+            }
+            catch (e) {
+                logger.warn(`Bot ${bot.selfId} 获取群列表失败: ${e}`);
+            }
+        }
+        return `✅ 全局扫描完成！\n共扫描群组: ${processedGuilds}/${totalGuilds}\n共处理黑名单用户: ${totalHandled} 人`;
+    });
+}

package/lib/types.d.ts

@@ -0,0 +1,47 @@
+export interface PluginConfig {
+    remoteApiUrl: string;
+    apiToken: string;
+    adminRoles: string[];
+    protectedUsers: string[];
+    defaultGuildMode: 'off' | 'notify' | 'kick' | 'both';
+    enableAutoReject: boolean;
+    skipBotMembers: boolean;
+    retryAttempts: number;
+    retryDelay: number;
+    verifyKickResult: boolean;
+    rejectionMessage: string;
+    adminNotifyMessage: string;
+    kickNotifyMessage: string;
+    kickFailMessage: string;
+    autoRejectNotifyMessage: string;
+}
+export interface BlacklistEntry {
+    userId: string;
+    reason: string;
+    operatorId?: string;
+    disabled: boolean;
+    updatedAt: Date;
+}
+export interface OfflineRequest {
+    id: string;
+    type: 'ADD' | 'REMOVE' | 'CANCEL';
+    payload: any;
+    createdAt: Date;
+    retryCount: number;
+}
+export interface MetaEntry {
+    key: string;
+    value: string;
+}
+export interface GuildSettings {
+    guildId: string;
+    mode: 'off' | 'notify' | 'kick' | 'both';
+}
+declare module 'koishi' {
+    interface Tables {
+        blacklist_users: BlacklistEntry;
+        blacklist_request_queue: OfflineRequest;
+        blacklist_meta: MetaEntry;
+        blacklist_guild_settings: GuildSettings;
+    }
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "koishi-plugin-blacklist-online",
+  "description": "自用插件",
+  "version": "0.1.0",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "auto-kick",
+    "blacklist",
+    "group-management",
+    "moderation",
+    "security"
+  ],
+  "peerDependencies": {
+    "koishi": "4.18.8"
+  }
+}

package/readme.md

@@ -0,0 +1,5 @@
+# koishi-plugin-blacklist-online
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-blacklist-online?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-blacklist-online)
+
+