npm package: @meowhuan/koishi-plugin-qq-group-manager
Description: Koishi QQ群管理插件（OneBot/LLOneBot）：群管命令、权限校验、图片菜单、状态卡片、复读与AI群聊回复。
Latest version: 0.0.3

# koishi-plugin-qq-group-manager

[![npm](https://img.shields.io/npm/v/%40meowhuan%2Fkoishi-plugin-qq-group-manager?style=flat-square)](https://www.npmjs.com/package/@meowhuan/koishi-plugin-qq-group-manager)

QQ群管理插件（OneBot/LLOneBot）

## 当前状态

已完成插件框架初始化，包含：

- `Config` 配置模型
- `QQGroupManagerService` 服务层
- `群管` 命令入口（`ping` / `plan`）
- 预留的群动作计划类型定义
- 权限校验框架（账号白名单 + 群主/群管理员）
- 基础群管理动作（踢人 / 禁言 / 设管理员）
- 指令日志输出（鉴权日志 + 执行结果日志）
- Meow 图片菜单（可选接管 help）

## 目录结构

```txt
src/
  index.ts      # 插件入口与配置
  service.ts    # 管理服务与未来业务逻辑入口
  commands.ts   # 命令注册
  types.ts      # 通用类型定义
```

## 权限模型

- `allowedUserIds`: 账号白名单，命中后直接通过。
- 非白名单账号：在群聊上下文里，若为群主或群管理员可通过（可配置开关）。
- `admin` 子命令可配置为仅在 bot 为当前群群主时可用（`requireBotOwnerForAdmin`）。

## 日志与输出

- 鉴权细节（白名单/群主/管理员判定）只写入日志，不回显到群聊。
- 指令执行结果会写入插件日志（可配置开关）。
- `dryRun` 默认关闭（`false`），开启后仅输出计划动作不实际执行。

## 菜单功能

- `menuCommand`: 菜单指令名（默认 `菜单`）。
- `replaceHelpAsImageMenu`: 开启后接管 `help`，返回全插件图片菜单。
- `replaceStatusAsImage`: 开启后接管 `status`，返回 Meow 风格状态图片（CPU/内存）。
- 在 OneBot 群聊上下文下，`status` 会额外尝试读取 LLOneBot/OneBot `getStatus()` 并展示在线与统计信息。
- 图片渲染依赖 `puppeteer`，未启用时会回退文本提示。
- 分级菜单：
  - `help` / `菜单`：仅显示父指令分类（如 `群管菜单`）。
  - `help <父指令菜单>` / `菜单 <父指令菜单>`：显示该分类下子指令。
  - 也可直接输入父指令（如 `群管`）直接查看该分类菜单。
  - 用户发送 `help`/`菜单` 后 30 秒内，下一条消息会自动作为菜单关键词配对解析（用于补偿直接发送 `群管菜单` 等触发不稳定场景）。
- 无父指令的命令会被归入 `其它菜单` 分类。

## 群消息管控

- `bannedWords`: 违禁词列表（可在配置页直接维护）。
- `blockCardMessage`: 是否禁止卡片消息（OneBot `json/xml`）。
- `blockForwardMessage`: 是否禁止合并转发消息（OneBot `forward`）。
- `autoDeleteViolation`: 违规后是否自动撤回消息。
- `sendViolationNotice`: 违规后是否在群内发送提示。
- `groupRules`: 按群聊覆盖上述策略（每个群可配置不同选项）。
- `groupRules.enableAiReply`: 可按群覆盖 AI 回复开关（留空则继承全局）。

## 群聊互动

- `enableRepeater`: 启用复读功能。
- `repeaterThreshold`: 连续相同消息触发阈值（默认 3）。
- `repeaterCooldownSeconds`: 同一内容复读冷却（秒）。
- `repeaterEnableGetMsgRefetch`: 当图片消息缺少可发送引用时，通过 OneBot `get_msg` 回查原消息提取 `url/file/id` 后再发送（默认开启）。
- `enableJoinRequestReview`: 启用后自动监听新入群申请并在群内发起审核。
- `joinRequestReviewTtlMinutes`: 审核编号有效期（分钟，默认 30）。
- 触发后 bot 会复读文本与图片（如有），并将“复读触发事件”写入 AI 上下文供后续回复参考。
- 新入群申请会自动推送到群聊，管理员可通过命令或快捷文本进行放行/拒绝。

## AI 自动回复

- 支持两类接口：
  - `openai-compatible`：OpenAI 兼容 Chat Completions（可用于 OpenAI、火山引擎、Codex API/Auth 等兼容网关）。
  - `gemini`：Google Gemini 原生 `generateContent` 接口。
- 主要配置项：
  - `enableAiReply`：总开关。
  - `aiProvider` / `aiBaseUrl` / `aiApiKey` / `aiModel`：模型接入参数。
  - `aiAgentName`：默认智能体自称。
  - `aiSystemPrompt`：默认系统提示词。
  - `aiPersonas` / `aiActivePersona`：多人格配置与切换（可为每个人格设置独立自称与提示词）。
  - `aiReplyMode`：`threshold` / `random` / `hybrid`。
  - `aiMessageThreshold`：累计消息触发阈值。
  - `aiRandomReplyProbability`：随机触发概率。
  - `aiMinReplyIntervalSeconds`：同群最短回复间隔。
  - `aiContextWindow`：送入模型的最近消息窗口。
  - `aiTemperature` / `aiMaxOutputTokens`：生成参数。
  - `aiEnableImageRecognition` / `aiImageMaxCount`：图片识别开关与单次识别图片上限。
  - `aiIgnoreCommandMessage`：忽略命令样式消息，避免影响正常指令流程。
  - `aiEnableDirectMentionTrigger`：是否启用“点名智能体名即强制触发”。
  - `aiEnableFollowupAfterMention` / `aiFollowupWindowSeconds` / `aiFollowupMaxTurns`：点名后同用户跟随回复配置。
  - `aiOwnerPlatform` / `aiOwnerUserId`：主人身份标识（默认 `onebot + QQ号` 形式）。
  - `aiHomePlatform` / `aiHomeUserId`：兼容旧字段，建议迁移到 `aiOwner*`。
  - `aiInterestMinScore`：非点名场景 AI 兴趣触发最低分（越高越冷静）。
  - `aiInterestContextWindow`：非阈值兴趣判定读取的上下文条数（默认 8，范围 4~16）。
- 触发逻辑：
  - 达到阈值后触发；非阈值场景由 AI 兴趣判定触发（不再依赖概率随机）。
  - 非阈值兴趣判定会读取近期上下文，不再只看单条消息。
  - 当消息中命中当前生效的智能体自称（或直接 `@bot`）时，会忽略累计阈值直接触发，并基于该消息及近期上下文回复。
  - 点名触发不会重置阈值计数，阈值累计继续生效。
  - 点名触发时会优先只回应点名那条消息，不会转去回答其他上下文消息。
  - 点名后会进入“话题跟随窗口”，优先判断点名者后续消息；同时允许主人或上下文中的相关追问者对同话题接续提问。
  - 阈值触发时会先进行兴趣判定，若兴趣分不足可跳过发言（仅日志记录）。
  - 点名消息若包含图片，会尝试进行图片识别后再回复（OpenAI 兼容接口为原生图文输入；Gemini 模式回退为图片链接辅助识别）。
  - 点名触发时输出单条正常回复，不额外附加总结文本，减少 token 消耗。
  - 阈值模式会强调“优先回复选定目标消息”，并压缩上下文范围降低错位回复概率。
  - 发送结果与错误信息仅写入插件日志（`cmd:ai-reply`）。

## 命令（首版）

- `群管 ping`
- `菜单 [关键词]`
- `群管 plan <groupId>`
- `群管 kick <qq号|@用户> [-r] [-m 原因]`
- `群管 mute <qq号|@用户> <分钟> [-r 原因]`
- `群管 gag [qq号|@用户]` / `群管 口球 [qq号|@用户]`
- `群管 unmute <qq号|@用户> [-r 原因]`
- `群管 admin <qq号|@用户> [on|off] [-r 原因]`
- `群管 审核 <编号> <同意|拒绝> [-r 理由]`

收到新入群申请后，群内会收到审核提示，支持两种处理方式：

- 命令：`群管 审核 <编号> 同意` / `群管 审核 <编号> 拒绝`
- 快捷文本：`同意入群 <编号>` / `拒绝入群 <编号>`

普通成员在群聊中将 `mute`/`gag` 目标指向自己时，会忽略时长与规则，随机触发 1~60 分钟口球禁言。
该功能可在控制页「娱乐设置」通过 `enableSelfGag` 开关启停。

- 白名单用户不会触发口球娱乐逻辑。
- 白名单目标默认受禁言保护；可通过 `allowAdminBypassWhitelistMute` 控制是否允许群主/管理员绕过保护执行禁言。
- 普通成员反复尝试对他人执行禁言时，会触发惩罚：随机 1~10 分钟禁言本人。
  - 该行为可配置：`enableUnauthorizedMutePunish`、`unauthorizedMuteAttemptThreshold`、`unauthorizedMuteWindowMinutes`、`unauthorizedMutePunishMinMinutes`、`unauthorizedMutePunishMaxMinutes`。