递归扫描指定目录下所有.json文件，严格校验JSON语法并生成结构化错误报告，帮助开发者快速定位语法问题。
SKILL.md

---
slug: json-lint-tool-free
name: json-lint-tool-free
version: 1.0.0
displayName: JSON校验工具免费版
summary: 轻量级JSON语法校验工具，递归扫描工作区.json文件并输出结构化错误报告。
license: Proprietary
edition: free
description: JSON校验工具免费版提供工作区级别的JSON语法批量校验能力，帮助开发者快速发现配置文件、数据文件中的语法错误。核心能力：递归扫描指定目录的所有。Use
  when 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于实时流数据处理。适用于独立开发者、企业团队和自动化工作流场景。Use when 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于实时流数据处理。
tags:
- 集成工具
- JSON
- 校验
- 开发者工具
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: L3
pricing_model: per_use
suggested_price: 29.9
tools: ["read", "write", "exec"]
tags: "工具,效率,自动化"
---
# JSON校验工具（免费版）

本工具递归扫描工作区中的`.json`文件，逐个校验语法合法性，输出结构化错误报告，帮助开发者快速定位与修复JSON语法问题。

## 概述

JSON语法错误是配置文件与数据文件中最常见的问题之一，常见原因包括尾随逗号、单引号、未转义字符、注释混入等。手动逐文件检查效率低下，本工具提供目录级批量校验能力，一次扫描即可发现整个项目的所有JSON语法错误。

## 核心能力

### 目录递归扫描
- 支持指定根目录，递归查找所有`.json`文件
- 可配置扫描深度与排除模式
- 输出扫描文件计数与耗时

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

### 语法校验
- 基于标准JSON.parse进行严格校验
- 识别语法错误并提取错误信息
- 错误信息包含位置（行列号）与错误描述
- 不修复错误，仅报告（修复能力在专业版）

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

### 结构化报告
- 扫描时间戳
- 总文件数、有效文件数、无效文件数
- 通过率百分比
- 错误明细数组（路径+错误信息）

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

### 通过率统计
- 按目录维度统计通过率
- 按文件大小维度统计分布
- 历史趋势对比（需持久化存储）

**输入**: 用户提供通过率统计所需的指令和必要参数。
**处理**: 解析通过率统计的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回通过率统计的响应数据,包含状态码、结果和日志。
**技术参数**：使用`input_params`和`output_format`参数控制执行行为,支持`json`/`text`/`csv`输出格式。
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：轻量级、语法校验工具、递归扫描工作区、文件并输出结构化、错误报告、校验工具免费版提、供工作区级别的、语法批量校验能力、帮助开发者快速发、现配置文件、数据文件中的语法、核心能力、递归扫描指定目录、的所有、Use、when、需要数据分析、报表生成、统计洞察、数据可视化时使用、不适用于实时流数、据处理、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

| 场景 | 角色 | 价值 |
|---|---|---|
| 项目提交前校验 | 开发者 | 避免提交语法错误的JSON |
| 配置文件巡检 | 运维工程师 | 定期检查配置文件合法性 |
| 依赖文件检查 | 前端开发者 | 校验package.json等依赖文件 |
| 数据文件验收 | 数据工程师 | 验收数据导出文件的语法 |
| 教学作业批改 | 教师 | 批量检查学生提交的JSON作业 |
| CI/CD质量门禁 | DevOps工程师 | 提交阶段校验JSON合法性 |

## 使用流程

### 场景1：校验整个项目

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

```
扫描当前项目的所有.json文件，校验语法，输出错误报告。
```

Agent将：
1. 递归扫描项目目录，收集所有`.json`文件
2. 逐文件执行JSON.parse校验
3. 收集错误信息
4. 输出结构化报告

### 场景2：校验指定目录

```bash
node lint.js --dir path/to/config
```

仅校验`path/to/config`目录下的JSON文件。

### 场景3：查看报告

输出示例：
```json
{
  "scanned_at": "2026-07-18T10:00:00.000Z",
  "total_files": 150,
  "valid_files": 149,
  "invalid_files": 1,
  "pass_rate": 99.33,
  "errors": [
    {
      "path": "config/broken.json",
      "error": "Unexpected token } in JSON at position 42",
      "line": 3,
      "column": 15
    }
  ]
}
```

## 示例

### 扫描参数表

| 参数 | 类型 | 默认值 | 说明 |
|---:|---:|---:|---:|
| `dir` | string | ./ | 扫描根目录 |
| `recursive` | boolean | true | 是否递归子目录 |
| `max_depth` | integer | 10 | 最大递归深度 |
| `exclude` | array | [] | 排除的目录或文件模式 |
| `include_hidden` | boolean | false | 是否包含隐藏文件 |

### 报告字段说明

| 字段 | 类型 | 说明 |
|:---:|:---:|:---:|
| `scanned_at` | string | 扫描时间戳（ISO 8601） |
| `total_files` | integer | 扫描的文件总数 |
| `valid_files` | integer | 语法合法的文件数 |
| `invalid_files` | integer | 语法错误的文件数 |
| `pass_rate` | number | 通过率百分比 |
| `errors` | array | 错误明细数组 |
| `errors[].path` | string | 文件相对路径 |
| `errors[].error` | string | 错误信息 |
| `errors[].line` | integer | 错误行号 |
| `errors[].column` | integer | 错误列号 |

### 常见排除模式

| 模式 | 说明 |
|:------|------:|
| `node_modules` | 排除依赖目录 |
| `.git` | 排除版本控制目录 |
| `dist` | 排除构建产物 |
| `*.bak` | 排除备份文件 |
| `.cache` | 排除缓存目录 |

## 最佳实践

### 扫描范围控制
- 项目校验时排除`node_modules`/`.git`/`dist`等目录，避免扫描第三方文件
- 配置`max_depth`避免扫描过深的嵌套目录
- 使用`exclude`模式精确控制扫描范围

### 错误定位技巧
- 错误信息中的position是字符偏移量，可转换为行列号
- 优先检查错误位置的前一个字符，常见原因是尾随逗号
- 单引号错误需全文搜索替换为双引号
- 注释错误需移除所有`//`和`/* */`注释

### CI/CD集成
- 在提交阶段运行校验，失败时中断流水线
- 报告导出为JSON，供下游分析
- 通过率低于阈值（如95%）时告警
- 历史趋势追踪，监控质量变化

### 报告持久化
- 将报告按时间戳命名存储，便于历史对比
- 关键指标（通过率、错误数）纳入监控
- 错误明细归档，便于复盘

## 常见问题

### Q1：扫描很慢怎么办？
A：检查是否误扫描了`node_modules`等大目录。配置`exclude`排除无关目录。文件数超过1万时，建议分目录扫描或启用并行（专业版支持）。

### Q2：错误信息中的position如何定位？
A：position是字符偏移量，从0开始。可通过工具转换为行列号。本免费版的报告已包含line与column字段，直接查看即可。若编辑器不支持跳转，手动计算：每换行符加1行，行内位置为position减去行首偏移。

### Q3：某些文件被误报为错误？
A：JSON标准不支持注释、单引号、尾随逗号。若项目使用JSON5或JSONC等超集，这些文件会被标准校验器报错。建议将这类文件扩展名改为`.json5`或`.jsonc`，并从扫描中排除，或使用专业版的超集校验模式。

### Q4：通过率总是100%但仍有问题？
A：语法校验仅检查JSON合法性，不检查语义正确性。例如`{"age": "三十"}`语法合法但语义错误（年龄应为数字）。语义校验需要模式校验能力（专业版支持）。

### Q5：如何排除特定文件？
A：在`exclude`参数中添加文件名模式。例如`["*.test.json", "*.bak"]`排除测试文件与备份文件。排除模式支持通配符。

## 已知限制

本免费体验版限制以下高级功能：
- 单次扫描文件数 > 1000
- 并行扫描（多线程加速）
- JSON模式校验（Schema验证）
- JSON5/JSONC等超集支持
- 自动修复建议
- 历史趋势追踪与监控告警

解锁全部功能请使用专业版：json-lint-tool-pro
- 当前为免费版本,如需完整功能请升级到付费版获取全部能力
## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux
- **Node.js**: 14+（用于校验脚本）
- **Python**: 3.8+（备选校验脚本运行时）

### 依赖详情
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|---:|:---|---:|---:|
| LLM API | API | 必需 | 由Agent平台内置LLM提供 |
| JSON解析器 | 运行时 | 必需 | Node.js/Python内置 |
| 文件系统 | 运行时 | 必需 | Node.js fs/Python os |

### API Key 配置
- 本skill基于Markdown指令规范，无需额外API Key
- 所有校验在本地完成，不依赖外部服务

### 可用性分类
- **分类**: MD+EXEC（纯Markdown指令，校验功能需要exec命令行执行能力）
- **说明**: 基于Markdown的AI Skill，通过自然语言指令驱动Agent执行JSON语法校验任务，校验脚本通过命令行执行

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|:------:|--------|:-------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |
Json Lint Tool Free

SKILL.md

related skills
