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

package/middlewares/keyword-reply/index.js

@@ -2,7 +2,7 @@
 import { defineMiddleware } from 'zhin.js/middleware';
 import { resolveGroupSuiteConfig } from "../../lib/config.js";
 import { matchKeyword } from "../../lib/keyword-store.js";
-import { resolveGroupSuiteRuntime } from "../../lib/runtime-state.js";
+import { keywords } from "../../lib/keywords.js";
 /**
  * Keyword auto-reply (enabled via config.keywordReply).
  * Uses Runtime Message.content / metadata (legacy used $raw / $channel).
@@ -15,9 +15,7 @@ export default defineMiddleware({
             await next();
             return;
         }
-        const meta = context.input.metadata ?? {};
-        const channelType = String(meta.type ?? meta.channelType ?? '');
-        if (channelType === 'private') {
+        if (context.input.conversation.kind !== 'group') {
             await next();
             return;
         }
@@ -26,7 +24,7 @@ export default defineMiddleware({
             await next();
             return;
         }
-        const reply = matchKeyword(text, resolveGroupSuiteRuntime(context).keywords);
+        const reply = matchKeyword(text, new Map(await keywords(context.input, context).read()));
         if (reply) {
             await context.input.$reply(reply);
             return;

package/middlewares/keyword-reply/index.ts

@@ -2,7 +2,7 @@ import { defineMiddleware } from 'zhin.js/middleware';
 import type { Message } from '@zhin.js/core/runtime';
 import { resolveGroupSuiteConfig, type GroupSuiteConfig } from '../../src/config.js';
 import { matchKeyword } from '../../src/keyword-store.js';
-import { resolveGroupSuiteRuntime } from '../../src/runtime-state.js';
+import { keywords } from '../../src/keywords.js';
 
 /**
  * Keyword auto-reply (enabled via config.keywordReply).
@@ -16,9 +16,7 @@ export default defineMiddleware<Message, GroupSuiteConfig>({
       await next();
       return;
     }
-    const meta = context.input.metadata ?? {};
-    const channelType = String(meta.type ?? meta.channelType ?? '');
-    if (channelType === 'private') {
+    if (context.input.conversation.kind !== 'group') {
       await next();
       return;
     }
@@ -27,7 +25,7 @@ export default defineMiddleware<Message, GroupSuiteConfig>({
       await next();
       return;
     }
-    const reply = matchKeyword(text, resolveGroupSuiteRuntime(context).keywords);
+    const reply = matchKeyword(text, new Map(await keywords(context.input, context).read()));
     if (reply) {
       await context.input.$reply(reply);
       return;

package/middlewares/stats-count/index.js

@@ -2,18 +2,14 @@
 import { defineMiddleware } from 'zhin.js/middleware';
 import { recordMessage } from "../../lib/stats-lib.js";
 import { resolveGroupSuiteRuntime } from "../../lib/runtime-state.js";
-/**
- * Buffer inbound messages into in-memory message_stats (flushed on query).
- * Skips command messages (legacy used `isActionMessage` to skip interactive
- * action/command messages; the Runtime pipeline represents commands as
- * text starting with the dispatcher prefix '/').
- */
+/** Count in memory; the admitted Schedule Host flushes batches without slowing every message. */
 export default defineMiddleware({
     target: 'inbound',
     async handle(context, next) {
         const content = typeof context.input.content === 'string' ? context.input.content : '';
         if (!content.startsWith('/')) {
-            recordMessage(context.input, resolveGroupSuiteRuntime(context));
+            const runtime = resolveGroupSuiteRuntime(context);
+            recordMessage(context.input, runtime);
         }
         await next();
     },

package/middlewares/stats-count/index.ts

@@ -4,18 +4,14 @@ import type { GroupSuiteConfig } from '../../src/config.js';
 import { recordMessage } from '../../src/stats-lib.js';
 import { resolveGroupSuiteRuntime } from '../../src/runtime-state.js';
 
-/**
- * Buffer inbound messages into in-memory message_stats (flushed on query).
- * Skips command messages (legacy used `isActionMessage` to skip interactive
- * action/command messages; the Runtime pipeline represents commands as
- * text starting with the dispatcher prefix '/').
- */
+/** Count in memory; the admitted Schedule Host flushes batches without slowing every message. */
 export default defineMiddleware<Message, GroupSuiteConfig>({
   target: 'inbound',
   async handle(context, next) {
     const content = typeof context.input.content === 'string' ? context.input.content : '';
     if (!content.startsWith('/')) {
-      recordMessage(context.input, resolveGroupSuiteRuntime(context));
+      const runtime = resolveGroupSuiteRuntime(context);
+      recordMessage(context.input, runtime);
     }
     await next();
   },

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@zhin.js/plugin-group-suite",
-  "version": "1.1.7",
-  "description": "Zhin.js 群运营套件 — slice-2 checkin/teach/stats + keywords (Plugin Runtime, in-memory)",
+  "version": "1.1.9",
+  "description": "Zhin.js 群运营套件：签到、教学、统计、持久词库与群欢迎",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "development": "./src/index.ts",
       "import": "./lib/index.js"
     },
     "./package.json": "./package.json"
@@ -18,6 +17,8 @@
     "schema.json",
     "commands",
     "middlewares",
+    "handlers",
+    "schedules",
     "src",
     "lib",
     "skills",
@@ -40,23 +41,25 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@zhin.js/components": "1.1.2",
-    "@zhin.js/core": "1.1.42",
-    "@zhin.js/jsx": "1.1.2",
-    "@zhin.js/skill": "1.1.4",
-    "@zhin.js/tool": "1.1.4"
+    "@zhin.js/components": "1.1.3",
+    "@zhin.js/core": "1.1.44",
+    "@zhin.js/jsx": "1.1.3",
+    "@zhin.js/skill": "1.1.6",
+    "@zhin.js/tool": "1.1.6"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.7"
+    "zhin.js": "1.1.9"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/command": "^1.1.5",
-    "@zhin.js/middleware": "^1.1.4",
-    "zhin.js": "^1.1.7"
+    "@zhin.js/command": "^1.1.7",
+    "@zhin.js/middleware": "^1.1.6",
+    "zhin.js": "^1.1.9",
+    "@zhin.js/handler": "^1.1.5",
+    "@zhin.js/schedule-feature": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -67,6 +70,12 @@
     },
     "zod": {
       "optional": true
+    },
+    "@zhin.js/handler": {
+      "optional": true
+    },
+    "@zhin.js/schedule-feature": {
+      "optional": true
     }
   },
   "repository": {
@@ -79,7 +88,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=22.19.0"
   },
   "zhin": {
     "protocol": 1,
@@ -103,6 +112,14 @@
       {
         "package": "@zhin.js/skill",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/handler",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/schedule-feature",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.js

@@ -1,14 +1,14 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { definePlugin, databaseHostToken } from 'zhin.js';
+import { resolveGroupSuiteConfig } from "./lib/config.js";
 import { createInMemoryGroupSuiteDb } from "./lib/memory-store.js";
 import { createGroupSuiteRuntime, groupSuiteRuntimeToken } from "./lib/runtime-state.js";
-import { flushStatsBuffer } from "./lib/stats-lib.js";
 import { defineGroupSuiteTables } from "./lib/tables.js";
 /**
  * Plugin Runtime:
  * - checkin / teach / stats commands + keyword middleware
  * - DB: prefer `databaseHostToken`; else in-memory fallback
- * - Stats buffer: periodic flush every 10s + final flush on dispose
+ * - Stats writes run inside admitted schedule/query operations
  */
 export default definePlugin({
     name: 'group-suite',
@@ -25,14 +25,14 @@ export default definePlugin({
             }
             return createInMemoryGroupSuiteDb();
         })();
+        const config = resolveGroupSuiteConfig(context.config.get());
+        if (config.keywordReply && !config.ephemeralKeywords) {
+            // Fail before activation rather than claiming durable keywords in a memory fallback.
+            if (!context.resources.has(databaseHostToken))
+                throw new Error('Persistent keywords require a Database Host; demos may explicitly set ephemeralKeywords: true');
+            void context.resources.use(databaseHostToken).state;
+        }
         const runtime = createGroupSuiteRuntime(db);
         context.resources.provide(groupSuiteRuntimeToken, runtime);
-        const flushTimer = setInterval(() => {
-            void flushStatsBuffer(runtime);
-        }, 10_000);
-        context.lifecycle.add(async () => {
-            clearInterval(flushTimer);
-            await flushStatsBuffer(runtime);
-        });
     },
 });

package/schedules/flush-stats/index.js

@@ -0,0 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineSchedule } from '@zhin.js/schedule-feature';
+import { groupSuiteRuntimeToken } from "../../lib/runtime-state.js";
+import { flushStatsBuffer } from "../../lib/stats-lib.js";
+export default defineSchedule({
+    cron: '*/10 * * * * *',
+    description: 'Flush owner-scoped message count batches',
+    execute(context) {
+        return flushStatsBuffer(context.use(groupSuiteRuntimeToken));
+    },
+});

package/schedules/flush-stats/index.ts

@@ -0,0 +1,11 @@
+import { defineSchedule } from '@zhin.js/schedule-feature';
+import { groupSuiteRuntimeToken } from '../../src/runtime-state.js';
+import { flushStatsBuffer } from '../../src/stats-lib.js';
+
+export default defineSchedule({
+  cron: '*/10 * * * * *',
+  description: 'Flush owner-scoped message count batches',
+  execute(context) {
+    return flushStatsBuffer(context.use(groupSuiteRuntimeToken));
+  },
+});

package/schema.json

@@ -3,15 +3,56 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "keywordReply": { "type": "boolean", "default": false },
-    "basePointsMin": { "type": "number", "default": 10 },
-    "basePointsMax": { "type": "number", "default": 30 },
-    "streakBonus": { "type": "number", "default": 5 },
-    "streakCap": { "type": "number", "default": 50 },
-    "rankSize": { "type": "number", "default": 10 },
-    "teachMaxPerGroup": { "type": "number", "default": 200 },
-    "teachCooldownMs": { "type": "number", "default": 3000 },
-    "teachAllowRegex": { "type": "boolean", "default": true },
-    "teachPageSize": { "type": "number", "default": 10 }
+    "keywordReply": {
+      "type": "boolean",
+      "default": false
+    },
+    "basePointsMin": {
+      "type": "number",
+      "default": 10
+    },
+    "basePointsMax": {
+      "type": "number",
+      "default": 30
+    },
+    "streakBonus": {
+      "type": "number",
+      "default": 5
+    },
+    "streakCap": {
+      "type": "number",
+      "default": 50
+    },
+    "rankSize": {
+      "type": "number",
+      "default": 10
+    },
+    "teachMaxPerGroup": {
+      "type": "number",
+      "default": 200
+    },
+    "teachCooldownMs": {
+      "type": "number",
+      "default": 3000
+    },
+    "teachAllowRegex": {
+      "type": "boolean",
+      "default": true
+    },
+    "teachPageSize": {
+      "type": "number",
+      "default": 10
+    },
+    "welcomeMessage": {
+      "type": "string",
+      "maxLength": 2000,
+      "default": "",
+      "description": "Group welcome text. Empty disables; {name}/{id} refer to the joined member."
+    },
+    "ephemeralKeywords": {
+      "type": "boolean",
+      "default": false,
+      "description": "Explicit volatile keywords. With false, automatic replies require Database Host at startup and keyword management requires its persistent state service when invoked."
+    }
   }
 }

package/skills/checkin/tools/checkin_query/index.js

@@ -1,4 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { conversationKey, toolGroupConversation } from "../../../../lib/conversation-scope.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { getCheckinModel } from "../../../../lib/db-store.js";
 import { groupSuiteRuntimeToken } from "../../../../lib/runtime-state.js";
@@ -13,19 +14,18 @@ export default defineAgentTool({
         },
     },
     requiresApproval: 'never',
+    scopes: ['group'],
     async execute({ user_id: userId, group_id: requestedGroupId }, context) {
         const runtime = context.use(groupSuiteRuntimeToken);
         const model = getCheckinModel(runtime.db);
         if (!model)
             return '签到数据库尚未就绪';
-        const groupId = requestedGroupId ?? currentGroupId(context.origin);
+        const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
         const query = {
             ...(userId ? { user_id: userId } : {}),
-            ...(groupId ? { context_type: 'group', context_id: groupId } : {}),
+            context_type: 'group', context_id: groupId,
         };
-        const rows = Object.keys(query).length > 0
-            ? await model.select().where(query)
-            : await model.select();
+        const rows = await model.select().where(query);
         if (userId) {
             if (rows.length === 0)
                 return `用户 ${userId} 没有签到记录`;
@@ -37,6 +37,3 @@ export default defineAgentTool({
         return `签到系统统计\n总用户: ${rows.length}\n总积分: ${totalPoints}\n今日签到: ${todayCount}人`;
     },
 });
-function currentGroupId(origin) {
-    return origin.kind === 'im' && origin.scope !== 'private' ? origin.sceneId : '';
-}

package/skills/checkin/tools/checkin_query/index.ts

@@ -1,3 +1,4 @@
+import { conversationKey, toolGroupConversation } from '../../../../src/conversation-scope.js';
 import { defineAgentTool } from '@zhin.js/tool';
 import { getCheckinModel } from '../../../../src/db-store.js';
 import { groupSuiteRuntimeToken } from '../../../../src/runtime-state.js';
@@ -13,18 +14,17 @@ export default defineAgentTool<{ user_id?: string; group_id?: string }>({
     },
   },
   requiresApproval: 'never',
+  scopes: ['group'],
   async execute({ user_id: userId, group_id: requestedGroupId }, context) {
     const runtime = context.use(groupSuiteRuntimeToken);
     const model = getCheckinModel(runtime.db);
     if (!model) return '签到数据库尚未就绪';
-    const groupId = requestedGroupId ?? currentGroupId(context.origin);
+    const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
     const query = {
       ...(userId ? { user_id: userId } : {}),
-      ...(groupId ? { context_type: 'group', context_id: groupId } : {}),
+      context_type: 'group', context_id: groupId,
     };
-    const rows = Object.keys(query).length > 0
-      ? await model.select().where(query)
-      : await model.select();
+    const rows = await model.select().where(query);
     if (userId) {
       if (rows.length === 0) return `用户 ${userId} 没有签到记录`;
       const user = rows[0]!;
@@ -35,7 +35,3 @@ export default defineAgentTool<{ user_id?: string; group_id?: string }>({
     return `签到系统统计\n总用户: ${rows.length}\n总积分: ${totalPoints}\n今日签到: ${todayCount}人`;
   },
 });
-
-function currentGroupId(origin: import('@zhin.js/tool').ToolInvocationOrigin): string {
-  return origin.kind === 'im' && origin.scope !== 'private' ? origin.sceneId : '';
-}

package/skills/checkin/tools/checkin_rank/index.js

@@ -1,4 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { conversationKey, toolGroupConversation } from "../../../../lib/conversation-scope.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { getCheckinModel } from "../../../../lib/db-store.js";
 import { groupSuiteRuntimeToken } from "../../../../lib/runtime-state.js";
@@ -12,17 +13,13 @@ export default defineAgentTool({
         },
     },
     requiresApproval: 'never',
+    scopes: ['group'],
     async execute({ limit, group_id: requestedGroupId }, context) {
         const model = getCheckinModel(context.use(groupSuiteRuntimeToken).db);
         if (!model)
             return '签到数据库尚未就绪';
-        const groupId = requestedGroupId
-            ?? (context.origin.kind === 'im' && context.origin.scope !== 'private'
-                ? context.origin.sceneId
-                : '');
-        const rows = groupId
-            ? await model.select().where({ context_type: 'group', context_id: groupId })
-            : await model.select();
+        const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
+        const rows = await model.select().where({ context_type: 'group', context_id: groupId });
         const count = Math.min(Math.max(Number(limit) || 10, 1), 50);
         const ranked = [...rows]
             .sort((left, right) => Number(right.points ?? 0) - Number(left.points ?? 0))

package/skills/checkin/tools/checkin_rank/index.ts

@@ -1,3 +1,4 @@
+import { conversationKey, toolGroupConversation } from '../../../../src/conversation-scope.js';
 import { defineAgentTool } from '@zhin.js/tool';
 import { getCheckinModel } from '../../../../src/db-store.js';
 import { groupSuiteRuntimeToken } from '../../../../src/runtime-state.js';
@@ -12,16 +13,12 @@ export default defineAgentTool<{ limit?: number; group_id?: string }>({
     },
   },
   requiresApproval: 'never',
+  scopes: ['group'],
   async execute({ limit, group_id: requestedGroupId }, context) {
     const model = getCheckinModel(context.use(groupSuiteRuntimeToken).db);
     if (!model) return '签到数据库尚未就绪';
-    const groupId = requestedGroupId
-      ?? (context.origin.kind === 'im' && context.origin.scope !== 'private'
-        ? context.origin.sceneId
-        : '');
-    const rows = groupId
-      ? await model.select().where({ context_type: 'group', context_id: groupId })
-      : await model.select();
+    const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
+    const rows = await model.select().where({ context_type: 'group', context_id: groupId });
     const count = Math.min(Math.max(Number(limit) || 10, 1), 50);
     const ranked = [...rows]
       .sort((left, right) => Number(right.points ?? 0) - Number(left.points ?? 0))

package/skills/group-daily-analysis/tools/stats_query/index.js

@@ -1,4 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { conversationKey, toolGroupConversation } from "../../../../lib/conversation-scope.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { groupSuiteRuntimeToken } from "../../../../lib/runtime-state.js";
 import { flushStatsBuffer, monthStartStr, queryStats, weekStartStr } from "../../../../lib/stats-lib.js";
@@ -13,13 +14,11 @@ export default defineAgentTool({
         },
     },
     requiresApproval: 'never',
+    scopes: ['group'],
     async execute({ group_id: requestedGroupId, period = 'today' }, context) {
         const runtime = context.use(groupSuiteRuntimeToken);
         await flushStatsBuffer(runtime);
-        const groupId = requestedGroupId
-            ?? (context.origin.kind === 'im' && context.origin.scope !== 'private'
-                ? context.origin.sceneId
-                : '');
+        const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
         const fromDate = period === 'week'
             ? weekStartStr()
             : period === 'month' ? monthStartStr() : todayStr();

package/skills/group-daily-analysis/tools/stats_query/index.ts

@@ -1,3 +1,4 @@
+import { conversationKey, toolGroupConversation } from '../../../../src/conversation-scope.js';
 import { defineAgentTool } from '@zhin.js/tool';
 import { groupSuiteRuntimeToken } from '../../../../src/runtime-state.js';
 import { flushStatsBuffer, monthStartStr, queryStats, weekStartStr } from '../../../../src/stats-lib.js';
@@ -15,13 +16,11 @@ export default defineAgentTool<{ group_id?: string; period?: Period }>({
     },
   },
   requiresApproval: 'never',
+  scopes: ['group'],
   async execute({ group_id: requestedGroupId, period = 'today' }, context) {
     const runtime = context.use(groupSuiteRuntimeToken);
     await flushStatsBuffer(runtime);
-    const groupId = requestedGroupId
-      ?? (context.origin.kind === 'im' && context.origin.scope !== 'private'
-        ? context.origin.sceneId
-        : '');
+    const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
     const fromDate = period === 'week'
       ? weekStartStr()
       : period === 'month' ? monthStartStr() : todayStr();

package/skills/group-daily-analysis/tools/stats_user/index.js

@@ -1,4 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { conversationKey, toolGroupConversation } from "../../../../lib/conversation-scope.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { getStatsModel } from "../../../../lib/db-store.js";
 import { groupSuiteRuntimeToken } from "../../../../lib/runtime-state.js";
@@ -15,19 +16,17 @@ export default defineAgentTool({
         required: ['user_id'],
     },
     requiresApproval: 'never',
+    scopes: ['group'],
     async execute({ user_id: userId, group_id: requestedGroupId }, context) {
         const runtime = context.use(groupSuiteRuntimeToken);
         await flushStatsBuffer(runtime);
         const model = getStatsModel(runtime.db);
         if (!model)
             return '统计数据库尚未就绪';
-        const groupId = requestedGroupId
-            ?? (context.origin.kind === 'im' && context.origin.scope !== 'private'
-                ? context.origin.sceneId
-                : '');
+        const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
         const rows = await model.select().where({
             user_id: userId,
-            ...(groupId ? { group_id: groupId } : {}),
+            group_id: groupId,
         });
         if (rows.length === 0)
             return `用户 ${userId} 暂无消息记录`;

package/skills/group-daily-analysis/tools/stats_user/index.ts

@@ -1,3 +1,4 @@
+import { conversationKey, toolGroupConversation } from '../../../../src/conversation-scope.js';
 import { defineAgentTool } from '@zhin.js/tool';
 import { getStatsModel } from '../../../../src/db-store.js';
 import { groupSuiteRuntimeToken } from '../../../../src/runtime-state.js';
@@ -15,18 +16,16 @@ export default defineAgentTool<{ user_id: string; group_id?: string }>({
     required: ['user_id'],
   },
   requiresApproval: 'never',
+  scopes: ['group'],
   async execute({ user_id: userId, group_id: requestedGroupId }, context) {
     const runtime = context.use(groupSuiteRuntimeToken);
     await flushStatsBuffer(runtime);
     const model = getStatsModel(runtime.db);
     if (!model) return '统计数据库尚未就绪';
-    const groupId = requestedGroupId
-      ?? (context.origin.kind === 'im' && context.origin.scope !== 'private'
-        ? context.origin.sceneId
-        : '');
+    const groupId = conversationKey(toolGroupConversation(context, requestedGroupId));
     const rows = await model.select().where({
       user_id: userId,
-      ...(groupId ? { group_id: groupId } : {}),
+      group_id: groupId,
     });
     if (rows.length === 0) return `用户 ${userId} 暂无消息记录`;
     const today = todayStr();

package/src/checkin-lib.ts

@@ -1,3 +1,4 @@
+import type { ConversationInput } from './conversation-scope.js';
 import type { GroupSuiteConfig } from './config.js';
 import { getCheckinModel } from './db-store.js';
 import {
@@ -64,7 +65,7 @@ function serializedCheckin<T>(
 }
 
 export async function doCheckin(
-  input: { sender?: { readonly id: string; readonly name?: string }; target?: string; metadata?: Readonly<Record<string, unknown>> },
+  input: ConversationInput,
   cfg: GroupSuiteConfig,
   runtime: GroupSuiteRuntime,
 ): Promise<string> {
@@ -113,7 +114,7 @@ export async function doCheckin(
 }
 
 export async function myPoints(
-  input: { sender?: { readonly id: string; readonly name?: string }; target?: string; metadata?: Readonly<Record<string, unknown>> },
+  input: ConversationInput,
   runtime: GroupSuiteRuntime,
 ): Promise<string> {
   const M = getCheckinModel(runtime.db);
@@ -139,7 +140,7 @@ export async function myPoints(
 }
 
 export async function pointsRank(
-  input: { sender?: { readonly id: string; readonly name?: string }; target?: string; metadata?: Readonly<Record<string, unknown>> },
+  input: ConversationInput,
   cfg: GroupSuiteConfig,
   runtime: GroupSuiteRuntime,
 ): Promise<string> {
@@ -147,9 +148,7 @@ export async function pointsRank(
   if (!M) return '签到数据库尚未就绪';
   const { type: ctxType, id: ctxId } = resolveContextKey(input);
   const all = (await M.select().where(
-    ctxType === 'global'
-      ? { context_type: 'global' }
-      : { context_type: ctxType, context_id: ctxId },
+    { 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));
@@ -159,7 +158,8 @@ export async function pointsRank(
     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 title = ctxType === 'group' ? '本群积分排行'
+    : ctxType === 'channel' ? '本频道积分排行' : '当前私聊积分排行';
   const { id: userId } = resolveSender(input);
   const myRank = sorted.findIndex((u) => u.user_id === userId);
   const footer = myRank >= 0 ? `\n你的排名: 第${myRank + 1}名` : '';

package/src/config.ts

@@ -1,5 +1,9 @@
 export interface GroupSuiteConfig {
   keywordReply: boolean;
+  /** Explicitly volatile keywords for demos without a persistent Database Host. */
+  ephemeralKeywords: boolean;
+  /** Empty disables group member welcomes. {name} and {id} are literal placeholders. */
+  welcomeMessage: string;
   basePointsMin: number;
   basePointsMax: number;
   streakBonus: number;
@@ -13,6 +17,8 @@ export interface GroupSuiteConfig {
 
 export const DEFAULT_GROUP_SUITE_CONFIG: GroupSuiteConfig = {
   keywordReply: false,
+  ephemeralKeywords: false,
+  welcomeMessage: '',
   basePointsMin: 10,
   basePointsMax: 30,
   streakBonus: 5,