databricks-setup-local

Databricks Setup-Local

必须首先执行： 使用 databricks-core 处理 CLI、身份验证和配置文件选择。切勿使用默认配置文件。对于现有环境，请使用 databricks-execution-compute。

工作流

1. 检查 CLI 和身份验证

CLI 必须为 v1.16.0 或更高版本——该版本新增了 --no-dbconnect 和本技能会处理的 E_PROVISION_CONFLICT 故障。请进行确定性比较，切勿凭目测判断版本（1.9.0 早于 1.16.0，字符串字典序比较会得出错误结果）。首先运行此检查，如果退出码非零，请勿继续：

# Subshell so a failed gate reports non-zero without closing a persistent shell.
(
  # Read stdout only -- upgrade nags on stderr carry their own semver and would win the parse.
  if ! raw="$(databricks version 2>/dev/null)"; then
    echo "STOP: databricks CLI is missing or failed to run -- install or upgrade it via databricks-core first"
    exit 1
  fi
  have="$(printf '%s\n' "$raw" | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | head -n1 | tr -d v)"
  [ -n "$have" ] || have="$(printf '%s\n' "$raw" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)"
  if [ -z "$have" ]; then
    echo "STOP: could not read a version from 'databricks version' -- upgrade via databricks-core first"
    exit 1
  fi
  case "$raw" in
    *-dev*)
      echo "NOTE: dev build $have -- the floor cannot be checked; ask the user to confirm this build has setup-local"
      ;;
    *)
      if [ "$(printf '%s\n%s\n' "1.16.0" "$have" | sort -V | head -n1)" != "1.16.0" ]; then
        echo "STOP: databricks CLI $have is older than v1.16.0, the floor this skill requires -- older CLIs can run setup-local but not as documented here; upgrade via databricks-core first"
        exit 1
      fi
      ;;
  esac
)

只有检查通过后，才能使用所选配置文件进行身份验证：

databricks auth describe --profile <PROFILE>

优先使用最新的稳定版 CLI；无需在线查询。如果检查退出码非零（版本低于 v1.16.0、未安装 CLI，或无法读取版本），或者帮助信息中没有 setup-local、报告 unknown command，或拒绝本技能要求传入的标志，请停止。如果输出 NOTE: dev build，则无法验证最低版本要求——请先向用户确认再继续。使用 databricks-core 并经批准后升级，然后进行验证；切勿手动重新创建 setup-local。

所有工作区命令都使用所选配置文件。未经批准，不要转换为其他包管理器。

2. 确认项目目录

确认包含（或计划包含）pyproject.toml、.venv 和 uv.lock 的根目录；如果可能存在多个根目录，请询问用户。预览和应用时都使用该目录。该目录必须是全新项目，或由 uv 管理，但预览时不必可写。

3. 选择一个目标

恰好选择一个分支：

• 集群： 使用 --cluster-id <ID> 或 --cluster-name <NAME>。如果集群未知，请使用所选配置文件列出集群并询问用户；参见示例。
• Serverless： 使用 --serverless-version <N>。没有可列出版本的命令；如果未指定版本，请询问用户。
• 作业任务： 使用 --job-task <JOB_ID>.<TASK_KEY>。如果任务未知，请运行 databricks jobs get <JOB_ID> --profile <PROFILE> --output json，列出任务键并询问用户。
• Bundle： 使用包含 databricks.yml 的项目。使用 databricks-dabs 检查其根目录和所选目标。只有当该目标解析为受支持的经典计算或 Serverless 计算时，才省略计算标志；否则请询问用户。对于命名目标，请添加 --target <BUNDLE_TARGET>。

切勿组合使用计算标志。如果无法确定分支，请询问用户。

4. 预览

先进行试运行；该操作不会写入或安装任何内容：

databricks environments setup-local --profile <PROFILE> <TARGET_ARGS> --dry-run --output json

对于 Bundle，<TARGET_ARGS> 为空，或为 --target <BUNDLE_TARGET>。默认使用普通模式。仅当用户明确表示不希望此命令管理 databricks-connect 时，才使用 --no-dbconnect；即使如此，结果中的 mode 仍会报告为 constraints-only。参见 JSON 输出 和示例。

5. 获取批准并应用

应用之前，请确认目录可写，并运行 uv --version。安装 uv 前请先询问；切勿擅自设置 DATABRICKS_LOCALENV_AUTO_INSTALL_UV=1 或运行远程安装程序。

向用户展示目标、版本、警告、plan.diff 和目录。说明应用操作可能会：

• 备份并重写 pyproject.toml；
• 安装 Python 和依赖项；
• 更新 .venv 和 uv.lock。

如果 Bundle 中使用 --serverless-version N，还要说明应用后会同步作业 YAML（如下所述），确保用户的批准同时涵盖这两项修改。

只有在用户请求配置，或批准了针对指定目录的计划后，才能应用。保留目录、配置文件、目标和模式。

如果预览后目录、配置文件、目标、模式或项目文件发生变化，请重新运行 --dry-run，展示新计划并再次获取批准。将其解析出的 Python、databricks-connect 和托管约束视为权威结果；不要替换为猜测的版本。用户管理的依赖项冲突应单独协调，并需获得批准。

6. 处理结果

• ok: true：如果目标是 bundle 且指定了 --serverless-version N，则在 YAML 源文件中将每个现有 job 的 environments[].spec.environment_version 更新为 "N"，然后验证 bundle。如果没有此类 job，则进行说明；不要自行创建。对于 cluster 和 job-task 目标，跳过此步骤。报告目标、版本、警告和 venvPath；优先使用 uv run <cmd>，或根据 venvPath 推导平台特定的解释器。
• ok: false：使用 troubleshooting。在执行会修改文件的诊断操作和提交外部问题之前，先征求同意。
• 没有 JSON：检查 stderr，查看是否存在发生在 pipeline 启动前的 CLI、身份验证、目录或缓存错误。