configuring-code-analyzer

配置 Code Analyzer Skill

概述

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

---

范围

涵盖内容：

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

不涵盖内容：

• 运行扫描（使用 running-code-analyzer 技能）
• 修复违规、解释规则、创建自定义规则、管理抑制项

---

工具使用规则

允许： Bash（sf、java、node、python3、git、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 规则”“硬编码值”），你必须在编写任何 YAML 之前，使用第 6.1 步中的查找方法解析出确切规则名称。code-analyzer.yml 会静默忽略名称不完全匹配的规则——不会报错，只是不会应用覆盖设置。

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

• “禁用 ApexDoc 规则” → 查找后确认名称为 ApexDoc（引擎：pmd）
• “将 no-console 降为 low” → 查找后确认名称为 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:
      NoHardcodedIds:
        regex: "/[a-zA-Z0-9]{15,18}/"
        file_extensions: [".cls", ".trigger"]
        description: "Detects hardcoded Salesforce record IDs"
        severity: 2
        tags: ["Security"]

有关各引擎的完整属性列表，请阅读 <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

---

跨技能协作

此技能与 running-code-analyzer 配合使用。AI Agent 应在两者之间无缝交接：

当 running-code-analyzer 将任务交给此技能时：

如果用户说“扫描我的代码”/“运行代码分析器”，但操作失败（CLI 缺失、插件未安装或扫描出错），running-code-analyzer 会将任务交给此技能。此时：

1. 执行诊断并修复流程（第 2A 步）——找出故障并修复
2. 一切正常后，自动继续运行扫描——不要停下来询问。用户最初的意图是扫描。
3. 将执行交回 running-code-analyzer 的工作流程（构建命令、执行、解析结果）。

当此技能将任务交给 running-code-analyzer 时：

成功完成任何配置操作后，询问用户是否要运行扫描（例如：“设置完成！要我运行扫描吗？”，“配置已更新——要扫描并验证吗？”）。如果用户同意，则继续执行 running-code-analyzer 的工作流程。

当用户的意图涉及两种技能时：

端到端完成任务：“无法正常工作” → 诊断 → 修复 → 扫描。“设置并扫描” → 安装 → 扫描。“禁用 ESLint 并扫描 Apex” → 编辑配置 → 使用 --rule-selector pmd 运行。务必完成用户的最终意图。

---

规则 / 约束

约束	原因
仅在用户要求自定义时创建 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 工作流