JSON 工具箱（免费版）

概述

本 Skill 为 Agent 提供 JSON 数据结构处理的优选实践指南。核心理念是"防御式设计"：在处理不可信输入前先校验，在定义 API 响应时先立契约，避免"假设结构正确"的陷阱。免费版覆盖个人开发者高频场景：Schema 校验、命名一致性、空值处理、日期时间、数字 ID、结构优选实践。

核心能力

核心功能执行

用input_params参数进行配置。

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

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

参数配置与调用

用config_options参数进行配置。

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

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

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

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：数据结构处理优选、含校验、数字规范、核心能力、校验与契约定义、命名规范与一致性、空值处理与可选字、段策略、日期时间与数字、结构优选实践与等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

1. API 接口设计：定义请求与响应的 JSON Schema，用 additionalProperties: false 拒绝未知字段，提前发现契约违反。
2. 前后端数据交换：统一命名约定（JS 生态用 camelCase，Python 用 snake_case），避免 userId 与 user_name 混用造成混淆。
3. 配置文件处理：处理外部配置 JSON 时先校验 Schema，避免缺字段或类型错误导致运行时崩溃。
4. 第三方接口对接：解析第三方 API 返回的 JSON 时用 try/catch 包裹，避免格式错误中断流程。

不适用场景

以下场景JSON工具箱(免费版)不适合处理：

• 实时流数据处理
• 小规模数据手动分析
• 非结构化文本情感分析

触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。

快速开始

上手时间：< 60 秒。本 Skill 为纯指令型，无需安装依赖。

Step 1：定义 Schema 校验

{
  "type": "object",
  "properties": {
    "id": {"type": "string"},
    "name": {"type": "string"},
    "price_cents": {"type": "integer"}
  },
  "required": ["id", "name"],
  "additionalProperties": false
}

Step 2：处理空值

{
  "id": "9007199254740993",
  "name": "示例",
  "deleted_at": null
}

Step 3：规范日期与数字

{
  "created_at": "2026-07-18T14:30:00Z",
  "price_cents": 1999,
  "user_id": "9007199254740993"
}

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤。

示例

命名约定对照表

空值处理策略

数字处理规范

优选实践

1. 处理前必校验：所有不可信输入先校验 JSON Schema，不假设结构正确。
2. 为 API 响应定义 Schema：提前发现契约违反，而非等消费方报错。
3. 严格上下文拒绝未知字段：additionalProperties: false 拒绝未知字段，避免"宽进严出"。
4. 命名约定统一：同一 payload 内不混用 camelCase 与 snake_case。
5. 集合用复数："users": [] 而非 "user": []，语义清晰。
6. 区分 null 与缺失：null 表示"显式置空"，缺失表示"从未设置"，二者含义不同。
7. 可选字段省略：无值时省略字段，减少 payload 体积，意图更清晰。
8. 日期用 ISO 8601："2026-07-18T14:30:00Z"，含时区或 UTC 的 Z 后缀。
9. 大数转字符串：ID 超过 2^53 用字符串，避免 JS 精度损失。
10. 金额不用浮点：用字符串 "19.99" 或整数分 1999，避免浮点误差。
11. 嵌套不超过 3 层：超过则扁平化或拆分到相关端点。
12. 统一 API 信封：{"data": ..., "meta": ..., "errors": ...} 标准结构。
13. 分页避免无界列表：大数组必须分页，含 next/prev 链接或游标。

常见问题

Q1：为什么建议用字符串表示大 ID？

A：JavaScript 安全整数上限是 2^53（约 9007 万亿）。超过该值的整数在 JSON.parse 后会丢失精度，如 9007199254740993 会变成 9007199254740992。用字符串可避免该问题。

Q2：null 和字段缺失有什么区别？

A：null 表示"字段存在但值为空"（如已删除的记录 deleted_at: null）；字段缺失表示"从未设置过"。消费方逻辑可能不同，Schema 中应明确标注哪些字段可空。

Q3：为什么金额不能用浮点数？

A：浮点数无法精确表示十进制小数（如 0.1 + 0.2 != 0.3）。金额计算会产生累计误差。建议用字符串 "19.99" 或整数分 1999（表示 19.99 元）。

Q4：日期时间为什么用字符串而非时间戳？

A：(1) 字符串可读，便于调试；(2) 时间戳整数在不同语言精度不一（秒/毫秒）；(3) ISO 8601 字符串含时区信息，避免歧义。

Q5：免费版是否支持循环引用序列化？

A：免费版仅提示"检测循环引用"。循环引用的深度处理（如 flatted 库）需使用专业版。

已知限制

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

• 高级序列化（Map/Set/BigInt/循环引用处理）（专业版支持）
• 深度解析安全（reviver 函数与 BOM 处理）（专业版支持）
• Unicode 边界处理（代理对与控制字符）（专业版支持）
• 自动化校验流水线（批量校验与报告）（专业版支持）
• 自定义 replacer 与 reviver 模板（专业版支持）

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

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

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 编程语言：任意支持 JSON 的语言（JavaScript / Python / Go / Java 等）

依赖详情

API Key 配置

• 本 Skill 基于指令驱动：无需额外 API Key，纯 Markdown 优选实践指南

可用性分类

• 分类：MD（纯 Markdown 指令，无需 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 遵循 JSON 处理优选实践

错误处理

输出格式

{
  "success": true,
  "data": {
    "result": "JSON工具箱(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "jsonkit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}