核心功能: 本技能提供化工作流场景等能力。
核心功能: 本技能提供中文交互、、报表生成、统计洞察、数据可视化时使用等能力。
核心功能: 本技能提供表数组与嵌套表)等能力。
数据格式转换器
快速开始
- 确认运行环境满足依赖说明中的要求
- 在AI Agent对话中调用本技能,提供必要的输入参数
- 检查输出结果,根据需要进行后续处理
详细的输入输出格式请参考下方章节说明。
输入参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input | string | 是 | 数据格式转换器处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |
专业版增强能力
| 能力 | 免费版 | 付费版 |
|---|---|---|
| 基础功能 | 支持 | 支持 |
| 数据格式转换器支持批量处理 | 不支持 | 支持 |
| 数据格式转换器与嵌套结构处理 | 不支持 | 支持 |
| 大数据集流式处理 | 不支持 | 支持 |
| 多数据源关联查询 | 不支持 | 支持 |
| 可视化图表自动生成 | 不支持 | 支持 |
依赖与配置
运行环境
- Agent平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
- 操作系统: Windows / macOS / Linux
依赖项
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---|---|---|---|
| LLM API | API | 必需 | 由Agent内置LLM提供 |
API Key 配置
需要配置对应API Key,详见上文环境配置章节
可用性分类
- 分类: MD+EXEC()
API Key配置方式:
export API_KEY="${API_KEY:?请设置环境变量}"
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.
主要能力
CSV与JSON互转
CSV转JSON:使用 csv.DictReader() 逐行读取为字典,通过 json.dumps(ensure_ascii=False, indent=2) 输出UTF-8中文JSON.
import csv, json
# ...
with open('data.csv', 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
rows = list(reader)
# ...
json_str = json.dumps(rows, ensure_ascii=False, indent=2)
JSON转CSV:使用 csv.DictWriter() 写入,需指定 fieldnames。嵌套JSON需先扁平化(如 {"a": {"b": 1}} → {"a.b": 1}).
import csv, json
# ...
with open('data.json', 'r', encoding='utf-8') as f:
data = json.load(f)
# ...
fieldnames = list(data[0].keys())
with open('output.csv', 'w', encoding='utf-8-sig', newline='') as f:
writer = csv.DictWriter(f, fieldnames=fieldnames)
writer.writeheader()
writer.writerows(data)
JSON与YAML互转
JSON转YAML:使用 yaml.safe_dump() 输出,default_flow_style=False 使用块样式(更易读),allow_unicode=True 保留中文.
import yaml, json
# ...
with open('data.json', 'r', encoding='utf-8') as f:
data = json.load(f)
# ...
yaml_str = yaml.safe_dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False)
YAML转JSON:使用 yaml.safe_load() 解析(安全加载,不执行任意Python对象).
import yaml, json
# ...
with open('data.yaml', 'r', encoding='utf-8') as f:
data = yaml.safe_load(f)
# ...
json_str = json.dumps(data, ensure_ascii=False, indent=2)
XML与JSON互转
XML转JSON:使用 xmltodict.parse() 将XML解析为有序字典,属性以 @ 前缀标记.
import xmltodict, json
# ...
with open('data.xml', 'r', encoding='utf-8') as f:
xml_str = f.read()
# ...
data = xmltodict.parse(xml_str)
json_str = json.dumps(data, ensure_ascii=False, indent=2)
JSON转XML:使用 xmltodict.unparse() 将字典转回XML,pretty=True 格式化输出.
import xmltodict, json
# ...
with open('data.json', 'r', encoding='utf-8') as f:
data = json.load(f)
# ...
xml_str = xmltodict.unparse(data, pretty=True)
- 异常时参考错误处理章节进行恢复
- 关键参数:
xml与json互转选项
TOML与JSON互转
TOML转JSON:使用 toml.load() 解析TOML文件,支持表数组和嵌套表.
import toml, json
# ...
with open('data.toml', 'r', encoding='utf-8') as f:
data = toml.load(f)
# ...
json_str = json.dumps(data, ensure_ascii=False, indent=2)
JSON转TOML:使用 toml.dumps() 输出TOML格式字符串.
import toml, json
# ...
with open('data.json', 'r', encoding='utf-8') as f:
data = json.load(f)
# ...
toml_str = toml.dumps(data)
- 异常时参考错误处理章节进行恢复
- 关键参数:
toml与json互转选项
批量转换
支持目录级批量处理,遍历源格式文件并批量转换为目标格式:
from pathlib import Path
# ...
def batch_convert(input_dir, output_dir, from_fmt, to_fmt):
input_path = Path(input_dir)
output_path = Path(output_dir)
output_path.mkdir(parents=True, exist_ok=True)
# ...
for file in input_path.glob(f'*.{from_fmt}'):
# 读取源文件 -> 转换 -> 写入目标文件
output_file = output_path / f'{file.stem}.{to_fmt}'
# 转换逻辑...
即刻上手
- 确认运行环境满足依赖说明中的要求
- 在AI Agent对话中调用本技能,提供必要的输入参数
- 检查输出结果,根据需要进行后续处理
详细的输入输出格式请参考下方章节说明。
支持格式矩阵
| 输入\输出 | CSV | JSON | YAML | XML | TOML |
|---|---|---|---|---|---|
| CSV | - | 支持 | 间接 | 间接 | 间接 |
| JSON | 支持 | - | 支持 | 支持 | 支持 |
| YAML | 间接 | 支持 | - | 间接 | 间接 |
| XML | 间接 | 支持 | 间接 | - | 间接 |
| TOML | 间接 | 支持 | 间接 | 间接 | - |
"间接"表示先转为JSON再转为目标格式。JSON是所有转换的中心枢纽.
使用指南
- 识别源格式:根据文件扩展名(
.csv/.json/.yaml/.xml/.toml)确定输入格式 - 选择目标格式:确认用户需要转换为何种格式
- 加载源数据:使用对应解析器读取文件(注意
encoding='utf-8') - 执行转换:通过JSON作为中间格式,或直接调用对应转换函数
- 输出结果:写入目标文件,注意
ensure_ascii=False保留中文,indent=2格式化
详细示例
示例1:CSV转JSON
输入 (CSV):
name,age,city
张三,30,北京
李四,25,上海
# ...
输出 (JSON):
[
{"name": "张三", "age": "30", "city": "北京"},
{"name": "李四", "age": "25", "city": "上海"}
]
示例2:JSON转YAML
输入 (JSON):
{"database": {"host": "localhost", "port": 5432}, "debug": true}
# ...
输出 (YAML):
database:
host: localhost
port: 5432
debug: true
示例3:XML转JSON
输入 (XML):
<user id="101"><name>张三</name><age>30</age></user>
# ...
输出 (JSON):
{"user": {"@id": "101", "name": "张三", "age": "30"}}
示例4:TOML转JSON
输入 (TOML):
[server]
host = "127.0.0.1"
port = 8080
# ...
[[users]]
name = "admin"
# ...
输出 (JSON):
{"server": {"host": "127.0.0.1", "port": 8080}, "users": [{"name": "admin"}]}
示例5:批量CSV转JSON
输入: ./csv_files/ 目录下 3 个CSV文件
处理: 遍历 *.csv,逐个用 csv.DictReader 读取,json.dumps 输出
输出: ./json_files/ 目录下 3 个对应JSON文件,文件名保持一致
异常处理指南
| 错误场景 | 原因 | 处理方式 |
|---|---|---|
json.JSONDecodeError | JSON格式错误(如尾随逗号、单引号) | 使用 json.loads() 严格解析,报告出错行号与列位置 |
| CSV含嵌套数据无法扁平化 | CSV单元格内含JSON字符串 | 先用 json.loads() 解析单元格内容,再展开为多列 |
| XML属性与子元素同名冲突 | xmltodict 属性加 @ 前缀,但子元素同名 | 自定义 attr_prefix 参数,如 attr_prefix='_' |
| YAML含特殊字符未加引号 | 值含 : # & 等保留字符 | 输出时用 default_style='"' 强制引号包裹 |
| TOML不支持嵌套数组中的数组 | TOML规范限制:表数组 [[x]] 内不能有数组值 | 将嵌套数组转为JSON字符串存储,或改用JSON格式 |
UnicodeDecodeError 编码错误 | 文件非UTF-8编码(如GBK、Latin-1) | 先用 chardet.detect() 检测编码,再以正确编码读取 |
| JSON转CSV时值含逗号或换行 | CSV字段需引号包裹 | csv.DictWriter 自动处理引号转义,确保 newline='' |
| YAML锚点与别名引用丢失 | yaml.safe_dump 不保留锚点 | 使用 yaml.dump(Dumper=yaml.Dumper) 保留引用关系 |
问题合集
Q1: JSON转CSV时,JSON值是数组或对象怎么办?
A: CSV是扁平格式,无法直接表示嵌套结构。需先将嵌套值扁平化(如 {"a": {"b": 1}} → {"a.b": 1}),或将数组/对象转为JSON字符串存入单元格.
Q2: 转换后中文变成 \u5f20\u4e09 怎么办?
A: 输出JSON时设置 ensure_ascii=False,如 json.dumps(data, ensure_ascii=False, indent=2)。YAML设置 allow_unicode=True.
Q3: XML的属性和子元素在JSON中如何区分?
A: xmltodict.parse() 默认将XML属性加 @ 前缀。如 <user id="1"><name>张三</name></user> 转为 {"user": {"@id": "1", "name": "张三"}}.
Q4: YAML转JSON时遇到 !!python/object 标签怎么办?
A: 这是非安全YAML标签,可能含恶意代码。务必使用 yaml.safe_load() 而非不安全的加载方式,safe_load 会拒绝执行任意Python对象.
Q5: TOML文件中的表数组 [[users]] 转JSON后是什么结构?
A: 转为JSON数组。多个 [[users]] 块合并为 "users": [{"name": "admin"}, {"name": "guest"}].
Q6: 批量转换时如何保持文件名一致?
A: 使用 Path.stem 获取文件名(不含扩展名),拼接目标扩展名:output_file = output_path / f'{file.stem}.{to_fmt}'.
使用约束
- CSV是扁平格式,无法无损表示JSON的嵌套结构,需扁平化或字符串化处理
- TOML不支持数组中的数组(如
[[a]] [[a.b]]内含数组值),复杂嵌套建议用JSON - YAML的锚点与别名在
safe_dump下会展开为独立副本,不保留引用关系 - XML与JSON的转换中,XML文本节点与属性节点的映射需自定义规则
- 批量转换不支持递归子目录,仅处理顶层文件
问题排查手册
| 错误现象 | 可能原因 | 诊断步骤 | 解决方案 |
|---|---|---|---|
| 转换后的文件内容错误 | 输入数据格式不正确或转换逻辑错误 | 检查输入数据格式,确认转换逻辑正确性,使用调试工具逐步检查转换过程 | 修正输入数据格式或转换逻辑,重新执行转换 |
| 转换速度慢 | 数据量过大或转换逻辑复杂 | 检查数据量大小,优化转换逻辑,考虑使用更高效的库或工具 | 减少数据量,优化转换逻辑,使用更高效的库或工具 |
| 文件编码错误 | 文件编码与程序预期不符 | 使用工具检测文件编码,确认程序对编码的处理方式 | 修正文件编码或程序对编码的处理方式 |
| 批量转换失败 | 源目录结构复杂或文件权限问题 | 检查源目录结构,确认文件权限设置正确 | 优化目录结构,确保文件权限正确 |
| 异步回调失败 | 网络问题或回调URL错误 | 检查网络连接,确认回调URL正确 | 修复网络问题,确保回调URL正确 |
安全指引
| 风险项 | 等级 | 防护措施 | 验证方法 |
|---|---|---|---|
| 数据泄露 | 高 | 对输入数据进行加密处理,确保输出数据安全存储 | 定期进行安全审计,检查数据加密情况 |
| 恶意代码攻击 | 中 | 对输入数据进行验证,防止执行恶意代码 | 使用安全扫描工具检测恶意代码 |
| 权限滥用 | 中 | 限制用户权限,确保只有授权用户可以访问敏感数据 | 定期进行权限审计,确保权限设置正确 |
| 网络攻击 | 高 | 使用防火墙和入侵检测系统,防止网络攻击 | 定期进行网络安全检查,确保系统安全 |
| 数据损坏 | 中 | 对数据进行备份,确保数据可恢复 | 定期进行数据备份,验证数据完整性 |
创新亮点
| 效率提升量化分析 |
|---|
| 转换速度提升 |
| 批量处理能力提升 |
| 转换格式种类 |
| 支持嵌套结构处理 |
| 差异性对比表格 |
|---|
| 功能 |
| --- |
| 支持格式种类 |
| 支持嵌套结构处理 |
| 批量处理能力 |
| 异步处理能力 |
| 编码处理能力 |
| 格式美化能力 |
性能评估
| 操作场景 | 手动耗时 | 自动化耗时 | 效率提升 |
|---|---|---|---|
| 文件解析与提取 | 5-10分钟/个 | <5秒/个 | 60-120x |
| 批量文件处理(100个) | 8-16小时 | <5分钟 | 96-192x |
| API调用与响应解析 | 2-3分钟/次 | <1秒/次 | 120-180x |
| 多接口数据聚合 | 15-30分钟 | <10秒 | 90-180x |
| 命令执行与结果收集 | 3-5分钟/次 | <2秒/次 | 90-150x |
| 重复任务批量执行 | 因任务而异 | 线性缩减 | 5-50x |
| 错误排查与修复 | 10-30分钟 | <30秒 | 20-60x |
特色对比
| 对比维度 | 数据格式转换器 | 传统手动方式 | 通用脚本工具 |
|---|---|---|---|
| 自动化程度 | 全流程自动 | 完全手动 | 部分自动 |
| 错误处理 | 内置错误恢复 | 依赖人工经验 | 基本try-catch |
| 可复用性 | 参数化配置 | 一次性脚本 | 模板化 |
| 安全合规 | 内置安全检查 | 无安全保障 | 无安全保障 |
| 适用场景 | 在CSV、JSON、X | 通用场景 | 通用场景 |
主要功能特点
- 自动化执行: 在CSV、JSON、X
- 文件处理: 支持多种文件格式的读取、解析和写入操作
- API集成: 通过标准化接口调用外部服务并处理响应
- 命令执行: 在安全沙箱中执行系统命令并收集结果
- 信息检索: 快速搜索和过滤目标数据
问题汇总解答
Q1: 数据格式转换器支持哪些输入格式?
A1: 在CSV、JSON、X。支持文本指令和结构化参数输入,具体格式参考使用流程章节。
Q2: 需要配置API Key吗?
A2: 是的,部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求,并通过环境变量安全配置。
Q3: 命令行执行失败怎么办?
A3: 检查命令参数是否正确,确认运行环境支持exec能力。如遇权限问题,请参照错误处理章节排查。
数据格式转换器通用排查步骤
- 检查输入参数: 确认所有必填参数已提供且格式正确
- 查看日志输出: 定位具体错误行和异常类型
- 验证环境配置: 确认依赖库版本和运行环境满足要求
- 逐步调试: 缩小问题范围,隔离故障模块
依赖说明
运行环境
- Agent 平台: 支持SKILL.md的任意AI Agent
- 操作系统: Windows / macOS / Linux
可用性分类
- 分类: MD(纯Markdown指令,通过自然语言驱动Agent完成操作)
- 说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作。
Related skills
- Downloads
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v1.0.0
- License
- MIT-0
