NapCatQQ/packages/napcat-protocol/README.md

NapCat Protocol Manager

统一管理 NapCat 的多协议适配器（OneBot 和 Satori）。

特性

• 🔌 统一接口: 提供统一的协议管理接口
• 🎯 插件化设计: 支持动态注册和管理协议适配器
• 🔄 热重载: 支持协议配置的热重载
• 📦 开箱即用: 内置 OneBot11 和 Satori 协议支持

架构

napcat-protocol
├── types.ts              # 协议接口定义
├── manager.ts            # 协议管理器
├── adapters/
│   ├── onebot.ts        # OneBot11 协议适配器包装
│   └── satori.ts        # Satori 协议适配器包装
└── index.ts             # 导出入口

使用方法

基础使用

import { ProtocolManager } from 'napcat-protocol';

// 创建协议管理器
const protocolManager = new ProtocolManager(core, context, pathWrapper);

// 初始化所有协议
await protocolManager.initAllProtocols();

// 获取协议适配器
const onebotAdapter = protocolManager.getOneBotAdapter();
const satoriAdapter = protocolManager.getSatoriAdapter();

单独初始化协议

// 只初始化 OneBot11
await protocolManager.initProtocol('onebot11');

// 只初始化 Satori
await protocolManager.initProtocol('satori');

获取原始适配器

// 获取 OneBot 原始适配器
const onebotAdapter = protocolManager.getOneBotAdapter();
if (onebotAdapter) {
  const rawOneBot = onebotAdapter.getRawAdapter();
  // 使用 NapCatOneBot11Adapter 的所有功能
}

// 获取 Satori 原始适配器
const satoriAdapter = protocolManager.getSatoriAdapter();
if (satoriAdapter) {
  const rawSatori = satoriAdapter.getRawAdapter();
  // 使用 NapCatSatoriAdapter 的所有功能
}

配置重载

// 重载 OneBot 配置
await protocolManager.reloadProtocolConfig('onebot11', prevConfig, newConfig);

// 重载 Satori 配置
await protocolManager.reloadProtocolConfig('satori', prevConfig, newConfig);

查询协议状态

// 获取所有已注册的协议信息
const protocols = protocolManager.getRegisteredProtocols();

// 检查协议是否已初始化
const isInitialized = protocolManager.isProtocolInitialized('onebot11');

// 获取所有已初始化的协议ID
const initializedIds = protocolManager.getInitializedProtocolIds();

销毁协议

// 销毁指定协议
await protocolManager.destroyProtocol('onebot11');

// 销毁所有协议
await protocolManager.destroyAllProtocols();

在 Framework 中使用

// packages/napcat-framework/napcat.ts
import { ProtocolManager } from 'napcat-protocol';

const protocolManager = new ProtocolManager(core, context, pathWrapper);
await protocolManager.initAllProtocols();

// 注册到 WebUI
const onebotAdapter = protocolManager.getOneBotAdapter();
if (onebotAdapter) {
  WebUiDataRuntime.setOneBotContext(onebotAdapter.getRawAdapter());
}

const satoriAdapter = protocolManager.getSatoriAdapter();
if (satoriAdapter) {
  WebUiDataRuntime.setSatoriContext(satoriAdapter.getRawAdapter());
}

在 Shell 中使用

// packages/napcat-shell/base.ts
import { ProtocolManager } from 'napcat-protocol';

export class NapCatShell {
  public protocolManager?: ProtocolManager;

  async InitNapCat() {
    await this.core.initCore();
    
    this.protocolManager = new ProtocolManager(
      this.core, 
      this.context, 
      this.context.pathWrapper
    );
    
    await this.protocolManager.initAllProtocols();
  }
}

扩展自定义协议

如果需要添加新的协议支持，可以实现 IProtocolAdapter 和 IProtocolAdapterFactory 接口：

import { IProtocolAdapter, IProtocolAdapterFactory } from 'napcat-protocol';

// 实现协议适配器
class MyProtocolAdapter implements IProtocolAdapter {
  readonly name = 'MyProtocol';
  readonly id = 'myprotocol';
  readonly version = '1.0.0';
  readonly description = '我的自定义协议';

  async init(): Promise<void> {
    // 初始化逻辑
  }

  async destroy(): Promise<void> {
    // 清理逻辑
  }

  async reloadConfig(prevConfig: unknown, newConfig: unknown): Promise<void> {
    // 配置重载逻辑
  }
}

// 实现工厂
class MyProtocolAdapterFactory implements IProtocolAdapterFactory {
  readonly protocolId = 'myprotocol';
  readonly protocolName = 'MyProtocol';
  readonly protocolVersion = '1.0.0';
  readonly protocolDescription = '我的自定义协议';

  create(core, context, pathWrapper) {
    return new MyProtocolAdapter(core, context, pathWrapper);
  }
}

// 注册到管理器
protocolManager.registerFactory(new MyProtocolAdapterFactory());
await protocolManager.initProtocol('myprotocol');

API 文档

ProtocolManager

方法

• registerFactory(factory: IProtocolAdapterFactory): 注册协议工厂
• getRegisteredProtocols(): 获取所有已注册的协议信息
• initProtocol(protocolId: string): 初始化指定协议
• initAllProtocols(): 初始化所有协议
• destroyProtocol(protocolId: string): 销毁指定协议
• destroyAllProtocols(): 销毁所有协议
• getAdapter<T>(protocolId: string): 获取协议适配器
• getOneBotAdapter(): 获取 OneBot 协议适配器
• getSatoriAdapter(): 获取 Satori 协议适配器
• reloadProtocolConfig(protocolId, prevConfig, newConfig): 重载协议配置
• isProtocolInitialized(protocolId: string): 检查协议是否已初始化
• getInitializedProtocolIds(): 获取所有已初始化的协议ID

IProtocolAdapter

协议适配器接口，所有协议适配器都需要实现此接口。

属性

• name: string: 协议名称
• id: string: 协议ID
• version: string: 协议版本
• description: string: 协议描述

方法

• init(): 初始化协议适配器
• destroy(): 销毁协议适配器
• reloadConfig(prevConfig, newConfig): 重载配置

IProtocolAdapterFactory

协议适配器工厂接口，用于创建协议适配器实例。

属性

• protocolId: string: 协议ID
• protocolName: string: 协议名称
• protocolVersion: string: 协议版本
• protocolDescription: string: 协议描述

方法

• create(core, context, pathWrapper): 创建协议适配器实例

依赖

• napcat-core: NapCat 核心
• napcat-common: NapCat 通用工具
• napcat-onebot: OneBot11 协议实现
• napcat-satori: Satori 协议实现

许可证

与 NapCat 主项目保持一致