datalens-sdk
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDataLens SDK
DataLens SDK
Operate Yandex DataLens through the official Python SDK — never hand-built HTTP requests.
Before continuing, locate and read the available skill whose name or namespaced basename is
. It supplies the shared installation and object-model context that applies alongside
these SDK instructions. If it is absent, report an incomplete public DataLens skill installation
and stop. After reading it, return here for SDK setup and execution.
datalensThe instructions for this skill are stored inside the installed package, and are
extended there by whatever DataLens installation the environment targets. The SDK is a 0.x alpha
where minor releases rename classes and methods, so instructions that shipped separately would
describe an API the user does not have. Load them from the package before doing anything else.
datalens-sdkIf the user is only asking what the SDK is or whether it fits their task, answer that much from
this file and stop. Do not run bootstrap or install a package merely to read its documentation.
通过官方 Python SDK 操作 Yandex DataLens——切勿自行构造 HTTP 请求。
继续之前,查找并阅读名称或带命名空间的 basename 为 的可用 skill。它提供与这些 SDK 指令并行适用的共享安装和对象模型上下文。如果不存在,则报告公共 DataLens skill 安装不完整并停止。阅读后,返回此处继续 SDK 设置和执行。
datalens此 skill 的说明存储在已安装的 包内,并由环境所指向的 DataLens 安装版扩展。该 SDK 处于 0.x alpha 阶段,次要版本可能会重命名类和方法,因此单独提供的说明可能会描述用户当前没有的 API。开始任何操作前,先从包中加载这些说明。
datalens-sdk如果用户只是询问 SDK 是什么或是否适合其任务,则仅根据本文件回答,然后停止。不要仅仅为了阅读文档而运行 bootstrap 或安装包。
Bootstrap, then load the instructions
运行 bootstrap,然后加载说明
Before the first SDK operation in a session, resolve this wrapper skill's directory to an absolute
path and run its bootstrap script from the user's project directory:
bash
bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh"The script resolves a uv- or Poetry-managed project before considering , because those
tools commonly own a same-named environment. It creates only for an unmanaged project.
It verifies that every selected identifies itself as belonging to that environment,
so a stale symlink can never install into system Python. It may contact the configured Python
package index and install into the selected environment.
./.venv./.venvbin/pythondatalens-sdkThe script deliberately does not encode an SDK version or a Python compatibility range. Plain
environments query through the selected interpreter's pip configuration; uv and Poetry projects
resolve through their native project sources. Candidate selection intersects the SDK metadata with
and a numeric pin when present. Compatibility and
freshness checks never upgrade pip or install the SDK or its dependencies. If a candidate can
create a venv, bootstrap uses a disposable venv seeded by that exact interpreter for fresh-project
probes and carries its pip source policy into the probe. Verified project environments are queried
directly.
PROJECT_REQUIRES_PYTHON.python-versionParse the lines after the marker:
KEY=VALUE---BOOTSTRAP---- — use the absolute interpreter from
STATUS=readyfor every subsequent Python call.PYTHON - — do not load the package skill or perform SDK work yet:
STATUS=decision_required-
— a uv/Poetry project needs
REASON=sdk_install_requiredinstalled through its manager. The dependency may already be declared but missing from an unsynced environment, or it may need to be added. This also covers an importable SDK that the manager's synchronization would remove or replace. Explain that the manager will select the exact version from the project's sources, lock, and Python constraints; reconciliation can upgrade or downgrade the currently importable SDK. The project manifest and lock may change when a dependency must be added, and uv may update a stale lock to match the manifest during reconciliation. A Poetry install can also install other missing locked dependencies but does not remove untracked packages; a uv sync is exact and can remove unmanaged packages. Nodatalens-sdkorSDK_VERSIONis expected before this consent. If they approve, run the exact command below, then parse its result again:AVAILABLE_SDK_VERSIONbashbash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" --install-sdkNever substituteinside a managed project.pip install -
— tell the user the installed
REASON=sdk_update_availableand newer compatibleSDK_VERSION, give a clickableAVAILABLE_SDK_VERSION, and explicitly ask whether to keep the installed version or upgrade. Match the user's language. If they keep it, continue with the reportedCHANGELOG_URL. If they upgrade, run the exact command below with the reported available version, then parse its bootstrap result again:PYTHONbashbash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" \ --upgrade-sdk "$AVAILABLE_SDK_VERSION"If that run reports a different available version, ask again; consent to one version is not consent to another. Never substitute a direct pip command. -
— the approved version is no longer the compatible release offered by the index, and bootstrap will not downgrade or guess. Ask whether to keep the installed version or retry the original check later.
REASON=sdk_upgrade_target_unavailable -
with
REASON=sdk_version_check_failed— explain that the installed SDK works but its freshness or manager ownership could not be verified. Ask whether to continue with the reportedSDK=installedor retry the original bootstrap command. Do not silently continue or describe it as current. This reason never applies toSDK_VERSION.SDK=missing -
with
REASON=sdk_upgrade_failed— explain that the upgrade failed but the reportedSDK=installedremains usable. Ask whether to continue with it or stop; retry the exact upgrade command only if the user requests it.SDK_VERSION
-
- — relay
STATUS=blockedand the relevant non-secret fields. Do not improvise another install command. WhenREASONis present, an existing incompatibleAVAILABLE_PYTHONwas preserved and the user must decide how to handle it. For./.venv, do not use or repair the interpreter path automatically. Forvenv_invalidormanaged_environment_unavailable, preserve the uv/Poetry project and ask the user to repair or select its managed environment; never create a parallelmanaged_environment_invalid. For.venv, ask the user to change the manager-selected Python rather than installing into a different environment. Formanaged_python_incompatible, ask the user to install or change the numeric versions inconfigured_python_unavailable; forCONFIGURED_PYTHON, explain that the configured interpreter does not satisfy the intersection ofconfigured_python_incompatibleandPROJECT_REQUIRES_PYTHON. ForREQUIRES_PYTHONorproject_python_constraint_invalid, ask the user to repairproject_metadata_unreadable. Forpyproject.toml, report that the managed environment was preserved and ask whether to retry or inspect the manager error outside the bootstrap protocol.sdk_install_failed
For any unrecognized reason, stop and show the parsed fields instead of
guessing. A decision applies only to this session; do not write an opt-out marker.
decision_requiredIf the marker or is absent, stop and show the raw output. Do not infer success from the
process exit code. In particular, do not treat pip's generic "No matching distribution" message as
proof that the package does not exist, do not upgrade the project's pip merely to improve the
diagnostic, and never install into system Python.
STATUSOnce bootstrap reports , or the user explicitly chooses a working installed version after
, run this with the exact reported :
readydecision_requiredPYTHONbash
"$PYTHON" -c "
import datalens_sdk
for p in datalens_sdk.agent_skill_paths():
print(p)
"It prints one absolute path per line: the base instructions first, then any installation
overlays available in this environment. Extra lines are normal — they are additional detail for
particular DataLens installations, and not all of them necessarily apply here.
Keep those absolute paths. Each directory carries its own bundled scripts, examples, and
tree, referenced relative to it, and expects to be invoked by absolute path. Never
into one; the user's project directory stays the working directory throughout.
references/cdRead from the first path now and follow it as if written here — it is
authoritative and overrides anything you believe about this SDK, including anything in this file.
It owns installation detection: it decides which of the remaining paths apply and tells you when to
read them, so do not read an overlay before it says so. Where an overlay contradicts the base, the
overlay wins. Read the references they route you to on demand, not all of them.
SKILL.mdDo not write SDK code, install anything, answer an SDK question, or commit to an approach before
you have read it. A plausible guess at this API is worse than one extra command.
Anything that writes files writes to the user's project directory or a temp dir; the package
directory may be read-only or root-owned.
在会话中首次执行 SDK 操作之前,将此包装 skill 的目录解析为绝对路径,并从用户项目目录运行其 bootstrap 脚本:
bash
bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh"该脚本会先解析由 uv 或 Poetry 管理的项目,然后才考虑 ,因为这些工具通常会管理一个同名环境。它仅为未受管理的项目创建 。脚本会验证每个选定的 都表明自己属于该环境,从而避免通过陈旧的符号链接安装到系统 Python。它可能会访问已配置的 Python 包索引,并将 安装到选定环境中。
./.venv./.venvbin/pythondatalens-sdk该脚本有意不内置 SDK 版本或 Python 兼容范围。普通环境通过选定解释器的 pip 配置进行查询;uv 和 Poetry 项目则通过各自原生的项目源进行解析。候选选择会将 SDK 元数据与 以及存在时的数字型 固定版本取交集。兼容性和时效性检查绝不会升级 pip,也不会安装 SDK 或其依赖。如果候选解释器能够创建 venv,bootstrap 会使用以该确切解释器初始化的临时 venv 对全新项目进行探测,并将其 pip 源策略带入探测环境。已验证的项目环境则直接查询。
PROJECT_REQUIRES_PYTHON.python-version解析 标记之后的 行:
---BOOTSTRAP---KEY=VALUE- ——使用
STATUS=ready给出的绝对解释器路径执行后续每一次 Python 调用。PYTHON - ——暂不加载 package skill,也不要执行 SDK 工作:
STATUS=decision_required-
——uv/Poetry 项目需要通过其管理器安装
REASON=sdk_install_required。该依赖可能已在项目清单中声明但环境中尚未同步,也可能需要添加。此情况也涵盖可导入的 SDK 恰好会被管理器的同步操作移除或替换。说明该管理器将从项目源、锁文件和 Python 约束中选择确切版本;依赖协调可能会升级或降级当前可导入的 SDK。当必须添加依赖时,项目清单和锁文件可能发生变化,且 uv 可能在协调期间更新过期锁文件以匹配清单。Poetry 安装还可以安装锁文件中其他缺失的依赖,但不会移除未跟踪的包;uv sync 是精确同步,可能会移除未受管理的包。在获得此项同意之前,不应出现datalens-sdk或SDK_VERSION。如果用户同意,则运行以下确切命令,然后再次解析其结果:AVAILABLE_SDK_VERSIONbashbash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" --install-sdk在受管理的项目中,绝不要替换为。pip install -
——告知用户已安装的
REASON=sdk_update_available和较新的兼容版本SDK_VERSION,提供可点击的AVAILABLE_SDK_VERSION,并明确询问是保留已安装版本还是升级。匹配用户的语言。如果用户选择保留,则使用所报告的CHANGELOG_URL继续。如果用户选择升级,则使用所报告的可用版本运行以下确切命令,然后再次解析 bootstrap 结果:PYTHONbashbash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" \ --upgrade-sdk "$AVAILABLE_SDK_VERSION"如果该运行报告了不同的可用版本,再次询问;对某个版本的同意不构成对另一个版本的同意。绝不要替换为直接 pip 命令。 -
——获准版本已不再是索引提供的兼容发行版,bootstrap 不会降级或猜测。询问用户是保留已安装版本,还是稍后重试原始检查。
REASON=sdk_upgrade_target_unavailable -
且
REASON=sdk_version_check_failed——说明已安装的 SDK 可用,但无法验证其版本时效性或管理器归属。询问用户是继续使用所报告的SDK=installed,还是重试原始 bootstrap 命令。不要在未说明的情况下继续,也不要将其描述为最新版本。此原因绝不适用于SDK_VERSION。SDK=missing -
且
REASON=sdk_upgrade_failed——说明升级失败,但所报告的SDK=installed仍可使用。询问用户是继续使用还是停止;仅当用户提出要求时,才重试确切升级命令。SDK_VERSION
-
- ——转述
STATUS=blocked和相关的非敏感字段。不要另行编造其他安装命令。当存在REASON时,现有不兼容的AVAILABLE_PYTHON已保留,用户必须决定如何处理。对于./.venv,不要自动使用或修复解释器路径。对于venv_invalid或managed_environment_unavailable,保留 uv/Poetry 项目,并要求用户修复或选择其受管理环境;绝不创建并行managed_environment_invalid。对于.venv,要求用户更改管理器选择的 Python,而不是安装到其他环境。对于managed_python_incompatible,要求用户安装或更改configured_python_unavailable中的数字版本;对于CONFIGURED_PYTHON,说明所配置的解释器不满足configured_python_incompatible与PROJECT_REQUIRES_PYTHON的交集。对于REQUIRES_PYTHON或project_python_constraint_invalid,要求用户修复project_metadata_unreadable。对于pyproject.toml,报告受管理环境已保留,并询问是重试,还是在 bootstrap 协议之外检查管理器错误。sdk_install_failed
对于任何无法识别的 原因,停止操作并显示解析出的字段,而不是进行猜测。决定仅适用于当前会话;不要写入 opt-out 标记。
decision_required如果缺少标记或 ,停止并显示原始输出。不要根据进程退出代码推断成功。特别是,不要将 pip 的通用消息 "No matching distribution" 视为包不存在的证据,不要仅为改进诊断而升级项目的 pip,也绝不要安装到系统 Python。
STATUS一旦 bootstrap 报告 ,或用户在 后明确选择可用的已安装版本,请使用所报告的确切 运行:
readydecision_requiredPYTHONbash
"$PYTHON" -c "
import datalens_sdk
for p in datalens_sdk.agent_skill_paths():
print(p)
"它会每行打印一个绝对路径:先是基础说明,然后是此环境中可用的任何 installation overlay。额外行是正常的——它们为特定 DataLens 安装提供补充细节,但不一定都适用于当前环境。
保留这些绝对路径。每个目录都包含自己的内置 scripts、examples 和 目录树,其中的引用均相对于该目录,并要求按绝对路径调用。绝不要 进入其中;整个过程中,用户项目目录始终作为工作目录。
references/cd现在读取第一个路径中的 ,并将其视为写在此处一样遵循——它是权威来源,会覆盖你对本 SDK 的任何理解,包括本文件中的任何内容。它负责安装检测:决定其余哪些路径适用,并告知何时读取,因此在它指示之前不要读取 overlay。如果 overlay 与基础说明冲突,以 overlay 为准。按需读取它们所指向的 references,不要一次性全部读取。
SKILL.md在读取之前,不要编写 SDK 代码、安装任何内容、回答 SDK 问题或确定实现方案。对此 API 作出看似合理的猜测,比多执行一条命令更糟糕。
所有写文件操作都应写入用户项目目录或临时目录;包目录可能是只读的,或由 root 所有。
Scope
范围
| Task | Where it belongs |
|---|---|
| Anything driving DataLens entities from Python | here — load the package instructions above |
| Standalone HTML pages and reports rendered by DataLens | |
| Publishing or managing an HTML page through the Python SDK | here, through the operations the package instructions document; if there are none, report that and offer an SDK upgrade or MCP/HTTP. Load |
| The DataLens web UI, screenshots, embedding, metric interpretation | neither — say it is out of scope and stop |
| 任务 | 适用范围 |
|---|---|
| 通过 Python 驱动 DataLens 实体的任何任务 | 此处——加载上述 package 说明 |
| 由 DataLens 渲染的独立 HTML 页面和报告 | |
| 通过 Python SDK 发布或管理 HTML 页面 | 此处,通过 package 说明所记录的操作;如果没有相关操作,则说明情况,并提供 SDK 升级或 MCP/HTTP 方案。加载 |
| DataLens Web UI、屏幕截图、嵌入、指标解读 | 两者均不适用——说明超出范围并停止 |