Models - 数据模型

EasyBot 机器人框架中的核心数据模型类，用于表示用户、群成员和机器人的基本信息。

UserProfile - 用户资料

用户基本信息的数据结构。

declare class UserProfile {
    Id: string;        // 用户唯一标识
    Name: string;      // 用户名称
    Nick?: string;     // 用户昵称（可选）
}

属性

Id

• 类型: string
• 描述: 用户的唯一标识符
• 必需: 是

Name

• 类型: string
• 描述: 用户的名称
• 必需: 是

Nick

• 类型: string | undefined
• 描述: 用户的昵称
• 必需: 否

使用示例

// 获取用户资料
const profile = await context.GetUserProfileAsync(selfId, userId);
logger.info(`用户ID: ${profile.Id}`);
logger.info(`用户名: ${profile.Name}`);
if (profile.Nick) {
    logger.info(`昵称: ${profile.Nick}`);
}

// 创建用户资料对象
const newProfile = new UserProfile();
newProfile.Id = "123456789";
newProfile.Name = "张三";
newProfile.Nick = "小张";

MemberInfo - 群成员信息

群组成员详细信息的数据结构。

declare class MemberInfo {
    GroupId: number;    // 群组ID
    UserId: number;     // 用户ID
    NickName: string;   // 用户昵称
    Card: string;       // 群名片
    Sex: string;        // 性别
    Age: number;        // 年龄
    Role: string;       // 群内角色
    Title: string;      // 专属头衔
}

属性

GroupId

• 类型: number
• 描述: 群组的唯一标识符
• 必需: 是

UserId

• 类型: number
• 描述: 用户的唯一标识符
• 必需: 是

NickName

• 类型: string
• 描述: 用户的昵称
• 必需: 是

Card

• 类型: string
• 描述: 用户在群内的名片（群昵称）
• 必需: 是

Sex

• 类型: string
• 描述: 用户性别
• 可能值: "male", "female", "unknown"
• 必需: 是

Age

• 类型: number
• 描述: 用户年龄
• 必需: 是

Role

• 类型: string
• 描述: 用户在群内的角色
• 可能值: "owner", "admin", "member"
• 必需: 是

Title

• 类型: string
• 描述: 用户的专属头衔
• 必需: 是

使用示例

// 获取群成员信息
const member = await context.GetGroupMemberInfo(groupId, userId);
logger.info(`群ID: ${member.GroupId}`);
logger.info(`用户ID: ${member.UserId}`);
logger.info(`昵称: ${member.NickName}`);
logger.info(`群名片: ${member.Card}`);
logger.info(`性别: ${member.Sex}`);
logger.info(`年龄: ${member.Age}`);
logger.info(`角色: ${member.Role}`);
logger.info(`头衔: ${member.Title}`);

// 检查用户权限
if (member.Role === "owner" || member.Role === "admin") {
    logger.info("用户具有管理权限");
}

// 获取群成员列表
const members = await context.GetGroupMemberList(groupId);
const adminCount = members.filter(m => m.Role === "admin").length;
logger.info(`群内管理员数量: ${adminCount}`);

RobotProfile - 机器人资料

机器人基本信息的数据结构。

declare class RobotProfile {
    Id: string;         // 机器人ID
    Name: string;       // 机器人名称
    IsActive: boolean;  // 是否活跃状态
}

属性

Id

• 类型: string
• 描述: 机器人的唯一标识符
• 必需: 是

Name

• 类型: string
• 描述: 机器人的名称
• 必需: 是

IsActive

• 类型: boolean
• 描述: 机器人是否处于活跃状态
• 必需: 是

使用示例

// 在机器人就绪事件中获取机器人信息
bus.on("bot_ready_event", (event) => {
    const robot = event.Profile;
    logger.info(`机器人ID: ${robot.Id}`);
    logger.info(`机器人名称: ${robot.Name}`);
    logger.info(`活跃状态: ${robot.IsActive ? "活跃" : "非活跃"}`);
});

// 在机器人掉线事件中处理
bus.on("bot_offline_event", (event) => {
    const robot = event.Profile;
    logger.info(`机器人 ${robot.Name} (${robot.Id}) 已掉线`);
    logger.info(`掉线原因: ${event.Reason}`);
});

// 创建机器人资料对象
const robotProfile = new RobotProfile();
robotProfile.Id = "bot123";
robotProfile.Name = "助手机器人";
robotProfile.IsActive = true;

实际应用示例

用户权限检查

bus.on("group_message_event", async (event) => {
    if (event.RawMessage.startsWith("/admin")) {
        // 获取发送者的群成员信息
        const member = await event.AdapterContext.GetGroupMemberInfo(
            event.PeerId, 
            event.SenderId
        );
        
        // 检查权限
        if (member.Role === "owner" || member.Role === "admin") {
            await event.Context.Reply(new MessageChain().Text("管理员命令执行成功"));
        } else {
            await event.Context.Reply(new MessageChain().Text("权限不足"));
        }
    }
});

群成员统计

async function getGroupStats(context, groupId) {
    const members = await context.GetGroupMemberList(groupId);
    
    const stats = {
        total: members.length,
        male: members.filter(m => m.Sex === "male").length,
        female: members.filter(m => m.Sex === "female").length,
        admins: members.filter(m => m.Role === "admin").length,
        owner: members.filter(m => m.Role === "owner").length
    };
    
    return stats;
}

// 使用示例
bus.on("group_message_event", async (event) => {
    if (event.RawMessage === "/stats") {
        const stats = await getGroupStats(event.AdapterContext, event.PeerId);
        
        const reply = new MessageChain()
            .Text(`群成员统计:`)
            .NextLine()
            .Text(`总人数: ${stats.total}`)
            .NextLine()
            .Text(`男性: ${stats.male}, 女性: ${stats.female}`)
            .NextLine()
            .Text(`管理员: ${stats.admins}, 群主: ${stats.owner}`);
            
        await event.Context.Reply(reply);
    }
});

机器人状态监控

const robotStatus = new Map();

bus.on("bot_ready_event", (event) => {
    robotStatus.set(event.Profile.Id, {
        name: event.Profile.Name,
        isOnline: true,
        lastSeen: new Date()
    });
    
    logger.info(`机器人 ${event.Profile.Name} 上线`);
});

bus.on("bot_offline_event", (event) => {
    const status = robotStatus.get(event.Profile.Id);
    if (status) {
        status.isOnline = false;
        status.lastSeen = new Date();
    }
    
    logger.info(`机器人 ${event.Profile.Name} 离线: ${event.Reason}`);
});

// 获取机器人状态
function getRobotStatus(robotId) {
    return robotStatus.get(robotId);
}

注意事项

1. 类型安全: 所有属性都有明确的类型定义
2. 可选属性: 注意 UserProfile 的 Nick 属性是可选的
3. 数据类型: GroupId 和 UserId 在 MemberInfo 中是 number 类型
4. 权限检查: 使用 Role 属性进行权限验证
5. 状态监控: 使用 IsActive 属性监控机器人状态