@zhin.js/plugin-content-moderation 1.1.15 → 1.1.17

package/middlewares/inbound/index.ts

@@ -3,7 +3,9 @@ import type { Message } from '@zhin.js/core/runtime';
 import { aiCompletionToken, createDeliveryTarget, databaseHostToken, getLogger, hasResource,
   outboundHostToken, usageSubjectFromMessage } from 'zhin.js';
 import { adapterFeatureId, type AdapterIndex } from 'zhin.js/adapter';
+import { groupRuleViolationToken, type GroupRuleViolationSink } from '@zhin.js/core/runtime';
 import { generationAdmissionSource } from 'zhin.js/plugin-runtime';
+import { resolveLocale } from 'zhin.js/i18n';
 import {
   buildScanContext,
   extractFromTextAndSegments,
@@ -30,6 +32,7 @@ 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);
@@ -70,6 +73,7 @@ export default defineMiddleware<Message, ModerationConfig>({
 
     const result = await engine.apply({
       direction: 'inbound',
+      locale,
       recallManaged: review?.done,
       extracted,
       scanInput,
@@ -115,6 +119,7 @@ async function enqueueGroupModeration(
   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
@@ -132,6 +137,19 @@ async function enqueueGroupModeration(
     const destination = createDeliveryTarget({ conversation });
     const scope = JSON.stringify(destination);
     const remembered = engine.groupModerator.remember(scope, message.sender?.id ?? '', text);
+    // ADR 0039 §5: punishment is the group rule's job. A configured group gets default pending rules once,
+    // and stays reminder / warning only until an owner or admin confirms them.
+    const rules: GroupRuleViolationSink | undefined = hasResource(context, groupRuleViolationToken)
+      ? context.use(groupRuleViolationToken) : undefined;
+    if (rules) {
+      engine.groupModerator.ensureRules(scope, async () => {
+        for (const trigger of ['advertising', 'abuse'] as const) {
+          const outcome = await rules.ensureDefaultRule({ conversation, trigger });
+          if (outcome === 'unavailable') throw new Error('Group rule storage unavailable');
+          if (outcome === 'created') logger.info({ event: 'group_rule_migrated', trigger, endpoint: conversation.endpoint.id, group: conversation.id });
+        }
+      });
+    }
     if (!bypass && message.sender?.id && message.origin !== 'self'
       && hasResource(context, aiCompletionToken) && hasResource(context, databaseHostToken)
       && hasResource(context, outboundHostToken)) {
@@ -151,7 +169,7 @@ async function enqueueGroupModeration(
       };
       try {
         const queued = await engine.groupReviewQueue.enqueue({
-          scope, group: conversation.id, sender: message.sender.id,
+          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),
@@ -159,17 +177,25 @@ async function enqueueGroupModeration(
             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,
           },
+          ...(rules ? { rules: async (hit) => {
+            assertTarget();
+            return rules.report({
+              conversation, memberId: message.sender!.id, trigger: hit.category, newcomer: hit.newcomer,
+              sentAt: Number(message.metadata?.platformSentAt), evidence: hit.evidence,
+              ...(message.sender?.name ? { memberName: message.sender.name } : {}),
+              ...(message.sender?.roles ? { memberRoles: message.sender.roles } : {}),
+              ...(messageId ? { messageId } : {}),
+              ...(hit.recall ? { recall: hit.recall } : {}),
+            });
+          } } : {}),
           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);
+            ] : content, { locale });
             if (!receipt) throw new Error('Moderation notice was not confirmed');
           },
           recall: async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-content-moderation",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "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.50",
+    "@zhin.js/core": "1.1.52",
     "@zhin.js/logger": "1.1.2"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zhin.js": "1.1.15"
+    "zhin.js": "1.1.17"
   },
   "repository": {
     "type": "git",
@@ -72,8 +72,8 @@
     "plugins": []
   },
   "peerDependencies": {
-    "@zhin.js/middleware": "^1.1.9",
-    "zhin.js": "^1.1.15"
+    "@zhin.js/middleware": "^1.1.10",
+    "zhin.js": "^1.1.17"
   },
   "peerDependenciesMeta": {
     "@zhin.js/middleware": {

package/schema.json

@@ -6,7 +6,7 @@
     "groupModeration": {
       "type": "array",
       "default": [],
-      "description": "自动广告/辱骂审核的精确范围；未配置时关闭。需要 AI、原子持久状态和适配器群管支持。",
+      "description": "自动广告/辱骂审核的精确范围；未配置时关闭。需要 AI、原子持久状态和适配器群管支持。禁言 / 踢人交给 Agent 群规（ADR 0039），名单内的群会生成待确认的默认规则，确认前只提醒 / 警告。",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -34,46 +34,88 @@
             "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",
@@ -81,12 +123,16 @@
           "properties": {
             "userIds": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "default": []
             },
             "conversationIds": {
               "type": "array",
-              "items": { "type": "string" },
+              "items": {
+                "type": "string"
+              },
               "default": []
             }
           }
@@ -97,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."
+            }
+          }
         }
       }
     },
@@ -114,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"
+                ]
               }
             }
           ]
@@ -130,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"
+                ]
               }
             }
           ]
@@ -146,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"
+                ]
               }
             }
           ]
@@ -162,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"
+                ]
               }
             }
           ]
@@ -178,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": {
@@ -197,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",
@@ -215,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",
@@ -264,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."
+              }
+            }
           }
         }
       }

package/src/config.ts

@@ -22,7 +22,6 @@ export const DEFAULT_MODERATION_CONFIG: ModerationConfig = Object.freeze({
   enabled: true,
   onError: 'open',
   maskChar: '*',
-  replyTemplate: '消息含不当内容，已拦截。',
   masters: Object.freeze([] as string[]),
   inbound: Object.freeze({
     enabled: true,
@@ -51,7 +50,7 @@ export function resolveModerationConfig(raw: unknown): ModerationConfig {
     : DEFAULT_MODERATION_CONFIG.maskChar;
   const replyTemplate = typeof input.replyTemplate === 'string' && input.replyTemplate.length > 0
     ? input.replyTemplate
-    : DEFAULT_MODERATION_CONFIG.replyTemplate;
+    : undefined;
 
   return Object.freeze({
     groupModeration: Object.freeze((Array.isArray(input.groupModeration) ? input.groupModeration : [])
@@ -66,7 +65,7 @@ export function resolveModerationConfig(raw: unknown): ModerationConfig {
     enabled: input.enabled !== false,
     onError,
     maskChar,
-    replyTemplate,
+    ...(replyTemplate === undefined ? {} : { replyTemplate }),
     masters: freezeStrings(input.masters),
     inbound: Object.freeze({
       enabled: inboundRaw.enabled !== false,

package/src/engine.ts

@@ -6,6 +6,8 @@ import { createProviders } from './providers/registry.js';
 import { GroupModerator } from './group-moderation.js';
 import { GroupReviewQueue } from './group-review-queue.js';
 import { generationAdmissionSource } from 'zhin.js/plugin-runtime';
+import type { Locale } from 'zhin.js/i18n';
+import { moderationMessages } from './messages.js';
 import type { ModerationProvider } from './providers/types.js';
 import {
   maxSeverity,
@@ -100,6 +102,7 @@ export class ModerationEngine {
 
   async apply(options: {
     readonly direction: Direction;
+    readonly locale?: Locale;
     readonly extracted: ExtractedContent;
     readonly scanInput: ScanInput;
     readonly hooks: ApplyHooks;
@@ -147,7 +150,7 @@ export class ModerationEngine {
 
     if (actionSet.has('reply') && options.direction === 'inbound') {
       try {
-        await options.hooks.reply?.(this.#config.replyTemplate);
+        await options.hooks.reply?.(this.#config.replyTemplate ?? moderationMessages(options.locale, 'blocked'));
       } catch (error) {
         this.#logger.warn(formatCompact({
           op: 'moderation_reply_failed',