K AegisSpam

# 🛡️ K AegisSpam - บอทป้องกันสแปม & ดูแลแชทอัจฉริยะแบบ Real-Time > **K AegisSpam** คือบอทระบบรักษาความปลอดภัยและป้องกันการสแปมข้อความสำหรับเซิร์ฟเวอร์ Discord ยุคใหม่ พัฒนาด้วย Python 3.11 และ discord.py 2.7+ (Discord API v10) มาพร้อมกลไกตรวจจับสแปมหลายมิติ (**Multi-Vector Spam Defense**) เช่น การฟลัดข้อความรัว (Flooding), ข้อความซ้ำ (Duplicate), การแท็กก่อกวน (Mass Mentions) และบล็อกลิงก์คำเชิญอัตโนมัติ โดยระงับสิทธิ์ทันทีผ่าน **Discord Native Timeout** มีตัวเลขนับถอยหลังบนหน้า Discord Client และระบบคำสั่งลบข้อความอัจฉริยะ `/clear` ครบวงจร --- ## 🌟 จุดเด่นและฟีเจอร์หลัก (Core Features) ### 1. 🛡️ กลไกตรวจจับสแปมหลายมิติ (Multi-Vector Spam Defense) - **Sliding Window Rate-Limiter (O(1)):** ตรวจจับการส่งข้อความถี่หรือรัวเกินเกณฑ์ (Flooding) ด้วยโครงสร้างข้อมูล Deque ประสิทธิภาพสูง ตัดการทำงานทันทีหากส่งเกินกำหนดในเวลาที่ตั้งไว้ - **Duplicate Message Hasher:** ตรวจจับและปรับสภาพข้อความ (Normalize) ดักจับผู้ใช้ที่ส่งข้อความเดิมซ้ำๆ เพื่อกวนแชทหรือโฆษณา - **Mass Mention Limiter:** ตรวจจับข้อความที่มีการแท็กสมาชิกหรือยศจำนวนมากผิดปกติ (User & Role Mentions) - **Discord Invite Blocker:** ดักจับ Regex URLs ของลิงก์คำเชิญ Discord ทุกรูปแบบ (`discord.gg/*`, `discord.com/invite/*`) ป้องกันการสแปมโปรโมตเซิร์ฟเวอร์ ### 2. ⚡ ระบบการลงโทษแบบ Discord Native Timeout (v10 API) - **Native Timeout อัตโนมัติ:** เมื่อตรวจพบสแปม บอทจะลงโทษด้วยการ Timeout ทันที สมาชิกจะไม่สามารถพิมพ์ข้อความ ส่งสติกเกอร์ รีแอคชั่น หรือพูดในห้องเสียงได้ - **มีตัวเลขนับถอยหลัง (Visual Countdown):** ฝั่ง Discord Client จะแสดงป้ายเวลานับถอยหลังชัดเจน - **Mute Role Fallback:** รองรับการสลับไปใช้ยศ `Muted` แบบดั้งเดิมได้ตามความต้องการของเซิร์ฟเวอร์ - **Rate-Limit Safe DM:** ส่งการ์ดแจ้งเตือนผ่าน DM ไปยังผู้กระทำผิดเพียงครั้งเดียว พร้อมระบบ Cooldown ป้องกันไม่ให้บอทถูก Discord แบน API ### 3. 🧹 เครื่องมือจัดการข้อความอัจฉริยะ (Advanced Purge & Moderation) - **Smart Filter `/clear messages`:** ลบข้อความ 1-100 ข้อความ พร้อมฟิลเตอร์คัดกรอง: - เลือกลบเฉพาะข้อความของผู้ใช้ที่ระบุ - เลือกลบเฉพาะข้อความจากบอท (Bots Only) - เลือกลบเฉพาะข้อความที่มีคำเฉพาะ (Contains Keyword) - **Channel Cleanup `/clear all`:** ล้างข้อความล่าสุดในห้องแชทอย่างปลอดภัย - **Manual Timeout `/timeout` & `/untimeout`:** สั่งระงับการใช้งานสมาชิกได้ด้วยตนเอง ระบุเวลาได้ยืดหยุ่น เช่น `60s`, `5m`, `2h`, `1d` ### 4. 📜 ระบบบันทึกประวัติความปลอดภัย (Audit Log System) - ส่งรายงานการตรวจจับและการลงโทษไปยังห้อง Log โดยอัตโนมัติ: - 👤 **ข้อมูลผู้กระทำผิด:** Avatar, Mention, Username และ User ID - 📍 **ห้องที่เกิดเหตุ:** ลิงก์ Channel Mention - ⚡ **มาตรการที่ใช้:** ระบุรูปแบบและระยะเวลาการลงโทษ - 🔍 **สาเหตุการตรวจพบ:** ประเภทของสแปมที่ตรวจเจอ - 💬 **ตัวอย่างข้อความ:** พรีวิวข้อความที่ถูกตรวจจับ ### 5. ⚙️ จัดการการตั้งค่าและข้อยกเว้น (Customization & Whitelist) - **Whitelist System:** ยกเว้น ยศ (Roles), ห้องแชท (Channels), และผู้ใช้ (Users) จากระบบตรวจจับ - **Per-Guild Persistent JSON:** บันทึกข้อมูลแยกรายเซิร์ฟเวอร์ด้วย Safe Atomic Write ข้อมูลไม่สูญหายแม้บอทรีสตาร์ท --- ## 📋 คู่มือคำสั่ง Slash Commands ฉบับสมบูรณ์ > 🔒 ทุกคำสั่งเป็น **Slash Commands (`/`)** และตอบกลับแบบ **Ephemeral** (มองเห็นเฉพาะผู้ใช้คำสั่ง) ### 🛡️ หมวดระบบป้องกันสแปม (`/antispam`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/antispam status` | *(ไม่มี)* | แสดงสถานะ เกณฑ์ตรวจจับ และห้อง Log ของเซิร์ฟเวอร์ | | `/antispam toggle` | *(ไม่มี)* | สลับเปิด/ปิดระบบ Anti-Spam ชั่วคราว | | `/antispam config` | `max_messages`<br>`time_window`<br>`duplicate_threshold`<br>`timeout_seconds`<br>`block_invites` | ปรับแต่งเกณฑ์ตรวจจับสแปมและเวลาลงโทษ | | `/antispam punishment` | `mode` *(timeout หรือ role)* | เลือกระบบการลงโทษ (Native Timeout หรือ Muted Role) | ### 📢 หมวดห้องบันทึกประวัติ (`/log`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/log set` | `channel` *(จำเป็น)* | กำหนดห้อง Text Channel สำหรับส่งแจ้งเตือนสแปม | | `/log disable` | *(ไม่มี)* | ปิดการส่ง Log ลงห้องแชท | ### ⚪ หมวดข้อยกเว้น (`/whitelist`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/whitelist add_role` | `role` *(จำเป็น)* | เพิ่มยศให้ได้รับการยกเว้นจากการตรวจจับ | | `/whitelist remove_role` | `role` *(จำเป็น)* | ลบยศออกจากรายการยกเว้น | | `/whitelist add_channel` | `channel` *(จำเป็น)* | เพิ่มห้องแชทให้ได้รับการยกเว้น | | `/whitelist remove_channel` | `channel` *(จำเป็น)* | ลบห้องแชทออกจากรายการยกเว้น | | `/whitelist list` | *(ไม่มี)* | แสดงรายการยศ ห้อง และผู้ใช้ที่ได้รับการยกเว้นทั้งหมด | ### 👑 หมวดผู้ดูแลระบบบอท (`/admin`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/admin add` | `member` *(จำเป็น)* | เพิ่มผู้ใช้ให้มีสิทธิ์ตั้งค่าและควบคุมบอทได้ | | `/admin remove` | `member` *(จำเป็น)* | ถอดสิทธิ์ผู้ดูแลบอท | | `/admin list` | *(ไม่มี)* | แสดงรายชื่อผู้ดูแลระบบบอททั้งหมด | ### 🧹 หมวดจัดการข้อความ & สมาชิก (`/clear`, `/timeout`) | คำสั่ง | พารามิเตอร์ | คำอธิบาย | |---|---|---| | `/clear messages` | `amount` *(1-100)*<br>`user` *(ไม่บังคับ)*<br>`bots_only` *(ไม่บังคับ)*<br>`contains` *(ไม่บังคับ)* | ลบข้อความในห้องแชทตามเงื่อนไขที่กำหนด | | `/clear user` | `member` *(จำเป็น)* | ค้นหาและลบข้อความเฉพาะของผู้ใช้ที่ระบุ | | `/clear all` | *(ไม่มี)* | ล้างข้อความล่าสุดทั้งหมดในห้องแชท | | `/timeout` | `member` *(จำเป็น)*<br>`duration` *(เช่น 60s, 5m, 1h)*<br>`reason` *(ไม่บังคับ)* | สั่ง Timeout สมาชิกด้วยตนเอง | | `/untimeout` | `member` *(จำเป็น)*<br>`reason` *(ไม่บังคับ)* | ปลดการ Timeout สมาชิก | ### ℹ️ หมวดทั่วไป (`/help`, `/ping`, `/stats`) | คำสั่ง | คำอธิบาย | |---|---| | `/help` | แสดงคู่มือสรุปคำสั่งและวิธีการใช้งานทั้งหมด | | `/ping` | ตรวจสอบ WebSocket Latency และเวลาตอบสนองของบอท | | `/stats` | ดูสถิติจำนวนสแปมที่สกัดกั้นได้ และเวลาเปิดทำงานต่อเนื่อง | --- ## 🔬 แผนผังการทำงานของระบบ (Architecture Overview) ``` [ ข้อความถูกส่งเข้ามาในเซิร์ฟเวอร์ ] │ ▼ [ 1. Whitelist & Permission Check ] ข้ามหากเป็นบอท, แอดมินเซิร์ฟเวอร์, ยศ/ห้อง/ผู้ใช้ที่อยู่ใน Whitelist │ (หากไม่ใช่ข้อยกเว้น) ▼ [ 2. Multi-Vector Spam Detection ] ├── ตรวจสอบลิงก์คำเชิญ Discord (Invite Regex) ├── ตรวจสอบการแท็กถี่ (Mass Mentions) ├── ตรวจสอบข้อความรัว (Sliding Window Rate Limit) └── ตรวจสอบข้อความซ้ำ (Duplicate Hasher) │ (หากพบสแปม) ▼ [ 3. Automated Enforcement Action ] ├── ลบข้อความสแปมทิ้งทันที (Delete Offending Message) ├── สั่งลงโทษ (Discord Native Timeout หรือ Muted Role) ├── ส่ง DM ตักเตือนผู้ใช้ (พร้อมระบบ Cooldown ป้องกัน Rate Limit) └── ส่งรายงาน Audit Log ไปยังห้องที่กำหนด ``` --- ## ⚙️ สิทธิ์ของบอทที่จำเป็น (Required Bot Permissions) เพื่อให้บอททำงานได้อย่างเต็มประสิทธิภาพ ควรให้สิทธิ์ดังนี้แก่ Role ของบอท: - **Moderate Members** *(จำเป็นอย่างยิ่งสำหรับคำสั่ง Timeout สมาชิก)* - **Manage Messages** *(จำเป็นสำหรับการลบข้อความสแปมและคำสั่ง /clear)* - **Manage Roles** *(กรณีต้องการใช้ระบบ Muted Role สำรอง)* - **Read Messages / View Channels** - **Send Messages & Embed Links** - **Read Message History** > ⚠️ **ข้อควรระวังเรื่องลำดับยศ (Role Hierarchy):** > ยศของบอทจะต้องอยู่**สูงกว่า**ยศของสมาชิกทั่วไป เพื่อให้สามารถ Timeout หรือจัดการยศของสมาชิกคนนั้นได้