@zhin.js/plugin-content-moderation 1.1.14 → 1.1.16

package/middlewares/inbound/index.ts

@@ -1,6 +1,10 @@
-import { defineMiddleware } from 'zhin.js/middleware';
+import { defineMiddleware, type MiddlewareContext } from 'zhin.js/middleware';
 import type { Message } from '@zhin.js/core/runtime';
-import { outboundHostToken } from 'zhin.js';
+import { aiCompletionToken, createDeliveryTarget, databaseHostToken, getLogger, hasResource,
+  outboundHostToken, usageSubjectFromMessage } from 'zhin.js';
+import { adapterFeatureId, type AdapterIndex } from 'zhin.js/adapter';
+import { generationAdmissionSource } from 'zhin.js/plugin-runtime';
+import { resolveLocale } from 'zhin.js/i18n';
 import {
   buildScanContext,
   extractFromTextAndSegments,
@@ -27,15 +31,18 @@ export default defineMiddleware<Message, ModerationConfig>({
     }
 
     const message = context.input;
+    const locale = resolveLocale(message.locale);
     const sender = message.sender?.id;
     const conversationId = message.conversation.id;
     const endpointMasters = resolveEndpointMasters(message, config);
 
-    if (shouldBypassInbound(config, {
+    const bypass = shouldBypassInbound(config, {
       sender,
       conversationId,
       endpointMasters,
-    })) {
+    });
+    const review = await enqueueGroupModeration(context, config, bypass);
+    if (bypass) {
       await next();
       return;
     }
@@ -65,6 +72,8 @@ export default defineMiddleware<Message, ModerationConfig>({
 
     const result = await engine.apply({
       direction: 'inbound',
+      locale,
+      recallManaged: review?.done,
       extracted,
       scanInput,
       hooks: {
@@ -104,6 +113,87 @@ export default defineMiddleware<Message, ModerationConfig>({
   },
 });
 
+async function enqueueGroupModeration(
+  context: MiddlewareContext<Message, ModerationConfig, string | undefined>,
+  config: ModerationConfig, bypass: boolean,
+): Promise<{ done: Promise<boolean> } | undefined> {
+  const message = context.input;
+  const locale = resolveLocale(message.locale);
+  const conversation = structuredClone(message.conversation);
+  const target = config.groupModeration.find((item) => conversation.kind === 'group'
+    && item.adapter === conversation.endpoint.adapter
+    && item.endpoint === message.endpointId && item.group === conversation.id);
+  if (!target) return;
+  const logger = getLogger('content-moderation');
+  try {
+    const adapters = context.project<AdapterIndex>(adapterFeatureId);
+    const endpoint = adapters.connection(conversation.endpoint.adapter, conversation.endpoint.id);
+    // Reject alias fallback and account switches, even when a local instance name is reused.
+    if (!endpoint || endpoint.identity.id !== conversation.endpoint.id
+      || endpoint.identity.adapter !== target.adapter || endpoint.selfUserId !== target.account) return;
+    const engine = context.use(moderationEngineToken);
+    const { text } = extractFromTextAndSegments(message.content, message.segments);
+    const destination = createDeliveryTarget({ conversation });
+    const scope = JSON.stringify(destination);
+    const remembered = engine.groupModerator.remember(scope, message.sender?.id ?? '', text);
+    if (!bypass && message.sender?.id && message.origin !== 'self'
+      && hasResource(context, aiCompletionToken) && hasResource(context, databaseHostToken)
+      && hasResource(context, outboundHostToken)) {
+      const host = context.use(outboundHostToken);
+      if (!host.sendTarget) return;
+      const lifetime = new AbortController();
+      const gates = adapters[generationAdmissionSource] ?? [];
+      const detach = gates.map(gate => gate.onDeactivate(() => lifetime.abort(new Error('Moderation adapter generation retired'))));
+      const signal = AbortSignal.any([context.signal, lifetime.signal]);
+      const messageId = message.id ?? '';
+      const assertTarget = () => {
+        signal.throwIfAborted();
+        if (endpoint.identity.id !== conversation.endpoint.id || endpoint.selfUserId !== target.account
+          || endpoint.identity.adapter !== target.adapter || gates.some(gate => !gate.active)) {
+          throw new Error('Moderation target account is no longer active');
+        }
+      };
+      try {
+        const queued = await engine.groupReviewQueue.enqueue({
+          scope, group: conversation.id, sender: message.sender.id, locale,
+          messageId, sentAt: Number(message.metadata?.platformSentAt), text, ...remembered,
+          signal,
+          state: context.use(databaseHostToken).state.forConversation(destination),
+          completion: context.use(aiCompletionToken), management: {
+            inspectGroupMember: endpoint.management?.inspectGroupMember ? async (group, member, operationSignal) => {
+              assertTarget(); return endpoint.management!.inspectGroupMember!(group, member, operationSignal);
+            } : undefined,
+            moderateGroupMember: endpoint.management?.moderateGroupMember ? async (group, member, action, operationSignal) => {
+              assertTarget(); return endpoint.management!.moderateGroupMember!(group, member, action, operationSignal);
+            } : undefined,
+          },
+          onBehalfOf: usageSubjectFromMessage(message),
+          reply: async (content, mention) => {
+            assertTarget();
+            const receipt = await host.sendTarget!(destination, mention ? [
+              { type: 'mention', data: { target: mention } },
+              { type: 'text', data: { text: ` ${content}` } },
+            ] : content, { locale });
+            if (!receipt) throw new Error('Moderation notice was not confirmed');
+          },
+          recall: async () => {
+            assertTarget();
+            if (!host.recall || !messageId) throw new Error('Original message cannot be recalled');
+            await host.recall({ adapter: target.adapter, endpointKey: conversation.endpoint.id,
+              message: { conversation, id: messageId } });
+          },
+          audit: (event) => logger.info({ ...event, endpoint: conversation.endpoint.id, group: conversation.id }),
+        });
+        return { done: queued.done.finally(() => detach.forEach(remove => remove())) };
+      } catch (error) {
+        detach.forEach(remove => remove()); throw error;
+      }
+    }
+  } catch (error) {
+    logger.warn('Automatic group moderation unavailable', error instanceof Error ? error.message : String(error));
+  }
+}
+
 /**
  * Masters from plugin config + optional metadata.endpointMaster / metadata.master.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-content-moderation",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Content moderation plugin for Zhin.js — inbound/outbound multi-source scanning (Plugin Runtime)",
   "type": "module",
   "main": "./lib/index.js",
@@ -37,13 +37,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@zhin.js/core": "1.1.49",
+    "@zhin.js/core": "1.1.51",
     "@zhin.js/logger": "1.1.2"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zhin.js": "1.1.14"
+    "zhin.js": "1.1.16"
   },
   "repository": {
     "type": "git",
@@ -72,8 +72,8 @@
     "plugins": []
   },
   "peerDependencies": {
-    "@zhin.js/middleware": "^1.1.8",
-    "zhin.js": "^1.1.14"
+    "@zhin.js/middleware": "^1.1.10",
+    "zhin.js": "^1.1.16"
   },
   "peerDependenciesMeta": {
     "@zhin.js/middleware": {

package/plugin.js

@@ -14,5 +14,6 @@ export default definePlugin({
         const engine = new ModerationEngine();
         engine.configure(context.config.get());
         context.resources.provide(moderationEngineToken, engine);
+        return () => engine.groupReviewQueue.stop();
     },
 });

package/schema.json

@@ -3,44 +3,119 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
+    "groupModeration": {
+      "type": "array",
+      "default": [],
+      "description": "自动广告/辱骂审核的精确范围；未配置时关闭。需要 AI、原子持久状态和适配器群管支持。",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "adapter",
+          "endpoint",
+          "account",
+          "group"
+        ],
+        "properties": {
+          "adapter": {
+            "type": "string",
+            "minLength": 1
+          },
+          "endpoint": {
+            "type": "string",
+            "minLength": 1
+          },
+          "account": {
+            "type": "string",
+            "minLength": 1
+          },
+          "group": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "x-i18n": {
+        "en": {
+          "description": "Exact scope for automatic advertising/abuse moderation. Disabled when unconfigured. Requires AI, atomic persistent state and adapter group-management support."
+        }
+      }
+    },
     "enabled": {
       "type": "boolean",
       "default": true,
-      "description": "总开关"
+      "description": "总开关",
+      "x-i18n": {
+        "en": {
+          "description": "Enable moderation."
+        }
+      }
     },
     "onError": {
       "type": "string",
-      "enum": ["open", "closed"],
+      "enum": [
+        "open",
+        "closed"
+      ],
       "default": "open",
-      "description": "审查源失败时的全局默认策略：open=视为通过，closed=视为 critical"
+      "description": "审查源失败时的全局默认策略：open=视为通过，closed=视为 critical",
+      "x-i18n": {
+        "en": {
+          "description": "Default policy when a review source fails: open treats it as passed; closed treats it as critical."
+        }
+      }
     },
     "maskChar": {
       "type": "string",
       "default": "*",
       "minLength": 1,
       "maxLength": 4,
-      "description": "文本打码字符"
+      "description": "文本打码字符",
+      "x-i18n": {
+        "en": {
+          "description": "Text masking character."
+        }
+      }
     },
     "replyTemplate": {
       "type": "string",
-      "default": "消息含不当内容，已拦截。",
-      "description": "reply 动作时的提示文案"
+      "description": "reply 动作时的提示文案；省略时按本次消息语言选择默认文案，显式文本保持原样",
+      "x-i18n": {
+        "en": {
+          "description": "Reply text for the reply action. When omitted, use the message language; explicit text is preserved."
+        }
+      }
     },
     "masters": {
       "type": "array",
-      "items": { "type": "string" },
+      "items": {
+        "type": "string"
+      },
       "default": [],
-      "description": "额外视为 master 的 userId（兜底，与 endpoint master 合并）"
+      "description": "额外视为 master 的 userId（兜底，与 endpoint master 合并）",
+      "x-i18n": {
+        "en": {
+          "description": "Additional user IDs treated as masters, merged with endpoint masters as a fallback."
+        }
+      }
     },
     "inbound": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "enabled": { "type": "boolean", "default": true },
+        "enabled": {
+          "type": "boolean",
+          "default": true
+        },
         "bypassMasters": {
           "type": "boolean",
           "default": true,
-          "description": "master 跳过入站审查"
+          "description": "master 跳过入站审查",
+          "x-i18n": {
+            "en": {
+              "description": "Skip inbound review for masters."
+            }
+          }
         },
         "whitelist": {
           "type": "object",
@@ -48,12 +123,16 @@
           "properties": {
             "userIds": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "default": []
             },
             "conversationIds": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "default": []
             }
           }
@@ -64,11 +143,19 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "enabled": { "type": "boolean", "default": true },
+        "enabled": {
+          "type": "boolean",
+          "default": true
+        },
         "bypass": {
           "type": "boolean",
           "default": false,
-          "description": "为 true 时跳过出站审查"
+          "description": "为 true 时跳过出站审查",
+          "x-i18n": {
+            "en": {
+              "description": "Skip outbound review when true."
+            }
+          }
         }
       }
     },
@@ -81,14 +168,28 @@
           "anyOf": [
             {
               "type": "string",
-              "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+              "enum": [
+                "allow",
+                "log",
+                "reply",
+                "redact",
+                "drop",
+                "recall"
+              ]
             },
             {
               "type": "array",
               "minItems": 1,
               "items": {
                 "type": "string",
-                "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+                "enum": [
+                  "allow",
+                  "log",
+                  "reply",
+                  "redact",
+                  "drop",
+                  "recall"
+                ]
               }
             }
           ]
@@ -97,14 +198,28 @@
           "anyOf": [
             {
               "type": "string",
-              "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+              "enum": [
+                "allow",
+                "log",
+                "reply",
+                "redact",
+                "drop",
+                "recall"
+              ]
             },
             {
               "type": "array",
               "minItems": 1,
               "items": {
                 "type": "string",
-                "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+                "enum": [
+                  "allow",
+                  "log",
+                  "reply",
+                  "redact",
+                  "drop",
+                  "recall"
+                ]
               }
             }
           ]
@@ -113,14 +228,28 @@
           "anyOf": [
             {
               "type": "string",
-              "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+              "enum": [
+                "allow",
+                "log",
+                "reply",
+                "redact",
+                "drop",
+                "recall"
+              ]
             },
             {
               "type": "array",
               "minItems": 1,
               "items": {
                 "type": "string",
-                "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+                "enum": [
+                  "allow",
+                  "log",
+                  "reply",
+                  "redact",
+                  "drop",
+                  "recall"
+                ]
               }
             }
           ]
@@ -129,14 +258,28 @@
           "anyOf": [
             {
               "type": "string",
-              "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+              "enum": [
+                "allow",
+                "log",
+                "reply",
+                "redact",
+                "drop",
+                "recall"
+              ]
             },
             {
               "type": "array",
               "minItems": 1,
               "items": {
                 "type": "string",
-                "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+                "enum": [
+                  "allow",
+                  "log",
+                  "reply",
+                  "redact",
+                  "drop",
+                  "recall"
+                ]
               }
             }
           ]
@@ -145,18 +288,37 @@
           "anyOf": [
             {
               "type": "string",
-              "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+              "enum": [
+                "allow",
+                "log",
+                "reply",
+                "redact",
+                "drop",
+                "recall"
+              ]
             },
             {
               "type": "array",
               "minItems": 1,
               "items": {
                 "type": "string",
-                "enum": ["allow", "log", "reply", "redact", "drop", "recall"]
+                "enum": [
+                  "allow",
+                  "log",
+                  "reply",
+                  "redact",
+                  "drop",
+                  "recall"
+                ]
               }
             }
           ]
         }
+      },
+      "x-i18n": {
+        "en": {
+          "description": "Severity-to-action mapping (string or array); uses the stricter default mapping when omitted."
+        }
       }
     },
     "sources": {
@@ -164,17 +326,43 @@
       "default": [],
       "items": {
         "type": "object",
-        "required": ["id", "type"],
+        "required": [
+          "id",
+          "type"
+        ],
         "additionalProperties": false,
         "properties": {
-          "id": { "type": "string", "minLength": 1 },
-          "type": { "type": "string", "enum": ["local", "http"] },
-          "enabled": { "type": "boolean", "default": true },
-          "onError": { "type": "string", "enum": ["open", "closed"] },
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "local",
+              "http"
+            ]
+          },
+          "enabled": {
+            "type": "boolean",
+            "default": true
+          },
+          "onError": {
+            "type": "string",
+            "enum": [
+              "open",
+              "closed"
+            ]
+          },
           "includeBuiltin": {
             "type": "boolean",
             "default": true,
-            "description": "是否合并内置分级违禁词词库"
+            "description": "是否合并内置分级违禁词词库",
+            "x-i18n": {
+              "en": {
+                "description": "Include the built-in graded blocked-word dictionary."
+              }
+            }
           },
           "words": {
             "type": "array",
@@ -182,45 +370,97 @@
             "description": "自定义词：字符串（用 defaultSeverity）或 { word, severity }",
             "items": {
               "anyOf": [
-                { "type": "string", "minLength": 1 },
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
                 {
                   "type": "object",
                   "additionalProperties": false,
-                  "required": ["word"],
+                  "required": [
+                    "word"
+                  ],
                   "properties": {
-                    "word": { "type": "string", "minLength": 1 },
-                    "text": { "type": "string", "minLength": 1 },
+                    "word": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "text": {
+                      "type": "string",
+                      "minLength": 1
+                    },
                     "severity": {
                       "type": "string",
-                      "enum": ["low", "medium", "high", "critical"]
+                      "enum": [
+                        "low",
+                        "medium",
+                        "high",
+                        "critical"
+                      ]
                     }
                   }
                 }
               ]
+            },
+            "x-i18n": {
+              "en": {
+                "description": "Custom words: strings using defaultSeverity, or { word, severity } objects."
+              }
             }
           },
           "wordFiles": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "default": [],
-            "description": "词库文件；行格式 word / severity:word / word|severity"
+            "description": "词库文件；行格式 word / severity:word / word|severity",
+            "x-i18n": {
+              "en": {
+                "description": "Dictionary file; line formats: word, severity:word, or word|severity."
+              }
+            }
           },
           "defaultSeverity": {
             "type": "string",
-            "enum": ["low", "medium", "high", "critical"],
+            "enum": [
+              "low",
+              "medium",
+              "high",
+              "critical"
+            ],
             "default": "high",
-            "description": "未标注分级的自定义词默认 severity"
+            "description": "未标注分级的自定义词默认 severity",
+            "x-i18n": {
+              "en": {
+                "description": "Default severity for custom words without an explicit severity."
+              }
+            }
           },
           "severity": {
             "type": "string",
-            "enum": ["low", "medium", "high", "critical"],
+            "enum": [
+              "low",
+              "medium",
+              "high",
+              "critical"
+            ],
             "default": "high",
-            "description": "兼容旧字段，等同 defaultSeverity"
+            "description": "兼容旧字段，等同 defaultSeverity",
+            "x-i18n": {
+              "en": {
+                "description": "Legacy alias for defaultSeverity."
+              }
+            }
+          },
+          "url": {
+            "type": "string"
           },
-          "url": { "type": "string" },
           "headers": {
             "type": "object",
-            "additionalProperties": { "type": "string" }
+            "additionalProperties": {
+              "type": "string"
+            }
           },
           "timeoutMs": {
             "type": "number",
@@ -231,7 +471,12 @@
           "forceUpload": {
             "type": "boolean",
             "default": false,
-            "description": "强制下载图片后上传，不传 URL"
+            "description": "强制下载图片后上传，不传 URL",
+            "x-i18n": {
+              "en": {
+                "description": "Download images before uploading them instead of passing the URL."
+              }
+            }
           }
         }
       }