KechuAI

mq：把 jq 那套查询语法搬到 Markdown 上

Markdown
Rust
命令行
开源工具
LLM
2026/9/29
·

阅读时间: 大约 8 分钟

mq：把 jq 那套查询语法搬到 Markdown 上

mq 官方演示动图：在终端里用类 jq 表达式查询 Markdown

mq 是开发者 harehare（Takahiro Sato）开源的命令行工具（MIT 协议，Rust + TypeScript monorepo，Rust 占 88.8%），口号是”Query. Filter. Transform Markdown.”。它把处理 JSON 时人手一个的 jq 那套思路，搬到了 Markdown 上——不写正则、不写临时脚本，用类 jq 表达式查询文档结构。据 Koala 项目库点评，在 LLM 时代大量内容需要先切分、过滤再喂给模型，一个可组合、可脚本化的 Markdown 处理器比手写解析高效得多。本文基于官方 README 与 mqlang.org 文档梳理。

一、为什么是 Markdown

官方开篇就强调一个定位：Structural, not textual（看结构，不看文本）。mq 的查询走的是 Markdown 的 AST，匹配的是标题、列表、表格、代码块这些节点，而不是在原始文本上做字符串匹配。这让它天然避免了正则提取标题/代码块时的脆弱。

目标场景被官方明确收敛到几类：

  • LLM 工作流：处理 LLM 提示词与输出里的 Markdown；
  • LLM 输入生成：既然 Markdown 是多数大模型的主要输入格式，就生成”对模型友好的结构化 Markdown”；
  • 文档管理：跨多个文档抽取、转换、整理内容；
  • 批量处理：对一批 Markdown 施加一致的转换。

二、查询语言：选择器与管道

核心语法直接沿用 jq 的心智模型——. 取字段、管道 | 串联、select(...) 过滤。官方给出的例子很直观：

mq '.h' README.md                 # 所有标题
mq '.h(1)' README.md              # 仅 h1
mq '.h(1..3)' README.md           # h1 到 h3
mq '.code("rust")' example.md      # 仅 Rust 代码块
mq '.code | select(contains("name"))' example.md   # 含 name 的代码块
mq '.link.url' README.md          # 所有链接 URL
mq '.code.lang' documentation.md   # 各代码块语言
mq -A 'section::section("Installation")' README.md  # 按标题名取整节
mq 'csv::csv_to_markdown_table' example.csv        # CSV 转 Markdown 表

可见它既有 .h、.code、.link 这类节点选择器，也有 section::、csv:: 这类命名空间函数库。官方提供独立的 Cookbook（任务优先）与 Example Guide（选择器/函数全览）。

三、子命令与 Unix 管道哲学

mq 把”转换其他格式”也做成了可管道拼接的子命令，官方推崇 Unix 管道组合：

mq conv report.xlsx | mq '.h'                 # Excel → Markdown → 抽标题
mq conv document.docx | mq -A 'section::section("Summary")'   # Word → 取章节
mq conv slides.pdf | mq view                  # PDF → 终端预览
mq --list                                     # 列出所有内建+外部子命令

除了 CLI，它还有：交互式 REPL、VSCode 扩展与 LSP（方便开发自定义函数）、一个实验性调试器 mq-dbg（交互式单步排查查询）。扩展机制很 Unix——往 ~/.local/bin/ 或 PATH 里放一个以 mq- 开头的可执行文件，就成了一个新的子命令，无需改动核心二进制。

四、生态与分发

  • 安装：brew install mq、yay -S mq-bin、cargo install mq-run、Docker（ghcr.io/harehare/mq），或 curl -sSL https://mqlang.org/install.sh | bash；
  • CI：官方 GitHub Action harehare/setup-mq@v1；
  • 托管 API：无需本地安装即可 curl --data-binary @doc.md https://api.mqlang.org/.h1；
  • 语言绑定：Elixir、Python、Ruby、Java、Go；
  • 编辑器集成：VSCode、Chrome、Neovim、Zed、JetBrains、Obsidian、Helix 均有对应支持。

版本活跃度不低：发布页显示已发 83 个 release，最新 v0.9.2。官方性能口径是”sub-millisecond execution（亚毫秒执行）“、单原生二进制、无运行时依赖。

五、口径与局限：官方自己标注的边界

  1. 仍在活跃开发中：README 顶部用 Important 框明确写着”This project is under active development”——版本停在 0.9.x，尚未到 1.0，语法与行为可能仍会变动。
  2. 性能数字是官方自称：“亚毫秒执行”来自官网首页宣传文案，并非在公开基准集上、由第三方复测的结果；大文档、深 AST 的实际表现需自行验证。
  3. curl | bash 安装：一键脚本直接管道到 bash，习惯审查安装脚本的人应先下载审阅。
  4. “看结构不看文本”是双刃剑：它匹配的是 AST 节点，若你的需求是在段落正文里做模糊文本搜索、跨结构模式匹配，反而不如直接用 grep/rg——它是结构查询器，不是全文搜索引擎。
  5. 转换类子命令质量待考：conv 支持 xlsx/docx/pdf 转 Markdown，但这类”文档→Markdown”转换的保真度（表格、公式、图片）官方未给出量化指标，复杂文档需人工抽检。

六、客观分析：优势与适合人群

优势： 把结构化查询能力带给了 Markdown 这个”半结构化”格式；纯 Rust 单二进制、无运行时依赖，在 CI 和 Serverless 里都好分发；围绕 LLM 输入/输出处理的定位很准——切片、取节、抽代码块、转格式，正好是 RAG/Agent 预处理里反复出现的动作。

适合： 在 LLM 流水线里需要批量切分、过滤、重排 Markdown 的工程师；文档站维护者；想把 jq 习惯迁移到 Markdown 的命令行用户。

注意： 还在 0.x 阶段，关键脚本里若深度依赖它，要预留语法变动的升级成本；把它当结构提取器用，而不是万能文本处理器。

参考来源