name: 在线状态 description: “在线状态、活动跟踪和多设备同步” emoji: “🟢”

在线状态 - 完整API参考

管理在线状态，跟踪跨设备的活动，并同步在线信息。

聊天命令

查看状态

/presence                                   显示您的状态
/presence who                               谁在线
/presence activity                          最近活动

设置状态

/presence online                            设置为在线
/presence away                              设置为离开
/presence dnd                               请勿打扰
/presence offline                           显示为离线
/presence status "会议中"                   自定义状态

设备

/presence devices                           您的连接设备
/presence sync                              强制同步所有设备

TypeScript API参考

创建在线状态服务

import { createPresenceService } from 'clodds/presence';

const presence = createPresenceService({
  // 更新间隔
  heartbeatIntervalMs: 30000,

  // 闲置后自动离开
  awayAfterMs: 300000,  // 5分钟

  // 存储
  storage: 'redis',  // 'redis' | 'memory'
  redisUrl: process.env.REDIS_URL,
});

获取状态

// 获取自身状态
const status = await presence.getStatus(userId);

console.log(`状态: ${status.status}`);  // 'online' | 'away' | 'dnd' | 'offline'
console.log(`自定义: ${status.customStatus}`);
console.log(`最后可见: ${status.lastSeen}`);
console.log(`设备: ${status.activeDevice}`);

// 获取多个用户
const statuses = await presence.getStatuses(['user-1', 'user-2', 'user-3']);

设置状态

// 设置状态
await presence.setStatus(userId, 'online');
await presence.setStatus(userId, 'away');
await presence.setStatus(userId, 'dnd');
await presence.setStatus(userId, 'offline');

// 设置自定义状态消息
await presence.setCustomStatus(userId, '交易BTC');

// 清除自定义状态
await presence.clearCustomStatus(userId);

活动跟踪

// 记录活动
await presence.recordActivity(userId, {
  type: 'message',
  channelId: 'telegram-123',
  timestamp: Date.now(),
});

// 获取最近活动
const activity = await presence.getActivity(userId, {
  limit: 10,
  since: Date.now() - 3600000,  // 过去一小时
});

for (const event of activity) {
  console.log(`${event.type} 在 ${event.timestamp}`);
  console.log(`  频道: ${event.channelId}`);
}

设备在线状态

// 获取用户的设备
const devices = await presence.getDevices(userId);

for (const device of devices) {
  console.log(`${device.id}: ${device.name}`);
  console.log(`  状态: ${device.status}`);
  console.log(`  最后可见: ${device.lastSeen}`);
  console.log(`  活跃: ${device.isActive}`);
}

// 设置设备状态
await presence.setDeviceStatus(userId, deviceId, 'online');

谁在线

// 获取在线用户
const online = await presence.getOnlineUsers({
  channelId: 'telegram-123',  // 可选：按频道过滤
});

for (const user of online) {
  console.log(`${user.name}: ${user.status}`);
}

事件处理程序

// 状态变化
presence.on('statusChange', (userId, oldStatus, newStatus) => {
  console.log(`${userId}: ${oldStatus} -> ${newStatus}`);
});

// 用户上线
presence.on('online', (userId) => {
  console.log(`${userId} 现在在线`);
});

// 用户离线
presence.on('offline', (userId) => {
  console.log(`${userId} 离线了`);
});

跨设备同步

// 强制同步
await presence.sync(userId);

// 获取同步状态
const syncStatus = await presence.getSyncStatus(userId);
console.log(`设备同步: ${syncStatus.synced}/${syncStatus.total}`);
console.log(`最后同步: ${syncStatus.lastSync}`);

状态类型

状态	描述
`online`	活跃且可用
`away`	闲置/不活跃
`dnd`	请勿打扰
`offline`	不可用

自动离开

在线状态在闲置后自动更改为 away：

const presence = createPresenceService({
  awayAfterMs: 300000,    // 5分钟闲置 -> 离开
  offlineAfterMs: 3600000, // 1小时闲置 -> 离线
});

多设备同步

当用户在多个设备上活跃时：

最近的活动决定主设备
状态在所有设备上同步
自定义状态到处共享

最佳实践

使用心跳 — 保持状态准确
适当设置离开 — 不要频繁更改状态
自定义状态 — 让他人知道您在做什么
审查设备 — 保持设备列表清洁
专注时使用DND — 交易期间静音通知