Default Implementation

Default Implementation

The default package contains OneBot V11 handlers that rely only on the standard OneBot V11 API surface. These handlers run on any OneBot V11 implementation (NapCat, Lagrange, etc.) without implementation-specific extensions.

Available commands

All commands listed in QQ Commands are available in the default implementation, except:

• 发送群公告 / send-announcement — gated by implementation version (see NapCat)
• 设置群头像 / set-group-avatar — gated by implementation version (see NapCat)
• 远程公告 / remote-announcement — gated by implementation version

Handler modules

Lifecycle operations

• 重启协议端 / restart-protocol-endpoint — requests protocol-side restart and confirms after reconnect.

Remote management

The remote.py module implements 8 cross-group commands unique to OneBot V11:

1. 远程禁言 / remote-mute
2. 远程解禁 / remote-unmute
3. 远程全体禁言 / remote-mute-all
4. 远程全体解禁 / remote-unmute-all
5. 远程踢出 / remote-kick (requires blocklist entry)
6. 远程拉黑 / remote-block
7. 远程删黑 / remote-unblock
8. 远程公告 / remote-announcement (version-gated)

Group ID resolution

All remote commands accept a group ID or group name, which can be:

• An int group ID — used directly.
• A str that parses as int — converted and used.
• A str that does not parse as int — fuzzy matched against get_group_list():
  1. Exact group_name match (first wins).
  2. Substring containment (group_id in group_name).
  3. Single match → resolved.
  4. Multiple matches → bot asks for a more precise name or group ID.
  5. No match → bot reports no matching group.

Context validation

Before executing a remote action, the bot checks:

1. The bot is a member of the target group (get_group_list).
2. The bot has admin/owner role in the target group (for most commands).
3. The target user is a member of the target group (for user-targeted commands).
4. The target is not the bot itself or the command sender.

Shared helpers

The recall command in mute.py stays on the standard OneBot V11 API surface: it verifies stored message IDs with get_msg before calling delete_msg.

common.py provides:

• resolve_user_onebot11(user, bot, event) — Resolves At | int to (user_id, name) tuple. Raises ValueError on invalid input.
• check_target_privilege(bot, event, target_user_id, cmd_matcher) — Checks protected targets first, allowing only repository-backed SUPERUSERS to bypass whitelist protection; then checks whether admin/owner targets can be managed by the operator. Returns True when the check passes.
• check_bot_privilege(bot, group_id, cmd_matcher) — Checks whether the bot has admin/owner role in the given group. Returns True when the check passes.
• CommandAudit(action, target_user_id=None, reason=None, duration=None, group_id=None) — Carries command audit payloads.
• record_command_audit(bot, event, CommandAudit(...)) / record_audit_fire_and_forget(bot, event, CommandAudit(...)) — Writes a command-level audit log entry via the message store repository, either awaited directly or scheduled in the background.

Permission API Integration

The permission system integrates with the OneBot V11 get_group_member_info API to actively verify user roles. When event.sender.role is missing, the system calls bot.call_api('get_group_member_info', group_id=..., user_id=...) to fetch the user's actual role. If the API call fails, the system falls back to the member role as a fail-safe measure.

Source reference

See handle/qq/adapters/onebot11/default/ in the repository.