Modern protocol-side framework based on NTQQ
Go to file
手瓜一十雪 3bead89d46 Support object references and deep proxying
Introduce remote object references (refId) and deep proxy support across client, server, serializer and types. Key changes:

- Add refId propagation in client proxies so child proxies inherit and include refId on RPC requests.
- Extend serializer to handle a new SerializedValueType.OBJECT_REF, add refResolver and pass refId to proxyCreator.
- Server: store object references in a Map with generated ref IDs, resolve paths with optional refId, serialize results to OBJECT_REF when shouldProxyResult returns true, and release cleans up references. Add defaultShouldProxyResult heuristic to decide which return values should remain proxied (class instances and objects with methods).
- Types: add refId fields and ObjectRef shape, expose shouldProxyResult option on RpcServerOptions, and include refId in ProxyMeta and serialized values.
- Tests updated across the suite to expect proxied return values (arrays/objects/class instances) and to await property access or method calls; add comprehensive tests for deep return value proxying, chained calls, callbacks, constructors on returned proxies, and lifecycle of remote object proxies.

These changes enable returning live/proxied remote objects (including class instances and objects with methods) from RPC calls, preserving remote behavior and allowing subsequent operations to target the same server-side object.
2026-02-02 18:43:37 +08:00
.github Add plugin data management API and frontend support 2026-01-28 13:39:36 +08:00
.vscode Update VSCode settings for formatting and file nesting 2025-11-15 17:17:24 +08:00
packages Support object references and deep proxying 2026-02-02 18:43:37 +08:00
.editorconfig refactor: 优化eslint配置,提升代码质量 (#1341) 2025-11-03 16:30:45 +08:00
.gitignore Ignore env file and db-shm in .gitignore 2026-02-02 13:22:29 +08:00
CODE_OF_CONDUCT.md doc: code of conduct 2025-03-16 09:33:06 +08:00
eslint.config.js Add ESLint config and update code style 2025-11-15 16:21:59 +08:00
LICENSE update: Limited Redistribution License 2024-11-23 18:52:53 +08:00
logo.png refactor: 整体重构 (#1381) 2025-11-13 15:39:42 +08:00
package.json Load .env, prefer WEBUI secret, add build script 2026-02-01 11:24:25 +08:00
pnpm-lock.yaml Add napcat-rpc package with deep RPC 2026-02-02 17:12:05 +08:00
pnpm-workspace.yaml refactor: 整体重构 (#1381) 2025-11-13 15:39:42 +08:00
README.md Update documentation links in README 2026-01-27 12:59:18 +08:00
SECURITY.md doc: security 2025-03-16 09:36:27 +08:00
tsconfig.base.json Add node types to package tsconfig; drop base typeRoots 2026-02-01 17:08:46 +08:00

NapCat

NapCat

Modern protocol-side framework implemented based on NTQQ.

云起兮风生,心向远方兮路未曾至.


New Feature

在 v4.8.115+ 版本开始

  1. NapCatQQ 支持 Stream Api
  2. NapCatQQ 推荐 message_id/user_id/group_id 均使用字符串类型
  • [1] 解决 Docker/跨设备/大文件 的多媒体上下传问题
  • [2] 采用字符串可以解决扩展到int64的问题同时也可以解决部分语言如JavaScript对大整数支持不佳的问题增加极少成本。

Welcome

  • NapCatQQ is a modern implementation of the Bot protocol based on NTQQ.
    • NapCatQQ 是现代化的基于 NTQQ 的 Bot 协议端实现

Feature

  • Easy to Use
    • 作为初学者能够轻松使用.
  • Quick and Efficient
    • 在低内存操作系统长时运行.
  • Rich API Interface
    • 完整实现了大部分标准接口.
  • Stable and Reliable
    • 持续稳定的开发与维护.

Quick Start

可前往 Release 页面下载最新版本

首次使用请务必查看如下文档看使用教程

项目非盈利,涉及 对接问题/基础问题/下层框架问题 请自行搜索解决,本项目社区不提供此类解答。

Docs Github.IO Cloudflare.Worker Cloudflare.HKServer
Docs Cloudflare.Pages Server.Other NapCat.Top
QQ Group QQ Group#4 QQ Group#3 QQ Group#2 QQ Group#1
Telegram Telegram
DeepWiki Ask DeepWiki

请不要在其余社区提及本项目(包括其余协议端/相关应用端项目)引发争论如有建议到达官方交流群讨论或PR。

Thanks

  • Lagrange 对本项目的大力支持 参考部分代码 已获授权

  • AstrBot 是完美适配本项目的LLM Bot框架 在此推荐一下

  • MaiBot 一只赛博群友 麦麦 Bot框架 在此推荐一下

  • qq-chat-exporter 基于NapCat的消息导出工具 在此推荐一下

  • 不过最最重要的 还是需要感谢屏幕前的你哦~


License

本项目采用 混合协议 开源,因此使用本项目时,你需要注意以下几点:

  1. 第三方库代码或修改部分遵循其原始开源许可.
  2. 本项目获取部分项目授权而不受部分约束
  3. 项目其余逻辑代码采用本仓库开源许可.

本仓库仅用于提高易用性,实现消息推送类功能,此外,禁止任何项目未经仓库主作者授权基于 NapCat 代码开发。使用请遵守当地法律法规,由此造成的问题由使用者和提供违规使用教程者负责。