![\"GroupHelper](\"./logo.svg\"){kind=logo}
\n\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/koishi-plugin-grouphelper?style=flat-square\")
![\"npm](\"https://img.shields.io/npm/dm/koishi-plugin-grouphelper?style=flat-square\")
![\"license\"](\"https://img.shields.io/github/license/camvanaa/koishi-plugin-grouphelper?style=flat-square\")
全方位的群组管理解决方案，为 Koishi 机器人提供强大的群管理能力
\n\n---\n\n## 特性亮点\n\n- **完善的成员管理** - 踢人、禁言、设置管理员、批量操作等\n- **灵活的警告系统** - 累计警告达到阈值自动禁言，支持自定义表达式\n- **自定义角色权限** - 基于角色的权限控制，细粒度的命令权限管理\n- **智能关键词系统** - 入群验证、违禁词检测，支持自动处理\n- **防撤回/防复读** - 记录撤回消息，检测并处理复读行为\n- **AI 智能审核** - 举报系统集成 AI，自动判断违规等级并处理\n- **丰富的娱乐功能** - 掷骰子、自助禁言抽卡（带保底机制）\n- **可视化控制台** - Web 面板管理权限、查看日志、配置功能\n\n---\n\n## 快速开始\n\n### 安装\n\n```bash\nnpm install koishi-plugin-grouphelper\n```\n\n或在 Koishi 控制台插件市场搜索 `grouphelper` 安装。\n\n### 依赖\n\n| 类型 | 服务 | 说明 |\n| ---- | ------------ | ------------------------------ |\n| 必需 | `database` | 数据库服务，用于存储配置和数据 |\n| 可选 | `console` | 控制台面板，提供 Web 管理界面 |\n| 可选 | `puppeteer` | 浏览器服务，用于生成状态图片 |\n\n### 基础配置\n\n在 Koishi 控制台中启用插件后，主要配置项包括：\n\n- **warnLimit** - 警告次数阈值，达到后触发自动禁言\n- **banTimes.expression** - 禁言时长表达式，支持数学运算\n- **forbidden** - 违禁词设置（自动撤回、禁言、踢出等）\n- **openai** - AI 功能配置（API Key、模型、提示词等）\n- **report** - 举报功能配置（启用、自动处理、上下文等）\n- **banme** - 自助禁言抽卡配置（概率、保底机制等）\n- **antiRecall** - 防撤回配置（保留天数、记录数量）\n- **antiRepeat** - 防复读配置（阈值设置）\n\n---\n\n## 权限系统\n\n### 权限来源\n\n用户权限由以下三部分组成：\n\n1. **Koishi Authority 等级** - 基于 `user.authority` 自动映射到对应的内置角色\n2. **群管理员身份** - 群主/管理员自动获得 `guild-admin` 角色权限（仅当前群生效）\n3. **自定义角色** - 通过控制台或命令手动分配的角色\n\n### 内置角色\n\n内置角色由系统自动分配，不支持手动添加或移除成员：\n\n| 角色 ID | 名称 | 自动分配条件 |\n| -------------- | ------------ | ------------------------------ |\n| `authority1` | Authority 1 | user.authority ≥ 1 |\n| `authority2` | Authority 2 | user.authority ≥ 2 |\n| `authority3` | Authority 3 | user.authority ≥ 3 |\n| `authority4+` | Authority ≥4 | user.authority ≥ 4 |\n| `guild-admin` | 群管理员 | 群主或管理员身份（仅群内生效） |\n\n> 在 Web 控制台中为内置角色配置权限节点，即可控制不同等级用户的命令访问权限。\n\n### 自定义角色\n\n可通过控制台创建自定义角色，并通过命令分配给用户：\n\n```bash\ngauth.list # 列出所有可用角色\ngauth.add @用户 moderator # 给用户添加角色\ngauth.remove @用户 moderator # 移除用户的角色\ngauth.info @用户 # 查看用户的所有角色\n```\n\n### 权限检查逻辑\n\n1. 精确匹配权限节点（如 `warn.add`）\n2. 超级通配符 `*`（拥有所有权限）\n3. 模块通配符（如 `warn.*` 匹配 `warn.add`、`warn.clear` 等）\n\n---\n\n## 时间表达式\n\n禁言时长支持灵活的时间表达式：\n\n| 格式 | 示例 | 说明 |\n| -------- | -------------------------- | ------------------ |\n| 基本单位 | `30s`, `10m`, `1h`, `1d` | 秒、分钟、小时、天 |\n| 组合格式 | `1h30m`, `2d12h` | 多单位组合 |\n| 数学运算 | `(10+5)*2m` | 支持 +, -, *, /, ^ |\n| 函数 | `sqrt(100)s` | 支持 sqrt() |\n| 科学计数 | `1e2s` | 100 秒 |\n\n**示例**：`(sqrt(100)+1e1)^2s` = 400秒 = 6分40秒\n\n---\n\n## 模块架构\n\n插件采用模块化设计，各功能独立：\n\n| 模块 | 功能 |\n| -------------- | -------------------------------- |\n| `MemberManage` | 成员管理（踢人、设管理、头衔等） |\n| `OrderManage` | 禁言管理（禁言、解禁、全体禁言） |\n| `Warn` | 警告系统 |\n| `Auth` | 角色权限管理 |\n| `Keyword` | 关键词管理（验证词、违禁词） |\n| `Welcome` | 欢迎/欢送语 |\n| `Antirecall` | 防撤回 |\n| `Antirepeat` | 防复读 |\n| `Report` | 举报系统（AI 审核） |\n| `AI` | AI 对话和翻译 |\n| `Log` | 日志记录和查询 |\n| `Subscription` | 通知订阅 |\n| `Dice` | 掷骰子 |\n| `Banme` | 自助禁言抽卡 |\n| `Status` | 系统状态 |\n\n---\n\n## 控制台面板\n\n启用 `console` 服务后，可通过 Web 面板进行管理：\n\n- **权限管理** - 可视化配置角色和权限节点\n- **日志查看** - 查看操作日志和命令执行记录\n- **数据统计** - 命令使用统计、用户活跃度等\n- **功能配置** - 各模块的开关和参数设置\n\n---\n\n## 命令列表\n\n完整的命令列表请在 Koishi 控制台的插件配置页面查看，或使用命令：\n\n```bash\ngrouphelper -a # 显示所有可用命令\ngrouphelper -v # 显示版本信息\n```\n\n---\n\n## 开发\n\n### 项目结构\n\n```bash\nsrc/\n├── index.ts # 插件入口\n├── config.ts # 配置和文档\n├── types/ # 类型定义\n├── utils/ # 工具函数\n└── core/\n ├── services/ # 核心服务\n │ ├── auth.service.ts # 权限服务\n │ └── grouphelper.service.ts\n ├── data/ # 数据管理\n └── modules/ # 功能模块\n ├── base.module.ts # 模块基类\n ├── warn.module.ts\n ├── auth.module.ts\n └── ...\n```\n\n### 添加新模块\n\n1. 创建模块文件继承 `BaseModule`\n2. 实现 `onInit()` 方法注册命令\n3. 在 `modules/index.ts` 导出\n4. 在 `src/index.ts` 注册模块\n\n---\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n- [GitHub Issues](https://github.com/camvanaa/koishi-plugin-grouphelper/issues) - 问题反馈和功能建议\n- [Pull Requests](https://github.com/camvanaa/koishi-plugin-grouphelper/pulls) - 代码贡献\n\n[](https://github.com/camvanaa/koishi-plugin-grouphelper/graphs/contributors)\n\n---\n\n## 许可证\n\nMIT License\n","readmeFilename":"readme.md"}