zephyrisle/flarum-ai-audit

AI-assisted content moderation for Flarum - supports posts, discussions, users, avatars, nicknames, bios, profile covers, images, and file uploads

dev-main 2026-08-30 04:20 UTC

Requires

• ext-json: *
• flarum/approval: ^2.0
• flarum/core: ^2.0
• flarum/suspend: ^2.0
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^9.5|^10.0|^11.0

Suggests

• flarum/nicknames: For auditing user nickname changes
• fof/upload: For auditing uploaded file content
• fof/user-bio: For auditing user bio/signature changes
• forumaker/profile-cover: For auditing profile cover image changes

MIT

Published on Packagist.org on 2026-08-30 04:23 UTC

README

一个用于 Flarum 的 AI 内容审核扩展，支持 OpenAI 兼容的 Chat Completions API（/v1/chat/completions）。

功能

• 自动采集内容快照：新回复、新讨论、用户资料变更（用户名/昵称/头像/签名/封面）、私信消息、上传文件
• 双阶段策略：本地信号评分 + 可选 LLM 判定（JSON Schema 输出，支持图片多模态）
• 自动动作：进入人工复核、隐藏（基于 is_approved）、删除私信、可选封禁/改名/重置资料
• 预审核：新内容先标记为未审核，AI 判定安全后自动放行
• 同主题去重：冷却窗口内重复保存不重复入队，节省 API 费用
• 自杀风险检测：前台暖性弹窗提醒 + 管理员通知（不做惩罚性动作）
• 审核日志：后台列表/详情页 + 支持重试

环境要求

• Flarum： ^2.0（含 flarum/approval、flarum/suspend）
• 可选依赖：flarum/flags（“加入待审核队列” Flag）、flarum/messages（私信审核）、fof/upload（上传审核）

安装

在 Flarum 根目录执行：

composer require zephyrisle/flarum-ai-audit
php flarum migrate
php flarum cache:clear

如果你修改了扩展前端源码，请重新构建并清理缓存：

cd js
npm install
npm run build
cd ..
php flarum cache:clear

配置项

后台 → 扩展 → AI Audit：

API 连接

键	说明	默认值
api_endpoint	OpenAI 兼容 API Endpoint	https://api.openai.com/v1
api_key	API Key（留空则仅用本地信号评分）	空
model	模型名	gpt-4o-mini
temperature	温度	0.2
max_tokens	最大输出 token	800
timeout	请求超时秒数	30
system_prompt	系统提示词（留空使用内置按类型动态提示）	空
use_json_schema	使用 JSON Schema 结构化输出（关闭则用 json_object）	true

审核策略

键	说明	默认值
pre_approve_enabled	预审核：新内容先标记为未审核，AI 判定安全后自动放行	false
review_threshold	进入人工复核阈值	0.55
action_threshold	自动动作阈值（不低于复核阈值）	0.75
suspend_days	封禁天数	7
dedup_window	同主题去重冷却窗口（秒），0 关闭	120

内容类型开关

键	默认值
enable_post_content_audit / enable_post_image_audit	true
enable_discussion_title_audit	true
enable_username_audit / enable_nickname_audit	true
enable_avatar_audit / enable_bio_audit / enable_cover_audit	true
enable_upload_audit / enable_message_audit	true

其他

键	说明	默认值
download_images	是否下载图片写入快照供多模态判定	true
image_download_timeout	图片下载超时秒数	8
enable_context	快照附带上下文	true
enable_notifications	惩罚性动作时通知作者	true

说明：

• is_approved 字段并非所有安装都存在；扩展会在运行时检测字段是否存在，避免数据库报错。
• 未配置 api_key 时不会调用 LLM，仅使用本地信号评分。

运行行为

• 预审核放行：开启 pre_approve_enabled 后，AI 判定安全（无任何动作）的帖子/主题会自动恢复 is_approved = true；判定违规则保持隐藏并进入人工复核。
• 去重冷却：同一主题在 dedup_window 秒内已有进行中（pending/retrying）的审核时不再入队。进行中的任务会从数据库读取最新内容快照，因此快速连续编辑只会产生一次 LLM 调用。
• 通知策略：仅当施加惩罚性动作（隐藏/删除/封禁/改名/重置资料等）时才通知作者；仅标记 review 或 flag 时保持静默，避免骚扰。
• 审核日志列表、详情、重试接口均要求已登录且具备对应后台权限。
• 列表查询参数会自动收敛：page.limit 最大 100，page.offset 最小 0。
• pending 或 retrying 状态的日志不可重复重试，避免重复入队。
• 图片快照下载仅允许外部 http/https 地址，默认阻止 localhost、内网 IP、保留地址等高风险目标。
• API 报错时会提取响应体中的错误信息写入日志错误字段，便于排障。

权限

后台权限页可配置：

• zephyrisle-ai-audit.viewAuditLogs：查看审核日志
• zephyrisle-ai-audit.viewFullAuditLogs：查看完整日志（含快照/分析/错误）
• zephyrisle-ai-audit.retryAudit：重试审核
• zephyrisle-ai-audit.bypassAudit：跳过 AI 审核
• zephyrisle-ai-audit.bypassPreApprove：跳过预审核

API

• GET /api/ai-audit/logs
• GET /api/ai-audit/logs/{id}
• POST /api/ai-audit/logs/{id}/retry

测试

composer install
composer test