koishi-plugin-ban-qrcode 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 koishi-plugin-ban-qrcode contributors
+
+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/lib/detect.d.ts

@@ -0,0 +1,31 @@
+export interface ImageNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    children?: ImageNode[];
+}
+export type RoleLike = string | {
+    id?: string;
+    name?: string;
+};
+export interface ModerateInput {
+    guildId?: string;
+    isDirect?: boolean;
+    userId?: string;
+    selfId?: string;
+    ignoreUsers: string[];
+    guilds: string[];
+    roles?: RoleLike[];
+    skipAdmins: boolean;
+}
+export interface QrHit {
+    src: string;
+    text: string;
+}
+export declare function roleLabels(roles?: RoleLike[]): string[];
+export declare function isAdminRole(roles?: RoleLike[]): boolean;
+export declare function collectImageSrcs(nodes: readonly ImageNode[]): string[];
+export declare function shouldModerate(input: ModerateInput): boolean;
+export declare function muteDurationMs(seconds: number): number;
+export declare function parseDataUrl(src: string): Buffer | null;
+export declare function defaultNotify(muteSeconds: number): string;
+export declare function findQrInImages(srcs: readonly string[], download: (src: string) => Promise<Buffer>, decode: (buffer: Buffer) => Promise<string | null>): Promise<QrHit | null>;

package/lib/detect.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roleLabels = roleLabels;
+exports.isAdminRole = isAdminRole;
+exports.collectImageSrcs = collectImageSrcs;
+exports.shouldModerate = shouldModerate;
+exports.muteDurationMs = muteDurationMs;
+exports.parseDataUrl = parseDataUrl;
+exports.defaultNotify = defaultNotify;
+exports.findQrInImages = findQrInImages;
+const ADMIN_ROLES = new Set([
+    'owner',
+    'admin',
+    'administrator',
+    'ADMINISTRATOR',
+]);
+function roleLabels(roles) {
+    if (!roles?.length)
+        return [];
+    const labels = [];
+    for (const role of roles) {
+        if (typeof role === 'string') {
+            if (role)
+                labels.push(role);
+            continue;
+        }
+        if (role.name)
+            labels.push(role.name);
+        if (role.id && role.id !== role.name)
+            labels.push(role.id);
+    }
+    return labels;
+}
+function isAdminRole(roles) {
+    return roleLabels(roles).some(role => ADMIN_ROLES.has(role) || role.toLowerCase() === 'owner');
+}
+function collectImageSrcs(nodes) {
+    const srcs = [];
+    const seen = new Set();
+    const visit = (items) => {
+        for (const node of items) {
+            if (node.type === 'img' || node.type === 'image') {
+                const src = pickSrc(node.attrs);
+                if (src && !seen.has(src)) {
+                    seen.add(src);
+                    srcs.push(src);
+                }
+            }
+            if (node.children?.length)
+                visit(node.children);
+        }
+    };
+    visit(nodes);
+    return srcs;
+}
+function pickSrc(attrs) {
+    const src = attrs?.src ?? attrs?.url;
+    return typeof src === 'string' && src.trim() ? src.trim() : undefined;
+}
+function shouldModerate(input) {
+    if (input.isDirect)
+        return false;
+    if (!input.guildId || !input.userId)
+        return false;
+    if (input.guilds.length && !input.guilds.includes(input.guildId))
+        return false;
+    if (input.userId === input.selfId)
+        return false;
+    if (input.ignoreUsers.includes(input.userId))
+        return false;
+    if (input.skipAdmins && isAdminRole(input.roles))
+        return false;
+    return true;
+}
+function muteDurationMs(seconds) {
+    return Math.max(0, Math.floor(seconds)) * 1000;
+}
+function parseDataUrl(src) {
+    const match = /^data:[^;,]+;base64,([\s\S]+)$/i.exec(src);
+    if (!match)
+        return null;
+    try {
+        return Buffer.from(match[1], 'base64');
+    }
+    catch {
+        return null;
+    }
+}
+function defaultNotify(muteSeconds) {
+    if (muteSeconds <= 0)
+        return '检测到二维码，已撤回。';
+    return `检测到二维码，已撤回并禁言 ${muteSeconds} 秒。`;
+}
+async function findQrInImages(srcs, download, decode) {
+    for (const src of srcs) {
+        try {
+            const text = await decode(await download(src));
+            if (text !== null)
+                return { src, text };
+        }
+        catch {
+            // skip a single failed image
+        }
+    }
+    return null;
+}

package/lib/index.d.ts

@@ -0,0 +1,15 @@
+import { Context, Schema } from 'koishi';
+export declare const name = "ban-qrcode";
+export declare const inject: string[];
+export declare const usage = "\n\u7FA4\u5185\u68C0\u6D4B\u5230\u56FE\u7247\u4E8C\u7EF4\u7801\u65F6\u81EA\u52A8\u64A4\u56DE\uFF0C\u5E76\u7981\u8A00\u53D1\u9001\u8005\uFF08\u9ED8\u8BA4 60 \u79D2\uFF09\u3002\u7528\u4E8E\u62E6\u622A\u5E7F\u544A\u7801\u3002\n\n\u673A\u5668\u4EBA\u9700\u8981\u64A4\u56DE\u6D88\u606F\u548C\u7981\u8A00\u6210\u5458\u7684\u6743\u9650\u3002\u7FA4\u4E3B / \u7BA1\u7406\u5458\u9ED8\u8BA4\u8DF3\u8FC7\u3002\n";
+export interface Config {
+    muteSeconds: number;
+    recall: boolean;
+    notify: boolean;
+    notifyText: string;
+    skipAdmins: boolean;
+    ignoreUsers: string[];
+    guilds: string[];
+}
+export declare const Config: Schema<Config>;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,71 @@
+"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 detect_1 = require("./detect");
+const qrcode_1 = require("./qrcode");
+exports.name = 'ban-qrcode';
+exports.inject = ['http'];
+exports.usage = `
+群内检测到图片二维码时自动撤回，并禁言发送者（默认 60 秒）。用于拦截广告码。
+
+机器人需要撤回消息和禁言成员的权限。群主 / 管理员默认跳过。
+`;
+exports.Config = koishi_1.Schema.object({
+    muteSeconds: koishi_1.Schema.number().min(0).default(60).description('禁言秒数。0 表示只撤回不禁言。'),
+    recall: koishi_1.Schema.boolean().default(true).description('撤回含二维码的消息。'),
+    notify: koishi_1.Schema.boolean().default(true).description('处理后在群内发送提示。'),
+    notifyText: koishi_1.Schema.string().default('').description('自定义提示。留空则按禁言秒数生成。'),
+    skipAdmins: koishi_1.Schema.boolean().default(true).description('跳过群主和管理员。'),
+    ignoreUsers: koishi_1.Schema.array(koishi_1.Schema.string()).role('table').default([]).description('忽略的用户 ID。'),
+    guilds: koishi_1.Schema.array(koishi_1.Schema.string()).role('table').default([]).description('只在这些群生效。留空表示全部群。'),
+});
+function apply(ctx, config) {
+    const logger = ctx.logger('ban-qrcode');
+    ctx.on('message', async (session) => {
+        if (!(0, detect_1.shouldModerate)({
+            guildId: session.guildId,
+            isDirect: session.isDirect,
+            userId: session.userId,
+            selfId: session.selfId,
+            ignoreUsers: config.ignoreUsers,
+            guilds: config.guilds,
+            roles: session.event.member?.roles,
+            skipAdmins: config.skipAdmins,
+        }))
+            return;
+        const srcs = (0, detect_1.collectImageSrcs)(session.elements ?? []);
+        if (!srcs.length)
+            return;
+        try {
+            const hit = await (0, detect_1.findQrInImages)(srcs, src => (0, qrcode_1.downloadImage)(ctx.http, src), qrcode_1.decodeQr);
+            if (!hit)
+                return;
+            logger.info('qrcode from %s in %s', session.userId, session.guildId);
+            if (config.recall && session.messageId && session.channelId) {
+                try {
+                    await session.bot.deleteMessage(session.channelId, session.messageId);
+                }
+                catch (error) {
+                    logger.warn(error);
+                }
+            }
+            const duration = (0, detect_1.muteDurationMs)(config.muteSeconds);
+            if (duration > 0 && session.guildId && session.userId) {
+                try {
+                    await session.bot.muteGuildMember(session.guildId, session.userId, duration);
+                }
+                catch (error) {
+                    logger.warn(error);
+                }
+            }
+            if (config.notify) {
+                await session.send(config.notifyText || (0, detect_1.defaultNotify)(config.muteSeconds));
+            }
+        }
+        catch (error) {
+            logger.warn(error);
+        }
+    });
+}

package/lib/qrcode.d.ts

@@ -0,0 +1,3 @@
+import { HTTP } from 'koishi';
+export declare function downloadImage(http: HTTP, src: string): Promise<Buffer>;
+export declare function decodeQr(buffer: Buffer): Promise<string | null>;

package/lib/qrcode.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadImage = downloadImage;
+exports.decodeQr = decodeQr;
+const jimp_1 = __importDefault(require("jimp"));
+const jsqr_1 = __importDefault(require("jsqr"));
+const detect_1 = require("./detect");
+async function downloadImage(http, src) {
+    if (src.startsWith('data:')) {
+        const data = (0, detect_1.parseDataUrl)(src);
+        if (!data)
+            throw new Error('invalid data url');
+        return data;
+    }
+    return Buffer.from(await http.get(src, { responseType: 'arraybuffer' }));
+}
+async function decodeQr(buffer) {
+    const image = await jimp_1.default.read(buffer);
+    const { data, width, height } = image.bitmap;
+    const result = (0, jsqr_1.default)(new Uint8ClampedArray(data), width, height, {
+        inversionAttempts: 'attemptBoth',
+    });
+    return result?.data ?? null;
+}

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "koishi-plugin-ban-qrcode",
-  "version": "0.0.0",
-  "description": "Placeholder for Trusted Publisher setup. Real plugin ships as 1.0.0 via OIDC.",
+  "description": "检测到群内二维码后自动撤回并禁言，用于防广告",
+  "version": "1.0.0",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
   "license": "MIT",
   "author": "K4F7",
   "repository": {
@@ -9,7 +14,53 @@
     "url": "git+https://github.com/K4F7/koishi-plugin-ban-qrcode.git"
   },
   "homepage": "https://github.com/K4F7/koishi-plugin-ban-qrcode",
+  "bugs": {
+    "url": "https://github.com/K4F7/koishi-plugin-ban-qrcode/issues"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "tsx --test tests/*.spec.ts"
+  },
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "qrcode",
+    "ban",
+    "mute",
+    "recall",
+    "二维码",
+    "禁言",
+    "撤回",
+    "广告"
+  ],
+  "peerDependencies": {
+    "koishi": "^4.18.7"
+  },
+  "dependencies": {
+    "jimp": "^0.22.12",
+    "jsqr": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "@types/qrcode": "^1.5.5",
+    "koishi": "^4.18.7",
+    "qrcode": "^1.5.4",
+    "tsx": "^4.16.2",
+    "typescript": "^5.6.2"
+  },
+  "koishi": {
+    "description": {
+      "zh": "检测到群内二维码后自动撤回并禁言，用于防广告",
+      "en": "Recall group QR-code images and mute the sender to stop ads"
+    },
+    "service": {
+      "required": [
+        "http"
+      ]
+    }
   }
-}
+}

package/readme.md

@@ -0,0 +1,262 @@
+# koishi-plugin-ban-qrcode
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-ban-qrcode?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-ban-qrcode)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Koishi](https://img.shields.io/badge/Koishi-4-026d4d?style=flat-square)](https://koishi.chat/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/K4F7/koishi-plugin-ban-qrcode/pulls)
+
+群内检测到图片二维码时自动撤回，并禁言发送者（默认 1 分钟）。用于群管理、拦截广告码。
+
+Recall group QR-code images and mute the sender for one minute by default, to stop advertising codes.
+
+## Features
+
+- 🔍 **扫图识码**：下载消息里的图片，解码是否含二维码
+- 🗑️ **自动撤回**：命中后立刻撤回原消息
+- 🔇 **自动禁言**：默认禁言 60 秒，秒数可配
+- 🛡️ **白名单**：默认跳过群主 / 管理员，也可按用户 ID、群 ID 过滤
+- 💬 **群内提示**：处理后可发一句说明，不回显码内内容
+
+## Quick Start
+
+在 [Koishi](https://koishi.chat/) 控制台搜索 `ban-qrcode` 安装，或：
+
+```bash
+npm install koishi-plugin-ban-qrcode
+```
+
+启用后，群成员发带二维码的图片会被撤回并禁言 1 分钟。机器人需要**撤回消息**和**禁言成员**的权限。
+
+依赖 Koishi 的 `http` 服务（`inject: ['http']`）。
+
+## Installation
+
+### Prerequisites
+
+- [Koishi](https://koishi.chat/) `^4.18.7`
+- Node.js 18 或更高（发布流水线使用 Node 24）
+- 适配器实现 `deleteMessage` 和 `muteGuildMember`（QQ / OneBot 等群聊平台）
+
+### Package Manager
+
+```bash
+# npm
+npm install koishi-plugin-ban-qrcode
+
+# pnpm
+pnpm add koishi-plugin-ban-qrcode
+
+# yarn
+yarn add koishi-plugin-ban-qrcode
+```
+
+安装后在控制台启用插件 `ban-qrcode`。
+
+### From Source
+
+```bash
+git clone https://github.com/K4F7/koishi-plugin-ban-qrcode.git
+cd koishi-plugin-ban-qrcode
+npm install
+npm test
+npm run build
+```
+
+`tsc -b` 输出到 `lib/`。GitHub Actions 发布也走这一套。
+
+## Usage
+
+插件没有指令。启用后监听群消息：
+
+1. 只处理群聊，忽略私聊和机器人自己的消息
+2. 收集消息及引用里的 `img` / `image`
+3. 下载图片并解码二维码
+4. 命中则撤回、禁言，可选发送提示
+
+不会把解码出的文本发回群里，避免扩散广告链接。
+
+## Configuration
+
+| 项 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `muteSeconds` | `number` | `60` | 禁言秒数。`0` 表示只撤回不禁言 |
+| `recall` | `boolean` | `true` | 撤回含二维码的消息 |
+| `notify` | `boolean` | `true` | 处理后在群内提示 |
+| `notifyText` | `string` | `''` | 自定义提示。留空则按秒数生成 |
+| `skipAdmins` | `boolean` | `true` | 跳过群主 / 管理员 |
+| `ignoreUsers` | `string[]` | `[]` | 忽略的用户 ID |
+| `guilds` | `string[]` | `[]` | 只在这些群生效。空数组表示全部群 |
+
+默认提示：`检测到二维码，已撤回并禁言 60 秒。`
+
+## API Reference
+
+插件入口导出 `name`、`inject`、`Config`、`apply`。判定与扫码编排在 `src/detect.ts`，下载和解码在 `src/qrcode.ts`。
+
+### `collectImageSrcs(nodes)`
+
+收集 `img` / `image` 的 `src` 或 `url`，去重并保留顺序，会走进嵌套节点（如引用）。
+
+### `shouldModerate(input)`
+
+群聊、非自己、未忽略、在生效群内，且（可选）不是管理员时返回 `true`。
+
+### `findQrInImages(srcs, download, decode)`
+
+按顺序下载并解码，返回第一张命中的 `{ src, text }`。单张失败会跳过。
+
+### `decodeQr(buffer)`
+
+用 Jimp 读图、jsQR 解码。没有码时返回 `null`。
+
+## Architecture
+
+```
+src/
+├── index.ts    # 插件入口：监听群消息，撤回 / 禁言 / 提示
+├── detect.ts   # 收集图片、是否处理、编排扫码
+└── qrcode.ts   # 下载图片、解码二维码
+tests/
+└── detect.spec.ts
+```
+
+数据流：群消息 → 收集图片 URL → 下载 → jsQR → `deleteMessage` + `muteGuildMember`。
+
+禁言时长按 Satori 约定传**毫秒**（60 秒 = `60000`）。
+
+## 工作区开发
+
+按 [Koishi 工作区开发](https://koishi.chat/zh-CN/guide/develop/workspace.html)：本仓库是**独立插件仓**，官方 Yakumo 工作区只用于本地调试，不要把整个工作区提交进来。
+
+```bash
+npm init koishi@latest
+cd <app>
+```
+
+把本仓接到工作区的 `external/ban-qrcode`（Windows 可用目录联接）：
+
+```bat
+mklink /J external\ban-qrcode D:\path\to\koishi-plugin-ban-qrcode
+```
+
+或：
+
+```bash
+npm run clone K4F7/koishi-plugin-ban-qrcode
+```
+
+与 `jandan` 等其它插件一起放在同一个 Yakumo 工作区即可联合调试：
+
+```
+koishi-workspace/
+├── external/
+│   ├── jandan          # junction → 独立仓
+│   └── ban-qrcode      # junction → 独立仓
+├── koishi.yml
+└── package.json
+```
+
+然后在工作区根目录：
+
+```bash
+yarn dev
+```
+
+插件会以 `ban-qrcode` 的名字热重载。本仓自己构建、测试：
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+## FAQ
+
+<details>
+<summary><strong>为什么没有撤回或禁言？</strong></summary>
+
+检查机器人是否有管理员权限，以及适配器是否实现 `deleteMessage` / `muteGuildMember`。权限不足时插件会打日志并继续后续步骤。
+</details>
+
+<details>
+<summary><strong>管理员发群码会被禁言吗？</strong></summary>
+
+默认不会。`skipAdmins` 为 `true` 时跳过角色为 `owner` / `admin` 的成员。
+</details>
+
+<details>
+<summary><strong>为什么有的二维码没扫到？</strong></summary>
+
+图太糊、码只占画面很小一块、或格式 Jimp 读不了（少见 webp）时可能漏检。把更清晰的整图发来更容易命中。
+</details>
+
+<details>
+<summary><strong>会公布码里的链接吗？</strong></summary>
+
+不会。提示语只说明「检测到二维码」，日志也不写码内文本。
+</details>
+
+## Troubleshooting
+
+**no bot permission / mute failed**
+
+机器人不是管理员，或目标是群主 / 更高权限成员。看 `ban-qrcode` logger。
+
+**图片下载失败**
+
+图床拒绝、过期或需要登录。插件会跳过这张图，继续扫同一条消息里的其它图。
+
+## 发布（OIDC Trusted Publishing）
+
+仓库：[`K4F7/koishi-plugin-ban-qrcode`](https://github.com/K4F7/koishi-plugin-ban-qrcode)
+
+工作流：[`.github/workflows/publish.yml`](.github/workflows/publish.yml)。推送 `v*` tag 后由 GitHub Actions 用 OIDC 发布，**不需要 `NPM_TOKEN`**。
+
+### 你需要在 npm 上完成（无法代做）
+
+1. 打开 [npmjs.com](https://www.npmjs.com/) 登录，进入 `koishi-plugin-ban-qrcode` 的包设置（新包可先配 **pending trusted publisher**）
+2. 配置 Trusted Publisher：
+   - Provider：GitHub Actions
+   - Organization or user：`K4F7`
+   - Repository：`koishi-plugin-ban-qrcode`
+   - Workflow filename：必须是 `publish.yml`（不要带路径）
+   - 允许 `npm publish`
+3. 新包可先配 pending trusted publisher，再打 `v1.0.0`；若 npm 要求先有包，用一次性 granular token 发首版再切 OIDC
+4. 首发成功后建议在包设置里开启「Require 2FA and disallow tokens」
+
+### 打正式版
+
+确认 Trusted Publisher 已配好、`package.json` 的 `version` 与 tag 一致后：
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+Actions 会 `npm ci` → `npm test` → `npm run build` → `npm publish --access public`，并自动带 provenance。
+
+## Contributing
+
+欢迎提 issue 和 PR。
+
+1. Fork 仓库，建分支：`git checkout -b feat/my-change`
+2. 改代码，补测试（`tests/detect.spec.ts`）
+3. `npm test` 和 `npm run build` 通过
+4. 开 Pull Request
+
+提交信息建议用 [Conventional Commits](https://www.conventionalcommits.org/)：`feat:` / `fix:` / `docs:` / `test:` / `chore:`。
+
+## Changelog
+
+当前版本 **1.0.0**：群内扫二维码、自动撤回、默认禁言 60 秒、管理员白名单。
+
+## License
+
+[MIT](./LICENSE) © 2026 koishi-plugin-ban-qrcode contributors
+
+## Support
+
+- 🐛 Issues：[github.com/K4F7/koishi-plugin-ban-qrcode/issues](https://github.com/K4F7/koishi-plugin-ban-qrcode/issues)
+- 📦 npm：[koishi-plugin-ban-qrcode](https://www.npmjs.com/package/koishi-plugin-ban-qrcode)
+- 📖 Koishi 文档：[koishi.chat](https://koishi.chat/)

package/index.js

@@ -1 +0,0 @@
-module.exports = {}