Table Collector 表格采集 Skill

功能概述

本 skill 用于读取单个结构化表格文件或目录中的表格文件，将每一行采集为统一结构化记录，并输出为 JSONL、JSON 或 CSV。

触发条件

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

• 表格文件采集
• 读取科研数据表
• 汇总 CSV、TSV、Excel 表格内容
• 将本地表格文件转为结构化记录
• 为后续清洗、校验、入库准备统一表格输入

不适用于 PDF 表格抽取、图片表格识别、表格清洗、空行删除、字段去空格、格式结构校验、字段过滤或格式转换；这些任务需要使用对应的文档、图像、清洗、校验、筛选或转换 skill。

核心参数说明

必需参数

参数	说明
--input	输入表格文件或目录路径
--output	输出文件路径

可选参数

参数	说明	默认值
--encoding	CSV/TSV 文件编码，auto 会按常见编码尝试读取	auto
--recursive	是否递归采集子目录中的表格文件	False
--add_metadata	是否为每行记录添加 _meta 来源文件元信息	True
--output_format	输出格式，支持 jsonl、json、csv、auto	jsonl

输入文件格式

输入可以是单个受支持表格文件，也可以是包含受支持表格文件的目录。目录模式只采集 .csv、.tsv、.xlsx、.xls，其它扩展名会跳过。

input_dir/
  station_observations.csv
  station_observations.tsv
  nested/station_observations.xlsx
  skip.txt

使用方法

递归采集目录并输出 JSONL

python scripts/run_table_collector.py \
  --input ./input_dir \
  --output ./table_collector_output.jsonl \
  --encoding auto \
  --recursive true \
  --add_metadata true \
  --output_format jsonl

采集单个表格文件并输出 JSON

python scripts/run_table_collector.py \
  --input ./station_observations.csv \
  --output ./table_collector_output.json \
  --output_format json

处理示例

输入文件	参数效果	预期结果
station_observations.csv	支持的 .csv 文件	每个数据行采集为一条记录
station_observations.tsv	支持的 .tsv 文件	每个数据行采集为一条记录
nested/station_observations.xlsx	--recursive true	每个数据行采集为一条记录
skip.txt	非支持扩展名	不进入采集列表

输出示例

{"sample_id": "QYZ-001", "domain": "forest", "value": "12.4", "_meta": {"source_file": "station_observations.csv", "filename": "station_observations.csv", "row_count": 12, "collected_at": "2026-06-12 10:00:00"}}

环境要求

使用仓库内 Python 环境运行；Windows bash 下建议加 PYTHONIOENCODING=utf-8 避免中文控制台编码问题。Excel 读取需要运行环境已安装 openpyxl。

注意事项

1. --recursive false 时只扫描输入目录第一层文件。
2. --add_metadata false 时输出记录只包含原始表格字段。
3. 输出文件扩展名不会自动决定格式，除非 --output_format auto。