上一篇 从 Context 到可检查 SQL:Data Agent 的语义编译链 介绍了 Semantic View 如何与业务知识结合,以及 SV 查询从何而来。这一篇换个角度:在 MirrorPilot 中,一个用户问题从提交到得到答案,要经过哪些步骤?

业务负责人在对话框里问:“上周华东区销售额为什么下降,主要集中在哪些渠道?”

回答这个问题,需要确定销售额的口径、比较窗口和渠道范围。把支付金额当成净销售额,或把不完整的一周拿来比较,后面的解释就可能跟着偏。查询之前,还得确认提问者有权访问这些数据。

沿着一次销售分析,可以把 MirrorPilot Data Agent 的分析过程拆成七个环节。实际运行会根据结果补充查询、澄清或停止,模型调用次数随任务变化。

文中的销售场景、视图名称和数值均为演示数据示例。
MirrorPilot 7 步链路图 1

图 1:MirrorPilot 负责问答运行和结果呈现,MirrorControl 提供管理入口与知识检索服务,StarRocks 执行数据查询。第三步按需查口径,第六步按需查背景。

第一步 校验用户与会话权限

用户提交的问题,连同所选 Agent、会话标识和认证信息一起进入 MirrorPilot。服务端先检查运行接口权限,再确认普通用户是否被分配给目标 Agent。通过检查后,请求才能继续运行。

Data Agent 模式要求明确指定 Agent。在已有会话中追问,还要通过会话访问检查;知道一个会话 ID,本身并不构成访问权限。

本例中,提问者需要有权使用“销售分析 Agent”。网页和 API 请求都经过服务端检查,权限不会因为换了入口而省略。

第二步 确定本轮可用的能力

请求获准运行后,MirrorPilot 根据服务端保存的 Agent 配置选择工具组和 Skills,再按产品能力上限及配置的授权策略过滤,得到本轮可用的工具、Skills、语义视图和知识库范围。

客户端传入的工具、Skill、语义视图范围等覆盖字段会被清理。用户无法借这些参数给 Agent 增加能力。分析提示词也按最终绑定的工具生成:知识检索工具可用,才会加入相关检索指引。

这里有两种不同的约束。工具绑定与资源校验决定一次调用能否执行;角色说明、提示词和 Skill 指导模型如何工作。例如,归因 Skill 要求先核对口径,但这条指引不会增加 Agent 的查询权限。

MirrorPilot 7 步链路图 2

图 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 提交以下参数。视图和字段名称为示例,实际调用必须使用目录中存在的名称:

Code
{
  "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 的后续动作

没有合适候选

no_choose,不返回 SQL

使用其他已授权的查询路径

只有一个候选,或前部候选与后部出现明显分差

choose_from_candidates,返回前部候选及 SQL

判断是否匹配问题,选择一个模板

分数接近,或分数无法支持可靠的分差判断

tier_then_fetch,先返回名称、描述、得分和文档 ID

根据语义缩小范围,再读取所选模板正文

走摘要分支时,模型先根据名称和描述选择文档 ID,无法区分时也可以选择全部候选。随后调用 do_sql_templates 读取所选模板的 SQL 正文;这次调用只读取模板。

相关性得分帮助缩小范围,模型仍需核对模板是否符合问题的指标与意图;不匹配时可以放弃使用。选定模板并填充值后,再以 filled_sql 参数进入执行分支。

候选已经足够明确,就直接附带 SQL,减少一次取正文的往返;候选难以区分,先给摘要,避免将多段长 SQL 一次性送入模型。

第五步 校验范围并执行查询

执行前,语义查询工具会再次检查目标视图是否在 Agent 的 sv_list 中,并校验指标和维度。直接提交一个越界视图名,也会被拒绝。

检查通过后,工具用配置的业务查询连接访问 StarRocks。它在数据查询前申请预算,完成后记录本轮的查询次数、返回行数、结果字符数和累计耗时,超限时返回错误。

sv_list 限定的是视图范围。“华东区”在本例中是业务筛选条件;若不同员工只能查看各自地区的数据,需要通过数据源权限、受控视图及相应授权配置。

查询完成后,工具把结果整理成以下内容,交给模型和前端使用:

返回内容

用途

columns、rows

模型分析和前端表格读取的查询结果

generated_sql

本次实际执行的语义查询 SQL

inlined_sql

数据库能提供时返回的展开 SQL

query_shape

对应结果列的指标、维度、格式和图表选择信息

截断标记、比较期告警等

提示结果覆盖或比较条件的限制

一次越权查询在哪里停止

以已经配置视图范围的销售 Agent 为例:服务端只为它分配了 business.sales_overview,但模型提交了 business.inventory_overview。工具会先检查目标视图,确认通过后才读取目录、构造 SQL。

python
# 本例的 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 再把结果列对应到语义指标与维度。例如,渠道和净销售额的映射片段可以写成:

Code
{
  "dimensions": [
    {"semantic_ref": "sales.channel", "result_column": "channel"}
  ],
  "metrics": [
    {"semantic_ref": "sales.net_sales", "result_column": "net_sales"}
  ]
}

前端结合字段映射和其他展示元信息,识别维度列与指标列,再规划适合的图表。表格、图表和 SQL 标签页都从同一条工具结果读取内容:

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)
MirrorPilot 7 步链路图 3

图 3:数据与 SQL 用于核对数值,知识片段用于检查解释,Trace 用于回看执行过程。

检查“下降 12%”时,可以对照视图、比较窗口、筛选条件、实际 SQL 和返回数据。检查活动影响的解释时,则需要回看检索片段,区分有支持的解释与待验证的假设。

配置好 Trace 采集后,可以在 MirrorControl 查看运行摘要、调用树和耗时,定位模型或工具调用的问题。Trace 记录成功并不能说明业务结论正确;底层数据发生变化后,同一 SQL 重跑也可能得到不同数值。

需要留存或汇报时,Agent 可以在已开放的报告工具范围内生成自包含 HTML 报告,供用户预览和下载。报告沿用本次分析的口径和数据,也保留尚未解决的问题。

对 MirrorPilot 中的这次销售分析,数值查询已经回答了降幅和渠道分布。如果业务负责人继续问“活动结束究竟影响了多少销售额”,就需要相应的指标或对照数据。只有渠道变化和一段活动说明时,回答应说明活动影响尚待验证,并列出还缺什么数据。Agent 能回答到什么深度,取决于企业的语义视图和知识库已经覆盖了哪些指标与业务规则,这两部分都需要随业务逐步建设。

By the way,更精细化的权限控制已经在路上了。