数据格式转换器

支持CSV、JSON、XML、YAML、TOML格式间高效互转，含嵌套结构与批量处理，适用于数据分析和报表生成。

核心功能: 本技能提供化工作流场景等能力。

核心功能: 本技能提供中文交互、、报表生成、统计洞察、数据可视化时使用等能力。

核心功能: 本技能提供表数组与嵌套表）等能力。

快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

输入参数

参数名	类型	必填	说明
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配置方式:

bash

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

主要能力

CSV与JSON互转

CSV转JSON：使用 csv.DictReader() 逐行读取为字典，通过 json.dumps(ensure_ascii=False, indent=2) 输出UTF-8中文JSON.

python

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}）.

python

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 保留中文.

python

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对象）.

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解析为有序字典，属性以 @ 前缀标记.

python

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 格式化输出.

python

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文件，支持表数组和嵌套表.

python

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格式字符串.

python

import toml, json
# ...
with open('data.json', 'r', encoding='utf-8') as f:
    data = json.load(f)
# ...
toml_str = toml.dumps(data)

• 异常时参考错误处理章节进行恢复
• 关键参数: toml与json互转 选项

批量转换

支持目录级批量处理，遍历源格式文件并批量转换为目标格式：

python

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}'
        # 转换逻辑...

即刻上手

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

支持格式矩阵

输入\输出	CSV	JSON	YAML	XML	TOML
CSV	-	支持	间接	间接	间接
JSON	支持	-	支持	支持	支持
YAML	间接	支持	-	间接	间接
XML	间接	支持	间接	-	间接
TOML	间接	支持	间接	间接	-

"间接"表示先转为JSON再转为目标格式。JSON是所有转换的中心枢纽.

使用指南

1. 识别源格式：根据文件扩展名（.csv/.json/.yaml/.xml/.toml）确定输入格式
2. 选择目标格式：确认用户需要转换为何种格式
3. 加载源数据：使用对应解析器读取文件（注意 encoding='utf-8'）
4. 执行转换：通过JSON作为中间格式，或直接调用对应转换函数
5. 输出结果：写入目标文件，注意 ensure_ascii=False 保留中文，indent=2 格式化

详细示例

示例1：CSV转JSON

text

输入 (CSV):
name,age,city
张三,30,北京
李四,25,上海
# ...
输出 (JSON):
[
  {"name": "张三", "age": "30", "city": "北京"},
  {"name": "李四", "age": "25", "city": "上海"}
]

示例2：JSON转YAML

text

输入 (JSON):
{"database": {"host": "localhost", "port": 5432}, "debug": true}
# ...
输出 (YAML):
database:
  host: localhost
  port: 5432
debug: true

示例3：XML转JSON

text

输入 (XML):
<user id="101"><name>张三</name><age>30</age></user>
# ...
输出 (JSON):
{"user": {"@id": "101", "name": "张三", "age": "30"}}

示例4：TOML转JSON

text

输入 (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

text

输入: ./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能力。如遇权限问题，请参照错误处理章节排查。

数据格式转换器通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。