file-type-detector

name	file-type-detector
description	使用 Google Magika 做文件类型检测 — AI 驱动的 content-type 识别工具， 支持深度学习模型判断文件类型（准确率高于传统 magic bytes）。 适用场景：文件乱码检测、扩展名与内容不符排查、批量文件分类、格式损坏初筛。 当用户提到"检测文件类型"、"判断文件编码"、"文件内容识别"、"文件扩展名不对"、 "文件乱码"、"magika"、"文件损坏"、"文件被篡改"时使用此 skill。
version	1.1.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["file","detection","magika","content-type","mime","encoding","corruption"],"category":"productivity"}}

File Type Detector (Google Magika)

核心能力

Google Magika 使用深度学习模型识别文件类型，相比传统 file 命令的 magic bytes：

• ✅ 更擅长识别伪装文件（扩展名与内容不符）
• ✅ 识别无扩展名文件
• ✅ 部分损坏/截断文件会降低置信度（可作为损坏信号）
• ⚠️ 不做格式/语法验证 — 语法错的 JSON、HTML、JS 照常识别为原类型

命令行用法

基本检测

magika path/to/file.txt

递归检测目录

magika -r path/to/directory/

输出 MIME 类型（而非描述）

magika -i file.txt          # 输出: text/plain

输出简短标签

magika -l file.txt          # 输出: txt

显示置信度分数

magika -s file.txt          # 包含 score 字段

JSON 输出（程序化处理）

magika --json path/to/file
magika -r --jsonl path/to/dir/   # 每行一个文件

自定义输出格式

magika --format "{path}: {label}" path/to/file

常用标签对照

label	描述	MIME
txt	普通文本	text/plain
html	HTML 文档	text/html
json	JSON 文档	application/json
python	Python 源码	text/x-python
javascript	JavaScript	application/javascript
jpeg	JPEG 图片	image/jpeg
png	PNG 图片	image/png
pdf	PDF 文档	application/pdf
zip	ZIP 压缩包	application/zip
pythonbytecode	Python 编译字节码	application/x-bytecode.python
unknown	无法识别	—
empty	空文件	—

典型使用场景

1. 文件乱码排查

文件打开是乱码，可能是编码问题，也可能是文件类型本身就不是文本：

magika mysterious_file.bin

如果返回 jpeg、zip、pdf 等 binary 类型，说明内容根本不是文本，无需查编码。

2. 伪装文件检测（扩展名 vs 内容不符）

扩展名是 .txt 但可能是伪装/被篡改的：

magika -s suspicious_file.txt

关注置信度分数和 unknown 结果：

• unknown [Low-confidence, score=0.35] → 文件异常，可能是伪装或损坏
• .pdf 文件被识别为 txt → 扩展名骗人，实际是文本

3. 格式损坏初筛

Magika 对损坏/截断文件的特征：返回 unknown 或低置信度

# 批量找出所有低置信度（可能损坏）的文件
magika -r --jsonl path/to/dir/ | jq 'select(.result.value.score < 0.7)'

损坏的典型信号：

情况	Magika 表现
文件被截断	unknown 或低分
二进制文件注入文本	unknown (低分)
空文件	empty
极小的畸形文件	unknown
伪造扩展名（文本伪装成图片等）	unknown (低分)

注意：以下情况 Magika 不会检测出损坏（语法错误不影响内容识别）：

• JSON/HTML/JS 语法错误 → 仍识别为原类型（语法验证要找专用工具）
• 正常文件 → 高分识别

4. 批量文件类型审计

# 递归检测目录，输出所有文件的真实类型
magika -r --jsonl ~/Downloads/ > file_types.jsonl

# 找出所有被误标为 .txt 的非文本文件
magika -r --jsonl ~/Downloads/ | jq 'select(.result.value.output.label != "txt")'

# 统计目录下各类型文件数量
magika -r --jsonl ~/projects/ | jq -r '.result.value.output.label' | sort | uniq -c | sort -rn

5. 验证文件扩展名是否正确

# 检查扩展名是否和内容匹配
magika -l file.pdf    # 应该是 pdf，如果不是说明文件损坏或伪装的

损坏检测总结

损坏检测总结

损坏类型	Magika 能检测？	信号
截断文件（PDF/ZIP/PNG）	✅ 较好	unknown 或低分
扩展名伪装（txt实际是jpg）	✅ 好	unknown (低分)
文本文件损坏乱码	✅ 好	返回 binary 类型
空文件	✅ 好	empty
JSON/JS/HTML/Python 语法错误	❌ 不能	不受影响，照常识别
极小畸形文件（几字节）	⚠️ 较差	unknown，但很多文件命令也认不出
ZIP/PDF 结构不完整	⚠️ 不稳定	偶尔误判为 npz 等

实测重要发现（需注意）

1. Magika vs file 命令：两者互补，不能互相替代

   • Magika 更擅长识别伪装文件（扩展名骗人）和无扩展名文件
   • file 命令对标准格式（标准JPEG、标准PDF、标准ZIP）识别更稳定
   • 两者联合使用效果最好

2. 极小文件是盲区：几字节的最小有效文件（如最小PDF）可能 unknown，file 也可能认不出

3. 语法错误 ≠ 内容类型错误：JSON 语法错误，Magika 仍识别为 json（只是置信度略低）。内容类型检测和语法正确性是两回事。

4. file 命令对标准格式更可靠：标准 JPEG magic bytes (\xff\xd8) 永远被 file 正确识别，而 Magika 可能因为某些 JPEG 变种给低分

依赖

• magika CLI 已安装在 /opt/anaconda3/bin/magika
• 无需 API key，纯本地运行