koishi-plugin-jx3broadcast

jx3-help 的自定义群发服务插件。

它用于替代直接调用 ctx.broadcast() 的批量推送场景，提供随机发送间隔、每群独立生成消息、在线 bot 过滤和更清晰的发送结果统计。

功能特性

• 按 Koishi channel.assignee 将目标群分配给负责的 bot。
• 默认跳过 Koishi silent 频道，支持 forced 强制发送。
• 只使用 Universal.Status.ONLINE 状态的 bot 发送消息。
• 同一个 bot 内部串行发送，并在配置范围内随机等待。
• 不同 bot 之间并行发送。
• 每个目标群发送前单独调用消息生成函数，可生成差异化消息。
• 返回成功、失败、跳过、未命中目标的完整统计。
• 注册全局消息组件 <kaomoji />，用于在消息中插入随机颜文字。

配置

plugins:
  group:bgk8b7:
    jx3broadcast:6pq9wb:
      minDelay: 1500
      maxDelay: 3000

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | minDelay | number | 1500 | 同一 bot 连续发送两条群消息之间的最小随机间隔，单位毫秒。 | | maxDelay | number | 3000 | 同一 bot 连续发送两条群消息之间的最大随机间隔，单位毫秒。 |

如果单次调用传入的 minDelay 大于 maxDelay，服务会自动交换两个值。

注入服务

消费者插件需要声明依赖：

export const inject = ["database", "jx3broadcast"];

并导入类型扩展：

import {} from "koishi-plugin-jx3broadcast";

之后即可通过 ctx.jx3broadcast 调用群发服务。

基本用法

await ctx.jx3broadcast.broadcast(sendList, () => (
  <p>刀豆提醒！世界 BOSS 活动即将开启。</p>
));

sendList 的格式与 Koishi ctx.broadcast() 一致：

const sendList = ["onebot:123456789", "onebot:987654321"];

每群生成不同消息

消息生成函数会在每个目标群发送前调用一次，并接收当前目标上下文：

await ctx.jx3broadcast.broadcast(sendList, ({ channel, index, total }) => (
  <p>
    群 {channel.guildId} 的专属提醒：这是第 {index + 1}/{total} 个目标。
  </p>
));

可用上下文包括：

| 字段 | 说明 | | --- | --- | | channel | 当前目标频道记录，包含 id、platform、guildId、locales、assignee。 | | session | 为当前目标构造的临时 Koishi session。 | | bot | 负责发送当前目标消息的 bot。 | | index | 当前目标序号，从 0 开始。 | | total | 本次实际进入发送流程的目标总数。 |

单次覆盖发送间隔

await ctx.jx3broadcast.broadcast(
  sendList,
  () => <p>这条消息使用更慢的群发间隔。</p>,
  {
    minDelay: 3000,
    maxDelay: 8000,
  }
);

强制发送 silent 频道

默认行为与 Koishi ctx.broadcast() 一致：跳过带 Channel.Flag.silent 标记的频道。

如需强制发送：

await ctx.jx3broadcast.broadcast(
  sendList,
  () => <p>强制发送消息。</p>,
  {
    forced: true,
  }
);

发送结果

const result = await ctx.jx3broadcast.broadcast(sendList, () => "测试消息");

ctx.logger("demo").info(
  `成功：${result.success}，失败：${result.failed.length}，跳过：${result.skipped.length}，未命中：${result.missing.length}`
);

返回结构：

interface BroadcastResult {
  messageIds: string[];
  success: number;
  failed: BroadcastFailure[];
  skipped: BroadcastSkipped[];
  missing: string[];
}

跳过原因：

| reason | 说明 | | --- | --- | | empty | 消息生成函数返回空内容。 | | silent | 目标频道带 Koishi silent 标记，且本次没有传 forced: true。 | | offline | 负责发送该频道的 bot 不是 Universal.Status.ONLINE。 |

失败阶段：

| stage | 说明 | | --- | --- | | generate | 消息生成函数抛错。 | | send | 调用 bot.sendMessage() 失败。 |

全局消息组件

插件会注册 Koishi 全局消息组件：

<kaomoji />

示例：

await ctx.jx3broadcast.broadcast(sendList, () => (
  <p>
    早上好！刀豆给大家准备了今日日常！
    <kaomoji />
  </p>
));

<kaomoji /> 每次被 Koishi 渲染时都会从 KAOMOJI_LIST 中随机取一个颜文字。

也可以直接使用工具函数：

import { randomKaomoji } from "koishi-plugin-jx3broadcast";

const text = `今天也要开心 ${randomKaomoji()}`;

注意事项

• 本服务不会修改 Koishi 官方 ctx.broadcast()。
• 本服务依赖数据库中的 channel.assignee，目标频道必须已经在 Koishi channel 表中并分配给当前 bot。
• 如果 bot 在状态检查后立刻断线，bot.sendMessage() 仍可能失败；服务会记录到 result.failed 并继续后续目标。
• 只检查 bot 是否 ONLINE，不会预先检查机器人是否仍在目标群内；退群、禁言、风控等错误会在发送阶段体现。