koishi-plugin-aaqqbot 0.1.0

package/lib/config.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.MODE_RANK = void 0;
+const koishi_1 = require("koishi");
+exports.MODE_RANK = { off: 0, report: 1, remind: 2, enforce: 3 };
+const modeSchema = koishi_1.Schema.union([
+    koishi_1.Schema.const('off').description('off：不管这个群'),
+    koishi_1.Schema.const('report').description('report：只在运维群报告，群成员感觉不到'),
+    koishi_1.Schema.const('remind').description('remind：群里 @ 提醒 + 名片加标记，不踢'),
+    koishi_1.Schema.const('enforce').description('enforce：提醒 + 宽限期到了移出'),
+]);
+exports.Config = koishi_1.Schema.intersect([
+    koishi_1.Schema.object({
+        aaBaseUrl: koishi_1.Schema.string().role('link').required()
+            .description('AA 的网址，例如 `https://auth.example.com`。AA 装在子路径下时连子路径一起写，例如 `https://example.com/auth`。正式环境必须用 https。'),
+        keyId: koishi_1.Schema.string().pattern(/^[\x21-\x7e]{1,64}$/).required()
+            .description('密钥编号：AA 的 `local.py` 里 `QQBOT_API_KEYS` 的键，例如 `koishi-1`。只能用英文、数字和符号，不能有空格。'),
+        secret: koishi_1.Schema.string().role('secret').required()
+            .description('密钥：`QQBOT_API_KEYS` 里对应的值。只填在这里，不要发给任何人。'),
+        timeoutSeconds: koishi_1.Schema.natural().min(5).max(120).default(30)
+            .description('每次请求 AA 最多等多少秒。'),
+        bindUrl: koishi_1.Schema.string().role('link').default('')
+            .description('成员去绑定 QQ 的网址，会写进拒绝理由和提醒里。留空时使用「AA 的网址 + /services/」。'),
+    }).description('连接 AA'),
+    koishi_1.Schema.object({
+        botId: koishi_1.Schema.string().default('')
+            .description('用哪个机器人账号管理（填机器人的 QQ 号）。这个 Koishi 里只有一个 QQ 机器人时可以留空。'),
+        adminGroupId: koishi_1.Schema.string().default('')
+            .description('运维群号：巡检汇总、报警都发到这里。只放管理人员，**不能是被管理的群**。管理命令也只能在这个群里或私聊机器人时使用。'),
+        operators: koishi_1.Schema.array(koishi_1.Schema.string()).role('table').default([])
+            .description('运维名单（QQ 号）：只有名单里、并且 Koishi 权限等级 ≥ 3 的人能用管理命令。'),
+        whitelist: koishi_1.Schema.array(koishi_1.Schema.string()).role('table').default([])
+            .description('白名单（QQ 号）：这些人永远不会被提醒、改名片或移出。机器人自己、群主、群管理员已自动保护，不用填。'),
+    }).description('机器人与运维'),
+    koishi_1.Schema.object({
+        defaultMode: modeSchema.default('report')
+            .description('AA 上新加的群默认用哪种模式。'),
+        groupModes: koishi_1.Schema.array(koishi_1.Schema.object({
+            groupId: koishi_1.Schema.string().required().description('群号'),
+            mode: modeSchema.default('report').description('模式'),
+        })).role('table').default([])
+            .description('单独设置某些群的模式。**升级到 remind 或 enforce 后，要等一轮巡检报告出来，由管理员发送 `aaqq.confirm 群号` 确认后才真正生效**；降级立即生效。'),
+    }).description('群模式'),
+    koishi_1.Schema.object({
+        autoReject: koishi_1.Schema.boolean().default(true)
+            .description('AA 明确判定不合格时自动拒绝入群申请（只在 remind / enforce 模式的群里）。关掉则留给管理员处理。AA 连不上、需要人工处理时永远不会拒绝。'),
+        rejectTemplate: koishi_1.Schema.string().default('{hint}。绑定地址：{url}')
+            .description('拒绝理由。`{hint}` 是自动生成的原因说明，`{url}` 是绑定网址。'),
+        inviteHandling: koishi_1.Schema.union([
+            koishi_1.Schema.const('same').description('和普通申请一样问 AA'),
+            koishi_1.Schema.const('manual').description('一律留给管理员'),
+        ]).default('same')
+            .description('群成员邀请别人入群、需要审核时（申请里没有验证信息）怎么处理。'),
+        catchUpRequests: koishi_1.Schema.boolean().default(true)
+            .description('机器人重新上线时，补处理掉线期间还挂着的入群申请。'),
+    }).description('入群申请'),
+    koishi_1.Schema.object({
+        patrolIntervalHours: koishi_1.Schema.natural().min(1).max(24).default(6)
+            .description('每隔几小时巡检一次所有群（插件启动后会先巡检一次）。'),
+        eventPollSeconds: koishi_1.Schema.natural().min(30).max(600).default(60)
+            .description('每隔几秒向 AA 拉取一次变化（解绑、退组等），发现后立即复查相关的人。'),
+        syncCards: koishi_1.Schema.boolean().default(true)
+            .description('按 AA 算好的名片同步合格成员的群名片（只在 remind / enforce 模式的群里；成员自己改掉的会在下次巡检时改回）。'),
+    }).description('巡检与群名片'),
+    koishi_1.Schema.object({
+        graceHours: koishi_1.Schema.natural().min(1).max(720).default(48)
+            .description('enforce 模式下的宽限期：从第一次收到带截止时间的 @ 提醒开始算，过了时间还不合格才移出。移出前 36 小时内一定成功提醒过这个人。'),
+        remindTime: koishi_1.Schema.string().pattern(/^\s*([01]?\d|2[0-3]):[0-5]\d\s*$/).default('19:30')
+            .description('每天几点在群里 @ 提醒不合格的人（机器人电脑的本地时间，格式 `19:30`）。'),
+        remindTemplate: koishi_1.Schema.string().role('textarea').default('以下成员还没有满足本群的要求，请尽快在联盟 AA 完成 QQ 绑定：{url}\n{list}')
+            .description('remind 模式的提醒文字。`{list}` 是被 @ 的人和原因，`{url}` 是绑定网址。'),
+        warnTemplate: koishi_1.Schema.string().role('textarea').default('以下成员还没有满足本群的要求，请在截止时间前在联盟 AA 完成 QQ 绑定，否则会被移出本群：{url}\n{list}')
+            .description('enforce 模式的提醒文字。`{list}` 里会带上每个人的截止时间。'),
+        markCards: koishi_1.Schema.boolean().default(true)
+            .description('给不合格的人的群名片前面加标记（remind / enforce 模式）。合格后自动改成 AA 给的名片。'),
+        markPrefix: koishi_1.Schema.string().default('【SPY】')
+            .description('名片标记，例如 `【SPY】`，会加在原名片前面。'),
+        kickAnnounce: koishi_1.Schema.boolean().default(true)
+            .description('enforce 模式移出成员后，在该群里也发一条公告。'),
+        kickAnnounceTemplate: koishi_1.Schema.string().role('textarea').default('以下成员因未满足本群的要求已被移出：{list}\n完成联盟 AA 绑定后可以重新申请入群：{url}')
+            .description('移出公告。`{list}` 是被移出的人的名片。'),
+    }).description('宽限、提醒与标记'),
+    koishi_1.Schema.object({
+        breakerCount: koishi_1.Schema.natural().min(1).max(100).default(5)
+            .description('熔断人数：一轮里某个群新增的不合格人数超过这个数（或超过下面的比例，取较小者，但至少为 1）时，这个群这一轮什么都不做，只报警，等管理员发送 `aaqq.confirm 群号` 确认。'),
+        breakerPercent: koishi_1.Schema.natural().min(1).max(100).default(10)
+            .description('熔断比例（占群人数的百分比）。'),
+        kickPerHour: koishi_1.Schema.natural().min(1).max(100).default(10)
+            .description('每个群每小时最多移出几个人，超过的留到下一轮。'),
+    }).description('防误踢（熔断）'),
+]);

package/lib/guard.d.ts

@@ -0,0 +1,175 @@
+import { Bot, Context, Logger } from 'koishi';
+import { AaClient, ManagedGroup } from './aa';
+import { Config, Mode } from './config';
+import { Notifier } from './notifier';
+import { Platform } from './platform';
+import { Member, Plan, Role } from './policy';
+import { GroupState, Store, TrackedMember } from './store';
+export interface GuardOptions {
+    now?: () => number;
+    /** 自动运行定时任务（测试里关掉，手动调用各方法）。 */
+    timers?: boolean;
+    /** AA 请求失败时的重试等待。 */
+    retryDelays?: number[];
+    /** 两次改名片之间的间隔。 */
+    cardDelayMs?: number;
+    /** 两次移出之间的间隔（实际在这个值到两倍之间随机）。 */
+    kickDelayMs?: number;
+    /** 巡检时两个群之间的间隔。 */
+    groupDelayMs?: number;
+}
+export interface ModeInfo {
+    desired: Mode;
+    effective: Mode;
+    /** 设了 remind / enforce 但还没确认。 */
+    awaiting: boolean;
+    held: boolean;
+}
+interface ApplyResult {
+    cardsOk: number;
+    cardsFailed: number;
+    cardsDeferred: number;
+    marked: number;
+    unmarked: number;
+    synced: number;
+    kicked: Array<{
+        qq: string;
+        name: string;
+    }>;
+    kickFailed: number;
+    kickSkipped: number;
+}
+export declare class Guard {
+    private ctx;
+    config: Config;
+    private options;
+    readonly logger: Logger;
+    readonly aa: AaClient;
+    readonly store: Store;
+    readonly platform: Platform;
+    readonly notifier: Notifier;
+    groups: ManagedGroup[];
+    groupsLoaded: boolean;
+    paused: boolean;
+    /** 运维群号出现在受管群列表里时为 true（这时不发通知，见 R18）。 */
+    adminGroupConflict: boolean;
+    rosters: Map<string, Map<string, Member>>;
+    lastRound: {
+        at: number;
+        ok: boolean;
+        text: string;
+    } | null;
+    patrolRunning: boolean;
+    nextPatrolAt: number | null;
+    /** start() 的执行结果（测试里用来等待启动完成）。 */
+    started: Promise<void> | null;
+    private life;
+    private round;
+    private patrolQueue;
+    private eventsBusy;
+    private remindBusy;
+    private aaDown;
+    private botProblem;
+    private handledFlags;
+    private approved;
+    private timers;
+    private lastPrune;
+    constructor(ctx: Context, config: Config, options?: GuardOptions);
+    now(): number;
+    get signal(): AbortSignal;
+    adminGroup(): string | null;
+    operators(): Set<string>;
+    protectedIds(): Set<string>;
+    /**
+     * 事件游标和受管群列表是「某一个 AA」的数据：换了 AA 网址（例如从测试 AA 换到正式 AA）后要重新开始，
+     * 否则会拿测试 AA 的游标去读正式 AA，漏掉一批变化。
+     */
+    get cursorKey(): string;
+    get groupsKey(): string;
+    private aaIdentity;
+    bindUrl(): string;
+    group(groupId: string): ManagedGroup | undefined;
+    groupLabel(groupId: string): string;
+    desiredMode(groupId: string): Mode;
+    modeInfo(groupId: string, state: GroupState): ModeInfo;
+    private writeMode;
+    install(): void;
+    dispose(): void;
+    /** 包一层 try/catch：Koishi 里同步抛错会让整个进程退出（R20）。 */
+    safely(what: string, task: () => unknown): void;
+    start(): Promise<void>;
+    private schedule;
+    private patrolTick;
+    private eventsTick;
+    private groupsTick;
+    private scheduleReminder;
+    /** 尽快巡检（全部群或指定的群）。正在巡检时，结束后立刻再跑一轮。 */
+    requestPatrol(groupIds?: string[]): void;
+    private noteAaFailure;
+    private noteAaOk;
+    private pickBot;
+    checkHealth(notify: boolean): Promise<string>;
+    refreshGroups(): Promise<boolean>;
+    /**
+     * 巡检一轮。返回 'busy'（上一轮还没结束）、'paused'、'no-bot'、'no-groups' 或 'done'。
+     * 同一时间只有一轮（R11）；暂停、停用、改配置会立即中止（R10）。
+     */
+    runPatrol(only?: string[]): Promise<'busy' | 'paused' | 'no-bot' | 'no-groups' | 'done'>;
+    private notifyBotProblemOnce;
+    patrolGroup(bot: Bot, g: ManagedGroup, signal: AbortSignal): Promise<{
+        ok: boolean;
+        text: string;
+    }>;
+    /** 管理员确认后 1 小时内有效的豁免。 */
+    private bypassFor;
+    /** 群改成 off 时，撤掉以前加的标记、清空宽限记录，之后就不再管这个群。 */
+    private cleanupOffGroup;
+    private planSettings;
+    private describePlan;
+    /**
+     * 执行规划。先移出、再改名片。每一次改动前都重新检查：没有中止、没有暂停、没有熔断；
+     * 移出前再问一次 AA、重读宽限记录、实时查询成员身份（R7）。通知失败不影响执行结果（R18）。
+     */
+    applyPlan(bot: Bot, groupId: string, plan: Plan, signal: AbortSignal): Promise<ApplyResult>;
+    /** 还能不能继续改动这个群：没有中止、没有暂停、没有进入熔断。 */
+    private stillWritable;
+    private applyKicks;
+    private pause;
+    private onRequestSession;
+    handleJoinRequest(bot: Bot, req: {
+        flag: string;
+        groupId: string;
+        qq: string;
+        comment: string;
+        invitorId: string | null;
+    }, source?: string, catchUp?: boolean): Promise<void>;
+    /** 机器人重新上线：补处理掉线期间积压的入群申请（DECISIONS 第 13 条）。 */
+    private onBotStatus;
+    catchUpRequests(bot: Bot): Promise<void>;
+    private onMemberAdded;
+    handleNewMember(bot: Bot, groupId: string, qq: string): Promise<void>;
+    private onMemberRemoved;
+    pollEvents(): Promise<void>;
+    /** 游标丢失（第一次运行）：把已有事件拉完只记游标，然后做一次完整巡检。 */
+    private initCursor;
+    /** 按群合并复查一批 QQ（每个群只发一次 check）。返回是否全部处理完。 */
+    recheck(qqs: string[]): Promise<boolean>;
+    runReminders(): Promise<void>;
+    /**
+     * 在群里 @ 提醒（每条最多 20 人）。enforce 模式下，第一次成功提醒某人时才定下他的截止时间
+     * （现在 + 宽限期），保证每个人被移出前都收到过带截止时间的提醒。
+     */
+    sendReminder(bot: Bot, groupId: string, mode: Mode, rows: TrackedMember[]): Promise<void>;
+    setPaused(paused: boolean, actor: string): Promise<void>;
+    /**
+     * 管理员确认：模式升级生效和/或解除熔断，并马上重新巡检这个群。
+     * 接下来 1 小时内的那一轮巡检，只要人数不超过这次确认时报告里的人数，就不会再熔断。
+     */
+    confirm(groupId: string, actor: string): Promise<string>;
+    statusText(): Promise<string>;
+    /** 查询一个 QQ 在各受管群的判定（只给运维用，输出不含角色名）。 */
+    checkQq(qq: string): Promise<string>;
+    private pruneMaps;
+    private pruneAudit;
+}
+export type { Role };