Skip to content
BranchesTags

Repository files navigation

jsonseek

PyPI version Downloads License: MIT Python 3.8+

JSON/JSONL 解析工具包，专为 LLM 设计。

When LLMs touch JSON, they should shape first, query second, never cat the whole file. When a human touches JSON, the same rules apply — just with a keyboard instead of a context window.

jsonseek 是一个针对 大 JSON / JSONL 文件做的 LLM-friendly 解析与局部修改工具。核心目标：不要让 LLM cat 整个 JSON 进上下文。先 shape 看骨架，再 query / get 精准定位，最后 set / add / del / append 做最小化修改。

支持 结构理解、字段简表、局部查询、局部修改、Bug 定位与修复 —— JSON 和 JSONL 同一套命令。

🤖 给 LLM Coding Agent 的 Skills（Claude / Kimi / Cursor / Codex 等）

直接告诉 agent "用 jsonseek" 即可。 Skills 文档就摆在下面，按需查阅。

Skills 链接 适用
SKILL.md 👉 在 GitHub 上查看 Agent 启动加载：触发场景、核心命令速查、写操作三铁律、Windows API 兜底
commands.md 👉 在 GitHub 上查看 按需查阅：每个命令的 flag / 示例 / 输出格式
path-syntax.md 👉 在 GitHub 上查看 按需查阅：路径语法全集（点号 / 方括号 / 混合 / 数组 / 转义）

Skills 在 GitHub 上的位置：lo2589/jsonseek/skills/jsonseek/

接入 agent（Claude Code / Cursor / Codex 等）：

git clone https://github.com/lo2589/JSONSEEK.git
ln -s ../jsonseek/skills/jsonseek/SKILL.md ~/.claude/skills/jsonseek.md
# 或 ~/.cursor/skills/  ~/.codex/skills/

或 pip 安装后从 site-packages 里：

<site-packages>/jsonseek-<current_version>.data/data/skills/jsonseek/
├── SKILL.md
└── references/
    ├── commands.md
    └── path-syntax.md

为什么 JSON 值得专门做一个工具

JSON 是现代数据交换的事实标准。从机器学习实验记录、API 接口配置、应用日志流，到微服务注册表和爬虫数据存储，JSON/JSONL 无处不在：

  • ML 实验追踪：训练参数、指标曲线、模型配置全存在 JSON 里，一个实验目录轻松堆出几十 MB
  • API / 微服务配置：服务发现、路由规则、环境变量往往以 JSON 配置形式管理
  • 日志与事件流：结构化日志（JSONL）比纯文本更易查询，但文件体积增长极快
  • 数据交换：前后端通信、服务间 RPC、爬虫落地，JSON 是最常见的数据格式

问题是：JSON 越大，处理它的成本越高。全量 cat 一个 10MB JSON 进 LLM 上下文，等于烧掉几百万 token；人类开发者面对几千行嵌套结构手翻也是折磨。

jsonseek 就是来解决这个问题的——用局部操作替代全量读取，用结构化查询替代肉眼翻找。对于需要频繁处理 JSON / JSONL 的 LLM coding agent 和开发者，这是一个必备工具。

为什么 LLM 应该用 jsonseek

当你（或你正在运行的 Claude / Kimi / Cursor / Codex 等 agent）面对一个 10MB 的 JSON 时，全量 cat 进上下文是 灾难性的 token 浪费。jsonseek 让 agent 可以：

  1. 先理解结构 —— shape 看骨架、fields 看字段表，不读内容
  2. 再定位目标 —— query 搜关键词、ls 看某层子节点、get 取指定值
  3. 最后局部修改 —— set / add / del / append 只动需要动的地方

Token 节省估算

文件大小 操作 全量读取 jsonseek 输出 节省
100KB config JSON shape ~25K tokens ~100 tokens 99%+
100KB config JSON fields ~25K tokens ~300 tokens 98%+
100KB config JSON get 单值 ~25K tokens ~10 tokens 99%+
100KB config JSON query 命中几条 ~25K tokens ~100 tokens 99%+
10MB log JSONL shape 采样 ~2.5M tokens ~200 tokens 99.9%+
10MB log JSONL query 命中几十 ~2.5M tokens ~1K tokens 99.9%+

粗估：1 token ≈ 4 bytes 英文文本。实际比例取决于内容和 tokenizer，但量级是稳定的——文件越大，省得越多。

给 LLM 的典型工作流

# 1. 看骨架 — 不用读内容
jsonseek shape data.jsonl

# 2. 看有哪些字段
jsonseek fields data.jsonl --top

# 3. 搜关键字段
jsonseek query data.jsonl password --record-id-field id --max-results 5

# 4. 读具体值
jsonseek get data.jsonl '[3].password'

# 5. 修改（**永远先 --dry-run**）
jsonseek set data.jsonl '[3].password' 'newpass' --dry-run
jsonseek set data.jsonl '[3].password' 'newpass' --backup

安装

pip install jsonseek

需要 Python 3.8+。零依赖、零配置，装完即用。

$ jsonseek --version
jsonseek <current_version>

命令一览

读 / 检视（只读，安全）

命令 用途
shape FILE 显示文件结构（树形）
fields FILE [keyword] 列出所有字段及类型
ls FILE [path] 列出某层子节点
get FILE path 取某个路径的值
query FILE keyword 搜索 key / value
extract PATTERN path 批量从多个文件取同一个路径
concat PATTERN 合并多个 JSON 文件为 JSONL

改 / 局部操作（写入）

命令 用途
set FILE path value 修改字段
add FILE path value 添加新字段
del FILE path 删除字段 / 数组项
append FILE path value 向数组追加一项
extend FILE path json_array 用一个 JSON 数组扩展目标数组
cutline FILE N 提取 JSONL 第 N 行到临时文件
replaceline FILE N 替换 JSONL 第 N 行

通用选项

选项 用途
--output json 输出机器可读 JSON（管道 / agent 调用必加）
--backup 写操作前生成 .bak 备份
--dry-run 写操作前永远先加这个预览
--kind {json,jsonl} 强制文件类型（自动检测失败时）
--encoding ENCODING 强制编码（自动检测失败时，例如 gbk）
--context N JSONL 预览行数（默认 2）

路径语法

写法 例子 含义
点号 a.b.c a -> b -> c
方括号 a[key1][key2] a -> key1 -> key2
混合 a[key1].b[0] a -> key1 -> b -> 0
数组下标 items[0][1] items -> 0 -> 1

⚠️ zsh 用户：路径里有 [N] 必须用单引号（或者 noglob），zsh 会尝试把方括号当 glob 展开：

# ❌ zsh 会报 "no matches found"
jsonseek del file.json services[0].deprecated

# ✅ 以下任意一种都行
jsonseek del file.json 'services[0].deprecated'
noglob jsonseek del file.json services[0].deprecated

bash / fish / 加引号的 zsh 都正常。

三条铁律（给 LLM 也给人类）

  1. 改之前，永远先 --dry-run： 
    jsonseek set file.json path value --dry-run
# [DRY-RUN] Before: path = old
# [DRY-RUN] After:  path = new
  2. 写之前，永远加 --backup： 
    jsonseek set file.json path value --backup
# → 生成 file.json.bak
  3. 管道到另一个工具，永远加 --output json： 
    jsonseek query file.json keyword --output json | jq '.hits[0]'

为 AI / Coding Agent 设计

jsonseek 的设计哲学是 LLM 的 token 预算：

  • 输出尽可能短：默认输出筛过的关键信息，不打印无用结构
  • 输出格式稳定：所有命令都支持 --output json，agent 能直接解析
  • 写操作可预览：所有 set / add / del 都有 --dry-run，agent 在工具调用前能先看 diff
  • 干运行：jsonseek shape 在 10MB JSONL 上只读前 100 行就停（--sample-size 可调），token 用量恒定

典型 agent 工作流：

读取 → shape / fields / ls / query / get
       ↓ （了解结构）
定位 → query / get
       ↓ （找到目标）
修改 → set / add / del / append   （先 --dry-run 预览 → 再加 --backup 真改）
       ↓ （验证）
读取 → query / get

跨平台

  • macOS / Linux：原生命令行工作
  • Windows PowerShell：读命令（shape / fields / get / query / ls / extract / concat）走 CLI 完全可用
  • Windows 写命令：因为 PowerShell 会剥离双引号，复杂值会失败——用 Python API 代替

Windows 写操作的 Python API：

import sys
sys.path.insert(0, '.')

from jsonseek.commands.set_cmd import set_value
from jsonseek.commands.add_cmd import add_value
from jsonseek.commands.append_cmd import append_value
from jsonseek.commands.extend_cmd import extend_value
from jsonseek.commands.del_cmd import del_value
from jsonseek.commands.replaceline_cmd import replace_line

# Set/Add/Append/Extend 复杂值 — 不受 shell quoting 影响
set_value('file.json', 'path', {"key": "value"})
add_value('file.json', 'path', ["item1", "item2"])
append_value('file.json', 'items', {"id": 1})
extend_value('file.json', 'items', [{"id": 2}, {"id": 3}])

# Delete
del_value('file.json', 'path')

# JSONL 替换整行
replace_line('file.jsonl', 5, '{"id": 5, "name": "fixed"}')

CLI 写命令成功时打印 patch 预览，失败时打印 Error: ...。Python API 写助手成功时静默，失败时抛异常。

完整命令参考

每个命令的完整签名、所有 flag、所有输出格式。最新最全的列表直接跑 jsonseek <command> --help。

只读命令

shape FILE

显示结构 / 骨架树。

--kind {json,jsonl}        强制文件类型（默认自动检测）
--output {pretty,json}     输出格式（默认 pretty）
--encoding ENCODING        强制编码（默认自动检测）
--max-depth N              限制遍历深度（默认不限制）
--array-mode {sample,full} JSONL 数组遍历方式，`sample` 默认，`full` 走全部
--sample-size N            JSONL 采样行数（默认 100）

fields FILE [keyword]

列出所有字段及类型 / 出现次数。

--top                      只显示顶层字段
--kind / --output / --encoding    (同上)

ls FILE [path]

列出某路径下的子节点。JSONL：路径必须以 [N] 或 records[N] 开头。

--kind / --output / --encoding    (同上)

get FILE path

读某路径下的值。--output 控制输出格式。

--kind / --output / --encoding    (同上)

query FILE term

搜索 key 或 value。

--case-sensitive           大小写敏感（默认不敏感）
--exact                    完全匹配（默认子串匹配）
--match-mode {key,value,both}    匹配目标（默认 both）
--max-results N            限制结果数
--record-id-field FIELD    JSONL：用 FIELD 当 record ID
--preview-field FIELD      JSONL：额外显示 FIELD 作为预览
--kind / --output / --encoding / --context N    (同上)

extract PATTERN path

从 glob 匹配到的多个 JSON 文件批量取同一个路径。

--include-missing          路径不存在的文件也包含进来（默认跳过）
--output {pretty,json}     输出格式（默认 pretty）

concat PATTERN

把多个 JSON 文件合并成一个 JSONL。

-o, --output-file FILE     输出文件（默认 stdout）
--no-sort                  保留 glob 顺序（默认按文件名排序）

写命令（永远先 --backup）

set FILE path value

修改某路径下的现有值。

--create-missing           自动创建中间路径（默认不存在就报错）
--from-file FILE           从文件读新值（避免 shell quoting 问题）
--backup                   写之前生成 FILE.bak
--dry-run                  只预览，不真写

add FILE path value

往 object 加新 key。key 已存在会报错。

--create-missing           自动创建中间路径
--from-file FILE           从文件读值
--backup / --dry-run       (同上)

del FILE path

删一个 key 或数组元素。

-y, --yes                  跳过确认
--backup / --dry-run       (同上)

append FILE path value

JSON：往数组追加一项，路径要指向数组。 JSONL：在根追加一条 record（不需要 path）。

--from-file FILE           从文件读值
--backup / --dry-run       (同上)

extend FILE path json_array

往数组扩展所有元素（自动展开 JSON 数组里的每个 item）。

--from-file FILE           从文件读数组
--backup / --dry-run       (同上)

cutline FILE LINE

提取指定 JSONL 行（1-indexed）到临时文件。用来修复坏行。

--save-temp                保存到临时文件并打印路径；否则打印到 stdout

replaceline FILE LINE [CONTENT]

替换指定 JSONL 行。用 --from-file 避免 quoting 问题。

--from-file FILE           从文件读替换内容

通用 flag（所有命令都有）

--kind {json,jsonl}        强制文件类型（默认自动检测）
--output {pretty,json}     pretty 默认人类可读；json 给 agent / 管道用
--encoding ENCODING        强制编码（默认自动检测，如 gbk / utf-8）
--backup                   写之前生成 FILE.bak
--dry-run                  预览，不真写
--context N                JSONL：目标行周围显示多少行（默认 2）

永远先用 --dry-run 试一遍。再加 --backup 真改。

退出码

码 含义
0 成功
1 通用错误（路径无效、文件不存在、写失败等）
2 CLI 参数错

环境变量

变量 作用
PYTHONIOENCODING 强制 stdout 编码（Windows 中文输出有用）

命令参考

完整文档见：

文档 内容
commands.md 每个命令的详细选项、参数、示例
path-syntax.md 路径语法的所有写法（点号、方括号、混合、数组下标、转义、负数下标等）

Skills 链接见 前面的 "🤖 给 LLM Coding Agent 的 Skills" 段。

Links

资源 链接
PyPI https://pypi.org/project/jsonseek/
GitHub https://github.com/lo2589/JSONSEEK
Issue 追踪 https://github.com/lo2589/JSONSEEK/issues

About

Path-based CLI for searching, inspecting, patching, and debugging JSON/JSONL files.

Topics

clicommand-line-tooldebuggingdeveloper-toolsjsonjson-toolsjsonljsonl-toolllmpython

Resources

Readme
MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages