Format Detector 格式识别 Skill

功能概述

本 skill 用于在采集入口扫描文件资源，按扩展名和轻量内容特征识别资源基础类型，并输出推荐后续处理路由。

触发条件

当用户请求以下任务时，应使用此 skill：

• 识别文件格式
• 判断资源是文本、表格、文档、图像、HTML 还是数据文件
• 为采集入口资源分配后续处理路由
• 对混合目录做格式预识别
• 降低异构资源进入流水线后的适配冲突

不适用于正文采集、图像元信息提取、表格读取、文档解析、格式转换或实际执行后续处理；这些任务需要使用对应的采集、解析或转换 skill。

核心参数说明

必需参数

参数	说明
--input	输入文件或目录路径
--output	输出文件路径（格式识别结果）

可选参数

参数	说明	默认值
--recursive	是否递归扫描子目录	False
--output_format	输出格式，支持 jsonl、json、csv、auto	jsonl

输入文件格式

输入可以是单个文件，也可以是包含多类文件的目录。目录模式会扫描所有普通文件并输出格式识别记录。

input_dir/
  notes.txt
  station_table.csv
  report.pdf
  image.png
  payload.json
  nested/raw.bin

使用方法

递归识别目录并输出 JSONL

python scripts/run_format_detector.py \
  --input ./input_dir \
  --output ./format_detector_output.jsonl \
  --recursive true \
  --output_format jsonl

识别单个文件并输出 JSON

python scripts/run_format_detector.py \
  --input ./notes.txt \
  --output ./format_detector_output.json \
  --output_format json

处理示例

输入文件	识别类型	推荐路由
notes.txt	text	text_collector
station_table.csv	table	table_collector
report.pdf	document	pdf_collector
image.png	image	image_collector
payload.json	data	content_parser
page.html	html	content_parser
raw.bin	unknown	manual_review

输出示例

{"file_path": "notes.txt", "filename": "notes.txt", "extension": ".txt", "category": "text", "content_format": "plain_text", "recommended_route": "text_collector", "file_size": 128, "detected_at": "2026-06-12 14:00:00"}

环境要求

使用仓库内 Python 环境运行；Windows bash 下建议加 PYTHONIOENCODING=utf-8 避免中文控制台编码问题。脚本仅使用 Python 标准库。

注意事项

1. 本 skill 只做格式识别和推荐路由，不读取完整正文或执行后续处理。
2. --recursive false 时只扫描输入目录第一层文件。
3. file_path 输出为相对输入根目录路径，不能包含本地绝对路径。
4. 未识别扩展名会归类为 unknown，推荐路由为 manual_review。