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

package/README.md

@@ -9,10 +9,12 @@ Plugin Runtime 群运营套件，提供签到积分、消息统计、群问答
 pnpm exec zhin install @zhin.js/plugin-group-suite
 ```
 
-安装会将实例挂在父插件的 `package.json#zhin.plugins`。手工挂载：
+安装会将实例声明写入主配置 `plugins` 映射。手工声明：
 
-```json
-{ "package": "@zhin.js/plugin-group-suite", "instanceKey": "group-suite" }
+```yaml
+configVersion: 2
+plugins:
+  group-suite: '@zhin.js/plugin-group-suite'
 ```
 
 应用 Host 必须共享同一物理实例的 `@zhin.js/command`、`@zhin.js/middleware`、
@@ -20,20 +22,22 @@ pnpm exec zhin install @zhin.js/plugin-group-suite
 Feature provider，并装配 Schedule Host。正常 CLI 负责 Host 装配；手写测试 Host 也需要显式安装这些资源。
 
 ```yaml
+configVersion: 2
 plugins:
-  group-suite:
-    keywordReply: true
-    ephemeralKeywords: false
-    welcomeMessage: "" # 默认关闭；可设为 欢迎 {name} ({id})
-    basePointsMin: 10
-    basePointsMax: 30
-    streakBonus: 5
-    streakCap: 50
-    rankSize: 10
-    teachMaxPerGroup: 200
-    teachCooldownMs: 3000
-    teachAllowRegex: true
-    teachPageSize: 10
+  group-suite: "@zhin.js/plugin-group-suite"
+group-suite:
+  keywordReply: true
+  ephemeralKeywords: false
+  welcomeMessage: "" # 默认关闭；可设为 欢迎 {name} ({id})
+  basePointsMin: 10
+  basePointsMax: 30
+  streakBonus: 5
+  streakCap: 50
+  rankSize: 10
+  teachMaxPerGroup: 200
+  teachCooldownMs: 3000
+  teachAllowRegex: true
+  teachPageSize: 10
 ```
 
 约束以 [schema.json](./schema.json) 为准。启用关键词回复时默认要求 Database Host 的原子
@@ -73,6 +77,35 @@ plugins:
 欢迎通过 `outboundMessageToken` 走统一发送链路，投递失败/未知会报错，不盲目重试。
 `stats-card` 是 HTML 图片/文本展示，不是平台原生 `card` 载荷。
 
+### 限定群欢迎范围
+
+`welcomeConversations` 是当前插件实例的精确会话白名单，最多 100 项。省略此字段保留原行为：
+设置非空 `welcomeMessage` 后，所有符合条件的群成员加入事件都可触发欢迎。显式配置 `[]`
+则不欢迎任何会话；`welcomeMessage` 为空时仍始终关闭欢迎。
+
+```yaml
+group-suite:
+  welcomeMessage: "欢迎 {name} ({id})"
+  welcomeConversations:
+    - endpoint:
+        adapter: "<复制实际 conversation.endpoint.adapter>"
+        id: "root/qq\u0000zhin.adapter\u0000icqq~main"
+      kind: group
+      id: "123456"
+```
+
+示例 Endpoint ID 仅说明格式，实际请复制当前 canonical `conversation.endpoint`，不要按昵称、
+账号、Endpoint 简称或实例名拼接。完整 Endpoint ID 中的 NUL 在双引号 YAML 中写为 `\u0000`。
+`endpoint.adapter` 也须与事件完全一致。
+
+每项同时匹配完整 Endpoint 身份、`kind`、会话 `id`、`parent.kind/id` 和 `threadId`，没有通配符。
+省略 `parent` 或 `threadId` 只匹配同样没有该字段的群根会话；需要父容器或线程时须完整填写。
+`null`、空 ID、残缺父容器和额外字段会被拒绝。重复条目不会重复发送欢迎。
+白名单只筛选入站群成员加入事件，不改写原会话投递目标，也不限制签到、词库、统计等能力。
+
+这不补充平台本身缺少的入站事件或目标：未提供 canonical 群会话的成员加入事件不会发送欢迎，
+也不会推测频道。配置可热更新，校验失败保留旧配置与 generation；没有单独的范围数据库。
+
 所有新数据按插件实例与完整会话隔离：平台、Endpoint 身份、群/频道/私聊类型与 ID，以及父会话、
 线程信息共同参与键。相同群号的两个 Bot 不共享词库、签到、教学或统计。群专用 Tool 只接受 IM
 群上下文，并通过当前 AdapterIndex 精确解析 Endpoint，无法确定唯一来源时拒绝执行。当前群的查询保留当前线程，只查该完整会话，不聚合其他线程。

package/handlers/welcome/index.js

@@ -2,18 +2,22 @@
 import { defineHandler } from 'zhin.js/handler';
 import { outboundMessageToken } from '@zhin.js/core/runtime';
 import { resolveGroupSuiteConfig } from "../../lib/config.js";
+import { welcomeConversationAllowed } from "../../lib/welcome-scope.js";
 /** Canonical notice input only; no SDK-specific callbacks or direct platform sends. */
 export default defineHandler({
     event: 'notice.receive',
     async handle({ payload: notice }) {
-        const text = resolveGroupSuiteConfig(this.config).welcomeMessage;
+        const config = resolveGroupSuiteConfig(this.config);
+        const text = config.welcomeMessage;
         if (!text || notice.name !== 'notice.group.member_increase'
             || notice.conversation?.kind !== 'group' || !notice.target?.id)
             return;
+        if (!welcomeConversationAllowed(config.welcomeConversations, notice.conversation))
+            return;
         const content = text.replaceAll('{name}', notice.target.name ?? notice.target.id)
             .replaceAll('{id}', notice.target.id);
         const result = await this.use(outboundMessageToken).send({
-            requester: this.owner,
+            requester: this.owner.id,
             conversation: notice.conversation,
             content: { type: 'text', data: { text: content } },
         });

package/handlers/welcome/index.ts

@@ -1,18 +1,21 @@
 import { defineHandler } from 'zhin.js/handler';
 import { outboundMessageToken } from '@zhin.js/core/runtime';
 import { resolveGroupSuiteConfig, type GroupSuiteConfig } from '../../src/config.js';
+import { welcomeConversationAllowed } from '../../src/welcome-scope.js';
 
 /** Canonical notice input only; no SDK-specific callbacks or direct platform sends. */
 export default defineHandler({
   event: 'notice.receive',
   async handle({ payload: notice }) {
-    const text = resolveGroupSuiteConfig(this.config as Partial<GroupSuiteConfig>).welcomeMessage;
+    const config = resolveGroupSuiteConfig(this.config as Partial<GroupSuiteConfig>);
+    const text = config.welcomeMessage;
     if (!text || notice.name !== 'notice.group.member_increase'
       || notice.conversation?.kind !== 'group' || !notice.target?.id) return;
+    if (!welcomeConversationAllowed(config.welcomeConversations, notice.conversation)) return;
     const content = text.replaceAll('{name}', notice.target.name ?? notice.target.id)
       .replaceAll('{id}', notice.target.id);
     const result = await this.use(outboundMessageToken).send({
-      requester: this.owner,
+      requester: this.owner.id,
       conversation: notice.conversation,
       content: { type: 'text', data: { text: content } },
     });

package/lib/config.d.ts

@@ -1,9 +1,12 @@
+import type { DeliveryTarget } from 'zhin.js';
 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;
+    /** Omitted preserves all groups; [] disables welcomes. Each address matches exactly. */
+    welcomeConversations?: readonly DeliveryTarget[];
     basePointsMin: number;
     basePointsMax: number;
     streakBonus: number;

package/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,OAAO,CAAC;IACtB,iFAAiF;IACjF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sFAAsF;IACtF,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,0BAA0B,EAAE,gBAaxC,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,SAAS,GACzC,gBAAgB,CAKlB"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,OAAO,CAAC;IACtB,iFAAiF;IACjF,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sFAAsF;IACtF,cAAc,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,oBAAoB,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,0BAA0B,EAAE,gBAaxC,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,SAAS,GACzC,gBAAgB,CAQlB"}

package/lib/config.js

@@ -1,3 +1,4 @@
+import { normalizeWelcomeConversations } from './welcome-scope.js';
 export const DEFAULT_GROUP_SUITE_CONFIG = {
     keywordReply: false,
     ephemeralKeywords: false,
@@ -16,6 +17,9 @@ export function resolveGroupSuiteConfig(raw) {
     return {
         ...DEFAULT_GROUP_SUITE_CONFIG,
         ...raw,
+        ...(raw?.welcomeConversations === undefined ? {} : {
+            welcomeConversations: normalizeWelcomeConversations(raw.welcomeConversations),
+        }),
     };
 }
 //# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,0BAA0B,GAAqB;IAC1D,YAAY,EAAE,KAAK;IACnB,iBAAiB,EAAE,KAAK;IACxB,cAAc,EAAE,EAAE;IAClB,aAAa,EAAE,EAAE;IACjB,aAAa,EAAE,EAAE;IACjB,WAAW,EAAE,CAAC;IACd,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;IACZ,gBAAgB,EAAE,GAAG;IACrB,eAAe,EAAE,IAAI;IACrB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,EAAE;CAClB,CAAC;AAEF,MAAM,UAAU,uBAAuB,CACrC,GAA0C;IAE1C,OAAO;QACL,GAAG,0BAA0B;QAC7B,GAAG,GAAG;KACP,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAqBnE,MAAM,CAAC,MAAM,0BAA0B,GAAqB;IAC1D,YAAY,EAAE,KAAK;IACnB,iBAAiB,EAAE,KAAK;IACxB,cAAc,EAAE,EAAE;IAClB,aAAa,EAAE,EAAE;IACjB,aAAa,EAAE,EAAE;IACjB,WAAW,EAAE,CAAC;IACd,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;IACZ,gBAAgB,EAAE,GAAG;IACrB,eAAe,EAAE,IAAI;IACrB,eAAe,EAAE,IAAI;IACrB,aAAa,EAAE,EAAE;CAClB,CAAC;AAEF,MAAM,UAAU,uBAAuB,CACrC,GAA0C;IAE1C,OAAO;QACL,GAAG,0BAA0B;QAC7B,GAAG,GAAG;QACN,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACjD,oBAAoB,EAAE,6BAA6B,CAAC,GAAG,CAAC,oBAAoB,CAAC;SAC9E,CAAC;KACH,CAAC;AACJ,CAAC"}

package/lib/welcome-scope.d.ts

@@ -0,0 +1,6 @@
+import { type DeliveryTarget } from 'zhin.js';
+/** Validate without resolving aliases, retaining clients or introducing another scope store. */
+export declare function normalizeWelcomeConversations(value: unknown): readonly DeliveryTarget[];
+/** Missing parent/thread matches absence, never all descendants or threads. */
+export declare function welcomeConversationAllowed(scopes: readonly DeliveryTarget[] | undefined, target: DeliveryTarget): boolean;
+//# sourceMappingURL=welcome-scope.d.ts.map

package/lib/welcome-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome-scope.d.ts","sourceRoot":"","sources":["../src/welcome-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAGpE,gGAAgG;AAChG,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,cAAc,EAAE,CAOvF;AAED,+EAA+E;AAC/E,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAIzH"}

package/lib/welcome-scope.js

@@ -0,0 +1,21 @@
+import { createDeliveryTarget } from 'zhin.js';
+import { conversationKey } from './conversation-scope.js';
+/** Validate without resolving aliases, retaining clients or introducing another scope store. */
+export function normalizeWelcomeConversations(value) {
+    if (!Array.isArray(value) || value.length > 100)
+        throw new TypeError('welcomeConversations must contain at most 100 exact group conversations');
+    return Object.freeze(value.map(entry => {
+        const target = createDeliveryTarget({ conversation: entry });
+        if (target.kind !== 'group')
+            throw new TypeError('welcomeConversations only supports group conversations');
+        return target;
+    }));
+}
+/** Missing parent/thread matches absence, never all descendants or threads. */
+export function welcomeConversationAllowed(scopes, target) {
+    if (scopes === undefined)
+        return true;
+    const key = conversationKey(target);
+    return scopes.some(scope => conversationKey(scope) === key);
+}
+//# sourceMappingURL=welcome-scope.js.map

package/lib/welcome-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome-scope.js","sourceRoot":"","sources":["../src/welcome-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAuB,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,gGAAgG;AAChG,MAAM,UAAU,6BAA6B,CAAC,KAAc;IAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,MAAM,IAAI,SAAS,CAAC,yEAAyE,CAAC,CAAC;IAChJ,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;QACrC,MAAM,MAAM,GAAG,oBAAoB,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7D,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;QAC3G,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,0BAA0B,CAAC,MAA6C,EAAE,MAAsB;IAC9G,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;AAC9D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-group-suite",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "description": "Zhin.js 群运营套件：签到、教学、统计、持久词库与群欢迎",
   "type": "module",
   "main": "./lib/index.js",
@@ -42,24 +42,24 @@
   "license": "MIT",
   "dependencies": {
     "@zhin.js/components": "1.1.3",
-    "@zhin.js/core": "1.1.44",
+    "@zhin.js/core": "1.1.46",
     "@zhin.js/jsx": "1.1.3",
-    "@zhin.js/skill": "1.1.6",
-    "@zhin.js/tool": "1.1.6"
+    "@zhin.js/skill": "1.1.7",
+    "@zhin.js/tool": "1.1.7"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.9"
+    "zhin.js": "1.1.11"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@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"
+    "@zhin.js/command": "^1.1.8",
+    "@zhin.js/middleware": "^1.1.7",
+    "zhin.js": "^1.1.11",
+    "@zhin.js/handler": "^1.1.6",
+    "@zhin.js/schedule-feature": "^1.1.6"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {

package/schema.json

@@ -49,6 +49,40 @@
       "default": "",
       "description": "Group welcome text. Empty disables; {name}/{id} refer to the joined member."
     },
+    "welcomeConversations": {
+      "type": "array",
+      "maxItems": 100,
+      "description": "Exact welcome conversations. Omitted welcomes all groups; [] welcomes none. Missing parent/thread requires their absence; no wildcards.",
+      "x-zhin-config": { "component": "conversation-scope" },
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["endpoint", "kind", "id"],
+        "properties": {
+          "endpoint": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["adapter", "id"],
+            "properties": {
+              "adapter": { "type": "string", "minLength": 1 },
+              "id": { "type": "string", "minLength": 1 }
+            }
+          },
+          "kind": { "type": "string", "enum": ["group"] },
+          "id": { "type": "string", "minLength": 1 },
+          "parent": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "id"],
+            "properties": {
+              "kind": { "type": "string", "enum": ["private", "group", "channel"] },
+              "id": { "type": "string", "minLength": 1 }
+            }
+          },
+          "threadId": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
     "ephemeralKeywords": {
       "type": "boolean",
       "default": false,

package/src/config.ts

@@ -1,9 +1,14 @@
+import type { DeliveryTarget } from 'zhin.js';
+import { normalizeWelcomeConversations } from './welcome-scope.js';
+
 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;
+  /** Omitted preserves all groups; [] disables welcomes. Each address matches exactly. */
+  welcomeConversations?: readonly DeliveryTarget[];
   basePointsMin: number;
   basePointsMax: number;
   streakBonus: number;
@@ -36,5 +41,8 @@ export function resolveGroupSuiteConfig(
   return {
     ...DEFAULT_GROUP_SUITE_CONFIG,
     ...raw,
+    ...(raw?.welcomeConversations === undefined ? {} : {
+      welcomeConversations: normalizeWelcomeConversations(raw.welcomeConversations),
+    }),
   };
 }

package/src/welcome-scope.ts

@@ -0,0 +1,19 @@
+import { createDeliveryTarget, type DeliveryTarget } from 'zhin.js';
+import { conversationKey } from './conversation-scope.js';
+
+/** Validate without resolving aliases, retaining clients or introducing another scope store. */
+export function normalizeWelcomeConversations(value: unknown): readonly DeliveryTarget[] {
+  if (!Array.isArray(value) || value.length > 100) throw new TypeError('welcomeConversations must contain at most 100 exact group conversations');
+  return Object.freeze(value.map(entry => {
+    const target = createDeliveryTarget({ conversation: entry });
+    if (target.kind !== 'group') throw new TypeError('welcomeConversations only supports group conversations');
+    return target;
+  }));
+}
+
+/** Missing parent/thread matches absence, never all descendants or threads. */
+export function welcomeConversationAllowed(scopes: readonly DeliveryTarget[] | undefined, target: DeliveryTarget): boolean {
+  if (scopes === undefined) return true;
+  const key = conversationKey(target);
+  return scopes.some(scope => conversationKey(scope) === key);
+}