功能说明: 本技能涵盖 中文交互、化工作流场景 等核心能力。

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发送指令：

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

Agent将：

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

场景2：校验指定目录

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

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

场景3：查看报告

输出示例：

{
  "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命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

安全注意事项

风险类型	防范措施
API密钥泄露	通过环境变量配置，禁止硬编码到代码或配置文件中
命令执行风险	仅执行白名单命令，避免拼接用户输入到命令行参数中
网络通信安全	使用HTTPS协议，验证SSL证书有效性
敏感数据暴露	输出结果中不包含密钥、令牌等敏感信息

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

核心功能

• 自动化执行: 基于指令驱动的自动化流程
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据