datalens-sdk

DataLens SDK

通过官方 Python SDK 操作 Yandex DataLens — 切勿手动构造 HTTP 请求。

继续之前，请查找并阅读名称或命名空间限定名称的基名为 datalens 的可用技能。它提供适用于这些 SDK 说明的通用安装和对象模型背景信息。如果缺少该技能，请报告 DataLens 公共技能安装不完整并停止。阅读后，返回此处进行 SDK 设置和执行。

此技能的说明存储在已安装的 datalens-sdk 包中，并会根据环境所针对的 DataLens 安装情况进行扩展。SDK 目前处于 0.x alpha 阶段，次版本更新可能会重命名类和方法，因此单独发布的说明可能描述的是用户并未安装的 API。在执行任何操作之前，请先从包中加载说明。

如果用户只是在询问 SDK 是什么，或是否适合其任务，请仅根据此文件回答，然后停止。不要仅为阅读文档而运行引导程序或安装包。

引导，然后加载说明

在会话中首次执行 SDK 操作之前，请将此包装技能的目录解析为绝对路径，并在用户的项目目录中运行其引导脚本：

bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh"

脚本会先解析由 uv 或 Poetry 管理的项目，再考虑 ./.venv，因为这些工具通常会管理同名环境。仅当项目不受管理时，才会创建 ./.venv。脚本会验证每个被选中的 bin/python 是否确认自身属于该环境，从而确保过时的符号链接绝不会将包安装到系统 Python 中。脚本可能会联系已配置的 Python 包索引，并将 datalens-sdk 安装到所选环境中。

脚本不会写死 SDK 版本或 Python 兼容性范围。普通环境会通过所选解释器的 pip 配置查询；uv 和 Poetry 项目则通过其原生项目源解析。候选版本会同时满足 SDK 元数据、PROJECT_REQUIRES_PYTHON 要求，以及（如有）数值格式的 .python-version 固定版本。兼容性和最新版本检查绝不会升级 pip，也不会安装 SDK 或其依赖。如果候选解释器可以创建虚拟环境，引导程序会使用该确切解释器创建临时虚拟环境，用于检查全新项目，并将其 pip 源策略传递给该检查。已验证的项目环境会被直接查询。

解析 ---BOOTSTRAP--- 标记之后的 KEY=VALUE 行：

• STATUS=ready — 后续每次调用 Python 都使用 PYTHON 中的绝对路径。
• STATUS=decision_required — 暂不加载包技能或执行 SDK 操作：

  • REASON=sdk_install_required — uv/Poetry 项目需要通过其包管理器安装 datalens-sdk。可能是依赖已声明但尚未同步到环境中，也可能需要添加该依赖。此情况也包括 SDK 虽可导入，但包管理器同步时会将其移除或替换。请说明包管理器将根据项目的软件源、锁文件和 Python 约束选择确切版本；协调操作可能会升级或降级当前可导入的 SDK。如果必须添加依赖，项目清单和锁文件可能会发生变化；协调时，uv 也可能会更新过时的锁文件，使其与项目清单一致。Poetry 安装还可能安装其他缺失的锁定依赖，但不会移除未跟踪的包；uv sync 则会严格同步，并可能移除未受管理的包。在获得此同意之前，不应出现 SDK_VERSION 或 AVAILABLE_SDK_VERSION。如果用户同意，请运行以下确切命令，然后再次解析其结果：

    bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" --install-sdk
    

    切勿在受管理的项目中改用 pip install。

  • REASON=sdk_update_available — 告知用户已安装的 SDK_VERSION 和更新且兼容的 AVAILABLE_SDK_VERSION，提供可点击的 CHANGELOG_URL，并明确询问是保留已安装版本还是升级。使用与用户相同的语言。如果用户选择保留，请使用报告中的 PYTHON 继续。如果用户选择升级，请使用报告的可用版本运行下方的确切命令，然后再次解析其引导结果：

    bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" \
      --upgrade-sdk "$AVAILABLE_SDK_VERSION"
    

    如果这次运行报告了不同的可用版本，请再次询问；用户同意一个版本，不代表同意另一个版本。切勿改用直接的 pip 命令。

  • REASON=sdk_upgrade_target_unavailable — 索引当前提供的兼容版本已不是获准的版本，引导程序不会降级或猜测。询问用户是保留已安装版本，还是稍后重试原始检查。

  • REASON=sdk_version_check_failed 且 SDK=installed — 说明已安装的 SDK 可以正常工作，但无法验证其是否为最新版本，或是否由管理器管理。询问用户是使用报告中的 SDK_VERSION 继续，还是重试原始引导命令。不得默默继续，也不得称其为最新版本。此原因不适用于 SDK=missing。

  • REASON=sdk_upgrade_failed 且 SDK=installed — 说明升级失败，但报告中的 SDK_VERSION 仍可使用。询问用户是使用该版本继续还是停止；只有用户要求时，才重试确切的升级命令。

• STATUS=blocked — 转达 REASON 和相关的非敏感字段。不要擅自改用其他安装命令。如果存在 AVAILABLE_PYTHON，则现有的不兼容 ./.venv 已保留，必须由用户决定如何处理。对于 venv_invalid，不要自动使用或修复该解释器路径。对于 managed_environment_unavailable 或 managed_environment_invalid，保留 uv/Poetry 项目，并请用户修复或选择其受管理的环境；切勿创建并行的 .venv。对于 managed_python_incompatible，请用户更改管理器选定的 Python，而不是安装到其他环境。对于 configured_python_unavailable，请用户安装或更改 CONFIGURED_PYTHON 中的数值版本；对于 configured_python_incompatible，说明所配置的解释器不满足 PROJECT_REQUIRES_PYTHON 和 REQUIRES_PYTHON 的交集。对于 project_python_constraint_invalid 或 project_metadata_unreadable，请用户修复 pyproject.toml。对于 sdk_install_failed，说明受管理的环境已保留，并询问用户是重试，还是在引导协议之外检查管理器错误。

对于任何无法识别的 decision_required 原因，请停止并显示已解析的字段，不要猜测。决定仅适用于本次会话；不要写入选择退出标记。

如果标记或 STATUS 缺失，请停止并显示原始输出。不要根据进程退出代码推断成功。尤其是，不要将 pip 的通用 “No matching distribution” 消息视为软件包不存在的证据；也不要仅为改善诊断而升级项目的 pip，更不要安装到系统 Python 中。

引导程序报告 ready 后，或用户在 decision_required 后明确选择继续使用可正常工作的已安装版本后，使用报告的确切 PYTHON 运行以下命令：

"$PYTHON" -c "
import datalens_sdk
for p in datalens_sdk.agent_skill_paths():
    print(p)
"

每行会输出一个绝对路径：先是基础说明，然后是此环境中可用的任何安装覆盖项。出现额外行是正常的 — 它们是特定 DataLens 安装的附加说明，不一定都适用于此处。 请保留这些绝对路径。 每个目录都包含自己的脚本、示例和 references/ 目录树，相关内容均通过相对于该目录的路径引用，并且要求通过绝对路径调用。切勿进入这些目录；在整个过程中，用户的项目目录都应保持为工作目录。

现在从第一个路径读取 SKILL.md，并将其视为本文内容并遵照执行——它具有权威性，优先于你对这个 SDK 的任何认知，包括本文中的任何内容。它负责检测安装情况：由它决定其余路径中哪些适用，以及何时读取这些路径，因此在它指示之前不要读取任何覆盖说明。如果覆盖说明与基础说明相矛盾，以覆盖说明为准。按需读取它们指向的参考资料，不要一次读完全部内容。

在读取之前，不要编写 SDK 代码、安装任何内容、回答 SDK 相关问题，也不要确定采用某种方案。对这个 API 做出看似合理的猜测，还不如多执行一条命令。

任何写入文件的操作都应写入用户的项目目录或临时目录；软件包目录可能是只读的，也可能归 root 所有。

范围

任务	适用位置
使用 Python 驱动 DataLens 实体的任何操作	此处——加载上方的软件包说明
由 DataLens 渲染的独立 HTML 页面和报告	datalens-html-pages
通过 Python SDK 发布或管理 HTML 页面	此处，通过软件包说明记录的操作进行；如果没有相关操作，请说明这一点，并提供升级 SDK 或使用 MCP/HTTP 的方案。加载 datalens-html-pages，以获取发布流程和最终链接
DataLens 网页 UI、屏幕截图、嵌入、指标解读	两者都不适用——说明这不在范围内，然后停止