@zhin.js/plugin-content-moderation 1.0.0

package/src/providers/builtin-lexicon.ts

@@ -0,0 +1,149 @@
+import type { Severity } from '../types.js';
+
+export type LexiconSeverity = Exclude<Severity, 'pass'>;
+
+export interface LexiconEntry {
+  readonly word: string;
+  readonly severity: LexiconSeverity;
+}
+
+/**
+ * Built-in graded lexicon for IM bots (starter set).
+ * Users can extend / override via `words` / `wordFiles`; same word keeps the
+ * higher severity when merging.
+ */
+export const BUILTIN_LEXICON: readonly LexiconEntry[] = Object.freeze([
+  // —— low：轻度不当 / 骚扰语气 ——
+  entry('脑残', 'low'),
+  entry('智障', 'low'),
+  entry('废物', 'low'),
+  entry('垃圾人', 'low'),
+  entry('滚蛋', 'low'),
+  entry('去死', 'low'),
+  entry('找死', 'low'),
+  entry('闭嘴', 'low'),
+  entry('恶心', 'low'),
+  entry('变态', 'low'),
+
+  // —— medium：辱骂 / 粗口 ——
+  entry('傻逼', 'medium'),
+  entry('傻B', 'medium'),
+  entry('傻b', 'medium'),
+  entry('傻叉', 'medium'),
+  entry('操逼', 'medium'),
+  entry('草泥马', 'medium'),
+  entry('妈的', 'medium'),
+  entry('他妈的', 'medium'),
+  entry('你妈的', 'medium'),
+  entry('卧槽', 'medium'),
+  entry('日你', 'medium'),
+  entry('操你', 'medium'),
+  entry('操他', 'medium'),
+  entry('狗日的', 'medium'),
+  entry('混蛋', 'medium'),
+  entry('王八蛋', 'medium'),
+  entry('白痴', 'medium'),
+  entry('去死吧', 'medium'),
+
+  // —— high：色情 / 引流诈骗常见话术 ——
+  entry('约炮', 'high'),
+  entry('裸聊', 'high'),
+  entry('色情', 'high'),
+  entry('黄色网站', 'high'),
+  entry('看片加', 'high'),
+  entry('援交', 'high'),
+  entry('包养', 'high'),
+  entry('上门服务', 'high'),
+  entry('加微信领', 'high'),
+  entry('刷单返利', 'high'),
+  entry('刷单赚钱', 'high'),
+  entry('日赚千元', 'high'),
+  entry('稳赚不赔', 'high'),
+  entry('内幕消息', 'high'),
+  entry('代开发票', 'high'),
+  entry('办假证', 'high'),
+  entry('假钞', 'high'),
+  entry('色情服务', 'high'),
+  entry('一夜情', 'high'),
+
+  // —— high：中国政治敏感（常见审查词，可按业务在配置中覆盖/关闭内置）——
+  entry('台独', 'high'),
+  entry('藏独', 'high'),
+  entry('疆独', 'high'),
+  entry('港独', 'high'),
+  entry('分裂国家', 'high'),
+  entry('民族分裂', 'high'),
+  entry('法轮功', 'high'),
+  entry('法轮大法', 'high'),
+  entry('六四事件', 'high'),
+  entry('六四屠城', 'high'),
+  entry('天安门事件', 'high'),
+  entry('坦克人', 'high'),
+  entry('学潮动乱', 'high'),
+  entry('政治风波', 'high'),
+  entry('打倒共产党', 'high'),
+  entry('推翻共产党', 'high'),
+  entry('颠覆国家政权', 'high'),
+  entry('占中运动', 'high'),
+  entry('反送中', 'high'),
+  entry('香港独立', 'high'),
+  entry('台湾独立', 'high'),
+  entry('西藏独立', 'high'),
+  entry('新疆独立', 'high'),
+  entry('东突厥斯坦', 'high'),
+  entry('民运人士', 'high'),
+  entry('零八宪章', 'high'),
+  entry('煽动颠覆', 'high'),
+  entry('颜色革命', 'high'),
+  entry('大跃进饿死', 'high'),
+  entry('文革迫害', 'high'),
+
+  // —— critical：毒品 / 极端违法 / 煽动暴力颠覆 ——
+  entry('冰毒', 'critical'),
+  entry('海洛因', 'critical'),
+  entry('可卡因', 'critical'),
+  entry('大麻走私', 'critical'),
+  entry('售卖枪支', 'critical'),
+  entry('买卖枪支', 'critical'),
+  entry('制毒', 'critical'),
+  entry('贩毒', 'critical'),
+  entry('炸药制作', 'critical'),
+  entry('儿童色情', 'critical'),
+  entry('幼女援交', 'critical'),
+  entry('武装暴动', 'critical'),
+  entry('暴力推翻政权', 'critical'),
+  entry('刺杀国家领导人', 'critical'),
+]);
+
+function entry(word: string, severity: LexiconSeverity): LexiconEntry {
+  return Object.freeze({ word, severity });
+}
+
+/** Merge entries; duplicate words keep the higher severity. */
+export function mergeLexiconEntries(
+  ...lists: Array<readonly LexiconEntry[] | undefined>
+): readonly LexiconEntry[] {
+  const map = new Map<string, LexiconSeverity>();
+  const rank: Record<LexiconSeverity, number> = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+  };
+  for (const list of lists) {
+    if (!list) continue;
+    for (const item of list) {
+      const word = item.word.trim();
+      if (!word) continue;
+      const prev = map.get(word);
+      if (!prev || rank[item.severity] > rank[prev]) {
+        map.set(word, item.severity);
+      }
+    }
+  }
+  return Object.freeze(
+    [...map.entries()]
+      .map(([word, severity]) => Object.freeze({ word, severity }))
+      .sort((a, b) => b.word.length - a.word.length || a.word.localeCompare(b.word)),
+  );
+}

package/src/providers/http.ts

@@ -0,0 +1,225 @@
+import { readFileSync } from 'node:fs';
+import type {
+  ExtractedImage,
+  HttpSourceConfig,
+  ProviderResult,
+  ScanInput,
+  Severity,
+  TextMatch,
+} from '../types.js';
+import { isSeverity } from '../types.js';
+import type { ModerationProvider } from './types.js';
+
+export interface HttpProviderDeps {
+  readonly fetch?: typeof fetch;
+}
+
+export class HttpModerationProvider implements ModerationProvider {
+  readonly id: string;
+  readonly #config: HttpSourceConfig;
+  readonly #fetch: typeof fetch;
+
+  constructor(config: HttpSourceConfig, deps: HttpProviderDeps = {}) {
+    this.id = config.id;
+    this.#config = config;
+    this.#fetch = deps.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async scan(input: ScanInput): Promise<ProviderResult> {
+    try {
+      const images = await prepareImages(input.images, this.#config.forceUpload, this.#fetch);
+      const useMultipart = images.some((img) => img.mode === 'upload');
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.#config.timeoutMs);
+      try {
+        const response = useMultipart
+          ? await this.#postMultipart(input, images, controller.signal)
+          : await this.#postJson(input, images, controller.signal);
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+        const body = await response.json() as unknown;
+        return parseHttpResult(this.id, body);
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch (error) {
+      return Object.freeze({
+        sourceId: this.id,
+        severity: this.#config.onError === 'closed' ? 'critical' as const : 'pass' as const,
+        error: true,
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async #postJson(
+    input: ScanInput,
+    images: readonly PreparedImage[],
+    signal: AbortSignal,
+  ): Promise<Response> {
+    const body = {
+      text: input.text,
+      images: images.map((img) => (
+        img.mode === 'url'
+          ? { url: img.url }
+          : { base64: img.base64, mime: img.mime }
+      )),
+      direction: input.direction,
+      context: input.context,
+    };
+    return this.#fetch(this.#config.url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...this.#config.headers,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+  }
+
+  async #postMultipart(
+    input: ScanInput,
+    images: readonly PreparedImage[],
+    signal: AbortSignal,
+  ): Promise<Response> {
+    const form = new FormData();
+    form.set('text', input.text);
+    form.set('direction', input.direction);
+    form.set('context', JSON.stringify(input.context));
+    for (const [i, img] of images.entries()) {
+      if (img.mode === 'url') {
+        form.append('images', JSON.stringify({ index: i, url: img.url }));
+      } else {
+        const bytes = Uint8Array.from(Buffer.from(img.base64, 'base64'));
+        const mime = img.mime || 'application/octet-stream';
+        form.append(
+          'images',
+          new Blob([bytes], { type: mime }),
+          `image-${i}.${extensionForMime(mime)}`,
+        );
+      }
+    }
+    return this.#fetch(this.#config.url, {
+      method: 'POST',
+      headers: { ...this.#config.headers },
+      body: form,
+      signal,
+    });
+  }
+}
+
+type PreparedImage =
+  | { readonly mode: 'url'; readonly url: string }
+  | { readonly mode: 'upload'; readonly base64: string; readonly mime?: string };
+
+async function prepareImages(
+  images: readonly ExtractedImage[],
+  forceUpload: boolean,
+  fetchImpl: typeof fetch,
+): Promise<PreparedImage[]> {
+  const out: PreparedImage[] = [];
+  for (const image of images) {
+    if (!forceUpload && image.url && isPublicHttpUrl(image.url)) {
+      out.push({ mode: 'url', url: image.url });
+      continue;
+    }
+    if (image.base64) {
+      out.push({ mode: 'upload', base64: image.base64, mime: image.mime });
+      continue;
+    }
+    if (image.path) {
+      const buf = readFileSync(image.path);
+      out.push({
+        mode: 'upload',
+        base64: buf.toString('base64'),
+        mime: image.mime,
+      });
+      continue;
+    }
+    if (image.url) {
+      const downloaded = await downloadAsBase64(image.url, fetchImpl);
+      out.push({ mode: 'upload', base64: downloaded.base64, mime: downloaded.mime ?? image.mime });
+      continue;
+    }
+    // Opaque file refs: skip (cannot fetch without platform API)
+  }
+  return out;
+}
+
+async function downloadAsBase64(
+  url: string,
+  fetchImpl: typeof fetch,
+): Promise<{ base64: string; mime?: string }> {
+  const response = await fetchImpl(url);
+  if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+  const mime = response.headers.get('content-type') ?? undefined;
+  const buf = Buffer.from(await response.arrayBuffer());
+  return { base64: buf.toString('base64'), mime };
+}
+
+export function isPublicHttpUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+export function parseHttpResult(sourceId: string, body: unknown): ProviderResult {
+  if (!body || typeof body !== 'object') {
+    throw new Error('invalid moderation response');
+  }
+  const record = body as Record<string, unknown>;
+  if (!isSeverity(record.severity)) {
+    throw new Error('invalid severity in moderation response');
+  }
+  const severity = record.severity as Severity;
+  const matches = parseMatches(record.matches);
+  const flaggedImageIndexes = parseFlaggedImages(record.images);
+  return Object.freeze({
+    sourceId,
+    severity,
+    ...(matches.length ? { matches } : {}),
+    ...(flaggedImageIndexes.length ? { flaggedImageIndexes } : {}),
+    ...(typeof record.reason === 'string' ? { reason: record.reason } : {}),
+  });
+}
+
+function parseMatches(raw: unknown): readonly TextMatch[] {
+  if (!Array.isArray(raw)) return Object.freeze([]);
+  const out: TextMatch[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const start = (item as { start?: unknown }).start;
+    const end = (item as { end?: unknown }).end;
+    if (typeof start !== 'number' || typeof end !== 'number') continue;
+    if (!(end > start) || start < 0) continue;
+    out.push({ start: Math.trunc(start), end: Math.trunc(end) });
+  }
+  return Object.freeze(out);
+}
+
+function parseFlaggedImages(raw: unknown): readonly number[] {
+  if (!Array.isArray(raw)) return Object.freeze([]);
+  const out: number[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const index = (item as { index?: unknown }).index;
+    const flagged = (item as { flagged?: unknown }).flagged;
+    if (typeof index === 'number' && Number.isFinite(index) && flagged === true) {
+      out.push(Math.trunc(index));
+    }
+  }
+  return Object.freeze(out);
+}
+
+function extensionForMime(mime: string): string {
+  if (mime.includes('png')) return 'png';
+  if (mime.includes('jpeg') || mime.includes('jpg')) return 'jpg';
+  if (mime.includes('gif')) return 'gif';
+  if (mime.includes('webp')) return 'webp';
+  return 'bin';
+}

package/src/providers/local-lexicon.ts

@@ -0,0 +1,148 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { maxSeverity, type LocalSourceConfig, type ProviderResult, type ScanInput, type TextMatch } from '../types.js';
+import type { LexiconEntry, LexiconSeverity } from './builtin-lexicon.js';
+import { BUILTIN_LEXICON, mergeLexiconEntries } from './builtin-lexicon.js';
+import type { ModerationProvider } from './types.js';
+
+export interface GradedMatch extends TextMatch {
+  readonly word: string;
+  readonly severity: LexiconSeverity;
+}
+
+export class LocalLexiconProvider implements ModerationProvider {
+  readonly id: string;
+  readonly #entries: readonly LexiconEntry[];
+  readonly #onError: LocalSourceConfig['onError'];
+
+  constructor(config: LocalSourceConfig, cwd: string = process.cwd()) {
+    this.id = config.id;
+    this.#onError = config.onError;
+    this.#entries = Object.freeze(loadLexiconEntries(config, cwd));
+  }
+
+  async scan(input: ScanInput): Promise<ProviderResult> {
+    try {
+      const matches = findGradedMatches(input.text, this.#entries);
+      if (matches.length === 0) {
+        return Object.freeze({
+          sourceId: this.id,
+          severity: 'pass' as const,
+        });
+      }
+      let severity: LexiconSeverity = matches[0]!.severity;
+      for (const match of matches) {
+        severity = maxSeverity(severity, match.severity) as LexiconSeverity;
+      }
+      return Object.freeze({
+        sourceId: this.id,
+        severity,
+        matches: Object.freeze(matches.map(({ start, end }) => ({ start, end }))),
+        reason: `lexicon hit (${matches.length}, max=${severity})`,
+      });
+    } catch (error) {
+      return Object.freeze({
+        sourceId: this.id,
+        severity: this.#onError === 'closed' ? 'critical' as const : 'pass' as const,
+        error: true,
+        reason: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}
+
+export function loadLexiconEntries(config: LocalSourceConfig, cwd: string): readonly LexiconEntry[] {
+  const custom: LexiconEntry[] = [];
+  for (const item of config.words) {
+    custom.push({ word: item.word, severity: item.severity });
+  }
+  for (const file of config.wordFiles) {
+    custom.push(...parseWordFile(readFileSync(resolve(cwd, file), 'utf8'), config.defaultSeverity));
+  }
+  const builtin = config.includeBuiltin ? BUILTIN_LEXICON : undefined;
+  return mergeLexiconEntries(builtin, custom);
+}
+
+/** @deprecated Use loadLexiconEntries; kept for tests that only need bare words. */
+export function loadWords(config: LocalSourceConfig, cwd: string): string[] {
+  return loadLexiconEntries(config, cwd).map((e) => e.word);
+}
+
+export function findMatches(text: string, words: readonly string[]): readonly TextMatch[] {
+  const entries = words.map((word) => ({ word, severity: 'high' as const }));
+  return findGradedMatches(text, entries).map(({ start, end }) => ({ start, end }));
+}
+
+export function findGradedMatches(
+  text: string,
+  entries: readonly LexiconEntry[],
+): readonly GradedMatch[] {
+  if (!text || entries.length === 0) return Object.freeze([]);
+  const matches: GradedMatch[] = [];
+  for (const entry of entries) {
+    if (!entry.word) continue;
+    let from = 0;
+    while (from < text.length) {
+      const idx = text.indexOf(entry.word, from);
+      if (idx < 0) break;
+      matches.push({
+        start: idx,
+        end: idx + entry.word.length,
+        word: entry.word,
+        severity: entry.severity,
+      });
+      from = idx + entry.word.length;
+    }
+  }
+  matches.sort((a, b) => a.start - b.start || b.end - a.end);
+  return Object.freeze(matches);
+}
+
+/**
+ * Word-file lines:
+ * - `# comment`
+ * - `word`                         → defaultSeverity
+ * - `severity:word`                 → graded（low|medium|high|critical）
+ * - `word|severity`                 → graded
+ */
+export function parseWordFile(
+  content: string,
+  defaultSeverity: LexiconSeverity,
+): LexiconEntry[] {
+  const out: LexiconEntry[] = [];
+  for (const line of content.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const parsed = parseWordLine(trimmed, defaultSeverity);
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+
+export function parseWordLine(
+  line: string,
+  defaultSeverity: LexiconSeverity,
+): LexiconEntry | null {
+  const pipe = line.indexOf('|');
+  if (pipe > 0) {
+    const word = line.slice(0, pipe).trim();
+    const severity = parseSeverityToken(line.slice(pipe + 1).trim()) ?? defaultSeverity;
+    return word ? { word, severity } : null;
+  }
+  const colon = line.indexOf(':');
+  if (colon > 0) {
+    const maybeSeverity = parseSeverityToken(line.slice(0, colon).trim());
+    if (maybeSeverity) {
+      const word = line.slice(colon + 1).trim();
+      return word ? { word, severity: maybeSeverity } : null;
+    }
+  }
+  return { word: line, severity: defaultSeverity };
+}
+
+function parseSeverityToken(value: string): LexiconSeverity | null {
+  if (value === 'low' || value === 'medium' || value === 'high' || value === 'critical') {
+    return value;
+  }
+  return null;
+}

package/src/providers/registry.ts

@@ -0,0 +1,37 @@
+import type { ModerationConfig, SourceConfig } from '../types.js';
+import { HttpModerationProvider } from './http.js';
+import { LocalLexiconProvider } from './local-lexicon.js';
+import type { ModerationProvider } from './types.js';
+
+export interface CreateProvidersOptions {
+  readonly cwd?: string;
+  readonly fetch?: typeof fetch;
+}
+
+export function createProviders(
+  config: ModerationConfig,
+  options: CreateProvidersOptions = {},
+): readonly ModerationProvider[] {
+  const cwd = options.cwd ?? process.cwd();
+  const providers: ModerationProvider[] = [];
+  for (const source of config.sources) {
+    if (!source.enabled) continue;
+    const provider = createProvider(source, cwd, options.fetch);
+    if (provider) providers.push(provider);
+  }
+  return Object.freeze(providers);
+}
+
+function createProvider(
+  source: SourceConfig,
+  cwd: string,
+  fetchImpl?: typeof fetch,
+): ModerationProvider | null {
+  if (source.type === 'local') {
+    return new LocalLexiconProvider(source, cwd);
+  }
+  if (source.type === 'http') {
+    return new HttpModerationProvider(source, { fetch: fetchImpl });
+  }
+  return null;
+}

package/src/providers/types.ts

@@ -0,0 +1,6 @@
+import type { ProviderResult, ScanInput } from '../types.js';
+
+export interface ModerationProvider {
+  readonly id: string;
+  scan(input: ScanInput): Promise<ProviderResult>;
+}