fx - JSON 交互式终端查看器与处理器

技能脚本入口

本技能附带三套等价包装脚本，提供友好子命令入口与安装自检，免去记忆原始参数。

macOS / Linux（bash）：

bash scripts/fx-skill.sh <subcommand> [args...]
# 查看完整用法与示例
bash scripts/fx-skill.sh help

Windows（推荐 PowerShell，功能更强）：

.\scripts\fx-skill.ps1 <subcommand> [args...]
# 若被执行策略拦截，用下面这种调用绕过：
powershell -ExecutionPolicy Bypass -File scripts\fx-skill.ps1 <subcommand> [args...]

Windows（cmd 兜底，零摩擦、无需改执行策略）：

scripts\fx-skill.cmd <subcommand> [args...]

可用子命令： view、search、transform、convert、stream、theme、vim

脚本选择规则： macOS / Linux 用 .sh；Windows 下若存在 PowerShell 就用 .ps1（推荐）；无 PowerShell 则用 .cmd。三者子命令完全一致。

脚本仅作便捷封装，最终调用系统的 fx 二进制；运行前请确保已安装对应工具（安装方式见下文各节）。三套脚本（.sh / .ps1 / .cmd）子命令完全一致：Windows 优先用 PowerShell 版 .ps1，若被执行策略或网络来源标记拦截，可用 -ExecutionPolicy Bypass 调用或用 .cmd；个别依赖 Unix 管道工具的子命令（如 gron 的 sed / fzf）在 Windows 下建议用 Git Bash 运行 .sh 版。

这是什么

fx 是一个终端 JSON 查看器和处理器（TUI），支持鼠标交互、流式处理大文件、搜索、导航和转换。它是 jq 的可视化增强版，适合探索未知结构的 JSON 数据。

GitHub: https://github.com/antonmedv/fx (20.6k ⭐)
文档: https://fx.wtf
单二进制文件，零依赖（Go 编写）

何时使用我

当用户出现以下意图时加载此技能：

"探索/查看/浏览 JSON 文件"
"交互式 JSON 查看器"、"JSON TUI"、"终端看 JSON"
"搜索 JSON 中的字段/值"
"大 JSON 文件打不开/太慢"
"fx 命令"、"用 fx 处理 JSON"
"JSON 转 YAML/CSV"、"格式转换"
"不知道 JSON 结构长什么样"

核心能力

1. 基础查看与导航

# 从文件读取
fx data.json

# 从 stdin 读取（管道）
cat data.json | fx
curl -s api.example.com | fx

# 鼠标/键盘导航：展开/折叠、上下翻页、跳转行号
# 按 `?` 查看帮助，按 `q` 退出

2. 搜索与过滤

# 交互式搜索：按 `/` 输入正则或关键词
# 按 `n`/`N` 跳转下一个/上一个匹配

# 启动时直接搜索
fx data.json -s "user.name"

# 只显示匹配路径的值
fx data.json '(.users[] | select(.age > 30))'

3. 数据转换与提取（类 jq 语法）

# 提取字段
fx data.json '.users[].name'

# 映射转换
fx data.json '(.items[] | {id, name: .title, price: .cost * 1.1})'

# 过滤数组
fx data.json '(.products[] | select(.in_stock == true))'

# 聚合统计
fx data.json '(.orders | map(.total) | add)'

4. 格式转换

# JSON -> YAML
fx data.json -o yaml

# JSON -> CSV（扁平化）
fx data.json -o csv

# JSON -> TOML
fx data.json -o toml

# 保存到文件
fx data.json -o yaml > output.yaml

5. 流式处理大文件

# 处理 GB 级 JSON Lines / NDJSON
fx huge.ndjson --stream

# 只读取前 N 行预览
fx huge.json --limit 100

6. 编程式使用（作为库）

import "github.com/antonmedv/fx/internal/api"

// 在 Go 代码中嵌入 fx 查看器
api.Run(jsonData)

常用操作速查表

| 操作 | 快捷键 / 命令 | |------|--------------| | 展开/折叠节点 | Enter / Space / 鼠标点击 | | 搜索 | / 然后输入正则 | | 下一个/上一个匹配 | n / N | | 跳转到行号 | : 输入行号 | | 复制路径 | y (yank path) | | 复制值 | Y (yank value) | | 切换原始/格式化视图 | r | | 另存为文件 | s (save) | | 退出 | q / Ctrl+C |

典型工作流示例

场景 1：探索陌生 API 响应

# 1. 先看结构
curl -s https://api.github.com/repos/antonmedv/fx | fx

# 2. 搜索关键字段
# 在 fx 里按 `/` 搜索 "stargazers_count"、"license" 等

# 3. 提取需要的字段
curl -s https://api.github.com/repos/antonmedv/fx | fx '.stargazers_count, .license.name'

场景 2：处理大型日志文件 (NDJSON)

# 流式查看，不加载全文
fx app.log.ndjson --stream

# 过滤错误级别
fx app.log.ndjson 'select(.level == "error")' --stream

场景 3：配置文件对比/合并

# 合并多个 JSON 配置
fx config1.json config2.json 'add' > merged.json

# 对比差异（配合 diff）
fx config1.json > /tmp/a.json && fx config2.json > /tmp/b.json && diff -u /tmp/a.json /tmp/b.json

进阶技巧

自定义主题

# 内置主题：dark, light, monokai, solarized
fx data.json --theme monokai

# 通过环境变量设置默认主题
export FX_THEME=monokai

Vim 模式键位

# 启用 vim 键位
fx data.json --vim

# 或永久启用
export FX_VIM=1

与其他工具组合

# fx + jq：fx 交互探索，jq 批量处理
fx data.json '(.items[] | select(.active))' | jq -c '.'

# fx + fzf：模糊搜索键名
fx data.json 'paths(scalars) as $p | {"path": $p, "value": getpath($p)}' | fzf

# fx + yq：跨格式转换
fx data.json -o yaml | yq -P '.key'

安装方式

# macOS (Homebrew)
brew install fx

# Linux (二进制下载)
curl -Ls https://fx.wtf/install.sh | sh

# Go 安装
go install github.com/antonmedv/fx@latest

# npm (Node 版本)
npm install -g fxjs

# Docker
docker run --rm -i ghcr.io/antonmedv/fx < data.json

故障排查

| 问题 | 解决方案 | |------|----------| | "command not found: fx" | 检查 PATH，或用完整路径 ~/go/bin/fx | | 大文件卡死 | 加 --stream 或 --limit N | | 终端显示乱码 | 确保终端支持 UTF-8，尝试 --theme light | | 搜索不生效 | 确认用 / 进入搜索模式，支持正则表达式 | | 无法退出 | 按 q 或 Ctrl+C，极端情况 Ctrl+\ 强制退出 |