jq 是命令行 JSON 处理器，已安装版本为 v1.8.1，路径为 /opt/homebrew/bin/jq。它从标准输入或文件读取 JSON，应用过滤器并输出转换后的 JSON。在 Shell 管道中处理 JSON 时，优先使用 jq，而不是自行编写脚本。
基本概念：jq 程序都是由过滤器组成，过滤器之间用 | 连接，可产生零个或多个输出。. 是恒等过滤器，原样传递输入。字段访问可写 .name，嵌套访问可写 .user.id，也可将多个过滤器串联，例如 .items | add。
数组操作：支持索引与切片，如 .[1]、.[1:3]；.[] 用于遍历所有元素；map(select(. > 2)) 可对数组做映射与筛选。
对象构造：可用 {name: .first, surname: .last} 构建新对象，用 {name, age} 简写，用 {(.key): .val} 生成计算键。
常用命令行参数：-r 输出原始字符串（不带引号）；-R 将每行作为原始字符串输入；-s 将所有输入合并为一个数组；-n 使用空输入；-c 紧凑输出（单行）；-S 对对象键排序；-e 根据输出设置退出状态（false/null 为 1）；--arg k v 绑定字符串变量；--argjson k v 绑定 JSON 变量；--slurpfile k f 将文件加载为数组变量；--rawfile k f 将文件加载为字符串变量；--tab 使用制表符缩进；--indent n 设置缩进级别。
常见模式包括：从对象数组中提取嵌套字段（.[].user.email）；重塑对象数组（[.[] | {id: .id, name: .name}]）；展平嵌套数组（[.[][]] 或 flatten）；按条件筛选（select(.status == "active")）；按正则筛选（select(.name | test("^A"))）；检查键是否存在（select(has("email"))）；统计元素数（length）；对字段求和（[.[].price] | add）；分组计数（group_by(.category) | map({key: .[0].category, count: length})）；按字段取最小/最大值（min_by(.age)）；更新字段（.version = "2.0"）；用 |= 更新嵌套字段（.config.timeout |= . + 10）；为数组元素添加字段（[.[] | . + {processed: true}]）；删除字段（del(.metadata)）。
格式转换：JSON 转 CSV（@csv）、JSON 转 TSV（@tsv）、URL 编码（@uri）、Shell 安全转义（@sh）、Base64 编码与解码（@base64、@base64d）。
多文件与变量操作：用 --arg 传入 Shell 变量并在过滤器中引用；用 --argjson 传入 JSON 值；用 -s 合并两个 JSON 文件（.[0] * .[1]）；用 reduce 与 inputs 处理多个输入。
字符串操作：支持字符串插值 "User: (.name) (age (.age))"、split/join、正则替换 gsub、trim 去空白等。
内置函数按类别包括：数组类（map、select、add、sort_by、group_by、unique_by、flatten、reverse、first、last、range、limit、nth、transpose、combinations 等）；对象类（keys、values、has、in、to_entries、from_entries、with_entries、del、pick）；字符串类（test、match、capture、scan、split、join、sub、gsub、ltrimstr、rtrimstr、trim、ascii_downcase、ascii_upcase、startswith、endswith、explode、implode）；类型类（type、length、utf8bytelength、tostring、tonumber 及各类型筛选器）；数学类（floor、ceil、round、sqrt、pow、log、exp、fabs、abs、sin、cos、atan 等）；日期类（now、todate、fromdate、strftime、strptime、gmtime、mktime 等）；路径类（path、paths、getpath、setpath、delpaths 等）；格式类（@csv、@tsv、@json、@html、@uri、@sh、@base64、@base64d、@text 等）；I/O 类（input、inputs、debug、stderr、halt、error、env、$ENV）；SQL 风格（INDEX、IN、GROUP_BY、UNIQUE_BY、JOIN）。
运算符：| 管道连接过滤器；, 产生多个输出；? 抑制错误；// 提供默认值（针对 null/false）；|= 原地更新；+= -= *= /= %= //= 算术更新；as $var 绑定变量；.. 递归下降。
错误处理：可用 ? 抑制错误（.foo.bar?）；用 try-catch 提供默认值；在脚本中用 -e 依据退出状态做条件判断。
面向智能体的建议：输出需要进入其他 Shell 命令时始终使用 -r；在条件判断中使用 -e 利用退出状态；使用 --arg/--argjson 传递 Shell 变量，避免将变量直接拼接进 jq 程序（有注入风险）；在命令间传递 JSON 时使用 -c 紧凑输出；用 -s 将多个 JSON 对象作为单个数组处理；可结合 curl -s 处理 API 响应，如 curl -s url | jq '.data'。
更多参考：references/filters.md 提供按类别组织的完整内置函数参考（含签名与示例）；references/advanced.md 涵盖 reduce、foreach、流式处理、递归处理、自定义函数和复杂数据转换等高级模式。