CLI工具使用嵌入模型检测代码非精确重复

Slopo：基于嵌入模型的非精确代码重复检测CLI工具

背景

在现代软件开发中，代码重复是长期维护的顽疾。传统检测工具（如Copypaste或相似性扫描器）主要关注精确复制（exact copy-paste）的代码片段，或者相邻位置的重复。这些工具无法有效识别“非精确重复”——即写法相似但实现细节有差异、散布在不同模块或大型文件中的代码。这类重复往往最难被人类发现，也最容易在代码库中累积，增加bug风险和维护成本。

Slopo.dev 作为高层次问题描述页面，指出这一痛点正是AI辅助开发中常引入的“缺失环节”。用户常通过AI代理在不同文件间复制上下文，导致代码库中出现“写法相似但功能类似”的冗余片段。Slopo 正是针对这类“最难检测、最有害”的非精确重复而设计的轻量级CLI工具，填补了传统检测工具的空白。

核心内容

Slopo 是一个专为 Python、TypeScript、JavaScript、Java、Kotlin、C#、Go、Rust 等主流语言设计的轻量级CLI工具，核心目标是使用嵌入模型（embedding models）检测代码库中非精确重复的代码片段。

工具采用与传统检测工具不同的方法：对每个代码单元（code unit）计算嵌入向量后，寻找嵌入向量距离较近的代码对。由于“写法相似但功能不同的代码”通常不会产生接近的嵌入，因此仅将相似代码对作为潜在重复的候选，再由后续确认环节验证是否为真正重复。完全不同实现的代码（如同一功能用不同语言/风格实现）因嵌入距离远而不会被检测到。

检测结果会生成代码单元集群（clusters），按相似度（cosine similarity）和代码库中位置距离（hops）排序。这些集群作为输入提供给AI编码代理（AI coding agent），让代理决定是否为真实重复。已验证重复可标记为“ignored”，或直接传递给重构（refactoring）。

工作流程详解：

1. 环境准备：

   • 使用 uv 工具安装（uv tool install slopo），在隔离虚拟环境中从 PyPI 安装，无需单独安装 Python。
   • 执行 slopo init 创建配置文件模板（slopo.config），仅需指定待分析的代码目录和嵌入模型配置。

2. 嵌入计算：

   • 使用外部提供商（如 Voyage AI，推荐512维度专用代码模型）计算嵌入。支持兼容 LiteLLM 的任何提供商。
   • API Key 通过环境变量 SLOPO_EMBEDDING_API_KEY 设置（或 .env 文件）。

3. 索引与分析：

   • slopo index：创建 SQLite 数据库（slopo.db），存储索引数据。
   • slopo embed：计算代码单元嵌入。
   • slopo analyze：生成报告，输出 index.md（包含所有集群列表及每文件详情）。

配置文件关键参数（大部分可选，智能默认值）：

• source_dir：待分析代码目录（绝对或相对路径）。
• source_dir_exclude：.gitignore 风格排除模式（建议排除测试目录）。
• db_file：SQLite 数据库文件。
• report_dir：报告输出目录。
• ignore_file：已审查集群忽略列表（可提交 Git）。
• embedding_model：LiteLLM 格式模型名称（如 voyage-3-small）。
• embedding_dimensions：模型兼容维度（如 512）。
• embedding_api_key：提供商密钥。
• embedding_batch_size / embedding_batch_chars：批处理参数。
• similarity_threshold：余弦相似度阈值（1 表示完全相同）。
• rerank_threshold：集群最高评分对的阈值（考虑目录跳数和行距加权）。
• body_node_count_threshold：AST 节点数阈值（排除签名和注解，反映代码复杂度）。

增量更新机制：

• 支持增量索引（仅更新修改文件）。
• 通过 ignore_file 提交 Git 仓库，实现跨团队复用。
• 不建议提交 slopo.db（本地数据）。

报告特性：

• 精确复制（exact copies）单独处理：报告一次代码，列出所有路径，避免重复片段。
• 分析报告包含两种相似度比率：含精确复制和不含精确复制。

示例：

• 分析代码库 src 目录（git tag v0.2.0），发现解析器代码存在大量重复（部分精确复制，部分相似变体），建议重构。
• 完整示例报告可在 slopo.dev 或仓库 doc/example-report 查看。

使用 slopo --help 或 slopo show-config 可随时查看配置。某些参数（如 source_dir、embedding_model）首次索引后不可更改，需删除 slopo.db 并重新从头执行。

关键要点

• 核心技术：嵌入模型检测非精确重复，而非精确复制；最终集群由 AI 代理确认。
• 适用语言：Python、TypeScript、JavaScript、Java、Kotlin、C#、Go、Rust。
• 安装与启动：uv install + slopo init + slopo show-config；支持环境变量与 .env 配置文件。
• 核心命令：slopo index / embed / analyze；支持增量更新与 ignore_file。
• 过滤机制：双阈值过滤（相似度 + rerank），body_node_count_threshold 基于 AST 节点数。
• 报告特点：index.md 详列集群，精确复制与非精确复制分开统计相似度比率。
• 安全与扩展性：API Key 环境变量可选；配置文件可提交 Git，slopo.db 不可提交。
• 推荐模型：专用代码嵌入模型（如 Voyage AI，低维度）效果最佳。

意义与影响

Slopo 填补了 AI 辅助开发中“AI 代理复制上下文导致代码库冗余”的关键空白。它能主动扫描散布在整个代码库的“最难检测”的非精确重复，帮助开发团队及时识别并重构，避免这些重复累积成维护噩梦。

通过将集群作为 AI 编码代理的输入，Slopo 实现了工具链闭环：检测 → AI 确认/忽略 → 增量报告 → 重构循环，大幅提升代码质量和团队效率。

该工具开源且轻量，用户可快速集成到现有 CI/CD 或开发工作流中。长期来看，它将显著降低软件维护成本，减少因重复代码引入的 bug，并为 AI 代理提供更干净的代码环境，推动更高效的代码治理和质量保障。