napcat-sdk 0.5.4

NapCat SDK for Python - Fully typed and async ready

NapCat-SDK for Python

Type-Safe • Async-Ready • Framework-Free

Stop guessing parameter types. Let the IDE do the work.

告别查文档，享受 100% 类型覆盖 带来的极致补全体验。

---

⚡ The "IDE Magic"

这就是为什么你应该选择 NapCat-SDK：

智能 API 补全 + 精准参数提示	原生开发体验 + 零心智负担

👆 真正的 160+ API 全量类型覆盖，每一次按键都有 IDE 的守护。

---

✨ Features

• 🔄 协议自动同步: 基于 OpenAPI 自动构建，与 NapCat 上游定义零时差同步。
• 🧘 原生无框架: 拒绝框架“黑魔法”，纯粹 Python 语法，零心智负担。
• 💎 极致类型: 100% 类型覆盖，每一个参数都有定义，享受极致 IDE 补全。
• ⚡ 完全异步: 基于 websockets + asyncio 原生开发，无惧高并发。
• 🔌 双模支持: 完美支持正向 (Client) 与反向 (Server) WebSocket 连接。
• 📦 极轻量级: 仅依赖 websockets 和 orjson，极速安装，拒绝臃肿。

---

📦 Installation

uv add napcat-sdk
# or
pip install napcat-sdk

---

📸 Quick Look

[!IMPORTANT] client.events() 方法已移除，请直接使用 async for event in client 监听事件。 当前截图因录制成本暂未更新，代码示例请以本文文本为准。

🖱️ 点击复制代码文本

import asyncio
from napcat import NapCatClient, GroupMessageEvent, PrivateMessageEvent

async def listen_private(client: NapCatClient):
    print(">> 私聊监听启动")
    async for event in client:
        match event:
            case PrivateMessageEvent():
                print(f"[私信] {event.sender.nickname}: {event.raw_message}")
                await event.send_msg("已阅")
            case _:
                pass

async def listen_group(client: NapCatClient):
    print(">> 群聊监听启动")
    async for event in client:
        match event:
            case GroupMessageEvent():
                print(f"[群消息] {event.group_id}: {event.raw_message}")
                await event.reply("复读")
            case _:
                pass

async def main():
    # 正向 WebSocket 连接（支持自动管理上下文）
    client = NapCatClient(ws_url="ws://localhost:3001", token="123")
    await asyncio.gather(
        listen_private(client),
        listen_group(client)
    )

if __name__ == "__main__":
    asyncio.run(main())

---

📖 Usage

NapCatClient 支持直接作为异步迭代器使用，并会在迭代开始/结束时自动管理连接生命周期。

🔌 反向 WebSocket 服务端 (Server Mode)

如果你配置 NapCat 主动连接你的程序，请使用 ReverseWebSocketServer。

import asyncio
from napcat import ReverseWebSocketServer, NapCatClient, GroupMessageEvent

async def handler(client: NapCatClient):
    """每个新的 WebSocket 连接都会触发此回调"""
    print(f"Bot Connected! Self ID: {client.self_id}")
    
    # 就像 Client 模式一样处理事件
    async for event in client:
        if isinstance(event, GroupMessageEvent):
            print(f"收到群 {event.group_id} 消息: {event.raw_message}")
            await event.reply("服务端已收到")

async def main():
    # 启动服务器监听 8080 端口
    server = ReverseWebSocketServer(handler, host="0.0.0.0", port=8080, token="my-token")
    await server.run_forever()

if __name__ == "__main__":
    asyncio.run(main())

🖼️ 发送富媒体消息 (图片/At/回复)

SDK 提供了强类型的 MessageSegment，告别手动拼接 CQ 码。

from napcat import (
    NapCatClient,
    Text,
    Image,
    At,
)

async def send_rich_media(client: NapCatClient, group_id: int):
    # 构建消息链：@某人 + 文本 + 图片
    message = [
        At(qq="12345678"),
        Text(text=" 来看这张图："),
        Image(file="https://example.com/image.jpg"),
    ]
    
    # 直接发送列表
    await client.send_group_msg(group_id=group_id, message=message)

🔗 调用 OneBot API (100% 类型提示)

所有 API 方法都直接挂载在 client 上，拥有完整的参数类型检查。

async def managing_bot(client: NapCatClient):
    # 获取登录号信息
    login_info = await client.get_login_info()
    print(f"当前登录: {login_info['nickname']}")

    # 获取群成员列表
    members = await client.get_group_member_list(
        group_id=123456, 
        no_cache=True
    )
    for member in members:
        print(f"成员: {member['card'] or member['nickname']}")
    
    # 动态调用（针对未收录的 API）
    await client.call_action("some_new_action", {"param": 1})

⚠️ 错误处理 (异常类型)

SDK 提供了明确的异常类型，方便区分错误来源：

from napcat import NapCatAPIError, NapCatProtocolError, NapCatStateError

try:
    await client.get_login_info()
except NapCatAPIError as exc:
    print("API 失败:", exc)
    print("action=", exc.action, "retcode=", exc.retcode)
except NapCatProtocolError as exc:
    print("上报数据异常:", exc)
except NapCatStateError as exc:
    print("客户端状态错误:", exc)

---

🛠️ Development

本项目使用 uv 进行包管理。

1. 克隆项目并同步环境:

git clone --recursive https://github.com/faithleysath/napcat-sdk.git
cd napcat-sdk
uv sync
cd NapCatQQ
pnpm install

2. 同步协议定义: SDK 的核心代码由 OpenAPI 规范自动生成，请运行以下命令重新生成代码：

uv run scripts/schema-codegen.py

这会自动更新 src/napcat/types/messages/generated.py、src/napcat/types/schemas.py、src/napcat/client_api.py 以及相关的 __init__.py。

3. 运行测试:

# 运行 tests
uv run pytest src/tests -q

---

📄 License

MIT License © 2025 faithleysath