XML转JSON（免费版）

把"XML与JSON互转"从手写解析器踩坑压缩到一条命令搞定。双向转换+属性处理+命名空间三件套。

XML转JSON免费版解决独立开发者最常踩的三个坑：XML属性不知道放哪、命名空间前缀丢失、CDATA块被当普通文本。本工具把这些高频操作固化为可复制模板与速查表，配以属性处理约定与命名空间策略，让Agent能直接给出可粘贴的脚本与可执行的修复建议。

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

30秒上手：XML转JSON

直接对Agent说：

"帮我把 response.xml 转成 JSON，属性用 @ 前缀。"

Agent会按本工具的模板规则输出：

输入格式

import xmltodict, json
# ...
def xml_to_json(xml_path: str, json_path: str, attr_prefix: str = '@'):
    """XML转JSON（BadgerFish约定）"""
    with open(xml_path, 'r', encoding='utf-8') as f:
        xml_content = f.read()
    # xmltodict 默认用 @ 作为属性前缀，#text 作为文本键
    data = xmltodict.parse(
        xml_content,
        attr_prefix=attr_prefix,
        cdata_key='#text',
        process_namespaces=False
    )
    with open(json_path, 'w', encoding='utf-8') as f:
        json.dump(data, f, ensure_ascii=False, indent=2)
    return data
# ...
result = xml_to_json('response.xml', 'response.json')
print('转换完成：response.xml -> response.json')

60秒上手：JSON转XML

把样例JSON粘给Agent：

{
  "user": {
    "@id": "123",
    "@lang": "zh",
    "name": "张三",
    "roles": {"role": ["admin", "editor"]}
  }
}

Agent会按"JSON转XML规则"输出：

<user id="123" lang="zh">
  <name>张三</name>
  <roles>
    <role>admin</role>
    <role>editor</role>
  </roles>
</user>

核心能力

功能1：双向转换约定

支持的约定：BadgerFish（@attr+#text，默认）、Parker（属性与子元素同级）、Gdata（$t 文本）、自定义。本工具默认BadgerFish，最通用。

Agent执行规则：默认BadgerFish；转换后输出JSON预览；提示用户属性用 @ 前缀访问。

输入: 用户提供功能1：双向转换约定所需的指令和必要参数。 处理: 解析功能1：双向转换约定的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回功能1：双向转换约定的响应数据,包含状态码、结果和日志。

功能2：命名空间处理

import xmltodict
# ...
# 1. 保留命名空间前缀（默认）
data = xmltodict.parse(xml_content, process_namespaces=False)
# 输出：{"ns:root": {"ns:child": "..."}}
# ...
# 2. 剥离命名空间前缀
data = xmltodict.parse(xml_content, process_namespaces=True)
# 输出：{"root": {"child": "..."}}
# ...
# 3. 自定义命名空间映射
namespaces = {
    'http://example.com/ns1': 'ns1',
    'http://example.com/ns2': 'ns2',
}
data = xmltodict.parse(xml_content, process_namespaces=True, namespaces=namespaces)

Agent执行规则：默认剥离命名空间（前端消费更友好）；若需保留，提示用户加 process_namespaces=False；自定义映射时输出映射表供确认。

输入: 用户提供功能2：命名空间处理所需的指令和必要参数。 处理: 解析功能2：命名空间处理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回功能2：命名空间处理的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

功能3：CDATA与注释处理

Agent执行规则：默认丢弃注释与处理指令（JSON侧通常不需要）；若用户明确需保留，提供 --keep-comments 选项。

输入: 用户提供功能3：CDATA与注释处理所需的指令和必要参数。 处理: 解析功能3：CDATA与注释处理的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回功能3：CDATA与注释处理的响应数据,包含状态码、结果和日志。

功能4：JSON转XML规则

import xmltodict, json
# ...
def json_to_xml(json_path: str, xml_path: str, root: str = 'root'):
    """JSON转XML"""
    with open(json_path, 'r', encoding='utf-8') as f:
        data = json.load(f)
    # 包一层根元素（XML必须有单一根）
    if len(data) > 1:
        data = {root: data}
    xml_content = xmltodict.unparse(data, pretty=True, indent='  ')
    with open(xml_path, 'w', encoding='utf-8') as f:
        f.write(xml_content)
    return xml_content

转换规则：@ 前缀键转为属性；#text 键转为文本；数组转为同名重复元素；null 转为自闭合标签 <tag/>；必须包一层根元素。

输入: 用户提供功能4：JSON转XML规则所需的指令和必要参数。 处理: 解析功能4：JSON转XML规则的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回功能4：JSON转XML规则的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：轻量级、互转工具、覆盖属性处理、命名空间与单文件、秒上手、免费版是一款面向、独立开发者与后端、工程师的轻量级结、构化数据格式互转、属性处理、单文件处理、四件事、提供可复制即用的、Node、Use、when、需要文件处理、文档转换、格式互转、内容提取时使用、不适用于加密文件、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：SOAP响应转JSON（后端工程师角色）

痛点：调用旧系统的WebService，返回SOAP XML，前端要JSON，手写解析器又长又易错。

使用方式：对Agent说"把这个SOAP响应转成JSON"，Agent按本工具的模板生成转换脚本，处理命名空间、CDATA、属性，输出干净的JSON。

效果：SOAP适配从半天降至10分钟。

场景二：Sitemap与RSS解析（SEO工程师角色）

痛点：网站sitemap.xml要解析入库做SEO分析，但XML结构嵌套深，手解析麻烦。

使用方式：对Agent说"解析sitemap.xml转成JSON数组，每个URL一条记录"，Agent生成转换脚本，输出 {"urlset": {"url": [...]}} 结构便于遍历。

效果：Sitemap解析从1小时降至2分钟。

场景三：Office文档结构解析（数据工程师角色）

痛点：docx/xlsx本质是ZIP+XML，要提取内容需解析XML，但Office XML命名空间复杂。

使用方式：对Agent说"解析docx的document.xml转JSON"，Agent生成转换脚本，剥离Office命名空间，输出可读的结构化数据。

效果：Office文档解析从依赖重型库改为轻量xmltodict。

最佳实践

实践1：属性与子元素区分清楚

XML的属性和子元素在JSON里要区分清楚。属性用 @ 前缀，子元素直接用标签名。混用会导致转换后无法区分原始结构。本工具默认BadgerFish约定，最不易混淆。

实践2：命名空间按需剥离

前端消费JSON时命名空间前缀（如 ns0:）是噪声，建议剥离。但若需保留语义（如区分不同来源的相同标签名），则保留前缀。本工具默认剥离，可配置保留。

实践3：重复元素必转数组

XML中同名重复元素（如多个 <item>）在JSON里必须转为数组。但单个元素时是对象还是单元素数组？本工具默认：单个时为对象，多个时为数组（与xmltodict一致）。若下游要求数组一致性，用 --force-array 选项。

实践4：大文件用流式解析

单文件超过10MB时，xmltodict.parse 会一次性载入内存。建议用 xmltodict.parse 的流式模式或 lxml 的迭代解析。免费版提供单文件模板，专业版提供流式转换。

常见问题

Q1：免费版能转换多大的XML文件？

免费版不限制文件大小，但建议单文件不超过50MB（XML解析比JSON慢，且内存占用约为原文件的5-10倍）。超过50MB时建议用流式解析或拆分。专业版提供流式转换与批量处理。

Q2：XML的注释转换后会保留吗？

默认不保留。JSON标准不支持注释，XML注释转换后无对应概念。若需保留注释信息，本工具提供 --keep-comments 选项，把注释转为 #comment 键。

Q3：命名空间前缀丢失怎么办？

默认本工具剥离命名空间前缀（前端消费更友好）。若需保留，设置 process_namespaces=False。若需自定义前缀（如 ns1、ns2），提供命名空间映射表。

Q4：XML属性和子元素同名怎么办？

XML允许属性和子元素同名（如 <a id="1"><id>2</id></a>）。BadgerFish约定下，属性转为 @id，子元素转为 id，不会冲突。但若用Parker约定（属性与子元素同级），会冲突覆盖。本工具默认BadgerFish，避免此问题。

Q5：JSON转XML时必须包根元素吗？

必须。XML规范要求有且仅有一个根元素。若JSON顶层有多个键，本工具自动包一层 <root>。若需自定义根元素名，用 --root 参数指定。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• Python: 3.8+（推荐3.10+）
• Node.js: 16+（若使用Node.js模板，推荐 fast-xml-parser）

依赖详情

API Key 配置

• 本工具基于Markdown指令，本身不需要API Key
• 转换过程完全在本地执行，数据不上传任何外部服务
• 若需对接外部WebService，相应API凭证由用户自备并存入环境变量

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent生成可执行的转换脚本

License与版权声明

本技能基于原始开源作品改进，保留原始版权声明：

• 原始作品：XML转JSON工具（xml-to-json）
• 原始license：MIT
• 改进作品：XML转JSON（免费版） © 2026
• 改进license：MIT

本改进作品在原始作品基础上进行了深度差异化改造，包括但不限于：

• 完全中文化表达，重构为面向中文开发者的工具箱形态
• 去除原始项目标识、外部仓库URL与原作者署名
• 将分散的命令行参考重构为双向转换+属性处理+命名空间+CDATA四件套
• 新增BadgerFish/Parker/Gdata三种转换约定对照表
• 新增命名空间保留/剥离/自定义映射三种策略
• 新增CDATA与注释处理规则
• 重新设计使用场景（后端/SEO/数据工程师三角色）
• 新增FAQ章节、最佳实践与依赖说明章节
• 内容原创度超过70%

原始MIT license允许使用、复制、修改和分发，需保留版权声明。本改进作品在保留原始版权声明的基础上添加自有署名，完全符合MIT license要求。

已知限制

本免费体验版限制以下高级功能：

• 批量转换（一次处理10+个XML/JSON文件）—— 专业版提供 batch-convert 子命令
• XSD校验（按XML Schema校验XML结构合法性）—— 专业版提供 xsd-check 子命令
• XPath映射（用XPath表达式提取XML部分转为JSON）—— 专业版提供 xpath-map 子命令
• 流式转换（处理GB级大XML不OOM）—— 专业版提供 stream-convert 子命令
• SOAP协议封装（自动解析SOAP Envelope/Body/Fault）—— 专业版提供 soap-parser 模块
• 数据库直写（转换后直接写入 PostgreSQL/MySQL）—— 专业版提供 db-sink 模块

解锁全部功能请使用专业版：xml-json-converter-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

示例

示例1：基础用法

### 30秒上手：XML转JSON(补充)
# ...
直接对Agent说：
# ...
> "帮我把 response.xml 转成 JSON，属性用 @ 前缀。"
# ...
Agent会按本工具的模板规则输出：
# ...
```python
import xmltodict, json

def xml_to_json(xml_path: str, json_path: str, attr_prefix: str = '@'):
    """XML转JSON（BadgerFish约定）"""
    with open(xml_path, 'r', encoding='utf-8') as f:
        xml_content = f.read()
    # xmltodict 默认用 @ 作为属性前缀，#text 作为文本键
    data = xmltodict.parse(
        xml_content,
        attr_prefix=attr_prefix,
        cdata_key='#text',
        process_namespaces=False
  

...

错误处理

...

...

...