从数据平台到智能数据助手：Agentic 数据分析与 API 生产实践

关于舟谱数据

舟谱数据是 2015 年成立的快消流通领域数智服务商，依托 AI 与数据能力，为超 4 万家经销商、上百家品牌商提供经销数字化、渠道数智化及供应链协同解决方案，覆盖 700 万 + 终端网点，以“让数据&智能成就每一位生意人”为使命，助力全链路流通效率升级。

01

普通 Text2SQL 卡在三道工程鸿沟

快消流通数据具有明显的复杂性：指标定义会随客户和业务要求变化，分析维度覆盖品牌、品类、商品、门店、渠道、员工、供应商、采购和库存等多个对象。同一个业务词也可能存在不同口径，例如“赠品进入门店是否计入铺市”，不同选择会形成不同指标，但同一客户必须使用统一口径。

为支撑这类场景，底层平台先完成数据采集、实时加工、湖仓处理和指标服务建设。数据从 RDS MySQL 出发，由自研 Photon 采集 Binlog 并发送至 Kafka，再由 Flink 接入后续处理；Hologres 承担实时数仓、ODS、宽表和维度表等加工，MaxCompute 承接离线侧处理。上层的一体化数据服务与 AI 数据开发平台，最初解决的是降低数据开发门槛、支持数据可视化和统一业务口径。

在此基础上引入 Text2SQL 后，问题并没有随着模型能够写 SQL 而消失，反而集中为三道工程鸿沟。

第一是语义鸿沟。业务人员提出的是“销售金额”“铺市”“门店表现”等业务词，SQL 需要的是确定的表达式、来源模块、维度关系、时间口径和过滤条件。只要口径错一位，即使 SQL 能执行，结论也失去可信度。

第二是安全鸿沟。平台采用多租户数据存储，一张表可能包含多个租户的数据。租户 ID 不是普通筛选条件，而是访问边界。主表带上租户条件并不意味着安全：JOIN 表未纳入关联约束，或 UNION 任一分支缺少限制，都可能将其他租户记录带入结果。仅在 Prompt 中要求模型遵守规则，无法构成最终防线。

第三是交付鸿沟。一次对话能够返回 SQL 和分析结果，但业务真正需要的往往是可以被系统持续调用的数据服务。如果答案停在代码块中，业务意图、验证过的 SQL 和参数信息仍要由不同角色在多个工具间重复搬运。

02

把一次问答拆成“步步有证据”的 Agent 链路

平台没有让单个 Agent 从问题直接跳到 SQL，而是把任务拆为一条结构化链路：业务问题进入后，规划层使用 LangGraph 组织 DAG 与 Subagent，并调度任务；指标解析 Agent 识别正式指标、维度和过滤条件；SQL Agent 生成候选查询；查询通过 MCP 网关和只读数据库身份完成权限内执行与真实取证；最后由 API Agent 生成未发布的 API 草稿。

这条链路有三个约束。其一，Agent 之间传递结构化产物，而不是不断拼接自然语言对话。其二，每一步都要留下可验证证据，指标解析、候选 SQL、执行结果和 API 草稿之间能够对应。其三，上下文按相关性装配并限制大小，避免数据库结果、长 SQL 和历史会话持续进入模型窗口，造成费用增长和注意力偏移。

链路中分别装配三类基础能力：指标解析和 SQL 生成使用版本化 Skill 快照；执行阶段经过 MCP 网关和只读数据库身份；规划与多轮分析使用知识、记忆、Capsule 和 Artifact 组成的有界 Context。由此，可信理解、安全执行和快速交付不再依赖一次模型调用，而是分散到不同工程环节中完成。

03

从统一指标平台反向生成 Skill，并用双路径验证语义

这套实践能够进入生产，一个前提是“先有指标平台，后有 Text2SQL"。统一指标平台已经沉淀了基于规则、参数化生成的指标服务，指标定义、数据模块、维度关系和过滤规则都有明确来源。平台再从这些既有资产中反向生成 Skill，而不是让模型从表结构开始猜测业务语义。

当前 Skill 快照覆盖 296 个正式指标、33 个数据模块和 17 个维度定义。快照中包含正式指标名称、表达式和依赖关系，指标到数据模块的路由关系，模块层级及最深模块选择规则，维度表、关联键和维度展开关系，以及时间口径、过滤条件、SQL 方言和原子指标、复合指标的组装规则。它本质上是对已有业务资产的结构化浓缩，并且可以装载和版本化。

生成候选 SQL 后，系统采用两条独立路径进行语义等价对比。路径 A 从自然语言出发，由 Skill 约束 Text2SQL，得到候选 SQL；路径 B 直接使用指标名称和参数，调用原指标项目，生成基准 SQL。系统比较两条路径中的表达式、模块、过滤条件、粒度和依赖关系。因为基准路径来自原有参数化指标服务，Text2SQL 不再只能依赖人工抽样判断。

对于无法确定的内容，处理原则是不猜：保留用户原词，返回候选项进行澄清；没有找到正式指标时拒绝回答；指标解析失败时阻断后续 SQL 和执行链路。这一机制把“生成得像不像”改为“是否与现有指标资产语义等价”。

04

权限进入执行链路，SQL 通过验证后再生成 API 草稿

安全控制被织入六个层次。指标与 Skill 层在生成阶段显式带入租户和关联约束；Agent 策略层限制为单条、可解析、只读查询，拒绝写入和副作用；项目 SQL 检查层通过 AST 遍历 JOIN、子查询和 UNION 等结构；MCP 接入层传递加密数据源信息和权限模式；MCP 网关按执行计划传播租户 ID 边界；数据库最终只提供只读账号。

其中关键点是不依赖模型“自觉”。SQL 文本中出现租户 ID 仍然不够，数据沿执行计划在多表关联和不同分支间流动时，也不能离开租户边界。因此，项目侧负责尽早规范和告警，MCP 与数据库负责执行期隔离。对于可能拖垮数据库的大查询，MCP 层还可以利用执行计划中的命中行数、Cost 等信息设置最大执行时间、最大行数和最大成本规则。

当 SQL 完成语义与执行验证后，API Agent 复用同一份业务意图和已验证 SQL，生成 API 草稿。流程包括参数识别、动态化改写、分层 AST 检查、MCP 可执行验证、草稿分页测试和创建未发布草稿。租户 ID、时间、门店、品牌等固定条件会被转换为 MyBatis 动态参数，必要的维表关联也在生成过程中补入。

系统默认只创建可编辑、可测试、可版本化的未发布草稿，最终发布仍由人决策。这样并没有取消知识、工具和责任边界，而是减少了跨边界搬运：后端不必重新猜测业务口径，开发人员不必在多个平台间复制 SQL，每一步也都有结构化输入和验证证据。

05

用有界 Context 支撑连续分析，并明确当前边界

为了支持多轮分析，平台把 Context 分为知识、记忆和会话三部分。知识侧采用 EXACT、词法和向量并行召回，再通过加权 RRF 融合，并同时限制召回数量和字符规模；长 SQL 不直接塞入上下文，而是保存为 unitId，由只读工具按需取回。向量化前还会对 SQL、字段和注释进行结构化预处理，避免一段完整 SQL 被任意切断。

记忆侧使用 category、key、title、content 等结构，每次装配不超过 8 条，单条不超过 500 字，并支持新增、合并、替代和失效治理。会话侧只保留最近消息、滚动摘要和 Capsule，Capsule 记录目标、已经作出的决定和未解决事项，不接受客户端无限上送历史。大结果则通过 Artifact 安全引用；裁剪以完整 item 为单位，避免 SQL 或 JSON 被截断，所有取舍由 Context Manifest 记录。

界面演示中，一个按月、按门店分析销售金额的复杂问题，会先生成执行计划，再输出趋势、异常、商品和渠道等进一步分析，并可继续创建 API、优化 API 或生成数据看板。对于分析方法，平台通过面向数据分析的 Subagent、Prompt 和场景知识文件注入业务侧重点，由分析师和算法工程师持续补充知识。

当前能力也有明确边界。权限控制重点覆盖租户 ID，材料中说明多角色、多身份、多数据种类的多维权限尚未实现；新增指标和可复用 API 回流统一指标平台仍需质量校验与人工审核。经过验证、具有重复调用价值的 API，可以反向沉淀为指标，再生成新的 Skill，形成“分析—服务—指标—Skill"的循环，但发布和资产化决策仍保留在人手中。

这套实践没有替代原有数据平台，而是把已经存在的指标资产、权限体系和服务生产流程重新组织进 Agent 链路。Agent 最终交付的也不只是一段 SQL，而是带有口径来源、执行证据、权限边界和可继续发布的数据服务草稿。

06

问答环节

Q1：在场景丰富、扩展性较强的情况下，标准指标体系如何继续扩展？

A1: 对于标准指标体系之外的新需求，方案允许先由 AI 生成 API。经过质量校验，并确认结果能够与业务库对齐后，具有业务价值且可能重复调用的 API，可以反向沉淀到统一指标平台，再由指标平台生成对应的 Skill。由于统一指标平台承载数据服务的定义，这一过程形成"API—指标—Skill"的回流链路。当前新增指标仍采用人工审核，发布和资产化并未完全自动化。

Q2：面对不同角色、身份和数据种类，如何实现多维度权限控制？

A2：当前权限控制重点覆盖租户 ID。即使只有租户这一维度，也需要处理 JOIN、UNION，以及 NOT IN、ALL 等可能绕过过滤条件的写法，相关判断要在执行计划解析和权限传播过程中完成。材料明确说明，在不深入数据库内部的情况下，多角色、多身份和多数据种类的多维权限复杂度已经超过当前可接受范围，因此目前尚未实现。

点个在看你最好看

SPRING HAS ARRIVED