python-library-napcat-adapter 0.1.0__tar.gz

python_library_napcat_adapter-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.env.*
+!.env.example
+# packages 示例本地密钥（*.example 为模板，可提交）
+packages/**/examples/**/.env
+!packages/**/examples/**/.env.example
+packages/**/examples/**/mcp.json
+!packages/**/examples/**/mcp.json.example
+packages/**/examples/**/.sandbox/
+.pytest_cache/
+config.yaml
+logs/
+.cursor/
+uv.lock

python_library_napcat_adapter-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: python-library-napcat-adapter
+Version: 0.1.0
+Summary: NapCat CQ 消息段与 OneBot 载荷互转及接入
+Requires-Python: >=3.10
+Requires-Dist: napcat-sdk
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: python-library-onebot-protocol

python_library_napcat_adapter-0.1.0/napcat_adapter/__init__.py

@@ -0,0 +1,4 @@
+from napcat_adapter.adapter import Adapter
+from napcat_adapter.listener import Listener
+
+__all__ = ["Adapter", "Listener"]

python_library_napcat_adapter-0.1.0/napcat_adapter/adapter.py

@@ -0,0 +1,136 @@
+from collections.abc import Awaitable, Callable
+
+from onebot_protocol import MessagePayload
+
+from napcat_adapter.bot import Bot
+from napcat_adapter.listener import (
+    Listener,
+    emit_disconnect,
+    emit_error,
+    emit_message,
+    emit_void,
+)
+from napcat_adapter.models import BotMessage
+from napcat_adapter.protocol_adapt import bot_to_onebot, onebot_to_bot
+
+MessageCallback = Callable[[MessagePayload], Awaitable[None]]
+
+
+class Adapter:
+    """NapCat 对外门面：入站转统一消息载荷，出站从载荷经 CQ 段发回。
+
+    群聊默认仅在 @ 机器人时上报；过滤规则在包内完成。
+    """
+
+    def __init__(
+        self,
+        ws_url: str,
+        *,
+        token: str | None = None,
+        reconnect_interval_seconds: float = 5.0,
+        listeners: list[Listener] | None = None,
+    ) -> None:
+        """创建适配器并绑定内部 NapCat 客户端。
+
+        Args:
+            ws_url: NapCat 正向 WebSocket 地址
+            token: 可选访问令牌
+            reconnect_interval_seconds: 断线后重连等待秒数
+            listeners: 构造期注册的多组事件监听器
+        """
+        self._callbacks: list[MessageCallback] = []
+        self._listeners: list[Listener] = list(listeners or [])
+        self._bot = Bot(
+            ws_url=ws_url,
+            token=token,
+            reconnect_interval_seconds=reconnect_interval_seconds,
+        )
+        self._bot.on_message(self._on_bot_message)
+        self._bot.on_connect(self._on_connect)
+        self._bot.on_ready(self._on_ready)
+        self._bot.on_disconnect(self._on_disconnect)
+        self._bot.on_error(self._on_error)
+
+    def register(self, callback: MessageCallback) -> None:
+        """登记一条消息回调，与监听器中的消息槽位一并触发。
+
+        Args:
+            callback: 异步处理入站统一消息载荷
+        """
+        self._callbacks.append(callback)
+
+    def on_message(
+        self, callback: MessageCallback | None = None
+    ) -> MessageCallback | Callable[[MessageCallback], MessageCallback]:
+        """登记消息回调；无参调用时返回装饰器。
+
+        Args:
+            callback: 直接传入的异步处理函数；省略时用于装饰器写法
+
+        Returns:
+            装饰器模式下返回原函数；直接传入时返回同一回调
+        """
+        if callback is not None:
+            self.register(callback)
+            return callback
+
+        def decorator(fn: MessageCallback) -> MessageCallback:
+            self.register(fn)
+            return fn
+
+        return decorator
+
+    async def send(self, payload: MessagePayload) -> None:
+        """按统一载荷向当前会话发送消息。
+
+        Args:
+            payload: 目标会话与消息段列表
+        """
+        await self._bot.send(onebot_to_bot(payload))
+
+    async def _on_bot_message(self, msg: BotMessage) -> None:
+        payload = bot_to_onebot(msg)
+        if payload is None:
+            return
+        await emit_message(self._listeners, payload)
+        for callback in self._callbacks:
+            try:
+                await callback(payload)
+            except Exception:
+                pass
+
+    async def _on_connect(self) -> None:
+        await emit_void(self._listeners, "on_connect")
+
+    async def _on_ready(self) -> None:
+        await emit_void(self._listeners, "on_ready")
+
+    async def _on_disconnect(self, reason: str) -> None:
+        await emit_disconnect(self._listeners, reason)
+
+    async def _on_error(self, exc: BaseException) -> None:
+        await emit_error(self._listeners, exc)
+
+    async def start(self) -> None:
+        """在后台启动 WebSocket 事件循环，不阻塞当前协程。
+
+        与 stop 配对；长期运行请用 run。
+        """
+        await emit_void(self._listeners, "on_start")
+        await self._bot.start()
+
+    async def stop(self) -> None:
+        """停止客户端并结束事件循环；会触发监听器的 on_stop。"""
+        await self._bot.stop()
+        await emit_void(self._listeners, "on_stop")
+
+    async def run(self) -> None:
+        """启动并阻塞直到停止；适合 asyncio.run(adapter.run())。
+
+        Ctrl+C 或任务取消时会断开连接并触发 on_stop。
+        """
+        await emit_void(self._listeners, "on_start")
+        try:
+            await self._bot.run()
+        finally:
+            await emit_void(self._listeners, "on_stop")

python_library_napcat_adapter-0.1.0/napcat_adapter/bot.py

@@ -0,0 +1,265 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from typing import Any
+
+from napcat import GroupMessageEvent, NapCatClient, PrivateMessageEvent
+from napcat.types.messages import Message, MessageSegment, UnknownMessageSegment
+from pydantic import BaseModel, Field, PrivateAttr
+
+from napcat_adapter.models import BotMessage, MessageType
+
+VoidCallback = Callable[[], Awaitable[None]]
+DisconnectCallback = Callable[[str], Awaitable[None]]
+ErrorCallback = Callable[[BaseException], Awaitable[None]]
+
+
+class Bot(BaseModel):
+    """NapCat 正向 WebSocket 客户端：收事件、发 CQ 消息。
+
+    构造入参见各字段的 description；包外请优先使用 Adapter。
+    """
+
+    ws_url: str = Field(description="NapCat 正向 WebSocket 地址")
+    token: str | None = Field(default=None, description="NapCat 访问令牌")
+    reconnect_interval_seconds: float = Field(
+        default=5.0,
+        ge=0.5,
+        le=3600.0,
+        description="断线或连接失败后再次尝试前的等待秒数",
+    )
+
+    _stop_event: asyncio.Event = PrivateAttr()
+    _task: asyncio.Task[None] | None = PrivateAttr(default=None)
+    _client: NapCatClient | None = PrivateAttr(default=None)
+    _login_info: dict[str, Any] | None = PrivateAttr(default=None)
+    _bot_name: str = PrivateAttr(default="")
+    _bot_id: str = PrivateAttr(default="")
+    _running: bool = PrivateAttr(default=False)
+    _on_message: Callable[[BotMessage], Awaitable[None]] | None = PrivateAttr(default=None)
+    _on_connect: VoidCallback | None = PrivateAttr(default=None)
+    _on_ready: VoidCallback | None = PrivateAttr(default=None)
+    _on_disconnect: DisconnectCallback | None = PrivateAttr(default=None)
+    _on_error: ErrorCallback | None = PrivateAttr(default=None)
+
+    def model_post_init(self, ctx: Any) -> None:
+        """初始化运行期状态与事件槽位。"""
+        self._stop_event = asyncio.Event()
+
+    def on_message(self, callback: Callable[[BotMessage], Awaitable[None]]) -> None:
+        """登记入站聊天事件回调。
+
+        Args:
+            callback: 异步处理包内机器人消息
+        """
+        self._on_message = callback
+
+    def on_connect(self, callback: VoidCallback) -> None:
+        """登记 WebSocket 已连接回调。"""
+        self._on_connect = callback
+
+    def on_ready(self, callback: VoidCallback) -> None:
+        """登记登录信息就绪回调。"""
+        self._on_ready = callback
+
+    def on_disconnect(self, callback: DisconnectCallback) -> None:
+        """登记连接断开回调。
+
+        Args:
+            callback: 异步处理断开原因短句
+        """
+        self._on_disconnect = callback
+
+    def on_error(self, callback: ErrorCallback) -> None:
+        """登记运行期错误回调。
+
+        Args:
+            callback: 异步处理异常对象
+        """
+        self._on_error = callback
+
+    async def _emit_connect(self) -> None:
+        if self._on_connect is None:
+            return
+        try:
+            await self._on_connect()
+        except Exception:
+            pass
+
+    async def _emit_ready(self) -> None:
+        if self._on_ready is None:
+            return
+        try:
+            await self._on_ready()
+        except Exception:
+            pass
+
+    async def _emit_disconnect(self, reason: str) -> None:
+        if self._on_disconnect is None:
+            return
+        try:
+            await self._on_disconnect(reason)
+        except Exception:
+            pass
+
+    async def _emit_error(self, exc: BaseException) -> None:
+        if self._on_error is None:
+            return
+        try:
+            await self._on_error(exc)
+        except Exception:
+            pass
+
+    async def _refresh_login_info(self) -> None:
+        if self._client is None:
+            return
+        try:
+            login_info = await self._client.get_login_info()
+            user_id = int(login_info["user_id"])
+            self._client.self_id = user_id
+            self._login_info = dict(login_info)
+            self._bot_id = str(user_id)
+            self._bot_name = str(login_info["nickname"])
+        except Exception:
+            pass
+
+    async def _handle_events(self) -> None:
+        try:
+            while not self._stop_event.is_set():
+                self._client = NapCatClient(ws_url=self.ws_url, token=self.token)
+
+                try:
+                    async with self._client:
+                        await self._emit_connect()
+                        await self._refresh_login_info()
+                        await self._emit_ready()
+                        async for event in self._client:
+                            if self._stop_event.is_set():
+                                break
+                            if isinstance(event, (GroupMessageEvent, PrivateMessageEvent)):
+                                await self._handle_message(event)
+                except asyncio.CancelledError:
+                    raise
+                except ConnectionRefusedError as exc:
+                    await self._emit_error(exc)
+                    await self._emit_disconnect("connection_refused")
+                except Exception as exc:
+                    await self._emit_error(exc)
+                    await self._emit_disconnect("error")
+                else:
+                    if self._stop_event.is_set():
+                        await self._emit_disconnect("stopped")
+                    else:
+                        await self._emit_disconnect("closed")
+                finally:
+                    self._client = None
+                    self._login_info = None
+                    self._bot_id = ""
+                    self._bot_name = ""
+
+                if self._stop_event.is_set():
+                    break
+
+                try:
+                    await asyncio.wait_for(
+                        self._stop_event.wait(),
+                        timeout=self.reconnect_interval_seconds,
+                    )
+                    break
+                except TimeoutError:
+                    continue
+        finally:
+            self._running = False
+
+    async def _handle_message(self, event: GroupMessageEvent | PrivateMessageEvent) -> None:
+        if self._login_info is None:
+            await self._refresh_login_info()
+
+        user_name = str(event.user_id)
+        session_id = str(event.group_id) if isinstance(event, GroupMessageEvent) else user_name
+        message_type = MessageType.GROUP if isinstance(event, GroupMessageEvent) else MessageType.PRIVATE
+        data_list = [dict(segment) for segment in event.message]
+
+        message = BotMessage(
+            session_id=session_id,
+            data_list=data_list,
+            bot_id=self._bot_id,
+            message_type=message_type,
+            user_name=user_name,
+            message_id=str(event.message_id),
+            bot_name=self._bot_name,
+        )
+
+        if self._on_message is None:
+            return
+        try:
+            await self._on_message(message)
+        except Exception:
+            pass
+
+    async def start(self) -> None:
+        """在后台启动 WebSocket 事件循环，不阻塞当前协程。"""
+        if self._running:
+            return
+        self._running = True
+        self._stop_event.clear()
+        self._task = asyncio.create_task(self._handle_events())
+
+    async def send(self, message: BotMessage) -> None:
+        """向群或好友发送 CQ 段列表。
+
+        Args:
+            message: 含会话类型与 data_list 的包内消息
+        """
+        if self._client is None or not self._client.is_running:
+            return
+
+        data_list = [
+            {"type": segment["type"], "data": segment.get("data", {})}
+            for segment in message.data_list
+        ]
+        messages = _to_napcat_messages(data_list)
+        if not messages:
+            return
+
+        try:
+            if message.message_type == MessageType.GROUP:
+                await self._client.send_group_msg(
+                    group_id=message.session_id, message=messages
+                )
+            else:
+                await self._client.send_private_msg(
+                    user_id=message.session_id, message=messages
+                )
+        except Exception:
+            pass
+
+    async def stop(self) -> None:
+        """停止客户端并结束事件循环。"""
+        if not self._running:
+            return
+        self._stop_event.set()
+        if self._task is not None and self._task is not asyncio.current_task():
+            self._task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._task
+        self._running = False
+
+    async def run(self) -> None:
+        """启动连接并阻塞；Ctrl+C 或任务取消时收尾退出。"""
+        await self.start()
+        try:
+            await self._stop_event.wait()
+        finally:
+            await self.stop()
+
+
+def _to_napcat_messages(data_list: list[dict[str, Any]]) -> list[Message]:
+    """把 CQ 字典段列表转为 NapCat SDK 消息对象，跳过未知段。"""
+    messages: list[Message] = []
+    for data in data_list:
+        segment = MessageSegment.from_dict(data)
+        if isinstance(segment, UnknownMessageSegment):
+            continue
+        messages.append(segment)
+    return messages

python_library_napcat_adapter-0.1.0/napcat_adapter/listener.py

@@ -0,0 +1,97 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from onebot_protocol import MessagePayload
+
+MessageCallback = Callable[[MessagePayload], Awaitable[None]]
+VoidCallback = Callable[[], Awaitable[None]]
+DisconnectCallback = Callable[[str], Awaitable[None]]
+ErrorCallback = Callable[[BaseException], Awaitable[None]]
+
+
+@dataclass
+class Listener:
+    """按事件名挂接异步回调；未赋值的槽位不参与派发。
+
+    构造适配器时传入列表，与运行期登记的消息回调可同时存在。
+    """
+
+    on_message: MessageCallback | None = None
+    """收到已转为统一消息载荷的入站聊天消息。"""
+    on_start: VoidCallback | None = None
+    """适配器开始监听或进入常驻运行。"""
+    on_stop: VoidCallback | None = None
+    """适配器停止监听或常驻运行结束。"""
+    on_ready: VoidCallback | None = None
+    """平台侧会话就绪，可稳定收发。"""
+    on_connect: VoidCallback | None = None
+    """底层传输已连通，未必已完成鉴权。"""
+    on_disconnect: DisconnectCallback | None = None
+    """传输断开；参数为平台给出的原因短句。"""
+    on_error: ErrorCallback | None = None
+    """连接或运行期未捕获的异常。"""
+
+
+async def emit_void(listeners: list[Listener], name: str) -> None:
+    """对监听器列表派发无参生命周期类回调。
+
+    Args:
+        listeners: 适配器持有的监听器实例
+        name: 监听器上对应的无参槽位名
+    """
+    for listener in listeners:
+        cb = getattr(listener, name, None)
+        if cb is None:
+            continue
+        try:
+            await cb()
+        except Exception:
+            pass
+
+
+async def emit_disconnect(listeners: list[Listener], reason: str) -> None:
+    """对监听器列表派发断开回调。
+
+    Args:
+        listeners: 适配器持有的监听器实例
+        reason: 断开原因，供日志或重连策略使用
+    """
+    for listener in listeners:
+        if listener.on_disconnect is None:
+            continue
+        try:
+            await listener.on_disconnect(reason)
+        except Exception:
+            pass
+
+
+async def emit_error(listeners: list[Listener], exc: BaseException) -> None:
+    """对监听器列表派发错误回调。
+
+    Args:
+        listeners: 适配器持有的监听器实例
+        exc: 本次错误对象
+    """
+    for listener in listeners:
+        if listener.on_error is None:
+            continue
+        try:
+            await listener.on_error(exc)
+        except Exception:
+            pass
+
+
+async def emit_message(listeners: list[Listener], payload: MessagePayload) -> None:
+    """对监听器列表派发消息回调。
+
+    Args:
+        listeners: 适配器持有的监听器实例
+        payload: 已转换为对外统一格式的入站消息
+    """
+    for listener in listeners:
+        if listener.on_message is None:
+            continue
+        try:
+            await listener.on_message(payload)
+        except Exception:
+            pass

python_library_napcat_adapter-0.1.0/napcat_adapter/models.py

@@ -0,0 +1,171 @@
+from enum import StrEnum
+from typing import Annotated, Literal, Union
+
+from pydantic import BaseModel, Field
+
+
+class MessageType(StrEnum):
+    """会话类型：私聊或群聊。"""
+
+    PRIVATE = "private"
+    GROUP = "group"
+
+
+class BaseSegment(BaseModel):
+    """CQ 消息段通用壳：类型名与原始数据字典。"""
+
+    type: str = Field(description="段类型，如 text、at、image")
+    data: dict = Field(description="协议原始字段字典")
+
+
+class AtSegment(BaseSegment):
+    """@ 成员段。"""
+
+    type: Literal["at"] = "at"
+    qq: str | None = None
+    name: str | None = None
+
+    def model_post_init(self, ctx) -> None:
+        self.qq = self.data["qq"]
+        raw_name = self.data.get("name") or ""
+        self.name = raw_name.lstrip("@").strip()
+
+
+class FaceSegment(BaseSegment):
+    """QQ 表情段。"""
+
+    type: Literal["face"] = "face"
+    id: str | None = None
+    large: str | None = None
+    result_id: str | None = None
+    chain_count: int | None = None
+
+    def model_post_init(self, ctx) -> None:
+        self.id = str(self.data["id"])
+        self.large = self.data.get("large")
+        self.result_id = self.data.get("resultId")
+        self.chain_count = self.data.get("chainCount")
+
+
+class TextSegment(BaseSegment):
+    """纯文本段。"""
+
+    type: Literal["text"] = "text"
+    text: str | None = None
+
+    def model_post_init(self, ctx) -> None:
+        self.text = self.data["text"]
+
+
+class ReplySegment(BaseSegment):
+    """引用回复段。"""
+
+    type: Literal["reply"] = "reply"
+    id: str | None = None
+
+    def model_post_init(self, ctx) -> None:
+        self.id = self.data["id"]
+
+
+class MfaceSegment(BaseSegment):
+    """商城表情段。"""
+
+    type: Literal["mface"] = "mface"
+    url: str | None = None
+    emoji_package_id: str | None = None
+    emoji_id: str | None = None
+    key: str | None = None
+    summary: str | None = None
+
+
+class LocationSegment(BaseSegment):
+    """位置段。"""
+
+    type: Literal["location"] = "location"
+    lat: float | None = None
+    lon: float | None = None
+    title: str | None = None
+    content: str | None = None
+
+
+class JsonSegment(BaseSegment):
+    """JSON 卡片段。"""
+
+    type: Literal["json"] = "json"
+
+
+class ImageSegment(BaseSegment):
+    """图片段。"""
+
+    type: Literal["image"] = "image"
+    file: str | None = None
+    filename: str | None = None
+    url: str | None = None
+    summary: str | None = None
+    subType: str | None = None
+
+
+class ForwardSegment(BaseSegment):
+    """合并转发段。"""
+
+    type: Literal["forward"] = "forward"
+    id: str | None = None
+
+
+class VideoSegment(BaseSegment):
+    """视频段。"""
+
+    type: Literal["video"] = "video"
+    file: str | None = None
+    url: str | None = None
+
+    def model_post_init(self, ctx) -> None:
+        self.file = self.data["file"]
+        self.url = self.data["url"]
+
+
+Segment = Annotated[
+    Union[
+        TextSegment,
+        ImageSegment,
+        FaceSegment,
+        AtSegment,
+        ForwardSegment,
+        ReplySegment,
+        JsonSegment,
+        VideoSegment,
+        MfaceSegment,
+        LocationSegment,
+    ],
+    Field(discriminator="type"),
+]
+
+
+class BotMessage(BaseModel):
+    """包内入站/出站消息：CQ 段列表与会话上下文。"""
+
+    message_id: str = Field(description="平台分配的消息编号")
+    data_list: list[dict] = Field(description="CQ 协议段列表，每项含 type 与 data")
+    message_type: MessageType = Field(description="私聊或群聊")
+    bot_id: str = Field(description="当前机器人 QQ 号")
+    bot_name: str | None = Field(default=None, description="机器人昵称，用于解析 @")
+    session_id: str = Field(description="群号或好友号，用作发送目标")
+    user_name: str = Field(description="发送方 QQ 号")
+
+
+__all__ = [
+    "BotMessage",
+    "BaseSegment",
+    "TextSegment",
+    "ImageSegment",
+    "FaceSegment",
+    "AtSegment",
+    "ForwardSegment",
+    "ReplySegment",
+    "JsonSegment",
+    "VideoSegment",
+    "MfaceSegment",
+    "LocationSegment",
+    "MessageType",
+    "Segment",
+]

python_library_napcat_adapter-0.1.0/napcat_adapter/protocol_adapt.py

@@ -0,0 +1,194 @@
+from typing import List, Union, Optional
+from napcat_adapter.models import (
+    BaseSegment,
+    TextSegment,
+    ImageSegment,
+    FaceSegment,
+    AtSegment,
+    ForwardSegment,
+    ReplySegment,
+    JsonSegment,
+    VideoSegment,
+    MfaceSegment,
+    LocationSegment,
+    BotMessage,
+    MessageType,
+)
+import onebot_protocol
+from onebot_protocol import MessagePayload
+
+SEGMENT_MAP = {
+    "text": TextSegment,
+    "image": ImageSegment,
+    "face": FaceSegment,
+    "at": AtSegment,
+    "forward": ForwardSegment,
+    "reply": ReplySegment,
+    "json": JsonSegment,
+    "video": VideoSegment,
+    "mface": MfaceSegment,
+    "location": LocationSegment,
+}
+
+USER_MAP: dict[str, str] = {}
+
+MENTION_ALL_NAME = "全体成员"
+
+
+def data_to_segments(data_list: list[dict], bot_name: str, bot_id: str) -> list[BaseSegment]:
+    """把原始段字典列表转为强类型段，并拆分正文里的 @ 机器人。
+
+    Args:
+        data_list: 事件中的 CQ 段列表
+        bot_name: 机器人昵称，用于匹配 @
+        bot_id: 机器人 QQ 号
+
+    Returns:
+        过滤无效项并展开 @ 后的段列表
+    """
+    segments = [_cast_segment(x) for x in data_list]
+    segments = [x for x in segments if x]
+
+    segments = [
+        (_extract_mention_robot(x, bot_name, bot_id) if isinstance(x, TextSegment) else [x])
+        for x in segments
+    ]
+    segments = [x for data in segments for x in data]
+
+    return segments
+
+
+def onebot_to_bot(payload: MessagePayload) -> BotMessage:
+    """把对外统一载荷转成 NapCat 可发送的 CQ 段列表。
+
+    Args:
+        payload: 会话、消息段与机器人标识
+
+    Returns:
+        含 data_list 的包内机器人消息
+    """
+    data_list = []
+    for message in payload.messages:
+        if isinstance(message, onebot_protocol.TextMessageSegment):
+            message = TextSegment(data={"text": message.data.text})
+        elif isinstance(message, onebot_protocol.MentionMessageSegment):
+            name = USER_MAP.get(message.data.user_id)
+            if not name:
+                continue
+            message = AtSegment(data={"qq": message.data.user_id, "name": name})
+        data_list.append(message.model_dump())
+
+    msg = BotMessage(
+        message_id=payload.message_id,
+        data_list=data_list,
+        message_type=MessageType(payload.source_type),
+        bot_id=payload.bot_id,
+        session_id=payload.session_id,
+        user_name=payload.user_id or "",
+    )
+
+    if msg.message_type == MessageType.GROUP:
+        if msg.user_name:
+            msg.data_list = [
+                AtSegment(data={"qq": msg.user_name, "name": USER_MAP.get(msg.user_name, "")}).model_dump(),
+                TextSegment(data={"text": " "}).model_dump(),
+            ] + msg.data_list
+
+    return msg
+
+
+def bot_to_onebot(msg: BotMessage) -> Optional[MessagePayload]:
+    """把 NapCat 入站消息转为对外统一载荷；群聊未 @ 机器人时返回空。
+
+    Args:
+        msg: 事件解析后的包内消息
+
+    Returns:
+        可上报的统一载荷；无需上报时为 None
+    """
+    global USER_MAP
+
+    segments = data_to_segments(msg.data_list, msg.bot_name, msg.bot_id)
+
+    if not _should_broadcast(msg, segments):
+        return None
+
+    for segment in segments:
+        if isinstance(segment, AtSegment) and segment.qq == msg.bot_id:
+            segments.remove(segment)
+
+    messages = []
+    for segment in segments:
+        if isinstance(segment, TextSegment):
+            text = segment.text.strip()
+            if not text:
+                continue
+            message = onebot_protocol.TextMessageSegment(data={"text": text})
+        elif isinstance(segment, AtSegment):
+            if segment.name == MENTION_ALL_NAME:
+                message = onebot_protocol.MentionAllMessageSegment()
+            else:
+                message = onebot_protocol.MentionMessageSegment(data={"user_id": segment.qq})
+            USER_MAP[segment.qq] = segment.name
+        else:
+            continue
+        messages.append(message)
+
+    if not messages:
+        return None
+
+    return MessagePayload(
+        message_id=msg.message_id,
+        source_type=msg.message_type.value,
+        bot_id=msg.bot_id,
+        session_id=msg.session_id,
+        user_id=msg.user_name,
+        messages=messages,
+    )
+
+
+def _should_broadcast(msg: BotMessage, segments: list[BaseSegment]) -> bool:
+    """群聊仅在 @ 到机器人时向上层上报。"""
+    if msg.message_type == MessageType.GROUP:
+        for segment in segments:
+            if isinstance(segment, AtSegment) and segment.qq == msg.bot_id:
+                return True
+        return False
+    return True
+
+
+def _cast_segment(data: dict) -> Optional[BaseSegment]:
+    """按 type 字段实例化对应段模型；未知或校验失败返回 None。"""
+    cls = SEGMENT_MAP.get(data["type"])
+    if not cls:
+        return None
+    try:
+        return cls(**data)
+    except Exception:
+        return None
+
+
+def _extract_mention_robot(
+    text: TextSegment, bot_name: str, bot_id: str
+) -> List[Union[TextSegment, AtSegment]]:
+    """把正文中「@昵称 」拆成文本段与 @ 段。"""
+
+    def split(text: TextSegment) -> List[Union[TextSegment, AtSegment]]:
+        content = text.text
+
+        keyword = f"@{bot_name} "
+        if keyword in content:
+            index = content.find(keyword)
+            before_text = content[:index]
+            after_text = content[index + len(keyword):]
+            return (
+                split(TextSegment(data={"text": before_text}))
+                + [AtSegment(data={"name": bot_name, "qq": bot_id})]
+                + split(TextSegment(data={"text": after_text}))
+            )
+        return [text]
+
+    try:
+        return split(text)
+    except Exception:
+        return [text]

python_library_napcat_adapter-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-napcat-adapter"
+version = "0.1.0"
+description = "NapCat CQ 消息段与 OneBot 载荷互转及接入"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0,<3",
+    "napcat-sdk",
+    "python-library-onebot-protocol",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["napcat_adapter"]