[scarletkc]

Summary

The global spam_words.txt substring-matches common words such as ad, DM, 投资 and 充值, so it produces many false positives. Admins who only wanted the paid AI check could not get it without that list: /spam ai on required the /spam master switch, and the master switch always turns on the global list unless the group has custom keywords.

The AI check is now its own switch.

Behaviour

/spam master	/spam ai	What runs
on	on	Unchanged: link → mention → keywords → AI
on	off	Unchanged: link → mention → keywords
off	on	New: AI only. Links, mentions, custom keywords and the global list are skipped, even if their per-group flags are still set
off	off	Nothing (unchanged)

• /spam ai on|renew no longer requires the master switch. It still requires the bot's delete-messages right.
• Turning the master switch off no longer implies that everything has stopped. If the AI check is still running, the reply adds 「AI 识别不受影响，仍在运行；如需暂停，使用 /spam ai off。」
• Strikes are unchanged: an AI deletion still counts toward the 3-in-1-hour kick.

Cost

process_message now calls the new spam_ai.handlers.is_running(chat_id) before the admin lookup. That function wraps judge.is_configured() and the cached operations.is_checking. Groups with neither switch on still return before any get_chat_member call. Groups with the master switch on never call is_running on that early path.

Texts

• /spam ai status with the master switch off says that only AI runs. Its "service unavailable" and "daily limit" notes then say 「不检查消息」 instead of promising keyword filtering.
• The expiry reminder now reads 「本群的 AI 识别已到期，不再用 AI 检查消息。」 because the reminder job does not know the master state.
• /spam help, the plain-text help and resources/docs/spam.md say that AI can run on its own.

Not changed

• The global word list itself. I looked at GitHub candidates, and the only ready-made Chinese list (dkgks/tgforwarder) is old web-censorship vocabulary without Telegram ad terms. It was shelved.

Test plan

• uv run pytest -q: 1224 passed, 68 skipped
• uv run ruff check src tests
• New tests:
  • With the master switch off, a running AI check gets messages that the keyword, link and mention filters would have caught.
  • Admins are still skipped.
  • Groups with nothing on skip the admin lookup.
  • is_running gating.
  • The disabled-switch reply.
• Not tried in a real Telegram group yet: enable /spam ai on in a group with /spam off and check that a spam message is deleted with the warning and buttons

---