dx-code-analyzer-run

运行 Code Analyzer 技能

关键：必须使用脚本

与 Code Analyzer 结果相关的所有操作都必须通过 <skill_dir>/scripts/ 中附带的脚本完成。不得例外。

错误做法 — 切勿这样做：

# WRONG: inline Python to parse results
python3 -c "import json; data = json.load(open('results.json'))..."

# WRONG: inline Node.js to parse results
node -e "const data = require('./results.json')..."

# WRONG: jq to filter results
cat results.json | jq '.violations[] | select(.engine=="pmd")'

# WRONG: reading the results file directly (it can be 10MB+)
Read tool → code-analyzer-results-*.json

同样禁止使用：run_code_analyzer 和任何 mcp__* 工具 — 仅限 Bash。

正确做法 — 始终这样做：

# Summarize scan results
node "<skill_dir>/scripts/parse-results.js" "./code-analyzer-results-TIMESTAMP.json"

# Filter/rank/query results (by engine, severity, file, rule, category)
node "<skill_dir>/scripts/query-results.js" "./code-analyzer-results-TIMESTAMP.json" --engine pmd --summary

# List/browse available rules (by engine, category, language, severity)
node "<skill_dir>/scripts/list-rules.js" "Security" --top 10

# Look up what a rule means
node "<skill_dir>/scripts/describe-rule.js" "ApexCRUDViolation" --engine pmd

# Discover fixable violations
node "<skill_dir>/scripts/discover-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

# Apply fixes (after user confirms)
node "<skill_dir>/scripts/apply-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

# Summarize applied fixes
node "<skill_dir>/scripts/summarize-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

# Filter vendor files (jQuery, Bootstrap, *.min.js) before applying fixes
node "<skill_dir>/scripts/filter-violations.js" "./code-analyzer-results-TIMESTAMP.json" "./code-analyzer-results-TIMESTAMP-filtered.json" --report

<skill_dir> 是包含此 SKILL.md 的目录的绝对路径。切勿使用 ./scripts/ — 它会相对于用户的 CWD 解析，而不是技能目录。

任何聚合、筛选或排名类问题（“哪个文件的违规最多？”，“有多少个 PMD 问题？”，“按数量排列的顶级规则”，“按严重性细分”）都要通过 query-results.js 回答 — 其输出已包含 topRules、topFiles 和 severityCounts。

---

概述

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

此技能会将自然语言请求（“扫描安全问题”，“检查我的更改”）转换为正确的 sf code-analyzer run 命令，针对任意引擎、目标和严重性组合执行扫描，并呈现可操作的结果。如果引擎提供了修复方案，它会查找这些方案、征求用户确认、安全地应用修复，并提供验证选项。适用于静态分析、安全审查、AppExchange 认证、代码质量检查，以及在 Salesforce 项目中查找重复项和漏洞。

范围内： 运行扫描、解析／筛选／排名结果、应用引擎自动修复、基于差异的扫描、所有输出格式（JSON/HTML/SARIF/CSV/XML）、描述／列出规则、排查扫描失败问题。

范围外： 安装／配置 sf 或插件（→ dx-code-analyzer-configure）、编写自定义规则／引擎（→ dx-code-analyzer-custom-rule-create）、引擎提供的修复方案以外的 AI 生成修复、深入重构、CI/CD 设置（→ dx-code-analyzer-configure）。

允许使用的工具： Bash（sf code-analyzer、node、git diff、date）、Read、Write、Edit。禁止使用： 任何 MCP 工具、Agent 工具、网页工具、其他技能、Python、jq、内联脚本／heredoc。此技能负责端到端完成扫描—修复—验证—查询—说明的整个工作流。

---

命令语法规则（请先阅读 — 绝对要求）

1. 命令必须是 sf code-analyzer run — 不能使用 sf scanner run（已弃用的 v3 命令）。
2. 不要使用 --format 标志。 使用 --output-file <path>.<ext>；扩展名决定格式。
3. 始终使用带时间戳的名称指定 --output-file（例如 ./code-analyzer-results-20260512-143022.json）— 不要依赖标准输出。
4. 仅限前台运行（不使用 run_in_background）；大型扫描的超时时间设为 1200000ms。
5. 会导致错误的无效 v3 标志： --format、--engine、--category、--json。改用 --rule-selector + --output-file。
6. 工具限制： 仅限 Bash、Read、Write、Edit。禁止使用 MCP 工具、Agent 工具、网页工具和其他技能。

原因：v4+ CLI 重新设计了标志接口；v3 标志现在会报错。

完整的标志／选择器文档：<skill_dir>/references/flag-reference.md。

---

前提条件

用户需要：Salesforce CLI（sf）、@salesforce/plugin-code-analyzer（v5.x+）、Java 11+（PMD/CPD/SFGE）、Node.js 18+（ESLint/RetireJS）、Python 3（Flow）、已认证的 org（ApexGuru）。

预检：运行 sf code-analyzer --help 2>&1 | head -1。如果失败，或扫描报告引擎启动错误（例如，“PMD failed to start”、“java: command not found”、“SFGE failed”）：

1. 停止 — 不要尝试自行安装或诊断前提条件。
2. 委派给 dx-code-analyzer-configure — 由它处理所有设置。
3. 完成后，返回此处并重新运行扫描。

如果扫描因其他原因失败，请参阅 <skill_dir>/references/error-handling.md。

---

快速入门：常见模式

匹配下方的请求；如果匹配，请跳至第 3 步（构建命令）。否则，从第 1 步开始。

用户说法	规则选择器	备注
“扫描我的代码” / “运行代码分析器”	Recommended	精选规则集，支持所有文件类型
“检查安全问题” / “安全审查”	all:Security:(1,2)	所有引擎，严重和高危
“扫描我的更改” / “检查差异”	（参见第 1.5 节）	使用 git diff 获取文件，筛选可扫描的类型，并通过 --target 传入
“运行 PMD” / “检查我的 Apex”	pmd	Apex 类和触发器
“检查我的 LWC” / “检查我的 JavaScript”	eslint	JavaScript/TypeScript/LWC
“查找重复项” / “检查复制粘贴代码”	cpd	代码克隆
“检查漏洞” / “扫描库”	retire-js	JavaScript 库 CVE
“深度分析” / “数据流分析”	sfge	Java 11+，耗时 10–20 分钟，使用 --workspace "force-app"
“性能分析” / “治理限制”	apexguru	需要经过身份验证的组织
“分析我的 Flows”	flow	--target **/*.flow-meta.xml，需要 Python 3
“AppExchange 安全审查”	all:Security:(1,2)	参见 <skill_dir>/references/special-behaviors.md → AppExchange

---

第 1 步：解析用户意图

从以下 7 个维度分析请求；这些维度可以组合使用。

1.1 引擎

PMD/Apex → pmd · ESLint/JS/TS/lint → eslint · Flows → flow · 重复项/CPD → cpd · 漏洞/CVE/RetireJS → retire-js · SFGE/数据流 → sfge · 性能/ApexGuru → apexguru · 正则表达式 → regex · 全部 → all · 未指定 → Recommended。

1.2 类别

安全/OWASP → Security · 性能 → Performance · 最佳实践 → BestPractices · 风格/格式 → CodeStyle · 设计/复杂度 → Design · 错误 → ErrorProne · 文档 → Documentation。

1.3 严重程度

1=严重 · 2=高危 · 3=中等 · 4=低 · 5=信息。“仅严重” → 1 · “严重+高危” → (1,2) · “中等及以上” → (1,2,3)。

1.4 特定规则

如果用户指定了规则（例如 “ApexCRUDViolation”、“no-unused-vars”）：使用 --rule-selector <engine>:<ruleName>；如果引擎不明确，则只使用 <ruleName>。

部分名称： --rule-selector 要求使用规则的完整准确名称（例如 @salesforce-ux/slds/no-hardcoded-values-slds2，而非 no-hardcoded-values）。不支持通配符。如果不能百分之百确定，请先查询——不要猜测：

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

存在多个匹配项 → 询问用户要选择哪一个。没有匹配项 → 告知用户未找到匹配项。

1.5 目标

指定路径 → --target <path> · glob（“所有 Apex”）→ --target **/*.cls,**/*.trigger · “我的更改”/“差异” → git diff --name-only [base]...HEAD，筛选可扫描的类型，并通过 --target 传入 · “LWC” → --target **/lwc/** · “Flows” → --target **/*.flow-meta.xml · 未指定 → 不添加参数（扫描整个工作区）。

差异筛选详情：<skill_dir>/references/special-behaviors.md。

1.6 输出

默认使用 JSON。 只有在用户明确要求时才更改。文件名：./code-analyzer-results-<YYYYMMDD-HHmmss>.<ext>，通过 TIMESTAMP=$(date +%Y%m%d-%H%M%S) 生成。格式：.json（默认）、.html、.sarif、.csv、.xml。

1.7 比较 / 差异

“main 之后新增” → git diff --name-only main...HEAD → 扫描这些文件 · “上次提交之后” → HEAD~1 · “与 develop 比较” → develop...HEAD。

---

第 2 步：构建规则选择器

语法：: = AND，, = OR，() = 分组。

• 仅引擎：pmd
• 引擎 + 类别：pmd:Security
• 引擎 + 严重程度：pmd:2
• 复杂示例：(pmd,eslint):Security:(1,2) =（PMD 或 ESLint）AND 安全 AND 严重程度（1 或 2）
• 特定规则：pmd:ApexCRUDViolation
• 全部：all

更多信息：<skill_dir>/references/command-examples.md。

---

第 3 步：构建完整命令

TIMESTAMP=$(date +%Y%m%d-%H%M%S)
sf code-analyzer run \
  --rule-selector <selector> \
  --target <targets> \                                              # optional
  --output-file "./code-analyzer-results-${TIMESTAMP}.json" \       # default JSON
  --include-fixes \                                                 # always
  --workspace <path>                                                # optional

• 默认使用带时间戳的 JSON；仅在用户明确要求时更改格式。
• 始终传入 --include-fixes（启用第 6 步的自动修复）。
• 省略 --target 以扫描整个工作区。
• 差异扫描：git diff --name-only → 筛选可扫描的类型 → 将其作为 --target 传入。

特殊情况（SFGE/ApexGuru/AppExchange/差异）：<skill_dir>/references/special-behaviors.md。

---

第 4 步：执行扫描

仅使用 Bash 工具——绝不使用 run_code_analyzer MCP 工具。

1. 通过 Bash 生成时间戳：date +%Y%m%d-%H%M%S → 例如 20260512-143022。
2. 告知用户：

   Starting scan...
   Results: ./code-analyzer-results-20260512-143022.json
   Log:     ./code-analyzer-results-20260512-143022.log
   May take several minutes for large codebases.
   

3. 运行命令时将时间戳直接写入命令（不要使用 $TIMESTAMP），在前台运行，超时设为 1200000ms，并通过 tee 输出到 .log 文件：

   sf code-analyzer run --rule-selector Recommended \
     --output-file "./code-analyzer-results-20260512-143022.json" \
     --include-fixes 2>&1 | tee "./code-analyzer-results-20260512-143022.log"
   

4. 退出代码为 0 = 成功。出错时，读取日志文件和 <skill_dir>/references/error-handling.md。
5. 立即解析结果（第 5 步）——不要询问用户接下来要做什么。

---

第 5 步：解析并呈现结果

扫描结束后立即运行解析脚本——不要暂停询问：

node "<skill_dir>/scripts/parse-results.js" "./code-analyzer-results-TIMESTAMP.json"

不要：

• 自行编写或生成脚本代码
• 使用 node scripts/parse-results.js 这类裸相对路径（无法从用户的当前工作目录解析）
• 使用 heredoc 或内联脚本内容
• 使用 jq 替代解析脚本（shell 引号会导致出错）
• 直接读取 JSON 文件

呈现模板

## Scan Complete

**Found X violations** across Y files.

| Severity | Count |
|----------|-------|
| Critical (1) | X |
| High (2) | X |
| Moderate (3) | X |
| Low (4) | X |
| Info (5) | X |

### Top Issues
| # | Rule | Engine | Sev | File | Line |
|---|------|--------|-----|------|------|
| 1 | ApexCRUDViolation | pmd | 2 | AccountService.cls | 42 |
| ... up to 10 most critical |

### Top Rules by Frequency
| Rule | Engine | Count |
|------|--------|-------|
| no-var | eslint | 170 |
| ... |

Full results: `./code-analyzer-results-20260512-143022.json`

根据结果数量调整呈现方式：0 →“未发现违规”；1–10 → 在一个表格中列出全部结果；11–50 → 显示严重性计数 + 前 10 项；50–5000 → 显示计数 + 前 10 项违规 + 前 10 条规则 + 前 5 个文件；5000+ → 同上，并建议缩小范围（严重性/类别/文件夹）。最后务必提供输出路径，并给出后续选项：筛选 / 解释规则 / 应用修复。

大结果处理：<skill_dir>/references/special-behaviors.md。

---

第 6 步：应用引擎提供的修复（扫描后）

引擎提供的修复是确定性的（并非由 AI 生成）。流程：供应商文件筛选（如有需要）→ 发现修复 → 呈现修复 → 等待用户确认 → 应用修复 → 总结。

6.1 供应商文件筛选（如有需要）

如果用户说“修复我的代码”/“项目源代码”，或者违规最多的文件是供应商库（jQuery、Bootstrap、*.min.js），则运行：

node "<skill_dir>/scripts/filter-violations.js" \
  "./code-analyzer-results-TIMESTAMP.json" \
  "./code-analyzer-results-TIMESTAMP-filtered.json" \
  --report

报告：“已排除 X 个供应商文件（Y 项违规）——包括 jQuery、Bootstrap 等。仅对 Z 个项目文件应用修复。”使用筛选后的文件执行第 6.2 步及后续操作。检测逻辑：<skill_dir>/references/vendor-file-handling.md。

6.2 发现修复

node "<skill_dir>/scripts/discover-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

6.3 呈现并询问（然后停止）

### Engine-Provided Fixes Available
**X of Y violations** have auto-fixes provided by the analysis engine:

| Rule | Engine | Sev | Fixable Count |
|------|--------|-----|---------------|
| no-var | eslint | 3 | 170 |
| ... |

These are safe, deterministic fixes generated by the engines (not AI-generated).

Would you like me to apply these fixes? (yes / no / select specific rules)

**停止并等待用户回复，即使用户最初说的是“扫描并修复所有问题”。**只有在下一轮收到新的“是”/“应用”/“继续”后才应用修复。

6.4 应用修复

node "<skill_dir>/scripts/apply-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

（如果第 6.1 步创建了筛选文件，则使用该文件。）

6.5 总结（第 6.4 步后必须立即执行）

node "<skill_dir>/scripts/summarize-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

然后呈现：

### Engine-Provided Fixes Applied Successfully
**Applied X auto-fixes across Y files.**

| Severity | Fixes Applied |
|----------|---------------|
| Critical (1) | X |
| ... |

| Rule | Fixes Applied |
|------|---------------|
| no-var | 169 |
| ... |

Want me to re-run the scan to verify the fixes resolved the violations?

6.6 — 处理用户的选择

• **拒绝 /“不”：**跳过应用修复，跳过总结。不要重新扫描。
• **“选择规则”：**将发现列表筛选为这些规则，并将筛选后的文件传给 apply-fixes.js。
• **“全部”/“是”：**直接对完整的（或经供应商筛选的）结果文件运行 apply-fixes.js。

6.7 — 可选：重新扫描以验证

如果用户接受第 6.5 步中的提议，则使用新的时间戳重新运行相同的扫描（不要覆盖原始结果）。比较修复前后的违规数量并显示差值——已成功解决的违规会消失；剩余违规则需要手动处理，或与本次修复无关。

---

第 7 步：查询和筛选现有结果

第 5 步之后，用户可能希望深入查看特定子集，而无需重新运行整个扫描。本步骤用于处理所有结果探索请求。

触发时机

当用户要求对现有结果进行筛选、过滤、排序或探索时启用：

• “只显示安全违规项”
• “AccountService.cls 中有什么？”
• “只显示 PMD 问题”／“筛选严重和高危问题”
• “触发了哪些 ESLint 规则？”／“显示 lwc 文件夹中的违规项”
• “最严重的 20 项”／“哪个文件的违规项最多？”
• “最常见的规则是什么？”／“每个引擎有多少项违规？”／“按严重程度分类统计”

重要： 任何关于现有扫描结果的问题——包括筛选、排序、计数和汇总——都必须使用 query-results.js。绝不要编写内联 Python、jq 或临时脚本来解析结果 JSON。查询脚本的输出已包含 topRules、topFiles 和 severityCounts。

如何执行

针对第 4 步中的同一个结果文件运行查询脚本（无需重新扫描）：

node "<skill_dir>/scripts/query-results.js" "./code-analyzer-results-TIMESTAMP.json" [options]

用户说	选项
“安全违规项”	--category Security
“只看 PMD 问题”	--engine pmd
“严重和高危”／“严重程度 1-2”	--severity 1,2
“AccountService.cls 中的”	--file AccountService.cls
“ApexCRUDViolation 规则”	--rule ApexCRUDViolation
“前 20 项”	--top 20
“按文件排序”	--sort file
“只给我计数”	--summary
“哪个文件的违规项最多？”	--sort file --summary（读取 topFiles）
“哪个文件的 PMD 违规项最多？”	--engine pmd --summary（读取 topFiles）
“最常见的规则？”	--summary（读取 topRules）
“每个引擎有多少项？”	使用第 5 步的汇总，或针对每个引擎运行 --engine X --summary
组合条件	--engine pmd --severity 1,2 --top 5

输出格式和展示模板：<skill_dir>/references/post-scan-workflows.md。

---

第 8 步：描述规则

当用户询问“这条规则是什么意思？”或“如何修复这个问题？”时，使用此步骤查找并解释特定规则。

触发时机

• “ApexCRUDViolation 是什么？”
• “解释这条规则”／“为什么会标记这个问题？”
• “no-var 是什么意思？”
• “如何修复 OperationWithLimitsInLoop？”
• “介绍一下这项违规”

如何执行

node "<skill_dir>/scripts/describe-rule.js" "<rule-name>" [--engine <engine>]

已知引擎时（根据扫描上下文）传入 --engine；如需更广泛的搜索，则省略此参数。返回 success／multiple_matches／not_found 之一。状态处理方式和模板：<skill_dir>/references/post-scan-workflows.md。

---

第 9 步：列出可用规则

触发条件：“有哪些安全规则可用？”、“列出所有 PMD 规则”、“JavaScript 的规则”、“推荐规则”、“有多少条 ESLint 规则？”、“Apex 的规则”。

node "<skill_dir>/scripts/list-rules.js" "<selector>" [options]

用户说	选择器	选项
“安全规则”	Security
“PMD 规则”	pmd
“ESLint 安全规则”	eslint:Security
“JavaScript 规则”	JavaScript
“Apex 规则”	Apex
“推荐规则”	Recommended
“高严重程度规则”	(1,2)
“只给我计数”	Recommended	--count-only
“前 10 条安全规则”	Security	--top 10

筛选条件：--engine、--severity、--top（默认值为 100）、--count-only。脚本会预先验证选择器标记（可在调用 CLI 前捕获 secruity 之类的拼写错误）。展示方式：<skill_dir>/references/post-scan-workflows.md。

---

跨技能集成

此技能属于由 3 个技能组成的 Code Analyzer 生态系统。应妥善移交任务，不要尝试处理属于其他技能的工作。

此技能委派给 dx-code-analyzer-configure 的情况：

• 预检失败（缺少 CLI、未安装插件或引擎前置条件未满足）→ 停止操作，委派任务，修复后返回此处
• 用户要求设置 CI/CD、编辑 code-analyzer.yml、更改严重程度或禁用引擎 → 完全委派

此技能委派给 dx-code-analyzer-custom-rule-create 的情况：

• 用户要求创建新规则、编写 XPath、编写正则规则，或强制执行内置规则未覆盖的模式 → 完全委派。不要在此处尝试创建规则。

当其他技能将任务交接到此处时：

• dx-code-analyzer-configure 完成设置 → 继续扫描（步骤 1–5）
• dx-code-analyzer-custom-rule-create 完成规则创建 → 继续扫描，并针对新规则进行扫描（例如，--rule-selector pmd:<RuleName>），以验证其是否有效

职责边界

此技能负责完整的 扫描 → 探索 → 修复 端到端工作流。它不负责安装、配置文件管理或规则编写。

---

约束与注意事项

项目	原因 / 解决方法
使用带时间戳的 JSON + .log，通过 tee 保存	防止覆盖；使日志与结果对应
--format 标志	在 v4+ 中已移除；请使用 --output-file <path>.<ext>
在前台运行，超时设为 1200000ms	SFGE 可能需要 10–20 分钟；在后台运行会丢失输出
使用绝对 <skill_dir> 路径运行脚本	./scripts/ 会相对于用户的当前工作目录解析，而非技能目录
未经确认绝不应用修复	用户必须批准代码修改
修复前检查供应商文件	如果 50% 以上是供应商文件（jQuery/Bootstrap/*.min.js），请先过滤
修复脚本顺序：过滤（如有需要）→ 发现 → 应用 → 汇总	跳过汇总会导致用户无法获得结果报告
SFGE 需要显式指定 --workspace	否则模板文件会导致编译错误
先查找部分规则名称	猜测会返回 0 个结果；请使用 sf code-analyzer rules
只能使用 Bash 工具，绝不使用 MCP	run_code_analyzer 和其他 MCP 工具会绕过脚本工作流
修复时绝不调用其他技能	此技能负责完整的端到端工作流
查询现有结果，不要重新扫描	步骤 7 会即时过滤现有 JSON
扫描返回 0 个结果	规则选择器无效——请使用 sf code-analyzer rules --rule-selector <selector> 验证
jq 解析失败	Shell 引号问题——请改用 parse-results.js / query-results.js
由 LLM 编写内联脚本	绝不编写脚本——请使用 <skill_dir>/scripts/ 中的现有脚本
使用临时 Python 回答排名/聚合问题	始终使用 query-results.js；其输出已包含 topFiles/topRules/severityCounts

---

参考文件索引

脚本（始终使用带绝对 <skill_dir>/ 前缀的路径通过 node 执行，绝不要使用 Read）：

文件	使用时机
<skill_dir>/scripts/parse-results.js	步骤 5 — 从扫描 JSON 中提取摘要
<skill_dir>/scripts/filter-violations.js	步骤 6.1 — 从修复范围中排除供应商文件（jQuery、Bootstrap）
<skill_dir>/scripts/discover-fixes.js	步骤 6.2 — 找出可修复的违规项
<skill_dir>/scripts/apply-fixes.js	步骤 6.4 — 用户确认后应用引擎修复
<skill_dir>/scripts/summarize-fixes.js	步骤 6.5 — 汇总已应用的更改
<skill_dir>/scripts/query-results.js	步骤 7 — 过滤/深入分析现有结果，无需重新扫描
<skill_dir>/scripts/describe-rule.js	步骤 8 — 查找规则说明和文档
<skill_dir>/scripts/list-rules.js	步骤 9 — 按选择器列出/浏览可用规则并进行验证

参考资料（按需阅读）：

文件	阅读时机
references/quick-start.md	命令语法模板
references/flag-reference.md	完整标志文档、规则选择器语法
references/error-handling.md	扫描失败诊断
references/engine-reference.md	引擎功能、文件类型、规则标签
references/command-examples.md	较少见的命令场景
references/special-behaviors.md	SFGE/ApexGuru/AppExchange/差异/大型扫描
references/vendor-file-handling.md	供应商文件检测与过滤
references/post-scan-workflows.md	步骤 7–9 — 查询、规则说明、规则列表

examples/ 包含输出结构验证和命令模式（基本/大型/安全扫描、修复工作流）。