{"id":47737834,"url":"https://github.com/caoergou/jzen","last_synced_at":"2026-04-02T23:02:03.996Z","repository":{"id":345663904,"uuid":"1186859562","full_name":"caoergou/jzen","owner":"caoergou","description":"Edit JSON configs without the struggle — interactive TUI for humans, agent-optimized CLI for AI","archived":false,"fork":false,"pushed_at":"2026-03-25T05:05:47.000Z","size":311,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T15:13:44.164Z","etag":null,"topics":["ai-agent-tools","cli","configuration","json","json-editor","ratatui","rust","tui"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caoergou.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T04:09:40.000Z","updated_at":"2026-03-25T05:05:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/caoergou/jzen","commit_stats":null,"previous_names":["caoergou/je","caoergou/jed","caoergou/jzen"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/caoergou/jzen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caoergou%2Fjzen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caoergou%2Fjzen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caoergou%2Fjzen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caoergou%2Fjzen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caoergou","download_url":"https://codeload.github.com/caoergou/jzen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caoergou%2Fjzen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31318137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T21:35:00.834Z","status":"ssl_error","status_checked_at":"2026-04-02T21:34:59.806Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent-tools","cli","configuration","json","json-editor","ratatui","rust","tui"],"created_at":"2026-04-02T23:02:03.129Z","updated_at":"2026-04-02T23:02:03.983Z","avatar_url":"https://github.com/caoergou.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jzen — JSON 配置编辑器\n\n[English Version](./README.md)\n\n无需费力编辑 JSON — **面向人类的交互式 TUI**，**面向 AI Agent 的优化 CLI**。\n\n- **面向人类**: 可视化树形导航、内联编辑、语法高亮、自动修复\n- **面向 AI Agent**: 最小 Token 输出、原子写入、批量操作\n\n同一二进制文件。两种模式。一个引擎。\n\n---\n\n## 为什么需要 Jzen？\n\n### 场景 1: 修改 Claude Code MCP 配置\n\n当需要修改 Claude Code 的 `settings.json` 配置 MCP servers 时，传统方式需要：\n\n- 将整个配置文件加载到上下文窗口（经常 100+ 行）\n- 手动定位需要修改的字段\n- 修改后重新写入整个文件\n- **结果**: Token 消耗高，手动编辑容易出错\n\n使用 Jzen，只需为你修改的部分付费：\n\n```bash\n# 检查结构而不读取值\njzen schema ~/.claude/settings.json\n\n# 只获取你需要的具体值\njzen get .mcpServers.github.command ~/.claude/settings.json\n\n# 原子更新单个字段\njzen set .mcpServers.github.env.TOKEN '\"ghp_xxxx\"' ~/.claude/settings.json\n\n# 一次调用批量更新（最少往返）\njzen patch '[\n  {\"op\": \"replace\", \"path\": \".defaultMode\", \"value\": \"acceptEdits\"},\n  {\"op\": \"add\", \"path\": \".mcpServers.github.enabled\", \"value\": true}\n]' ~/.claude/settings.json\n```\n\n**Token 节省**: 90%+ — 只读取查询的内容，而非整个文件。\n\n---\n\n### 场景 2: 修改 OpenClaw Agent 配置\n\nOpenClaw 使用 JSON 配置 agent 行为。传统工具需要：\n\n- 打开整个文件来了解其结构\n- 手动编辑并保存整个文件\n- 格式错误导致 agent 崩溃的风险\n\nJzen 让这一切变得简单：\n\n```bash\n# 一目了然地查看结构\njzen tree ~/.config/openclaw/agent.json\n\n# 更新模型配置\njzen set .model.provider '\"openai\"' ~/.config/openclaw/agent.json\njzen set .model.name '\"gpt-4o\"' ~/.config/openclaw/agent.json\n\n# 添加新的 MCP server\njzen set .mcpServers.github '{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"]\n}' ~/.config/openclaw/agent.json\n\n# 自动修复常见 JSON 错误\njzen fix --strip-comments ~/.config/openclaw/agent.json\n```\n\n**优势**: 原子写入、崩溃安全操作、自动格式修复。\n\n---\n\n## 对比：传统方式 vs Jzen\n\n| 任务 | 传统方式 | Jzen |\n|------|----------|------|\n| 读取配置结构 | 加载整个文件 | `schema` → 仅类型输出 |\n| 读取具体值 | 解析完整 JSON | `get .key` → 单个值 |\n| 修改一个字段 | 重写整个文件 | `set .key val` → 原子操作 |\n| 多个修改 | 多次往返 | `patch` → 单次调用 |\n| 修复 JSON 错误 | 手动修复 | `fix` → 自动修复 |\n| Token 成本 | 完整文件在上下文中 | 仅查询的值 |\n\n---\n\n## 快速开始\n\n```bash\n# TUI 模式（人类）\njzen config.json\n\n# 命令模式（agent / 脚本）\njzen get .name config.json\njzen set .name '\"Bob\"' config.json\njzen fix --strip-comments config.json\n\n# 两种参数顺序都支持\njzen config.json get .name\njzen get .name config.json\n```\n\n---\n\n## 安装\n\n### 包管理器（推荐）\n\n```bash\n# macOS / Linux (Homebrew)\nbrew install caoergou/jzen/jzen\n\n# Debian / Ubuntu\nsudo dpkg -i jzen_*.deb\n\n# Fedora / RHEL / CentOS\nsudo rpm -i jzen-*.rpm\n```\n\n### 安装脚本\n\n```bash\n# Linux / macOS — 自动检测平台，安装到 /usr/local/bin\ncurl -fsSL https://github.com/caoergou/jzen/releases/latest/download/install.sh | sh\n\n# 跳过自动安装 shell 补全\nSKIP_COMPLETIONS=1 curl -fsSL https://github.com/caoergou/jzen/releases/latest/download/install.sh | sh\n\n# 自定义安装目录\nINSTALL_DIR=~/.local/bin curl -fsSL https://github.com/caoergou/jzen/releases/latest/download/install.sh | sh\n```\n\n安装脚本会：\n1. 为你的平台下载正确的二进制文件\n2. 检测你的 shell (bash/zsh/fish)\n3. 自动将 shell 补全安装到适当的位置\n4. 如果需要手动设置，会给出提示\n\n### 预编译二进制\n\n从 [Releases](https://github.com/caoergou/jzen/releases) 页面下载：\n\n| 平台 | 二进制文件 |\n|------|-----------|\n| Linux x86_64 | `jzen-linux-x86_64` |\n| Linux aarch64 | `jzen-linux-aarch64` |\n| macOS x86_64 | `jzen-macos-x86_64` |\n| macOS Apple Silicon | `jzen-macos-aarch64` |\n| Windows x86_64 | `jzen-windows-x86_64.exe` |\n\n将二进制文件放到你的 `$PATH` 中的某个位置。\n\n### 从 crates.io 安装\n\n```bash\ncargo install jzen\n```\n\n### 从源码安装（需要 Rust）\n\n```bash\ncargo install --git https://github.com/caoergou/jzen\n```\n\n---\n\n## Agent Skill\n\n安装 jzen skill 使 AI agents 能够以最小的 token 使用量编辑 JSON：\n\n```bash\n# 为 Claude Code、OpenClaw、Codex 等安装\nnpx skills add caoergou/jzen\n\n# 或从本仓库安装特定 skill\nnpx skills add caoergou/jzen --skill jzen\n```\n\n安装后，agent 将自动使用 jzen 进行 JSON 操作，Token 消耗降低 90%+。\n\n---\n\n## TUI 模式\n\n通过仅传入文件名启动：\n\n```bash\njzen settings.json\n```\n\n| 按键 | 操作 |\n|------|------|\n| `↑/↓` | 上/下移动 |\n| `←` | 折叠 / 返回父级 |\n| `→` / `Space` | 展开 / 切换 |\n| `Enter` | 编辑叶子节点 / 展开容器 |\n| `N` / `Insert` | 添加新节点 |\n| `Delete` | 删除当前节点 |\n| `Ctrl+S` | 保存 |\n| `Ctrl+F` / `/` | 搜索 |\n| `Ctrl+Z` | 撤销 |\n| `Ctrl+Y` | 重做 |\n| `F1` | 帮助 |\n| `q` | 退出（有未保存更改时提示）|\n\n---\n\n## 命令模式\n\n专为 **AI agents** 设计，以最小的 token 使用量读取和写入 JSON。\n\n### 读取\n\n```bash\njzen get .key file.json              # 获取路径处的值\njzen get '.servers[0].host' file.json\njzen keys . file.json                # 列出所有顶层键\njzen len .tags file.json             # 数组 / 对象长度\njzen type .count file.json           # 类型名称: string|number|boolean|null|object|array\njzen exists .key file.json           # 退出 0=存在, 2=未找到\njzen schema file.json                # 推断结构（无值）\njzen check file.json                 # 验证；错误到 stderr\n```\n\n### 写入\n\n```bash\njzen set .name '\"Bob\"' file.json     # 设置值\njzen del .legacy file.json           # 删除键\njzen add .tags '\"go\"' file.json      # 追加到数组\njzen mv .oldKey .newKey file.json    # 重命名键\n\n# 批量（JSON Patch RFC 6902）— 一次调用，原子操作\njzen patch '[\n  {\"op\": \"replace\", \"path\": \".name\",    \"value\": \"Bob\"},\n  {\"op\": \"add\",     \"path\": \".tags/-\",  \"value\": \"go\"},\n  {\"op\": \"remove\",  \"path\": \".legacy\"}\n]' file.json\n```\n\n### 格式化 / 修复\n\n```bash\njzen fmt file.json                   # 原地美化格式化\njzen fix --strip-comments file.json  # 自动修复 JSONC、尾随逗号等\njzen fix --dry-run file.json         # 预览修复而不写入\njzen minify file.json                # 压缩 JSON\njzen diff old.json new.json          # 结构化 diff\n```\n\n### 检查 / 转换\n\n```bash\njzen tree file.json                  # 显示为缩进树\njzen tree -e file.json               # 展开所有节点\njzen tree -p .servers file.json      # 子路径的树视图\njzen query '.users[0]' file.json     # get 的别名，带路径过滤语义\njzen validate schema.json file.json  # 根据 JSON Schema 验证\njzen convert yaml file.json          # 转换为 YAML\njzen convert toml file.json          # 转换为 TOML\n```\n\n### 发现\n\n```bash\njzen commands                        # 列出所有可用命令\njzen explain get                     # 特定命令的详细帮助\njzen completions bash                # 生成 shell 补全脚本\njzen completions zsh\njzen completions fish\n```\n\n### 全局选项\n\n| 选项 | 描述 |\n|------|------|\n| `--json` | 将所有输出包装为 `{\"ok\":...,\"value\":...}` |\n| `--lang \u003clang\u003e` | 输出语言: `en`, `zh-CN`, `zh-TW` |\n| `--quiet` | 抑制信息输出 |\n| `-h, --help` | 显示帮助 |\n| `-V, --version` | 显示版本 |\n\n### 退出码\n\n| 码 | 含义 |\n|----|------|\n| 0 | 成功 |\n| 1 | 一般错误 |\n| 2 | 路径未找到 |\n| 3 | 类型不匹配 |\n\n---\n\n## AI Agents 为什么选择 Jzen？\n\n| 传统方式 | jzen 命令模式 |\n|----------|---------------|\n| 将整个文件读入上下文 | `get .key` → 仅目标值 |\n| 修改后重写整个文件 | `set .key val` → 返回 `ok` |\n| Agent 手动解析 JSON | 路径寻址处理导航 |\n| Agent 格式错误时重试 | `fix` 自动修复错误 |\n| 多次往返 | `patch` 一次调用批量修改 |\n\n### 示例：配置 Claude Code MCP server\n\n```bash\n# 1. 检查文件结构而不读取值\njzen schema ~/.claude/settings.json\n\n# 2. 检查 server 是否存在\njzen exists .mcpServers.github ~/.claude/settings.json\n\n# 3. 只读取需要的具体值\njzen get .mcpServers.github.command ~/.claude/settings.json\n\n# 4. 更新单个字段\njzen set .mcpServers.github.env.TOKEN '\"ghp_xxxx\"' ~/.claude/settings.json\n\n# 5. 批量更新（一次调用）\njzen patch '[\n  {\"op\": \"replace\", \"path\": \".defaultMode\", \"value\": \"acceptEdits\"},\n  {\"op\": \"add\",     \"path\": \".mcpServers.github.enabled\", \"value\": true}\n]' ~/.claude/settings.json\n```\n\n### 示例：配置 OpenClaw agent\n\n```bash\n# 1. 检查配置结构\njzen tree ~/.config/openclaw/agent.json\n\n# 2. 更新模型配置\njzen set .model.provider '\"openai\"' ~/.config/openclaw/agent.json\njzen set .model.name '\"gpt-4o\"' ~/.config/openclaw/agent.json\n\n# 3. 添加新的 MCP server\njzen set .mcpServers.github '{\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"]\n}' ~/.config/openclaw/agent.json\n\n# 4. 修复和格式化后再保存\njzen fix --strip-comments ~/.config/openclaw/agent.json\n```\n\n---\n\n## 自动修复功能\n\n`jzen fix` 修复最常见的 JSON 格式错误：\n\n| 错误 | 示例 | 修复 |\n|------|------|------|\n| 尾随逗号 | `{\"a\": 1,}` | 移除 |\n| 单引号 | `{'key': 'val'}` | 替换为双引号 |\n| 未加引号的键 | `{key: \"val\"}` | 添加引号 |\n| 缺失逗号 | `{\"a\": 1 \"b\": 2}` | 插入逗号 |\n| 行注释 | `// comment` | 剥离 |\n| 块注释 | `/* comment */` | 剥离 |\n| Python 字面量 | `True`, `False`, `None` | 替换为 JSON 等价物 |\n| BOM | 领先的 `\\uFEFF` | 剥离 |\n\n---\n\n## 路径语法\n\n使用类 jq 的路径语法：\n\n```\n.                      # 根\n.key                   # 对象字段\n.key.nested            # 嵌套字段\n.array[0]              # 数组索引\n.array[-1]             # 最后一个元素\n.key.array[2].field    # 深度路径\n```\n\n---\n\n## Stdin / 管道支持\n\n所有读取命令在没有文件参数时接受来自 stdin 的 JSON：\n\n```bash\ncat config.json | jzen get .name\necho '{\"a\":1}' | jzen schema\n```\n\n---\n\n## 从源码构建\n\n```bash\ngit clone https://github.com/caoergou/jzen\ncd jzen\ncargo build --release\n./target/release/jzen --version\n```\n\n---\n\n## Shell 补全\n\n为 `jzen` 命令和选项启用 tab 补全。\n\n### Bash\n\n```bash\n# 写入 bash-completion 目录（推荐）\njzen completions bash \u003e ~/.local/share/bash-completion/completions/jzen\n\n# 或添加到自定义目录并 source\njzen completions bash \u003e ~/.bash_completion.d/jzen\necho 'source ~/.bash_completion.d/jzen' \u003e\u003e ~/.bashrc\n```\n\n### Zsh\n\n```bash\n# 写入 fpath 目录\nmkdir -p ~/.zfunc\njzen completions zsh \u003e ~/.zfunc/_jzen\n\n# 添加到 .zshrc（在任何 compinit 调用之前）：\n# fpath=(~/.zfunc $fpath)\n\n# 重载 shell\nexec zsh\n```\n\n### 其他 Shell\n\n也支持 Fish、PowerShell 和 Elvish。详见 [CLI_SPEC.md](CLI_SPEC.md#completions-shell)。\n\n---\n\n## 路线图\n\n### v1.x — ✅ 完成（完善和分发）\n\n- [x] Shell 补全 (bash/zsh/fish/powershell/elvish)\n- [x] `diff --json` 结构化输出模式\n- [x] TOML 转换 (`jzen convert toml`)\n- [x] 完整 JSON Schema 验证 (`type`, `required`, `properties`, `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`, `maxItems`, `items`, `enum`)\n- [x] 包管理器分发: Homebrew, apt/deb, rpm\n- [x] YAML 转换 (`jzen convert yaml`)\n- [x] TUI 模式文件监控\n\n### v2.x — 强力功能（进行中）\n\n- [ ] 交互式 shell 模式 (`jzen shell`) — 持久 REPL，无需重新打开文件即可批量编辑\n- [ ] 保存时保留 JSONC 注释（基于 CST；当前写入时剥离）\n- [ ] TUI 鼠标支持\n- [ ] 大文件优化（\u003e 1 MB 文件的虚拟滚动）\n\n### v3.x — 长期\n\n- [ ] TUI 多文件标签\n- [ ] JSON Pointer (RFC 6901) 作为替代路径语法\n\n---\n\n## 许可证\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaoergou%2Fjzen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaoergou%2Fjzen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaoergou%2Fjzen/lists"}