running-code-analyzer

运行 Code Analyzer Skill

⚠️ 严重警告：必须使用脚本

所有与 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 解析，而非 skill 目录。

任何汇总、筛选或排名问题（“哪个文件的违规最多？”、“有多少个 PMD 问题？”、“按数量排名的规则”、“按严重程度细分”）都由 query-results.js 回答 — 其输出已包含 topRules、topFiles 和 severityCounts。

---

概述

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

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

范围外： 安装／配置 sf 或插件（→ configuring-code-analyzer）、编写自定义规则／引擎、超出引擎所提供范围的 AI 生成修复、深度重构、CI/CD 设置（→ configuring-code-analyzer）。

允许的工具： Bash（sf code-analyzer、node、git diff、date）、Read、Write、Edit。禁止： 任何 MCP 工具、Agent 工具、Web 工具、其他 skills、Python、jq、内联脚本／heredoc。此 skill 全权负责端到端的扫描－修复－验证－查询－解释工作流。

---

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

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 工具、Web 工具和其他 skills。

原因：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. 委派给 configuring-code-analyzer — 它负责处理所有设置。
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"
“性能分析” / “Governor 限制”	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 · Bug → 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 · “我的更改”/“diff” → 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 Security 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 这样的裸相对路径（无法从用户的 CWD 解析）
• ❌ 使用 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)

⚠️ 停止并等待用户回复，即使用户最初说的是“扫描并修复所有内容”。 只有在下一轮收到明确的“yes”/“apply”/“go ahead”后才应用修复。

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 — 处理用户的选择

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

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

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

---

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

步骤 5 之后，用户可能希望在不重新运行整个扫描的情况下深入查看特定子集。此步骤处理所有结果探索请求。

触发条件

当用户要求筛选、过滤、排序或查看现有结果时激活：

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

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

执行方法

对 Step 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）
“每种引擎有多少？”	使用 Step 5 的摘要，或按引擎分别使用 --engine X --summary 运行
组合条件	--engine pmd --severity 1,2 --top 5

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

---

Step 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。

---

Step 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。

---

约束与注意事项

项目	原因／解决方法
使用带时间戳的 JSON + .log，通过 tee 输出	防止覆盖；使日志与结果对应
--format 标志	已在 v4+ 中移除；请使用 --output-file <path>.<ext>
在前台运行，超时设为 1200000ms	SFGE 可能需要 10–20 分钟；在后台运行会丢失输出
使用绝对 <skill_dir> 路径运行脚本	./scripts/ 会相对于用户的 CWD 而非技能目录解析
未经确认绝不应用修复	用户必须批准代码修改
修复前检查供应商文件	如果供应商文件占 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/diff/大型扫描
references/vendor-file-handling.md	供应商文件检测与过滤
references/post-scan-workflows.md	第 7–9 步 — 查询、规则说明、规则列表

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