koishi-plugin-qq-group-manager

QQ群管理插件（OneBot/LLOneBot）

当前状态

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

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

目录结构

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。