jiq

jiq — 给 JSON 数据查询装上「实时滤镜」的 Rust TUI 工具

在日常开发和数据处理工作中，JSON 无处不在。从 API 返回的复杂嵌套结构，到日志文件里的半结构化输出，如何快速从海量 JSON 中捞出你需要的那一小块数据？传统的做法是写 Python 脚本或者用 jq 命令行，但每次修改查询条件都要重新运行，结果还不能实时预览——效率低下且体验割裂。

jiq 正是为解决这一痛点而生：它是一个交互式 JSON 查询工具，在终端里提供了一个实时刷新的 TUI 界面，用户在输入框中敲入 jq 查询表达式，左侧的结果区域会实时显示过滤后的 JSON 输出，无需反复运行命令。结合上下文感知的自动补全、AI 辅助查询建议，以及 Vim 风格的键盘操作，jiq 将 JSON 数据探索变成了一种流畅的交互体验。

图1：jiq 的 AI 助手功能——输入自然语言描述查询需求，AI 自动生成 jq 查询语句并实时展示结果

---

背景：从命令行 jq 到交互式查询的演进

jq 是 Linux 命令行中处理 JSON 的瑞士军刀，功能强大且语法表达力丰富，但它的交互体验始终停留在批处理模式：用户需要反复修改表达式 → 运行 → 查看结果的循环，调试一个复杂查询往往要尝试十余次。对于不熟悉 jq 语法的新手来说，光是理解 select(.age > 30) | .name 这样的管道表达式就要花不少时间。

jiq 的作者 bellicose100xp 从 2025 年 11 月开始开发这个项目，核心思路是将 jq 的查询能力与现代化 TUI（终端用户界面）框架结合，在保留 jq 全部语法表达能力的同时，叠加实时预览、自动补全和 AI 辅助三重交互增强。项目当前版本为 3.32.2（2026 年 6 月持续活跃更新），采用 Rust 语言实现，以保证终端渲染的高性能和跨平台兼容性。

从 GitHub 的提交记录来看，项目采用了非常规范的模块化开发模式：每个功能都是一个独立的子模块（ai、autocomplete、history、snippets 等），每个子模块内部进一步拆分为 state/events/render 三层结构，遵循 Rust 2018+ 的无 mod.rs 命名约定。这种架构设计让项目的代码量虽然超过 2 万行，但组织依然清晰，单元测试和快照测试覆盖率极高。

---

核心功能：不止是 jq 的图形化前端

实时查询执行

jiq 最基础也是最核心的功能是实时 jq 查询。用户无需手动触发执行——只要在输入框中修改表达式，结果面板立即刷新。这种「所见即所得」的反馈机制让调试查询变得极为高效，特别适合处理复杂的嵌套 JSON 结构，例如从 API 响应中提取多层级的数组字段。jiq 底层通过 tokio 异步任务执行 jq 进程，配合防抖（debounce）机制避免在快速输入时产生过多无意义的查询调用。

上下文感知自动补全

jiq 的自动补全系统远比简单的关键词提示更智能。它在用户输入时会分析当前光标位置周围的 JSON Schema 上下文，推荐符合条件的字段路径、函数名和值候选项。例如，当用户在数组迭代器内部时，会优先展示当前数组元素可用的字段；当光标在比较表达式中时，会列出该字段所有出现过的值作为候选。整个补全系统由 autocomplete/ 子模块完整实现，包含 brace_tracker（括号追踪）、json_navigator（JSON 导航）、value_collector（值收集）等专门组件。

图2：jiq 的代码片段库功能——保存常用查询、一键复用，支持模糊搜索

AI 助手：自然语言到 jq 的翻译

jiq 集成了一个完整的 AI 辅助查询系统（ai/ 子模块），支持多种 AI Provider：OpenAI（GPT-4o）、Anthropic（Claude）、Google Gemini 和 AWS Bedrock。当用户按下 Ctrl+A 时，AI 助手弹出，用户可以用自然语言描述想要的查询结果，AI 会生成对应的 jq 表达式并直接展示过滤效果。如果当前查询存在语法错误，AI 还能根据错误信息提供修复建议。

ai/ 模块内部实现了完整的异步流式响应处理（基于 reqwest + tokio），包括 SSE（Server-Sent Events）解析和请求取消机制。AI 请求会携带当前 JSON 数据的 Schema 信息和查询上下文，确保生成的 jq 表达式与实际数据结构匹配。

Vim 操作与鼠标支持

对于习惯 Vim 的开发者，jiq 提供了完整的 Vim 键位映射：Normal/Insert/Operator-pending 三种模式，支持动作（motions）、操作符（operators）和文本对象（text objects）。与此同时，项目也支持鼠标点击、滚轮滚动和拖拽选择，照顾不熟悉 Vim 的用户。

其他实用功能

• 查询历史：可搜索的历史记录，保存所有成功执行的查询
• 代码片段库：保存/命名/复用常用查询，支持模糊匹配
• 结果搜索：在查询结果中高亮/导航匹配项（Shift+Tab 切换焦点）
• 剪贴板集成：自动检测剪贴板中的 JSON 数据，支持一键导入和结果导出
• 语法高亮：jq 查询和 JSON 输出均支持彩色高亮
• 多主题：支持亮色/暗色主题切换，可跟随终端背景自动适应

---

技术架构：Rust + Ratatui 的模块化 TUI 设计

jiq 的技术选型非常明确：Rust 作为系统编程语言，Ratatui 作为 TUI 渲染框架（Python 著名库 textual 的 Rust 版本）。整个项目约有 200+ 个 Rust 源文件，按照功能边界拆分为 20+ 个顶级模块，模块之间通过 App 状态对象进行集成。

图3：jiq 的结果搜索功能——在大量查询结果中快速定位目标内容

核心模块结构

模块	职责
query/	jq 查询执行：异步执行 jq 进程、防抖、错误增强
ai/	AI 助手：多 Provider 兼容、流式响应、补全建议
autocomplete/	自动补全：JSON Schema 感知、字段/值推荐
app/	主应用状态：事件分发、焦点管理、渲染协调
results/	结果面板渲染：语法高亮、滚动、错误展示
history/	查询历史：持久化存储、模糊搜索
snippets/	代码片段库：CRUD、模糊匹配
clipboard/	剪贴板：OSC52 协议（终端复制）、系统剪贴板
editor/	Vim 编辑器模拟：多模式、TextObject
search/	结果内搜索：高亮匹配项、导航

测试覆盖

jiq 的代码质量在开源 CLI 工具中属于顶级水准。项目中大量使用快照测试（Snapshot Testing），通过 cargo-insta 库保存 UI 渲染快照，任何 UI 改动都会触发测试失败，确保视觉一致性。根目录下 .github/workflows/ci.yml 配置了完整的 CI 流程，包括 Rust 工具链安装、jq 1.8.1 安装和覆盖率报告生成。

AI Provider 实现

jiq 的 AI 模块支持四种主流 LLM Provider，每种都封装了独立的异步 HTTP 客户端（async_openai.rs、async_anthropic.rs、async_gemini.rs、async_bedrock.rs），统一通过 reqwest（rustls-tls 版本，无 OpenSSL 依赖）发起 SSE 流式请求。其中 AWS Bedrock 使用 AWS SDK 实现，支持 IAM 认证，是目前开源项目中较为少见的特性。

---

上手体验：零学习成本的 JSON 探索

安装方式

jiq 提供了四种安装途径，覆盖了主流场景：

1. 一键安装脚本（macOS/Linux）：curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bellicose100xp/jiq/releases/latest/download/jiq-installer.sh | sh
2. Homebrew：brew install bellicose100xp/tap/jiq
3. Cargo：cargo install jiq
4. 手动下载：从 GitHub Releases 页面下载预编译二进制

唯一的前提依赖是 jq >= 1.8.1（jiq 调用 jq 执行实际查询，本身只是前端界面）。

使用场景

# 从文件查询
jiq data.json

# 从 stdin 管道输入
cat data.json | jiq

# 实时监控 API 响应
curl https://api.example.com/data | jiq

# 自动检测剪贴板中的 JSON
jiq --clipboard

jiq 启动后会展示一个分屏界面：上半部分是 jq 表达式输入框（带语法高亮），下半部分是实时结果输出。输入框底部会动态显示自动补全建议，结果区域支持滚动和高亮导航。

---

局限与争议

尽管 jiq 功能丰富，但也存在一些值得注意的局限：

1. 外部 jq 依赖：jiq 本身不包含 jq 引擎，而是调用系统中的 jq 二进制。这在某些受限环境中（如没有 jq 的 Docker 镜像）会成为障碍。理想情况下，jiq 可以考虑内置一个轻量 jq 实现（如 jq 的 Rust 绑定）作为备选。

2. 纯终端界面：jiq 没有 Web UI 或 API 接口，不适合作为服务组件嵌入到数据管道中。如果需要在程序中调用 JSON 查询能力，只能通过 CLI 子进程方式调用。

3. 不支持 JSON Lines（JSONL）：jiq 主要面向标准 JSON 对象，对于流式的 JSONL 格式支持有限，这在处理日志流等场景时可能不适用。

4. AI 功能需额外配置：AI 助手需要用户自行配置 OpenAI/Anthropic 等 API Key，且部分 Provider（如 Bedrock）需要额外的 AWS 凭证配置，学习成本较高。

---

行业意义与增长趋势

jiq 虽然是一个相对小众的开发工具（319 stars），但在 Rust TUI 开源社区中具有代表性意义。它展示了如何用 Rust 构建高质量的终端交互应用，在快照测试驱动的 UI 开发方面树立了良好范例。随着 LLM 在开发工具中的深度集成趋势，jiq 的 AI 辅助查询功能也代表了未来 CLI 工具的一个发展方向——从被动接受用户指令，到主动理解用户意图并提供智能化建议。

项目目前保持活跃维护（2026 年 6 月仍有提交），GitHub Actions CI 全绿，crates.io 版本持续迭代，展示了良好的工程成熟度。对于需要频繁处理 JSON 数据的开发者（API 测试、数据调试、日志分析等），jiq 是一款值得加入工具链的效率利器。