koishi-plugin-aaqqbot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yilifaer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# koishi-plugin-aaqqbot
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-aaqqbot)](https://www.npmjs.com/package/koishi-plugin-aaqqbot)
+
+用 QQ 机器人管理 EVE 联盟的 QQ 群：**只有 AllianceAuth（AA）认可的人才能留在对应的群里。**
+
+这是一个 [Koishi](https://koishi.chat) 插件，需要配合 AA 端插件 [aa-qqbot](https://github.com/yilifaer/aa-qqbot-plugin) 使用。
+
+- **审批入群申请**：申请人在「验证信息」里填 AA 上显示的验证码，机器人问 AA，合格就同意。
+- **定时巡检**：每隔几小时把每个群的完整名单交给 AA，找出不合格的人。
+- **提醒**：每天定时在群里 @ 不合格的人，并在他们的群名片前加标记（例如「【SPY】张三」）。
+- **移出**：收到带截止时间的提醒后，宽限期（默认 48 小时）过了还不合格，移出群（不拉黑，补好绑定可以重新申请）。
+- **同步群名片**：按 AA 算好的名片自动改，例如 `[IGC] Kaela Voss - 凯拉`。
+- **快速反应**：每分钟向 AA 拉取一次变化（解绑、退组、账号停用……），相关的人立即复查。
+
+## 目录
+
+1. [它是怎么工作的](#1-它是怎么工作的)
+2. [安全保证](#2-安全保证)
+3. [安装](#3-安装)
+4. [配置](#4-配置)
+5. [群模式与上线步骤](#5-群模式与上线步骤)
+6. [管理命令](#6-管理命令)
+7. [常见问题](#7-常见问题)
+8. [开发](#8-开发)
+
+## 1. 它是怎么工作的
+
+```
+   AllianceAuth（aa-qqbot）                         Koishi（本插件）+ LLBot
+   ──────────────────────                          ─────────────────────────
+   成员在「服务」页绑定 QQ                           入群申请 ──► 问 AA ──► 同意 / 拒绝 / 留给管理员
+   QQ 管理员在前台配置受管群        ◄── 签名请求 ──  巡检（每 6 小时）──► 完整名单 ──► 判定
+   回答：合格 / 不合格 / 需人工           HTTPS      变化（每 60 秒）──► 相关的人 ──► 复查
+   算好每个人的群名片                               提醒、加标记、移出、改名片
+```
+
+- **只有机器人主动连 AA**，AA 不需要能连到机器人（机器人可以在家里的电脑上）。
+- **管哪些群由 AA 决定**：QQ 管理员在 AA 前台添加的群才归机器人管，其他群机器人一概不碰。
+- **踢不踢人由机器人这边决定**：真正移出成员的开关只在 Koishi 里，AA 前台再怎么改也打不开。
+
+## 2. 安全保证
+
+这些规则都有自动化测试覆盖：
+
+- **拿不到明确答案就什么都不做**：AA 连不上、超时、返回网页、返回 3xx/4xx/5xx、内容格式不对，一律当作「无法判断」，不拒绝、不提醒、不移出。AA 连不上时只在运维群报警一次，恢复后再通知一次。
+- **「需要人工处理」永不处置**：例如同一个 QQ 被两个 AA 账号认领（冲突），只报告，由 QQ 管理员在 AA 上处理。
+- **永不处置的人**：群主、管理员、QQ 官方机器人、机器人自己、白名单。移出前还会**实时**再查一次对方的身份。
+- **先提醒、后移出**：截止时间从第一次成功 @ 提醒时开始算，移出前 36 小时内一定成功提醒过这个人；提醒没发出去就不会被移出。移出前还会再问一次 AA。
+- **熔断**：一轮里某个群新发现的不合格人数、或者一次到期要移出的人数太多（默认超过 5 人或群人数的 10%，取较小者，至少 1 人），很可能是 AA 被改错了——这个群立即停止一切处置，只在运维群报警，等管理员核实后发送 `aaqq.confirm` 才继续。确认只在 1 小时内、只对报告里的人数有效。
+- **限速**：每个群每小时最多移出 10 人。
+- **升级要确认**：把群改成 remind 或 enforce 后，必须等一轮巡检报告出来、由管理员确认，才真正生效。
+- **紧急刹车**：`aaqq.pause` 立即中止正在进行的巡检，暂停一切操作；停用插件或修改配置同样会立即中止。
+- **不拉黑**：移出时不勾选「拒绝再次申请」，误判了也能补救。
+- **防注入**：群名、名片、错误信息都按纯文本发送，里面的 `<at type="all"/>` 之类不会变成真的 @全体成员。
+
+## 3. 安装
+
+### 3.1 准备
+
+| 需要 | 说明 |
+|---|---|
+| Koishi 4.18 及以上 | 推荐 Koishi Desktop |
+| OneBot 机器人 | `adapter-onebot` 适配器 + [LLBot](https://github.com/LLOneBot/LuckyLilliaBot) 等 OneBot v11 实现 |
+| 数据库插件 | 例如 `database-sqlite`（Koishi Desktop 默认已启用） |
+| 机器人是每个受管群的**管理员** | 审批申请、改名片、移出都需要管理员权限 |
+| AA 上装好 aa-qqbot | 并由 IT 在 `local.py` 配置好 `APPS_WITH_PUBLIC_VIEWS` 和 `QQBOT_API_KEYS`，见 aa-qqbot 的 README |
+
+### 3.2 安装插件
+
+在 Koishi 控制台打开「插件市场」，搜索 **aaqqbot**，点「添加」，然后在「插件配置」里找到 `aaqqbot` 进行配置。
+
+### 3.3 生成密钥（在你自己的电脑上）
+
+密钥是机器人和 AA 之间的暗号，**只能由你自己生成，不要发给任何人（包括 AI 助手），不要贴进聊天记录。**
+
+在自己的电脑上打开终端，运行：
+
+```bash
+python3 -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+把输出的那一长串：
+
+1. 交给 IT，写进 AA 的 `local.py`：`QQBOT_API_KEYS = {"koishi-1": "那一长串"}`，然后重启 AA；
+2. 自己填进 Koishi 插件配置的「密钥」一栏，「密钥编号」填 `koishi-1`。
+
+## 4. 配置
+
+| 分组 | 配置项 | 默认值 | 说明 |
+|---|---|---|---|
+| 连接 AA | AA 的网址 | — | 例如 `https://auth.example.com`。正式环境必须用 https |
+| | 密钥编号 / 密钥 | — | 见 3.3 |
+| | 超时 | 30 秒 | |
+| | 绑定网址 | 空 | 写进拒绝理由和提醒里；留空时用「AA 网址 + /services/」 |
+| 机器人与运维 | 机器人账号 | 空 | 只有一个 QQ 机器人时留空 |
+| | 运维群号 | 空 | 汇总和报警发到这里。**只放管理人员，不能是受管群** |
+| | 运维名单 | 空 | 能用管理命令的 QQ |
+| | 白名单 | 空 | 永远不会被处置的 QQ |
+| 群模式 | 默认模式 | report | AA 上新加的群用哪种模式 |
+| | 单独设置 | 空 | 表格：群号 + 模式 |
+| 入群申请 | 自动拒绝 | 开 | 只在 remind / enforce 模式的群里生效 |
+| | 拒绝理由 | `{hint}。绑定地址：{url}` | `{hint}` 是自动生成的原因 |
+| | 邀请入群 | 和普通申请一样 | 也可以选「一律留给管理员」 |
+| | 补处理积压的申请 | 开 | 机器人重新上线时处理掉线期间的申请 |
+| 巡检与群名片 | 巡检间隔 | 6 小时 | 插件启动后先巡检一次 |
+| | 拉取变化间隔 | 60 秒 | |
+| | 同步群名片 | 开 | 只在 remind / enforce 模式 |
+| 宽限、提醒与标记 | 宽限期 | 48 小时 | enforce 模式下，从第一次带截止时间的提醒开始，多久后移出 |
+| | 提醒时间 | 19:30 | 每天几点 @ 提醒（机器人电脑的本地时间） |
+| | 提醒文字 | | remind 和 enforce 各一份，`{list}` 是被 @ 的人 |
+| | 名片加标记 / 标记文字 | 开 / 【SPY】 | |
+| | 移出公告 / 公告文字 | 开 | 移出后在该群发一条公告 |
+| 防误踢 | 熔断人数 / 比例 | 5 人 / 10% | 取较小者，至少为 1 |
+| | 每小时最多移出 | 10 人 | 每个群 |
+
+## 5. 群模式与上线步骤
+
+| 模式 | 审批申请 | 提醒、加标记、同步名片 | 移出 |
+|---|---|---|---|
+| **off** | 不管 | 不管 | 不管 |
+| **report**（默认） | 合格的同意，不合格的留给管理员 | ✗（只写进运维群报告） | ✗ |
+| **remind** | 合格的同意，不合格的拒绝 | ✓ | ✗ |
+| **enforce** | 合格的同意，不合格的拒绝 | ✓ | 宽限期过后 ✓ |
+
+建议的上线步骤：
+
+1. 所有群先用 **report** 跑至少一周，看运维群里的报告，督促大家在 AA 上绑定 QQ。
+2. 在每个受管群的 QQ 设置里，把加群方式改成 **「需要发送验证信息」**，否则机器人收不到入群申请。
+3. 先挑一个小群改成 **remind**：在插件配置的「单独设置」里填群号和模式 → 保存 → 等巡检报告（或在运维群发 `aaqq.patrol 群号`）→ 看报告没问题后发送 `aaqq.confirm 群号`。
+4. 提醒跑几天没有问题，再按同样的方法改成 **enforce**。
+
+## 6. 管理命令
+
+只能在**运维群**里或**私聊机器人**时使用，并且要**同时**满足：QQ 在「运维名单」里、Koishi 权限等级 ≥ 3。在其他群里发这些命令，机器人不会回应。
+
+| 命令 | 作用 |
+|---|---|
+| `aaqq.status` | 查看状态：机器人、AA 连接、各群模式、熔断、宽限中人数 |
+| `aaqq.health` | 检查与 AA 的连接和 AA 的配置 |
+| `aaqq.patrol [群号]` | 立即巡检（不填群号就巡检全部） |
+| `aaqq.confirm <群号>` | 确认模式升级；解除熔断 |
+| `aaqq.check <QQ号>` | 查询某个 QQ 在各群的判定 |
+| `aaqq.pause` | 紧急暂停一切操作 |
+| `aaqq.resume` | 恢复 |
+
+给运维加权限等级（两种方法任选一种）：
+
+- 在 Koishi 控制台的「数据库」页面打开 `user` 表，把对应用户的 `authority` 改成 3。（表里还没有这个人时，先让他私聊机器人发一次 `aaqq.status`，会提示「权限不足」，这时表里就有他了。）
+- 启用 `admin` 插件后，由权限等级 ≥ 4 的人发送 `authorize 3 -u @某人`。
+
+## 7. 常见问题
+
+| 运维群里看到 | 原因和解决办法 |
+|---|---|
+| 「AA 把请求转到了登录页」 | AA 的 `local.py` 缺少 `APPS_WITH_PUBLIC_VIEWS += ["qqbot"]`，请 IT 追加（不要整行覆盖）后重启 AA |
+| 「签名不对」（bad_signature） | Koishi 里的密钥和 AA 上的不一致，注意不要多复制空格 |
+| 「时间相差太大」（stale_timestamp） | 打开机器人电脑的「自动设置日期与时间」 |
+| 「密钥编号在 AA 上不存在」 | Koishi 里的密钥编号要和 `QQBOT_API_KEYS` 的键完全一样 |
+| 「AA 没有配置机器人密钥」 | 请 IT 配置 `QQBOT_API_KEYS` |
+| 「运维群同时是受管群」 | 换一个只有管理人员的群做运维群 |
+| 「这个 Koishi 里有多个 OneBot 机器人」 | 在配置里填「机器人账号」 |
+| 「⛔ 熔断」 | 先核对 AA 上的设置（例如群的类型、要求的组、成员权限有没有被改错），确认名单没问题后发送 `aaqq.confirm 群号` |
+
+## 8. 开发
+
+```bash
+npm install
+npm test          # 自动化测试（真实的 Koishi + 模拟的 AA 和 LLBot）
+npm run typecheck
+npm run build     # 编译到 lib/
+```
+
+接口契约见 aa-qqbot 仓库的 `API.md`；设计决定见本仓库的 [`DECISIONS.md`](DECISIONS.md)。
+
+发布：在 GitHub 的 Actions 页面运行 **Publish to npm**（需要仓库里配置了 `NPM_TOKEN`）。
+
+## 许可证
+
+MIT

package/lib/aa.d.ts

@@ -0,0 +1,91 @@
+import type { Context } from 'koishi';
+export type Decision = 'allow' | 'deny' | 'review' | 'unknown';
+export interface Verdict {
+    qq: string;
+    decision: Decision;
+    reason: string;
+    card: string | null;
+}
+export interface ManagedGroup {
+    groupId: string;
+    name: string;
+    kind: string;
+}
+export interface AaEvent {
+    id: number;
+    kind: string;
+    qq: string;
+}
+export interface ApiFailure {
+    ok: false;
+    /** network：连不上；timeout：超时；http：非 200；invalid：200 但内容不对；aborted：插件停用或暂停。 */
+    kind: 'network' | 'timeout' | 'http' | 'invalid' | 'aborted';
+    status?: number;
+    error?: string;
+    message?: string;
+    retryable: boolean;
+    /** 给运维看的中文说明。 */
+    hint: string;
+}
+export type ApiResult<T> = ({
+    ok: true;
+    serverTime?: string;
+} & T) | ApiFailure;
+export interface CallOptions {
+    signal?: AbortSignal;
+    /** 网络错误、超时、5xx 时的重试等待（毫秒），长度就是重试次数。 */
+    retryDelays?: number[];
+}
+export interface AaClientOptions {
+    baseUrl: string;
+    keyId: string;
+    secret: string;
+    timeoutMs: number;
+    now?: () => number;
+}
+export declare class AaClient {
+    private ctx;
+    private options;
+    /** 最近一次成功响应里 AA 的时间与本机时间之差（毫秒，AA 减本机）。 */
+    clockSkewMs: number | null;
+    constructor(ctx: Context, options: AaClientOptions);
+    private now;
+    endpoint(name: string): URL;
+    /** 调用一个接口，返回解析后的 JSON 对象或失败说明。 */
+    call(name: string, payload: object, options?: CallOptions): Promise<ApiResult<{
+        data: any;
+    }>>;
+    private once;
+    private request;
+    private noteServerTime;
+    health(options?: CallOptions): Promise<ApiResult<{
+        version: string;
+        configOk: boolean;
+        problems: string[];
+    }>>;
+    groups(options?: CallOptions): Promise<ApiResult<{
+        groups: ManagedGroup[];
+    }>>;
+    /**
+     * 对一个群的一组 QQ 求判定。结果按请求顺序一一对应（API.md 5.3）；
+     * 顺序对不上、QQ 回显不一致、判定值不认识的项，都当作 unknown。
+     */
+    check(groupId: string, qqs: string[], fullRoster: boolean, options?: CallOptions): Promise<ApiResult<{
+        verdicts: Map<string, Verdict>;
+        roster: unknown;
+    }>>;
+    /** 入群申请：申请人 QQ + 验证信息原文。只看 result.decision（API.md 5.4）。 */
+    claim(qq: string, text: string, groupId: string, options?: CallOptions): Promise<ApiResult<{
+        verdict: Verdict;
+        outcome: string;
+        message: string;
+        claimed: boolean;
+    }>>;
+    events(after: number, limit: number, options?: CallOptions): Promise<ApiResult<{
+        events: AaEvent[];
+        lastId: number;
+        hasMore: boolean;
+    }>>;
+}
+/** 一行给运维看的失败说明。 */
+export declare function describeFailure(result: ApiFailure): string;

package/lib/aa.js

@@ -0,0 +1,255 @@
+"use strict";
+// 调用 AA（aa-qqbot）的机器人接口。接口契约见 aa-qqbot 仓库 API.md。
+//
+// 核心原则（API.md 1.1）：只有「HTTP 200 + JSON + ok === true + 字段结构正确」才算拿到了答案；
+// 其余一切（网络错误、超时、重定向、网页、4xx/5xx、结构不对）都是「无法判断」，调用方绝不能据此处置任何人。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AaClient = void 0;
+exports.describeFailure = describeFailure;
+const signing_1 = require("./signing");
+const texts_1 = require("./texts");
+const util_1 = require("./util");
+const DEFAULT_RETRY_DELAYS = [3_000, 15_000];
+const MAX_RETRY_AFTER_MS = 120_000;
+class AaClient {
+    ctx;
+    options;
+    /** 最近一次成功响应里 AA 的时间与本机时间之差（毫秒，AA 减本机）。 */
+    clockSkewMs = null;
+    constructor(ctx, options) {
+        this.ctx = ctx;
+        this.options = options;
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    endpoint(name) {
+        const base = this.options.baseUrl.trim().replace(/\/+$/, '');
+        return new URL(`${base}/qqbot/api/v1/${name}/`);
+    }
+    /** 调用一个接口，返回解析后的 JSON 对象或失败说明。 */
+    async call(name, payload, options = {}) {
+        let url;
+        try {
+            url = this.endpoint(name);
+        }
+        catch {
+            return failure('invalid', { hint: 'AA 网址格式不对，请检查插件配置', retryable: false });
+        }
+        if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+            return failure('invalid', { hint: 'AA 网址必须以 https:// 开头', retryable: false });
+        }
+        const bodyText = JSON.stringify(payload); // 只序列化一次，签名和发送用同一个字符串
+        const delays = options.retryDelays ?? DEFAULT_RETRY_DELAYS;
+        let attempt = 0;
+        while (true) {
+            const result = await this.once(url, bodyText, options.signal);
+            if (result.ok || !result.retryable || attempt >= delays.length)
+                return result;
+            let wait = delays[attempt++];
+            if (result.status === 429 && result.retryAfterMs)
+                wait = result.retryAfterMs;
+            try {
+                await (0, util_1.sleep)(wait, options.signal);
+            }
+            catch {
+                return failure('aborted', { hint: '已中止', retryable: false });
+            }
+        }
+    }
+    async once(url, bodyText, signal) {
+        if (signal?.aborted)
+            return failure('aborted', { hint: '已中止', retryable: false });
+        // HTTP 插件会在传入的 signal 上挂监听器且不移除；每次请求用一个临时的 signal，用完解绑，避免长期累积
+        const local = new AbortController();
+        const forward = () => local.abort();
+        signal?.addEventListener('abort', forward, { once: true });
+        try {
+            return await this.request(url, bodyText, local.signal, signal);
+        }
+        finally {
+            signal?.removeEventListener('abort', forward);
+        }
+    }
+    async request(url, bodyText, requestSignal, signal) {
+        // 每次请求（包括重试）都重新生成时间戳、随机数和签名
+        const headers = (0, signing_1.signedHeaders)(this.options.keyId, this.options.secret, url.pathname, bodyText, this.now());
+        let response;
+        try {
+            response = await this.ctx.http(url.href, {
+                method: 'POST',
+                data: bodyText,
+                headers: { ...headers },
+                redirect: 'manual', // 绝不跟随重定向（API.md 1.1 第 3 条）
+                validateStatus: () => true, // 状态码由下面自己判断
+                responseType: 'text', // 自己解析 JSON，不让 HTTP 库按 Content-Type 猜
+                timeout: this.options.timeoutMs,
+                signal: requestSignal,
+            });
+        }
+        catch (error) {
+            if (signal?.aborted || error instanceof util_1.AbortedError)
+                return failure('aborted', { hint: '已中止', retryable: false });
+            if (error?.code === 'ETIMEDOUT') {
+                if (/disposed/.test(String(error?.message)))
+                    return failure('aborted', { hint: '插件已停用', retryable: false });
+                return failure('timeout', { hint: `等待 AA 超过 ${Math.round(this.options.timeoutMs / 1000)} 秒没有回应`, retryable: true });
+            }
+            const cause = error?.cause?.cause?.code ?? error?.cause?.code ?? error?.cause?.message ?? error?.message;
+            return failure('network', { hint: `无法连接 AA（${String(cause ?? '网络错误')}）`, retryable: true });
+        }
+        const status = response.status;
+        let data = null;
+        if (typeof response.data === 'string') {
+            try {
+                data = JSON.parse(response.data);
+            }
+            catch {
+                data = null;
+            }
+        }
+        if (status === 200) {
+            if (data && typeof data === 'object' && !Array.isArray(data) && data.ok === true) {
+                this.noteServerTime(data.server_time);
+                return { ok: true, data, serverTime: typeof data.server_time === 'string' ? data.server_time : undefined };
+            }
+            return failure('invalid', { status, hint: 'AA 返回了 200，但内容不是预期的 JSON（可能是网页或代理页面）', retryable: false });
+        }
+        const error = data && typeof data.error === 'string' ? data.error : undefined;
+        const message = data && typeof data.message === 'string' ? data.message : undefined;
+        const location = response.headers?.get?.('location');
+        const result = failure('http', {
+            status,
+            error,
+            message,
+            hint: (0, texts_1.errorHint)(error, status, location),
+            // 只有 5xx 值得重试；AA 没配密钥（503 misconfigured）重试也没用
+            retryable: status >= 500 && error !== 'misconfigured',
+        });
+        if (status === 429) {
+            const seconds = Number(response.headers?.get?.('retry-after'));
+            result.retryAfterMs = Math.min(Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 30_000, MAX_RETRY_AFTER_MS);
+            result.retryable = true;
+        }
+        return result;
+    }
+    noteServerTime(value) {
+        if (typeof value !== 'string')
+            return;
+        const time = Date.parse(value);
+        if (Number.isFinite(time))
+            this.clockSkewMs = time - this.now();
+    }
+    // ---------------------------------------------------------------- 各接口
+    async health(options) {
+        const result = await this.call('health', {}, options);
+        if (!result.ok)
+            return result;
+        const { data } = result;
+        return {
+            ok: true,
+            serverTime: result.serverTime,
+            version: typeof data.version === 'string' ? data.version : '?',
+            configOk: data.config_ok === true,
+            problems: Array.isArray(data.problems) ? data.problems.filter((p) => typeof p === 'string') : [],
+        };
+    }
+    async groups(options) {
+        const result = await this.call('groups', {}, options);
+        if (!result.ok)
+            return result;
+        if (!Array.isArray(result.data.groups))
+            return invalid('groups 响应里没有 groups 列表');
+        const groups = [];
+        for (const item of result.data.groups) {
+            const groupId = (0, util_1.normalizeId)(item?.group_id);
+            if (!groupId)
+                continue;
+            groups.push({
+                groupId,
+                name: typeof item.name === 'string' ? item.name : groupId,
+                kind: typeof item.kind === 'string' ? item.kind : 'fixed',
+            });
+        }
+        return { ok: true, serverTime: result.serverTime, groups };
+    }
+    /**
+     * 对一个群的一组 QQ 求判定。结果按请求顺序一一对应（API.md 5.3）；
+     * 顺序对不上、QQ 回显不一致、判定值不认识的项，都当作 unknown。
+     */
+    async check(groupId, qqs, fullRoster, options) {
+        const result = await this.call('check', { group_id: groupId, qqs, full_roster: fullRoster }, options);
+        if (!result.ok)
+            return result;
+        const results = result.data.results;
+        if (!Array.isArray(results) || results.length !== qqs.length) {
+            return invalid('check 响应的 results 数量和请求的不一致');
+        }
+        const verdicts = new Map();
+        qqs.forEach((qq, index) => {
+            verdicts.set(qq, parseVerdict(results[index], qq));
+        });
+        return { ok: true, serverTime: result.serverTime, verdicts, roster: result.data.roster };
+    }
+    /** 入群申请：申请人 QQ + 验证信息原文。只看 result.decision（API.md 5.4）。 */
+    async claim(qq, text, groupId, options) {
+        const result = await this.call('claim', { qq, text: text.slice(0, 2000), group_id: groupId }, options);
+        if (!result.ok)
+            return result;
+        const { data } = result;
+        if (!data.result || typeof data.result !== 'object')
+            return invalid('claim 响应里没有 result');
+        return {
+            ok: true,
+            serverTime: result.serverTime,
+            verdict: parseVerdict(data.result, qq),
+            outcome: typeof data.outcome === 'string' ? data.outcome : '',
+            message: typeof data.message === 'string' ? data.message : '',
+            claimed: data.claimed === true,
+        };
+    }
+    async events(after, limit, options) {
+        const result = await this.call('events', { after, limit }, options);
+        if (!result.ok)
+            return result;
+        const { data } = result;
+        if (!Array.isArray(data.events) || !Number.isSafeInteger(data.last_id) || data.last_id < after) {
+            return invalid('events 响应格式不对');
+        }
+        const events = [];
+        for (const item of data.events) {
+            if (!item || !Number.isSafeInteger(item.id) || typeof item.kind !== 'string')
+                continue;
+            events.push({ id: item.id, kind: item.kind, qq: (0, util_1.normalizeId)(item.qq) ?? '' });
+        }
+        return { ok: true, serverTime: result.serverTime, events, lastId: data.last_id, hasMore: data.has_more === true };
+    }
+}
+exports.AaClient = AaClient;
+function parseVerdict(item, requestedQq) {
+    const unknown = { qq: requestedQq, decision: 'unknown', reason: 'UNKNOWN', card: null };
+    if (!item || typeof item !== 'object')
+        return unknown;
+    // AA 回显的 QQ 必须和请求的一致，否则不信任这一项
+    if ((0, util_1.normalizeId)(item.qq) !== requestedQq)
+        return unknown;
+    const reason = typeof item.reason === 'string' ? item.reason : 'UNKNOWN';
+    const decision = item.decision === 'allow' || item.decision === 'deny' || item.decision === 'review'
+        ? item.decision
+        : 'unknown'; // 不认识的 decision 一律当作「不处置」
+    const card = decision === 'allow' && typeof item.card === 'string' && item.card.trim() ? item.card : null;
+    return { qq: requestedQq, decision, reason, card };
+}
+function failure(kind, rest) {
+    return { ok: false, kind, ...rest };
+}
+function invalid(hint) {
+    return failure('invalid', { status: 200, hint: `AA 的响应格式不对：${hint}`, retryable: false });
+}
+/** 一行给运维看的失败说明。 */
+function describeFailure(result) {
+    const parts = [result.hint];
+    if (result.message && result.message !== result.hint)
+        parts.push(`AA 说明：${result.message}`);
+    return parts.join('；');
+}

package/lib/commands.d.ts

@@ -0,0 +1,3 @@
+import { Context } from 'koishi';
+import type { Guard } from './guard';
+export declare function registerCommands(ctx: Context, guard: Guard): void;

package/lib/commands.js

@@ -0,0 +1,73 @@
+"use strict";
+// 管理命令。必须同时满足三个条件才能用（DECISIONS 第 10 条、交接文档 R13）：
+//   ① 在运维群里或私聊机器人；② QQ 在运维名单里；③ Koishi 权限等级 ≥ 3。
+// 在其他任何群（包括受管群）里发命令，一律不回应。
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCommands = registerCommands;
+const koishi_1 = require("koishi");
+const util_1 = require("./util");
+function registerCommands(ctx, guard) {
+    const gate = ({ session }) => {
+        if (!session || session.platform !== 'onebot')
+            return '';
+        const admin = guard.adminGroup();
+        const inPrivate = session.isDirect;
+        const inAdminGroup = !session.isDirect && !!admin && (0, util_1.normalizeId)(session.guildId) === admin;
+        if (!inPrivate && !inAdminGroup)
+            return ''; // 不回应
+        const qq = (0, util_1.normalizeId)(session.userId);
+        if (!qq || !guard.operators().has(qq))
+            return koishi_1.h.text('你不在运维名单里，不能使用这个命令。');
+        // 返回 undefined 表示继续，接下来由 Koishi 检查权限等级（authority: 3）
+    };
+    const define = (decl, description) => ctx.command(decl, description, { authority: 3 }).before(gate);
+    define('aaqq', 'AA QQ 群管理').action(() => koishi_1.h.text([
+        'AA QQ 群管理命令：',
+        'aaqq.status　查看状态',
+        'aaqq.health　检查与 AA 的连接',
+        'aaqq.patrol [群号]　立即巡检（不填群号就巡检全部）',
+        'aaqq.confirm <群号>　确认模式升级 / 解除熔断',
+        'aaqq.check <QQ号>　查询某个 QQ 的判定',
+        'aaqq.pause　紧急暂停（停止一切审批、提醒、改名片、移出）',
+        'aaqq.resume　恢复',
+    ].join('\n')));
+    define('aaqq.status', '查看状态').action(async () => koishi_1.h.text(await guard.statusText()));
+    define('aaqq.health', '检查与 AA 的连接').action(async () => koishi_1.h.text(await guard.checkHealth(false)));
+    define('aaqq.patrol [group:string]', '立即巡检').action(async (_, group) => {
+        if (guard.paused)
+            return koishi_1.h.text('插件暂停中，先发送 aaqq.resume 恢复。');
+        let only;
+        if (group) {
+            const groupId = (0, util_1.normalizeId)(group);
+            if (!groupId || !guard.group(groupId))
+                return koishi_1.h.text(`${group} 不是 AA 上的受管群。`);
+            only = [groupId];
+        }
+        if (guard.patrolRunning) {
+            guard.requestPatrol(only);
+            return koishi_1.h.text('正在巡检中，这一轮结束后会马上再巡检一次。');
+        }
+        guard.requestPatrol(only);
+        return koishi_1.h.text('已开始巡检，结果会发到运维群。');
+    });
+    define('aaqq.confirm <group:string>', '确认模式升级 / 解除熔断').action(async ({ session }, group) => {
+        const groupId = (0, util_1.normalizeId)(group);
+        if (!groupId)
+            return koishi_1.h.text('用法：aaqq.confirm 群号');
+        return koishi_1.h.text(await guard.confirm(groupId, session?.userId ?? ''));
+    });
+    define('aaqq.check <qq:string>', '查询某个 QQ 的判定').action(async (_, qq) => {
+        const id = (0, util_1.normalizeId)(qq);
+        if (!id)
+            return koishi_1.h.text('用法：aaqq.check QQ号（5–11 位数字）');
+        return koishi_1.h.text(await guard.checkQq(id));
+    });
+    define('aaqq.pause', '紧急暂停').action(async ({ session }) => {
+        await guard.setPaused(true, session?.userId ?? '');
+        return koishi_1.h.text('⏸ 已暂停：正在进行的巡检已中止；在恢复之前不会审批、提醒、改名片或移出任何人（入群申请留给管理员）。发送 aaqq.resume 恢复。');
+    });
+    define('aaqq.resume', '恢复').action(async ({ session }) => {
+        await guard.setPaused(false, session?.userId ?? '');
+        return koishi_1.h.text('▶ 已恢复，马上巡检一次。');
+    });
+}

package/lib/config.d.ts

@@ -0,0 +1,39 @@
+import { Schema } from 'koishi';
+export type Mode = 'off' | 'report' | 'remind' | 'enforce';
+export declare const MODE_RANK: Record<Mode, number>;
+export interface GroupModeEntry {
+    groupId: string;
+    mode: Mode;
+}
+export interface Config {
+    aaBaseUrl: string;
+    keyId: string;
+    secret: string;
+    timeoutSeconds: number;
+    bindUrl: string;
+    botId: string;
+    adminGroupId: string;
+    operators: string[];
+    whitelist: string[];
+    defaultMode: Mode;
+    groupModes: GroupModeEntry[];
+    autoReject: boolean;
+    rejectTemplate: string;
+    inviteHandling: 'same' | 'manual';
+    catchUpRequests: boolean;
+    patrolIntervalHours: number;
+    eventPollSeconds: number;
+    syncCards: boolean;
+    graceHours: number;
+    remindTime: string;
+    remindTemplate: string;
+    warnTemplate: string;
+    markCards: boolean;
+    markPrefix: string;
+    kickAnnounce: boolean;
+    kickAnnounceTemplate: string;
+    breakerCount: number;
+    breakerPercent: number;
+    kickPerHour: number;
+}
+export declare const Config: Schema<Config>;