配置参考

Deslop 有两种配置方式：

.deslop.toml — 与代码放在一起、并纳入版本管理的文件。项目级策略写在这里：跳过什么、隐藏什么、何时让 CI 失败。
命令行参数 — 单次运行的覆盖项。参数始终优先于对应的配置键。

本页是一份参考手册。需要循序渐进的教程，请从快速开始读起。

`.deslop.toml` 文件

文件位置

Deslop 会在扫描根目录（你指向的目录）旁查找 .deslop.toml。用 --config 可以指向别处：

deslop .                          # 若存在则使用 ./.deslop.toml
deslop ./src --config ci.toml     # 显式指定配置，文件名任意

缺少配置文件不算错误 — Deslop 会按下文的内置规则运行。

格式

TOML 格式：一个共享的 [defaults] 区段，外加可选的按语言覆盖区段和四个行为区段。模式是带 gitignore 语义的 glob 模式，相对扫描根目录解析 — 无论仓库在磁盘上位于何处，subdir/** 都匹配 <扫描根>/subdir/...。

`exclude` 与 `report_hide` — 核心区别

这两层做的事不同，区别很关键：

	会发生什么	适用于
`exclude`	文件在分析前被丢弃 — 既不解析，也不指纹化。	第三方代码、构建产物，以及任何你永远不想参与比较的内容。
`report_hide`	文件会被分析，但每处出现都被标记为隐藏。只有当一个簇的全部成员都是隐藏的时，它才会从报告中移除。	生成的代码。你仍然想知道何时手写代码与某个生成文件重复了。

这种不对称是刻意的。report_hide 让"生成代码与自身重复"不进入头条，同时仍然暴露"你的代码与生成代码重复"的情况 — 因为那个簇至少有一个非隐藏成员，所以它会保留下来。

`[defaults]`

应用于每个文件，与语言无关。

[defaults]
exclude = [
  "**/node_modules/**",
  "**/dist/**",
  "vendor/**",
]
report_hide = [
  "**/*.snapshot.cs",
]

[defaults.boilerplate]
imports = "report"

键	类型	默认值	含义
`exclude`	glob 列表	`[]`	从发现阶段丢弃的文件。与内置 exclude 叠加。
`report_hide`	glob 列表	`[]`	会被分析但从渲染报告中隐藏的文件。与内置隐藏规则叠加。
`boilerplate.imports`	`"suppress"` \| `"report"`	`"suppress"`	如何处理仅由 import / 序言构成的克隆。`suppress` 静默丢弃；`report` 仍抑制克隆告警，但发出一条低严重度的整洁度提示。

`[language.<name>]`

按语言的覆盖区段。名称是解析器的语言 id：csharp、rust、python、dart。这里的模式扩展默认值 — 永不替换 — 因此一个 .cs 文件会同时针对 defaults.exclude 加上 language.csharp.exclude 进行测试。

[language.csharp]
report_hide = ["**/Migrations/**"]

[language.python]
exclude = ["**/conftest.py"]

[language.dart.boilerplate]
imports = "report"

每个覆盖区段都接受与 [defaults] 相同的三个键：exclude、report_hide 和 boilerplate.imports。

`[threshold]` — CI 门禁

[threshold]
max_duplication_percent = 20

键	类型	范围	含义
`max_duplication_percent`	浮点数	`0.0`–`100.0`	当全仓库的 `duplication_percent` 超过此值时，`deslop` 以 `3` 退出并使 CI 失败。

这是唯一需要显式启用的失败路径。没有 [threshold] 区段（且没有 --fail-over）时，无论发现多少重复，deslop 始终以 0 退出。命令行 --fail-over 参数会覆盖此键；--no-fail-over 会在单次运行中清除它。参见输出格式 → 退出码。

`[analysis]`

[analysis]
allow_cross_language_comparison = false

键	类型	默认值	含义
`allow_cross_language_comparison`	布尔	`false`	为 `true` 时，候选克隆对可以跨越不同语言。默认关闭，使报告聚焦于同语言重构。

`[report]`

[report]
split_by_language = false

键	类型	默认值	含义
`split_by_language`	布尔	`false`	将 HTML 报告按语言划分为各自的区段。`--split-by-language` 参数也能开启它 — 任一来源都会生效。

`[ranking]`

控制两类可降权克隆的评分方式。数据克隆是近乎逐字的数据块（长字面量表、夹具）。仅结构簇仅在形状上匹配，没有词法或语义支撑。两者都默认 demote，从而沉到真正的全证据克隆之下，但不消失。

[ranking]
data_clones = "demote"
data_clone_weight = 0.15
structural_only = "demote"
structural_only_weight = 0.15

键	类型	默认值	含义
`data_clones`	`"demote"` \| `"ignore"` \| `"keep"`	`"demote"`	数据类簇的策略。`demote` 降权，`ignore` 从报告中丢弃，`keep` 以全权重排名。
`data_clone_weight`	浮点数	`0.15`	`data_clones = "demote"` 时所乘的系数。必须在 `(0.0, 1.0]` 内。
`structural_only`	`"demote"` \| `"ignore"` \| `"keep"`	`"demote"`	对仅结构簇的同一套三选一策略。
`structural_only_weight`	浮点数	`0.15`	`structural_only = "demote"` 时所乘的系数。必须在 `(0.0, 1.0]` 内。

系数 0.0 会被拒绝（被降权的簇绝不能被静默抹除），大于 1.0 的值同样被拒绝（那会提升被降权的类别）。VS Code 扩展可以从其设置覆盖 structural_only；编辑器设置优先于文件。

内置规则（始终生效）

无论你如何配置，这些规则都会运行且无法关闭 — 它们让依赖树和机器生成代码远离每一份报告。

始终排除（路径中包含以下任一目录组件的文件）：

node_modules   target   dist   build   .venv   __pycache__
.cargo   .git   .claude   .dart_tool   .pub-cache

始终从报告中隐藏（会被分析，但不进入头条）：

目录组件 generated/。
相邻组件对 alembic/versions、test/fixtures、tests/fixtures — 除非该对本身就是你的扫描根，从而让你能够刻意分析一个夹具语料库。
文件后缀：.g.cs、.generated.cs、.designer.cs、.pb.cs、.openapi.cs、.generated.py、_generated.py、.g.dart、.freezed.dart、.gr.dart、.config.dart、.gen.dart、.mocks.dart、.pb.dart、.pbenum.dart、.pbjson.dart、.pbserver.dart、.pbgrpc.dart。
任何在前一千字节内带有生成代码横幅的文件：@generated、GENERATED CODE、auto-generated、autogenerated 或 automatically generated（不区分大小写匹配）。

一个完整示例

# 在各处跳过第三方代码和构建产物。
[defaults]
exclude = [
  "**/node_modules/**",
  "**/dist/**",
  "third_party/**",
]
report_hide = [
  "**/*.snapshot.cs",
]

# 对仅由 import 构成的克隆给出整洁度提示，而非静默丢弃。
[defaults.boilerplate]
imports = "report"

# C# 数据库迁移是生成的 — 分析但隐藏它们。
[language.csharp]
report_hide = ["**/Migrations/**"]

# 全仓库重复超过 20% 时让 CI 失败。
[threshold]
max_duplication_percent = 20

# 将 HTML 报告按语言拆分。
[report]
split_by_language = true

# 直接丢弃纯仅结构匹配，而不是降权。
[ranking]
structural_only = "ignore"

命令行参数

每次运行也接受参数。在该次运行中，参数会覆盖对应的 .deslop.toml 键。

参数	默认值	含义
`PATH`	`.`	要分析的目录（位置参数）。
`--min-nodes <N>`	`30`	构成克隆候选的最小 AST 子树节点数。越大 = 克隆越少、越大。
`--output <PREFIX>`	`deslop-report`	报告的基路径；会追加 `.json` / `.txt` / `.html`。
`--config <FILE>`	`<root>/.deslop.toml`	显式配置文件。
`--split-by-language`	关	每种语言一个 HTML 区段（等同于 `[report] split_by_language`）。
`--nojson` / `--notext` / `--nohtml`	全开	抑制单一输出格式。至少需保留一种。
`--fail-over <PERCENT>`	—	重复超过 `PERCENT` 时以 `3` 退出。覆盖 `[threshold]`。
`--no-fail-over`	—	在该次运行中清除任何阈值；绝不以 `3` 退出。
`--technical`	关	在 stderr 上显示研究者视图（分类 id、信号字母、节点数）。

嵌入

混合嵌入层默认关闭；Deslop 不依赖它即可提供结构与词法信号。在你有可用提供方时再开启。

参数	默认值	含义
`--embeddings <MODE>`	`off`	`off` 跳过嵌入；`auto` 探测提供方，不可用时带告警回退；`required` 在提供方不可达时硬失败。
`--embedding-provider <ID>`	`ollama`	提供方注册键。目前仅实现了 `ollama`。
`--embedding-model <MODEL>`	`nomic-embed-text`	提供方所理解的模型 id（对 Ollama 即 `ollama list` 中的名称）。
`--embedding-endpoint <URL>`	`http://127.0.0.1:11434`	提供方端点。

日志与颜色

参数	默认值	含义
`--log-to-console`	关	将日志发往 stderr，而非带时间戳的 `deslop-<timestamp>.log` 文件。
`--log-level <LEVEL>`	`info`	`error` \| `warn` \| `info` \| `debug` \| `trace`。被 `RUST_LOG` 覆盖。
`--no-color`	关	关闭 stderr 前导与摘要中的颜色。
`--incremental`	关	启用 `<root>/.deslop-cache/` 下的磁盘指纹缓存。下次运行时未改动的文件会跳过解析。

开发与模拟参数

这些参数绕过或重放流水线，不属于常规使用：--from-report <FILE> 将已有的 JSON 报告重新渲染为 .txt/.html；--debug-ast <FILE> 打印单个文件的规范化 AST 后退出；--rerun-touch、--rerun-remove 和 --rerun-add 通过增量会话重放文件变更，以演练实时更新路径。

优先级与环境

当同一项设置来自多处时，由谁胜出如下：

阈值： --no-fail-over → --fail-over <n> → [threshold] max_duplication_percent → 关闭。
按语言拆分： --split-by-language 参数或 [report] split_by_language — 任一项都会启用。
排名（structural_only）： VS Code 扩展设置覆盖 .deslop.toml。

另有两个环境变量同样生效：

RUST_LOG — 以标准 tracing 过滤器语法覆盖 --log-level。
NO_COLOR — 即使没有 --no-color 也关闭颜色。当 stderr 不是终端时也会自动抑制颜色。