上一篇 从 Context 到可检查 SQL:Data Agent 的语义编译链 介绍了 Semantic View 如何与业务知识结合,以及 SV 查询从何而来。这一篇换个角度:在 MirrorPilot 中,一个用户问题从提交到得到答案,要经过哪些步骤?
业务负责人在对话框里问:“上周华东区销售额为什么下降,主要集中在哪些渠道?”
回答这个问题,需要确定销售额的口径、比较窗口和渠道范围。把支付金额当成净销售额,或把不完整的一周拿来比较,后面的解释就可能跟着偏。查询之前,还得确认提问者有权访问这些数据。
沿着一次销售分析,可以把 MirrorPilot Data Agent 的分析过程拆成七个环节。实际运行会根据结果补充查询、澄清或停止,模型调用次数随任务变化。
文中的销售场景、视图名称和数值均为演示数据示例。

图 1:MirrorPilot 负责问答运行和结果呈现,MirrorControl 提供管理入口与知识检索服务,StarRocks 执行数据查询。第三步按需查口径,第六步按需查背景。
第一步 校验用户与会话权限
用户提交的问题,连同所选 Agent、会话标识和认证信息一起进入 MirrorPilot。服务端先检查运行接口权限,再确认普通用户是否被分配给目标 Agent。通过检查后,请求才能继续运行。
Data Agent 模式要求明确指定 Agent。在已有会话中追问,还要通过会话访问检查;知道一个会话 ID,本身并不构成访问权限。
本例中,提问者需要有权使用“销售分析 Agent”。网页和 API 请求都经过服务端检查,权限不会因为换了入口而省略。
第二步 确定本轮可用的能力
请求获准运行后,MirrorPilot 根据服务端保存的 Agent 配置选择工具组和 Skills,再按产品能力上限及配置的授权策略过滤,得到本轮可用的工具、Skills、语义视图和知识库范围。
客户端传入的工具、Skill、语义视图范围等覆盖字段会被清理。用户无法借这些参数给 Agent 增加能力。分析提示词也按最终绑定的工具生成:知识检索工具可用,才会加入相关检索指引。
这里有两种不同的约束。工具绑定与资源校验决定一次调用能否执行;角色说明、提示词和 Skill 指导模型如何工作。例如,归因 Skill 要求先核对口径,但这条指引不会增加 Agent 的查询权限。

图 2:入口、运行时和工具分别检查各自负责的权限,数据库执行权限还需要在部署时配置。
第三步 对齐业务口径并按需查知识库
拿到问题和会话上下文后,Agent 要把“销售额”对应到一个实际存在的指标。下单金额、支付金额、扣除退款后的净销售额,都可能被业务用户简称为销售额,查询时必须选定口径。
Semantic View 即语义视图,定义了可查询的业务指标和维度。目录中的描述和同义词帮助模型找到字段,查询工具还会校验字段引用。
本例把问题落实为以下条件:
项目 | 示例约定 |
|---|---|
指标 | 净销售额,按企业语义视图定义扣除退款 |
当前窗口 | 2026 年 10 月 26 日至 11 月 1 日 |
基准窗口 | 2026 年 10 月 19 日至 10 月 25 日 |
时区与粒度 | UTC+8,两个完整自然周 |
范围 | 华东区 |
首轮拆分 | 渠道 |
如果环比和同比会得出不同结论,而用户没有说清,分析要求先澄清。时间、单位、统计粒度以及周期是否完整,也在检查范围内。
有些业务规则在目录里解释得不够细。比如跨周退款该算在哪一周,Agent 可以调用 search_starrocks_knowledge 检索相关说明。工具接收自然语言问题,经 MirrorControl 的知识检索服务返回文档片段,供模型与指标定义对照。
检索有两个前提:Agent 已获授该工具,并配置了知识库范围。模型提供检索词,工具从服务端运行上下文读取 kb_list,转换为请求中的 kb_ids。没有分配知识库时,工具返回提示,不发起检索。
是否需要调用,由 Agent 结合问题和已有上下文判断。目录足够清楚时,可以直接查询数据。
SV 路由与渐进式披露
一个 Agent 可能关联多个Semantic View,而当前问题只涉及其中一部分。路由阶段需要先判断哪个视图能回答问题。如果此时就把所有视图的完整定义放入上下文,模型会同时读到大量无关字段。
MirrorPilot 将元数据的返回分成两层。调用 discover_starrocks_semantic_views 时不指定视图名,工具返回授权范围内视图的轻量摘要;传入选定的视图名,才返回这一视图的详细目录。
层次 | 返回给模型的信息 | 用于判断 |
|---|---|---|
视图摘要 | 视图名称、说明和路由元信息 | 哪些视图可能覆盖当前问题 |
详细目录 | 选定视图的指标、维度、表达式及关系等 | 具体使用哪些字段,能否表达所需口径 |
这可以理解为面向模型的渐进式披露:先用摘要选择方向,需要字段细节时再展开。模型读取的材料可以组织为“摘要列表+本轮需要的详细目录”,而非预先展开所有视图。
这里按需加载的是模型需要理解的元数据;真正执行语义查询时,工具仍会读取目标视图目录,校验指标和维度。它与业务知识检索也是两个独立动作:前者选择数据对象,后者补充规则和事件背景。
第三步结束时,指标、比较条件和候选视图都已明确,必要的口径资料也已补充;销售数值仍要通过语义查询取得。
第四步 把分析意图转换为查询
进入语义视图查询时,模型向工具提交结构化参数:选定的指标和维度、过滤条件、排序方式及行数限制。分组排名、占比、增长率等已支持的分析,还可以选择固定查询形态并填写参数。
服务端检查字段是否属于视图目录,校验标识符和操作符,对筛选值转义,然后构造 SQL。需要多阶段查询时,也由代码组织 SQL 结构,基础数据来自语义视图。
取回本例两个自然周的渠道数据,可以向 query_starrocks_semantic_view 提交以下参数。视图和字段名称为示例,实际调用必须使用目录中存在的名称:
{
"semantic_view": "business.sales_overview",
"metrics": ["sales.net_sales"],
"dimensions": ["sales.week_start", "sales.channel"],
"filters": [
{"field": "sales.region", "operator": "=", "value": "华东"},
{"field": "sales.week_start", "operator": "IN", "value": ["2026-10-19", "2026-10-26"]}
],
"order_by": [{"field": "sales.week_start", "direction": "asc"}],
"limit": 100
}复核时,可以逐项对照这组参数:是否查了指定视图,是否按渠道分组,两个周起始日期是否正确。这些选择随后体现在生成的 SQL 中。
SQL 模板的分阶段选择
企业已有的业务 SQL 可以保存为模板复用。Agent 同时绑定模板检索和执行工具时,工具说明会引导它优先检索模板;没有合适模板,再使用已分配的查询工具。因此,模板选择与前面的 SV 路由是相互配合的路径,并非所有问题都要依次完成两者。
模板选择首先处理候选范围。search_sql_templates 用用户的原始问题在已分配知识库中召回模板,保留检索排序,过滤低于最低相关性要求的结果。接下来,它根据候选数量和分数分布决定是否向模型返回 SQL 正文。
候选情况 | 工具返回 | Agent 的后续动作 |
|---|---|---|
没有合适候选 |
| 使用其他已授权的查询路径 |
只有一个候选,或前部候选与后部出现明显分差 |
| 判断是否匹配问题,选择一个模板 |
分数接近,或分数无法支持可靠的分差判断 |
| 根据语义缩小范围,再读取所选模板正文 |
走摘要分支时,模型先根据名称和描述选择文档 ID,无法区分时也可以选择全部候选。随后调用 do_sql_templates 读取所选模板的 SQL 正文;这次调用只读取模板。
相关性得分帮助缩小范围,模型仍需核对模板是否符合问题的指标与意图;不匹配时可以放弃使用。选定模板并填充值后,再以 filled_sql 参数进入执行分支。
候选已经足够明确,就直接附带 SQL,减少一次取正文的往返;候选难以区分,先给摘要,避免将多段长 SQL 一次性送入模型。
第五步 校验范围并执行查询
执行前,语义查询工具会再次检查目标视图是否在 Agent 的 sv_list 中,并校验指标和维度。直接提交一个越界视图名,也会被拒绝。
检查通过后,工具用配置的业务查询连接访问 StarRocks。它在数据查询前申请预算,完成后记录本轮的查询次数、返回行数、结果字符数和累计耗时,超限时返回错误。
sv_list 限定的是视图范围。“华东区”在本例中是业务筛选条件;若不同员工只能查看各自地区的数据,需要通过数据源权限、受控视图及相应授权配置。
查询完成后,工具把结果整理成以下内容,交给模型和前端使用:
返回内容 | 用途 |
|---|---|
| 模型分析和前端表格读取的查询结果 |
| 本次实际执行的语义查询 SQL |
| 数据库能提供时返回的展开 SQL |
| 对应结果列的指标、维度、格式和图表选择信息 |
截断标记、比较期告警等 | 提示结果覆盖或比较条件的限制 |
一次越权查询在哪里停止
以已经配置视图范围的销售 Agent 为例:服务端只为它分配了 business.sales_overview,但模型提交了 business.inventory_overview。工具会先检查目标视图,确认通过后才读取目录、构造 SQL。
# 本例的 runtime.sv_list 已由服务端配置
def query_view(request, runtime):
name = validate_view_name(request["semantic_view"])
allowed = normalize_all(runtime.sv_list)
if normalize(name) not in allowed:
return {"error": "视图不在当前 Agent 的授权范围内"}
catalog = read_catalog(name)
sql = build_semantic_sql(request, catalog)
return run_sql(sql)这个请求在视图范围检查处结束,目标视图的目录不会被读取,目标数据查询也不会执行。代码片段合并了范围检查与工具层错误返回;实际调用还会经过前文的身份、Agent 访问和工具授权检查。
不同工具检查的资源不同。知识检索从运行时取得 kb_list,作为检索请求的 kb_ids,未分配知识库时不发起检索。模板取正文也限定在已分配知识库的召回候选中;模板 SQL 的执行则有自己的语句检查和数据库权限边界。视图范围检查不能代替这些路径各自的授权。
第六步 核对变化并按需查业务背景
拿到渠道数据,还要和总体变化对账。MirrorPilot 的归因分析要求先复现总体差异,再选择维度下钻,检查拆分结果能否与总体对上。模型据此选择后续查询;这些分析步骤的执行情况和结果仍需要核查。
假设演示数据如下,金额统一换算为万元。三个渠道互斥,且覆盖全部销售:
渠道 | 前一周 | 上周 | 变化 |
|---|---|---|---|
直营电商 | 600 | 420 | -180 |
经销渠道 | 300 | 340 | +40 |
门店零售 | 100 | 120 | +20 |
合计 | 1,000 | 880 | -120 |
总体减少了 120 万元,降幅为 12%。直营电商的降幅更大,达到 180 万元;经销和门店渠道合计增加了 60 万元,抵消了部分下降。三项变化加起来正好是 -120 万元。
这也解释了一个容易误读的数字:按净变化计算带符号的贡献份额,直营电商为 -180 ÷ -120 = 150%。其他渠道在增长,对净下降的贡献为负,三项仍合计为 100%。这里计算的是变化贡献,与销售占比含义不同。
这种加法对账适用于本例的可加指标。转化率、均值、去重客户数或分位数,还需要检查分子、分母、权重、重叠和分布。
渠道贡献定位之后,Agent 可以按需检索业务背景,例如:“2026 年 10 月 26 日至 11 月 1 日,华东直营电商有哪些活动结束或规则调整?”调用的仍是 search_starrocks_knowledge,检索范围仍由当前 Agent 的知识库配置决定。
如果文档提到某次活动在上周结束,需要核对它的时间、适用渠道和变化方向,并检查是否有数据支持其影响量级。必要时再查语义视图;缺少数据,就把这条解释保留为待验证假设。更强的因果判断需要相应的实验或对照信息。
做到这里,回答可以交代变化集中在哪里、哪些解释有支持、还有多少没有解释。指标不够、比较数据缺失或残差较大时,应把这些限制写出来。
第七步 交付答案与查询依据
有了比较结果和相关背景,Agent 可以组织答案。本例的回答可以写成:
在上述两个完整自然周和净销售额口径下,华东区销售额由 1,000 万元降至 880 万元,下降 12%。降幅集中在直营电商,该渠道减少 180 万元;经销和门店渠道合计增加 60 万元,抵消了部分下降。具体业务原因仍需结合活动与交易因素验证。
用户可以继续打开语义查询结果卡,查看图表、表格和 SV SQL、Inline SQL。
结果带有截断标记或缺少比较期告警时,界面会提示,便于用户判断这份数据能回答到什么程度。
同一份结果如何生成表格、图表与 SQL 展示
查询工具把数据列、数据行和实际执行的 SQL 一起返回。query_shape 再把结果列对应到语义指标与维度。例如,渠道和净销售额的映射片段可以写成:
{
"dimensions": [
{"semantic_ref": "sales.channel", "result_column": "channel"}
],
"metrics": [
{"semantic_ref": "sales.net_sales", "result_column": "net_sales"}
]
}前端结合字段映射和其他展示元信息,识别维度列与指标列,再规划适合的图表。表格、图表和 SQL 标签页都从同一条工具结果读取内容:
# 前端读取同一个查询结果
result = parse_tool_message(tool_message)
render_table(result.columns, result.rows)
chart_plan = plan_chart(result)
if chart_plan.supported:
render_chart(chart_plan, result.rows)
render_sql("SV SQL", result.generated_sql)
if result.inlined_sql:
render_sql("SQL", result.inlined_sql)
render_result_warnings(result)
图 3:数据与 SQL 用于核对数值,知识片段用于检查解释,Trace 用于回看执行过程。
检查“下降 12%”时,可以对照视图、比较窗口、筛选条件、实际 SQL 和返回数据。检查活动影响的解释时,则需要回看检索片段,区分有支持的解释与待验证的假设。
配置好 Trace 采集后,可以在 MirrorControl 查看运行摘要、调用树和耗时,定位模型或工具调用的问题。Trace 记录成功并不能说明业务结论正确;底层数据发生变化后,同一 SQL 重跑也可能得到不同数值。
需要留存或汇报时,Agent 可以在已开放的报告工具范围内生成自包含 HTML 报告,供用户预览和下载。报告沿用本次分析的口径和数据,也保留尚未解决的问题。
对 MirrorPilot 中的这次销售分析,数值查询已经回答了降幅和渠道分布。如果业务负责人继续问“活动结束究竟影响了多少销售额”,就需要相应的指标或对照数据。只有渠道变化和一段活动说明时,回答应说明活动影响尚待验证,并列出还缺什么数据。Agent 能回答到什么深度,取决于企业的语义视图和知识库已经覆盖了哪些指标与业务规则,这两部分都需要随业务逐步建设。
By the way,更精细化的权限控制已经在路上了。
