@zhin.js/plugin-group-suite 0.1.0

package/skills/group-daily-analysis/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: group-daily-analysis
+description: >-
+  群日常分析：基于收件箱统计群消息数量、参与人数、活跃时段，
+  支持按群启用/禁用和定时分析报告。通过命令和定时任务运行，无 AI 工具。
+keywords:
+  - 群分析
+  - 日常分析
+  - 群统计
+  - 活跃
+  - 报告
+tags:
+  - group
+  - analysis
+  - stats
+  - inbox
+tools: []
+---
+
+# 群日常分析
+
+基于收件箱数据自动分析群活跃度。无 AI 工具可调用。
+
+## 能力
+
+- 统计群消息数量、参与人数、活跃时段分布
+- 支持按群启用/禁用分析功能
+- 定时任务自动生成分析报告推送到群内
+- 通过聊天命令管理分析设置

package/src/admin.ts

@@ -0,0 +1,145 @@
+import {
+  formatCompact,
+  MessageCommand,
+  type Plugin,
+  ZhinTool,
+} from "zhin.js";
+import { adapterAllowed } from "./shared.js";
+import type { GroupSuiteConfig } from "./config.js";
+
+export function registerAdmin(plugin: Plugin, cfg: GroupSuiteConfig): void {
+  const { addCommand, addMiddleware, addTool, logger } = plugin;
+  const welcomeTemplate = cfg.welcome;
+  const noticeAdapters = cfg.noticeAdapters;
+
+  plugin.on("notice.receive", async (notice) => {
+    if (!adapterAllowed(noticeAdapters, String(notice.$adapter))) return;
+
+    if (notice.$type === "group_member_increase") {
+      if (notice.$channel.type !== "group") return;
+      const targetName =
+        notice.$target?.name || notice.$target?.id || "新成员";
+      const welcomeMsg = `🎉 ${targetName}，${welcomeTemplate}`;
+      try {
+        const adapter = plugin.inject(notice.$adapter as never) as any;
+        if (!adapter?.sendMessage) return;
+        await adapter.sendMessage({
+          context: notice.$adapter,
+          bot: notice.$bot,
+          content: welcomeMsg,
+          id: notice.$channel.id,
+          type: notice.$channel.type,
+        });
+      } catch (e: unknown) {
+        logger.warn(
+          formatCompact({
+            op: "welcome",
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+          }),
+        );
+      }
+      return;
+    }
+
+    if (cfg.recallNotify && notice.$type === "group_recall") {
+      if (notice.$channel.type !== "group") return;
+      const operatorName =
+        notice.$operator?.name || notice.$operator?.id || "某人";
+      const msg = `⚠️ ${operatorName} 撤回了一条消息`;
+      try {
+        const adapter = plugin.inject(notice.$adapter as never) as any;
+        if (!adapter?.sendMessage) return;
+        await adapter.sendMessage({
+          context: notice.$adapter,
+          bot: notice.$bot,
+          content: msg,
+          id: notice.$channel.id,
+          type: notice.$channel.type,
+        });
+      } catch (e: unknown) {
+        logger.warn(
+          formatCompact({
+            op: "recall_notice",
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+          }),
+        );
+      }
+    }
+  });
+
+  if (!cfg.keywordReply) return;
+
+  const keywords = new Map<string, string>();
+
+  addMiddleware(async (message, next) => {
+    if (message.$channel.type !== "group") {
+      await next();
+      return;
+    }
+    const raw = message.$raw?.trim();
+    if (!raw) {
+      await next();
+      return;
+    }
+    for (const [keyword, reply] of keywords) {
+      if (raw.includes(keyword)) {
+        await message.$reply(reply);
+        return;
+      }
+    }
+    await next();
+  });
+
+  addCommand(
+    new MessageCommand("添加关键词 <keyword:text> <reply:text>")
+      .desc("添加一个关键词自动回复对")
+      .action(async (_message, result) => {
+        const { keyword, reply } = result.params as {
+          keyword: string;
+          reply: string;
+        };
+        if (!keyword || !reply) return "请提供关键词和回复内容";
+        keywords.set(keyword, reply);
+        return `已添加关键词「${keyword}」→「${reply}」`;
+      }),
+  );
+
+  addCommand(
+    new MessageCommand("删除关键词 <keyword:text>")
+      .desc("删除一个关键词")
+      .action(async (_message, result) => {
+        const { keyword } = result.params as { keyword: string };
+        if (!keyword) return "请提供要删除的关键词";
+        if (!keywords.has(keyword)) return `关键词「${keyword}」不存在`;
+        keywords.delete(keyword);
+        return `已删除关键词「${keyword}」`;
+      }),
+  );
+
+  addCommand(
+    new MessageCommand("关键词列表")
+      .desc("查看所有关键词回复对")
+      .action(async () => {
+        if (keywords.size === 0) return "当前没有设置任何关键词";
+        const lines = Array.from(keywords.entries()).map(
+          ([k, v], i) => `${i + 1}. 「${k}」→「${v}」`,
+        );
+        return `关键词列表（共 ${keywords.size} 条）：\n${lines.join("\n")}`;
+      }),
+  );
+
+  addTool(
+    new ZhinTool("group_announce")
+      .desc("向群聊发送公告/通知消息")
+      .keyword("群公告", "通知", "announce")
+      .param("message", { type: "string", description: "要发送的公告内容" }, true)
+      .execute(async (args) => {
+        const content = args.message as string;
+        if (!content?.trim()) return "公告内容不能为空";
+        return `📢 群公告：\n${content}`;
+      })
+      .toTool(),
+  );
+}

package/src/analysis.ts

@@ -0,0 +1,227 @@
+/**
+ * 群日常分析：从收件箱查询、基础统计、文本报告。
+ * 数据源为 zhin 内置 unified_inbox_message 表（需 inbox.enabled）。
+ *
+ * 话题/金句/用户画像分析逻辑灵感来自：
+ * https://github.com/SXP-Simon/astrbot_plugin_qq_group_daily_analysis
+ */
+
+export interface InboxMessageRow {
+  id?: number;
+  adapter: string;
+  bot_id: string;
+  channel_id: string;
+  channel_type: string;
+  sender_id: string;
+  sender_name: string | null;
+  content: string;
+  /** 收件箱里可能是字符串，也可能被 ORM/驱动解析成对象 */
+  raw: unknown;
+  created_at: number;
+}
+
+export interface BasicStats {
+  messageCount: number;
+  participantCount: number;
+  totalChars: number;
+  hourlyDistribution: Record<number, number>;
+  mostActiveHour: number;
+}
+
+/** 话题摘要（灵感来自 astrbot_plugin_qq_group_daily_analysis） */
+export interface SummaryTopic {
+  topic: string;
+  summary?: string;
+}
+
+/** 金句（灵感来自 astrbot_plugin_qq_group_daily_analysis） */
+export interface GoldenQuote {
+  content: string;
+  sender: string;
+  reason: string;
+}
+
+/** 用户称号/画像（灵感来自 astrbot_plugin_qq_group_daily_analysis） */
+export interface UserTitle {
+  name: string;
+  user_id: string;
+  title: string;
+  reason?: string;
+}
+
+export interface LLMAnalysis {
+  topics: SummaryTopic[];
+  quotes: GoldenQuote[];
+  userTitles: UserTitle[];
+}
+
+export interface AnalysisResult {
+  stats: BasicStats;
+  textReport: string;
+  llm?: LLMAnalysis;
+}
+
+/**
+ * 从 content (JSON) 或 raw 提取纯文本，用于统计与 LLM
+ */
+export function extractText(row: InboxMessageRow): string {
+  const raw = row.raw;
+  if (typeof raw === "string") {
+    const t = raw.trim();
+    if (t) return t;
+  }
+  // 非字符串 raw（如 icqq 存的对象）不走 trim，避免报错；改从 content 解析
+  try {
+    const c = row.content;
+    const contentStr = typeof c === "string" ? c : JSON.stringify(c ?? []);
+    const content = JSON.parse(contentStr || "[]");
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content
+        .map((part: any) => {
+          if (part?.type === "text") {
+            return part.data?.text ?? part.text ?? "";
+          }
+          return part?.text ?? "";
+        })
+        .filter(Boolean)
+        .join("");
+    }
+  } catch {
+    // ignore
+  }
+  return "";
+}
+
+/**
+ * 计算基础统计：消息数、人数、总字数、按小时分布、最活跃时段
+ */
+export function computeBasicStats(rows: InboxMessageRow[]): BasicStats {
+  const participantIds = new Set<string>();
+  let totalChars = 0;
+  const hourly: Record<number, number> = {};
+  for (let h = 0; h < 24; h++) hourly[h] = 0;
+
+  for (const row of rows) {
+    participantIds.add(row.sender_id);
+    const text = extractText(row);
+    totalChars += text.length;
+    const date = new Date(row.created_at);
+    const h = date.getHours();
+    hourly[h] = (hourly[h] || 0) + 1;
+  }
+
+  let mostActiveHour = 0;
+  let maxCount = 0;
+  for (let h = 0; h < 24; h++) {
+    if (hourly[h] > maxCount) {
+      maxCount = hourly[h];
+      mostActiveHour = h;
+    }
+  }
+
+  return {
+    messageCount: rows.length,
+    participantCount: participantIds.size,
+    totalChars,
+    hourlyDistribution: hourly,
+    mostActiveHour,
+  };
+}
+
+/**
+ * 生成纯文本报告（不含 LLM 内容）
+ */
+export function formatTextReport(
+  stats: BasicStats,
+  options: { channelName?: string; days: number; startDate: string; endDate: string }
+): string {
+  const lines: string[] = [];
+  const title = options.channelName
+    ? `【${options.channelName}】群日常分析`
+    : "群日常分析";
+  lines.push(`📊 ${title}`);
+  lines.push(`📅 统计区间：${options.startDate} 至 ${options.endDate}（最近 ${options.days} 天）`);
+  lines.push("");
+  lines.push(`💬 消息总数：${stats.messageCount} 条`);
+  lines.push(`👥 参与人数：${stats.participantCount} 人`);
+  lines.push(`📝 总字数：${stats.totalChars} 字`);
+  lines.push(`⏰ 最活跃时段：${stats.mostActiveHour}:00 - ${stats.mostActiveHour + 1}:00`);
+  lines.push("");
+  lines.push("📈 每小时消息分布：");
+  const maxH = Math.max(...Object.values(stats.hourlyDistribution), 1);
+  for (let h = 0; h < 24; h++) {
+    const c = stats.hourlyDistribution[h] || 0;
+    const bar = "█".repeat(Math.round((c / maxH) * 10)) || "░";
+    lines.push(`  ${String(h).padStart(2, "0")}:00 ${bar} ${c}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * 将 LLM 分析结果追加到文本报告。
+ * 话题/金句/用户画像 设计灵感来自 astrbot_plugin_qq_group_daily_analysis
+ */
+export function appendLLMReport(textReport: string, llm: LLMAnalysis): string {
+  const lines: string[] = [textReport, ""];
+  if (llm.topics?.length) {
+    lines.push("🔥 热门话题（LLM 提取）：");
+    llm.topics.forEach((t, i) => {
+      lines.push(`  ${i + 1}. ${t.topic}${t.summary ? ` — ${t.summary}` : ""}`);
+    });
+    lines.push("");
+  }
+  if (llm.quotes?.length) {
+    lines.push("💬 金句（LLM 筛选）：");
+    llm.quotes.forEach((q, i) => {
+      lines.push(`  ${i + 1}. 「${q.content}」 — ${q.sender}（${q.reason}）`);
+    });
+    lines.push("");
+  }
+  if (llm.userTitles?.length) {
+    lines.push("👤 用户画像/称号（LLM）：");
+    llm.userTitles.forEach((u, i) => {
+      lines.push(`  ${i + 1}. ${u.name} — ${u.title}${u.reason ? `（${u.reason}）` : ""}`);
+    });
+  }
+  return lines.join("\n");
+}
+
+/**
+ * 从 LLM 返回的文本中解析出 topics / quotes / userTitles。
+ * 约定 LLM 返回 JSON 或类似结构，此处做宽松解析。
+ */
+export function parseLLMResponse(raw: string): LLMAnalysis {
+  const result: LLMAnalysis = { topics: [], quotes: [], userTitles: [] };
+  try {
+    const trimmed = raw.trim();
+    const jsonMatch = trimmed.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      const obj = JSON.parse(jsonMatch[0]) as Record<string, unknown>;
+      if (Array.isArray(obj.topics)) {
+        result.topics = obj.topics.map((t: any) => ({
+          topic: typeof t.topic === "string" ? t.topic : String(t.topic || ""),
+          summary: typeof t.summary === "string" ? t.summary : undefined,
+        }));
+      }
+      if (Array.isArray(obj.quotes)) {
+        result.quotes = obj.quotes.map((q: any) => ({
+          content: String(q.content ?? ""),
+          sender: String(q.sender ?? ""),
+          reason: String(q.reason ?? ""),
+        }));
+      }
+      if (Array.isArray(obj.user_titles)) {
+        result.userTitles = obj.user_titles.map((u: any) => ({
+          name: String(u.name ?? ""),
+          user_id: String(u.user_id ?? ""),
+          title: String(u.title ?? ""),
+          reason: typeof u.reason === "string" ? u.reason : undefined,
+        }));
+      }
+    }
+  } catch {
+    // ignore parse errors
+  }
+  return result;
+}

package/src/checkin.ts

@@ -0,0 +1,191 @@
+import { formatCompact, MessageCommand, type Plugin } from "zhin.js";
+import type { GroupSuiteConfig } from "./config.js";
+import { getDatabase, getMessageContextKey, todayStr, ts } from "./shared.js";
+
+function yesterdayStr(): string {
+  const d = new Date();
+  d.setDate(d.getDate() - 1);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+function randomInt(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+let _db: any = null;
+
+function getModel(): any {
+  return _db?.models?.get("checkin_records") ?? null;
+}
+
+export function registerCheckin(plugin: Plugin, cfg: GroupSuiteConfig): void {
+  const { logger, addCommand, useContext } = plugin;
+
+  useContext("database", (db: any) => {
+    _db = db;
+    db.define("checkin_records", {
+      user_id: { type: "text", nullable: false },
+      user_name: { type: "text", default: "" },
+      points: { type: "integer", default: 0 },
+      total_checkins: { type: "integer", default: 0 },
+      streak: { type: "integer", default: 0 },
+      max_streak: { type: "integer", default: 0 },
+      last_checkin: { type: "text", default: "" },
+      context_type: { type: "text", default: "global" },
+      context_id: { type: "text", default: "" },
+      created_at: { type: "text", default: "" },
+      updated_at: { type: "text", default: "" },
+    });
+    logger.info(formatCompact({ op: "checkin_model" }));
+  });
+
+  async function getOrCreateUser(
+    model: any,
+    userId: string,
+    userName: string,
+    ctxType: string,
+    ctxId: string,
+  ): Promise<Record<string, unknown> | null> {
+    const rows = (await model.select().where({
+      user_id: userId,
+      context_type: ctxType,
+      context_id: ctxId,
+    })) as Record<string, unknown>[];
+    if (rows.length > 0) return rows[0];
+
+    await model.insert({
+      user_id: userId,
+      user_name: userName,
+      points: 0,
+      total_checkins: 0,
+      streak: 0,
+      max_streak: 0,
+      last_checkin: "",
+      context_type: ctxType,
+      context_id: ctxId,
+      created_at: ts(),
+      updated_at: ts(),
+    });
+
+    const created = (await model.select().where({
+      user_id: userId,
+      context_type: ctxType,
+      context_id: ctxId,
+    })) as Record<string, unknown>[];
+    return created[0] ?? null;
+  }
+
+  addCommand(
+    new MessageCommand("checkin")
+      .desc("签到", "每日签到获得积分")
+      .action(async (message) => {
+        const M = getModel();
+        if (!M) return "签到数据库尚未就绪，请稍后重试";
+
+        const userId = String(message.$sender?.id || "");
+        const userName = String(message.$sender?.name || "用户");
+        if (!userId) return "无法获取用户信息";
+
+        const { type: ctxType, id: ctxId } = getMessageContextKey(message);
+        const user = await getOrCreateUser(M, userId, userName, ctxType, ctxId);
+        if (!user) return "签到失败，请重试";
+
+        const today = todayStr();
+        if (user.last_checkin === today) {
+          return `你今天已经签到过了哦～\n当前积分: ${user.points}\n连续签到: ${user.streak} 天`;
+        }
+
+        const isConsecutive = user.last_checkin === yesterdayStr();
+        const newStreak = isConsecutive ? Number(user.streak) + 1 : 1;
+        const base = randomInt(cfg.basePointsMin, cfg.basePointsMax);
+        const bonus = Math.min(newStreak * cfg.streakBonus, cfg.streakCap);
+        const earned = base + bonus;
+        const newPoints = Number(user.points || 0) + earned;
+
+        await M.update({
+          points: newPoints,
+          total_checkins: Number(user.total_checkins || 0) + 1,
+          streak: newStreak,
+          max_streak: Math.max(Number(user.max_streak || 0), newStreak),
+          last_checkin: today,
+          user_name: userName,
+          updated_at: ts(),
+        }).where({ id: user.id });
+
+        const lines = [`签到成功！`, `基础积分: +${base}`];
+        if (bonus > 0) lines.push(`连续奖励: +${bonus} (连续${newStreak}天)`);
+        lines.push(`本次获得: +${earned}`, `当前积分: ${newPoints}`);
+        return lines.join("\n");
+      }),
+  );
+
+  addCommand(
+    new MessageCommand("mypoints")
+      .desc("我的积分", "查看个人积分与签到信息")
+      .action(async (message) => {
+        const M = getModel();
+        if (!M) return "签到数据库尚未就绪";
+        const userId = String(message.$sender?.id || "");
+        const { type: ctxType, id: ctxId } = getMessageContextKey(message);
+        const rows = (await M.select().where({
+          user_id: userId,
+          context_type: ctxType,
+          context_id: ctxId,
+        })) as Record<string, unknown>[];
+        if (rows.length === 0) return "你还没有签到记录哦，发送「签到」开始吧！";
+        const u = rows[0];
+        const checkedToday = u.last_checkin === todayStr();
+        return [
+          `${u.user_name || "用户"} 的积分信息`,
+          `积分: ${u.points}`,
+          `累计签到: ${u.total_checkins} 天`,
+          `连续签到: ${u.streak} 天`,
+          `最长连续: ${u.max_streak} 天`,
+          checkedToday ? "今日已签到 ✓" : "今日未签到",
+        ].join("\n");
+      }),
+  );
+
+  addCommand(
+    new MessageCommand("rank")
+      .desc("积分排行", "查看积分排行榜")
+      .action(async (message) => {
+        const M = getModel();
+        if (!M) return "签到数据库尚未就绪";
+        const { type: ctxType, id: ctxId } = getMessageContextKey(message);
+        const all = (await M.select().where(
+          ctxType === "global"
+            ? { context_type: "global" }
+            : { context_type: ctxType, context_id: ctxId },
+        )) as Record<string, unknown>[];
+        if (all.length === 0) return "还没有人签到过哦～";
+        const sorted = all.sort(
+          (a, b) => Number(b.points || 0) - Number(a.points || 0),
+        );
+        const top = sorted.slice(0, cfg.rankSize);
+        const medals = ["🥇", "🥈", "🥉"];
+        const lines = top.map((u, i) => {
+          const prefix = i < 3 ? medals[i] : `${i + 1}.`;
+          return `${prefix} ${u.user_name || u.user_id} — ${u.points}分 (${u.total_checkins}天)`;
+        });
+        const title = ctxType === "group" ? "本群积分排行" : "全局积分排行";
+        const userId = String(message.$sender?.id || "");
+        const myRank = sorted.findIndex((u) => u.user_id === userId);
+        const footer = myRank >= 0 ? `\n你的排名: 第${myRank + 1}名` : "";
+        return `${title}\n${lines.join("\n")}${footer}`;
+      }),
+  );
+
+  if (!_db) {
+    const db = getDatabase(plugin);
+    if (db) _db = db;
+  }
+
+  logger.info(
+    formatCompact({
+      op: "checkin_load",
+      base_min: cfg.basePointsMin,
+      base_max: cfg.basePointsMax,
+    }),
+  );
+}

package/src/config.ts

@@ -0,0 +1,72 @@
+import { Schema } from "zhin.js";
+
+/** 扁平 groupSuite 配置（单层字段，默认值覆盖多数场景） */
+export const groupSuiteSchema = Schema.object({
+  welcome: Schema.string()
+    .default("欢迎新成员加入本群！")
+    .description("入群欢迎语"),
+  recallNotify: Schema.boolean()
+    .default(true)
+    .description("群消息撤回时是否提示"),
+  keywordReply: Schema.boolean()
+    .default(false)
+    .description("内置关键词回复（默认关闭，用 teach 问答）"),
+  noticeAdapters: Schema.list(Schema.string())
+    .default(["icqq"])
+    .description("处理 notice 的适配器（欢迎/撤回）"),
+
+  basePointsMin: Schema.number().default(10).min(1).max(100),
+  basePointsMax: Schema.number().default(30).min(1).max(200),
+  streakBonus: Schema.number().default(5).min(0).max(100),
+  streakCap: Schema.number().default(50).min(0).max(500),
+
+  rankSize: Schema.number()
+    .default(10)
+    .min(3)
+    .max(50)
+    .description("签到排行与消息统计排行显示人数"),
+  statsRetentionDays: Schema.number().default(90).min(7).max(365),
+
+  analysisDays: Schema.number().default(1).min(1).max(30),
+  autoAnalysisEnabled: Schema.boolean().default(false),
+  autoAnalysisCron: Schema.string().default("0 9 * * *"),
+  analysisGroups: Schema.list(Schema.string())
+    .default([])
+    .description("启用群日报的群 ID 白名单（空=不限制）"),
+  analysisGroupsBlock: Schema.list(Schema.string())
+    .default([])
+    .description("禁用群日报的群 ID"),
+  analysisFormat: Schema.string()
+    .default("text")
+    .description("日报格式 text | image"),
+  analysisMaxMessages: Schema.number().default(500).min(100).max(5000),
+
+  teachMaxPerGroup: Schema.number().default(200).min(1).max(1000),
+  teachCooldownMs: Schema.number().default(3000).min(0).max(60000),
+  teachAllowRegex: Schema.boolean().default(true),
+  teachPageSize: Schema.number().default(10).min(5).max(50),
+});
+
+export type GroupSuiteConfig = {
+  welcome: string;
+  recallNotify: boolean;
+  keywordReply: boolean;
+  noticeAdapters: string[];
+  basePointsMin: number;
+  basePointsMax: number;
+  streakBonus: number;
+  streakCap: number;
+  rankSize: number;
+  statsRetentionDays: number;
+  analysisDays: number;
+  autoAnalysisEnabled: boolean;
+  autoAnalysisCron: string;
+  analysisGroups: string[];
+  analysisGroupsBlock: string[];
+  analysisFormat: string;
+  analysisMaxMessages: number;
+  teachMaxPerGroup: number;
+  teachCooldownMs: number;
+  teachAllowRegex: boolean;
+  teachPageSize: number;
+};