DOCSEARCHbyAlgolia
Submit Docs

NapCat Documentation

repository·main·Indexed 27 days ago

https://github.com/napneko/napcatqq

A modern bot protocol framework based on NTQQ designed for efficiency and stability on low-memory systems. It includes a WebUI for management and debugging, a protocol adapter manager supporting onebot11 and napcat-protocol, and a set of common utilities for asynchronous task management, file cleanup, and URI handling.

Tokens
44.8K
Snippets
77
Records
340
Agent score
95%

What's inside NapCat

  1. Overview of NapCat WebUI features

    main

    NapCat WebUI is a web-based interface for managing NapCatQQ. It provides several management and debugging capabilities:

    • Authentication: WebUI login and QQ login.
    • Configuration: Network configuration and OneBot/WebUI configuration.
    • Logging: Viewing both real-time and historical logs.
    • Debugging: HTTP and WebSocket (WS) debugging tools.
    • Media: An online music player that supports NetEase Cloud Music playlists (displayed in the bottom right for large screens and at the bottom for small screens).

  4. Get Started with NapCat

    main

    NapCat is a modern protocol-side framework implemented based on NTQQ, designed for building bots. It is optimized for low-memory operating systems and provides a rich API interface that implements most standard bot protocols.

    To get started, download the latest version from the official releases page. For first-time users, it is highly recommended to consult the official documentation for tutorials before proceeding.

    https://github.com/NapNeko/NapCatQQ/releases/

  5. Manage NapCat OneBot 11 Actions

    main

    The packages/napcat-onebot/action module provides a mechanism to access and execute various bot actions (e.g., sending messages, managing groups, user info) through a type-safe interface. You can retrieve specific action handlers or call them directly using the createActionMap utility.

    Actions are categorized into:

    • OneBot 11 standard actions: SendMsg, GetGroupList, etc.
    • Go-CQHTTP compatible actions: GoCQHTTPGetGroupMsgHistory, etc.
    • Extended/Custom actions: SetQQAvatar, GetAiRecord, etc.

    Each action is an instance of a class implementing the OneBotAction interface.

  6. Initialize NapCat WebUI Frontend

    main

    The NapCat WebUI frontend is a React-based application that initializes several core services upon loading:

    1. Authentication: It checks login status via WebUIManager.checkWebUiLogined().
    2. Theme & Fonts: It loads the user's preferred theme and initializes fonts using loadTheme() and initFont().
    3. Routing: The application uses BrowserRouter with a base path of /webui/.
    4. Service Worker: In production environments (non-DEV), it registers a service worker (sw.js) at the application's base URL to enable PWA/offline capabilities.

    Developers integrating or hosting this frontend should ensure the application is served from a path that matches the basename='/webui/' configuration if using standard routing.

  7. Use vitePluginNapcatVersion to inject NapCat version into Vite

    main

    The vitePluginNapcatVersion plugin automatically fetches the latest GitHub tag from the NapNeko/NapCatQQ repository and injects it into your application's environment variables. This allows you to access the version string within your client-side code via import.meta.env.VITE_NAPCAT_VERSION.

    Version Resolution Priority

    1. Environment Variable: If NAPCAT_VERSION is set in the environment (useful for CI/CD), it is used immediately.
    2. Cache: If a valid tag is found in the local .napcat-version.json cache (and is less than 24 hours old), it is used.
    3. GitHub API: Fetches the latest tag from GitHub if no cache or environment variable is available.
    4. Fallback: Defaults to 1.0.0-dev if all other methods fail.

    Integration

    Add the plugin to your vite.config.js or vite.config.ts file.

  8. Debug WebSocket connections via WebUI

    main

    The WSDebug component in the NapCat WebUI provides a graphical interface for testing and debugging WebSocket connections to the NapCat server. It allows users to:

    1. Configure Connection: Set a custom WebSocket URL (e.g., ws://localhost:3001/api/Debug/ws) and an authentication token.
    2. Automatic Adapter Creation: The component can automatically call the /api/Debug/create endpoint to generate a debug adapter and retrieve a valid WebSocket URL and token.
    3. Monitor Traffic: View incoming messages in a real-time list (OneBotMessageList) and filter messages by type.
    4. Send Messages: Use the OneBotSendModal to send test messages over the established WebSocket connection.
    5. Manage Logs: Clear the message history using the clearMessages function.

    Note on URL Formats:

    • The UI supports absolute URLs starting with ws:// or wss://.
    • Relative paths starting with / are automatically prefixed with the current window's protocol and host.
    • The default debug endpoint typically follows the pattern: {protocol}://{host}/api/Debug/ws.

  10. Use the HTTP Debugging interface in NapCat WebUI

    main

    The HTTP Debugging page in the NapCat WebUI allows developers to test and debug OneBot HTTP APIs.

    Key Features:

    • Command Palette: Press Ctrl/Cmd + K to open a command palette to quickly search and select APIs.
    • API Tabs: Open multiple API debuggers simultaneously in a tabbed interface.
    • Automatic Payload Generation: When selecting an API, the interface automatically generates a default JSON body based on the API's schema (using TypeBox definitions) or a provided payloadExample.
    • Execution Modes:
      • Enter: Sends the request immediately.
      • Shift + Enter: Opens the API debugger with the payload pre-filled but does not send the request.

    API Discovery:

    The interface fetches available OneBot HTTP APIs via fetchOneBotHttpApi() and identifies the active adapter name via a POST request to /api/Debug/create (requiring a Bearer token in the Authorization header).

  12. Use loadNapCat.cjs to initialize the NapCat development environment

    main

    The loadNapCat.cjs script is a utility used to prepare the development environment by locating the correct QQNT version, copying necessary DLLs and configuration files to a dist directory, and setting required environment variables. It then dynamically imports the NapCat module.

    Usage

    Run the script via Node.js, providing the base directory of your QQ installation as the first argument:

    node loadNapCat.cjs /path/to/your/qq/installation

    Environment Variables Set

    The script configures the following environment variables for the process:

    VariableDescription
    NAPCAT_WRAPPER_PATHPath to wrapper.node in the target directory
    NAPCAT_QQ_PACKAGE_INFO_PATHPath to package.json in the target directory
    NAPCAT_QQ_VERSION_CONFIG_PATHPath to config.json in the target directory
    NAPCAT_DISABLE_PIPESet to '1' to disable pipes
    NAPCAT_DISABLE_MULTI_PROCESSSet to '1' to disable restart and multi-process features
    NAPCAT_WORKDIRThe target dist directory
    NAPCAT_WEBUI_JWT_SECRET_KEYFixed key for development: napcat_dev_secret_key
    NAPCAT_WEBUI_SECRET_KEYFixed key for development: napcatqq