JSON解析引擎（免费版）

本工具提供JSON数据的解析、展平、提取与校验能力，帮助开发者将复杂嵌套JSON转化为可消费的结构化数据，适用于数据预处理与字段提取场景。

概述

JSON作为现代数据交换的主流格式，其嵌套结构往往复杂，直接消费困难。本工具围绕"解析与转化"场景，提供从原始JSON到可消费数据的完整处理链路：解析（文件/字符串）、展平（嵌套转单层）、提取（路径定位）、校验（字段完整度）。

核心能力

文件解析

支持UTF-8编码的JSON文件
自动检测并报告JSON语法错误
返回结构化的解析结果对象
记录数统计（数组长度/对象数）

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

字符串解析

支持任意JSON字符串输入
与文件解析相同的错误处理
适用于API响应、日志字段等场景

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

嵌套展平

将多层嵌套的JSON对象展平为单层字典
键名通过下划线连接父级与子级
数组按索引展开（如items_0_name）
保留原始值类型（字符串/数字/布尔/null）

输入: 用户提供嵌套展平所需的指令和必要参数。处理: 解析嵌套展平的输入参数,完成核心逻辑,返回结构化响应。输出: 返回嵌套展平的响应数据,包含状态码、结果和日志。

路径提取

支持点分路径语法（如project.building.floors）
支持数组下标（如items.0.name）
路径不存在时返回空数组
自动判断返回单值还是数组

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

字段校验

按必填字段列表校验
输出缺失字段与存在字段
计算完整度百分比
适用于数据质量评估

输入: 用户提供字段校验所需的指令和必要参数。处理: 解析字段校验的输入参数,完成核心逻辑,返回结构化响应。输出: 返回字段校验的响应数据,包含状态码、结果和日志。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：轻量级、展平与提取工具、支持文件与字符串、嵌套结构展平、解析引擎免费版提、路径提取四项核心、帮助开发者将复杂、转化为可消费的结、构化数据、核心能力、两种输入源、点分路径提取嵌套、必填字段校验与完、整度评分、记录计数与错误报、Use、when、需要数据分析、报表生成、统计洞察、数据可视化时使用、不适用于实时流数、据处理等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景	角色	价值
API响应解析	后端开发者	将嵌套响应展平为可消费字段
配置文件读取	运维工程师	提取配置中的关键参数
数据清洗预处理	数据分析师	将JSON转为表格友好结构
日志结构化	运维工程师	从日志JSON提取关键字段
教学示例演示	教师/学生	直观展示JSON解析过程
字段校验	测试工程师	验证响应字段完整度

使用流程

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

场景1：解析文件并展平

输入格式

参数名	类型	必填	说明
input	string	是	JSON解析引擎免费版处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

parser = JSONParser()
result = parser.parse_file("data.json")
if result.success:
    flat = parser.flatten_json(result.data)
    print(f"加载 {result.record_count} 条记录，展平为 {len(flat)} 个字段")

场景2：字符串解析与路径提取

json_str = '{"project":{"name":"测试项目","floors":[{"id":1}]}}'
result = parser.parse_string(json_str)
elements = parser.extract_elements(result.data, "project.floors")
# 返回 [{"id": 1}]

场景3：字段校验

required = ["user.name", "user.age", "user.email"]
report = parser.validate_schema(result.data, required)
print(f"完整度: {report['completeness']}%")
print(f"缺失: {report['missing_fields']}")

示例

解析结果对象字段

字段	类型	说明
`success`	boolean	解析是否成功
`data`	any	解析后的数据（失败时为None）
`errors`	array	错误信息数组
`record_count`	integer	记录数（数组长度或1）

展平规则表

原始结构	展平后键名	示例值
`{"a": {"b": 1}}`	`a_b`	1
`{"a": [1, 2]}`	`a_0`, `a_1`	1, 2
`{"a": [{"b": 1}]}`	`a_0_b`	1
`{"a": {"b": {"c": 1}}}`	`a_b_c`	1

路径语法速查

表达式	含义	示例
`key`	顶层字段	`name`
`key.subkey`	嵌套字段	`user.name`
`key.0`	数组首元素	`items.0`
`key.0.subkey`	数组元素的字段	`items.0.name`

字段校验报告

字段(续)	类型	说明
`valid`	boolean	是否全部必填字段都存在
`missing_fields`	array	缺失的字段列表
`present_fields`	array	存在的字段列表
`completeness`	number	完整度百分比（0-100）

最佳实践

展平策略选择

消费场景需表格结构时启用展平
保留原始嵌套时跳过展平，直接消费data
数组元素为对象时，展平会按索引展开，键名可能较长
深层嵌套（>5层）展平后键名可读性下降，建议限制深度

路径提取技巧

路径不存在时返回空数组，不会抛异常
数组下标必须是数字字符串（如"0"而非0）
路径区分大小写，与JSON键名完全一致
复杂提取建议先展平再按键名过滤

字段校验策略

必填字段列表建议从API契约或数据规范导出
完整度100%表示所有必填字段都存在
完整度低于阈值时触发数据质量告警
缺失字段明细用于定位数据采集问题

错误处理

解析失败时检查errors数组的错误信息
常见错误：编码问题（非UTF-8）、语法错误、文件不存在
错误信息包含行列号，便于定位
生产环境应捕获异常并记录日志

常见问题

Q1：展平后键名太长怎么办？

A：深层嵌套展平后键名确实较长（如a_b_c_d_e）。建议：(1) 限制展平深度；(2) 在展平前裁剪不必要的层级；(3) 使用路径提取替代全量展平，仅提取所需字段。

Q2：数组展平后字段数量爆炸？

A：大数组展平会生成大量字段（如100个元素的数组生成100组键）。建议：(1) 数组单独处理，不展平；(2) 按需提取数组元素；(3) 使用专业版的批处理与流式展平。

Q3：路径提取返回空数组？

A：路径不存在时返回空数组是预期行为。检查路径拼写、大小写、数组下标是否正确。路径区分大小写，User.name与user.name不同。

Q4：字段校验的完整度如何计算？

A：完整度 = 存在字段数 / 必填字段总数 × 100。例如必填5个字段，存在4个，完整度为80%。注意：字段存在但值为null仍算存在，若需校验非空，需在业务层处理。

Q5：解析大文件内存溢出？

A：本免费版为全量解析，大文件（>100MB）可能内存溢出。建议：(1) 拆分大文件；(2) 仅提取必要字段；(3) 使用专业版的流式解析。

已知限制

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

单次解析文件大小 > 10MB
流式解析（大文件分块处理）
批量文件解析（目录级扫描）
DataFrame转换（JSON转表格）
自定义展平策略（深度限制、键名分隔符）
增量解析与断点续传

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

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

依赖说明

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux
Python: 3.8+（用于解析脚本）

依赖详情

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent平台内置LLM提供
JSON解析器	运行时	必需	Python内置json模块
文件系统	运行时	必需	Python内置os/pathlib

API Key 配置

本skill基于Markdown指令规范，无需额外API Key
所有解析在本地完成，不依赖外部服务

可用性分类

分类: MD+EXEC（纯Markdown指令，解析功能需要exec命令行执行能力）
说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行JSON解析、展平、提取与校验任务，解析脚本通过命令行执行

输出格式

{
  "success": true,
  "data": {
    "result": "JSON解析引擎免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "json parse engine"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

Json Parse Engine Free

安装到 Tokeny（自动）

SKILL.md