koishi-plugin-aaqqbot 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+import { Context } from 'koishi';
+import { Config } from './config';
+export declare const name = "aaqqbot";
+export declare const inject: {
+    required: string[];
+};
+export { Config };
+export declare const usage = "\n\u914D\u5408 AllianceAuth \u63D2\u4EF6 **aa-qqbot** \u7BA1\u7406\u8054\u76DF QQ \u7FA4\uFF1A\u5BA1\u6279\u5165\u7FA4\u7533\u8BF7\u3001\u5B9A\u65F6\u5DE1\u68C0\u3001@ \u63D0\u9192\u3001\u540D\u7247\u52A0\u6807\u8BB0\u3001\u79FB\u51FA\u4E0D\u5408\u683C\u6210\u5458\u3001\u540C\u6B65\u7FA4\u540D\u7247\u3002\n\n**\u7B2C\u4E00\u6B21\u4F7F\u7528\uFF1A**\n\n1. \u5728 AA \u4E0A\u88C5\u597D aa-qqbot\uFF0C\u7531 IT \u5728 `local.py` \u91CC\u914D\u7F6E `QQBOT_API_KEYS`\uFF08\u5BC6\u94A5\u7F16\u53F7 \u2192 \u5BC6\u94A5\uFF09\u3002\n2. \u5728\u4E0B\u9762\u586B\u597D\u300CAA \u7684\u7F51\u5740\u300D\u300C\u5BC6\u94A5\u7F16\u53F7\u300D\u300C\u5BC6\u94A5\u300D\uFF0C\u4EE5\u53CA\u8FD0\u7EF4\u7FA4\u53F7\u3001\u8FD0\u7EF4\u540D\u5355\u3002\n3. \u542F\u7528\u63D2\u4EF6\u540E\uFF0C\u5728\u8FD0\u7EF4\u7FA4\u91CC\u53D1\u9001 `aaqq.health` \u68C0\u67E5\u8FDE\u63A5\uFF0C\u53D1\u9001 `aaqq.status` \u67E5\u770B\u53D7\u7BA1\u7FA4\u3002\n4. \u6240\u6709\u7FA4\u9ED8\u8BA4 **report\uFF08\u53EA\u62A5\u544A\uFF09**\uFF1A\u673A\u5668\u4EBA\u53EA\u5BA1\u6279\u5408\u683C\u7684\u5165\u7FA4\u7533\u8BF7\uFF0C\u5E76\u628A\u5DE1\u68C0\u7ED3\u679C\u53D1\u5230\u8FD0\u7EF4\u7FA4\uFF0C\u4E0D\u6539\u52A8\u7FA4\u91CC\u4EFB\u4F55\u4E1C\u897F\u3002\n5. \u770B\u8FC7\u62A5\u544A\u3001\u786E\u8BA4\u6CA1\u95EE\u9898\u540E\uFF0C\u518D\u628A\u67D0\u4E2A\u7FA4\u6539\u6210 remind \u6216 enforce\uFF0C\u5E76\u5728\u8FD0\u7EF4\u7FA4\u53D1\u9001 `aaqq.confirm \u7FA4\u53F7` \u786E\u8BA4\u3002\n\n**\u5B89\u5168\u4FDD\u8BC1\uFF1A** AA \u8FDE\u4E0D\u4E0A\u3001\u8FD4\u56DE\u5F02\u5E38\u6216\u5224\u5B9A\u4E3A\u300C\u9700\u8981\u4EBA\u5DE5\u5904\u7406\u300D\u65F6\uFF0C\u673A\u5668\u4EBA\u4EC0\u4E48\u90FD\u4E0D\u505A\uFF1B\u7FA4\u4E3B\u3001\u7BA1\u7406\u5458\u3001\u673A\u5668\u4EBA\u81EA\u5DF1\u548C\u767D\u540D\u5355\u6C38\u8FDC\u4E0D\u4F1A\u88AB\u5904\u7F6E\uFF1B\n\u4E00\u8F6E\u91CC\u65B0\u53D1\u73B0\u7684\u4E0D\u5408\u683C\u4EBA\u6570\u592A\u591A\u65F6\u81EA\u52A8\u7194\u65AD\uFF0C\u7B49\u7BA1\u7406\u5458\u786E\u8BA4\u3002\u7D27\u6025\u60C5\u51B5\u53D1\u9001 `aaqq.pause` \u7ACB\u5373\u505C\u6B62\u4E00\u5207\u64CD\u4F5C\u3002\n\n\u8BE6\u7EC6\u8BF4\u660E\u89C1 [README](https://github.com/yilifaer/Koishi-AAqqbot-plugin#readme)\u3002\n";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usage = exports.Config = exports.inject = exports.name = void 0;
+exports.apply = apply;
+const commands_1 = require("./commands");
+const config_1 = require("./config");
+Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_1.Config; } });
+const guard_1 = require("./guard");
+exports.name = 'aaqqbot';
+// 数据库：保存宽限记录、游标、暂停状态；没有数据库时 Koishi 的权限检查会完全失效（交接文档 03 #26）
+exports.inject = { required: ['database', 'http'] };
+exports.usage = `
+配合 AllianceAuth 插件 **aa-qqbot** 管理联盟 QQ 群：审批入群申请、定时巡检、@ 提醒、名片加标记、移出不合格成员、同步群名片。
+
+**第一次使用：**
+
+1. 在 AA 上装好 aa-qqbot，由 IT 在 \`local.py\` 里配置 \`QQBOT_API_KEYS\`（密钥编号 → 密钥）。
+2. 在下面填好「AA 的网址」「密钥编号」「密钥」，以及运维群号、运维名单。
+3. 启用插件后，在运维群里发送 \`aaqq.health\` 检查连接，发送 \`aaqq.status\` 查看受管群。
+4. 所有群默认 **report（只报告）**：机器人只审批合格的入群申请，并把巡检结果发到运维群，不改动群里任何东西。
+5. 看过报告、确认没问题后，再把某个群改成 remind 或 enforce，并在运维群发送 \`aaqq.confirm 群号\` 确认。
+
+**安全保证：** AA 连不上、返回异常或判定为「需要人工处理」时，机器人什么都不做；群主、管理员、机器人自己和白名单永远不会被处置；
+一轮里新发现的不合格人数太多时自动熔断，等管理员确认。紧急情况发送 \`aaqq.pause\` 立即停止一切操作。
+
+详细说明见 [README](https://github.com/yilifaer/Koishi-AAqqbot-plugin#readme)。
+`;
+function apply(ctx, config) {
+    const guard = new guard_1.Guard(ctx, config);
+    guard.install();
+    (0, commands_1.registerCommands)(ctx, guard);
+}

package/lib/notifier.d.ts

@@ -0,0 +1,24 @@
+import { Logger } from 'koishi';
+import type { Platform } from './platform';
+export declare class Notifier {
+    private platform;
+    private logger;
+    private getAdminGroup;
+    private now;
+    private queue;
+    private timer;
+    private sentAt;
+    private dropped;
+    /** 测试用：记录发出的每条消息。 */
+    history: string[];
+    constructor(platform: Platform, logger: Logger, getAdminGroup: () => string | null, now?: () => number);
+    /** 排队一条通知；几秒内的通知合并发送。 */
+    push(text: string): void;
+    dispose(): void;
+    flush(): Promise<void>;
+    private sendOne;
+}
+/** 按行把多条通知拼成若干条不超过上限的消息。 */
+export declare function pack(items: string[]): string[];
+/** 运维群号：规范化后返回；没填返回 null。 */
+export declare function resolveAdminGroup(value: string): string | null;

package/lib/notifier.js

@@ -0,0 +1,126 @@
+"use strict";
+// 发到运维群的通知：短时间内的多条合并成一条、全局限速、发送失败只记日志（交接文档 R18）。
+// 所有内容都按纯文本发送（h.text），名片、群名、错误信息里的 <at> 之类不会被当成消息元素。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Notifier = void 0;
+exports.pack = pack;
+exports.resolveAdminGroup = resolveAdminGroup;
+const koishi_1 = require("koishi");
+const util_1 = require("./util");
+const MAX_MESSAGE_CHARS = 1500;
+const MAX_MESSAGES_PER_HOUR = 30;
+const FLUSH_DELAY_MS = 3000;
+class Notifier {
+    platform;
+    logger;
+    getAdminGroup;
+    now;
+    queue = [];
+    timer = null;
+    sentAt = [];
+    dropped = 0;
+    /** 测试用：记录发出的每条消息。 */
+    history = [];
+    constructor(platform, logger, getAdminGroup, now = Date.now) {
+        this.platform = platform;
+        this.logger = logger;
+        this.getAdminGroup = getAdminGroup;
+        this.now = now;
+    }
+    /** 排队一条通知；几秒内的通知合并发送。 */
+    push(text) {
+        this.logger.info('%s', text.replace(/\n/g, ' | '));
+        if (!this.getAdminGroup())
+            return;
+        this.queue.push(text);
+        if (!this.timer)
+            this.timer = setTimeout(() => void this.flush(), FLUSH_DELAY_MS);
+    }
+    dispose() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.queue = [];
+    }
+    async flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        const items = this.queue.splice(0);
+        if (!items.length)
+            return;
+        const groupId = this.getAdminGroup();
+        if (!groupId)
+            return;
+        for (const message of pack(items)) {
+            await this.sendOne(groupId, message);
+        }
+    }
+    async sendOne(groupId, text) {
+        const now = this.now();
+        this.sentAt = this.sentAt.filter((t) => now - t < 3600_000);
+        if (this.sentAt.length >= MAX_MESSAGES_PER_HOUR) {
+            this.dropped++;
+            this.logger.warn('运维通知超过每小时 %d 条的上限，这条只写日志', MAX_MESSAGES_PER_HOUR);
+            return;
+        }
+        if (this.dropped) {
+            text = `（之前有 ${this.dropped} 条通知因为限速没有发出，请看 Koishi 日志）\n${text}`;
+            this.dropped = 0;
+        }
+        const { bot, problem } = this.platform.pickBot();
+        if (!bot) {
+            this.logger.warn('运维通知没有发出：%s', problem);
+            return;
+        }
+        try {
+            this.sentAt.push(now);
+            this.history.push(text);
+            if (this.history.length > 50)
+                this.history.shift();
+            await this.platform.sendGroup(bot, groupId, koishi_1.h.text(text));
+        }
+        catch (error) {
+            this.logger.warn('运维通知发送失败：%s', error);
+        }
+    }
+}
+exports.Notifier = Notifier;
+/** 按行把多条通知拼成若干条不超过上限的消息。 */
+function pack(items) {
+    const messages = [];
+    let current = '';
+    for (const item of items) {
+        for (const piece of splitLong(item)) {
+            if (current && current.length + 2 + piece.length > MAX_MESSAGE_CHARS) {
+                messages.push(current);
+                current = '';
+            }
+            current = current ? `${current}\n\n${piece}` : piece;
+        }
+    }
+    if (current)
+        messages.push(current);
+    return messages;
+}
+function splitLong(text) {
+    if (text.length <= MAX_MESSAGE_CHARS)
+        return [text];
+    const pieces = [];
+    let current = '';
+    for (const line of text.split('\n')) {
+        const safeLine = line.length > MAX_MESSAGE_CHARS ? line.slice(0, MAX_MESSAGE_CHARS - 1) + '…' : line;
+        if (current && current.length + 1 + safeLine.length > MAX_MESSAGE_CHARS) {
+            pieces.push(current);
+            current = '';
+        }
+        current = current ? `${current}\n${safeLine}` : safeLine;
+    }
+    if (current)
+        pieces.push(current);
+    return pieces;
+}
+/** 运维群号：规范化后返回；没填返回 null。 */
+function resolveAdminGroup(value) {
+    return (0, util_1.normalizeId)(value);
+}

package/lib/platform.d.ts

@@ -0,0 +1,34 @@
+import { Bot, Context, Fragment } from 'koishi';
+import type { Member } from './policy';
+export interface PendingJoinRequest {
+    flag: string;
+    groupId: string;
+    qq: string;
+    comment: string;
+    invitorId: string | null;
+}
+export declare class Platform {
+    private ctx;
+    private getBotId;
+    constructor(ctx: Context, getBotId: () => string);
+    /** 所有机器人账号（任何平台），永远不处置。 */
+    allSelfIds(): Set<string>;
+    /**
+     * 选出负责管理的 OneBot 机器人。配置了 botId 时只用它；
+     * 没配置时，只有恰好一个 OneBot 机器人才使用，避免多个机器人重复处置（交接文档 D37）。
+     */
+    pickBot(): {
+        bot: Bot | null;
+        problem: string | null;
+    };
+    listMembers(bot: Bot, groupId: string): Promise<Member[]>;
+    /** 实时查询一个成员（不走缓存）。查不到或出错时返回 null。 */
+    getMember(bot: Bot, groupId: string, qq: string): Promise<Member | null>;
+    /** 移出，不拉黑（reject_add_request = false，DECISIONS 第 15 条）。 */
+    kick(bot: Bot, groupId: string, qq: string): Promise<void>;
+    setCard(bot: Bot, groupId: string, qq: string, card: string): Promise<void>;
+    handleJoinRequest(bot: Bot, flag: string, approve: boolean, reason?: string): Promise<void>;
+    sendGroup(bot: Bot, groupId: string, content: Fragment): Promise<void>;
+    /** 掉线期间积压的入群申请（LLBot 的 get_group_system_msg；字段名按 LLBot 实际返回解析）。 */
+    pendingJoinRequests(bot: Bot): Promise<PendingJoinRequest[]>;
+}

package/lib/platform.js

@@ -0,0 +1,116 @@
+"use strict";
+// 对 OneBot（LLBot）接口的薄封装。只用 adapter-onebot 6.9.4 里确实存在的方法（见交接文档 03 平台调研）。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Platform = void 0;
+const util_1 = require("./util");
+class Platform {
+    ctx;
+    getBotId;
+    constructor(ctx, getBotId) {
+        this.ctx = ctx;
+        this.getBotId = getBotId;
+    }
+    /** 所有机器人账号（任何平台），永远不处置。 */
+    allSelfIds() {
+        return new Set(this.ctx.bots.map((bot) => bot.selfId).filter(Boolean));
+    }
+    /**
+     * 选出负责管理的 OneBot 机器人。配置了 botId 时只用它；
+     * 没配置时，只有恰好一个 OneBot 机器人才使用，避免多个机器人重复处置（交接文档 D37）。
+     */
+    pickBot() {
+        const bots = this.ctx.bots.filter((bot) => bot.platform === 'onebot');
+        const wanted = (0, util_1.normalizeId)(this.getBotId());
+        let bot;
+        if (wanted) {
+            bot = bots.find((b) => b.selfId === wanted);
+            if (!bot)
+                return { bot: null, problem: `找不到 QQ 号为 ${wanted} 的 OneBot 机器人` };
+        }
+        else if (bots.length === 1) {
+            bot = bots[0];
+        }
+        else if (bots.length === 0) {
+            return { bot: null, problem: '这个 Koishi 里没有 OneBot 机器人' };
+        }
+        else {
+            return { bot: null, problem: '这个 Koishi 里有多个 OneBot 机器人，请在插件配置里填写「用哪个机器人账号管理」' };
+        }
+        if (bot.status !== 1 /* Universal.Status.ONLINE */)
+            return { bot: null, problem: `机器人 ${bot.selfId} 当前不在线` };
+        if (typeof bot.internal?._request !== 'function')
+            return { bot: null, problem: `机器人 ${bot.selfId} 与 LLBot 的连接已断开` };
+        return { bot, problem: null };
+    }
+    async listMembers(bot, groupId) {
+        const list = await bot.internal.getGroupMemberList(groupId);
+        if (!Array.isArray(list))
+            throw new Error('群成员列表格式不对');
+        const members = [];
+        for (const item of list) {
+            const member = toMember(item);
+            if (member)
+                members.push(member);
+        }
+        return members;
+    }
+    /** 实时查询一个成员（不走缓存）。查不到或出错时返回 null。 */
+    async getMember(bot, groupId, qq) {
+        try {
+            return toMember(await bot.internal.getGroupMemberInfo(groupId, qq, true));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 移出，不拉黑（reject_add_request = false，DECISIONS 第 15 条）。 */
+    async kick(bot, groupId, qq) {
+        await bot.internal.setGroupKick(groupId, qq, false);
+    }
+    async setCard(bot, groupId, qq, card) {
+        await bot.internal.setGroupCard(groupId, qq, card);
+    }
+    async handleJoinRequest(bot, flag, approve, reason = '') {
+        await bot.handleGuildMemberRequest(flag, approve, reason);
+    }
+    async sendGroup(bot, groupId, content) {
+        await bot.sendMessage(groupId, content);
+    }
+    /** 掉线期间积压的入群申请（LLBot 的 get_group_system_msg；字段名按 LLBot 实际返回解析）。 */
+    async pendingJoinRequests(bot) {
+        const data = await bot.internal.getGroupSystemMsg();
+        const list = Array.isArray(data?.join_requests) ? data.join_requests : [];
+        const result = [];
+        for (const item of list) {
+            if (!item || item.checked === true)
+                continue;
+            const groupId = (0, util_1.normalizeId)(item.group_id);
+            const qq = (0, util_1.normalizeId)(item.requester_uin);
+            if (!groupId || !qq || item.request_id === undefined || item.request_id === null)
+                continue;
+            result.push({
+                flag: String(item.request_id),
+                groupId,
+                qq,
+                comment: typeof item.message === 'string' ? item.message : '',
+                invitorId: (0, util_1.normalizeId)(item.invitor_uin),
+            });
+        }
+        return result;
+    }
+}
+exports.Platform = Platform;
+function toMember(item) {
+    const qq = (0, util_1.normalizeId)(item?.user_id);
+    if (!qq)
+        return null;
+    // 只有明确是 member 的才算普通成员；认不出来的按受保护处理（R7「角色判不出就跳过」）
+    const role = item.role === 'owner' || item.role === 'admin' || item.role === 'member' ? item.role : 'unknown';
+    return {
+        qq,
+        role,
+        card: typeof item.card === 'string' ? item.card : '',
+        nickname: typeof item.nickname === 'string' ? item.nickname : '',
+        isRobot: item.is_robot === true,
+    };
+}

package/lib/policy.d.ts

@@ -0,0 +1,122 @@
+import type { Verdict } from './aa';
+import type { Mode } from './config';
+import type { TrackedMember } from './store';
+/** QQ 群名片上限按 60 字节处理（与 AA 端一致，API.md 第 9 节）。 */
+export declare const CARD_LIMIT_BYTES = 60;
+/** unknown：平台返回的身份认不出来，按受保护处理（R7「角色判不出就跳过」）。 */
+export type Role = 'owner' | 'admin' | 'member' | 'unknown';
+export interface Member {
+    qq: string;
+    role: Role;
+    card: string;
+    nickname: string;
+    isRobot: boolean;
+}
+export interface PlanSettings {
+    breakerCount: number;
+    breakerPercent: number;
+    /** 这个群这一小时里还能移出几个人。 */
+    kickBudget: number;
+    syncCards: boolean;
+    markCards: boolean;
+    markPrefix: string;
+    /** 只有完整巡检才允许移出；事件、新人、提醒这些局部复查不移出。 */
+    allowKicks: boolean;
+    /** 移出前多久之内必须成功提醒过（毫秒）。 */
+    remindFreshMs: number;
+}
+/** 管理员确认后的豁免：不超过报告里看到的人数就不熔断。 */
+export interface Bypass {
+    maxNew: number;
+    maxKicks: number;
+}
+export interface PlanInput {
+    groupId: string;
+    /** 生效中的模式（未确认的升级不生效）。 */
+    mode: Mode;
+    /** 这个群已经处于熔断状态。 */
+    held: boolean;
+    bypass: Bypass | null;
+    /** 截止时间在这个时刻之前的，已经由管理员确认过（不计入「批量移出」熔断）。 */
+    kickApprovedBefore: number;
+    /** members 只是群里的一部分人（事件、新人、提醒）。 */
+    partial: boolean;
+    /** 群的总人数，用来算熔断比例。 */
+    groupSize: number;
+    members: Member[];
+    verdicts: Map<string, Verdict>;
+    tracked: Map<string, TrackedMember>;
+    /** 这个 Koishi 里的机器人账号 + 白名单。 */
+    protectedIds: Set<string>;
+    /** 机器人在这个群里的身份；不是群主或管理员时什么都改不了。 */
+    botRole: Role | null;
+    now: number;
+    settings: PlanSettings;
+}
+export interface CardChange {
+    qq: string;
+    from: string;
+    to: string;
+    why: 'sync' | 'mark' | 'unmark';
+}
+export interface KickPlan {
+    qq: string;
+    reason: string;
+    name: string;
+}
+export interface Plan {
+    counts: {
+        members: number;
+        allow: number;
+        deny: number;
+        review: number;
+        unknown: number;
+    };
+    /** 不受保护、判为 deny 的人。 */
+    denies: Array<{
+        qq: string;
+        reason: string;
+        isNew: boolean;
+    }>;
+    /** 判为 deny 但受保护（群主、管理员、机器人、白名单），永不处置，只报告。 */
+    protectedDenies: Array<{
+        qq: string;
+        reason: string;
+    }>;
+    reviews: Array<{
+        qq: string;
+        reason: string;
+    }>;
+    unknowns: string[];
+    newDenies: Array<{
+        qq: string;
+        reason: string;
+    }>;
+    threshold: number;
+    /** 宽限期已到、可以移出的人数（未扣除每小时上限）。 */
+    kicksDue: number;
+    /** 这一轮新触发了熔断。 */
+    tripped: boolean;
+    tripReason: string;
+    /** 无法判断的人太多，这一轮不改动（R9 ③）。 */
+    unknownHeavy: boolean;
+    /** 这一轮允许改动群（加标记、改名片、移出）。 */
+    writes: boolean;
+    track: TrackedMember[];
+    untrack: string[];
+    /** 先加/去标记，再同步名片。 */
+    cards: CardChange[];
+    kicks: KickPlan[];
+    kicksDeferred: number;
+    /** 不允许改动时，本来要同步的名片数（写进报告）。 */
+    cardsPending: number;
+}
+export declare function breakerThreshold(groupSize: number, count: number, percent: number): number;
+/** 只有身份确定是普通成员、不是机器人、不在保护名单里的人才可能被处置。 */
+export declare function isProtected(member: Member, protectedIds: Set<string>): boolean;
+export declare function botCanWrite(botRole: Role | null): boolean;
+/** 机器人能不能改这个普通成员的名片（群主和管理员都能改普通成员）。 */
+export declare function canEditCard(botRole: Role | null, target: Member): boolean;
+export declare function markedCard(prefix: string, member: Member): string;
+export declare function stripMark(prefix: string, card: string): string;
+export declare function planGroup(input: PlanInput): Plan;

package/lib/policy.js

@@ -0,0 +1,203 @@
+"use strict";
+// 处置规划：给定群成员、AA 判定和已有的宽限记录，算出这一轮要做的事。
+// 这里是纯函数，不碰 QQ 也不碰数据库；真正执行由 guard.ts 完成（执行前还会再实时复核一次）。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CARD_LIMIT_BYTES = void 0;
+exports.breakerThreshold = breakerThreshold;
+exports.isProtected = isProtected;
+exports.botCanWrite = botCanWrite;
+exports.canEditCard = canEditCard;
+exports.markedCard = markedCard;
+exports.stripMark = stripMark;
+exports.planGroup = planGroup;
+const util_1 = require("./util");
+/** QQ 群名片上限按 60 字节处理（与 AA 端一致，API.md 第 9 节）。 */
+exports.CARD_LIMIT_BYTES = 60;
+function breakerThreshold(groupSize, count, percent) {
+    return Math.max(1, Math.min(count, Math.floor(groupSize * percent / 100)));
+}
+/** 只有身份确定是普通成员、不是机器人、不在保护名单里的人才可能被处置。 */
+function isProtected(member, protectedIds) {
+    return member.role !== 'member' || member.isRobot || protectedIds.has(member.qq);
+}
+function botCanWrite(botRole) {
+    return botRole === 'owner' || botRole === 'admin';
+}
+/** 机器人能不能改这个普通成员的名片（群主和管理员都能改普通成员）。 */
+function canEditCard(botRole, target) {
+    return botCanWrite(botRole) && target.role === 'member';
+}
+function markedCard(prefix, member) {
+    const base = member.card || member.nickname || member.qq;
+    return (0, util_1.truncateUtf8)(prefix + base, exports.CARD_LIMIT_BYTES);
+}
+function stripMark(prefix, card) {
+    return prefix && card.startsWith(prefix) ? card.slice(prefix.length) : card;
+}
+function planGroup(input) {
+    const { settings, mode, now } = input;
+    const prefix = settings.markPrefix;
+    const writesMode = mode === 'remind' || mode === 'enforce';
+    const plan = {
+        counts: { members: input.members.length, allow: 0, deny: 0, review: 0, unknown: 0 },
+        denies: [],
+        protectedDenies: [],
+        reviews: [],
+        unknowns: [],
+        newDenies: [],
+        threshold: breakerThreshold(input.groupSize, settings.breakerCount, settings.breakerPercent),
+        kicksDue: 0,
+        tripped: false,
+        tripReason: '',
+        unknownHeavy: false,
+        writes: false,
+        track: [],
+        untrack: [],
+        cards: [],
+        kicks: [],
+        kicksDeferred: 0,
+        cardsPending: 0,
+    };
+    const allowed = [];
+    const denied = [];
+    const settled = []; // 已有宽限记录、现在变成合格 / 需人工 / 受保护的人
+    const kickable = [];
+    const present = new Set();
+    for (const member of input.members) {
+        present.add(member.qq);
+        const verdict = input.verdicts.get(member.qq);
+        const decision = verdict?.decision ?? 'unknown';
+        const record = input.tracked.get(member.qq);
+        const prot = isProtected(member, input.protectedIds);
+        if (decision === 'allow') {
+            plan.counts.allow++;
+            allowed.push({ member, verdict: verdict });
+            if (record)
+                settled.push(member);
+        }
+        else if (decision === 'deny') {
+            plan.counts.deny++;
+            if (prot) {
+                plan.protectedDenies.push({ qq: member.qq, reason: verdict.reason });
+                if (record)
+                    settled.push(member);
+                continue;
+            }
+            plan.denies.push({ qq: member.qq, reason: verdict.reason, isNew: !record });
+            if (!record)
+                plan.newDenies.push({ qq: member.qq, reason: verdict.reason });
+            denied.push({ member, verdict: verdict });
+            // 可以移出：enforce、完整巡检、截止时间已到、并且最近成功提醒过（截止时间是在提醒时定下的）
+            const deadline = record?.graceUntil?.getTime();
+            const remindedAt = record?.lastRemindedAt?.getTime();
+            if (mode === 'enforce' && settings.allowKicks && deadline !== undefined && deadline <= now
+                && remindedAt !== undefined && now - remindedAt <= settings.remindFreshMs) {
+                kickable.push({ qq: member.qq, reason: verdict.reason, name: member.card || member.nickname || member.qq, deadline });
+            }
+        }
+        else if (decision === 'review') {
+            // 需要人工处理（例如冲突）：永不处置；已有的宽限记录取消
+            plan.counts.review++;
+            plan.reviews.push({ qq: member.qq, reason: verdict.reason });
+            if (record)
+                settled.push(member);
+        }
+        else {
+            // 无法判断：什么都不改，宽限记录原样保留
+            plan.counts.unknown++;
+            plan.unknowns.push(member.qq);
+        }
+    }
+    // 已经离开群的人，删除宽限记录（只有完整名单才能判断谁离开了）
+    if (!input.partial) {
+        for (const qq of input.tracked.keys()) {
+            if (!present.has(qq))
+                plan.untrack.push(qq);
+        }
+    }
+    // 熔断：新发现的不合格太多，或者一次要移出的人太多（没被管理员确认过的）
+    plan.kicksDue = kickable.length;
+    const unapprovedKicks = kickable.filter((k) => k.deadline > input.kickApprovedBefore).length;
+    const maxNew = Math.max(plan.threshold, input.bypass?.maxNew ?? 0);
+    const maxKicks = Math.max(plan.threshold, input.bypass?.maxKicks ?? 0);
+    if (writesMode && !input.held) {
+        if (plan.newDenies.length > maxNew) {
+            plan.tripped = true;
+            plan.tripReason = `新发现不合格 ${plan.newDenies.length} 人，超过阈值 ${maxNew} 人`;
+        }
+        else if (unapprovedKicks > maxKicks) {
+            plan.tripped = true;
+            plan.tripReason = `一次有 ${unapprovedKicks} 人到期要移出，超过阈值 ${maxKicks} 人`;
+        }
+    }
+    plan.unknownHeavy = plan.unknowns.length > plan.threshold;
+    plan.writes = writesMode && !input.held && !plan.tripped && !plan.unknownHeavy && botCanWrite(input.botRole);
+    if (!plan.writes) {
+        // 机器人以后能改的名片里，和 AA 不一致的有多少（写进报告）
+        for (const { member, verdict } of allowed) {
+            if (settings.syncCards && verdict.card && member.card !== verdict.card && !isProtected(member, input.protectedIds))
+                plan.cardsPending++;
+        }
+        // 降级到 report 时，撤掉以前加的标记、清空宽限记录（恢复原状）。
+        // 其他不能改动的情况（熔断、机器人不是管理员……）保留宽限记录，等能改动时再撤标记，避免标记残留。
+        if (mode === 'report' && !input.held && botCanWrite(input.botRole)) {
+            for (const member of input.members) {
+                const record = input.tracked.get(member.qq);
+                if (!record)
+                    continue;
+                if (record.marked && prefix && member.card.startsWith(prefix) && canEditCard(input.botRole, member)) {
+                    plan.cards.push({ qq: member.qq, from: member.card, to: stripMark(prefix, member.card), why: 'unmark' });
+                }
+                if (!plan.untrack.includes(member.qq))
+                    plan.untrack.push(member.qq);
+            }
+        }
+        return plan;
+    }
+    // ---- 以下只在允许改动时执行
+    const marks = [];
+    const syncs = [];
+    // 不再需要宽限的人：取消记录，撤掉标记（受保护的人只取消记录，不碰名片）
+    for (const member of settled) {
+        plan.untrack.push(member.qq);
+        const verdict = input.verdicts.get(member.qq);
+        const willSync = verdict?.decision === 'allow' && settings.syncCards && !!verdict.card;
+        if (!willSync && input.tracked.get(member.qq)?.marked && prefix && member.card.startsWith(prefix)
+            && !isProtected(member, input.protectedIds) && canEditCard(input.botRole, member)) {
+            marks.push({ qq: member.qq, from: member.card, to: stripMark(prefix, member.card), why: 'unmark' });
+        }
+    }
+    // 合格的人：同步名片（受保护的人不改，DECISIONS 第 26 条）
+    for (const { member, verdict } of allowed) {
+        if (isProtected(member, input.protectedIds) || !canEditCard(input.botRole, member))
+            continue;
+        if (settings.syncCards && verdict.card && member.card !== verdict.card) {
+            syncs.push({ qq: member.qq, from: member.card, to: verdict.card, why: 'sync' });
+        }
+    }
+    for (const { member, verdict } of denied) {
+        const existing = input.tracked.get(member.qq);
+        const row = existing
+            ? { ...existing }
+            : { groupId: input.groupId, qq: member.qq, reason: verdict.reason, firstDeniedAt: new Date(now), graceUntil: null, marked: false, lastRemindedAt: null };
+        row.reason = verdict.reason;
+        // 截止时间只在 enforce 模式下、第一次成功发出带截止时间的提醒时定下（guard.sendReminder）
+        if (mode !== 'enforce')
+            row.graceUntil = null;
+        if (settings.markCards && prefix) {
+            if (member.card.startsWith(prefix)) {
+                row.marked = true;
+            }
+            else if (canEditCard(input.botRole, member)) {
+                marks.push({ qq: member.qq, from: member.card, to: markedCard(prefix, member), why: 'mark' });
+                row.marked = true;
+            }
+        }
+        plan.track.push(row);
+    }
+    plan.cards = [...marks, ...syncs];
+    const budget = Math.max(0, settings.kickBudget);
+    plan.kicks = kickable.slice(0, budget).map(({ qq, reason, name }) => ({ qq, reason, name }));
+    plan.kicksDeferred = kickable.length - plan.kicks.length;
+    return plan;
+}