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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/plugin-group-suite",
-  "version": "1.1.6",
-  "description": "Zhin.js 群运营套件 — slice-2 checkin/teach/stats + keywords (Plugin Runtime, in-memory)",
+  "version": "1.1.8",
+  "description": "Zhin.js 群运营套件：签到、教学、统计、持久词库与群欢迎",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,6 +18,8 @@
     "schema.json",
     "commands",
     "middlewares",
+    "handlers",
+    "schedules",
     "src",
     "lib",
     "skills",
@@ -40,23 +42,25 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@zhin.js/components": "1.1.1",
-    "@zhin.js/core": "1.1.41",
-    "@zhin.js/jsx": "1.1.1",
-    "@zhin.js/skill": "1.1.4",
-    "@zhin.js/tool": "1.1.4"
+    "@zhin.js/components": "1.1.2",
+    "@zhin.js/core": "1.1.43",
+    "@zhin.js/jsx": "1.1.2",
+    "@zhin.js/skill": "1.1.5",
+    "@zhin.js/tool": "1.1.5"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.6"
+    "zhin.js": "1.1.8"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/command": "^1.1.5",
-    "@zhin.js/middleware": "^1.1.4",
-    "zhin.js": "^1.1.6"
+    "@zhin.js/command": "^1.1.6",
+    "@zhin.js/middleware": "^1.1.5",
+    "zhin.js": "^1.1.8",
+    "@zhin.js/handler": "^1.1.4",
+    "@zhin.js/schedule-feature": "^1.1.4"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -67,6 +71,12 @@
     },
     "zod": {
       "optional": true
+    },
+    "@zhin.js/handler": {
+      "optional": true
+    },
+    "@zhin.js/schedule-feature": {
+      "optional": true
     }
   },
   "repository": {
@@ -103,6 +113,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,

package/src/conversation-scope.ts

@@ -0,0 +1,45 @@
+import { createDeliveryTarget, type DeliveryTarget } from 'zhin.js';
+import { adapterFeatureId, type AdapterIndex } from 'zhin.js/adapter';
+import type { ToolInvocationOrigin } from '@zhin.js/tool';
+
+export interface ConversationInput {
+  readonly conversation?: DeliveryTarget;
+  readonly sender?: Readonly<{ id: string; name?: string }>;
+  readonly content?: unknown;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/** Versioned, unambiguous identity; historical bare group ids are deliberately not read. */
+export function conversationKey(target: DeliveryTarget): string {
+  const canonical = createDeliveryTarget({ conversation: target });
+  return JSON.stringify(['conversation-v1', canonical.endpoint.adapter, canonical.endpoint.id,
+    canonical.kind, canonical.id, canonical.parent?.kind ?? null, canonical.parent?.id ?? null,
+    canonical.threadId ?? null]);
+}
+
+export function requireConversation(input: ConversationInput): DeliveryTarget {
+  if (!input.conversation) throw new Error('Group Suite requires a canonical conversation');
+  return createDeliveryTarget({ conversation: input.conversation });
+}
+
+/** Tool origins contain an endpoint selector, not a canonical endpoint capability id. */
+export function toolGroupConversation(context: {
+  readonly origin: ToolInvocationOrigin;
+  project<T>(feature: typeof adapterFeatureId): T;
+}, groupId?: string): DeliveryTarget {
+  if (context.origin.kind !== 'im' || context.origin.scope !== 'group') {
+    throw new Error('Group Suite query tools require a group IM origin');
+  }
+  const origin = context.origin;
+  const index = context.project<AdapterIndex>(adapterFeatureId);
+  const matches = index.describe().filter(endpoint =>
+    (String(endpoint.id) === origin.endpoint || endpoint.name === origin.endpoint)
+    && index.clientAdapter(endpoint.id) === origin.platform);
+  if (matches.length !== 1) throw new Error('Group Suite tool endpoint is missing or ambiguous');
+  return createDeliveryTarget({ conversation: {
+    endpoint: { id: String(matches[0]!.id), adapter: origin.platform },
+    kind: 'group', id: groupId ?? origin.sceneId,
+    ...(origin.threadId !== undefined && (groupId === undefined || groupId === origin.sceneId)
+      ? { threadId: origin.threadId } : {}),
+  } });
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export type { GroupSuiteConfig } from './config.js';
 export { doCheckin, myPoints, pointsRank } from './checkin-lib.js';
 export {
   addKeyword,
+  keywordStore,
   listKeywords,
   matchKeyword,
   removeKeyword,

package/src/keyword-store.ts

@@ -1,3 +1,7 @@
+import type { MessageBase } from '@zhin.js/core/runtime';
+import { conversationKey } from './conversation-scope.js';
+import type { GroupSuiteRuntime } from './runtime-state.js';
+
 export function addKeyword(keyword: string, reply: string, store: Map<string, string>): void {
   store.set(keyword, reply);
 }
@@ -16,3 +20,21 @@ export function matchKeyword(text: string, store: Map<string, string>): string |
   }
   return null;
 }
+
+/** Owner is already isolated by the Resource; canonical endpoint and group form the inner scope. */
+export function keywordStore(
+  input: Pick<MessageBase, 'conversation'> | undefined,
+  runtime: GroupSuiteRuntime,
+): Map<string, string> {
+  const conversation = input?.conversation;
+  if (conversation?.kind !== 'group' || !conversation.id || !conversation.endpoint.id) {
+    throw new Error('Keywords require a group conversation with an endpoint');
+  }
+  const key = conversationKey(conversation);
+  let store = runtime.keywords.get(key);
+  if (!store) {
+    store = new Map();
+    runtime.keywords.set(key, store);
+  }
+  return store;
+}