Agentic Jackal: Live Execution and Semantic Value Grounding for Text-to-JQL

本文提出了首个基于实时执行的大规模文本转 JQL 基准"Jackal"及其配套的智能体框架"Agentic Jackal"，通过结合 Jira MCP 服务器执行与语义检索工具 JiraAnchor，显著提升了大语言模型在解析模糊字段引用和实例特定值方面的准确率，并揭示了当前该任务的主要瓶颈在于语义歧义而非值解析。

要点

这篇论文讲述了一个关于如何让电脑更聪明地听懂人类语言，并去“翻找”特定数据库的故事。

我们可以把这篇论文想象成是在解决一个**“翻译官”和“图书管理员”**之间的配合问题。

1. 背景：为什么这很难？（翻译官的困境）

想象一下，你是一家大公司的老板，你想查一下公司里所有关于"2023 年那个红色项目”的“未完成”任务。

• 你的语言（自然语言）： “帮我看看 2023 年红色项目里还没做完的事。”
• 电脑的语言（JQL）： 这是一种非常严谨、像代码一样的查询语言。它必须精确地写成：project = "RedProject" AND status != "Done" AND created >= "2023-01-01"。

问题出在哪？
以前的电脑（大语言模型）就像是一个才华横溢但有点“死脑筋”的翻译官。

• 如果你说得很清楚（比如直接说“红色项目”），它能翻译得很准。
• 但如果你说得稍微模糊一点（比如“那个红色的项目”），或者你提到的版本号（比如"6.5 版”）在电脑里其实叫"6.5.0 Beta"，这个翻译官就会瞎猜。
• 最糟糕的是，翻译官没有眼睛。它不知道公司里到底有哪些项目、哪些版本是真实存在的。它可能会编造一个不存在的"6.5.1 版”，导致查出来的结果是空的，但它自己还以为自己翻译对了。

2. 解决方案：Agentic Jackal（聪明的“侦探 + 图书管理员”组合）

为了解决这个问题，作者们发明了一个叫 Agentic Jackal 的新系统。我们可以把它想象成给那个“翻译官”配了两个超级助手：

助手 A：Jira Search（活体“试错”侦探）

• 以前： 翻译官写完翻译稿，直接交给你。如果错了，你才发现。
• 现在： 翻译官写完翻译稿后，先自己跑一遍。
  • 如果查出来有结果，侦探说：“老板，这个翻译好像是对的！”
  • 如果查出来是空的，侦探说：“老板，查不到东西，可能是‘红色项目’这个名字不对，或者‘未完成’的状态定义错了，我再去改改。”
  • 如果报错，侦探说：“语法错了，我马上改。”
• 比喻： 就像你写代码时，先自己运行一下，报错了就改，而不是等用户来投诉。

助手 B：JiraAnchor（精准的“图书管理员”）

• 以前： 翻译官不知道公司里到底有哪些“组件”或“版本”。
• 现在： 当翻译官听到“数据结构的任务”时，它不知道这对应哪个具体的组件名。这时候，图书管理员（JiraAnchor） 就出场了。
  • 它会立刻去公司的真实数据库里搜索：“谁的名字跟‘数据结构’最像？”
  • 它发现真实名字是"Core: Containers and Algorithms"。
  • 它把这个确切的名字告诉翻译官，翻译官再把它写进查询语句里。
• 比喻： 就像你去图书馆找书，只说“找那本关于恐龙的书”，图书管理员不会瞎猜，而是直接去书架上把《恐龙大百科》拿给你，确保你拿到的就是那本真书。

3. 他们做了什么实验？（大考）

作者们建立了一个巨大的**“考试系统”**（叫 Jackal 基准），里面有 10 万道题目，都是把“人话”翻译成“电脑话”。他们找了 9 个最顶尖的 AI 模型来考试。

• 单干模式（Naive）： 让 AI 自己瞎猜，不许用助手。
  • 结果： 遇到稍微难一点的题目（比如话没说全），正确率只有 43% 左右。就像让一个没带地图的导游带路，很容易迷路。
• 特工模式（Agentic Jackal）： 让 AI 带上“侦探”和“图书管理员”。
  • 结果： 正确率提升到了 64% 左右。对于最难猜的题目，提升更是明显。
  • 特别亮点： 在“组件”这种需要精确名称的领域，没有图书管理员时，正确率只有 16.9%（几乎全错）；有了图书管理员，正确率飙升到 66.2%。

4. 发现了什么新问题？（为什么还没完美？）

虽然进步很大，但作者发现，剩下的错误不是因为“找不到书”，而是因为“话太含糊”。

• 例子： 用户说“找 Bug"。
  • 是指“任务类型是 Bug"？
  • 还是指“在‘摘要’里搜索包含'bug'这个词的任务”？
• 结论： 这种语义上的歧义（到底想表达什么），是目前的 AI 和工具都很难解决的。就像你问朋友“我要那个红色的”，朋友不知道你是指“红色的苹果”还是“红色的车”。这时候，工具再厉害也没用，需要人来澄清。

5. 代价是什么？（时间 vs. 金钱）

• 代价： 这种“先试错、再查书”的方法，比直接瞎猜要慢很多（大概慢了 7 倍），用的“算力”（Token）也多了很多（大概 15 倍）。
• 权衡： 如果你只是随便问问，直接猜可能就够了；但如果你要查重要的商业数据，多花点时间让 AI 多跑几遍、多查几次，确保结果绝对准确，是非常值得的。

总结

这篇论文的核心思想是：不要指望 AI 能一次性猜对所有的复杂指令。

最好的办法是给 AI 装上**“手脚”（让它能去数据库里真正跑一下查询）和“眼睛”**（让它能去查真实的列表）。虽然这样做会让它变慢一点，但它能极大地减少“瞎编乱造”的错误，特别是在处理那些只有公司内部才知道的具体名称（如版本号、组件名）时，效果立竿见影。

这就好比：与其让一个天才翻译官在房间里凭空想象，不如让他拿着对讲机，一边翻译一边问现场的工作人员：“你们这儿真的有这个零件吗？”

技术摘要

这是一份关于论文《Agentic Jackal: Live Execution and Semantic Value Grounding for Text-to-JQL》的详细技术总结。

1. 研究背景与问题定义 (Problem)

核心挑战：
将自然语言（NL）转换为 Jira 查询语言（JQL）是一项极具挑战性的任务，主要面临以下三大障碍：

1. 模糊的字段引用： 用户自然语言描述往往无法直接对应到具体的 JQL 字段（例如，“问题”是指 issuetype 还是文本搜索 summary？）。
2. 实例特定的分类值： Jira 实例中的分类字段（如组件 component、修复版本 fixVersion、标签 labels）包含成千上万个实例特定的值。大语言模型（LLM）无法仅凭训练数据知道某个特定实例中实际存在哪些值（例如，用户说"6.5"，实际实例中可能是"6.5.0"或"6.5.0 Beta1"）。
3. 复杂的布尔逻辑与验证缺失： 单次生成的 LLM 无法验证生成的查询是否有效，也无法在查询返回空结果或报错时进行自我修正。

现有局限：

• 现有的单轮（Single-pass）LLM 方法在字面翻译任务上表现尚可（>90%），但在处理 paraphrased（改写）或描述模糊的查询时，准确率急剧下降至 30% 以下。
• 缺乏基于**实时执行（Execution-based）**的开源基准测试来评估 Text-to-JQL 任务。
• 缺乏机制让模型在生成过程中发现并纠正实例中不存在的分类值。

2. 方法论 (Methodology)

为了解决上述问题，作者提出了 Agentic Jackal，这是一个基于工具增强（Tool-augmented）的多步智能体框架，并引入了一个新的语义检索工具 JiraAnchor。

2.1 核心架构：Agentic Jackal

该智能体基于 Jira MCP (Model Context Protocol) 服务器构建，采用迭代式工作流：

1. 生成与执行： 智能体根据自然语言请求生成候选 JQL 查询。
2. 实时反馈循环： 通过 Jira Search 工具在真实的 Jira 实例上执行查询。
3. 信号驱动修正： 智能体根据执行结果接收三种信号进行针对性修正：
   • 非空结果集： 查询有效，可能直接返回。
   • 零结果集： 提示过滤条件过严或值不匹配，需放宽条件或修正值。
   • 错误信息： 提示语法错误或字段不存在，需修正语法。
4. 迭代终止： 当智能体决定不再调用工具并输出最终答案，或达到最大迭代次数（25 步）时终止。

2.2 关键组件：JiraAnchor

为了解决“实例特定值”的歧义问题，作者开发了 JiraAnchor，这是一个独立的语义检索工具（非 MCP 原生工具）：

• 功能： 将自然语言中的分类值提及（如"6.5"）映射到 Jira 实例中实际存在的标准值（如"6.5.0 Beta1"）。
• 机制：
  1. 通过 REST API 获取指定字段在特定项目下的所有唯一值。
  2. 利用 基于嵌入（Embedding）的相似度搜索（以及可选的 grep/正则匹配）计算用户输入与候选值的相似度。
  3. 返回 Top-K 匹配项供智能体选择。
• 设计原则： 将“值 grounding"（由 JiraAnchor 处理）与“查询构建”（由 LLM 处理）解耦，确保模型不猜测不存在的值。

2.3 基准测试：Jackal-1K

• 基于 Jackal 基准（包含 10 万个验证过的 NL-JQL 对，运行在拥有 20 万+ 工单的真实 Jira 实例上）。
• 构建了 Jackal-1K 评估集：1000 个分层采样的查询，包含四种自然语言变体：
  • Semantically Exact（字面翻译）
  • Long NL（多句详细解释）
  • Short NL（简短意图描述，最具挑战性）
  • Semantically Similar（完全避免 JQL 术语的改写）

3. 主要贡献 (Key Contributions)

1. Agentic Jackal 框架： 首个面向企业级 Text-to-JQL 的开源智能体基线。它结合了实时执行反馈和语义值检索，证明了多步迭代优于单步生成。
2. JiraAnchor 工具： 提出了一种新颖的语义字段值检索方法，专门解决实例特定分类值的歧义问题，显著提升了涉及组件和版本字段的查询准确率。
3. 错误分类学（Error Taxonomy）： 对失败案例进行了详细分析，识别出六大类错误，并指出语义解释歧义（如问题类型歧义、文本字段选择、版本混淆）是主要失败原因，而非值解析错误。
4. 开源资源： 公开了基准测试数据、所有智能体交互日志（transcripts）及评估代码。

4. 实验结果 (Results)

研究在 Jackal-1K 上评估了 9 个前沿 LLM（包括 GPT-5, Claude, Gemini, Pixtral 等）。

4.1 整体执行准确率 (Experiment 1)

• 对比： 单轮生成（Naive）vs. 智能体方法（Agentic）。
• 结果： 9 个模型中有 7 个 得到提升。
  • 平均执行准确率从 62.5% 提升至 64.4%。
  • 在最具挑战性的 Short NL 变体上，相对提升达到 9.0%（绝对提升 3.9%）。
  • 表现最好的模型是 Gemini 3 Flash，整体准确率从 62.8% 提升至 71.0%。

4.2 JiraAnchor 消融实验 (Experiment 2)

• 目标： 隔离 JiraAnchor 对分类字段值解析的贡献。
• 结果：
  • 整体准确率从 48.7% 大幅提升至 71.7%。
  • 组件（Component）字段： 准确率从 16.9% 激增至 66.2%（提升 49.3%）。这是因为组件命名通常非标准化，模型无法猜测，必须依赖实时检索。
  • 版本（Version）字段： 准确率也有显著提升（如 fixVersion 从 63.1% 升至 73.0%）。
  • 所有 9 个模型均表现出正向收益。

4.3 错误分析

• 主要失败模式： 在 Short NL 和 Semantically Similar 变体中，58%-68% 的错误源于语义解释歧义（Issue Type Interpretation, Text Field Selection, Version Confusion），而非值解析失败。
• 结论： 工具（JiraAnchor）能有效解决值匹配问题，但自然语言本身的模糊性（如用户说“版本 6.5"未指明是修复版本还是受影响版本）是当前的主要瓶颈，需要用户澄清或更丰富的上下文。

4.4 成本分析

• 延迟与 Token： 智能体方法相比单轮生成，平均延迟增加约 7 倍（从 4.8s 到 32.4s），Token 消耗增加约 15 倍。
• JiraAnchor 开销： 引入 JiraAnchor 平均增加 1 次工具调用，延迟增加约 34 秒（主要用于 API 获取值和计算相似度），但在交互式场景中是可接受的。

5. 意义与展望 (Significance)

• 范式转变： 证明了在 Text-to-Structured-Query 任务中，“执行即验证”（Execution-as-Verification） 和 实时值 grounding 是解决企业级复杂查询的关键。单轮 LLM 无法处理实例特定的动态数据。
• 企业应用价值： 为 Jira 等项目管理平台提供了更可靠、更准确的自然语言搜索接口，降低了非专家用户的使用门槛。
• 未来方向：
  • 针对语义歧义（如字段选择、版本类型混淆）开发用户澄清机制（User Clarification）。
  • 优化 JiraAnchor 的检索策略（结合结构化启发式规则与嵌入相似度），减少过匹配（Overmatching）。
  • 探索混合策略：对清晰查询使用低成本单轮生成，对模糊查询触发智能体迭代。

总结：
Agentic Jackal 通过引入实时执行反馈循环和专门的语义检索工具，成功解决了 Text-to-JQL 中实例值不可知和查询无法验证的核心痛点。虽然它显著提高了准确率（特别是针对模糊查询和复杂分类字段），但也揭示了自然语言语义歧义仍是当前技术的主要瓶颈，未来的突破点在于结合工具能力与用户交互澄清机制。