Back to Details

json-flat-tool

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

JSON Flat Tool

JSON扁平工具

A single-script tool (
jstool.py
) for viewing, inspecting, and editing JSON data.
Script path: 
~/.claude/skills/json-flat-tool/jstool.py
一款单脚本工具（
jstool.py
），用于查看、检查和编辑JSON数据。
脚本路径：
~/.claude/skills/json-flat-tool/jstool.py

Invocation

调用方式

bash
python3 ~/.claude/skills/json-flat-tool/jstool.py <command> [args]
bash
python3 ~/.claude/skills/json-flat-tool/jstool.py <command> [args]

Commands

命令列表

CommandDescription
view [file] [opts]
Flat path/type/value display
schema [file] [--title T]
Infer JSON Schema Draft 7
set <path> <value> [file] [-f]
Set a field value
<path> = <value> [file] [-f]
Same, B-style syntax
before <path> <value> [file] [-f]
Insert before array element
after <path> <value> [file] [-f]
Insert after array element
del <path> [file] [-f]
Delete a key or element
set-null <path> [file] [-f]
Set a field to null
copy <src> <dst> [file] [-f]
Deep-clone a subtree to a new path
merge <path> <patch.json> [file] [-f]
Deep-merge a JSON file into a path
find <pattern> [file] [opts]
Search paths and values by regex or glob
Omit 
[file]
to read from stdin.
命令描述
view [file] [opts]
以扁平路径/类型/值形式展示
schema [file] [--title T]
推断JSON Schema Draft 7格式的Schema
set <path> <value> [file] [-f]
设置字段值
<path> = <value> [file] [-f]
功能同上，B风格语法
before <path> <value> [file] [-f]
在数组元素前插入内容
after <path> <value> [file] [-f]
在数组元素后插入内容
del <path> [file] [-f]
删除键或元素
set-null <path> [file] [-f]
将字段设为null
copy <src> <dst> [file] [-f]
将子树深度克隆到新路径
merge <path> <patch.json> [file] [-f]
将JSON文件深度合并到指定路径
find <pattern> [file] [opts]
通过正则表达式或通配符搜索路径和值
省略
[file]
则从stdin读取数据。

view Options

view命令参数

FlagUnitDescription
-s
—Schema mode: collapse 
[N]→[*]
, deduplicate, hide values
-F <path>
—Filter: show only this path and its children
-n <N>
rowsShow at most N rows
-O <N>
rowsSkip first N rows
-E <N>
elementsSkip first N array elements (use with 
-F
)
-L <N>
elementsShow at most N array elements (use with 
-F
)
-E
and 
-L
are element-aware and never cut an element in the middle.
参数单位描述
-s
—Schema模式：折叠
[N]→[*]
、去重、隐藏值
-F <path>
—过滤：仅显示该路径及其子节点
-n <N>
行数最多显示N行
-O <N>
行数跳过前N行
-E <N>
元素数跳过前N个数组元素（需配合
-F
使用）
-L <N>
元素数最多显示N个数组元素（需配合
-F
使用）
-E
和
-L
是元素感知的，绝不会从元素中间截断。

Edit flags

编辑参数

  • -f
    — Force: apply change to file. Default is preview-only.
  • Without 
    -f
    : shows a color-annotated diff of the original JSON with 
    ~~~~~
    underline markers at the exact change position.
  • -f
    — 强制：将更改应用到文件。默认仅预览。
  • 不使用
    -f
    时：显示原始JSON与更改后的彩色标注差异，在确切更改位置用
    ~~~~~
    下划线标记。

Path syntax

路径语法

root              root node
count             root-level key
users[0]          array element
users[0].name     nested key
root[0].key       root-array element key
root              根节点
count             根级键
users[0]          数组元素
users[0].name     嵌套键
root[0].key       根数组元素的键

Value parsing

值解析规则

Values are parsed as JSON first, then fall back to plain string:
Alice          → string
42             → integer
3.14           → number
true / false   → boolean
null           → null
'{"k":"v"}'    → object
'[1,2,3]'      → array
@path/to.json  → read value from file
值会先按JSON格式解析，解析失败则 fallback 为普通字符串：
Alice          → 字符串
42             → 整数
3.14           → 数字
true / false   → 布尔值
null           → null
'{"k":"v"}'    → 对象
'[1,2,3]'      → 数组
@path/to.json  → 从文件读取值

Output format (view)

输出格式（view命令）

root object
users array
users[0] object
users[0].name string Alice
users[0].age integer 30
users[1].age integer (null)    ← magenta: null with inferred type
orphan unknown (null)          ← red: null, type unknown
meta object (empty)            ← dim: empty container
Colors: cyan = path, yellow = type, green = value, magenta = inferred null, red = unknown/delete, dim = empty.
root object
users array
users[0] object
users[0].name string Alice
users[0].age integer 30
users[1].age integer (null)    ← 品红色：带推断类型的null
orphan unknown (null)          ← 红色：null，类型未知
meta object (empty)            ← 暗色：空容器
颜色说明：青色=路径，黄色=类型，绿色=值， 品红色=推断类型的null，红色=未知/已删除，暗色=空容器。

Workflow

使用流程

Explore a JSON file

探索JSON文件

bash
undefined
bash
undefined

Quick structure overview

快速查看结构概览

python3 ~/.claude/skills/json-flat-tool/jstool.py view data.json -s
python3 ~/.claude/skills/json-flat-tool/jstool.py view data.json -s

Filter to a nested array, element-aware pagination

过滤到嵌套数组，按元素分页

python3 ~/.claude/skills/json-flat-tool/jstool.py view data.json -F "data[0].bids" -E 5 -L 3
python3 ~/.claude/skills/json-flat-tool/jstool.py view data.json -F "data[0].bids" -E 5 -L 3

Infer JSON Schema Draft 7

推断JSON Schema Draft 7格式

python3 ~/.claude/skills/json-flat-tool/jstool.py schema data.json --title "My API"
undefined
python3 ~/.claude/skills/json-flat-tool/jstool.py schema data.json --title "My API"
undefined

Edit a JSON file

编辑JSON文件

bash
undefined
bash
undefined

Preview change (default)

预览更改（默认）

python3 ~/.claude/skills/json-flat-tool/jstool.py set users[0].name Bob data.json
python3 ~/.claude/skills/json-flat-tool/jstool.py set users[0].name Bob data.json

Apply change

应用更改

python3 ~/.claude/skills/json-flat-tool/jstool.py set users[0].name Bob data.json -f
python3 ~/.claude/skills/json-flat-tool/jstool.py set users[0].name Bob data.json -f

B-style

B风格语法

python3 ~/.claude/skills/json-flat-tool/jstool.py "users[0].name" = Bob data.json -f
python3 ~/.claude/skills/json-flat-tool/jstool.py "users[0].name" = Bob data.json -f

Insert / delete

插入 / 删除

python3 ~/.claude/skills/json-flat-tool/jstool.py before users[1] '{"name":"Eve"}' data.json -f python3 ~/.claude/skills/json-flat-tool/jstool.py del users[2] data.json -f python3 ~/.claude/skills/json-flat-tool/jstool.py set-null users[0].age data.json -f
undefined
python3 ~/.claude/skills/json-flat-tool/jstool.py before users[1] '{"name":"Eve"}' data.json -f python3 ~/.claude/skills/json-flat-tool/jstool.py del users[2] data.json -f python3 ~/.claude/skills/json-flat-tool/jstool.py set-null users[0].age data.json -f
undefined

Set value from file (
@file
)

从文件设置值（
@file
语法）

bash
undefined
bash
undefined

Write a complex object to a file, then set it at a path

将复杂对象写入文件，然后设置到指定路径

python3 ~/.claude/skills/json-flat-tool/jstool.py set provider.openai @/tmp/openai.json config.json -f
undefined
python3 ~/.claude/skills/json-flat-tool/jstool.py set provider.openai @/tmp/openai.json config.json -f
undefined

Clone a subtree (
copy
)

克隆子树（
copy
命令）

bash
undefined
bash
undefined

Clone an existing model as the base for a new one (preview)

克隆现有模型作为新模型的基础（预览）

python3 ~/.claude/skills/json-flat-tool/jstool.py copy
provider.google.models.antigravity-gemini-3-pro
provider.google.models.my-new-model
config.json
python3 ~/.claude/skills/json-flat-tool/jstool.py copy
provider.google.models.antigravity-gemini-3-pro
provider.google.models.my-new-model
config.json

Apply

应用克隆

python3 ~/.claude/skills/json-flat-tool/jstool.py copy
provider.google.models.antigravity-gemini-3-pro
provider.google.models.my-new-model
config.json -f
undefined
python3 ~/.claude/skills/json-flat-tool/jstool.py copy
provider.google.models.antigravity-gemini-3-pro
provider.google.models.my-new-model
config.json -f
undefined

Deep-merge a patch file (
merge
)

深度合并补丁文件（
merge
命令）

bash
undefined
bash
undefined

patch.json only needs to contain the fields to add/update

patch.json只需包含要添加/更新的字段

preview: shows which keys are added (+) and updated (~)

预览：显示哪些键是新增（+）和更新（~）的

python3 ~/.claude/skills/json-flat-tool/jstool.py merge provider.google.models /tmp/new-models.json config.json
python3 ~/.claude/skills/json-flat-tool/jstool.py merge provider.google.models /tmp/new-models.json config.json

Apply

应用合并

python3 ~/.claude/skills/json-flat-tool/jstool.py merge provider.google.models /tmp/new-models.json config.json -f
undefined
python3 ~/.claude/skills/json-flat-tool/jstool.py merge provider.google.models /tmp/new-models.json config.json -f
undefined

Find nodes by pattern (
find
)

按模式查找节点（
find
命令）

bash
undefined
bash
undefined

Regex search in both paths and values (default)

默认：在路径和值中进行正则搜索

python3 ~/.claude/skills/json-flat-tool/jstool.py find apiKey config.json
python3 ~/.claude/skills/json-flat-tool/jstool.py find apiKey config.json

Search path only (-k), value only (-v)

仅搜索路径（-k），仅搜索值（-v）

python3 ~/.claude/skills/json-flat-tool/jstool.py find apiKey config.json -k python3 ~/.claude/skills/json-flat-tool/jstool.py find "sk-.*" config.json -v
python3 ~/.claude/skills/json-flat-tool/jstool.py find apiKey config.json -k python3 ~/.claude/skills/json-flat-tool/jstool.py find "sk-.*" config.json -v

Case-insensitive

大小写不敏感

python3 ~/.claude/skills/json-flat-tool/jstool.py find "APIKEY" config.json -k -i
python3 ~/.claude/skills/json-flat-tool/jstool.py find "APIKEY" config.json -k -i

Glob mode (full-string wildcard, use * to match anywhere)

通配符模式（全字符串通配符，用*匹配任意位置）

python3 ~/.claude/skills/json-flat-tool/jstool.py find "api" config.json -k -g -i

**find options**:

| Flag | Description |
|------|-------------|
| `-k` | Match path only |
| `-v` | Match value only |
| `-i` | Case-insensitive |
| `-g` | Glob mode (fnmatch full-string wildcard instead of regex) |

`-k` and `-v` are mutually exclusive. Without either flag, both path and value are searched.
python3 ~/.claude/skills/json-flat-tool/jstool.py find "api" config.json -k -g -i

**find命令参数**:

| 参数 | 描述 |
|------|-------------|
| `-k` | 仅匹配路径 |
| `-v` | 仅匹配值 |
| `-i` | 大小写不敏感 |
| `-g` | 通配符模式（使用fnmatch全字符串通配符，而非正则） |

`-k`和`-v`互斥。若不指定两者，则同时搜索路径和值。

Inline / piped JSON

内联/管道JSON数据

bash
echo '{"name":"Alice"}' | python3 ~/.claude/skills/json-flat-tool/jstool.py view
curl https://api.example.com/data | python3 ~/.claude/skills/json-flat-tool/jstool.py schema
bash
echo '{"name":"Alice"}' | python3 ~/.claude/skills/json-flat-tool/jstool.py view
curl https://api.example.com/data | python3 ~/.claude/skills/json-flat-tool/jstool.py schema

Notes

注意事项

  • before
    / 
    after
    only apply to array elements, not object keys.
  • To add a new key to an object, use 
    set
    .
  • -f
    without a file path prints modified JSON to stdout.
  • -E
    / 
    -L
    require 
    -F
    pointing to an array path.
  • Array sampling for schema inference: up to 20 elements.
  • required
    in schema = fields present and non-empty in all sampled elements.
  • @file
    syntax works with 
    set
    and B-style (
    =
    ); 
    merge
    always takes a file path directly.
  • copy
    performs a deep clone — mutations to the copy do not affect the source.
  • merge
    for non-dict targets replaces the value entirely (patch wins).
  • find -g
    uses 
    fnmatch
    (full-string wildcard): use 
    *api*
    not 
    api*
    for substring matching.
  • find
    without 
    -g
    uses Python 
    re.search
    (substring regex by default).
  • before
    /
    after
    仅适用于数组元素，不适用于对象键。
  • 要为对象添加新键，请使用
    set
    命令。
  • 不带文件路径使用
    -f
    会将修改后的JSON输出到stdout。
  • -E
    /
    -L
    需要配合指向数组路径的
    -F
    参数使用。
  • Schema推断的数组采样：最多20个元素。
  • Schema中的
    required
    字段=所有采样元素中都存在且非空的字段。
  • @file
    语法适用于
    set
    和B风格（
    =
    ）命令；
    merge
    始终直接接收文件路径。
  • copy
    执行深度克隆——对副本的修改不会影响源数据。
  • 针对非字典目标的
    merge
    操作会完全替换值（补丁优先级更高）。
  • find -g
    使用
    fnmatch
    （全字符串通配符）：若要匹配子串，请使用
    *api*
    而非
    api*
    。
  • 不带
    -g
    的
    find
    使用Python的
    re.search
    （默认子串正则匹配）。