@nestim/koishi-plugin-qq-group-manager 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/commands.d.ts +4 -0
- package/lib/commands.js +212 -0
- package/lib/index.d.ts +99 -0
- package/lib/index.js +187 -0
- package/lib/service.d.ts +167 -0
- package/lib/service.js +3160 -0
- package/lib/types.d.ts +23 -0
- package/lib/types.js +2 -0
- package/package.json +37 -0
- package/readme.md +203 -0
package/lib/types.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export interface GroupActionPlan {
|
|
2
|
+
action: string;
|
|
3
|
+
groupId: string;
|
|
4
|
+
targetId?: string;
|
|
5
|
+
reason?: string;
|
|
6
|
+
}
|
|
7
|
+
export interface ActionResult {
|
|
8
|
+
ok: boolean;
|
|
9
|
+
message: string;
|
|
10
|
+
plan?: GroupActionPlan;
|
|
11
|
+
}
|
|
12
|
+
export type MemberRole = 'owner' | 'admin' | 'member';
|
|
13
|
+
export interface AuthorizationResult {
|
|
14
|
+
ok: boolean;
|
|
15
|
+
message: string;
|
|
16
|
+
userMessage?: string;
|
|
17
|
+
}
|
|
18
|
+
export interface MuteParseResult {
|
|
19
|
+
ok: boolean;
|
|
20
|
+
targetId: string;
|
|
21
|
+
minutes: number;
|
|
22
|
+
message: string;
|
|
23
|
+
}
|
package/lib/types.js
ADDED
package/package.json
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@nestim/koishi-plugin-qq-group-manager",
|
|
3
|
+
"description": "Koishi QQ群管理插件（OneBot/LLOneBot）：群管命令、权限校验、图片菜单、状态卡片、复读、AI群聊回复、记忆库、识图与自动管控（禁言/踢人）。",
|
|
4
|
+
"version": "0.1.3",
|
|
5
|
+
"main": "lib/index.js",
|
|
6
|
+
"typings": "lib/index.d.ts",
|
|
7
|
+
"files": [
|
|
8
|
+
"lib",
|
|
9
|
+
"dist"
|
|
10
|
+
],
|
|
11
|
+
"license": "MIT",
|
|
12
|
+
"scripts": {
|
|
13
|
+
"build": "tsc -b",
|
|
14
|
+
"clean": "tsc -b --clean",
|
|
15
|
+
"rebuild": "npm run clean && npm run build"
|
|
16
|
+
},
|
|
17
|
+
"keywords": [
|
|
18
|
+
"qq",
|
|
19
|
+
"group",
|
|
20
|
+
"onebot",
|
|
21
|
+
"llonebot",
|
|
22
|
+
"koishi",
|
|
23
|
+
"koishi-plugin",
|
|
24
|
+
"chatbot",
|
|
25
|
+
"moderation",
|
|
26
|
+
"memory",
|
|
27
|
+
"vision",
|
|
28
|
+
"ai"
|
|
29
|
+
],
|
|
30
|
+
"devDependencies": {},
|
|
31
|
+
"peerDependencies": {
|
|
32
|
+
"koishi": "^4.18.7"
|
|
33
|
+
},
|
|
34
|
+
"koishi": {
|
|
35
|
+
"description": "QQ群管理插件（群管、自动管控、记忆、识图、AI回复）。"
|
|
36
|
+
}
|
|
37
|
+
}
|
package/readme.md
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# koishi-qq-group-manager
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@nestim/koishi-qq-group-manager)
|
|
4
|
+
|
|
5
|
+
QQ群管理插件（OneBot/LLOneBot）：群管命令、权限校验、图片菜单、状态卡片、复读、AI群聊回复、记忆库、识图与自动管控（禁言/踢人）。
|
|
6
|
+
|
|
7
|
+
## 禁言指令优化（v0.0.4）
|
|
8
|
+
|
|
9
|
+
`群管 mute` 不再依赖固定顺序解析参数，改为智能解析，避免「禁言时长被识别成 QQ 号」：
|
|
10
|
+
|
|
11
|
+
- 目标优先取 `@用户`（支持群内 @ 及 `[CQ:at]`），再考虑文本中的 QQ 号；
|
|
12
|
+
- 时长支持多种写法：`10`（分钟）、`10分钟` / `10分` / `10min` / `10m`、`1小时` / `1时` / `1h`、`1天` / `1d`、`1周` / `1w`；
|
|
13
|
+
- 兼容「先时长后 QQ」的输入（如 `群管 mute 30 123456`），会自动与群成员比对纠正目标；
|
|
14
|
+
- 缺少目标或时长时会给出明确提示与示例，不再静默把数字当 QQ 号处理；
|
|
15
|
+
- 时长上限 30 天（43200 分钟），超出部分按 30 天处理并在结果中提示。
|
|
16
|
+
|
|
17
|
+
示例：
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
群管 mute @用户 10 # 10 分钟
|
|
21
|
+
群管 mute 123456 30分钟 # QQ 123456 禁言 30 分钟
|
|
22
|
+
群管 mute @用户 1小时 -r 刷屏 # 1 小时，附原因
|
|
23
|
+
群管 unmute @用户 # 解除禁言
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## 自动管控（v0.0.4 新增）
|
|
27
|
+
|
|
28
|
+
成员在群内触发违规（命中违禁词 / 卡片消息 / 合并转发，行为沿用「消息管控」既有配置）后，插件会按群统计违规次数，达到阈值自动处理：
|
|
29
|
+
|
|
30
|
+
- **自动禁言**：累计违规达到阈值 → 按设定时长禁言；
|
|
31
|
+
- **自动踢人**：累计违规达到更高阈值 → 自动移出群聊并清零计数；
|
|
32
|
+
- 计数采用滑动窗口（默认 60 分钟）：窗口内连续违规才累计，超时未违规则重新计数；
|
|
33
|
+
- 白名单账号、群主、群管理员、bot 自身不会触发自动禁言/踢人（消息撤回与提示仍按原逻辑执行）；
|
|
34
|
+
- 自动处理后若开启「违规群内提示」，会在群内公告处理结果；所有判定均写入插件日志。
|
|
35
|
+
|
|
36
|
+
全局默认设置（插件配置 →「自动管控」）：
|
|
37
|
+
|
|
38
|
+
| 配置项 | 默认值 | 说明 |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| `enableAutoMute` | false | 是否启用自动禁言 |
|
|
41
|
+
| `autoMuteViolationThreshold` | 3 | 触发自动禁言的违规次数 |
|
|
42
|
+
| `autoMuteMinutes` | 10 | 自动禁言时长（分钟） |
|
|
43
|
+
| `enableAutoKick` | false | 是否启用自动踢人 |
|
|
44
|
+
| `autoKickViolationThreshold` | 5 | 触发自动踢人的违规次数 |
|
|
45
|
+
| `autoViolationWindowMinutes` | 60 | 违规计数统计窗口（分钟） |
|
|
46
|
+
|
|
47
|
+
按群单独设置：在插件配置 →「消息管控」→ `groupRules` 中为某个群新增一条记录并填写 `autoMuteEnabled` / `autoMuteThreshold` / `autoMuteMinutes` / `autoKickEnabled` / `autoKickThreshold` / `autoViolationWindowMinutes`，即可覆盖全局设置；留空则跟随全局。
|
|
48
|
+
|
|
49
|
+
## 记忆库（v0.0.4+）
|
|
50
|
+
|
|
51
|
+
通过群聊指令维护一份 `Memory.md`（默认存储在 Koishi 数据目录），充当长期记忆库；
|
|
52
|
+
|
|
53
|
+
- **保存**：`[记忆]+内容`（如 `[记忆] 小明的生日是2000年6月`），自动带上时间与用户写入 `Memory.md`，每条记忆之间用 `---` 分隔。
|
|
54
|
+
- **查询**：`[记忆查询] 关键词`（无关键词则列出最近几条）。
|
|
55
|
+
- **列表**：`[记忆列表]`（列出最近记忆）。
|
|
56
|
+
- **删除**：`[记忆删除] 关键词`（删除所有包含该关键词的记忆）。
|
|
57
|
+
- **供 AI 引用**：开启 `memoryInAi` 后，AI 回复与识图时会检索相关记忆并注入上下文（相关才引用，不编造）。
|
|
58
|
+
- **查看/编辑**：在 Koishi 控制台左侧「Explorer（探索器）」里打开 `Memory.md`，可直接查看和手动增删改。
|
|
59
|
+
|
|
60
|
+
全局开关：插件配置 →「记忆库」→ `enableMemory` / `memoryFileName` / `memoryInAi`。
|
|
61
|
+
|
|
62
|
+
## AI 识图（v0.0.4+）
|
|
63
|
+
|
|
64
|
+
- 识图走 OpenAI 兼容接口的 `image_url` 格式（`deepseek-v4-flash-vision-exp` 等支持视觉的模型可用）。
|
|
65
|
+
- 图片来源要求：`[CQ:image,url=http(s)://...]` 或图片元素中的 http(s)/`data:image/` 链接；若 LLOneBot 只给了 `file=`/`file_id` 本地路径（无 http 链接），则无法直接识别。
|
|
66
|
+
- 调试：
|
|
67
|
+
- 群内发送 `群管 查图`（可附一张图），会显示这条消息里识别到的图片数量与链接/原始字段；
|
|
68
|
+
- 发送图片并 `@bot` 时，若检测到图片但提取不到可发送链接，会写 `[img-debug]` 日志。
|
|
69
|
+
- 前提：`aiEnableImageRecognition` 为 true、`aiImageMaxCount > 0`，且所用模型支持视觉输入。
|
|
70
|
+
|
|
71
|
+
## 当前状态
|
|
72
|
+
|
|
73
|
+
已完成插件框架初始化，包含：
|
|
74
|
+
|
|
75
|
+
- `Config` 配置模型
|
|
76
|
+
- `QQGroupManagerService` 服务层
|
|
77
|
+
- `群管` 命令入口（`ping` / `plan`）
|
|
78
|
+
- 预留的群动作计划类型定义
|
|
79
|
+
- 权限校验框架（账号白名单 + 群主/群管理员）
|
|
80
|
+
- 基础群管理动作（踢人 / 禁言 / 设管理员）
|
|
81
|
+
- 指令日志输出（鉴权日志 + 执行结果日志）
|
|
82
|
+
- Meow 图片菜单（可选接管 help）
|
|
83
|
+
|
|
84
|
+
## 目录结构
|
|
85
|
+
|
|
86
|
+
```txt
|
|
87
|
+
src/
|
|
88
|
+
index.ts # 插件入口与配置
|
|
89
|
+
service.ts # 管理服务与未来业务逻辑入口
|
|
90
|
+
commands.ts # 命令注册
|
|
91
|
+
types.ts # 通用类型定义
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## 权限模型
|
|
95
|
+
|
|
96
|
+
- `allowedUserIds`: 账号白名单，命中后直接通过。
|
|
97
|
+
- 非白名单账号：在群聊上下文里，若为群主或群管理员可通过（可配置开关）。
|
|
98
|
+
- `admin` 子命令可配置为仅在 bot 为当前群群主时可用（`requireBotOwnerForAdmin`）。
|
|
99
|
+
|
|
100
|
+
## 日志与输出
|
|
101
|
+
|
|
102
|
+
- 鉴权细节（白名单/群主/管理员判定）只写入日志，不回显到群聊。
|
|
103
|
+
- 指令执行结果会写入插件日志（可配置开关）。
|
|
104
|
+
- `dryRun` 默认关闭（`false`），开启后仅输出计划动作不实际执行。
|
|
105
|
+
|
|
106
|
+
## 菜单功能
|
|
107
|
+
|
|
108
|
+
- `menuCommand`: 菜单指令名（默认 `菜单`）。
|
|
109
|
+
- `replaceHelpAsImageMenu`: 开启后接管 `help`，返回全插件图片菜单。
|
|
110
|
+
- `replaceStatusAsImage`: 开启后接管 `status`，返回 Meow 风格状态图片（CPU/内存）。
|
|
111
|
+
- 在 OneBot 群聊上下文下，`status` 会额外尝试读取 LLOneBot/OneBot `getStatus()` 并展示在线与统计信息。
|
|
112
|
+
- 图片渲染依赖 `puppeteer`，未启用时会回退文本提示。
|
|
113
|
+
- 分级菜单：
|
|
114
|
+
- `help` / `菜单`：仅显示父指令分类（如 `群管菜单`）。
|
|
115
|
+
- `help <父指令菜单>` / `菜单 <父指令菜单>`：显示该分类下子指令。
|
|
116
|
+
- 也可直接输入父指令（如 `群管`）直接查看该分类菜单。
|
|
117
|
+
- 用户发送 `help`/`菜单` 后 30 秒内，下一条消息会自动作为菜单关键词配对解析（用于补偿直接发送 `群管菜单` 等触发不稳定场景）。
|
|
118
|
+
- 无父指令的命令会被归入 `其它菜单` 分类。
|
|
119
|
+
|
|
120
|
+
## 群消息管控
|
|
121
|
+
|
|
122
|
+
- `bannedWords`: 违禁词列表（可在配置页直接维护）。
|
|
123
|
+
- `blockCardMessage`: 是否禁止卡片消息（OneBot `json/xml`）。
|
|
124
|
+
- `blockForwardMessage`: 是否禁止合并转发消息（OneBot `forward`）。
|
|
125
|
+
- `autoDeleteViolation`: 违规后是否自动撤回消息。
|
|
126
|
+
- `sendViolationNotice`: 违规后是否在群内发送提示。
|
|
127
|
+
- `groupRules`: 按群聊覆盖上述策略（每个群可配置不同选项）。
|
|
128
|
+
- `groupRules.enableAiReply`: 可按群覆盖 AI 回复开关（留空则继承全局）。
|
|
129
|
+
- 自动禁言 / 自动踢人：见上方「自动管控」一节，支持全局与按群配置。
|
|
130
|
+
|
|
131
|
+
## 群聊互动
|
|
132
|
+
|
|
133
|
+
- `enableRepeater`: 启用复读功能。
|
|
134
|
+
- `repeaterThreshold`: 连续相同消息触发阈值（默认 3）。
|
|
135
|
+
- `repeaterCooldownSeconds`: 同一内容复读冷却（秒）。
|
|
136
|
+
- `repeaterEnableGetMsgRefetch`: 当图片消息缺少可发送引用时，通过 OneBot `get_msg` 回查原消息提取 `url/file/id` 后再发送（默认开启）。
|
|
137
|
+
- `enableJoinRequestReview`: 启用后自动监听新入群申请并在群内发起审核。
|
|
138
|
+
- `joinRequestReviewTtlMinutes`: 审核编号有效期（分钟，默认 30）。
|
|
139
|
+
- 触发后 bot 会复读文本与图片（如有），并将“复读触发事件”写入 AI 上下文供后续回复参考。
|
|
140
|
+
- 新入群申请会自动推送到群聊，管理员可通过命令或快捷文本进行放行/拒绝。
|
|
141
|
+
|
|
142
|
+
## AI 自动回复
|
|
143
|
+
|
|
144
|
+
- 支持两类接口：
|
|
145
|
+
- `openai-compatible`：OpenAI 兼容 Chat Completions（可用于 OpenAI、火山引擎、Codex API/Auth 等兼容网关）。
|
|
146
|
+
- `gemini`：Google Gemini 原生 `generateContent` 接口。
|
|
147
|
+
- 主要配置项：
|
|
148
|
+
- `enableAiReply`：总开关。
|
|
149
|
+
- `aiProvider` / `aiBaseUrl` / `aiApiKey` / `aiModel`：模型接入参数。
|
|
150
|
+
- `aiAgentName`：默认智能体自称。
|
|
151
|
+
- `aiSystemPrompt`：默认系统提示词。
|
|
152
|
+
- `aiPersonas` / `aiActivePersona`：多人格配置与切换（可为每个人格设置独立自称与提示词）。
|
|
153
|
+
- `aiReplyMode`：`threshold` / `random` / `hybrid`。
|
|
154
|
+
- `aiMessageThreshold`：累计消息触发阈值。
|
|
155
|
+
- `aiRandomReplyProbability`：随机触发概率。
|
|
156
|
+
- `aiMinReplyIntervalSeconds`：同群最短回复间隔。
|
|
157
|
+
- `aiContextWindow`：送入模型的最近消息窗口。
|
|
158
|
+
- `aiTemperature` / `aiMaxOutputTokens`：生成参数。
|
|
159
|
+
- `aiEnableImageRecognition` / `aiImageMaxCount`：图片识别开关与单次识别图片上限。
|
|
160
|
+
- `aiIgnoreCommandMessage`：忽略命令样式消息，避免影响正常指令流程。
|
|
161
|
+
- `aiEnableDirectMentionTrigger`：是否启用“点名智能体名即强制触发”。
|
|
162
|
+
- `aiEnableFollowupAfterMention` / `aiFollowupWindowSeconds` / `aiFollowupMaxTurns`：点名后同用户跟随回复配置。
|
|
163
|
+
- `aiOwnerPlatform` / `aiOwnerUserId`：主人身份标识（默认 `onebot + QQ号` 形式）。
|
|
164
|
+
- `aiHomePlatform` / `aiHomeUserId`：兼容旧字段，建议迁移到 `aiOwner*`。
|
|
165
|
+
- `aiInterestMinScore`：非点名场景 AI 兴趣触发最低分（越高越冷静）。
|
|
166
|
+
- `aiInterestContextWindow`：非阈值兴趣判定读取的上下文条数（默认 8，范围 4~16）。
|
|
167
|
+
- 触发逻辑：
|
|
168
|
+
- 达到阈值后触发；非阈值场景由 AI 兴趣判定触发（不再依赖概率随机）。
|
|
169
|
+
- 非阈值兴趣判定会读取近期上下文，不再只看单条消息。
|
|
170
|
+
- 当消息中命中当前生效的智能体自称（或直接 `@bot`）时，会忽略累计阈值直接触发，并基于该消息及近期上下文回复。
|
|
171
|
+
- 点名触发不会重置阈值计数，阈值累计继续生效。
|
|
172
|
+
- 点名触发时会优先只回应点名那条消息，不会转去回答其他上下文消息。
|
|
173
|
+
- 点名后会进入“话题跟随窗口”，优先判断点名者后续消息；同时允许主人或上下文中的相关追问者对同话题接续提问。
|
|
174
|
+
- 阈值触发时会先进行兴趣判定，若兴趣分不足可跳过发言（仅日志记录）。
|
|
175
|
+
- 点名消息若包含图片，会尝试进行图片识别后再回复（OpenAI 兼容接口为原生图文输入；Gemini 模式回退为图片链接辅助识别）。
|
|
176
|
+
- 点名触发时输出单条正常回复，不额外附加总结文本，减少 token 消耗。
|
|
177
|
+
- 阈值模式会强调“优先回复选定目标消息”，并压缩上下文范围降低错位回复概率。
|
|
178
|
+
- 发送结果与错误信息仅写入插件日志（`cmd:ai-reply`）。
|
|
179
|
+
|
|
180
|
+
## 命令（首版）
|
|
181
|
+
|
|
182
|
+
- `群管 ping`
|
|
183
|
+
- `菜单 [关键词]`
|
|
184
|
+
- `群管 plan <groupId>`
|
|
185
|
+
- `群管 kick <qq号|@用户> [-r] [-m 原因]`
|
|
186
|
+
- `群管 mute <qq号|@用户> <时长>`（时长支持 `10`、`10分钟`、`1小时`、`1天` 等写法，见上文）
|
|
187
|
+
- `群管 gag [qq号|@用户]` / `群管 口球 [qq号|@用户]`
|
|
188
|
+
- `群管 unmute <qq号|@用户> [-r 原因]`
|
|
189
|
+
- `群管 admin <qq号|@用户> [on|off] [-r 原因]`
|
|
190
|
+
- `群管 审核 <编号> <同意|拒绝> [-r 理由]`
|
|
191
|
+
|
|
192
|
+
收到新入群申请后，群内会收到审核提示，支持两种处理方式：
|
|
193
|
+
|
|
194
|
+
- 命令：`群管 审核 <编号> 同意` / `群管 审核 <编号> 拒绝`
|
|
195
|
+
- 快捷文本：`同意入群 <编号>` / `拒绝入群 <编号>`
|
|
196
|
+
|
|
197
|
+
普通成员在群聊中将 `mute`/`gag` 目标指向自己时，会忽略时长与规则，随机触发 1~60 分钟口球禁言。
|
|
198
|
+
该功能可在控制页「娱乐设置」通过 `enableSelfGag` 开关启停。
|
|
199
|
+
|
|
200
|
+
- 白名单用户不会触发口球娱乐逻辑。
|
|
201
|
+
- 白名单目标默认受禁言保护；可通过 `allowAdminBypassWhitelistMute` 控制是否允许群主/管理员绕过保护执行禁言。
|
|
202
|
+
- 普通成员反复尝试对他人执行禁言时，会触发惩罚：随机 1~10 分钟禁言本人。
|
|
203
|
+
- 该行为可配置：`enableUnauthorizedMutePunish`、`unauthorizedMuteAttemptThreshold`、`unauthorizedMuteWindowMinutes`、`unauthorizedMutePunishMinMinutes`、`unauthorizedMutePunishMaxMinutes`。
|