IAdetector

IAdetector

检测文本是否由 AI 生成，100% 本地运行：不会调用任何付费外部 API（OpenAI、GPTZero、Originality.ai 等）。它将纯统计/文体学信号与两个在本地运行的小型 ONNX 模型（RoBERTa 分类器和 DistilGPT-2 困惑度模型）相结合，并通过基于真实数据（HC3）的逻辑回归进行校准。

同一引擎可通过两种方式使用：

• MCP 服务（IAdetector.Mcp）——为 Agent（Claude Code、VS Code Copilot 等）提供分析文本的工具。
• CLI（IAdetector.Cli，命令 iadetector）——可直接在终端或脚本中使用。

你可以向它提问什么

问题	对应的工具
“这段文本是 AI 写的吗？”	detect_text
“分析这个文件”	detect_file
“检查这个文件夹里的 500 份文档”	batch_detect_directory
“为什么会得出这个判定？”	explain_detection

所有操作都在你的设备上完成。没有外部 API，也不需要密钥，分析的文本绝不会离开你的设备。这与 GPTZero、Originality.ai 或任何云端检测器有本质区别：你可以分析未发表的手稿或机密文档，而不必将其交给任何人。

重要

**结果是证据，绝非定论。**AI 生成文本检测具有概率性，确实存在误报，而且对使用非母语写作的人以及公式化程度很高的技术文风影响尤为严重。

不要仅凭这个工具就指控学生或员工。它的用途是帮助你优先筛选出需要由人审慎复核的内容，而不是替你做决定。

架构

务实的 Clean Architecture，共 4 个生产项目：

src/
  IAdetector.Core/            Dominio + casos de uso. Cero dependencias externas.
  IAdetector.Infrastructure/  Señales (estadísticas + ONNX), ensemble calibrado, descarga de modelos.
  IAdetector.Mcp/             Servidor MCP (stdio), vía ModelContextProtocol C# SDK.
  IAdetector.Cli/             CLI (comando `iadetector`), vía System.CommandLine.
tools/
  IAdetector.Calibration/     Herramienta de desarrollo: extrae features para recalibrar el ensemble.
tests/                        xUnit: Core, Infrastructure, e integración end-to-end (corpus HC3 held-out).
scripts/calibration/          Dataset de calibración + script Python (scikit-learn) que ajusta los pesos.

CalibratedEnsembleScorer 将七种信号结合起来：突发性、type-token 比率、词汇熵、压缩比、n 元语法重复、ONNX 分类器（RoBERTa）和困惑度（DistilGPT-2）。校准系数请参见 EnsembleWeights.json。

要求

• .NET 10 SDK
• 要在 Windows 上发布 Native AOT 二进制文件：需要安装带有 C++ 工作负载的 Visual Studio Build Tools（必须能访问 vswhere.exe；通常位于 C:\Program Files (x86)\Microsoft Visual Studio\Installer\）。

安装

CLI

选项 A——通过 NuGet 使用 dotnet tool（只需一条命令，但需要 .NET runtime）：

dotnet tool install --global IAdetector.Cli
iadetector detect ejemplo.txt

（若要从源代码安装而不是通过 NuGet 安装：运行 dotnet pack src/IAdetector.Cli -c Release -o ./nupkg，然后运行 dotnet tool install --global --add-source ./nupkg IAdetector.Cli。）

选项 B——独立原生二进制文件（无需安装 .NET）：

dotnet publish src/IAdetector.Cli -c Release -r win-x64 -p:PublishAot=true -o ./publish/cli
./publish/cli/IAdetector.Cli.exe detect ejemplo.txt

根据平台，将 win-x64 替换为 linux-x64。

MCP 服务

选项 A——通过 dnx 使用 NuGet 包（无需克隆仓库或事先安装任何内容）：

配置 MCP 宿主（例如 .vscode/mcp.json），dnx 会从 NuGet 下载并运行服务：

{
  "servers": {
    "IAdetector": {
      "type": "stdio",
      "command": "dnx",
      "args": ["IAdetector.Mcp", "--version", "1.0.1", "--yes"]
    }
  }
}

选项 B——直接指定独立原生二进制文件：

dotnet publish src/IAdetector.Mcp -c Release -r win-x64 -p:PublishAot=true -o ./publish/mcp

{
  "servers": {
    "IAdetector": {
      "type": "stdio",
      "command": "C:/ruta/a/publish/mcp/IAdetector.Mcp.exe"
    }
  }
}

ONNX 模型

模型（RoBERTa 分类器约 126MB，DistilGPT-2 约 237MB）不会在检测过程中自动下载——必须手动下载一次：

iadetector models download --model roberta-openai-detector
iadetector models download --model distilgpt2-perplexity
iadetector models list

模型会缓存在 %LOCALAPPDATA%\IAdetector\models（Windows）中，并通过 SHA-256 校验完整性。没有这两个模型时，相应的两种信号将保持中性（权重降低），其余集成模型仍会正常运行。

CLI 用法

iadetector detect archivo.txt [--json] [--verbose] [--no-color]
iadetector detect --text "texto a analizar" [--verbose]
cat archivo.txt | iadetector detect               # también lee de stdin si no hay archivo ni --text
iadetector batch <directorio> [--pattern *.txt] [--recursive] [--max-files 1000] [--output resultados.csv]
iadetector models download --model <id> [--force]
iadetector models list
iadetector models verify [--model <id>]

Tools MCP

• detect_text(text, verbose) — 内联文本（最多 20 000 个字符）。
• detect_file(path, verbose) — 本地文件（最多 5MB；会自动分段处理长文本，文本特别大时会抽样）。
• batch_detect_directory(path, pattern, recursive, maxFiles) — 一次处理多个文件。
• explain_detection(text) — 提供处方性解释：逐项说明信号是否已测量、对结果的影响程度（对 logit 的贡献）、在人类参考文本中的典型范围，以及超出范围时应如何调整，并按优先级排列操作建议。
• compare_versions(originalText, rewrittenText) — 将改写文本与原文进行比较（无状态）：比较概率及各项信号的变化，并提供含义保护机制（如果改写文本失去了原文中的内容词汇，即使概率降低，结果也会是 no_concluyente）。参见 docs/AGENT_LOOP.md。

供使用这些工具的 Agent 参考：完整约定（字段、语义、循环协议、按语言划分的可靠性和限制）见 docs/AGENT_GUIDE.md。

Agent 技能（Claude Code）

skills/（标准的扁平布局 skills/<nombre>/SKILL.md，与 Vercel 或 Supabase 等项目分发自有技能时使用的布局相同）包含两个可通过 npx skills 安装的技能：

• iadetector-setup — 安装、发布和配置 CLI/MCP，下载 ONNX 模型，并在 .mcp.json 中注册服务。
• iadetector-usage — 解读结果（判定、概率、置信度），并在传达时避免过度断言。

注意：这些技能位于 skills/（由 git 跟踪），而非 .claude/skills/（会被忽略——这是按会话／机器保存的本地状态）。每位用户都可以运行下方的安装命令，将所需技能放入自己的本地 .claude/skills/；不会提交该副本。

此仓库托管到 GitHub 后，可在其他项目中安装：

npx skills add <usuario>/IAdetector-mcp --skill iadetector-setup --skill iadetector-usage

也可以直接从本地仓库副本安装（无需 GitHub）：

npx skills add /ruta/a/IAdetector-mcp --skill '*'

开发

dotnet build
dotnet test tests/IAdetector.Core.Tests
dotnet test tests/IAdetector.Infrastructure.Tests   # requiere modelos descargados para las señales ONNX
dotnet test tests/IAdetector.Integration.Tests       # requiere modelos + scripts/calibration/data/open_qa.jsonl

重新校准 ensemble

dotnet run --project tools/IAdetector.Calibration -- <dataset.jsonl formato HC3> scripts/calibration/data/features.csv
python scripts/calibration/fit_logistic_regression.py scripts/calibration/data/features.csv src/IAdetector.Infrastructure/Ensemble/EnsembleWeights.json

已知限制

• 纯统计信号（阶段 1）的阈值是初始启发式值；只有完整的 ensemble 经过了正式校准。
• RoBERTa 分类器使用 GPT-2（2019 年）的输出进行训练；它对较新的 LLM 风格的泛化能力并不完美，因此 ensemble 还包含了互补信号。
• perplexity 信号是 Fast-DetectGPT/Binoculars 思路的简化版本（仅使用一个模型），并非两个模型之间的完整比率。
• 使用 HC3（英语）的一个子集进行校准；未针对西班牙语或其他语言进行专门验证。

面向 Agent 的 CLI

作者身份筛查完全在本机进行——不会将任何文本发送到其他地方。

此 CLI 遵循 ARSENAL-SPEC.md，这是此工作区中所有研究工具共同遵循的约定：能驱动其中一个工具的 Agent，也能驱动所有工具。

无需阅读此文件即可了解工具

iadetector describe --json          # every command, argument, row field and example
iadetector describe <command> --json

清单由解析器本身生成，因此不会过时。

输出

-f, --format 接受 table、json、jsonl、csv、md；-o FILE 将内容写入文件；-q 禁止输出说明。 数据输出到 stdout，说明和进度输出到 stderr——通过管道传给 jq 时始终会得到可解析的 JSON。

--format json 会返回标准封装：

{
  "ok": true,
  "command": "detect",
  "source": "iadetector",
  "fetched_at": "2026-08-21T14:03:11Z",
  "cached": false,
  "count": 10,
  "meta": {},
  "data": {},
  "rows": []
}

count 始终等于 len(rows)。结果为空时退出码为 0，不视为错误。失败时会返回包含 error.code、error.message 和可执行的 error.hint 的错误封装；在机器可读格式下，该封装会输出到 stdout，便于管道检查。

退出码

代码	含义
0	成功，包括结果为空。
1	分析失败或返回了意外结果（模型损坏、内部错误）。
2	使用错误：未知标志、格式无效、参数不兼容。
3	找不到指定的文件、目录或模型。
4	不适用：检测完全在本地进行，不需要 API 密钥或凭据。
5	不适用：没有带配额的外部服务。
6	网络故障或超时——仅在 models download 时可能出现。

缓存

结果会缓存在磁盘上，并在多次调用之间保留，因此重复查询会即时返回。--refresh 会重新获取并写入结果；--no-cache 会完全跳过缓存；结果封装中会报告 cached。

iadetector cache stats -f json
iadetector cache clear

使用示例

iadetector detect informe.txt -f json
iadetector detect --text "un párrafo cualquiera" --verbose -f json
cat ensayo.md | iadetector detect -f json
iadetector batch corpus/ -f csv -o corpus.csv
iadetector batch corpus/ --verbose -f jsonl --max 500

也可以通过工作区级入口调用：arsenal run iadetector <command> ...，并运行 arsenal doctor iadetector --live，检查此 CLI 是否仍遵守约定。

故障排除

模型尚未下载 ONNX 模型不会随附提供。只需下载一次： iadetector models download。模型占用数百 MB，并会保存在应用缓存中；运行 iadetector models list 查看。

首次分析耗时远超后续分析 这是 ONNX 模型首次加载到内存所需的时间。之后的分析会很快，已分析过的文本则会立即从结果缓存中返回。

重新分析语料库时耗时仍然相同 检查是否传入了 --no-cache 或 --refresh。运行 iadetector cache stats 可查看已保存的结果数量。缓存键包含模型版本：如果更新模型，之前的缓存会按预期失效。

很短的文本置信度较低 词数较少时，统计信号不足以支撑判断。少于一个段落的文本无法提供有用结果——系统也会如此报告。

文档

文档	内容
CHANGELOG.md	各版本的更改内容
CONTRIBUTING.md	开发环境设置、CLI 约定以及运行测试的方法
SECURITY.md	此服务会发送哪些内容以及发送到哪里；如何报告漏洞
server.json	官方 MCP 注册表的注册表元数据
../ARSENAL-SPEC.md	此处每个研究服务共用的 CLI 约定

许可证

MIT——参见 LICENSE。