做过数仓的人应该都懂日常工作中最消耗精力的事情往往不是写SQL而是找口径。业务方拿着报表来问这个GMV怎么和另一个看板对不上这个转化率到底包不包含某个渠道指标在数仓里到底是怎么算出来的每一次都要在十几个模型、几百张表、数不清的调度任务里去翻找。传统做法是靠文档、靠老员工记忆、靠群里翻聊天记录效率极低。而Agent MCP Skill这套组合恰好就是冲着这个痛点来的让AI智能体通过标准化协议连接数仓各个系统再用沉淀好的查询技能把一条指标从业务定义到SQL实现、再到调度和报表展示的完整链路自动串起来。这篇文章就围绕我在实际项目中搭建这套全链路口径查询系统的过程讲讲架构思路、落地细节和踩过的坑适合正在做数仓平台、数据治理或者AI应用开发的团队参考。1. 口径查询这件事难在哪里1.1 口径的全链路到底指什么先理清楚一个概念。数仓里的指标口径不是一句GMV 支付成功订单金额就能说清楚的。一个指标从提出到落地至少要经过这么几个环节业务方定义口径比如GMV含运费不含退款→ 数仓建模时把口径翻译成维度、度量、逻辑模型 → 开发人员写ETL SQL实现 → 调度平台定时跑数 → 指标平台或报表系统对外展示。这条链路上的任何一环都可能出现偏差而口径查询要做的就是把这条链路完整地找出来、讲清楚。举个例子业务问最近30天DAU为什么下降了一个好的口径查询系统应该能回答DAU的业务定义是什么去重设备号还是用户ID、对应的明细表是哪张、DWD层的SQL是怎么算的用了什么去重逻辑、调度任务几点跑、产出数据口径在报表端有没有二次加工。任何一个环节的信息缺失排查问题就得靠人肉翻代码。1.2 传统方案为什么搞不定以前大家也做过不少尝试。最常见的是建指标字典把指标定义、计算公式维护在Excel或在线文档里结果维护不及时、口径变了文档不更新最终沦为废纸。也有的企业上了元数据管理平台能查到表结构、字段注释和简单的血缘关系但血缘往往只覆盖到表级字段级的转换逻辑不清晰而且元数据平台和实际SQL实现经常脱节。更深层的问题是口径查询本质上是多源信息聚合逻辑推理的活儿。你得同时查业务文档、模型设计、SQL代码、调度配置、报表配置然后把碎片信息串成一条完整链路。传统搜索引擎也好、元数据平台也好都只覆盖了其中一个信息源。而Agent天然适合做这件事它能把多个工具的查询结果拿回来再基于对业务和数仓的理解二次加工成一条有逻辑、有依据的完整回答。这也是我选择这个技术路线最核心的理由。2. Agent、MCP、Skill三者怎么分工2.1 用生活化的方式理解这套架构很多刚接触的朋友搞不清Agent、MCP、Skill这三者的区别。我打个比方Agent是大脑和指挥官负责听懂你要什么、拆解任务、决定先调哪个工具MCP是神经和手脚负责用统一的标准方式把各种外部系统连接起来Skill是肌肉记忆把你做某类事情的经验和套路预先编排好让Agent不用每次从零开始想怎么办。具体到口径查询这个场景Agent负责解析最近DAU为什么降了这种模糊提问把它拆成查DAU定义、查核心表血缘、查调度状态、查指标趋势几个子任务MCP Server负责去接数仓的元数据库、SQL引擎、调度平台和指标平台提供标准的工具接口Skill则把指标口径解读这件事分成固定的几个步骤——先查指标注册信息、再定位物理模型、再追SQL实现、最后核对报表口径每一步调什么MCP工具、结果如何拼接都在Skill里预设好。2.2 MCP在这个项目里解决的核心问题没有MCP之前让Agent去连数仓系统是一件很痛苦的事。每个系统都有自己的API、鉴权方式、返回格式Agent没法直接用得针对每个系统写大量的胶水代码和prompt适配。MCPModel Context Protocol做的事情就是把这些系统封装成统一的工具每个MCP Server暴露若干个tool每个tool有明确的名称、参数schema和返回结构Agent通过MCP协议就能自动发现和调用这些工具。在我这个项目里MCP Server的价值特别明显。我们接入了四个系统元数据管理平台查表和字段信息、SQL查询引擎跑验证SQL、调度平台查任务状态和运行日志、指标平台查指标注册和报表配置。这四个系统的接口风格完全不同但通过各自封装成MCP Server后对Agent暴露出来的是统一的工具列表。Agent不需要关心底层是HTTP还是RPC只管传参数、收结果大大降低了集成复杂度。2.3 Skill为什么不是普通的PromptSkill和Prompt的区别在于Prompt只是给Agent一段指令文本而Skill是可执行的能力封装通常包含一系列预设的步骤、每个步骤对应的工具调用策略、异常分支处理和输出模板。它不光是告诉Agent怎么做更是把踩过坑之后沉淀下来的最佳实践固化下来。比如我们的口径解读Skill最开始只是简单让Agent去查一下指标定义结果发现它经常漏掉核对SQL实现与业务定义是否一致这一步直接照着文档念给业务方。后来我们把完整的解读流程写进Skill第一步查指标注册信息第二步定位核心物理表第三步抽取ETL SQL中的关键计算逻辑与业务口径做比对第四步检查调度产出时间是否满足时效要求第五步生成多级视图报告。每一步都对应具体的MCP工具调用如果某一步没有搜到预期数据Skill里还定义了怎么降级处理。这才是Skill区别于普通Prompt的本质它是经过验证的操作流程而不是一段描述性的建议。3. MCP Server的选型与搭建3.1 连接数仓系统时工具粒度怎么定搭建MCP Server的第一步是想清楚暴露哪些工具、粒度多大。工具粒度太粗Agent拿不到精细信息太细Agent要多轮调用才能凑齐信息既慢又容易出错。我的实践经验是以数仓角色为粒度来定工具。面向元数据平台的工具我暴露了get_table_schema、search_table_by_business、get_field_lineage、get_table_owner这四个覆盖了查表结构、按业务词搜表、查字段级血缘、找负责人的常见需求。面向SQL引擎的暴露了execute_query和dry_run_query两个一个是真跑查询一个只做语法和字段校验不真正执行。面向调度平台的暴露了get_task_info、get_task_run_history、get_task_dependencies三个。面向指标平台的暴露了get_metric_definition、list_related_reports、get_metric_daily_value三个。工具粒度定的精髓在于每个工具都要有明确的信息价值Agent只需要一次调用就能拿到一个完整的信息块。比如get_metric_definition返回的不仅是指标名称和公式还包括指标对应的事实表、维度表、创建人、最近修改时间一次调用就能支撑后续的分析判断。3.2 鉴权、超时和返回体量的设计细节MCP Server对接数仓系统有几个工程细节必须在设计阶段就考虑到位。第一是鉴权。我们内部系统采用统一SSO登录但MCP Server是服务端调用的没法走用户浏览器登录流程。我最后用的是服务账号API Token的方式每个MCP Server启动时从配置中心拉取Token每隔一小时自动刷新。要注意的是不同的内网系统鉴权方式不一样有的是Header Token、有的是签名参数这些差异要封装在MCP Server内部不要让Agent感知到。第二是超时控制。数仓的SQL查询和元数据扫描都可能很慢agent reasoning token的上下文窗口又有限如果工具调用长期挂起整个会话就卡死了。我给每个MCP工具都设了三档超时快速查询5秒、元数据查询15秒、SQL执行60秒。超时后返回结构化错误信息Agent可以根据错误信息决定是重试还是换个方案。第三是返回体量。这是最容易踩坑的地方。元数据平台检索结果动辄几万行直接返回给Agent会把上下文窗口撑爆。我在MCP Server里做了截断和聚合处理默认只返回前50条每条截断到200个字符以内对于血缘查询先做层级归纳只返回指定层级的邻居而不是全量链路。这样既保证了信息的可用性又防止了上下文爆炸。3.3 私有化MCP Server的注册与调试流程项目里我使用的是基于Python的MCP SDK来搭建Server整体流程不复杂但有几个环节需要格外注意。首先是配置SSE传输和工具命名。我们内部的Agent框架支持连接独立的MCP Server进程通过SSEServer-Sent Events协议通信。Server启动后会自动向Agent注册工具列表Agent端就能直接发现工具。工具命名我建议统一用动词名词的格式比如get_table_schema、execute_query这样Agent在意图匹配时更容易把用户问题映射到正确的工具上。其次是联调阶段的工具参数校验。MCP协议里的tool是有JSON Schema参数定义的Agent生成的参数必须符合Schema才能被调用。我一开始对参数做了严格校验结果发现Agent经常因为少传一个非必填参数就报错后来把所有非必填参数都加了默认值容错率大幅提升。最后是日志和可观测性。MCP Server必须要有完整的请求日志记录每次工具调用的入参、出参、耗时和错误信息。这样当Agent的回答不对时我们能快速定位是Agent推理错了还是工具返回的数据有问题。我在项目里给每个工具都加了trace_id贯穿Agent、MCP Server和底层系统排查问题效率提升了一个量级。4. Skill的设计把数仓专家的查询套路固化下来4.1 口径解读Skill的核心流程口径解读是使用频率最高的Skill我把它设计成五个固定步骤。第一步用get_metric_definition拿到指标在指标平台上的注册信息包括业务定义、负责人和更新记录。第二步用search_table_by_business把指标映射到数仓里的物理表这一步经常会遇到一指标多表的场景所以Skill要求Agent把匹配到的所有候选表都列出来再做筛选。第三步用get_field_lineage和execute_query定位核心字段的加工逻辑重点看SQL里有没有过滤条件、去重逻辑、类型转换可能导致口径偏移的地方。第四步查调度任务确认数据产出时效。第五步汇总所有信息生成包含业务口径—模型实现—SQL验证—产出时效—风险提示五个板块的口径报告。这五个步骤的顺序不能乱。先统一认识指标定义再找物理载体表再看实现细节SQL最后核对时效调度。如果先查SQL很容易被一个具体的实现细节带偏而忽略了指标的整体业务背景。4.2 血缘追溯Skill和分层策略血缘追溯Skill解决的是这张表的这个字段是怎么来的下游哪些报表用了它。这个Skill本身不复杂关键在于分层策略的设计。数仓是分层架构ODS、DWD、DWS、ADS血缘横跨多个层级如果把全链路血缘一次性拉出来结果会非常庞大且难以理解。我的做法是把血缘查询按层级分段默认查两层即当前表的上游一层和下游一层。如果Agent判断需要更完整的链路再逐层往下钻取。这样的好处是回答问题的响应时间可控而且分段查询的结果更容易被业务方看懂。另外血缘数据本身的质量决定了这个Skill的天花板。我们内部元数据平台对字段级血缘的解析覆盖率大约在85%左右剩余的15%往往是因为SQL太复杂用了自定义UDF、动态SQL导致解析失败。针对这种情况Skill里增加了一个补偿步骤当get_field_lineage返回为空或报错时自动降级为用execute_query去跑一段解析SQL直接查询SQL文本中对该字段的引用关系把这个结果补进血缘链路中。4.3 影响分析Skill从查口径到管口径口径查询做到第二步会自然衍生出口径变更影响分析的需求。比如数仓团队想把某个字段从String类型改成BigInt或者调整某个指标的过滤逻辑这时候就必须知道影响面有多大哪些下游模型依赖它哪些报表会变哪些业务方在使用影响分析Skill的思路其实是血缘追溯的反向应用。核心步骤是用get_field_lineage拿到当前字段的全部下游引用对每个引用点进一步查询其所属的模型和报表最后按影响等级分类——直接影响报表数值会变、间接影响上游模型变更导致传导、潜在影响被动态表名引用无法精确解析。这个Skill上线后数仓团队做变更评审的时间从半天缩短到了二十分钟这算是整个项目里ROI最高的一个模块。5. 完整实操一次真实的跨链路口径查询5.1 一个典型问题的全流程走查我拿一个真实场景来演示整个系统是怎么工作的。假设业务方在群里问上个月我们官网的注册转化率是多少这个口径是只算新用户还是包含回流用户用户输入这句话后Agent先做人设判断识别出这是一个指标查询口径解读的复合需求于是同时激活指标查询Skill和口径解读Skill。第一步Agent调用get_metric_definition参数填注册转化率 官网返回结果里有两条注册指标记录一个是注册转化率全量定义是当天注册用户数/当天官网UV口径包含回流用户另一个是拉新转化率定义只统计过去180天内无登录记录的新用户。Agent识别到问题中新用户还是回流用户的疑惑决定把两个指标都纳入分析范围。第二步Agent分别映射这两个指标到物理表。注册转化率全量对应DWS层的dws_kpi_register_di拉新转化率对应dws_kpi_pull_new_di。Agent调用get_table_schema确认两张表的时间分区字段和关键指标字段名。第三步Agent对口径做SQL验证。它用dry_run_query找了个过去30天的临时分区分别跑了一遍两种口径的SQL确认计算结果与指标平台上的历史数值吻合。这一步很关键因为如果SQL实现和指标注册的定义不一致后面所有分析结论都是错的。第四步Agent查调度任务确认这两张表每天凌晨2点产出、调度状态正常最近一天的数据已经产出。第五步Agent把所有信息汇总成口径报告并主动对比了两个口径在数字上的差异全量口径注册转化率3.2%拉新口径2.1%差异来源正是回流用户占注册量的三成以上。业务方看完报告直接确认了自己要的是哪个口径。整个查询从提问到完整回答耗时约40秒而以前人工排查至少需要1小时。5.2 交互链路里的关键参数与耗时数据我实测了整个链路的耗时分布Agent意图识别和任务规划约3秒第一次MCP工具调用get_metric_definition2秒元数据映射和表结构查询共消耗6秒dry_run_query校验两段SQL耗时15秒调度信息查询2秒剩余10秒是Agent整合结果和生成报告的时间。这里面最耗时的是SQL校验环节。为了控制复杂度我在Skill里设置了两个参数exclude_list指定哪些表跳过校验max_run_seconds限制单条SQL最大执行时长。这两个参数在大多数场景下有效控制住了整体耗时。另外Agent在处理多指标并行查询时会采取串行策略避免多个SQL同时执行对后端的压力冲击虽然总耗时变长但系统稳定性可控。5.3 这套链路在团队里的落地形态系统落地后我没有直接给业务方开放Agent的独立入口而是做了一个折中方案先接入数仓团队内部的工作协作群和工单系统。数仓同学在工作群里被业务问到口径问题直接机器人提问Agent跑查询结果回传到群里。工单系统则是自动对每个口径咨询生成一条记录沉淀成口径问答的知识库。现在团队里做口径咨询复盘不再需要翻聊天记录直接在知识库里看历史问答就能了解常见问题和盲区。这个落地形态好处在于风险可控Agent的回答先经过数仓同学确认再对外、数据可沉淀每次问答都入库、团队可感知用起来没有迁移成本。等跑顺两三个月积累的语料也足够训练出更精准的意图识别模型后再考虑对业务方全面开放。6. 常见问题与排查技巧实录6.1 上下文溢出的系统级对策整个项目上线后遇到最普遍的问题是Agent在整合多工具返回结果时经常出现上下文窗口溢出。典型场景是一个指标关联了十几张表每次get_field_lineage返回几百条血缘记录几轮调用下来上下文里塞满了原始数据Agent开始失忆回答质量急剧下降。我的对策是三层。第一层是在MCP Server端做返回压缩血缘只返回字段名、表名、层级、链路类型四要素不返回注释和属性信息。第二层是在Skill里做中间结论替换每完成一个步骤Agent把这一步的结论提炼成一两句话替代原始数据留在上下文里。第三层是拆分查询遇到超长链路时强制分轮查询不要求Agent一次把10层血缘全查完。6.2 MCP工具调用失败的典型处理工具调用失败是家常便饭但失败的原因各不相同处理方式也不一样。最常见的是权限不足。我们的元数据平台对敏感表的访问有严格管控Agent用的服务账号没有权限时返回的报错信息都是统一的access denied。一开始Agent遇到这个报错就傻掉了直接跟用户说查不到。后来我在MCP Server的错误信息里加了错误码PERM_DENIED、NOT_FOUND、TIMEOUT、PARSE_ERROR并在Skill里定义了对应的降级策略遇到PERM_DENIED先尝试查缓存或调用脱敏版接口如果还是不行就明确告诉用户该表受权限管控建议联系数据Owner而不是简单说查不到。第二个常见失败是SQL执行超时。数仓里一张大表即使加上了分区过滤跑聚合查询也可能超过60秒。我的对策是把验证SQL拆成两步先用dry_run_query跑EXPLAIN确认扫描分区数如果扫描分区超过阈值就自动缩小时间范围再决定是否真正执行。这样既避免了长时间占用查询资源也减少了超时概率。6.3 Skill迭代时容易忽略的幂等性问题Skill迭代过程中踩过一个大坑同一个问题在不同时间问Agent回答的链路和格式经常不一致导致用户困惑。刚开始我没在意后来发现是Skill在编排时允许了多种分支路径导致的。比如口径解读Skill里我最初允许Agent根据数据情况自由选择先查血缘还是先校验SQL。结果就是Agent今天觉得先查血缘方便明天觉得先跑SQL验证也行输出报告的顺序、详略都会变。我在迭代时加了强制约束Skill的执行路径必须是固定的分支只有在遇到错误时才允许进入降级逻辑。这样虽然灵活性降低了一些但输出的稳定性和可比性大幅提升。对于企业内部工具稳定压倒一切。还有个细节容易忽略Skill本身有版本。每次修改Skill后要给Skill加版本号并在Agent会话里记录用的哪个版本的Skill。否则出了线上问题你都不确定是Agent推理导致的还是Skill改动引入的。后来我们上了配置中心统一管理Skill版本可回溯性好了很多。7. 做得好的和做得不够好的从实用性角度看这套系统目前的完成度大约七成。做得好的地方在于口径查询从人肉翻代码变成了智能问答日常口径咨询量里大约六成可以交给Agent直接答复剩下的四成是口径本身定义不清、链路数据缺失这种情况即使人查也很费劲Agent做不到也不奇怪。做得不够好的地方我总结两个方向给后来者参考。一是元数据质量仍然是天花板。系统再好如果表注释是空的、字段命名不规范、血缘解析不全Agent能查到的东西就有限。所以做这套系统前先把元数据治理的基本功补齐收益会大得多。二是Agent的自我评估能力不足。它经常自信地给出一个口径解释但实际上漏掉了某个重要的过滤条件而这只有对业务很熟的人才能识别出来。目前我的应对措施是关键指标自动做过一次历史数值比对数值对不上就自动在报告里打上置信度低的标签提醒用户复核。按照目前的迭代节奏下一步我打算把口径问答中沉淀出的高质量问答对用来微调一套面向数仓领域的轻量模型把常见口径的识别准确率再往上提一提同时减少对大型模型推理能力的依赖降低单次查询的调用成本。最后再分享一个实操心得做一个AI应用最大的坑往往不在模型不在框架而在底层数据质量和系统集成。MCP和Skill解决了连通性和可编排的问题但如果上游元数据本身脏乱差再聪明的Agent也只能在垃圾数据里打转。先把数仓的看家本事——规范建模、管理元数据——做扎实再上AI这才是最稳的落地路径。