dx-code-analyzer-configure

配置 Code Analyzer 技能

概述

生态系统： 此技能属于由 3 个技能组成的 Code Analyzer 套件 — dx-code-analyzer-run（扫描与结果）· dx-code-analyzer-configure（设置、配置、CI/CD）· dx-code-analyzer-custom-rule-create（自定义规则编写）。

此技能用于管理 code-analyzer.yml 配置文件，这是决定 Code Analyzer 在项目中如何运行的唯一事实来源。所有自定义设置（引擎、规则、忽略项、抑制项）都通过创建或编辑此文件完成。如果文件不存在，此技能会在当前工作目录中创建该文件。

---

范围

范围内：

• 检查先决条件（sf CLI、Java、Node.js、Python、组织身份验证）
• 安装或更新 Code Analyzer 插件
• 如果 code-analyzer.yml 不存在，则创建该文件
• 编辑 code-analyzer.yml 以进行所有配置更改
• 引擎设置、规则覆盖、忽略模式、抑制项
• CI/CD 流水线设置（GitHub Actions、Jenkins 等）
• 环境验证与故障排除

范围外：

• 运行扫描 → 使用 dx-code-analyzer-run 技能
• 修复违规项、解释规则、管理抑制项 → 使用 dx-code-analyzer-run 技能
• 创建自定义规则 → 使用 dx-code-analyzer-custom-rule-create 技能

---

工具使用规则

允许： Bash（sf、java、node、python3、npm）、Read、Write、Edit 禁止： MCP 工具、Agent 工具、Web 工具、其他技能、which、find、locate、搜索二进制文件

---

核心原则：仅在自定义时使用 YAML

Code Analyzer 开箱即用，无需配置文件——所有默认设置都内置于工具中。仅当用户明确要求进行自定义时，才创建 code-analyzer.yml 文件。

规则：

• 不要主动创建 code-analyzer.yml——仅在用户要求更改某项设置时创建
• 不要重复内置默认设置——仅编写有意覆盖行为的条目
• 始终将文件放在项目根目录——即 sfdx-project.json 或 sf-project.json 所在的位置
• CLI 会自动发现该文件——在项目根目录运行 sf code-analyzer run 时，会自动读取该目录中的 code-analyzer.yml。无需使用 --config-file 标志。
• 用户只说“配置 code analyzer”，却没有说明具体需求？→ 询问他们想自定义什么。不要创建空文件或模板文件。

工作流：

1. 用户请求自定义设置（例如“禁用 PMD”“忽略测试文件”“增加 SFGE 内存”）
2. 检查项目根目录是否存在 code-analyzer.yml
3. 如果不存在 → 在项目根目录创建该文件，且只添加用户要求的覆盖项
4. 如果存在 → 读取文件，然后按要求进行编辑
5. 使用 sf code-analyzer config 验证

---

第 1 步：理解意图并映射到配置部分

用户可以用自然语言请求任意组合的配置更改。你的任务是：

1. 解析用户的需求——可能是一项设置，也可能是多项组合
2. 将每项请求映射到 code-analyzer.yml 中的正确部分
3. 如果文件不存在，则创建文件，然后应用所有更改

code-analyzer.yml 的结构（可编写或编辑的内容）

config_root: .                    # Root for relative path resolution
log_folder: <path>                # Where logs are written
log_level: <1-5>                  # 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Fine

ignores:                          # Files/folders excluded from scanning
  files: [<glob patterns>]

engines:                          # Per-engine settings
  <engine_name>:
    disable_engine: <bool>
    <engine_specific_keys>: ...

rules:                            # Per-rule overrides
  <engine_name>:
    <rule_name>:
      severity: <1-5>
      tags: [<strings>]
      disabled: <bool>

suppressions:                     # Bulk suppression configuration
  disable_suppressions: <bool>
  "<file_or_folder_path>":
    - rule_selector: "<selector>"
      max_suppressed_violations: <number|null>
      reason: "<why>"

映射原则

任何用户请求都映射到上文中的一个或多个部分。解析意图并编辑相应部分：

意图类别	映射到	用户可能提出的示例
设置 / 安装	步骤 2（先决条件 + 安装）	“设置”“安装”“开始使用”“新笔记本电脑”“从头开始”
诊断 / 修复	步骤 2A（系统化调试）	“无法运行”“坏了”“修复我的设置”“扫描失败”“出现错误”
引擎控制	engines.<name>.disable_engine	“禁用 X”“关闭 Y”“仅使用 Z”“全部启用”
引擎调优	engines.<name>.<property>	“增加内存”“更改堆大小”“使用我的 eslint 配置”“将令牌数设为 50”
文件排除	ignores.files	“排除”“忽略”“跳过”“不要扫描 X”
规则严重性	rules.<engine>.<rule>.severity	“将 X 设为严重”“提升”“降低”“更改严重性”
禁用规则	rules.<engine>.<rule>.disabled	“禁用规则 X”“关闭规则 Y”“移除 Z”
规则标签	rules.<engine>.<rule>.tags	“将 X 标记为安全规则”“添加 recommended 标签”
抑制项	suppressions 部分	“在文件夹 Y 中抑制 X”“允许 N 个违规”
CI/CD	生成流水线文件（与配置分开）	“github actions”“CI”“质量门禁”
查看 / 检查	读取文件 + sf code-analyzer config	“显示配置”“配置了什么”“当前设置”

文件存在性判断

在编辑任何内容之前，检查项目根目录下是否存在 code-analyzer.yml：

ls code-analyzer.yml code-analyzer.yaml 2>/dev/null

• 文件不存在 → 在项目根目录创建该文件，且只包含用户请求的覆盖项
• 文件存在 → 读取该文件，然后编辑以添加 / 修改请求的部分

CLI 会自动在当前目录中发现 code-analyzer.yml。由于扫描从项目根目录运行，该文件必须位于此处。

规则名称解析——写入 YAML 前务必执行

当用户通过部分名称、描述性名称或近似名称提及规则时（例如“文档规则”“CRUD 违规”“console 规则”“硬编码值”），必须先使用步骤 6.1 中的查询解析为确切规则名称，再写入任何 YAML。code-analyzer.yml 会静默忽略与规则名称不完全匹配的条目——不会报错，只是覆盖不会生效。

需要将模糊名称解析为确切名称的示例：

• “禁用 ApexDoc 规则” → 查询确认名称为 ApexDoc（引擎：pmd）
• “将 no-console 降为低级别” → 查询确认名称为 no-console（引擎：eslint）
• “将 CRUD 违规设为严重” → 查询确认名称为 ApexCRUDViolation（引擎：pmd）
• “关闭硬编码值检查” → 查询到 @salesforce-ux/slds/no-hardcoded-values-slds2（引擎：eslint）
• “禁用注入规则” → 可能匹配多个规则 → 询问用户要禁用哪一个

只有在用户提供了明确、准确且广为人知的名称时才可跳过查询（例如 “ApexDoc”“no-console”“no-unused-vars”）。

处理组合 / 复杂请求

用户通常会在一个请求中组合多项更改。请在单次编辑中全部处理：

• “禁用 PMD 的 ApexDoc 规则，并将 CRUD 违规设为严重” → 编辑 rules.pmd 下的两个条目
• “排除测试文件和供应商代码，并增加 SFGE 内存” → 编辑 ignores.files + engines.sfge.java_max_heap_size
• “设置 code analyzer，只启用 ESLint 和 PMD，并忽略 node_modules” → 创建文件，配置 engines（禁用其他引擎）+ ignores
• “将所有安全规则的严重性设为 1” → 使用 sf code-analyzer rules --rule-selector Security 查询规则，然后逐一覆盖
• “配置 code analyzer”（未提供具体要求）→ 在创建任何文件之前，先询问用户希望自定义哪些内容

快速参考：常见请求 → 配置输出

用户说	生成的 YAML
"configure code analyzer"	询问用户想自定义哪些内容——在有实际覆盖项之前不要创建文件
"disable the ApexDoc rule"	rules: pmd: ApexDoc: disabled: true
"only scan Apex, no JavaScript"	engines: eslint: disable_engine: true + engines: retire-js: disable_engine: true
"ignore all test files"	ignores: files: ["**/test/**", "**/__tests__/**", "**/*.test.js"]
"make security rules critical"	查找规则，然后为每条规则设置 rules: <engine>: <rule>: severity: 1
"increase SFGE memory to 8g"	engines: sfge: java_max_heap_size: "8g"
"use my project's ESLint config"	engines: eslint: auto_discover_eslint_config: true
"suppress CRUD violations in legacy folder"	suppressions: "force-app/legacy/": [{rule_selector: "pmd:ApexCRUDViolation", reason: "..."}]

AI 必须理解 YAML 架构，并针对任何请求编写有效配置，而不仅限于上述示例。

---

步骤 2：检查先决条件并安装

运行 bash "<skill_dir>/scripts/check-prerequisites.sh"，或手动检查：

sf --version 2>&1                                    # sf CLI
sf plugins --core 2>&1 | grep -i "code-analyzer"    # Plugin
java -version 2>&1                                   # Java 11+ (PMD, CPD, SFGE)
node --version 2>&1                                  # Node 18+ (ESLint, RetireJS)
python3 --version 2>&1                               # Python 3 (Flow engine)

如果缺少任何内容，请安装（务必先询问用户）：

npm install -g @salesforce/cli                       # sf CLI
sf plugins install @salesforce/plugin-code-analyzer  # Code Analyzer plugin

安装 Java/Node/Python 时，请阅读 <skill_dir>/references/engine-prerequisites.md。 如果安装失败，请阅读 <skill_dir>/references/troubleshooting.md。

---

步骤 2A：诊断并修复故障配置

触发条件： 用户说“无法运行”“出故障了”“出现错误”“扫描失败”“帮我修复”等。

阅读 <skill_dir>/references/diagnostic-flow.md，了解完整的分层诊断流程、修复表和反模式。

关键原则（始终遵守）：

• 绝不搜索二进制文件（which、find、ls /opt/homebrew/bin/）
• 绝不使用 sfdx 作为变通方案——只能使用 sf
• 逐层修复：CLI → 插件 → 引擎依赖项 → 验证扫描
• 每次只给用户一条命令，等待确认后再继续
• 修复成功后，自动继续运行完整扫描

---

步骤 3：创建或编辑 code-analyzer.yml

仅在用户请求自定义时触发。 切勿主动创建。

创建（文件不存在）

从以下两种方法中选择一种——不要同时执行：

选项 A——根据项目类型自动生成（推荐用于首次设置）：

运行 bash "<skill_dir>/scripts/generate-config.sh"。此脚本会检测 Apex、LWC 和 Flow 标记，并生成适用于该项目的精简 code-analyzer.yml。然后跳转到“任何创建/编辑操作之后都要验证”部分。

注意：如果 code-analyzer.yml 已存在，脚本会报错退出。如果需要重新生成，请先删除现有文件。

选项 B——手动编写（适用于用户有具体自定义需求的情况）：

读取相应的示例配置作为结构参考：

• 对于仅包含 Apex 的项目，读取 <skill_dir>/examples/apex-project-config.yml
• 对于仅包含 LWC 的项目，读取 <skill_dir>/examples/lwc-project-config.yml
• 对于全栈项目（Apex + LWC + Flows），读取 <skill_dir>/examples/fullstack-project-config.yml

使用 Write 工具在项目根目录创建文件。仅包含用户要求的更改：

# Example: user said "ignore test files and increase SFGE memory"
# → Write to project root (where sfdx-project.json lives):

ignores:
  files:
    - "**/test/**"
    - "**/__tests__/**"

engines:
  sfge:
    java_max_heap_size: "4g"

不要添加 config_root、log_folder 或用户未要求的任何其他字段。

编辑（文件已存在）

读取文件，然后使用 Edit 工具，仅添加或修改相关部分。其余内容一律保留。

任何创建/编辑操作之后都要验证：

运行 bash "<skill_dir>/scripts/validate-config.sh" 验证 YAML 语法和架构是否正确，或直接使用 CLI：

sf code-analyzer config

（无需使用 --config-file——CLI 会自动在 CWD 中查找 code-analyzer.yml。）

如果用户只说“configure code analyzer”，没有提供具体要求

询问：“您想自定义哪些内容？例如：忽略特定文件、调整规则严重级别、优化引擎设置，或禁用不需要的引擎。”

步骤 4：启用/禁用引擎

编辑 code-analyzer.yml 中的 engines 部分：

engines:
  pmd:
    disable_engine: true       # Disable PMD
  eslint:
    disable_engine: false      # Enable ESLint (default)

有效的引擎名称：pmd、cpd、eslint、regex、retire-js、flow、sfge、apexguru

编辑后务必进行验证：

sf code-analyzer config --config-file code-analyzer.yml

---

步骤 5：忽略模式

编辑 code-analyzer.yml 中的 ignores 部分：

ignores:
  files:
    - "**/node_modules/**"
    - "**/.sfdx/**"
    - "**/.sf/**"
    - "**/vendor/**"
    - "**/*.min.js"

常见模式：

模式	排除内容
**/node_modules/**	npm 依赖项
**/.sfdx/**、**/.sf/**	SF CLI 内部文件
**/test/**、**/__tests__/**	测试目录
**/*.test.js、**/*.spec.js	测试文件
**/jest-mocks/**	Jest 模拟对象
**/vendor/**、**/*.min.js	第三方/压缩文件
**/staticresources/**	静态资源

---

步骤 6：规则覆盖

编辑 code-analyzer.yml 中的 rules 部分。每条规则都可以覆盖 severity、tags 和 disabled：

rules:
  pmd:
    ApexCRUDViolation:
      severity: 1              # Promote to Critical
    AvoidGlobalModifier:
      disabled: true           # Turn off entirely
    ApexDoc:
      severity: 5              # Demote to Info
      tags: ["Documentation"]
  eslint:
    no-console:
      severity: 4              # Demote to Low
    no-unused-vars:
      severity: 2              # Promote to High

严重性值： 1/严重、2/高、3/中、4/低、5/信息

6.1 规则名称解析（模糊匹配）

重要： code-analyzer.yml 中拼写错误或不完整的规则名称会被静默忽略——不会报错，只是不会应用该覆盖设置。

当用户通过近似名称引用规则时（例如“文档规则”“CRUD 违规”“硬编码值”），应在编写 YAML 之前解析出准确名称：

sf code-analyzer rules --rule-selector all 2>&1 | grep -i "<USER_KEYWORD>"

• 1 个匹配项 → 在 YAML 路径中使用该准确名称及其引擎
• 多个匹配项 → 询问用户指的是哪一个
• 0 个匹配项 → 尝试更宽泛的关键词或告知用户

仅当名称明确且准确时才跳过查找（例如 “ApexDoc”、“no-console”、“no-unused-vars”）。

**关于详细的匹配策略、常见的模糊名称→准确名称映射及引擎识别：**请阅读 <skill_dir>/references/rule-name-resolution.md。

---

步骤 7：引擎专属设置

编辑 engines 部分。最常见的覆盖设置：

engines:
  sfge:
    java_max_heap_size: "4g"      # <200 classes→"2g", 200-500→"4g", 500+→"6g"/"8g"
    java_thread_count: 4
    java_thread_timeout: 900000
  eslint:
    auto_discover_eslint_config: true    # Use project's own ESLint config
    eslint_config_file: "./eslint.config.mjs"
  pmd:
    custom_rulesets: ["./config/custom-pmd-rules.xml"]
    java_classpath_entries: ["./lib/custom-rules.jar"]
  cpd:
    minimum_tokens: { apex: 100, javascript: 100 }
  apexguru:
    target_org: "my-org-alias"
  flow:
    python_command: "python3"
  # regex.custom_rules — use the dx-code-analyzer-custom-rule-create skill to create these.
  # Never hand-write regex patterns into code-analyzer.yml: quotes/backslashes
  # inside YAML cause parsing failures. The create-regex-rule.js script handles
  # serialization correctly and must always be used for regex rule creation.

如需查看各引擎的完整属性列表，请阅读 <skill_dir>/references/config-schema.md。

---

步骤 8：CI/CD 流水线设置

从工作区检测 CI 系统（.github/workflows/ → GitHub Actions，Jenkinsfile → Jenkins，等等）。阅读 <skill_dir>/references/ci-cd-templates.md 获取模板。使用 <skill_dir>/examples/ci-github-actions.yml 作为 GitHub Actions 基础模板。关键标志：--severity-threshold 2（门禁）、--output-file results.sarif（GitHub 扫描）、--config-file code-analyzer.yml。

---

步骤 9：查看当前配置

sf code-analyzer config                               # Show effective config
sf code-analyzer config --rule-selector pmd:Security  # Specific rules
sf code-analyzer config --include-unmodified-rules    # All defaults

---

跨技能集成

此技能与 dx-code-analyzer-run 协同工作。AI Agent 应在两者之间无缝交接：

当 dx-code-analyzer-run 委托给此技能时：

如果用户说“扫描我的代码”/“运行代码分析器”，但操作失败（CLI 缺失、插件未安装或扫描出错），dx-code-analyzer-run 会委托给此技能。在这种情况下：

1. 执行诊断和修复流程（步骤 2A）——找出问题并修复
2. 一切正常后，自动继续运行扫描——不要停下来询问。用户最初的意图就是扫描。
3. 将执行交还给 dx-code-analyzer-run 的行为（构建命令、执行、解析结果）。

当此技能交接给 dx-code-analyzer-run 时：

任何配置操作成功后，都应主动提出运行扫描（例如：“设置完成！要我运行扫描吗？”、“配置已更新——要扫描并验证吗？”）。如果用户同意，请按 dx-code-analyzer-run 的行为继续操作。

当此技能交接给 dx-code-analyzer-custom-rule-create 时：

如果用户在配置过程中要求创建自定义规则（例如“也添加一条禁止使用 System.debug 的规则”、“设置一条 PMD XPath 规则”），请委托给 dx-code-analyzer-custom-rule-create。该技能完成后，可能需要设置 code-analyzer.yml 中的 custom_rulesets 或 eslint_config_file 指针——这项编辑属于此技能。

当用户意图同时涉及两项技能时：

端到端处理：“无法正常运行” → 诊断 → 修复 → 扫描。“设置并扫描” → 安装 → 扫描。“禁用 ESLint 并扫描 Apex” → 编辑配置 → 使用 --rule-selector pmd 运行。“配置自定义规则并扫描” → dx-code-analyzer-custom-rule-create → 接入配置 → dx-code-analyzer-run。始终继续处理，直到满足用户的最终意图。

---

规则 / 约束

约束	理由
仅在用户要求自定义时创建 YAML	默认设置无需任何文件即可使用——不要创建样板文件
仅将 YAML 放在项目根目录	CLI 会从 CWD 自动发现 code-analyzer.yml
仅写入覆盖项，绝不重复默认值	让文件保持精简且有明确用途
使用 Write 工具创建，使用 Edit 工具修改	保留现有设置
每次更改后都进行验证	sf code-analyzer config 可捕获 YAML 错误
安装先决条件前先询问	未经同意绝不自动安装
未经询问绝不删除现有配置	用户可能有自定义设置
设置完成后，主动提出扫描	完成闭环——只有配置而没有扫描并不完整

---

注意事项

问题	解决方案
未读取配置	必须在 CWD 中使用 code-analyzer.yml，或使用 --config-file
YAML 验证失败	仅使用空格（不要使用制表符），检查冒号后的空格
SFGE 内存不足	在 engines 部分增大 java_max_heap_size
缺少 ESLint 规则	设置 auto_discover_eslint_config: true

完整的故障排除信息请参阅 <skill_dir>/references/troubleshooting.md。

---

参考文件索引

<skill_dir> 是包含此 SKILL.md 文件的目录的绝对路径。

文件	用途
<skill_dir>/scripts/check-prerequisites.sh	环境检查
<skill_dir>/scripts/generate-config.sh	自动检测项目类型并生成配置
<skill_dir>/scripts/validate-config.sh	更改后验证 YAML
<skill_dir>/references/config-schema.md	完整的 YAML 架构文档
<skill_dir>/references/diagnostic-flow.md	步骤 2A：分层诊断流程和修复表
<skill_dir>/references/rule-name-resolution.md	步骤 6.1：模糊规则名称查找策略和映射
<skill_dir>/references/engine-prerequisites.md	各引擎的安装说明
<skill_dir>/references/ci-cd-templates.md	CI/CD 流水线模板
<skill_dir>/references/troubleshooting.md	常见设置问题及修复方法
<skill_dir>/examples/apex-project-config.yml	仅包含 Apex 的项目配置
<skill_dir>/examples/lwc-project-config.yml	仅包含 LWC 的项目配置
<skill_dir>/examples/fullstack-project-config.yml	包含 Apex + LWC + Flows 的项目配置
<skill_dir>/examples/ci-github-actions.yml	GitHub Actions 工作流