lookml-reviewer

LookML 审查技能

此技能使用 Looker CLI（looker-cli）对 LookML 文件进行严格的代码审计，并依据随附的一组最佳实践参考资料和风格指南进行检查。

工作流说明

调用时，请严格执行以下步骤：

1. 预检防护与验证： 在请求详细信息或获取代码之前，验证 looker-cli 已安装并完成身份验证：

   • 验证 CLI 安装情况： 运行：looker-cli --help 如果命令失败或找不到该命令：立即停止，并告知用户：

     "looker-cli 未安装或不在 PATH 中。请参阅 Looker CLI 文档中的安装说明：https://github.com/looker-open-source/looker-cli"

   • 验证身份验证与 Looker 配置： 运行：looker-cli user me 如果尚未通过身份验证或连接失败：立即停止，并告知用户：

     "你尚未通过身份验证连接到 Looker 实例。请使用以下任一方法配置并验证 looker-cli：

     方法 1：交互式 OAuth（推荐）

     1. 在 Looker 中，确保已启用 Looker CLI 连接器： 前往 Admin > Platform > BI Connectors > 在 Developer Tools 下，将 Looker CLI 切换为 ON。
     2. 配置个人资料并登录：

        looker-cli profile add default --host <your-looker-host> --port 443
        looker-cli profile use default
        looker-cli session login --oauth
        

     方法 2：API 密钥（客户端 ID 和客户端密钥） 如果未启用 OAuth，或用于无头／服务账户：

     looker-cli profile add default --host <your-looker-host> --port 443 --client-id <CLIENT_ID> --client-secret <CLIENT_SECRET>
     looker-cli profile use default
     

     配置完成后，请重新提交审查请求。"

2. 了解审查范围并验证分支：

   • 确认 Looker 实例 URL（例如，https://<instance>.looker.com 或 https://<instance-id>.<region>.looker.app）、Looker 项目名称（例如，fashionly）、目标分支，以及用户希望审查整个项目还是某个特定的 LookML 文件（例如，views/order_items.view.lkml）。
   • 关键——Looker 实例 URL：如果未提及 Looker 实例 URL，必须先询问用户并要求其提供，然后才能继续。
   • 关键：除非用户已在请求中明确提供，否则必须先询问用户的项目名称和分支名称，然后才能继续。
   • 关键防护——分支验证（不要创建分支）：
     • 确保会话工作区处于开发模式：

       looker-cli session update dev
       

     • 检查所有现有分支：

       looker-cli project branch <project_id> --all
       

     • 如果分支不存在，不要创建分支。 切勿使用会创建分支的命令或 API 调用。
     • master / main 等效处理：如果用户请求 master，但仅存在 main（反之亦然），则自动映射到现有分支（main 或 master），并告知用户。
     • 未找到分支：如果指定分支（或其 master／main 等效分支）不在分支列表中，立即停止，向用户列出可用分支，并请求其澄清。

3. 通过 looker-cli 获取 LookML 文件：

   • 检出目标分支：

     looker-cli project checkout <project_id> <branch_name>
     

     • 冲突防护：如果因当前开发工作区存在未提交的本地更改或检出冲突而导致检出失败，请立即停止。向用户报告冲突文件，并请他们在 Looker 中提交或丢弃更改，然后再重试。
   • 列出项目文件：获取项目的文件列表：

     looker-cli project file ls <project_id>
     

   • 获取文件内容：
     • 单文件模式：如果用户明确提到某个 LookML 文件，请确认该文件存在于项目文件列表中，并且只获取该文件：

       looker-cli project file cat <project_id> <file_path>
       

       (如果找不到该文件，请停止操作，列出匹配的项目文件，并请用户澄清。)
     • 完整项目模式：如果未指定单个文件，则读取每个 LookML 文件（*.model.lkml、*.explore.lkml、*.view.lkml、manifest.lkml 和配置文件）的内容：

       looker-cli project file cat <project_id> <file_path>
       

4. 分析代码库／目标文件：

   • 根据 Looker 最佳实践对获取的 LookML 文件进行全面分析（参阅 references/ 中的指南：conversational-analytics-best-practices.md、lams-style-guide.md、lookml-dos-and-donts.md 和 sustainable-maintainable-lookml.md）。
   • 如果审查单个文件，请全面审计该文件（检查字段定义、主键、外键、命名规范、描述、count 度量的过滤条件，以及对话式分析就绪情况）。
   • 如果审查完整项目，请从整体上分析项目，提供全面审查结果（检查模型与 Explore 的关系、视图连接、主键、datagroup、命名规范，以及对话式分析就绪情况）。

5. 编写报告：根据分析结果起草一份详尽全面的审查报告。报告必须包含以下部分：

   • 摘要：概述目标文件或完整代码库的健康状况，注明所审查的项目、分支和目标文件（单文件模式），并列出主要发现。
   • 优点：以项目符号列出表现出色的代码模式。
   • 改进项：按文件详细列出违规项。对于每项：
     • 清楚描述违规情况。请勿在报告中明确列出或复述完整规则。
     • 准确说明如何修复（提供具体的修复前／修复后代码片段）。
     • 重要：注明违规的确切文件路径和行号（例如：views/order_items.view.lkml:L16-L19）。使用 Looker 实例 URL 构造指向 Looker IDE 中文件的直接链接：<instance_url>/projects/<project_id>/files/<file_path>。

6. 输出报告：整理报告并直接在聊天或控制台中输出，作为主要响应。不要将报告保存到文件或其他载体。