#mbt-filetype

#特性

• 基于结构的识别，而不是字符串搜索：ZIP 走 EOCD → 中央目录 → 条目名；OLE2 走 FAT → 目录扇区 → 流名；ISO-BMFF 走 box 树 → mdia/hdlr；RIFF 遍历 chunk；EBML 解 vint 取 DocType；tar 校验 header checksum；PE 校验 COFF/Optional Header
• 证据链 + 派生评分：每条证据带种类、偏移、权重；置信度由总分推导，不是人工标注的标签
• 可扩展规则：Registry + Rule + Matcher，调用方可以注册自己的签名与检测器，与内置规则走同一套流程
• 不猜原则：结构校验不通过就降级或返回 unknown，歧义时返回候选列表
• 确定性：纯函数识别，不访问网络、不依赖时区与 locale
• 边界安全：所有字节访问都先检查长度，任意输入都不会越界；附带固定种子 fuzz
• CI 友好：--expect 断言类型，--scan 报告扩展名与内容不符的文件

#安装

moon add Mr-Houjie/mbt-filetype

#库 API

let detection = @Mr-Houjie/mbt-filetype.detect(bytes)
match detection.file_type {
  Some(file_type) => {
    println(file_type.id)       // "docx"
    println(file_type.mime)     // "application/vnd.openxmlformats-officedocument..."
    println(detection.score)    // 100
    for item in detection.evidence {
      println("\{item.kind} +\{item.weight}: \{item.label}")
    }
  }
  None => println("unknown")
}

#置信度如何得出

• 总分 ≥ 90 → certain，≥ 20 → probable，否则 unknown
• 所以「BM 开头的文本」只有 20 分且被 DIB header 校验拦下，会回落到 text； 「结构完整的 docx」是 90 + 40 分，判定为 certain

examples/sample.png
  type:       png
  mime:       image/png
  extension:  .png
  category:   image
  confidence: certain (90/100)
  evidence:   PNG signature
  offset:     0
  bytes:      8
    [1] magic +90 @0: PNG signature

#扩展：自定义规则与检测器

let registry = @Mr-Houjie/mbt-filetype.Registry::new()

// 声明式规则：支持固定偏移、尾部偏移、位掩码、ASCII、与/或组合
registry.add_rule(
  @Mr-Houjie/mbt-filetype.Rule::new(
    "myfmt", "application/x-myfmt", "myfmt", @Mr-Houjie/mbt-filetype.Other,
    "MYFMT v1 魔数", 90,
    @Mr-Houjie/mbt-filetype.Matcher::all([
      @Mr-Houjie/mbt-filetype.Matcher::magic_at(0, b"MYFMT"),
      @Mr-Houjie/mbt-filetype.Matcher::masked_at(5, b"\x01\x00", b"\xff\x00"),
    ]),
  ),
)

// 命令式检测器：规则与内置签名都没命中时兜底
registry.add_detector(fn(data) { ... })

let detection = @Mr-Houjie/mbt-filetype.detect_with(registry, bytes)

#CLI

# 识别单个文件
moon run cmd/main -- examples/sample.png

# 以 JSON 输出
moon run cmd/main -- --json examples/sample.json

# 显示证据链、偏移与评分
moon run cmd/main -- --explain examples/sample.png

# 断言类型：不匹配时退出码为 1
moon run cmd/main -- --expect image/png examples/sample.png

# 递归扫描目录，报告扩展名与内容不符的文件
moon run cmd/main -- --scan examples

# 列出全部已知类型
moon run cmd/main -- --list-types

#支持等级与判定终点

#支持的结构判定

#一致性语料与测试

• 完整 ZIP（本地头 + 中央目录 + EOCD），含 64 KiB 之后的中央目录用例
• 完整 OLE2（header + FAT + 目录扇区 + 流名），含 doc / xls / ppt 与「前缀相似流名」对抗样本
• 完整 RIFF/IFF chunk、ISO-BMFF box 树、EBML vint、Ogg 页、tar header、PE 头
• 对抗样本：真 ZIP 里塞 word/document.xml 文本、mimetype 不在首位、 缺少 [Content_Types].xml、BMW 320i … 文本、MZ … 文本

moon test          # 标准测试（部分 Windows 环境受嵌套进程限制）
moon run cmd/verify  # 独立自检入口，与 moon test 等价

#跨库一致性对拍

# 准备一个真实文件语料目录，然后：
python tools/crosscheck.py corpus/

#已知边界（都有明确的降级路径）

#许可证