Json Parse Engine Free

SKILL.md

---
slug: json-parse-engine-free
name: json-parse-engine-free
version: 1.0.0
displayName: JSON解析引擎免费版
summary: 轻量级JSON解析、展平与提取工具，支持文件与字符串解析、嵌套结构展平、路径提取。
license: Proprietary
edition: free
description: JSON解析引擎免费版提供文件解析、字符串解析、嵌套展平、路径提取四项核心能力，帮助开发者将复杂JSON转化为可消费的结构化数据。核心能力：支持文件与字符串两种输入源、嵌套JSON展平为单层字典、点分路径提取嵌套元素、必填字段校验与完整度评分、记录计数与错误报告。Use
  when 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于实时流数据处理。
tags:
- 集成工具
- JSON
- 解析
- 开发者工具
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: L2
pricing_model: per_use
suggested_price: 19.9
tools: ["read", "write", "exec"]
tags: "工具,效率,自动化"
---
# 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解析过程 |
| 字段校验 | 测试工程师 | 验证响应字段完整度 |

## 使用流程

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

### 场景1：解析文件并展平

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

```python
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：字符串解析与路径提取

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

### 场景3：字段校验

```python
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解析、展平、提取与校验任务，解析脚本通过命令行执行

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