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 服务的依赖：

``typescript
// 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 了
}
`

---

$3


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

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

示例:

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

---

$3

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

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

示例:

`typescript
ctx.command('my-accounts ')
.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};
});
`

---

$3

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

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

示例:

`typescript
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')};
});
`

---

$3

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

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

示例:

`typescript
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} 位用户发言。;
});
``