query

Agent 规则

• 对于已知术语，先使用 grep -n -i -C2 "term" file | head 进行范围有限的搜索。
• 如果不知道确切措辞，或普通搜索返回过多匹配项，请使用 query。
• 对于单个事实，使用 -k 1 或 -k 2。添加 --language <lang> 以匹配相关词形。
• 只有在预计会对同一文件进行多次查询时，才使用 --emit-index 构建索引。

查询文档

搜索提取后的 Markdown 或文本文件，并返回最相关的行范围。该命令读取本地文件；不会解析 PDF。

相关技能

• pdf-to-markdown — 将 PDF 转换为结构化 Markdown。
• pdf-to-text — 将 PDF 转换为纯文本，同时保留分栏和间距。

用法

将 SKILL_DIR 设置为包含此文件的目录的绝对路径。在以下命令中使用 $SKILL_DIR/bin/query。

该包装脚本首次运行时会从 Nutrient 的 CDN 下载 CLI，并将其存储在 ~/.local/share/nutrient/cli/ 中。它每六小时检查一次更新。

$SKILL_DIR/bin/query text INPUT.md "your question" [-k N] [-e N]

• INPUT.md — 提取后的 Markdown 或文本文件，或已保存的查询索引。
• "your question" — 用于排序的词语。必要时可包含多个具体术语。
• -k N — 结果窗口的最大数量。默认值为 8；大多数问题使用 1–3。
• -e N — 周边行数。默认值为 5；使用 0 仅返回匹配行。

每个结果都以从 1 开始的 Lines A-B 范围开头。需要时可使用该范围进行有针对性的后续读取。

重用索引

如果预计会对同一文件提出多个问题，请创建索引：

$SKILL_DIR/bin/query text INPUT.md "first question" --emit-index INPUT.idx
$SKILL_DIR/bin/query text INPUT.idx "second question"

索引包含源文件的行，因此后续查询只需使用索引文件。

工作流

1. 使用 pdf-to-markdown 或 pdf-to-text 转换一次 PDF。
2. 使用较小的 -k 值运行一次有针对性的查询。
3. 根据返回的段落作答。仅在必要时读取更大的行范围。
4. 对同一文件的后续问题重用索引。

查询提示

• 使用可能出现在文档中的具体词语。
• 将相关术语放在同一个查询中，而不要运行多个范围狭窄的查询。
• 添加 --language en 或其他 ISO 语言代码，以匹配词形变化。
• 增大 -e 以获取更多上下文。只有在预计会有多个独立答案时才增大 -k。

故障排除

• No relevant matches found： 尝试使用更具体的术语、同义词或 --mode lenient。该消息不是文档内容。
• 输出为空： 检查转换后的文件是否包含文本。query 不会执行 OCR。
• 匹配效果不佳： 添加更少见的术语，或使用 --mode strict。
• 退出码非零： 阅读 stderr 并报告具体错误。常见原因包括输入文件缺失或首次运行时下载失败。
• 首次运行较慢： 包装脚本只会下载一次平台二进制文件。后续运行会使用缓存副本。

使用与许可

query 可免费使用。它在本地运行，无需账户，不会报告用量，也不会使用 Vision 页面。

使用须遵守 Nutrient PDF to Markdown 许可协议和 Nutrient 的隐私政策。再分发、OEM、嵌入式和白标用途均需与 Nutrient 另行签订协议。