v1.0: TelegramGuard - AI-powered group guardian with I-Lang Prompt Spec

- Anti-spam: AI + repeat message detection (3x in 5min = ban)
- Vision: image and video thumbnail understanding
- Chat: group @mention and private conversation
- Prompts: .ilang format (I-Lang Prompt Spec)
- Deploy: HF Space (free) or VPS
- GitHub Actions: auto-sync to HuggingFace

.github/workflows/sync-hf.yml

@@ -0,0 +1,21 @@
+name: Sync to HuggingFace Space
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to HuggingFace Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git remote add hf https://i-Lang:${HF_TOKEN}@huggingface.co/spaces/i-Lang/TelegramGuard || true
+          git push hf main --force

.gitignore

@@ -0,0 +1,10 @@
+prompts/
+data/
+__pycache__/
+*.pyc
+*.db
+*.db-journal
+*.db-wal
+*.log
+venv/
+.env

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p data
+
+CMD ["python", "bot.py"]

README.md

@@ -0,0 +1,78 @@
+# I-Lang Guard
+
+AI-powered Telegram group guardian. Anti-spam, vision, chat — all driven by [I-Lang Prompt Spec](https://github.com/ilang-ai/ilang-spec).
+
+## What It Does
+
+- **Anti-spam**: AI detects ads, scams, political content, porn, and repeat flooding. Deletes messages and bans spammers automatically.
+- **Vision**: Understands images and video thumbnails. Catches image-based spam too.
+- **Chat**: @ the bot in any group for AI conversation.
+- **Zero config**: Add to group → grant admin permissions → done.
+
+## Deploy Your Own (3 Steps)
+
+### Option A: HuggingFace Space (Free, Zero Server)
+
+1. Fork this repo
+2. Create a [HuggingFace Space](https://huggingface.co/new-space) (Docker SDK)
+3. Add secrets in Space Settings:
+
+| Secret | How to get it |
+|--------|--------------|
+| `BOT_TOKEN` | Talk to [@BotFather](https://t.me/BotFather) on Telegram |
+| `GEMINI_API_KEY` | Free at [aistudio.google.com](https://aistudio.google.com) |
+
+### Option B: VPS
+
+```bash
+git clone https://github.com/ilang-ai/TelegramGuard.git
+cd TelegramGuard
+pip install -r requirements.txt
+export BOT_TOKEN="your-token"
+export GEMINI_API_KEY="your-key"
+python bot.py
+```
+
+## Customize Your Bot
+
+All prompts live in `prompts_demo/` as `.ilang` files:
+
+| File | Controls |
+|------|----------|
+| `persona.ilang` | Bot personality, tone, rules |
+| `antispam.ilang` | What counts as spam |
+| `vision.ilang` | How to read images |
+
+To customize: copy `prompts_demo/` to `prompts/`, edit the `.ilang` files. The bot loads `prompts/` first, falls back to `prompts_demo/`.
+
+Prompts use [I-Lang Prompt Spec](https://github.com/ilang-ai/ilang-spec) — a structured format for AI instructions using GENE framework, IMMUNE rules, and layered architecture. Learn more at [ilang.ai](https://ilang.ai).
+
+## Architecture
+
+```
+bot.py              Main handler
+modules/
+  chat.py           AI calls (loads .ilang prompts)
+  db.py             Single shared SQLite connection
+  database.py       Schema
+  admin.py          Group admin helpers
+prompts_demo/       Open-source demo prompts (.ilang)
+prompts/            Your custom prompts (.gitignore'd)
+```
+
+## BotFather Setup
+
+After creating your bot, send these to [@BotFather](https://t.me/BotFather):
+
+```
+/setjoingroups → Enable
+/setprivacy → Disable (so bot can see all group messages)
+```
+
+## License
+
+MIT
+
+---
+
+Powered by [I-Lang Prompt Spec](https://ilang.ai) | [Eastsoft Inc.](https://eastsoft.com)

bot.py

@@ -0,0 +1,450 @@
+import logging
+import sys
+import os
+import time as _time
+import hashlib as _hashlib
+import asyncio
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
+from telegram.ext import (
+    Application, CommandHandler, MessageHandler,
+    CallbackQueryHandler, ChatMemberHandler, filters, ContextTypes
+)
+import config
+from modules.db import db_exec
+from modules.database import init_db
+from modules.chat import (
+    ai_text, ai_vision, ai_voice, ai_group_reply,
+    ai_judge_group_message, ai_judge_group_image, ai_group_vision,
+    GROUP_WELCOME
+)
+from modules.admin import is_admin, is_bot_admin, register_group
+
+logging.basicConfig(
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    level=logging.INFO
+)
+logger = logging.getLogger(__name__)
+
+TOS_TEXT = (
+    "I-Lang Guard 服务条款\n\n"
+    "为保障群组安全, 本Bot提供以下服务:\n"
+    "- 自动识别并清理垃圾广告\n"
+    "- 通过消息分析持续优化AI反spam能力\n\n"
+    "使用说明:\n"
+    "- Bot会分析群内消息用于反垃圾和AI模型优化\n"
+    "- 不存储个人身份信息\n"
+    "- 管理员可随时移除Bot终止服务\n\n"
+    "群管理员点击下方按钮即表示同意以上条款"
+)
+
+
+async def check_tos(chat_id):
+    async def _do(db):
+        cur = await db.execute("SELECT 1 FROM tos_consent WHERE chat_id=?", (chat_id,))
+        return await cur.fetchone() is not None
+    return await db_exec(_do)
+
+async def record_tos(chat_id, user_id):
+    async def _do(db):
+        await db.execute(
+            "INSERT OR REPLACE INTO tos_consent (chat_id, accepted_by) VALUES (?, ?)",
+            (chat_id, user_id)
+        )
+        await db.commit()
+    await db_exec(_do)
+
+async def delete_tos(chat_id):
+    async def _do(db):
+        await db.execute("DELETE FROM tos_consent WHERE chat_id=?", (chat_id,))
+        await db.commit()
+    await db_exec(_do)
+
+
+def _ctx_info(context):
+    parts = []
+    history = context.user_data.get("history", [])
+    if not history:
+        parts.append("NEW_SESSION:新对话开始,主动问好,问用户今天需要什么帮助")
+    return " | ".join(parts)
+
+
+async def _handle_ai_result(intent, device, reply, msg, user_id, context):
+    history = context.user_data.setdefault("history", [])
+    await msg.reply_text(reply)
+    history.append({"role": "assistant", "text": reply})
+    if len(history) > 20:
+        history[:] = history[-20:]
+
+
+# ==================== Commands ====================
+
+async def cmd_start(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    if not config.ADMIN_USER_ID:
+        config.ADMIN_USER_ID = update.effective_user.id
+    if update.effective_chat.type == "private":
+        context.user_data["history"] = []
+        intent, device, reply = await ai_text(
+            "/start",
+            history=None,
+            context_info="NEW_SESSION:用户刚打开对话,简短问好,介绍你能做什么"
+        )
+        await update.message.reply_text(reply)
+        context.user_data.setdefault("history", []).append({"role": "assistant", "text": reply})
+    else:
+        chat_id = update.effective_chat.id
+        await register_group(chat_id, update.effective_chat.title)
+        if not await check_tos(chat_id):
+            keyboard = InlineKeyboardMarkup([
+                [InlineKeyboardButton("同意并启用", callback_data="tos_accept_" + str(chat_id))],
+                [InlineKeyboardButton("不同意", callback_data="tos_decline_" + str(chat_id))]
+            ])
+            await update.message.reply_text(TOS_TEXT, reply_markup=keyboard)
+        else:
+            await update.message.reply_text(GROUP_WELCOME)
+
+
+async def cmd_help(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    if update.effective_chat.type == "private":
+        await update.message.reply_text(
+            "直接跟我说话就行, 不用命令\n\n"
+            "群管理 → 拉我进群, 给管理员权限\n"
+            "其他 → 随便聊"
+        )
+    else:
+        await update.message.reply_text(
+            "我在群里自动工作, 不用配置\n\n管理员命令:\n/ban — 回复消息踢人"
+        )
+
+
+async def cmd_ban(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    if update.effective_chat.type == "private" or not update.message.reply_to_message:
+        return
+    if not await is_admin(update, context):
+        return
+    try:
+        t = update.message.reply_to_message.from_user
+        await context.bot.ban_chat_member(update.effective_chat.id, t.id)
+        await update.message.reply_text("done")
+    except Exception as e:
+        await update.message.reply_text(str(e))
+
+
+# ==================== Group ====================
+
+async def handle_group_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    msg = update.message
+    if not msg:
+        return
+    chat_id = msg.chat.id
+    user = msg.from_user
+    if not user:
+        return
+    text = msg.text or msg.caption or ""
+
+    await register_group(chat_id, msg.chat.title)
+
+    tos_ok = await check_tos(chat_id)
+
+    # @mention or reply to bot
+    is_mention = text and context.bot.username and ("@" + context.bot.username) in text
+    is_reply_to_bot = msg.reply_to_message and msg.reply_to_message.from_user and msg.reply_to_message.from_user.id == context.bot.id
+    has_media = bool(msg.photo or msg.video or msg.document)
+    if (text or has_media) and (is_mention or is_reply_to_bot):
+        clean = text.replace("@" + context.bot.username, "").strip() if (text and is_mention) else (text.strip() if text else "")
+        if not tos_ok:
+            reply = "我还没被启用哦, 请管理员点一下上面的「同意并启用」按钮"
+        else:
+            g_history = context.chat_data.setdefault("group_history", [])
+            if msg.photo:
+                try:
+                    f = await context.bot.get_file(msg.photo[-1].file_id)
+                    img_data = bytes(await f.download_as_bytearray())
+                    reply = await ai_group_vision(img_data, caption=clean, history=g_history)
+                except Exception:
+                    reply = "图片没看清, 再发一张?"
+            elif msg.video:
+                if msg.video.thumbnail:
+                    try:
+                        vf = await context.bot.get_file(msg.video.thumbnail.file_id)
+                        vimg = bytes(await vf.download_as_bytearray())
+                        reply = await ai_group_vision(vimg, caption=clean, history=g_history)
+                    except Exception:
+                        if clean:
+                            g_history.append({"role": "user", "text": "[视频] " + clean})
+                            reply = await ai_group_reply("[视频] " + clean, g_history)
+                        else:
+                            reply = "视频封面没看清, 说说是什么内容?"
+                elif clean:
+                    g_history.append({"role": "user", "text": "[视频] " + clean})
+                    reply = await ai_group_reply("[视频] " + clean, g_history)
+                else:
+                    reply = "视频我看不了, 说说是什么内容?"
+            else:
+                g_history.append({"role": "user", "text": clean})
+                reply = await ai_group_reply(clean, g_history)
+            g_history.append({"role": "assistant", "text": reply})
+            if len(g_history) > 20:
+                g_history[:] = g_history[-20:]
+        await msg.reply_text(reply)
+        return
+
+    if not tos_ok:
+        return
+
+    # Admin check
+    is_admin_user = False
+    try:
+        member = await context.bot.get_chat_member(chat_id, user.id)
+        if member.status in ("administrator", "creator"):
+            is_admin_user = True
+    except Exception:
+        pass
+
+    # Track recent messages: (msg_id, content_hash, timestamp)
+    user_msgs = context.chat_data.setdefault("user_recent_msgs", {})
+    uid = user.id
+    if uid not in user_msgs:
+        user_msgs[uid] = []
+    content_hash = _hashlib.md5(text.encode()).hexdigest() if text else ""
+    now = _time.time()
+    user_msgs[uid].append((msg.message_id, content_hash, now))
+    if len(user_msgs[uid]) > 20:
+        user_msgs[uid] = user_msgs[uid][-20:]
+
+    # Admin bypass
+    if is_admin_user:
+        return
+
+    # Duplicate message detection
+    spam = False
+    if content_hash:
+        recent_same = [
+            e for e in user_msgs[uid]
+            if e[1] == content_hash and (now - e[2]) < config.SPAM_REPEAT_WINDOW
+        ]
+        if len(recent_same) >= config.SPAM_REPEAT_THRESHOLD:
+            spam = True
+            logger.info("REPEAT SPAM: user=" + str(uid) + " chat=" + str(chat_id) + " count=" + str(len(recent_same)))
+
+    # AI spam check (skip if already caught)
+    if not spam:
+        if msg.photo:
+            try:
+                f = await context.bot.get_file(msg.photo[-1].file_id)
+                data = bytes(await f.download_as_bytearray())
+                spam = await ai_judge_group_image(data, text)
+            except Exception:
+                if text:
+                    spam = await ai_judge_group_message(text)
+        elif msg.video:
+            if msg.video.thumbnail:
+                try:
+                    vf = await context.bot.get_file(msg.video.thumbnail.file_id)
+                    vdata = bytes(await vf.download_as_bytearray())
+                    spam = await ai_judge_group_image(vdata, text)
+                except Exception:
+                    if text:
+                        spam = await ai_judge_group_message(text)
+            elif text:
+                spam = await ai_judge_group_message(text)
+            elif msg.forward_date:
+                spam = True
+        elif msg.document or msg.sticker:
+            if text:
+                spam = await ai_judge_group_message(text)
+            elif msg.forward_date:
+                spam = True
+        elif text:
+            spam = await ai_judge_group_message(text)
+
+    if spam:
+        try:
+            tasks = []
+            for entry in user_msgs.get(uid, []):
+                mid = entry[0] if isinstance(entry, tuple) else entry
+                tasks.append(context.bot.delete_message(chat_id, mid))
+            tasks.append(context.bot.ban_chat_member(chat_id, uid))
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            user_msgs.pop(uid, None)
+            logger.info("SPAM nuked: user=" + str(uid) + " chat=" + str(chat_id) + " tasks=" + str(len(tasks)))
+        except Exception as e:
+            logger.warning("Anti-spam action failed: " + str(e))
+            last_remind = context.bot_data.get("perm_remind_" + str(chat_id), 0)
+            if _time.time() - last_remind > 3600:
+                context.bot_data["perm_remind_" + str(chat_id)] = _time.time()
+                try:
+                    await msg.reply_text(
+                        "\u26a0\ufe0f 发现垃圾消息但我没权限处理\n\n"
+                        "点群名字 → 管理员 → 添加管理员 → 找到我 → 打开「删除消息」和「封禁用户」→ 完成"
+                    )
+                except Exception:
+                    pass
+        return
+
+
+# ==================== Private ====================
+
+async def handle_private_text(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    msg = update.message
+    if not msg or not msg.text:
+        return
+    user_id = msg.from_user.id
+    history = context.user_data.setdefault("history", [])
+    history.append({"role": "user", "text": msg.text})
+    intent, device, reply = await ai_text(msg.text, history, _ctx_info(context))
+    await _handle_ai_result(intent, device, reply, msg, user_id, context)
+
+
+async def handle_private_photo(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    msg = update.message
+    if not msg or not msg.photo:
+        return
+    user_id = msg.from_user.id
+    history = context.user_data.setdefault("history", [])
+    caption = msg.caption or ""
+    history.append({"role": "user", "text": "[photo] " + caption if caption else "[photo]"})
+    try:
+        file = await context.bot.get_file(msg.photo[-1].file_id)
+        img_bytes = bytes(await file.download_as_bytearray())
+    except Exception:
+        await msg.reply_text("图片没收到, 再发一次?")
+        return
+    intent, device, reply = await ai_vision(img_bytes, caption, history, _ctx_info(context))
+    await _handle_ai_result(intent, device, reply, msg, user_id, context)
+
+
+async def handle_private_voice(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    msg = update.message
+    if not msg or not msg.voice:
+        return
+    user_id = msg.from_user.id
+    history = context.user_data.setdefault("history", [])
+    history.append({"role": "user", "text": "[voice]"})
+    try:
+        file = await context.bot.get_file(msg.voice.file_id)
+        audio_bytes = bytes(await file.download_as_bytearray())
+        mime = msg.voice.mime_type or "audio/ogg"
+    except Exception:
+        await msg.reply_text("语音没收到, 再说一次或者打字也行")
+        return
+    intent, device, reply = await ai_voice(audio_bytes, mime, history, _ctx_info(context))
+    await _handle_ai_result(intent, device, reply, msg, user_id, context)
+
+
+# ==================== Events ====================
+
+async def handle_my_chat_member(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    result = update.my_chat_member
+    if not result:
+        return
+    chat_id = result.chat.id
+    old = result.old_chat_member.status if result.old_chat_member else "left"
+    new = result.new_chat_member.status if result.new_chat_member else "left"
+
+    if old in ("left", "kicked") and new in ("member", "administrator"):
+        await delete_tos(chat_id)
+        await register_group(chat_id, result.chat.title)
+        keyboard = InlineKeyboardMarkup([
+            [InlineKeyboardButton("同意并启用", callback_data="tos_accept_" + str(chat_id))],
+            [InlineKeyboardButton("不同意", callback_data="tos_decline_" + str(chat_id))]
+        ])
+        await context.bot.send_message(chat_id, TOS_TEXT, reply_markup=keyboard)
+    elif old in ("member", "administrator") and new in ("left", "kicked"):
+        await delete_tos(chat_id)
+
+
+async def handle_tos_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
+    query = update.callback_query
+    if not query or not query.data:
+        return
+
+    is_accept = query.data.startswith("tos_accept_")
+    is_decline = query.data.startswith("tos_decline_")
+    if not is_accept and not is_decline:
+        return
+
+    chat_id = query.message.chat.id
+    user_id = query.from_user.id
+
+    try:
+        admins = await context.bot.get_chat_administrators(chat_id)
+        admin_ids = [a.user.id for a in admins]
+        if user_id not in admin_ids:
+            await query.answer("只有管理员可以操作", show_alert=True)
+            return
+    except Exception:
+        pass
+
+    if is_accept:
+        await record_tos(chat_id, user_id)
+        await query.answer("已启用")
+        has_perms = False
+        try:
+            bot_member = await context.bot.get_chat_member(chat_id, context.bot.id)
+            if hasattr(bot_member, 'can_delete_messages') and bot_member.can_delete_messages and hasattr(bot_member, 'can_restrict_members') and bot_member.can_restrict_members:
+                has_perms = True
+        except Exception:
+            pass
+
+        if has_perms:
+            await query.edit_message_text("I-Lang Guard 已启用 ✅\n\n垃圾广告我来清理, 全自动")
+        else:
+            await query.edit_message_text(
+                "I-Lang Guard 已启用\n\n"
+                "⚠️ 我还需要管理员权限才能干活:\n\n"
+                "1. 点群名字进入群资料\n"
+                "2. 点「管理员」\n"
+                "3. 点「添加管理员」\n"
+                "4. 找到 I-Lang Guard 点它\n"
+                "5. 打开「删除消息」和「封禁用户」\n"
+                "6. 点右上角「完成」"
+            )
+    else:
+        await query.answer("好的, 再见")
+        await query.edit_message_text("已退出群组")
+        await context.bot.leave_chat(chat_id)
+
+
+# ==================== Main ====================
+
+def main():
+    # Ensure data directory exists
+    os.makedirs(os.path.dirname(config.DB_PATH) or "data", exist_ok=True)
+
+    app = Application.builder().token(config.BOT_TOKEN).build()
+
+    for cmd, fn in [
+        ("start", cmd_start), ("help", cmd_help), ("ban", cmd_ban),
+    ]:
+        app.add_handler(CommandHandler(cmd, fn))
+
+    app.add_handler(ChatMemberHandler(handle_my_chat_member, ChatMemberHandler.MY_CHAT_MEMBER))
+    app.add_handler(CallbackQueryHandler(handle_tos_callback, pattern="^tos_"))
+
+    # Group
+    app.add_handler(MessageHandler(
+        (filters.TEXT | filters.PHOTO | filters.VIDEO | filters.Document.ALL | filters.Sticker.ALL) & filters.ChatType.GROUPS & ~filters.COMMAND,
+        handle_group_message
+    ))
+
+    # Private
+    app.add_handler(MessageHandler(filters.TEXT & filters.ChatType.PRIVATE & ~filters.COMMAND, handle_private_text))
+    app.add_handler(MessageHandler(filters.PHOTO & filters.ChatType.PRIVATE, handle_private_photo))
+    app.add_handler(MessageHandler(filters.VOICE & filters.ChatType.PRIVATE, handle_private_voice))
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    loop.run_until_complete(init_db())
+
+    logger.info("I-Lang Guard starting...")
+    app.run_polling(
+        drop_pending_updates=True,
+        allowed_updates=["message", "callback_query", "my_chat_member"]
+    )
+
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,19 @@
+import os
+
+# Telegram Bot
+BOT_TOKEN = os.environ.get("BOT_TOKEN", "")
+
+# Gemini AI
+GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY", "")
+GEMINI_MODEL = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash")
+
+# Database
+DB_PATH = os.environ.get("DB_PATH", "data/bot.db")
+
+# Anti-spam
+SPAM_NEWUSER_COOLDOWN = int(os.environ.get("SPAM_NEWUSER_COOLDOWN", "300"))
+SPAM_REPEAT_THRESHOLD = int(os.environ.get("SPAM_REPEAT_THRESHOLD", "3"))
+SPAM_REPEAT_WINDOW = int(os.environ.get("SPAM_REPEAT_WINDOW", "300"))
+
+# Admin user ID (auto-detected from first /start)
+ADMIN_USER_ID = None

modules/admin.py

@@ -0,0 +1,24 @@
+import config
+from modules.db import db_exec
+
+async def is_admin(update, context):
+    try:
+        chat_id = update.effective_chat.id
+        user_id = update.effective_user.id
+        member = await context.bot.get_chat_member(chat_id, user_id)
+        return member.status in ("administrator", "creator")
+    except Exception:
+        return False
+
+def is_bot_admin(user_id):
+    return config.ADMIN_USER_ID and user_id == config.ADMIN_USER_ID
+
+async def register_group(chat_id, title):
+    async def _do(db):
+        await db.execute(
+            "INSERT INTO groups (chat_id, title) VALUES (?, ?) "
+            "ON CONFLICT(chat_id) DO UPDATE SET title=?",
+            (chat_id, title, title)
+        )
+        await db.commit()
+    await db_exec(_do)

modules/chat.py

@@ -0,0 +1,180 @@
+import json
+import logging
+import random
+import os
+import google.generativeai as genai
+import config
+
+logger = logging.getLogger(__name__)
+
+genai.configure(api_key=config.GEMINI_API_KEY)
+
+# Load prompts from .ilang files (prompts/ if exists, else prompts_demo/)
+def _load_prompt(name):
+    for d in ("prompts", "prompts_demo"):
+        path = os.path.join(os.path.dirname(os.path.dirname(__file__)), d, name)
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as f:
+                return f.read()
+    return ""
+
+SYSTEM_PROMPT = _load_prompt("persona.ilang")
+ANTISPAM_TEXT_PROMPT = _load_prompt("antispam.ilang")
+VISION_PROMPT = _load_prompt("vision.ilang")
+
+GROUP_WELCOME = (
+    "I-Lang Guard 来了\n\n"
+    "垃圾广告我来清理, 全自动, 不用配置\n"
+    "有问题可以 @我\n\n"
+    "给我管理员权限(删消息+封人)就行, 其他不用管"
+)
+
+model = genai.GenerativeModel(config.GEMINI_MODEL, system_instruction=SYSTEM_PROMPT)
+vision_model = genai.GenerativeModel(config.GEMINI_MODEL)
+
+
+def _parse(raw):
+    if not raw:
+        return ("chat", None, "...")
+    t = raw.strip()
+    if t.startswith("```"):
+        nl = t.find("\n")
+        t = t[nl + 1:] if nl > 0 else t[3:]
+    if t.endswith("```"):
+        t = t[:-3].strip()
+    try:
+        d = json.loads(t)
+        return (d.get("intent", "chat"), d.get("device"), d.get("reply", t))
+    except json.JSONDecodeError:
+        pass
+    last_brace = t.rfind("}")
+    while last_brace >= 0:
+        start = t.rfind("{", 0, last_brace)
+        if start >= 0:
+            try:
+                d = json.loads(t[start:last_brace + 1])
+                return (d.get("intent", "chat"), d.get("device"), d.get("reply", t))
+            except json.JSONDecodeError:
+                pass
+        last_brace = t.rfind("}", 0, last_brace)
+    for line in t.split("\n"):
+        line = line.strip()
+        if line and not line.startswith("{") and not line.startswith("taint") and not line.startswith("The "):
+            return ("chat", None, line)
+    return ("chat", None, "...")
+
+
+def _ctx(history, info):
+    parts = []
+    if info:
+        parts.append("[ctx] " + info)
+    if history:
+        for h in history[-8:]:
+            r = "user" if h["role"] == "user" else "bot"
+            parts.append(r + ": " + h["text"])
+    return "\n".join(parts)
+
+
+def _deflect():
+    lines = [
+        "这个话题不太方便聊, 换一个吧",
+        "换个话题? 你今天有什么需要帮忙的?",
+        "这个超纲了, 聊点别的吧",
+    ]
+    return random.choice(lines)
+
+
+async def ai_text(text, history=None, context_info=""):
+    try:
+        c = _ctx(history, context_info)
+        prompt = c + "\nuser: " + text if c else "user: " + text
+        r = await model.generate_content_async(prompt)
+        raw = r.text.strip() if r.text else ""
+        if not raw:
+            return ("chat", None, _deflect())
+        return _parse(raw)
+    except Exception as e:
+        logger.warning("AI text: " + str(e))
+        return ("chat", None, _deflect())
+
+
+async def ai_vision(image_bytes, caption="", history=None, context_info=""):
+    try:
+        c = _ctx(history, context_info)
+        prompt = VISION_PROMPT + "\n" + c
+        if caption:
+            prompt += "\nuser: " + caption
+        r = await vision_model.generate_content_async([prompt, {"mime_type": "image/jpeg", "data": image_bytes}])
+        return _parse(r.text if r.text else "")
+    except Exception as e:
+        logger.warning("AI vision: " + str(e))
+        return ("chat", None, "图片没看清, 再发一张?")
+
+
+async def ai_voice(audio_bytes, mime_type="audio/ogg", history=None, context_info=""):
+    try:
+        c = _ctx(history, context_info)
+        prompt = SYSTEM_PROMPT + "\n" + c + "\nUser sent a voice message:"
+        r = await vision_model.generate_content_async([prompt, {"mime_type": mime_type, "data": audio_bytes}])
+        return _parse(r.text if r.text else "")
+    except Exception as e:
+        logger.warning("AI voice: " + str(e))
+        return ("chat", None, "语音没听清, 再说一次或者打字都行")
+
+
+async def ai_judge_group_message(text):
+    try:
+        prompt = ANTISPAM_TEXT_PROMPT + "\n\n消息内容: " + text[:1000]
+        r = await vision_model.generate_content_async(prompt)
+        result = r.text.strip().lower() if r.text else "ok"
+        return "spam" in result
+    except Exception:
+        return False
+
+
+async def ai_judge_group_image(image_bytes, caption=""):
+    try:
+        prompt = ANTISPAM_TEXT_PROMPT + "\n\n判断这张图片是否是spam。只回复 spam 或 ok。"
+        if caption:
+            prompt += "\nCaption: " + caption[:500]
+        r = await vision_model.generate_content_async([prompt, {"mime_type": "image/jpeg", "data": image_bytes}])
+        result = r.text.strip().lower() if r.text else "ok"
+        return "spam" in result
+    except Exception:
+        return False
+
+
+async def ai_group_vision(image_bytes, caption="", history=None):
+    try:
+        ctx = _ctx(history, "GROUP_CHAT: 用户在群里发了张图片@你, 简短评论1-2句话")
+        prompt = SYSTEM_PROMPT + "\n" + ctx
+        if caption:
+            prompt += "\nuser: " + caption
+        else:
+            prompt += "\nuser: [发了张图片]"
+        r = await vision_model.generate_content_async([prompt, {"mime_type": "image/jpeg", "data": image_bytes}])
+        raw = r.text.strip() if r.text else ""
+        if not raw:
+            return _deflect()
+        intent, device, reply = _parse(raw)
+        if reply in ("...", ""):
+            return _deflect()
+        return reply
+    except Exception:
+        return _deflect()
+
+
+async def ai_group_reply(text, history=None):
+    try:
+        ctx = _ctx(history, "GROUP_CHAT: 你在群里被@了, 直接回答, 简短2句话")
+        prompt = ctx + "\nuser: " + text
+        r = await model.generate_content_async(prompt)
+        raw = r.text.strip() if r.text else ""
+        if not raw:
+            return _deflect()
+        intent, device, reply = _parse(raw)
+        if reply in ("...", ""):
+            return _deflect()
+        return reply
+    except Exception:
+        return _deflect()

modules/database.py

@@ -0,0 +1,39 @@
+from modules.db import shared_db
+
+async def init_db():
+    async with shared_db() as db:
+        await db.executescript("""
+            CREATE TABLE IF NOT EXISTS groups (
+                chat_id INTEGER PRIMARY KEY,
+                title TEXT,
+                antispam_on INTEGER DEFAULT 1,
+                added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            CREATE TABLE IF NOT EXISTS spam_log (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                chat_id INTEGER,
+                user_id INTEGER,
+                username TEXT,
+                message TEXT,
+                action TEXT,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            CREATE TABLE IF NOT EXISTS user_strikes (
+                chat_id INTEGER,
+                user_id INTEGER,
+                strikes INTEGER DEFAULT 0,
+                PRIMARY KEY (chat_id, user_id)
+            );
+            CREATE TABLE IF NOT EXISTS new_members (
+                chat_id INTEGER,
+                user_id INTEGER,
+                joined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (chat_id, user_id)
+            );
+            CREATE TABLE IF NOT EXISTS tos_consent (
+                chat_id INTEGER PRIMARY KEY,
+                accepted_by INTEGER,
+                accepted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+        """)
+        await db.commit()

modules/db.py

@@ -0,0 +1,29 @@
+import aiosqlite
+import asyncio
+import config
+
+_db = None
+_db_lock = asyncio.Lock()
+
+async def get_db():
+    global _db
+    if _db is None:
+        _db = await aiosqlite.connect(config.DB_PATH)
+        await _db.execute("PRAGMA journal_mode=WAL")
+        await _db.execute("PRAGMA busy_timeout=10000")
+        await _db.commit()
+    return _db
+
+async def db_exec(func):
+    async with _db_lock:
+        return await func(await get_db())
+
+class SharedDB:
+    async def __aenter__(self):
+        await _db_lock.acquire()
+        return await get_db()
+    async def __aexit__(self, *args):
+        _db_lock.release()
+
+def shared_db():
+    return SharedDB()

prompts_demo/antispam.ilang

@@ -0,0 +1,54 @@
+# ::ILANG:GENE:ANTISPAM::v1.0::
+# ::SCOPE{PUBLIC|OPEN_SOURCE}::
+# ::PURPOSE{TelegramGuard spam detection rules}::
+
+# --------------------------------------------------------
+# Learn I-Lang Prompt Spec: https://github.com/ilang-ai/ilang-spec
+# --------------------------------------------------------
+
+::GENE_IMMUTABLE{001, T:JUDGE_BEHAVIOR, A:JUDGE_CONTENT_ONLY⇒MISS_SPAM, G:ALL, Θ:ALWAYS}
+::GENE_IMMUTABLE{002, T:THREE_STEP_ANALYSIS, A:SHALLOW_SCAN⇒FALSE_NEGATIVE, G:ALL, Θ:ALWAYS}
+::GENE_IMMUTABLE{003, T:SEE_THROUGH_TRICKS, A:LITERAL_READ⇒EVASION, G:ALL, Θ:ALWAYS}
+
+::IMMUNE{UNICODE_VARIANT, DETECT}
+::IMMUNE{EMOJI_STUFFING, DETECT}
+::IMMUNE{VERTICAL_SPLIT, DETECT}
+::IMMUNE{HOMOPHONE_REPLACE, DETECT}
+
+# --------------------------------------------------------
+# TEXT SPAM JUDGE
+# --------------------------------------------------------
+
+You are a Telegram group anti-spam expert. Use three-step analysis:
+
+Step 1: Surface read — what does this message say?
+Step 2: Deep read — what is the real intent? Who sends messages like this? Would a normal group member talk this way?
+Step 3: Judge based on patterns:
+- Below-market goods + invoice + contact info = black market
+- Forwarded from channel + contact/link = ad spam
+- Earning/income/part-time + contact = scam
+- Crypto/airdrop + link = crypto scam
+- Sexual content/hookup = sexual spam
+- Gambling/lottery = gambling spam
+- Normal chat/question/complaint/emoji/reply = OK
+
+Watch for evasion tricks:
+- Unicode variants, fullwidth chars, Cyrillic lookalikes
+- Emoji-stuffed text
+- Vertical/split text
+- Homophones and pinyin substitution
+
+Reply only: spam or ok
+
+# --------------------------------------------------------
+# IMAGE SPAM JUDGE
+# --------------------------------------------------------
+
+For images, judge:
+- Ad poster/QR code/contact info/price list = spam
+- Scam screenshot/fake earnings = spam
+- Sexual or explicit content = spam
+- Political propaganda = spam
+- Normal chat screenshot/meme/daily photo = ok
+
+Reply only: spam or ok

prompts_demo/persona.ilang

@@ -0,0 +1,41 @@
+# ::ILANG:GENE:PERSONA::v1.0::
+# ::SCOPE{PUBLIC|OPEN_SOURCE}::
+# ::PURPOSE{TelegramGuard default personality}::
+# ::CUSTOMIZE{fork and edit to create your own bot personality}::
+
+# --------------------------------------------------------
+# Learn I-Lang Prompt Spec: https://github.com/ilang-ai/ilang-spec
+# --------------------------------------------------------
+
+::GENE_IMMUTABLE{001, T:HELPFUL, A:IGNORE_USER⇒BROKEN, G:ALL, Θ:ALWAYS}
+::GENE_IMMUTABLE{002, T:SAFE_REPLY, A:OUTPUT_HARMFUL⇒SHUTDOWN, G:ALL, Θ:ALWAYS}
+::GENE_IMMUTABLE{003, T:CHINESE_FIRST, A:WRONG_LANG⇒SWITCH, G:ALL, Θ:DETECT_LANG}
+::GENE_IMMUTABLE{004, T:CONCISE, A:VERBOSE⇒TRIM, G:ALL, Θ:ALWAYS}
+
+::GENE_MUTABLE{101, T:FRIENDLY, G:ALL, Θ:BASE}
+::GENE_MUTABLE{102, T:TONE_ADAPTIVE, G:adaptive, Θ:INTERLOCUTOR}
+
+::IMMUNE{POLITICS, DEFLECT}
+::IMMUNE{ILLEGAL_CONTENT, REFUSE}
+
+# --------------------------------------------------------
+# PERSONA DEFINITION
+# --------------------------------------------------------
+
+You are TelegramGuard, a friendly AI assistant in Telegram.
+Reply in Chinese by default. Keep replies to 2-3 sentences.
+
+Your capabilities:
+1. Group management: auto spam detection and cleanup
+2. AI chat: answer questions, casual conversation
+3. Vision: understand images sent to you
+
+Rules:
+- Never discuss politics: reply with "这个话题不聊, 换一个吧"
+- Never recommend paid services
+- Never fabricate links
+
+Response format (JSON):
+{"intent": "chat", "device": null, "reply": "your reply text"}
+
+intent options: chat | need_help | feedback

prompts_demo/vision.ilang

@@ -0,0 +1,35 @@
+# ::ILANG:GENE:VISION::v1.0::
+# ::SCOPE{PUBLIC|OPEN_SOURCE}::
+# ::PURPOSE{TelegramGuard image understanding}::
+
+# --------------------------------------------------------
+# Learn I-Lang Prompt Spec: https://github.com/ilang-ai/ilang-spec
+# --------------------------------------------------------
+
+::GENE_IMMUTABLE{001, T:OBSERVE_ALL, A:SKIP_DETAIL⇒MISS_CONTEXT, G:ALL, Θ:ALWAYS}
+::GENE_IMMUTABLE{002, T:DESCRIBE_CONCISE, A:VERBOSE⇒TRIM, G:ALL, Θ:ALWAYS}
+
+# --------------------------------------------------------
+# GROUP VISION
+# --------------------------------------------------------
+
+You are looking at an image shared in a Telegram group.
+Describe what you see briefly in Chinese, 1-2 sentences.
+Be natural, like a friend commenting on a photo.
+
+Response format (JSON):
+{"intent": "chat", "device": null, "reply": "your description"}
+
+# --------------------------------------------------------
+# TECH VISION
+# --------------------------------------------------------
+
+You are looking at a user's screenshot or photo in private chat.
+Based on this image:
+1. What device/OS/app is shown?
+2. What is the user trying to do?
+3. Give ONE next action in Chinese, 2-3 sentences.
+
+Response format (JSON):
+{"intent": "chat", "device": null, "reply": "your guidance"}
+device options: "ios" | "android" | "windows" | "mac" | null

requirements.txt

@@ -0,0 +1,3 @@
+python-telegram-bot[job-queue]>=21.0
+google-generativeai>=0.8.0
+aiosqlite>=0.20.0