Framework 核心框架

Framework 是 EasyBot 的核心中间层，旨在解耦底层通信协议与上层业务逻辑。通过将不同的底层协议（如 OneBot11、明信、各平台原生 SDK）抽象为统一的 IAdapter 接口，开发者只需编写一套插件代码，即可无缝迁移至不同平台运行。

核心概念

IAdapter (适配器接口)

IAdapter 是所有适配器必须实现的基准接口，定义了适配器的生命周期管理、状态获取以及上下文调度。

/**
 * 抽象适配器接口
 */
interface IAdapter {
    /** 适配器名称，例如 "OneBot11" */
    AdapterName: string;
    
    /** 平台名称，例如 "qq"、"discord" */
    PlatformName: string;

    /** 适配器实例唯一 ID，用于区分同类型多实例 */
    InstanceId: string;

    /** 适配器实例显示名称（用户可读） */
    DisplayName: string;

    /** 是否在启动时自动连接 */
    StartupConnect: boolean;

    /** 启动适配器实例 */
    Start(): Promise<void>;
    
    /** 停止适配器实例 */
    Stop(): Promise<void>;
    
    /** 重启适配器实例 */
    Restart(): Promise<void>;

    /**
     * 获取当前机器人的基本信息与运行状态
     * @returns RobotProfile 包含 ID、名称、统计数据等
     */
    GetProfile(): RobotProfile;

    /**
     * 异步获取机器人加入的所有群组列表
     */
    GetGroupsAsync(): Promise<Group[]>;

    /**
     * 获取适配器上下文对象（用于高级操作）
     */
    GetAdapterContext(): IAdapterContext;
}

---

数据模型

RobotProfile (机器人资料)

描述当前登录机器人的身份信息与运行统计。

属性	类型	描述
Id	string	机器人在该平台下的唯一标识
Name	string	机器人昵称
IsActive	boolean	当前连接状态是否激活
Received	number	自启动以来接收的消息总数
Sent	number	自启动以来发送的消息总数
Started	Date	适配器启动的时间戳

Group (群组信息)

v0.4.0 破坏性变更：Id 属性已移除，改用 GroupId + Platform + FromAdapterInstance 三字段复合键。

属性	类型	描述
GroupId	string	群组唯一 ID（平台原生群号）
Platform	string	所属平台名称
FromAdapterInstance	string	所属适配器实例 ID
Name	string	群名称
GroupAvatar	string | null	群头像 URL（可能为空）
Enabled	boolean	是否在该群内启用了机器人功能
MemberCount	number	当前成员数量
MaxMemberCount	number	该群最大成员上限
Path	string (只读)	群唯一路径标识，格式：Platform.GroupId

AdapterFieldDeclaration (适配器配置字段声明)

v0.4.0 新增：适配器可声明配置字段，前端自动生成配置表单。

属性	类型	描述
FieldName	string	字段名（对应配置 JSON 中的 key）
DisplayName	string	显示名称（表单 label）
FieldType	string	字段类型：string | number | boolean | password | select
Required	boolean	是否必填
Description	string | null	帮助描述文本（可选）
DefaultValue	any	默认值（可选）
MinValue	number | null	数字类型的最小值（可选）
MaxValue	number | null	数字类型的最大值（可选）
DependsOn	string | null	条件显示 —— 依赖的字段名（可选）
DependsOnValue	any	条件显示 —— 依赖字段为何值时显示本字段（可选）
SelectOptions	string[] | null	select 类型的可选项（可选）

---

全局 API 引用

framework 命名空间提供了访问和管理所有已加载适配器的入口。

declare namespace framework {
    /**
     * 获取指定名称的适配器实例
     * @param platformName 平台名称 (如 "qq")
     * @param adapterName 适配器名称 (如 "onebot11")
     * @returns IAdapter 实例，若未找到则返回 null
     */
    function GetAdapter(platformName: string, adapterName: string): IAdapter | null;

    /**
     * 根据实例 ID 获取适配器实例
     * @param instanceId 适配器实例唯一 ID
     * @returns IAdapter 实例，若未找到则返回 null
     */
    function GetAdapterById(instanceId: string): IAdapter | null;

    /**
     * 获取当前系统加载的所有适配器列表
     */
    function GetAdapters(): IAdapter[];
}

---

使用示例

1. 获取特定机器人的名称

这是最基础的用法，通过可选链安全地获取信息。

const botName = framework.GetAdapter("qq", "onebot11")?.GetProfile().Name;
logger.info(`当前机器人名称: ${botName ?? "未知"}`);

2. 遍历所有适配器并打印状态

用于监控当前所有已连接平台的运行情况。

const adapters = framework.GetAdapters();

adapters.forEach(adapter => {
    const profile = adapter.GetProfile();
    logger.info(`[${adapter.PlatformName}] ${profile.Name} - 已接收: ${profile.Received} 条消息`);
});

3. 异步获取群组列表

获取机器人所在的所有群组名称。

async function logGroupNames() {
    const adapter = framework.GetAdapter("qq", "onebot11");
    if (!adapter) return;

    const groups = await adapter.GetGroupsAsync();
    groups.forEach(g => logger.info(`发现群组: ${g.Name} (${g.Path})`));
}

4. 根据实例 ID 获取适配器

通过实例 ID 精确定位特定适配器实例。

const adapter = framework.GetAdapterById("adapter-instance-001");
if (adapter) {
    logger.info(`适配器 ${adapter.DisplayName} 已就绪`);
}

---

提示

在编写插件时，建议优先通过 framework.GetAdapters() 动态获取实例，以增强插件对多账号、多协议的兼容能力。