@zhin.js/plugin-group-suite 1.1.7 → 1.1.8

package/src/keywords.ts

@@ -0,0 +1,72 @@
+import { createDeliveryTarget, databaseHostToken, type Token } from 'zhin.js';
+import type { GroupSuiteConfig } from './config.js';
+import type { ConversationInput } from './conversation-scope.js';
+import { requireConversation } from './conversation-scope.js';
+import { keywordStore } from './keyword-store.js';
+import { resolveGroupSuiteRuntime } from './runtime-state.js';
+
+export const KEYWORD_STORAGE_REQUIREMENT = '关键词管理需要 Database Host 的持久状态服务；请配置数据库，或显式设置 ephemeralKeywords: true 使用临时词库';
+class KeywordStorageRequirementError extends Error {}
+const MAX_KEYWORD_BYTES = 64 * 1024;
+
+type KeywordRows = readonly (readonly [string, string])[];
+interface KeywordContext {
+  readonly config: Readonly<Partial<GroupSuiteConfig>>;
+  use<T>(token: Token<T>): T;
+}
+
+/** Persistent owner + exact conversation state; volatile storage requires an explicit opt-in. */
+export function keywords(input: ConversationInput | undefined, context: KeywordContext) {
+  const target = requireConversation(input ?? {});
+  if (target.kind !== 'group') throw new Error('Keywords require a group conversation');
+  if (context.config.ephemeralKeywords === true) {
+    const store = keywordStore({ conversation: target }, resolveGroupSuiteRuntime(context));
+    return {
+      read: async () => [...store.entries()] as KeywordRows,
+      update: async (updater: (current: Map<string, string>) => void) => {
+        const next = new Map(store);
+        updater(next);
+        assertLimit(next);
+        store.clear();
+        for (const [key, value] of next) store.set(key, value);
+      },
+    };
+  }
+  const hostState = (() => {
+    try { return context.use(databaseHostToken).state; }
+    catch (cause) { throw new KeywordStorageRequirementError(KEYWORD_STORAGE_REQUIREMENT, { cause }); }
+  })();
+  const state = hostState.forConversation(createDeliveryTarget({ conversation: target }));
+  return {
+    read: async () => (await state.get<KeywordRows>('keywords')) ?? [],
+    update: async (updater: (current: Map<string, string>) => void) => {
+      await state.update<KeywordRows>('keywords', current => {
+        const next = new Map(current ?? []);
+        updater(next);
+        assertLimit(next);
+        return [...next.entries()];
+      });
+    },
+  };
+}
+
+/** Management commands surface a storage requirement instead of inventing an empty dictionary. */
+export function keywordsForCommand(input: ConversationInput | undefined, context: KeywordContext) {
+  try { return keywords(input, context); }
+  catch (error) {
+    if (error instanceof KeywordStorageRequirementError) return error.message;
+    throw error;
+  }
+}
+
+function assertLimit(store: Map<string, string>): void {
+  if (store.size > 200) throw new Error('Group keywords are limited to 200 entries');
+  if (new TextEncoder().encode(JSON.stringify([...store.entries()])).byteLength >= MAX_KEYWORD_BYTES) {
+    throw new Error('Keyword dictionary JSON must be below 64 KiB (UTF-8); shorten replies or remove entries');
+  }
+  for (const [keyword, reply] of store) {
+    if (!keyword || keyword.length > 200 || !reply || reply.length > 2000) {
+      throw new Error('Keyword must contain 1–200 characters and reply 1–2000 characters');
+    }
+  }
+}

package/src/runtime-state.ts

@@ -7,14 +7,18 @@ export interface PendingStatsIncrement {
   group_id: string;
   date: string;
   count: number;
+  recorded: number;
+  flushed: number;
 }
 
 /** All mutable state owned by one group-suite plugin instance. */
 export interface GroupSuiteRuntime {
   readonly db: GroupSuiteMemoryDb;
-  readonly keywords: Map<string, string>;
+  readonly keywords: Map<string, Map<string, string>>;
   readonly teachCooldowns: Map<string, number>;
   readonly statsBuffer: Map<string, PendingStatsIncrement>;
+  /** Serialized finite batches shared by admitted queries and scheduler calls. */
+  statsFlush?: Promise<void>;
   readonly checkinChains: Map<string, Promise<unknown>>;
 }
 

package/src/shared-runtime.ts

@@ -1,3 +1,4 @@
+import { conversationKey, requireConversation, type ConversationInput } from './conversation-scope.js';
 export function todayStr(): string {
   const d = new Date();
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
@@ -17,20 +18,10 @@ export function randomInt(min: number, max: number): number {
   return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 
-/** Runtime Message → group/global context */
-export function resolveContextKey(input: {
-  conversation?: { readonly kind?: string; readonly id?: string };
-  metadata?: Readonly<Record<string, unknown>>;
-}): { type: string; id: string } {
-  const meta = input.metadata ?? {};
-  const channelType = String(meta.type ?? meta.channelType ?? '');
-  if (channelType === 'group' || channelType === 'guild' || channelType === 'channel') {
-    return { type: 'group', id: String(meta.channelId ?? input.conversation?.id ?? '') };
-  }
-  if (input.conversation && channelType !== 'private') {
-    return { type: 'group', id: String(input.conversation.id ?? '') };
-  }
-  return { type: 'global', id: '' };
+/** Every scene includes endpoint, parent and thread; no cross-bot global fallback. */
+export function resolveContextKey(input: ConversationInput): { type: string; id: string } {
+  const target = requireConversation(input);
+  return { type: target.kind, id: conversationKey(target) };
 }
 
 export function resolveSender(input: {

package/src/stats-lib.ts

@@ -1,3 +1,4 @@
+import { conversationKey, requireConversation, type ConversationInput } from './conversation-scope.js';
 import type { GroupSuiteConfig } from './config.js';
 import { getStatsModel } from './db-store.js';
 import {
@@ -26,29 +27,14 @@ export function monthStartStr(): string {
 }
 
 function bufferKey(userId: string, groupId: string, date: string): string {
-  return `${userId}:${groupId}:${date}`;
+  return JSON.stringify([userId, groupId, date]);
 }
 
-export function resolveGroupId(input: {
-  conversation?: { readonly kind?: string; readonly id?: string };
-  metadata?: Readonly<Record<string, unknown>>;
-}): string {
-  const meta = input.metadata ?? {};
-  const channelType = String(meta.type ?? meta.channelType ?? '');
-  if (channelType === 'group' || channelType === 'guild' || channelType === 'channel') {
-    return String(meta.channelId ?? input.conversation?.id ?? '');
-  }
-  if (input.conversation && channelType !== 'private') {
-    return String(input.conversation.id ?? '');
-  }
-  return '';
+export function resolveGroupId(input: ConversationInput): string {
+  return conversationKey(requireConversation(input));
 }
 
-export function recordMessage(input: {
-  sender?: { readonly id: string; readonly name?: string };
-  conversation?: { readonly kind?: string; readonly id?: string };
-  metadata?: Readonly<Record<string, unknown>>;
-}, runtime: GroupSuiteRuntime): void {
+export function recordMessage(input: ConversationInput, runtime: GroupSuiteRuntime): void {
   const targetBuffer = runtime.statsBuffer;
   const { id: userId, name: userName } = resolveSender(input);
   if (!userId) return;
@@ -57,6 +43,7 @@ export function recordMessage(input: {
   const pending = targetBuffer.get(key);
   if (pending) {
     pending.count++;
+    pending.recorded++;
     pending.user_name = userName;
   } else {
     targetBuffer.set(key, {
@@ -65,17 +52,40 @@ export function recordMessage(input: {
       group_id: groupId,
       date: todayStr(),
       count: 1,
+      recorded: 1,
+      flushed: 0,
     });
   }
 }
 
-export async function flushStatsBuffer(runtime: GroupSuiteRuntime): Promise<void> {
+interface StatsBatchEntry {
+  readonly key: string;
+  readonly entry: PendingStatsIncrement;
+  readonly watermark: number;
+}
+
+/** Flush only the increments visible to this caller; new traffic cannot prolong its batch. */
+export function flushStatsBuffer(runtime: GroupSuiteRuntime): Promise<void> {
+  const batch = [...runtime.statsBuffer.entries()].map(([key, entry]) => ({
+    key, entry, watermark: entry.recorded,
+  }));
+  const previous = runtime.statsFlush ?? Promise.resolve();
+  const flush = previous.catch(() => undefined).then(() => flushStatsBatch(runtime, batch)).finally(() => {
+    if (runtime.statsFlush === flush) runtime.statsFlush = undefined;
+  });
+  runtime.statsFlush = flush;
+  return flush;
+}
+
+async function flushStatsBatch(runtime: GroupSuiteRuntime, batch: readonly StatsBatchEntry[]): Promise<void> {
   const targetBuffer = runtime.statsBuffer;
+  if (batch.length === 0) return;
   const M = getStatsModel(runtime.db);
-  if (!M || targetBuffer.size === 0) return;
-  for (const [key, entry] of [...targetBuffer.entries()]) {
-    // 快照本次要落库的计数；flush 期间新累计的部分留在缓冲
-    const countSnapshot = entry.count;
+  if (!M) return;
+  for (const { key, entry, watermark } of batch) {
+    // Earlier batches may already have committed part/all of this caller's watermark.
+    const countSnapshot = Math.min(entry.count, watermark - entry.flushed);
+    if (countSnapshot <= 0 || targetBuffer.get(key) !== entry) continue;
     try {
       const existing = (await M.select().where({
         user_id: entry.user_id,
@@ -104,6 +114,7 @@ export async function flushStatsBuffer(runtime: GroupSuiteRuntime): Promise<void
       }
       // 只移除写入成功的部分；失败的 key 留在缓冲等下一轮重试
       entry.count -= countSnapshot;
+      entry.flushed += countSnapshot;
       if (entry.count <= 0 && targetBuffer.get(key) === entry) targetBuffer.delete(key);
     } catch {
       /* single row failure: keep entry in buffer for next flush */
@@ -139,11 +150,7 @@ export async function queryStats(
   return result;
 }
 
-type MessageInput = {
-  sender?: { readonly id: string; readonly name?: string };
-  target?: string;
-  metadata?: Readonly<Record<string, unknown>>;
-};
+type MessageInput = ConversationInput;
 
 export async function statsRankText(
   input: MessageInput,

package/src/teach-lib.ts

@@ -1,3 +1,4 @@
+import type { ConversationInput } from './conversation-scope.js';
 import type { GroupSuiteConfig } from './config.js';
 import { getTeachModel } from './db-store.js';
 import {
@@ -70,12 +71,7 @@ function qaWhereKey(row: {
   };
 }
 
-type MessageInput = {
-  sender?: { readonly id: string; readonly name?: string };
-  target?: string;
-  content?: unknown;
-  metadata?: Readonly<Record<string, unknown>>;
-};
+type MessageInput = ConversationInput;
 
 async function findMatch(
   content: string,
@@ -86,12 +82,9 @@ async function findMatch(
 ): Promise<Record<string, unknown> | null> {
   const QA = getTeachModel(runtime.db);
   if (!QA) return null;
-  const allItems = (await QA.select()) as Record<string, unknown>[];
-  const candidates = allItems.filter(
-    (item) =>
-      item.context_type === 'global' ||
-      (item.context_type === ctxType && item.context_id === ctxId),
-  );
+  const candidates = (await QA.select().where({
+    context_type: ctxType, context_id: ctxId,
+  })) as Record<string, unknown>[];
   for (const item of candidates) {
     if (!item.is_regex && item.question === content) return item;
   }
@@ -196,9 +189,7 @@ export async function teachList(
   const safePage = Math.max(1, page);
   const { type: ctxType, id: ctxId } = resolveContextKey(input);
   const allItems = (await QA.select().where(
-    ctxType === 'global'
-      ? { context_type: 'global' }
-      : { context_type: ctxType, context_id: ctxId },
+    { context_type: ctxType, context_id: ctxId },
   )) as Record<string, unknown>[];
   if (allItems.length === 0) return '还没有教过任何问答哦～';
   const totalPages = Math.ceil(allItems.length / cfg.teachPageSize);
@@ -210,7 +201,7 @@ export async function teachList(
     const q = item.is_regex ? `/${item.question}/` : item.question;
     return `${start + i + 1}. ${prefix} ${q} → ${item.answer}`;
   });
-  const header = ctxType === 'global' ? '全局问答列表' : '本群问答列表';
+  const header = '本会话问答列表';
   return `${header}\n${lines.join('\n')}\n第 ${pageNum}/${totalPages} 页 · 共 ${allItems.length} 条`;
 }
 
@@ -253,7 +244,7 @@ export async function tryTeachReply(
   const matched = await findMatch(content, ctxType, ctxId, cfg, runtime);
   if (!matched) return null;
 
-  const cooldownKey = `${matched.question}:${ctxType}:${ctxId}:${matched.is_regex ?? 0}`;
+  const cooldownKey = JSON.stringify([matched.question, ctxType, ctxId, matched.is_regex ?? 0]);
   const cooldowns = runtime.teachCooldowns;
   const last = cooldowns.get(cooldownKey);
   if (last && Date.now() - last < cfg.teachCooldownMs) return null;