natural-language-queries

自然语言查询

概述

Happy Platform MCP 5.1 会将一组范围有限的自然语言短语转换为 ServiceNow 编码条件。对于以下经过解析器验证的原子模式，请使用 SN-Natural-Language-Search。如果需要精确运算符、多个分支、排除项、特定字段的文本处理行为或确定性排序，请使用 SN-Query-Table。

权威测试样例位于 contracts/happy-platform-mcp-5.1.0-natural-language.json，可使用 npm run contract:nl-check 与同级 MCP 源代码进行校验。

前置条件

• 已为目标实例配置 Happy Platform MCP 5.1.0
• 对目标表具有读取权限
• 确切的表名
• 对探索性搜索设置较小的结果上限，并明确指定返回字段

操作步骤

1. 选择一个经过解析器验证的短语

以下原子短语可在 MCP 5.1.0 中完整解析：

意图	支持的短语	生成的编码条件
优先级标签	high priority	priority=2
优先级数字	P1 或 priority 2	priority=1 或 priority=2
影响	high impact	impact=1
紧急程度	medium urgency	urgency=2
当前用户	assigned to me	assigned_to=javascript:gs.getUserID()
无受派人	unassigned	assigned_toISEMPTY
指定受派人	assigned to John Smith	assigned_to.nameLIKEJohn Smith
今天打开	opened today	sys_created_on>javascript:gs.daysAgoStart(0)
最近打开	opened in the last 7 days	sys_created_on>javascript:gs.daysAgo(7)
最近记录	recent	sys_created_on>javascript:gs.daysAgo(7)
活跃记录	active	active=true
描述文本	description contains authentication	descriptionLIKEauthentication
一般内容	about SAP	short_descriptionLIKESAP^ORdescriptionLIKESAP
精确编号	number is INC0012345	number=INC0012345
来电者	caller is John Smith	caller_id.nameLIKEJohn Smith
类别	category is Software	categoryLIKESoftware
分配组	assignment group is Network Team	assignment_group.nameLIKENetwork Team

以上映射是 v5.1 解析器的实际输出。例如，“high”映射到优先级值 2，而“critical”映射到值 1。

2. 执行范围受限的搜索

务必提供 table；v5.1 的参数名不是 table_name。对于实时或并发任务，请指定目标实例。

Tool: SN-Natural-Language-Search
Parameters:
  table: incident
  query: P1
  fields: sys_id,number,short_description,priority
  limit: 10
  instance: dev

检查 encodedQuery、matchedPatterns、unmatchedText 和返回的记录。即使工具也返回了编码条件，只要 unmatchedText 非空，就应视为校验失败。

3. 保持探索性调用原子化

针对每个独立问题，分别进行一次范围受限的调用：

Tool: SN-Natural-Language-Search
Parameters:
  table: incident
  query: unassigned
  fields: sys_id,number,assigned_to
  limit: 10
  instance: dev

Tool: SN-Natural-Language-Search
Parameters:
  table: incident
  query: opened in the last 7 days
  fields: sys_id,number,sys_created_on
  limit: 10
  instance: dev

不要假设两个分别受支持的短语可以随意组合。v5.1 解析器对每种模式最多处理一次，剩余词语可能改变或削弱结果。

4. 使用编码查询确保精确性

如果需求包含精确比较、排除项、多个值、特定字段的文本运算符或确定性排序，请构建并检查编码查询，然后使用 SN-Query-Table：

Tool: SN-Query-Table
Parameters:
  table_name: incident
  query: priority=1^state!=7^assigned_toISEMPTY^ORDERBYDESCsys_created_on
  fields: sys_id,number,short_description,priority,state,assigned_to,sys_created_on
  limit: 25
  instance: dev

自动化场景也应选择编码查询路径，因为其含义不依赖于从自由文本中提取模式。

5. 明确校验非 incident 目标

自然语言解析会使用提供的表来处理依赖表的行为。搜索其他表时，切勿依赖默认值：

Tool: SN-Natural-Language-Search
Parameters:
  table: change_request
  query: recent
  fields: sys_id,number,short_description,sys_created_on
  limit: 10
  instance: dev

对于不熟悉的表，在自然语言搜索结果与已知记录核实之前，优先使用编码的 SN-Query-Table 查询。

工具用法

工具	用途
SN-Natural-Language-Search	使用一个经过解析器验证的短语进行范围受限的探索
SN-Query-Table	执行精确、可重复的编码查询

最佳实践

• 明确提供 table、fields、limit 和 instance。
• 从打包的 fixture 契约中选择一个原子短语作为起点。
• 确认 unmatchedText 为空后，再信任解析器结果。
• 在扩大 limit 前，将探索性结果与已知记录进行比较。
• 在生产自动化和复杂条件中使用编码查询。
• 尽量减少字段选择，以减少负载和意外的数据泄露。

故障排除

未返回编码条件

该短语未匹配 v5.1 模式。请使用一个有 fixture 支持的原子短语，或切换到 SN-Query-Table 并使用经过审核的编码查询。

返回的条件中有剩余文本

解析器只匹配了请求的一部分。不要将结果视为等效查询。请将请求精简为一个已验证短语，或使用编码查询。

返回的条件含义不正确

停止使用该短语。自然语言匹配可能会按非预期的模式接受词语。请直接将需求表达为编码查询，并在小型结果集上进行验证。

非 incident 搜索返回了 incident 形式的结果

确认调用使用的是 table，而不是过时的参数名称，并确认显式指定的表值正确。

相关技能

• itsm/incident-triage
• itsm/quick-reference
• admin/generic-crud-operations