关于 datalens
DataLens 是商业智能与数据可视化系统，此技能负责引导用户选择合适的操作接口。它区分 Python SDK、MCP 服务、HTTP API 和 Web UI，并说明不同部署方式的注意事项。
主要功能
- 01说明实体的数据流转
- 02区分不同部署类型
- 03为任务选择操作接口
- 04指导使用对象 ID
- 05界定不支持的任务
适用场景
- 01选择 DataLens 自动化接口
- 02规划数据集和仪表板操作
- 03确认部署相关的 API 要求
- 04避免对 ID 或容器作出假设
MCP 相关
此技能将 Agent 会话中的交互式任务引导至 `@datalens-tech/mcp` 服务。该服务启动时获取 API 的 OpenAPI 规范，并通过 `list_commands`、`describe_commands` 和 `invoke_command` 三个工具提供命令网关。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/datalens确认已加载。
详细介绍
DataLens
DataLens 是一个商业智能和数据可视化系统：它连接数据库，将数据建模为数据集，并基于数据集生成图表和仪表板。它以托管服务的形式在 Yandex Cloud 中提供，也可部署在本地，并由 Yandex 内部运行。
本文件用于引导和路由，不会讲解任何单一接口——请从下方选择相应接口，并遵循负责该接口的技能。
数据流
database → connection → source → dataset → chart → dashboard
- 连接 — 一个数据库的凭据和驱动程序。
- 数据源 — 通过该连接公开的表或 SQL 查询。
- 数据集 — 建模层：字段、计算字段、联接、参数、行级安全。
- 图表 — 一种可视化。向导图表基于数据集；QL图表跳过数据集，直接查询连接；编辑器图表使用自定义 JavaScript。
- 仪表板 — 基于图表的标签页、组件、选择器和布局。
从左向右构建，并通过 ID 引用。删除上游对象会导致所有下游对象失效。
对象 ID 和 URL
具有明确类型的对象，其 DataLens URL 可以采用以下任一形式：
/<object_type>/<object_id>-<readable_slug>— 仅将可读后缀之前的对象 ID 传递给 API。/<object_type>/<object_id>— 没有可读后缀时，最后一个路径段整体就是对象 ID。
仪表板链接还有一种简短形式：https://datalens.ru/<dashboard_id>。当 URL 被识别为仪表板链接时，唯一的路径段就是仪表板 ID；其中没有对象类型段。例如，https://datalens.ru/bgquq1234567 指向 ID 为 bgquq1234567 的仪表板。
对于明确标注类型的对象，https://datalens.ru/connections/r6wa2j1ww5cad-demo 指向 ID 为 r6wa2j1ww5cad 的连接；demo 是便于阅读的 URL 后缀。如果 URL 为 https://datalens.ru/connections/r6wa2j1ww5cad，则将完整路径段用作 ID。连接、数据集和图表均适用同一规则。不要将根路径级别的简短形式用于这些对象类型。
将对象 ID 视为不透明值。若有 Copy ID 的值或 API 响应中的 id 字段，请优先使用。如果 URL 有歧义或不符合这些形式，不要猜测 ID。不要将对象 ID 与显示名称、可读 URL 后缀或字段 UUID 混淆。
对象模型
对象的归属位置与上述数据流是不同的维度。连接、数据集、图表和仪表板都是条目，条目存放在容器树中。有两种方案，具体安装提供哪一种各不相同：
newer collection
├── collection … nested, arbitrarily deep
└── workbook
└── entries connection, dataset, chart, dashboard
older folder tree, path-addressed e.g. Users/someone/reports
└── entries held directly, no workbook in between
在较新的方案中，工作簿是分组和权限的基本单位；在较旧的方案中，文件夹路径承担这一角色。绝不要假设当前提供的是哪一种——某个安装可能提供其中一种，也可能两种都提供。因此，请按照接口技能的说明确认，而不要针对仅支持工作簿的部署编写基于路径的逻辑。
安装类型
绝不要假设当前使用的是哪种安装类型——主机、身份验证方式以及可用的连接器和图表类型都各不相同。在编写任何与 API 交互的内容之前，请先确认安装类型。
| 安装类型 | UI | API 主机 | 身份验证 |
|---|---|---|---|
| Yandex Cloud | datalens.ru | api.datalens.tech | yc CLI IAM 令牌，以及组织 ID |
| 本地部署 | 询问用户 | 询问用户 | 因部署而异；通常为环境变量中的 OAuth 令牌 |
| Yandex Team（内部） | datalens.yandex-team.ru | api.datalens.yandex.net | 内部身份验证 |
Yandex Cloud 是托管服务。本地部署包括开源自托管版本（docker compose，UI 位于 :8080）和商业企业版。Yandex Team 是 Yandex 的内部安装版本——回答任何与其相关的具体问题之前，请先参阅下方的安装专属说明。
特定工具的技能会为你检测安装类型——例如，SDK 自带一个可报告安装类型的预检程序。不要自行编写检测逻辑。
选择接口
| 想要 | 使用 | 技能 |
|---|---|---|
| 使用 Python 管理实体——创建、更新、检查、导出、克隆 | Python SDK（PyPI 上的 datalens-sdk） | datalens-sdk |
| 让 Agent 通过工具直接调用 DataLens API | MCP 服务（@datalens-tech/mcp） | — 请参阅其 README |
| 其他编程需求 | 公共 HTTP API | — 请参阅下文 |
| 浏览、点击操作、查看渲染后的图表 | Web UI | — 供人使用，不适用于 Agent |
SDK 与 MCP。 对于任何脚本化、可重复或提交到代码仓库的任务，SDK 都是默认选择——它有类型定义和完善的对象模型，而且工作成果会以代码形式保留下来。MCP 服务适合在 Agent 会话中进行交互式的一次性操作：它会在启动时获取 API 的 OpenAPI 规范，并提供一个包含三个工具的网关（list_commands → describe_commands → invoke_command），而不是数百个工具。不要在同一任务中混用两者。
两者都不适用时，使用 HTTP API。 SDK 和 MCP 服务都基于该 API 构建，因此只有在它们无法满足需求时，才直接调用 HTTP API。它采用 RPC 风格而非 REST 风格：你需要使用 JSON 负载调用具名命令，而不是操作资源。它还支持自描述——从安装环境的 API 主机上的 /json/ 获取 OpenAPI 规范（参见上文的 安装环境；云端地址为 https://api.datalens.tech/json/），并根据规范操作，不要猜测命令名称或负载结构。在云端，必须提供组织 ID，并通过 x-dl-org-id 标头发送。
特定安装环境的说明
有两种安装环境不会提供你需要的信息，遇到这两种情况时，都应询问，而不是自行补全。
Yandex Team 通过单独分发的技能 datalens-yateam 扩展。如果可用技能列表中包含该技能，且环境面向该安装环境，请调用它：该技能会补充并覆盖本文档中的特定安装环境说明；若两者有冲突，以该技能为准。如果任务涉及 Yandex Team，但列表中没有该技能，请停止并请用户按照 https://datalens.yandex-team.ru/get-skills 中的说明安装。与此同时，不要自行推断其内容——说明答案中的哪部分取决于安装环境，并将其留待确认。
本地部署版不会公布任何端点，而且 API 不一定与 UI 位于同一主机上。在编写任何会与这两者通信的内容之前，请停止并向用户询问 DataLens 端点和 DataLens API 端点。不要根据其中一个推导另一个，不要回退到云端默认值，也不要使用占位符继续操作。
不在讨论范围内
明确说明边界，并停止操作，不要临时拼凑相邻解决方案：
- 指标在业务上代表什么，或某个数值看起来是否正确。
- 对 Web UI 截图或进行自动化操作。
- 将 DataLens 嵌入其他产品，或使用 iframe。
- 不涉及 DataLens 实体的 SQL 和分析。