lkr-project-helper

用途

lkr-project-helper 是一个面向 AI 智能体的技能，用于端到端处理 Looker LookML 项目的创建工作。它把项目初始化、数据库连接验证、LookML 自动生成、本地与远端文件同步、校验、提交和部署串联成一套可执行流程，并配套 lkr-code-mode 沙箱脚本来调用 Python Looker SDK。

安装

在智能体工作区中使用 npx skills 安装：

npx skills add lkrdev/cli --skill lkr-project-helper

该技能与 lkr-code-mode 技能配合使用：

npx skills add lkrdev/cli --skill lkr-code-mode

沙箱脚本通过以下命令执行：

uvx --from "lkr-dev-cli[codemode]" lkr-dev-cli code-mode sandbox

主要能力

项目与裸 Git 初始化：使用 ensure_project_and_model.py 以 --dev-mode 创建项目（create_project）、配置 git_service_name: "bare"、初始化开发者副本（create_developer_copy）并注册初始模型配置。
连接检查：inspect_connections.py 可列出实例上的数据库连接、测试连接健康状态并查看 schema 与表。若要从原始 SQL 实例化，目标连接需配置 tmp_db_name（临时 schema/dataset）且 Looker 具备写入权限以创建临时视图。
LookML 生成：支持三种实例化来源。
- Pattern A：基于 schema 与表，通过 generate_lookml.py 调用 generate_lookml_with_new_files。该方法在生成前快照现有文件，运行 Looker 的 LookML 生成器，返回 new_files 中所有新建的 .view.lkml 与 .model.lkml 文件。参数包括 project_id、connection、model_name、folder_name、file_type_for_explores（"model"、"explore" 或 "none"）、generate_descriptions（默认 True）以及包含 tables 和/或 semantic_generation_input 的 body。
- Pattern B：基于原始 SQL，使用 bq_view_lookml_generator.py 先读取连接的 tmp_db_name，执行 CREATE OR REPLACE VIEW 创建临时视图，再对其调用 generate_lookml_with_new_files 以获取准确的列类型并生成完整维度与度量，随后 DROP VIEW IF EXISTS，并返回生成文件的直接 URL。若连接无 tmp_db_name 或用户希望使用纯 LookML 派生表（derived_table: { sql: ... ;; }），可改用 create_custom_view.py。
- Pattern C：基于自然语言语义意图，通过 generate_lookml.py 传入 user_intention 与 questions 等参数生成 LookML。
本地文件拉取与推送：使用 uvx lkr-dev-cli tools lookml pull 将远端 LookML 文件拉取到本地目录；使用 uvx lkr-dev-cli tools lookml push 推送本地 LookML 文件夹。push 默认会先将开发者工作区重置到生产环境（reset_project_to_production，失败时回退到 create_developer_copy），可通过 --no-reset 跳过重置以在未提交的开发者改动之上增量推送；遇到 .model.lkml 文件时会自动检查连接声明、调用 all_lookml_models()，并按需调用 create_lookml_model 或 update_lookml_model；加 --deploy 可部署并重置工作区；加 --file 可只推送单个文件且不删除远端孤立文件。
严格校验与部署：deploy_and_reset_workspace.py 以 --dev-mode 运行，执行 LookML 语法校验（validate_project）并在出错时中止，然后提交、部署到生产环境（deploy_to_production）并重置开发者工作区。

使用方式

标准工作流如下：

检查认证与数据库连接（inspect_connections.py）。
向用户确认实例化来源：schema 与表、原始 SQL 查询，还是业务语义/自然语言意图。
确保项目、裸 Git、开发者副本与模型配置存在（ensure_project_and_model.py --dev-mode）。
按所选模式生成 LookML 视图与 Explore，并检查新建文件路径。
用 lookml pull / push 在本地与 Looker 之间同步文件。
运行 deploy_and_reset_workspace.py 完成校验、提交、部署与工作区重置。

示例命令（节选）：

# 检查连接
uvx --from "lkr-dev-cli[codemode]" lkr-dev-cli code-mode sandbox \
  --file=.agents/skills/lkr-project-helper/scripts/inspect_connections.py

# 初始化项目与模型
uvx --from "lkr-dev-cli[codemode]" lkr-dev-cli code-mode sandbox --dev-mode \
  --file=.agents/skills/lkr-project-helper/scripts/ensure_project_and_model.py \
  --var project_name="my_new_project" \
  --var model_name="my_model" \
  --var connection_name="looker-private-demo"

# 从表生成 LookML
uvx --from "lkr-dev-cli[codemode]" lkr-dev-cli code-mode sandbox --dev-mode \
  --file=.agents/skills/lkr-project-helper/scripts/generate_lookml.py \
  --var project_name="my_new_project" \
  --var model_name="my_model" \
  --var connection_name="looker-private-demo" \
  --var schema_name="ecomm" \
  --var table_names="orders,order_items,users" \
  --var folder_name="views" \
  --var file_type_for_explores="model"

# 从原始 SQL 生成
uvx --from "lkr-dev-cli[codemode]" lkr-dev-cli code-mode sandbox --dev-mode \
  --file=.agents/skills/lkr-project-helper/scripts/bq_view_lookml_generator.py \
  --var project="my_new_project" \
  --var connection="looker-private-demo" \
  --var model="my_model" \
  --var view_name="order_summary_view" \
  --var sql_content="SELECT status, COUNT(*) AS order_count FROM `ecomm.orders` GROUP BY 1"

# 拉取与推送
uvx lkr-dev-cli tools lookml pull ./my_new_project --project-id="my_new_project"
uvx lkr-dev-cli tools lookml push ./my_new_project --project-id="my_new_project" --deploy

# 校验、部署并重置
uvx --from "lkr-dev-cli[codemode]" lkr-dev-cli code-mode sandbox --dev-mode \
  --file=.agents/skills/lkr-project-helper/scripts/deploy_and_reset_workspace.py \
  --var project_name="my_new_project" \
  --var commit_message="Initial LookML project setup and deployment" \
  --var strict="true"

配套脚本还包括 init_project.py、configure_model.py、validate_and_commit.py、upload_assets.py（上传非 LookML 资源，如 .js、.css、.json）与 migrate_dashboard_to_udd.py（将 LookML 仪表盘转换为 UDD）。

适用场景

需要从数据库表、原始 SQL 或业务意图快速搭建新的 Looker LookML 项目。
需要以裸 Git 仓库模式管理 LookML 项目并在开发者副本上迭代。
希望在部署前执行严格的 LookML 语法校验并自动提交与发布。
需要将 Looker 上的 LookML 文件同步到本地进行检查或修改。

限制

需要可用的 Looker 实例、相应认证与数据库连接环境；具体账号与权限要求资料未提供。
从原始 SQL 创建临时视图要求连接配置了 tmp_db_name 且具备写入权限，否则需改用派生表方式。
所有开发工作区相关脚本需使用 --dev-mode；具体参数细节以资料所列脚本与命令为准。
关于该技能的收费、版本与支持范围，资料暂未提供。

技能介绍

用途

安装

主要能力

使用方式

适用场景

限制