Lightdash Analytics 技能指南让 AI Agent 通过 MCP 服务治理化语义层【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash本指南系统讲解 Lightdash 仓库中plugins/lightdash/skills/lightdash-analytics/SKILL.md定义的 Agent 分析工作流如何借助 Lightdash MCP 服务器完成业务问答、治理指标查询以及图表/仪表盘的创建并给出源码级的工具清单与调用顺序说明。读完本文你将掌握先发现、后查询、再落盘的规范 Agent 分析流程以及如何把该技能接入 Codex、Cursor 等编码 Agent 中安全地操作分析内容。技能定位与核心原则lightdash-analytics是随 Lightdash agent plugin 分发的一个分析工作流技能面向受治理的指标发现governed metric discovery、语义层查询、安全创建分析内容三类场景。它的核心主张只有一条将 Lightdash MCP 服务器视为用户治理语义层的唯一事实来源source of truth。也就是说Agent 在回答任何与业务数据相关的问题时不应凭记忆或猜测构造指标定义、字段 ID 或过滤器取值而应通过 MCP 工具去发现、确认、再执行。技能文件本身很短但配合后端McpService的实现可以还原出一套完整的工具链与约束体系。Discover before querying先发现后查询技能给出的查询前发现流程共 4 步设置活动项目如果服务器要求指定项目先完成项目上下文设置路由与探索列表route_agent可用时优先使用否则先列出可用 explores检查结构在组合指标查询前先检查所选 explore 及其字段参考已验证内容当请求与已验证verified内容匹配时以之为参考。技能同时给出了硬性纪律绝不凭空发明 explore 名称、字段 ID、指标定义、过滤器值或查询 UUID当字符串过滤器必须匹配某个已有值时应通过搜索字段值来获取。该流程在后端 prompt 中被编码为具体的工具调用序列。见 mcpAnalyst.ts 中的buildMcpAnalystPrompt其查询构建工作流依次是步骤工具作用0get_context选择作用域向项目级工具显式传递projectUuidagent 场景下还有agentUuid1grep_fields发现字段并在正确粒度上选择一个 explore2get_metadata查询前确认元数据只使用发现阶段返回的精确字段 ID3search_field_values需要过滤值时搜索合法取值4run_metric_query查询治理指标5get_query_result轮询运行中的查询绝不重新提交原查询6render_chart需要图表时渲染已完成查询7list_content浏览可访问内容8find_content搜索仪表盘、图表和 Data Apps这些工具名与 McpService.ts 中定义的McpToolName枚举一一对应其中run_metric_query、render_chart、run_sql、get_query_result、search_field_values等均要求项目作用域——所有项目级工具都会通过withProjectScopeInput扩展出projectUuid必填与可选的agentUuid参数见 McpService.ts。Answering questions优先走语义层SQL 是兜底在回答问题环节技能给出了明确的优先级与处理细则优先run_metric_query凡是能放进语义层的问题都用它作答run_sql仅在无法用治理 explore 表达时使用且仅当会话可用该工具时轮询查询仍在运行时用返回的 query UUID 调用get_query_result轮询直至完成可视化当图表有助于澄清结果时用render_chart渲染已完成的指标查询如实陈述答案中要说明所用指标、时间周期、过滤器与重要注意事项空结果也是合法结果把空结果视为有效答案而非查询失败。后端 prompt 对两种模式的分流逻辑印证了这一点。mcpAnalyst.ts 的getMcpAnalystPrompt依据两个布尔开关分流runSqlEnabledfalse且runMetricQueryEnabledfalse→Saved Content Mode纯内容模式只允许get_context/find_content/read_content/list_content禁止任何绕过手段runMetricQueryEnabledfalse→SQL Runner Mode只用run_sql默认返回 500 行、上限 5000 行可用limit参数调整且同样必须先get_context选项目两者都开启 → 完整 MCP Analyst 模式run_sql被限定用于未被建模进 explore 的临时查询、跨表 join 或用户明确要求裸 SQL的场景。run_metric_query的底层实现在 runMetricQuery.ts它围绕 AI 生成参数做了一组严格的校验validateFieldEntityType维度和指标必须真实存在且实体类型正确、validateCustomMetricsDefinition、validateFilterRules、validateMetricDimensionFilterPlacement过滤器/指标/表计算的放置位置合法性、validateSelectedFieldsExistence、validateSortFieldsAreSelected排序字段必须已被选中。这解释了技能中绝不发明字段 ID、指标定义这条纪律的技术来源——参数在服务端会被逐项核对而非盲执行。此外该工具还支持自定义指标custom metrics与表计算并通过toModelOutput将结果序列化后返回给 Agent。Creating content and changing analytics先验证再落盘对于创建图表/仪表盘或修改分析内容的场景技能给出的约束是创建前先检查相关 schema 与已有内容先验证查询再走服务器的创建工作流涉及 dbt 或 content-as-code 的改动在分支上工作走 Lightdash CLI 工作流preview预览→validate校验→review评审→merge合并除非用户明确要求不要执行部署或启动 AI writeback外部变更。CLI 的preview命令在 packages/cli/src/index.ts 有完整定义Creates a new preview project - waits for a keypress to stop即创建一个独立预览项目支持--name自定义名称、--select/-m按 dbt 选择语法圈定模型、--target指定 profiles 目标、--defer/--favor-state等 dbt 属性、--table-configuration prod|all控制表配置来源、--skip-copy-content跳过复制源项目内容等选项。这套先预览、后合并的设计与技能中的分支工作流一一对应确保对生产语义层的任何改动都经过可审查的流程而不是由 Agent 直接写回。内置 Lightdash 技能通过 MCP 暴露更多能力技能的最后一部分说明MCP 服务器可以暴露额外的 Lightdash 技能与参考资料。当客户端没有直接呈现 MCP 资源时使用list_skills列出技能然后只读取与当前任务相关的技能或参考。这在源码中有两层体现McpToolName枚举包含LIST_SKILLS、READ_SKILL、READ_SKILL_RESOURCE三个工具且它们与get_lightdash_version、list_projects、get_context一样属于项目无关工具见 McpService.ts即无需项目上下文即可调用仓库后端自带一组内置技能见 builtInSkills 目录developing-in-lightdash、filter-expressions过滤器表达式与run_metric_query/search_field_values配套使用、mcp-artifact-integration含结果契约资源result-contracts.md、table-calculations表计算。mcpAnalyst.ts中的过滤器技能提示FILTER_EXPRESSION_SKILL_REMINDER也印证了这一点在编写过滤器表达式之前应先读取run_metric_query与search_field_values引用的共享技能。技能的 MCP 扩展标识为io.modelcontextprotocol/skillsSkills-over-MCP extension见 McpService.ts。接入方式插件、OAuth 与环境变量lightdash-analytics技能随 agent plugin 分发一个插件包同时服务于两大市场CodexOpenAI 插件目录使用.codex-plugin/plugin.json与.mcp.jsonCursorCursor 市场使用.cursor-plugin/plugin.json与mcp.json通过仓库根部的.cursor-plugin/marketplace.json被发现。两者共享skills/lightdash-analytics与assets/品牌图片。MCP 端点使用OAuth认证安装插件后在 Agent 中完成 Lightdash 登录提示即可。端点地址的配置方式为Cursormcp.json 从环境变量LIGHTDASH_MCP_URL读取端点一份配置即可通用于所有 Lightdash 实例。首次使用前设置# Cloud 工作区 export LIGHTDASH_MCP_URLhttps://your-workspace.lightdash.cloud/api/v1/mcp # 自托管实例 export LIGHTDASH_MCP_URLhttps://your-lightdash-host/api/v1/mcpCodex.mcp.json默认指向 Lightdash Cloudapp.lightdash.cloud若使用其他工作区或自托管实例需手动替换为https://your-lightdash-host/api/v1/mcp——因为 Codex 清单格式目前不支持 URL 模板。实践要点小结顺序即正确性get_context → grep_fields → get_metadata → search_field_values → run_metric_query → get_query_result → render_chart是受源码 prompt 约束的标准调用链跳过发现直接查询会被服务端校验拒绝语义层优先治理指标的定义在语义层保持一致裸 SQLrun_sql只在语义层无法表达时兜底并受 500 行默认/5000 行上限约束空结果不是失败应把空结果作为有效答案而不是反复重试制造噪声改动必走流程dbt 与 content-as-code 改动始终在分支上经preview → validate → review → merge落地部署与 AI writeback 需用户显式授权按需读取技能用list_skills发现、read_skill精确读取相关技能避免引入无关上下文。这套技能定义与后端McpService、AI prompt 构建器、CLI 命令共同构成了 Lightdash 的Agent 安全操作语义层闭环Agent 在服务端校验与最小权限约束下发现和查询治理指标并通过受控工作流沉淀为可持续复用的分析内容。【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考