configure-codacy

配置 Codacy

术语表： 有关 Codacy 概念（问题、发现项、严重性、覆盖率、工具、模式等）的通用定义，请参阅 glossary.md。

此技能会根据项目的实际技术栈和编码规范定制 Codacy 配置。它会识别代码库使用的语言和框架，初始化一系列工具和模式，运行分析，然后智能地减少噪声，最终生成一份干净、高信号的配置，并完整记录所有更改及其原因。

前提条件

• Codacy Analysis CLI（codacy-analysis），支持 discover 和 init --auto。如果 CLI 不支持这些命令，请运行以下命令更新：npm i -g @codacy/analysis-cli。请参阅 codacy-analysis-cli 了解设置方法。
• Codacy Cloud CLI（codacy）——用于确认代码库是否位于 Codacy Cloud 上；如果是，则从仅限云端的工具中获取问题。请参阅 codacy-cloud-cli 了解设置方法。

两个 CLI 共用 ~/.codacy/credentials 中的凭据，因此登录一次即可同时用于二者。

配置的工作方式

所有配置都通过 .codacy/codacy.config.json 在本地完成。编辑文件并运行分析，即可立即查看结果，无需推送或在云端重新分析。调整完成后，只需一步即可将配置导入 Codacy Cloud。

关键原则：先广泛启用，再根据数据减少噪声。通过 init --auto 初始化最大范围的模式覆盖，运行分析以了解所有问题的概况，然后根据严重性和类别分布决定要停用或调整的内容。

编辑前，请阅读配置格式参考了解完整架构——字段名称很重要（例如，排除字段是 exclude，而不是 excludePaths）。要停用某个模式，请将其从 patterns 数组中移除。要停用某个工具，请移除整个工具条目。

组织标准优先。 如果某个模式由组织级编码标准强制执行，则无法在代码库级别更改。

仅限本地配置。 .codacy/codacy.config.json 文件仅用于本地分析。将其提交或推送到代码库不会对 Codacy Cloud 分析产生任何影响。要将配置应用到 Codacy Cloud，请使用导入命令（codacy tools ... --import）。

调用模式

此技能支持三种模式，用于控制调整配置后是否将其导入 Codacy Cloud：

• 交互模式（默认）： 调整配置并展示结果后，通过 AskUserQuestion 询问用户是否要将配置导入 Codacy Cloud。未提供参数时默认采用此模式。
• 自动导入： 如果用户的调用参数中包含单词 “import”（例如，/configure-codacy import configuration、/configure-codacy --import），则跳过导入提示，并在展示结果后自动导入。适用于 CI 运行和自动化。
• 仅本地模式： 如果代码库不在 Codacy Cloud 上（由步骤 0 确认），则绝不询问是否导入。展示结果，并说明配置已准备好，仅供本地分析使用。

此外，force 标志控制导入期间对编码标准的处理方式：

• 禁用 force（默认）： 如果导入时遇到编码标准冲突（409 错误），请勿自动使用 --force 重试。应通过 AskUserQuestion 向用户展示冲突，并由用户决定是否取消关联编码标准。
• 启用 force： 如果用户的调用参数中包含单词 “force”（例如，/configure-codacy import force），则在发生编码标准冲突时自动使用 --force 重试。

在最开始解析调用参数，并设置步骤 6 将引用的内部标志：

• 如果参数包含 “import” → 自动导入模式
• 如果参数包含 “force” → force 模式（允许自动取消关联编码标准）
• 否则 → 交互模式（如果步骤 0 发现代码库不在云端，则可能转为仅本地模式）

定制配置工作流

Configuration Progress:
- [ ] Step 0: Check environment and capture baseline
- [ ] Step 1: Discover repository stack
- [ ] Step 2: Initialize auto-tuned configuration
- [ ] Step 3: Run broad-config baseline analysis
- [ ] Step 4: Smart noise evaluation and tuning
- [ ] Step 5: Show local results
- [ ] Step 6: Cloud import (conditional)
- [ ] Step 7: Clean-up

步骤 0：检查环境并记录基线

此步骤用于确定起始状态，并记录最终摘要中的 BEFORE 指标。流程取决于两个条件：仓库是否位于 Codacy Cloud，以及是否已存在本地配置。

0a. 创建临时目录并检查 Codacy Cloud 状态

创建用于存放中间分析文件的临时目录：

mkdir -p .codacy/tmp

Cloud CLI 会根据 git 远程 origin URL 自动检测提供方、组织和仓库，无需手动推导。在仓库目录中，以下所有 codacy 命令都可以不显式指定 <provider> <org> <repo>。为便于说明，示例使用显式形式；实际操作时请替换为自动检测的简写形式。

CLI 输出注意事项：codacy 和 codacy-analysis CLI 都会在实际 JSON 输出前将进度行（例如 - Fetching tools...、- Fetching issues...）写入 stderr。将 CLI 输出直接通过管道传给 jq 时，请重定向 stderr，以免出现解析错误：

codacy repository --output json 2>/dev/null | jq '...'

检查 Cloud 状态：

codacy repository --output json

如果成功，说明仓库位于 Codacy Cloud。还要列出已启用的工具，以便稍后识别仅限云端的工具：

codacy tools --output json 2>/dev/null | jq '[.[] | select(.settings.isEnabled == true) | {name, isClientSide}]'

如果失败（仓库未接入 Codacy、未通过身份验证，或没有 Cloud CLI），请记下将跳过云端功能——本地工作流完全独立运行。将调用模式设为仅本地（参见“调用模式”部分）。

0b. 记录基线（BEFORE 参考）

根据 Cloud 状态和本地配置是否存在来选择分支。此处记录的基线是步骤 5 摘要中的真实 BEFORE 参考。

路径 A——仓库位于 Codacy Cloud（权威基线）：

Cloud 配置是权威来源。使用 init --remote 获取配置。

**重要：**如果 .codacy/codacy.config.json 已存在，init --remote 将会失败。请务必先删除它（备份副本步骤应在删除前执行）：

# Delete any existing config first — init --remote refuses to overwrite
rm -f .codacy/codacy.config.json

# Fetch the current Cloud configuration
codacy-analysis init --remote <provider> <org> <repo>

# Store a copy for later merging and comparison
cp .codacy/codacy.config.json .codacy/tmp/codacy-remote-config.json

# Record BEFORE metrics
jq '[.tools[].patterns | length] | add' .codacy/codacy.config.json
jq '.tools | length' .codacy/codacy.config.json

# Run analysis with the Cloud config to capture the BEFORE issue landscape
codacy-analysis analyze --install-dependencies --output-format json --output .codacy/tmp/codacy-remote-results.json

# Record BEFORE issue count and runtime
jq '.issues | length' .codacy/tmp/codacy-remote-results.json
jq '.metadata.durationMs' .codacy/tmp/codacy-remote-results.json

获取 Cloud 问题概览——无需下载每个单独问题，即可查看整个仓库按模式统计的问题数、误报数和建议操作：

codacy issues -O -o json > .codacy/tmp/codacy-cloud-overview.json

此概览数据对步骤 4 的调优决策很有价值：它显示 Cloud 上产生问题最多的模式（生产环境的实际情况），包含各模式的误报率，并生成降低噪声的建议操作（识别占所有问题 10% 以上或达到平均值 3 倍的问题模式）。建议操作包含可直接运行的禁用命令，并会根据编码规范或配置文件约束进行调整。请保存，以便稍后比较。

还要检查仅限云端的工具——即在 Cloud 中启用、但本地 Analysis CLI 不支持的工具。通过 codacy-analysis info 获取本地 CLI 支持的工具，再与上方已启用的 Cloud 工具列表比较。任何已在 Cloud 启用、但未出现在 info 输出中的工具，都是仅限云端的工具（例如 SonarSharp、Codacy ScalaMeta Pro）。如果存在仅限云端的工具且它们有问题，请获取这些问题：

codacy issues --output json > .codacy/tmp/codacy-remote-cloud-results.json

路径 B——未接入 Cloud，但存在本地 .codacy/codacy.config.json：

# Store a copy for later merging and comparison
cp .codacy/codacy.config.json .codacy/tmp/codacy-previous-config.json

# Record BEFORE metrics
jq '[.tools[].patterns | length] | add' .codacy/codacy.config.json
jq '.tools | length' .codacy/codacy.config.json

# Run analysis with the existing local config
codacy-analysis analyze --install-dependencies --output-format json --output .codacy/tmp/codacy-previous-results.json

# Record BEFORE issue count and runtime
jq '.issues | length' .codacy/tmp/codacy-previous-results.json
jq '.metadata.durationMs' .codacy/tmp/codacy-previous-results.json

路径 C——未接入 Cloud，且没有本地配置：

将 BEFORE 记录为未配置：0 个模式、0 个工具、0 个问题，运行时为 null。无需运行分析。

保存实际执行路径中的 BEFORE 指标。步骤 2-3 中的广义配置指标仅供内部使用，不会报告给用户。

0c. 云端噪声预评估（仅限 Track A）

如果已获取 Cloud 概览（.codacy/tmp/codacy-cloud-overview.json 存在），现在分析该概览，找出基于 Cloud 生产数据已知的噪声模式。这样可以在运行本地分析前，预先禁用已知噪声，节省时间。

首先查看概览中的建议操作——CLI 已识别出占所有问题 10% 以上或数量达到每种模式平均值 3 倍的模式，并提供可直接运行的禁用命令。将这些建议作为主要依据，再参考以下标准进行补充。

解析概览中的 patterns 数组（每个条目包含 {id, title, total}）和误报计数：

# Issue counts per pattern
jq '[.overview.patterns[] | {id, title, total}] | sort_by(-.total)' .codacy/tmp/codacy-cloud-overview.json

# Patterns with potential false positives (count > 0)
jq '[.overview.patterns[] | select(.potentialFalsePositives > 0) | {id, title, total, potentialFalsePositives, falsePositiveRatio: ((.potentialFalsePositives / .total) * 100 | round)}] | sort_by(-.falsePositiveRatio)' .codacy/tmp/codacy-cloud-overview.json

根据以下标准识别噪声模式：

1. 语言不匹配的模式——将模式 ID 与已发现的技术栈交叉比对（下一步会运行步骤 1，但步骤 0a 的 Cloud 工具列表可以大致反映项目使用的语言）。模式 ID 通常包含目标语言（例如 python.、java.、ruby.）。将明显不属于项目所用语言的模式标记出来。

2. 约定或风格噪声——在 CodeStyle、Documentation 或 Comprehensibility 等类别中，问题数量特别高（按数量排名位于前 5%）的模式可能与约定不匹配。将这些模式列为候选项。

3. 误报率较高的模式——如果某种模式的相当一部分问题被标记为潜在误报（例如 potentialFalsePositives / total > 30%），则应优先考虑预先禁用。这些模式产生的结果被 Codacy 自身的启发式判断为不可靠。保存误报数据，以供步骤 4b 的规则 7 使用；在本地验证期间，应对误报率较高的模式进行额外审查。

4. 绝不预先禁用 Security 模式——无论问题数量或误报率如何，都不得将 Security 模式标记为预先禁用。这些模式将在步骤 4 中结合完整上下文进行处理。

5. 绝不预先禁用 Critical/High 严重级别的模式——在采取任何操作前，必须先进行本地验证。

将每个噪声模式归入以下两个列表：

• cloudNoiseLocal——来自本地 Analysis CLI 支持的工具的噪声模式。在步骤 2 中运行 init --auto 后，会立即从 .codacy/codacy.config.json 中移除这些模式。
• cloudNoiseCloudOnly——来自仅限云端的工具的噪声模式（在步骤 0b 中识别）。仅当执行导入时，才会在步骤 6（导入）期间通过 Cloud CLI 禁用这些模式。

保存这两个列表，以供步骤 2 和步骤 6 使用。这是预过滤——步骤 4 将根据本地分析结果进行更深入的噪声评估。

Step 1：发现代码仓库技术栈

运行发现命令，了解代码仓库使用的语言、框架和库：

codacy-analysis discover --output-format json --output .codacy/tmp/codacy-discover.json

解析输出，了解：

• 项目中使用的语言
• 使用的框架和库（例如 React、Django、Spring Boot）
• 这些信息有助于在步骤 4 中评估噪声（例如，知道项目使用 React 后，就能判断与 JSX 相关的模式是否适用）

注意：已在步骤 0 中检查 Codacy Cloud。

步骤 2：初始化自动调优配置

首先，删除现有的 .codacy/codacy.config.json（备份副本已在步骤 0 中保存）：

rm -f .codacy/codacy.config.json

使用范围最广且实用的模式集进行初始化，并根据已识别的技术栈进行筛选：

codacy-analysis init --auto "Critical,High,Warning,Minor,AllSecurity,ErrorProne,Performance,BestPractice,UnusedCode,Compatibility,Complexity,Comprehensibility,CodeStyle,Documentation"

此筛选条件表示：

• Critical — Codacy 推荐的（默认）严重级别模式
• AllSecurity — 所有安全类别模式（包括非默认模式）
• 其他所有内容 — Codacy 推荐的（默认）模式，涵盖所有类别中的 High、Warning 和 Minor 严重级别

目的是先扩大范围，再在步骤 4 中根据实际分析数据进行精简。

应用 Cloud 噪声预筛选（仅限 Track A）： 如果在步骤 0c 中识别出了 cloudNoiseLocal 模式，现在请将其从新创建的配置中移除。对于 cloudNoiseLocal 中的每个模式，在 .codacy/codacy.config.json 中找到其所属工具的 patterns 数组并将其移除。这样可以避免将本地分析时间浪费在已知会产生噪声的模式上，这些噪声是根据 Cloud 生产数据确认的。请记录这些移除项，以便在摘要中说明（预筛选更改会记录在 patternChanges 中，原因需引用 Cloud 数据）。

合并保留的配置（来自步骤 0 中保存的基线配置）：

• Track A（Cloud）：从 .codacy/tmp/codacy-remote-config.json 合并
• Track B（本地配置）：从 .codacy/tmp/codacy-previous-config.json 合并
• Track C（没有先前配置）：无需合并

对于适用的轨道：

1. 读取新创建的 .codacy/codacy.config.json
2. 合并存储配置中的全局 exclude 数组（合并而非替换——新配置可能已有自己的排除项）
3. 对于存储配置和新配置中都存在的每个工具，合并其工具级 exclude 数组
4. 对于存储配置中 useLocalConfigurationFile 为 true 且在新配置中仍然存在的工具，恢复该设置以及 localConfigurationFile 路径

记录宽泛配置的指标（内部数据——不是摘要中的 BEFORE 参考值）：

# Count enabled patterns across all tools in the broad config
jq '[.tools[].patterns | length] | add' .codacy/codacy.config.json

# Count enabled tools in the broad config
jq '.tools | length' .codacy/codacy.config.json

步骤 3：运行宽泛配置的基线分析

使用宽泛配置运行分析，以了解完整的问题分布。这是用于调优决策的内部步骤——面向用户的摘要中的 BEFORE 参考值来自步骤 0。

codacy-analysis analyze --install-dependencies --output-format json --output .codacy/tmp/codacy-baseline.json

始终使用 --output <file>，以避免 stdout 缓冲导致 JSON 损坏。

记录宽泛配置的指标（用于步骤 4 的调优决策，不用于摘要）：

# Total issues in broad config
jq '.issues | length' .codacy/tmp/codacy-baseline.json

# Total runtime in milliseconds
jq '.metadata.durationMs' .codacy/tmp/codacy-baseline.json

解析问题分布——这是所有调优决策的依据：

# Issues grouped by pattern (noise detection)
jq '[.issues | group_by(.patternId) | .[] | {patternId: .[0].patternId, toolId: .[0].toolId, severity: .[0].severity, category: .[0].category, count: length}] | sort_by(-.count)' .codacy/tmp/codacy-baseline.json

# Issues by severity
jq '.issues | group_by(.severity) | map({severity: .[0].severity, count: length})' .codacy/tmp/codacy-baseline.json

# Issues by category
jq '.issues | group_by(.category) | map({category: .[0].category, count: length})' .codacy/tmp/codacy-baseline.json

# Top 20 files by issue count
jq '[.issues | group_by(.filePath) | .[] | {filePath: .[0].filePath, count: length}] | sort_by(-.count) | .[0:20]' .codacy/tmp/codacy-baseline.json

# Per-tool results
jq '.toolResults | map({toolId, status, issueCount, durationMs, filesAnalyzed})' .codacy/tmp/codacy-baseline.json

步骤 4：智能噪声评估与调优

这是此技能的核心。使用结构化且结合上下文的决策框架，处理基线结果。

将 Cloud 概览作为交叉参考（仅限 Track A）： 如果 .codacy/tmp/codacy-cloud-overview.json 存在（在步骤 0b 中获取），请使用其中按模式统计的问题数量和误报数据，与本地基线进行交叉参考。Cloud 概览反映的是 Codacy 上对整个代码仓库的分析结果（生产环境的真实情况），而本地基线仅涵盖本地 CLI 能够分析的文件。当某个模式在 Cloud 概览中问题数量较多，而在本地数量较少时，这可能表明该工具仅在 Cloud 上受支持——在进行去重和停用决策时应考虑这一点（不要停用在 Cloud 上仍有用的模式）。概览中的误报数量对于下文规则 7 尤其有价值——在 Cloud 上误报比例较高的模式，在本地也可能产生同样不可靠的结果。

4a. 确定噪声基线

计算严重程度为 "Error" 或 "High" 的严重及高优先级问题占问题总数的百分比。根据该比例，决定要多大幅度地削减低优先级类别：

严重及高优先级问题占比	对 CodeStyle 和 Documentation 模式的处理
>50%	禁用所有严重程度为 Minor 和 Warning 的 CodeStyle 和 Documentation 模式。代码库存在严重问题，样式问题只会掩盖这些问题，造成干扰。
30–50%	禁用严重程度为 Minor 的 CodeStyle 和 Documentation 模式。保留 Warning 级别的模式。
10–30%	保留所有模式，但重点排除噪声较多的文件路径。
<10%	保留所有内容——代码库足够整洁，可以从样式检查中受益。

当严重问题占主导时，同样的逻辑也适用于其他低优先级类别（Comprehensibility、Compatibility），按比例调整即可。请酌情判断。

4b. 模式级决策

对于基线结果中的每个模式，按问题数量从高到低排序，并按照以下优先级链进行处理：

1. 安全模式必须覆盖所有安全问题。 任何 category == "Security" 的模式都应保持启用，除非另一个来自不同工具的活动模式已覆盖相同的语义问题（见规则 2）。如果某个安全模式产生过多噪声，且不适用去重，则应排除特定文件，而不是停用该模式。

2. 对跨工具的重叠模式进行去重。 当多个工具标记相同的语义问题（例如“硬编码密钥”“SQL 注入”“XSS”“未使用的导入”）时，通过比较问题消息、受影响的文件和受影响的行来识别重叠。对于重叠的一对模式：

   • 保留来自更专业或更精确工具的模式（例如，优先保留 Semgrep 安全规则，而不是 Biome 通用检查；优先保留专用 SAST 扫描器，而不是通用 Linter）
   • 如果精度相当，则保留来自项目中使用更活跃工具的模式（启用的模式更多、在 CI 中使用，或有本地配置文件）
   • 停用另一个工具中的冗余模式
   • 这并非移除问题，而是进行去重。保留的模式仍会覆盖该问题。
   • 这适用于所有类别，而不仅限于 Security——例如，两个工具都标记“未使用的导入”
   • 在变更日志中说明：保留了哪个模式、停用了哪个模式，以及保留的模式为何是更好的来源

3. 绝不能停用有效的 Critical/High 问题。 severity == "Error" 或 severity == "High" 且发现真实问题的模式必须保留。如果它们看起来像误报，应排除相关文件，而不是停用该模式。

4. 技术栈不匹配 → 停用。 与 Step 1 的 discover 输出交叉核对。针对项目中不存在的语言或框架的模式只会产生噪声。例如：

   • 仅包含 JavaScript 的项目中出现 Python 安全模式
   • 仅包含 Java 的项目中出现 PMD7 的 Apex 模式
   • 针对仓库中不存在语言的 Semgrep 规则

   从配置中移除这些模式。

5. 噪声下限 → 停用。 应用 4a 中的决策。如果噪声下限要求移除 Minor 严重级别的 CodeStyle/Documentation，则移除这些模式。

6. 与项目约定不符 → 停用。 如果某个模式标记的行为在代码库中有超过 80% 的代码都一致采用，则该模式与项目既有约定相矛盾。例如：

   • 当整个项目都一致采用所谓“错误”风格时，检查制表符与空格的规则
   • 与项目既有命名方式不符的命名约定规则

7. 容易产生误报 → 停用。 将 Cloud 概览中的误报数据（来自 Step 0c）作为主要依据：potentialFalsePositives / total > 30% 的模式是很有可能需要停用的候选项——Codacy 自身的启发式判断表明，其相当一部分结果不可靠。对于这些模式，应检查代码中的一些实际实例以确认。如果本地实例表明该模式在此代码库中产生的结果价值较低，则停用它。对于没有 Cloud 误报数据的模式，应检查该模式是否通常容易产生大量误报。只有在确认命中结果对这个代码库确实没有价值后，才停用该模式。

8. 优先调整参数，而非停用。 停用有价值的模式之前，检查它是否有可配置参数：

   • Lizard 复杂度阈值——提高阈值，使其符合代码库的实际复杂度
   • 行长度限制——设置为项目中观测到的最大值
   • 其他基于阈值的规则——调整阈值，在保留规则启用的同时减少误报

   调整参数可以在降低噪声的同时保留覆盖范围。

9. 优先排除文件，而非停用。 当某个模式有效，但在不适用的文件中触发时，应排除这些文件，而不是停用该模式。该模式应继续对真正的源代码保持启用。

4c. 文件级评估

查看基线结果（步骤 3）中问题数最多的文件。排除项必须严格基于数据——仅为实际出现在基线结果中且产生显著噪声的文件／路径添加排除项。

**重要：**分析 CLI 已遵循 .gitignore。被 .gitignore 匹配的文件绝不会纳入分析，因此无需在 Codacy 配置中排除。除非结果中确实出现这些路径并报告了问题，否则不要预先添加 dist/**、node_modules/**、build/** 或 coverage/** 等路径的排除项。

针对问题数排名前 N 的每个嘈杂文件／路径，执行以下流程：

1. 检查该文件是否为生成代码（例如 *.generated.ts、routeTree.gen.ts、自动生成的 API 客户端、.pb.go 文件）
2. 检查该文件是否为提交到代码仓库的供应商或第三方代码（例如未被 gitignore 的 .yarn/releases/、vendor/）
3. 检查该文件是否为已提交的构建产物（未被 gitignore）
4. 检查该文件是否为测试夹具、快照或模拟数据，且会导致特定工具产生误报
5. 如果符合以上任一情况，请添加到相应的排除项：
   • 影响所有工具的生成代码／供应商代码／构建产物：添加到全局 exclude 数组
   • 仅对特定工具产生噪声的文件：添加到该工具的专属 exclude 数组（例如 markdownlint 命中 CHANGELOG.md、Stylelint 命中已提交的供应商 CSS）
6. 如果文件属于正常源代码，不要排除它——改用模式级调整（以上规则 1–9）处理噪声

每个排除项都必须有实际结果作为依据。不要维护规定性的“始终排除这些路径”清单。

4d. 工具级评估

对配置中的每个工具：

• 与技术栈无关？ 如果 discover 输出显示没有该工具目标语言的文件，请移除整个工具条目。例如：项目中没有 Ruby 时移除 RuboCop，没有 Java 时移除 Checkstyle。
• 运行失败？ 检查 toolResults[].status。如果值为 "failed"，请查看 errors[] 了解原因。保留配置中的工具（修复根本原因后可能可以正常运行），但在摘要中注明。
• 问题数为零？ 工具没有报告问题并不代表它会产生噪声——这可能说明它确认了代码质量，或没有找到目标文件。除非它明显与技术栈无关，否则保持启用。

4e. 恢复丢失的模式

将基线分析结果（步骤 0）与调整后的 .codacy/codacy.config.json 对比。对于满足以下条件的每个模式：

• 在基线分析中发现了问题（Track A 查看 .codacy/tmp/codacy-remote-results.json，Track B 查看 .codacy/tmp/codacy-previous-results.json）
• category == "Security"，或 severity == "Error"，或 severity == "High"
• 当前配置中不存在（因 init --auto 排除或在调整时移除）

→ 将其添加回相应工具的配置中。这是内部保留步骤——恢复的模式不会在摘要中作为变更报告（它们已存在于基线配置中，因此从用户角度来看并无变化）。

Track C 跳过此步骤（没有先前配置需要恢复）。

应用所有更改

根据 4a–4e 中的所有决策编辑 .codacy/codacy.config.json。记录每项更改，以便在第 5 步生成摘要：

• 对于每个已禁用的模式：记录 patternId、操作 "disabled" 和原因
• 对于每个已调整的模式：记录 patternId、操作 "updated"、旧参数/新参数和原因
• 对于每个已移除的工具：在 toolChanges 中记录
• 对于每个已添加的工具：在 toolChanges 中记录
• 对于每个新添加的文件排除项：在 fileExclusions 中记录
• 已恢复的模式（第 4e 步）不纳入摘要——它们会保留现状

安全防护——保存前必须检查。 写入更新后的配置前，请确认每个安全问题（例如硬编码密钥、SQL 注入、XSS、路径遍历、开放重定向）仍由至少一个 category == "Security" 的活动模式覆盖。只有当另一个不同工具中的活动模式覆盖相同问题时，才可以禁用安全模式（按第 4b 步规则 2 进行跨工具去重）。如果任何问题失去了所有覆盖，请重新启用针对该问题最精准的模式。

4f. 验证

使用调整后的配置运行分析，以验证改进效果：

codacy-analysis analyze --install-dependencies --output-format json --output .codacy/tmp/codacy-tuned.json

记录分析后的指标：

# Enabled patterns after tuning
jq '[.tools[].patterns | length] | add' .codacy/codacy.config.json

# Enabled tools after tuning
jq '.tools | length' .codacy/codacy.config.json

# Total issues after tuning
jq '.issues | length' .codacy/tmp/codacy-tuned.json

# Runtime after tuning
jq '.metadata.durationMs' .codacy/tmp/codacy-tuned.json

验证：

• 与宽泛配置基线（第 3 步）相比，问题数量应显著减少。
• 如果问题数量增加或没有显著减少（降幅低于 20%），请检查调整决策并重新迭代一次：返回“对结果进行 AI 分析”（第 4b 步），使用更新后的结果进行分析，应用进一步更改，然后重新运行此验证。
• 目标是让每个剩余问题都值得进一步查看。

第 5 步：显示本地结果

5a. 生成摘要 JSON

将 .codacy/configure-codacy-summary.json 写入文件，其中包含更改前后的指标、详细的更改日志以及支持上下文。运行时长的单位为毫秒（CLI 返回的原始 durationMs）。

before 值来自第 0 步（任何更改之前记录的基线——Track A 使用 Cloud 配置，Track B 使用本地配置，Track C 使用未配置状态）。after 值来自第 4f 步（最终调整后的配置）。如果不存在初始配置（Track C），则 before 值反映未配置状态——对于无法测量的指标（例如运行时长）使用 null，对于计数（模式、工具、问题）使用 0。

{
  "summary": {
    "enabledPatterns": { "before": 1000, "after": 300 },
    "enabledTools": { "before": 34, "after": 15 },
    "issues": { "before": 7000, "after": 550 },
    "analysisRuntime": { "before": 240000, "after": 60000 }
  },
  "toolChanges": [
    {
      "toolId": "Biome",
      "action": "disabled",
      "reason": "Project uses ESLint9 with local config; Biome is redundant and produced 16K false positives in TypeScript",
      "patternsAffected": 232
    },
    {
      "toolId": "markdownlint",
      "action": "enabled",
      "reason": "New tool added for Markdown linting; README.md excluded per-tool to avoid inline HTML noise",
      "patternsAffected": 43
    }
  ],
  "patternChanges": [
    {
      "patternId": "Semgrep_python.lang.security.audit.xss.template-injection",
      "toolId": "Semgrep",
      "action": "disabled",
      "reason": "Wrong stack — pattern for Python; project is JavaScript-only",
      "delta": -45,
      "parameters": []
    },
    {
      "patternId": "Lizard_ccn-medium",
      "toolId": "Lizard",
      "action": "updated",
      "reason": "Raised threshold from 10 to 20 to match codebase complexity profile",
      "delta": -120,
      "parameters": [
        { "id": "threshold", "before": "10", "after": "20" }
      ]
    },
    {
      "patternId": "Semgrep_codacy.javascript.security.hard-coded-password",
      "toolId": "Semgrep",
      "action": "enabled",
      "reason": "New High Security pattern — detects hardcoded passwords; found 101 issues across 41 files for review",
      "delta": 101,
      "parameters": []
    }
  ],
  "fileExclusions": {
    "global": ["src/routeTree.gen.ts"],
    "perTool": {
      "markdownlint": ["README.md"]
    }
  },
  "securityCoverage": {
    "deduplication": [
      "Semgrep slack-webhook-url disabled — same concern covered by Semgrep detected-slack-webhook"
    ],
    "newCoverage": [
      "unsafe-dynamic-method (Critical, 5 issues)",
      "open-redirect-from-function (Critical, 4 issues)",
      "hard-coded-password (High, 101 issues)"
    ],
    "noisyButKept": [
      "Semgrep hard-coded-password (101 issues) — kept per security guardrail, file exclusions preferred over disabling"
    ]
  },
  "keyImprovements": [
    "Lizard complexity thresholds tuned to match mature React SPA — 576 fewer noise issues while keeping genuinely complex functions flagged",
    "6 new security patterns detecting open redirects, unsafe dynamic methods, hardcoded passwords, and React href injection (119 new findings)",
    "markdownlint added for Markdown quality",
    "Checkov expanded from 6 to 1358 IaC security patterns"
  ],
  "localConfigTools": [
    {
      "toolId": "ESLint9",
      "configFile": "eslint.config.js",
      "issueCount": 42,
      "note": "Issues from this tool are controlled by the project's ESLint config, not Codacy patterns. Edit eslint.config.js to reduce noise."
    }
  ],
  "codacyYaml": null,
  "importResults": null,
  "cloudVerification": null
}

字段说明：

summary — 更改前/后的指标（与之前相同）。

toolChanges — 每个已添加或移除的工具对应一条记录。每条记录包含：

• toolId — 工具标识符
• action — "enabled"（已添加工具）或 "disabled"（已移除工具）
• reason — 添加或移除工具的原因
• patternsAffected — 已添加/移除工具中的模式数量

patternChanges — 每个单独模式更改对应一条记录。每条记录包含：

• patternId — 模式标识符
• toolId — 此模式所属的工具
• action — "enabled"、"disabled" 或 "updated"
• reason — 进行此更改的原因（便于审计）
• delta — 此模式的问题数量变化，比较初始状态（第 0 步）与最终调整后的状态（第 4f 步）。如果该模式在初始配置中未启用，delta 就是调整后分析中该模式产生的问题总数（新启用时为正数，调整期间禁用时为 0）。
• parameters — 参数更改（不适用时为空数组）

如果某个模式是作为整个工具更改的一部分而添加/移除的，请勿在 patternChanges 中为其添加单独的记录。这些更改已由 toolChanges 条目涵盖。patternChanges 用于记录仍保持启用状态的工具内部，对单个模式进行的精细调整。

请勿在此处包含 "restored" 模式。恢复（第 4e 步）是一种内部机制，用于确保 init --auto 不会遗漏基线配置中产生 Critical/High/Security 结果的模式。它会保留原有配置，并非面向用户的更改。 fileExclusions — 仅列出本次调优新增的排除项。基线配置中已有的排除项会自动保留，但不会在此列出（它们不属于变更）。

• global — 调优期间新增的全局排除 glob
• perTool.<toolId> — 调优期间新增的各工具排除 glob

如果没有新增排除项，则完全省略 fileExclusions。

securityCoverage — 说明如何处理安全问题：

• deduplication — 因其他模式已覆盖相同问题而停用的安全模式（列出保留的模式和停用的模式）
• newCoverage — 启用的、不在基线配置中的新安全模式，以及问题数量
• noisyButKept — 噪声较大但根据安全防护规则仍保持启用的安全模式

keyImprovements — 包含 3–6 句易于理解的句子，总结影响最大的改进。重点说明发生了哪些变化及其量化影响。这些内容应适合向用户展示为摘要。

localConfigTools — 包含 useLocalConfigurationFile: true 的工具数组。每个条目包括：

• toolId — 工具标识符
• configFile — 此工具使用的项目配置文件路径
• issueCount — 此工具在调优后的分析中产生的问题数量
• note — 易于理解的说明，指出此工具的噪声由项目自身的配置控制，而非 Codacy 模式

如果没有工具使用本地配置文件，则为空数组。

codacyYaml — 如果添加了文件排除项（见步骤 5c），则为包含生成的 .codacy.yaml 文件内容的字符串。如果未生成 .codacy.yaml，则为 null。

importResults — 在步骤 6 执行之前为 null。如果执行了 Cloud 导入，则填入导入结果（架构见步骤 6f）。

cloudVerification — 除非执行步骤 6e，否则为 null。包含导入后 Cloud 验证结果：重新分析是否已完成、前后问题数量、在 Cloud 上停用的模式以及警告。架构见步骤 6e。

5b. 展示本地结果

向用户清晰展示变更前后的摘要：

1. 指标表 — 启用的模式、启用的工具、问题总数和运行时间（变更前与变更后，并显示减少百分比）。“变更前”应使用步骤 0 中的基线。如果之前不存在配置（Track C），则在“变更前”列注明“无先前配置”。
2. 工具变更 — 新增或移除的工具及其原因
3. 影响最大的模式变更 — 按 |delta| 从大到小排序的 patternChanges 条目
4. 新增安全覆盖 — 基线配置中不存在的新安全模式
5. 安全去重 — 已去重的安全模式（说明保留了哪些模式、停用了哪些模式）
6. 关键改进 — 将摘要 JSON 中的 keyImprovements 数组以项目符号列表形式呈现
7. 警告 — 失败的工具、Semgrep 解析错误、匹配到 0 个文件的工具，以及遇到的其他问题
8. 本地配置文件的限制 — 对于 useLocalConfigurationFile: true 的工具，请说明其问题由项目自身的配置文件（例如 .eslintrc、.rubocop.yml）控制，而非由 Codacy 托管的模式控制。要减少这些工具产生的噪声，只能编辑项目自身的配置。列出每个此类工具及其产生的问题数量，以便用户知道如需进一步降低噪声应查看哪些内容。

5c. 为 Cloud 文件排除项生成 .codacy.yaml

.codacy/codacy.config.json 中的文件排除项仅适用于本地分析。Codacy Cloud 不支持通过 API 或 CLI 导入文件排除项。若要在 Codacy Cloud 上应用文件排除项，必须将其定义在提交到仓库根目录的 .codacy.yaml 文件中（参见 Codacy 配置文件）。

如果在调整过程中添加了任何新的文件排除项（全局或按工具设置），请生成 .codacy.yaml 文件：

1. 读取仓库根目录中现有的 .codacy.yaml（如果存在），以保留已有配置
2. 将新的排除项与现有的 exclude_paths 和按引擎设置的 exclude_paths 合并
3. 将更新后的 .codacy.yaml 写入仓库根目录

.codacy.yaml 格式使用 Java glob 语法：

---
exclude_paths:
  - "src/routeTree.gen.ts"
  - "vendor/**"
engines:
  markdownlint:
    exclude_paths:
      - "CHANGELOG.md"
  stylelint:
    exclude_paths:
      - "assets/vendor/**"

引擎名称映射： .codacy.yaml 中的引擎名称可能与 .codacy/codacy.config.json 中的工具 ID 不同。请使用小写形式的工具 ID 作为引擎名称（例如，ESLint9 → eslint9、Semgrep → semgrep、markdownlint → markdownlint）。如果不确定，使用小写形式的工具 ID 是安全的默认选择。

4. 将生成的 .codacy.yaml 完整内容作为字符串，存入摘要 JSON 的 codacyYaml 字段
5. 告知用户：
   • 文件排除项无法通过 API 导入 Codacy Cloud
   • 已在仓库根目录创建或更新 .codacy.yaml 文件
   • 用户应提交并推送此文件，以便在 Codacy Cloud 上应用排除项
   • Codacy Cloud 始终从默认分支读取 .codacy.yaml

如果没有添加新的文件排除项，则跳过此步骤，并将 codacyYaml 保留为 null。

步骤 6：导入 Cloud（有条件）

6a. 检查 Cloud 状态

如果仓库不在 Codacy Cloud 上（根据步骤 0）：完全跳过此步骤。在结果中注明：“配置已准备好用于本地分析。若要在 Codacy Cloud 上使用，请先将仓库添加到 Codacy。”

6b. 确定导入行为

根据调用模式（参见“调用模式”部分）：

1. 自动导入模式（用户使用“import”参数调用）：直接继续执行 6c。
2. 交互模式（默认）：使用 AskUserQuestion 询问用户：“要在 Codacy Cloud 中更新这些配置吗？”如果用户拒绝，则跳到步骤 7。
3. 仅本地模式：已在 6a 中处理（已跳过）。

6c. 评估 Cloud 专属工具的问题噪声

仅当步骤 0 中获取了 Cloud 专属工具的问题时（.codacy/tmp/codacy-remote-cloud-results.json 存在）：

对从 Cloud 获取的问题应用步骤 4 中相同的噪声评估框架。对于每个 Cloud 专属工具产生的噪声模式：

• 检查是否可以调整其参数以减少结果 → codacy pattern <toolName> <patternId> --parameter key=value
• 如果无法调整 → 尝试禁用它：codacy pattern <toolName> <patternId> --disable
• 如果禁用失败（受编码标准强制约束）→ 在结果中注明

6d. 导入本地配置

codacy tools --import .codacy/codacy.config.json -y

如果导入遇到编码标准冲突（409 错误——组织级强制执行的模式/工具无法被覆盖）：

1. 如果启用了强制模式（用户使用“force”参数调用）：自动使用 --force 重试：

   codacy tools --import .codacy/codacy.config.json --force -y
   

   在结果中注明使用了 --force，以及取消关联了哪些编码标准。

2. 如果未启用强制模式（默认）：不要自动使用 --force 重试。相反：

   • 报告哪些工具/模式因编码标准强制执行而无法更改
   • 列出阻止这些更改的具体编码标准
   • 使用 AskUserQuestion 询问用户：“导入被编码标准 [list names] 部分阻止。是否要取消关联这些编码标准并使用 --force 重试？这会切断此代码库与组织级标准之间的关联。”
   • 如果用户接受 → 使用 --force 重试
   • 如果用户拒绝 → 保留当前部分导入状态，并在结果中注明被阻止的更改

未经用户明确同意或未使用“force”调用标志，绝不取消关联编码标准。

重要： .codacy/codacy.config.json 文件仅供本地使用。将其提交或推送到代码库对 Codacy Cloud 没有任何影响。导入命令是将本地配置同步到 Cloud 的唯一方式。

6e. 导入后验证 Cloud

成功导入（或部分导入）后，触发重新分析并等待 Cloud 结果，以验证配置在 Cloud 环境中是否按预期生效。Cloud 分析结果可能与本地分析不同（工具版本不同、以容器方式执行、文件可见性不同）。

1. 触发重新分析并等待完成：

使用 --reanalyze-and-wait 触发重新分析，自动轮询（每 10 秒一次，最长 20 分钟），并获取按模式、严重程度和类别划分的问题变化增量报告：

codacy repository --reanalyze-and-wait -o json > .codacy/tmp/codacy-reanalysis-delta.json

这取代了手动轮询。CLI 会在重新分析前捕获基线，等待分析完成，并报告完整增量。如果 20 分钟后超时，它会报告已知信息并退出——在警告中注明超时，并在未完成 Cloud 验证的情况下继续。

2. 获取最新的 Cloud 概览并进行评估：

重新分析完成后（检查增量报告），获取更新后的问题概览：

codacy issues -O -o json > .codacy/tmp/codacy-post-import-overview.json

将导入后的概览与导入前的概览（.codacy/tmp/codacy-cloud-overview.json）进行比较。对于新概览中的每种模式，按问题数量从高到低排序：

• 如果某种模式的问题数量较多，且不属于安全类别，严重程度也不是严重/高 → 则可考虑在 Cloud 端禁用
• 使用 Cloud 数据，应用步骤 4b 中相同的噪声处理框架（语言不匹配、约定不匹配、重复项）
• 对于应禁用的模式，使用 Cloud CLI：

  codacy pattern <toolId> <patternId> --disable
  

• 如果因编码标准强制执行而无法禁用，请在警告中注明
• 还要禁用步骤 0c 中 cloudNoiseCloudOnly 列表内此前暂缓处理的所有模式

4. 记录 Cloud 验证结果：

在摘要中新增 cloudVerification 字段，跟踪所有 Cloud 端的模式更改：

{
  "cloudVerification": {
    "reanalysisCompleted": true,
    "issuesBefore": 375,
    "issuesAfter": 280,
    "patternsDisabled": [
      {
        "patternId": "markdownlint_MD033",
        "toolId": "markdownlint",
        "reason": "Convention mismatch — 150 inline HTML issues in documentation files",
        "issueCount": 150
      }
    ],
    "warnings": []
  }
}

如果重新分析超时或跳过了 Cloud 验证，将 reanalysisCompleted: false 设为 false，并在警告中注明原因。

6f. 显示 Cloud 导入结果

使用导入结果更新 .codacy/configure-codacy-summary.json 中的 importResults 字段：

{
  "importResults": {
    "status": "success | completed_with_errors | failed",
    "toolsConfigured": 10,
    "toolsEnabled": ["markdownlint"],
    "toolsDisabled": ["PMD"],
    "errors": [
      {
        "toolId": "ESLint9",
        "error": "Conflict (409)",
        "detail": "Unable to update Project Tool Patterns, repository is using a Configuration File"
      },
      {
        "toolId": "PMD",
        "error": "Conflict (409)",
        "detail": "Cannot disable a tool that is enabled by a standard"
      }
    ],
    "warnings": [
      "7 Semgrep pattern parsing errors (non-blocking)",
      "Agentlinter: 0 files matched — no agent config files in this SPA"
    ],
    "codingStandards": ["AI Policy", "Our Default + SOC2"],
    "forceUsed": false
  }
}

importResults 字段参考：

• status — 如果所有工具均无错误地导入，则为 "success"；如果部分工具失败但其他工具成功，则为 "completed_with_errors"；如果导入命令本身失败，则为 "failed"
• toolsConfigured — 成功配置的工具数量
• toolsEnabled — 在 Cloud 中新启用的工具（之前处于禁用状态）
• toolsDisabled — 在 Cloud 中禁用的工具（之前处于启用状态）——如果编码标准阻止禁用，则可能为空
• errors — 按工具列出的错误数组，每项包含 toolId、error（HTTP 状态或错误类型）和 detail（CLI 返回的错误消息）
• warnings — 非阻塞警告数组（分析错误、没有文件的工具等）
• codingStandards — 与仓库关联的编码标准名称（来自步骤 0）；如果没有，则为空数组
• forceUsed — 是否使用了 --force 来取消关联编码标准

向用户展示导入结果：

• 成功更新的内容
• 无法更改的内容（编码标准强制执行）——逐条列出错误及其详细信息
• 仅限 Cloud 的工具模式更改（来自 6c）
• 是否使用了 --force，以及这意味着什么

步骤 7：清理

删除临时目录和所有中间文件：

rm -rf .codacy/tmp

各工具调优提示

Semgrep

Semgrep 提供了适用于 30 多种语言的模式。初始化后，许多模式可能针对项目中未使用的语言。在步骤 4 中，禁用 discover 未发现的语言所对应的模式——这通常是减少噪声最有效的方法。将模式 ID 前缀（例如 python.、javascript.、java.）与发现的语言进行交叉比对。

Lizard（复杂度）

Lizard 提供圈复杂度（CCN）、代码行数（NLOC）和参数数量的规则，每项指标都有三个严重级别（Critical、Medium、Minor），并提供可配置的 threshold 参数。

对于已有一定规模／成熟的代码库，默认的 Medium 阈值会在旧代码中产生数百条命中。可选做法：

• 禁用 Medium 级别规则，仅保留 Critical
• 或提高 Medium 阈值，使其符合项目的实际复杂度情况（更推荐——这样可以保留可见性）

对于从零开始的项目，默认阈值较为合理。

ESLint9

ESLint 会加载项目自身的配置文件（例如 eslint.config.js），其中可能会导入依赖包。如果项目已有 ESLint 配置，步骤 3 中的 --install-dependencies 标志应能处理这种情况。如果 ESLint 仍然因 InvocationError 失败，分析前可能需要在项目中运行 npm install 或等效命令。

如果项目已有 ESLint 配置，且用户希望保留该配置，请在 ESLint9 工具条目中设置 useLocalConfigurationFile: true，而不是使用 Codacy 管理的模式。

markdownlint

MD034（裸 URL）、MD024（重复标题）、MD010（硬制表符）、MD004（列表样式）、MD033（内联 HTML）和 MD036（用强调格式充当标题）等规则会在 CHANGELOG 和自动生成的文档中大量触发。这些属于风格问题，而非 Bug。建议通过针对工具的 exclude 排除噪声文件，而不是彻底禁用这些规则。

Stylelint

请结合上下文审查结果——一些看似违规的 CSS 规则可能是有意为之（例如，需要覆盖第三方样式的应用通常需要 !important 和限定选择器）。如果项目已有 Stylelint 配置，可考虑设置 useLocalConfigurationFile: true。

安全防护原则

每项安全问题都必须至少由一个启用的模式覆盖。 这是硬性规则，没有例外。

防护原则适用于问题级别，而非单个模式级别。如果两个工具都能检测“硬编码密钥”，那么停用精度较低的那个工具是可以接受的，因为该问题仍有覆盖。不过，如果停用某个模式会导致某项安全问题（例如 SQL 注入、XSS、路径遍历、硬编码密钥）失去所有启用模式的覆盖，则必须撤销停用操作。

如果某个安全模式误报较多，且无法去重：

• 排除触发误报的特定文件（例如测试夹具、模拟数据）
• 保留误报，供用户在 Codacy Cloud 中审核（用户可以填写原因，忽略个别实例）
• 绝不要移除覆盖某项安全问题的最后一个模式——必须保持启用，以便发现未来代码中的实际漏洞

对于非 Security 类别中的 Critical/High 严重性模式，也要采取同样谨慎的做法：优先排除文件，而不是停用模式。只有当这些模式明显针对错误的技术栈时，才停用它们（例如，在纯 Python 项目中使用 Java Critical 模式）。