user-presence 插件开发文档

user-presence 是一个为 Koishi 设计的基础服务插件。它旨在解决两个核心问题：用户身份的统一管理和群组用户活跃度的追踪。

通过提供一套稳定、简洁的 API，其他插件可以轻松地实现以下功能，而无需关心底层的实现细节：

• 在不同平台的用户ID和 Koishi 内部的全局UID之间进行转换。
• 获取在特定时间段内（如30天）在群聊中发言过的活跃用户列表。
• 自动记录用户活动并定期清理不活跃数据，保持数据库的整洁和高效。

✨ 核心功能

• 双向ID转换: 轻松实现 平台ID -> UID 和 UID -> 平台ID 的查询。
• 自动活动追踪: 自动监听群聊消息，记录用户的最后发言时间。
• 可配置数据保留: 可自由配置用户活动记录的保留天数（默认为30天）。
• 定时自动清理: 使用 cron 任务在指定时间（默认为每天零点）自动删除过期的用户记录。
• 简洁的服务API: 所有功能都通过 ctx.presence 服务暴露，方便其他插件调用。

📖 API 参考

一旦 user-presence 插件被正确加载，您就可以在其他插件中通过 ctx.presence 来访问其提供的所有服务。

首先，在您的插件中声明对 presence 服务的依赖：

// your-plugin/index.ts
import { Context } from 'koishi'

export const name = 'my-cool-plugin'
// 声明对 presence 服务的依赖
export const inject = ['presence']

export function apply(ctx: Context) {
  // 现在可以安全地使用 ctx.presence 了
}

ctx.presence.getUid()

根据平台名称和平台特定的用户ID，查询该用户在 Koishi 中的全局唯一ID (uid)。

• 签名: async getUid(platform: string, userId: string): Promise<number | null>
• 参数:
  • platform: string - 平台名称，例如 'onebot', 'discord', 'kook'。
  • userId: string - 用户在该平台上的ID。
• 返回值: Promise<number | null> - 如果找到用户，则返回其 uid (一个数字)；否则返回 null。

示例:

ctx.command('my-uid')
  .action(async ({ session }) => {
    const uid = await ctx.presence.getUid(session.platform, session.userId);
    if (uid) {
      return `您的全局 UID 是: ${uid}`;
    } else {
      return '抱歉，无法在数据库中找到您的记录。';
    }
  });

ctx.presence.getBindings()

根据 Koishi 的全局唯一ID (uid)，反向查询该用户绑定的所有平台账户。一个用户可能在不同平台有多个账户，因此返回的是一个数组。

• 签名: async getBindings(uid: number): Promise<{ platform: string; userId: string }[]>
• 参数:
  • uid: number - Koishi 的全局唯一ID。
• 返回值: Promise<{ platform: string; userId: string }[]> - 一个包含用户所有绑定信息的对象数组。如果该 uid 没有任何绑定，则返回一个空数组。

示例:

ctx.command('my-accounts <uid:number>')
  .action(async ({}, uid) => {
    const accounts = await ctx.presence.getBindings(uid);
    if (accounts.length === 0) {
      return `UID ${uid} 没有绑定任何平台账户。`;
    }
    const accountList = accounts.map(acc => `- ${acc.platform}: ${acc.userId}`).join('\n');
    return `UID ${uid} 绑定的账户有：\n${accountList}`;
  });

ctx.presence.getGuildMembers()

获取指定群组内，在配置的 retentionDays 时间段内所有活跃过（即发过言）的用户的列表。

• 签名: async getGuildMembers(platform: string, guildId: string): Promise<string[]>
• 参数:
  • platform: string - 平台名称。
  • guildId: string - 群组/频道的ID。
• 返回值: Promise<string[]> - 一个字符串数组，其中包含所有活跃用户的平台用户ID (userId)。

示例:

ctx.command('active-list', '查看本群活跃用户列表')
  .guild() // 限制在群聊中使用
  .action(async ({ session }) => {
    const members = await ctx.presence.getGuildMembers(session.platform, session.guildId);
    if (members.length === 0) {
      return '最近本群还没有人发言哦。';
    }
    return `本群最近的活跃用户列表：\n${members.join('\n')}`;
  });

ctx.presence.getGuildMemberCount()

获取指定群组的活跃用户数量。这比获取完整列表然后计算长度更高效。

• 签名: async getGuildMemberCount(platform: string, guildId: string): Promise<number>
• 参数:
  • platform: string - 平台名称。
  • guildId: string - 群组/频道的ID。
• 返回值: Promise<number> - 活跃用户的总数。

示例:

ctx.command('active-count', '查看本群活跃人数')
  .guild()
  .action(async ({ session }) => {
    const count = await ctx.presence.getGuildMemberCount(session.platform, session.guildId);
    const days = ctx.config.retentionDays; // 可以从插件配置中获取保留天数
    return `在过去 ${days} 天内，本群共有 ${count} 位用户发言。`;
  });