Discord Guardian（启用MCP）
该项目提供了一个强大的两级Discord审核系统，旨在实现快速和智能。它结合了用于即时操作的本地预过滤器和用于对边缘内容进行细致决策的大型语言模型（LLM），所有这些都是通过模型上下文协议（MCP）编排的。MCP将审核操作作为结构化工具公开，确保LLM只能通过受约束和可观察的界面执行批准的、可审计的操作。
运作原理
适度逻辑遵循一个精确的、政策驱动的流程：
- 消息拦截：机器人会监听它可以访问的频道中的每条消息。
- 毒性评分：使用级联提供者系统对每条消息的毒性进行评分。它首先尝试Perspective API（如果提供了密钥），然后返回到本地
detoxify如果两者都不可用，则最终获得中性分数。 - 政策评估：根据中定义的规则检查消息的毒性评分
policies/moderation.yaml. - 行动调度：根据匹配的规则，触发一个或多个操作：
- 立即行动：对于明显的违规行为（例如“毒性极高”），机器人会立即删除消息并警告用户。 - 法学硕士评审：对于“Borderline”内容 ask_llm 动作被触发。机器人将消息内容发送到MCP服务器，MCP服务器使用LLM（如Gemini或Ollama模型）从可用工具列表中决定最佳行动方案(warn_user, delete_message, timeout_member，或 ignore).
- 升级引擎：机器人跟踪本地SQLite数据库中的所有审核操作。如果用户在配置的时间窗口内反复违反规则（例如，在60分钟内收到2个警告），升级引擎会自动应用更严重的操作，如超时。
- 审计跟踪：机器人采取的每一个行动都会被记录下来，提供清晰可审计的审核事件历史。
特性
- 政策驱动逻辑：以简单的方式定义所有审核规则
policies/moderation.yaml文件。无需更改代码来调整阈值。 - 两阶段缓和：将快速的局部毒性过滤器与基于LLM的智能裁决相结合，用于细微差别的案件。
- 模型上下文协议（MCP）：将审核操作暴露为LLM可以使用的“工具”
FastMCP，确保LLM只能执行经批准的结构化操作。 - 自动升级：自动超时或升级被反复警告的用户。
- 多提供商LLM支持：与Ollama（本地模型）、OpenAI、Anthropic和Gemini合作。
- 斜杠命令：提供用于检查机器人状态、查看审核历史、管理上诉等的命令。
- 角色豁免：轻松免除版主或其他受信任角色的审核操作。
- 结构化日志记录：所有日志都是结构化的（JSON格式可用），便于解析和监控。
- 地方优先发展：可以在本地完全运行和测试，而无需依赖外部服务。
项目结构
src/modbot/：主机器人应用程序，包含所有核心逻辑。
- domain/：业务逻辑、模型和接口。 - infrastructure/：数据库、法学硕士提供者和其他外部服务。 - discord/：Discord特定代码，包括命令和事件处理程序。
src/mcp_server/：MCP服务器，它将审核操作作为LLM的工具公开。policies/moderation.yaml：机器人的核心，在那里你定义了所有的审核规则。infra/docker-compose.yml：运行Ollama等服务的Docker配置。modbot.db：运行时创建的SQLite数据库文件，用于存储审核历史记录。
安装和设置
1.先决条件
- Python 3.11+
uv（可选，建议用于快速环境管理）- Docker（用于通过Ollama运行本地LLM）
获取Discord Bot令牌
要运行机器人，您需要一个Discord机器人令牌。遵循官方Discord指南：\ Discord开发者门户-入门
- 转到 Discord开发者门户.
- 点击“新建应用程序”并为其命名。
- 在“Bot”下，单击“添加Bot”并确认。
- 在“机器人”设置下，单击“重置令牌”并复制您的机器人令牌。
- 将令牌添加到您的
.env归档DISCORD_TOKEN.
所需的Bot权限
创建机器人时，请确保 打开 以下权限：-
- 消息内容意图
- 服务器成员意图
获取透视API密钥
如果你想使用透视API进行毒性评分，你需要从谷歌获得API密钥。请按照此处的官方codelab指南进行操作：\ 设置透视API
一旦你有了钥匙，就把它添加到你的 .env 归档 PERSPECTIVE_API_KEY.
2.安装依赖项
您可以使用提供的安装项目依赖项 uv 助手（推荐）或与 pip.
Windows（PowerShell）
# create & activate virtualenv
python -m venv .venv
# PowerShell activation
.\.venv\Scripts\Activate.ps1
# upgrade packaging tools
pip install --upgrade pip setuptools wheel
# Option A (recommended if you have 'uv'):
uv sync --extra dev
# Option B (pip): install editable package + extras (dev + llm)
pip install -e ".[dev,llm]"POSIX（macOS/Linux）
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
# Option A (recommended if you have 'uv'):
uv sync --extra dev
# Option B (pip): install editable package + extras (dev + llm)
pip install -e ".[dev,llm]"笔记：
uv sync --extra dev安装pyproject.toml中定义的base+dev-extras。- 如果您只喜欢核心运行时deps，请使用
pip install -e . - 这
llmextra安装可选的LLM提供程序，只有在使用云提供程序或高级本地模型时才需要。
3.配置环境
复制 .env.example 到 .env 并填写所需的值（Discord令牌、提供商API密钥、MCP_SERVER_URL等）
copy .env.example .env # Windows PowerShell
cp .env.example .env # POSIX4.启动服务
- 如果使用Ollama（本地模型），请使用Docker启动：
docker-compose -f infra/docker-compose.yml up ollama- 启动MCP服务器：
# preferred (run module)
uv run python -m mcp_server.main
# or
uv run python src/mcp_server/main.py- 启动机器人
uv run -m modbot选项2：使用云LLM（无Docker）
如果你没有Docker或不想在本地运行LLM，这种方法会更简单。您将需要两个独立的终端。
1.配置您的 .env 云提供商（例如Gemini）的文件： 确保您已设置 MODEL_PROVIDER 以及相应的 API_KEY 在你的 .env 文件。
MODEL_PROVIDER=gemini
MODEL_NAME=gemini-1.5-flash
GEMINI_API_KEY=YOUR_GEMINI_API_KEY2.终端1：启动MCP工具服务器 此服务器将审核操作作为LLM的工具公开。
uv run python src/mcp_server/main.py3.终端2：启动Discord Bot 最后，启动机器人本身。
uv run -m modbot您的机器人现在应该在Discord中联机并完全运行，使用配置的云LLM进行决策。
策略配置(policies/moderation.yaml)
此文件用于定义机器人的所有行为。机器人在启动时加载此文件。它有两个主要部分： rules 和 escalation.
规则解释
- 每个规则都有一个名称（例如。，
"Very High Toxicity"). - 这
condition是一个必须为真才能触发规则的表达式。您可以使用toxicity,contains_regex()以及其他助手。 actions是要执行的操作列表。操作可以有参数，如警告的原因。
升级解释
window_minutes：定义跟踪重复犯罪的时间范围（以分钟为单位）。thresholds：定义当用户累积一定数量的操作时会发生什么。
- warns：跟踪 warn_user 行动。 - timeouts：跟踪 timeout_member 行动。 - 语法是 count -> action(args)。您可以用分号链接多个阈值。
健康终点
MCP服务器公开了一个简单的健康端点，您可以使用它来验证服务和LLM连接：
- 网址：http://localhost:8000/health
- 返回JSON:status、llm_provider、llm_initialized（bool）、tools_registered、uptime_seconds
示例（卷曲）：
curl http://localhost:8000/health
# {"status":"ok","llm_provider":"gemini","llm_initialized":true,"tools_registered":4,"uptime_seconds":42}