feat(gateway/feishu): skip @mention gate for small groups with configurable require_mention

[songlairui]

What does this PR do?

Feishu group chats where only one human and the bot are present should behave like a DM — requiring an explicit @mention before every message is unnecessary friction. This PR adds a three-tier mention-gate bypass for the Feishu adapter.

Related Issue

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

gateway/platforms/feishu.py

• FeishuGroupRule: add require_mention: Optional[bool] = None — per-group override, None inherits global
• FeishuAdapterSettings: add require_mention: bool = True — global default
• _load_settings(): parse FEISHU_REQUIRE_MENTION env var and per-group require_mention key from config
• _apply_settings(): store self._require_mention
• get_chat_info(): extract and cache member_count from im.v1.chat.get API response
• _handle_message_event_data(): pre-fetch chat_info (cached) for group messages to obtain member_count
• _should_accept_group_message(): new member_count parameter + three-tier logic

tests/gateway/test_feishu.py

• 10 new test cases in TestRequireMentionConfig

Mention Gate Priority (highest wins)

Priority	Condition	Effect
1	group_rules.<chat_id>.require_mention: false/true	Per-group explicit override
2	FEISHU_REQUIRE_MENTION=false env var (or config key)	Global disable
3	member_count <= 2 auto-detection	Small group = DM-like, skip @mention
4	Default	Require @mention

No Duplicate Replies

When member_count <= 2 and the user also @mentions the bot explicitly, the small-group branch short-circuits and returns True immediately — the @mention check is never reached. Combined with the existing _is_duplicate(message_id) dedup, each message is processed exactly once regardless.

How to Test

Config flag (manual):

# ~/.hermes/config.yaml  (or via env)
# FEISHU_REQUIRE_MENTION=false   ← disables globally
platforms:
  feishu:
    extra:
      group_rules:
        "oc_your_chat_id":
          policy: open
          require_mention: false   # ← this chat only

Auto-detection: Add the Feishu bot to a group with only yourself. Send a message without @mentioning it — it should respond.

Unit tests:

pytest tests/gateway/test_feishu.py::TestRequireMentionConfig -v

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature
• I've run pytest tests/gateway/test_feishu.py -q and all relevant tests pass
• I've added tests for my changes (10 new cases)
• I've tested on my platform: macOS 25.3.0

Documentation & Housekeeping

• I've updated relevant documentation — N/A (cli-config.yaml.example has no Feishu section; env var is documented in the commit message and PR body)
• I've updated cli-config.yaml.example — N/A (no Feishu config exists in the example file)
• I've updated CONTRIBUTING.md or AGENTS.md — N/A
• I've considered cross-platform impact — N/A (pure Python, no OS-specific code)
• I've updated tool descriptions/schemas — N/A (gateway adapter, not a tool)

Notes

One pre-existing test failure unrelated to this PR:
TestAdapterBehavior::test_build_event_handler_registers_reaction_and_card_processors — fails due to a lark_oapi SDK version mismatch ('_Builder' object has no attribute 'register_p2_im_chat_member_bot_added_v1'). This failure exists on main before this PR.

[alt-glitch]

Multiple competing PRs for Feishu require_mention: #12411, #9479, #5219, #7546. This one adds auto-detection for small groups on top of the basic toggle.

[teknium1]

Thanks for the small-group usability proposal. The global and per-chat controls in this PR are already present on current main via b94cb8e2: plugins/platforms/feishu/adapter.py:1600 resolves FEISHU_REQUIRE_MENTION, and :4278 resolves a per-group override.

Problems

• The submitted implementation targets gateway/platforms/feishu.py, but 560010547 moved the adapter to plugins/platforms/feishu/adapter.py. Current inbound admission is _handle_message_event_data() → _admit() (plugins/platforms/feishu/adapter.py:2522, :4231), so _should_accept_group_message() is no longer the integration point.
• The member-count portion needs a cache-freshness design. get_chat_info() currently returns cached metadata at plugins/platforms/feishu/adapter.py:2353; current invalidation only covers bot-added and bot-removed events (:2558-2570). A cached count of two could otherwise continue bypassing the mention gate after another human joins.

Suggested changes

• Re-scope the salvage to the still-missing member-count bypass in the plugin adapter, feeding it through the current _admit() flow while retaining its bot and group-policy checks.
• Add coverage for membership changing from two to three and verify the mention gate becomes active again.

Automated hermes-sweeper review.