bub-qq 0.0.1__py3-none-any.whl

bub_qq/__init__.py

@@ -0,0 +1,37 @@
+"""QQ Open Platform channel for Bub.
+
+Package layout:
+
+- ``protocol``: auth, OpenAPI client, signatures, and event models
+- ``gateway``: webhook / websocket receive transports
+- ``inbound``: QQ events adapted to Bub ``ChannelMessage``
+- ``outbound``: Bub messages delivered through QQ OpenAPI
+"""
+
+from __future__ import annotations
+
+from .channel import QQChannel
+from .config import QQConfig
+from .gateway import QQGatewayInfo
+from .gateway import QQSessionStartLimit
+from .gateway import QQWebhookServer
+from .gateway import QQWebSocketClient
+from .protocol import QQC2CMessage
+from .protocol import QQGroupMessage
+from .protocol import QQOpenAPI
+from .protocol import QQOpenAPIError
+from .protocol import QQTokenProvider
+
+__all__ = [
+    "QQChannel",
+    "QQConfig",
+    "QQGatewayInfo",
+    "QQOpenAPI",
+    "QQOpenAPIError",
+    "QQSessionStartLimit",
+    "QQTokenProvider",
+    "QQWebhookServer",
+    "QQWebSocketClient",
+    "QQC2CMessage",
+    "QQGroupMessage",
+]

bub_qq/channel.py

@@ -0,0 +1,290 @@
+"""QQ channel with auth, OpenAPI and pluggable receive transports."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+import bub
+from bub.channels import Channel
+from bub.channels.message import ChannelMessage
+from bub.channels.contracts import MessageHandler
+from loguru import logger
+
+from .config import QQConfig
+from .gateway.webhook import QQWebhookServer
+from .gateway.websocket import QQWebSocketClient
+from .inbound.c2c import QQC2CInboundService
+from .inbound.group import GROUP_EVENTS
+from .inbound.group import QQGroupInboundService
+from .inbound.group import group_was_mentioned
+from .inbound.interaction import INTERACTION_QUERY
+from .inbound.interaction import INTERACTION_UPDATE
+from .inbound.interaction import build_claw_cfg
+from .inbound.interaction import extract_claw_cfg_update
+from .inbound.interaction import parse_interaction_event
+from .outbound.c2c import QQC2CSendService
+from .outbound.group import QQGroupSendService
+from .protocol.auth import QQTokenProvider
+from .protocol.errors import QQOpenAPIError
+from .protocol.openapi import QQOpenAPI
+from .runtime import set_active_channel
+from .security import QQAccessPolicy
+from .session import QQInboundDeduper
+from .session import QQSessionState
+from .store import QQPlatformStore
+
+# Admin toggles for proactive messages, pushed when a group admin or C2C
+# user flips the "allow active messages" switch in the QQ client.
+_MSG_TOGGLE_EVENTS: dict[str, tuple[str, str, bool]] = {
+    "GROUP_MSG_RECEIVE": ("group", "group_openid", True),
+    "GROUP_MSG_REJECT": ("group", "group_openid", False),
+    "C2C_MSG_RECEIVE": ("c2c", "openid", True),
+    "C2C_MSG_REJECT": ("c2c", "openid", False),
+}
+
+
+class QQChannel(Channel):
+    """QQ channel registration with reusable auth and OpenAPI client."""
+
+    name = "qq"
+
+    def __init__(self, on_receive: MessageHandler) -> None:
+        self._on_receive = on_receive
+        self._config = bub.ensure_config(QQConfig)
+        self._token_provider = QQTokenProvider(self._config)
+        self._openapi = QQOpenAPI(self._config, self._token_provider)
+        self._webhook = QQWebhookServer(self._config, self._handle_transport_payload)
+        self._websocket = QQWebSocketClient(
+            self._config, self._openapi, self._handle_transport_payload
+        )
+        self._deduper = QQInboundDeduper(self._config.inbound_dedupe_size)
+        self._session_state = QQSessionState(
+            max_entries=self._config.session_state_size
+        )
+        self._policy = QQAccessPolicy.from_config(self._config)
+        self._platform_store = QQPlatformStore(self._resolve_state_path())
+        # In tool reply mode the model must reply through the qq.send tool,
+        # so direct model output is routed to the "null" channel and dropped.
+        suppress_direct_output = self._config.reply_mode == "tool"
+        self._c2c_inbound = QQC2CInboundService(
+            channel_name=self.name,
+            deduper=self._deduper,
+            state=self._session_state,
+            policy=self._policy,
+            suppress_direct_output=suppress_direct_output,
+        )
+        self._group_inbound = QQGroupInboundService(
+            channel_name=self.name,
+            deduper=self._deduper,
+            state=self._session_state,
+            policy=self._policy,
+            suppress_direct_output=suppress_direct_output,
+        )
+        self._c2c_send = QQC2CSendService(
+            channel_name=self.name,
+            receive_mode=self._config.receive_mode,
+            state=self._session_state,
+            openapi=self._openapi,
+            passive_reply_window_seconds=self._config.passive_reply_window_seconds,
+            passive_replies_per_msg_id=self._config.passive_replies_per_msg_id,
+        )
+        self._group_send = QQGroupSendService(
+            channel_name=self.name,
+            receive_mode=self._config.receive_mode,
+            state=self._session_state,
+            openapi=self._openapi,
+            passive_reply_window_seconds=self._config.passive_reply_window_seconds,
+            passive_replies_per_msg_id=self._config.passive_replies_per_msg_id,
+            active_messages=self._config.active_messages,
+            platform_store=self._platform_store,
+        )
+        set_active_channel(self)
+
+    def _resolve_state_path(self) -> Path:
+        raw = (self._config.state_file or "").strip()
+        if raw:
+            return Path(raw).expanduser()
+        return bub.home / "qq" / "state.json"
+
+    @property
+    def needs_debounce(self) -> bool:
+        return True
+
+    async def start(self, stop_event: asyncio.Event | None) -> None:
+        if not self._config.appid or not self._config.secret:
+            raise RuntimeError("qq appid/secret is empty")
+
+        mode = self._normalize_receive_mode()
+        if mode == "webhook":
+            await self._webhook.start()
+            logger.info(
+                "qq.start mode=webhook reply_mode={} token_url={} openapi_base_url={} webhook=http://{}:{}{} websocket=disabled",
+                self._config.reply_mode,
+                self._config.token_url,
+                self._config.openapi_base_url,
+                self._config.webhook_host,
+                self._config.webhook_port,
+                self._config.webhook_path,
+            )
+            return
+
+        await self._websocket.start(stop_event)
+        logger.info(
+            "qq.start mode=websocket reply_mode={} token_url={} openapi_base_url={} intents={} webhook=disabled",
+            self._config.reply_mode,
+            self._config.token_url,
+            self._config.openapi_base_url,
+            self._config.websocket_intents,
+        )
+
+    async def stop(self) -> None:
+        await self._webhook.stop()
+        await self._websocket.stop()
+        await self._openapi.aclose()
+        logger.info("qq.stopped")
+
+    async def send(self, message: ChannelMessage) -> None:
+        await self.send_for_result(message)
+
+    async def send_for_result(self, message: ChannelMessage) -> dict[str, object] | None:
+        """Send and return the send-service result (used by the qq.send tool)."""
+
+        if _is_group_target(self.name, message):
+            return await self._group_send.send(message)
+        return await self._c2c_send.send(message)
+
+    async def _handle_transport_payload(self, payload: dict[str, Any]) -> None:
+        op = payload.get("op")
+        event_type = payload.get("t")
+        if op != 0:
+            logger.info("qq.transport.ignored op={} t={}", op, event_type)
+            return
+        if event_type == "READY":
+            logger.info("qq.websocket.ready")
+            return
+        if event_type == "RESUMED":
+            logger.info("qq.websocket.resumed")
+            return
+        if event_type == "C2C_MESSAGE_CREATE":
+            await self._handle_c2c_message(payload)
+            return
+        if event_type in GROUP_EVENTS:
+            await self._handle_group_message(payload)
+            return
+        if event_type == "INTERACTION_CREATE":
+            await self._handle_interaction(payload)
+            return
+        if event_type in _MSG_TOGGLE_EVENTS:
+            self._handle_msg_toggle(event_type, payload)
+            return
+        logger.info("qq.transport.unhandled event={} op={}", event_type, op)
+
+    def _handle_msg_toggle(self, event_type: str, payload: dict[str, Any]) -> None:
+        scope, id_field, allowed = _MSG_TOGGLE_EVENTS[event_type]
+        data = payload.get("d")
+        openid = str(data.get(id_field) or "").strip() if isinstance(data, dict) else ""
+        if not openid:
+            logger.warning(
+                "qq.msg_toggle.invalid_payload event={} reason=missing_{}",
+                event_type,
+                id_field,
+            )
+            return
+        self._platform_store.update(scope, openid, active_messages=allowed)
+        logger.info(
+            "qq.msg_toggle event={} scope={} openid={} active_messages={}",
+            event_type,
+            scope,
+            openid,
+            allowed,
+        )
+
+    async def _handle_c2c_message(self, payload: dict[str, Any]) -> None:
+        parsed = self._c2c_inbound.parse_inbound(payload)
+        if parsed is None:
+            return
+        message, channel_message = parsed
+        logger.info(
+            "qq.c2c.inbound session_id={} user_openid={} content_len={} attachments={}",
+            channel_message.session_id,
+            message.user_openid,
+            len(message.content),
+            len(message.attachments),
+        )
+        await self._on_receive(channel_message)
+
+    async def _handle_group_message(self, payload: dict[str, Any]) -> None:
+        parsed = self._group_inbound.parse_inbound(payload)
+        if parsed is None:
+            return
+        message, channel_message = parsed
+        logger.info(
+            "qq.group.inbound session_id={} group_openid={} member_openid={} was_mentioned={} is_active={} content_len={}",
+            channel_message.session_id,
+            message.group_openid,
+            message.member_openid,
+            group_was_mentioned(message),
+            channel_message.is_active,
+            len(message.content),
+        )
+        await self._on_receive(channel_message)
+
+    async def _handle_interaction(self, payload: dict[str, Any]) -> None:
+        event = parse_interaction_event(payload)
+        if event is None:
+            return
+        event_type = event["type"]
+        if event_type in {INTERACTION_QUERY, INTERACTION_UPDATE}:
+            group_openid = event["group_openid"]
+            if event_type == INTERACTION_UPDATE and group_openid:
+                update = extract_claw_cfg_update(event)
+                if update:
+                    self._platform_store.update("group", group_openid, **update)
+                    logger.info(
+                        "qq.interaction.claw_cfg_updated group_openid={} update={}",
+                        group_openid,
+                        update,
+                    )
+            require_mention = (
+                self._platform_store.require_mention(group_openid)
+                if group_openid
+                else None
+            )
+            claw_cfg = (
+                build_claw_cfg(require_mention=require_mention)
+                if require_mention
+                else build_claw_cfg()
+            )
+            try:
+                await self._openapi.put_interaction(
+                    interaction_id=event["id"],
+                    code=0,
+                    data={"claw_cfg": claw_cfg},
+                )
+            except QQOpenAPIError as exc:
+                logger.warning(
+                    "qq.interaction.ack_failed id={} code={} error={}",
+                    event["id"],
+                    exc.error_code,
+                    exc.error_message,
+                )
+            return
+        logger.info("qq.interaction.unhandled type={}", event_type)
+
+    def _normalize_receive_mode(self) -> str:
+        mode = (self._config.receive_mode or "").strip().lower()
+        if mode not in {"webhook", "websocket"}:
+            raise RuntimeError(
+                f"qq receive_mode must be webhook or websocket, got {self._config.receive_mode!r}"
+            )
+        return mode
+
+
+def _is_group_target(channel_name: str, message: ChannelMessage) -> bool:
+    chat_id = message.chat_id or ""
+    session_id = message.session_id or ""
+    return chat_id.startswith("group:") or session_id.startswith(
+        f"{channel_name}:group:"
+    )

bub_qq/config.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from typing import Literal
+
+import bub
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+
+type ToolPolicy = Literal["open", "restricted", "locked"]
+type ReplyMode = Literal["direct", "tool"]
+
+
+@bub.config(name="qq")
+class QQConfig(bub.Settings):
+    """QQ Open Platform adapter config."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="BUB_QQ_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    appid: str = ""
+    secret: str = ""
+    token_url: str = "https://bots.qq.com/app/getAppAccessToken"
+    openapi_base_url: str = "https://api.bot.qq.com"
+    timeout_seconds: float = 30.0
+    token_refresh_skew_seconds: int = 60
+    receive_mode: str = Field(
+        default="",
+        description="QQ inbound transport mode. Must be set to 'webhook' or 'websocket' before gateway start.",
+    )
+    webhook_host: str = "127.0.0.1"
+    webhook_port: int = 8080
+    webhook_path: str = "/qq/webhook"
+    webhook_callback_timeout_seconds: float = 15.0
+    verify_signature: bool = True
+    webhook_signature_timestamp_tolerance_seconds: float = Field(
+        default=0.0,
+        ge=0,
+        description=(
+            "Reject webhook requests whose signature timestamp deviates from local"
+            " time by more than this many seconds. 0 disables the freshness check."
+        ),
+    )
+    inbound_dedupe_size: int = Field(default=1024, ge=1)
+    session_state_size: int = Field(
+        default=1024,
+        ge=1,
+        description="Max sessions/send records kept in memory for passive replies.",
+    )
+    passive_reply_window_seconds: float = Field(
+        default=3600.0,
+        gt=0,
+        description="How long after an inbound message passive replies are attempted.",
+    )
+    active_messages: bool = Field(
+        default=False,
+        description=(
+            "Send proactive group messages (no msg_id) when a passive reply"
+            " is impossible. Requires the group admin to allow proactive"
+            " messages in the QQ client; consumes platform quota."
+        ),
+    )
+    reply_mode: ReplyMode = Field(
+        default="direct",
+        description=(
+            "How model output reaches QQ. 'direct' forwards the model's"
+            " final text as the reply (output exactly <no_reply/> to stay"
+            " silent). 'tool' disables direct forwarding and exposes the"
+            " qq.send tool instead; staying silent means not calling it."
+        ),
+    )
+    passive_replies_per_msg_id: int = Field(
+        default=4,
+        ge=1,
+        description=(
+            "Local cap of passive replies per inbound msg_id, aligned with"
+            " the platform limit; beyond it the send falls back to an active"
+            " message (when enabled) or is skipped."
+        ),
+    )
+    state_file: str = Field(
+        default="",
+        description=(
+            "Path of the JSON file persisting platform switches (active"
+            "-message opt-ins, group claw_cfg). Empty uses"
+            " <bub home>/qq/state.json."
+        ),
+    )
+    websocket_intents: int = 1 << 25
+    websocket_use_shard_gateway: bool = False
+    websocket_reconnect_delay_seconds: float = 5.0
+    websocket_reconnect_max_delay_seconds: float = 300.0
+    websocket_max_identify_rejections: int = 5
+    admin_users: str = Field(
+        default="",
+        description=(
+            "Comma-separated user openids with full comma-command and tool"
+            " access in every scope. Comma commands from anyone else are"
+            " treated as plain text (in groups, owners/admins also qualify)."
+        ),
+    )
+    allow_users: str = Field(
+        default="",
+        description=(
+            "Comma-separated C2C user openid allowlist. When set, C2C"
+            " messages from anyone else are dropped. Empty allows everyone."
+        ),
+    )
+    allow_groups: str = Field(
+        default="",
+        description=(
+            "Comma-separated group openid allowlist. When set, messages from"
+            " other groups are dropped. Empty allows every group."
+        ),
+    )
+    group_tool_policy: ToolPolicy = Field(
+        default="restricted",
+        description=(
+            "Tool policy for group sessions: 'open' allows all tools,"
+            " 'restricted' denies shell/file-write/subagent tools,"
+            " 'locked' denies every tool. Group owners/admins and"
+            " admin_users bypass the policy."
+        ),
+    )
+    c2c_tool_policy: ToolPolicy = Field(
+        default="open",
+        description="Tool policy for C2C sessions; same values as group_tool_policy.",
+    )
+    denied_tools: str = Field(
+        default="",
+        description=(
+            "Extra comma-separated tool-name glob patterns denied under the"
+            " 'restricted' policy, e.g. 'web.fetch,tape.*'."
+        ),
+    )
+    llm_rate_limit_per_minute: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Max LLM calls per sender per session per minute; exceeding calls"
+            " are short-circuited with llm_rate_limit_notice. 0 disables."
+        ),
+    )
+    llm_rate_limit_notice: str = Field(
+        default="请求过于频繁，请稍后再试。",
+        description="Reply text used when a sender hits the LLM rate limit.",
+    )

bub_qq/gateway/__init__.py

@@ -0,0 +1,25 @@
+"""Receive transports (webhook / websocket) and gateway session helpers."""
+
+from .info import QQGatewayInfo
+from .info import QQSessionStartLimit
+from .info import get_gateway
+from .info import get_shard_gateway
+from .info import heartbeat_payload
+from .info import identify_payload
+from .info import resume_payload
+from .webhook import QQWebhookServer
+from .websocket import QQWebSocketClient
+from .ws_errors import QQWebSocketFatalError
+
+__all__ = [
+    "QQGatewayInfo",
+    "QQSessionStartLimit",
+    "QQWebSocketClient",
+    "QQWebSocketFatalError",
+    "QQWebhookServer",
+    "get_gateway",
+    "get_shard_gateway",
+    "heartbeat_payload",
+    "identify_payload",
+    "resume_payload",
+]

bub_qq/gateway/info.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..protocol.openapi import QQOpenAPI
+
+
+@dataclass(frozen=True)
+class QQSessionStartLimit:
+    total: int
+    remaining: int
+    reset_after: int
+    max_concurrency: int
+
+
+@dataclass(frozen=True)
+class QQGatewayInfo:
+    url: str
+    shards: int | None = None
+    session_start_limit: QQSessionStartLimit | None = None
+
+    @property
+    def max_concurrency(self) -> int | None:
+        if self.session_start_limit is None:
+            return None
+        return self.session_start_limit.max_concurrency
+
+
+async def get_gateway(openapi: QQOpenAPI) -> QQGatewayInfo:
+    payload = await openapi.get("/gateway")
+    return QQGatewayInfo(url=str(payload["url"]))
+
+
+async def get_shard_gateway(openapi: QQOpenAPI) -> QQGatewayInfo:
+    payload = await openapi.get("/gateway/bot")
+    return QQGatewayInfo(
+        url=str(payload["url"]),
+        shards=int(payload["shards"]) if payload.get("shards") is not None else None,
+        session_start_limit=_parse_session_start_limit(
+            payload.get("session_start_limit")
+        ),
+    )
+
+
+def identify_payload(
+    *, token: str, intents: int, shard: tuple[int, int] | None = None
+) -> dict[str, Any]:
+    data: dict[str, Any] = {
+        "token": f"QQBot {token}",
+        "intents": intents,
+        "properties": {
+            "$os": "macos",
+            "$browser": "bub-qq",
+            "$device": "bub-qq",
+        },
+    }
+    if shard is not None:
+        data["shard"] = [shard[0], shard[1]]
+    return {"op": 2, "d": data}
+
+
+def resume_payload(*, token: str, session_id: str, sequence: int) -> dict[str, Any]:
+    return {
+        "op": 6,
+        "d": {
+            "token": f"QQBot {token}",
+            "session_id": session_id,
+            "seq": sequence,
+        },
+    }
+
+
+def heartbeat_payload(sequence: int | None) -> dict[str, Any]:
+    return {"op": 1, "d": sequence}
+
+
+def _parse_session_start_limit(payload: Any) -> QQSessionStartLimit | None:
+    if not isinstance(payload, dict):
+        return None
+    required_fields = ("total", "remaining", "reset_after", "max_concurrency")
+    if any(payload.get(field) is None for field in required_fields):
+        return None
+    return QQSessionStartLimit(
+        total=int(payload["total"]),
+        remaining=int(payload["remaining"]),
+        reset_after=int(payload["reset_after"]),
+        max_concurrency=int(payload["max_concurrency"]),
+    )