Desloppify - 一款让您的代码库更美好的代理工具 🤌

Desloppify 为您的 AI 编码代理提供了识别、理解并系统性提升代码库质量的工具。它结合了机械检测（如无用代码、重复代码、复杂度）与主观的 LLM 审查（如命名、抽象设计、模块边界），然后按照优先级驱动的修复循环逐步推进。扫描状态会持续保存，因此即使分多次进行也能不断优化代码；其评分机制经过精心设计，能够有效防止被“刷分”。

评分结果为您的代理提供了一个明确的目标指引，而配套工具则帮助它规划、执行并解决各类问题，直至达到您设定的质量标准——同时内置多种机制确保流程始终按计划推进。当评分超过 98 分时，通常意味着该代码库已达到了资深工程师所认为的“优美”水平。

这一评分还会生成一个积分卡徽章，您可以将其展示在 GitHub 个人主页或 README 文件中：

目前支持 29 种编程语言：对 TypeScript、Python、C#、C++、Dart、GDScript、Go 和 Rust 提供完整的插件深度支持；而对于 Ruby、Java、Kotlin 等另外 18 种语言，则采用通用的 linter 结合 Tree-sitter 解析器的支持。对于 C++ 项目，compile_commands.json 是主要的分析入口，而基于 Makefile 的仓库则会退而求其次，通过尽力扫描本地包含文件来进行分析。

供您的代理参考...

请将以下提示粘贴到您的代理中：

我希望你提升这个代码库的质量。为此，请安装并运行 desloppify。
请执行以下所有步骤（需 Python 3.11+）：

pip install --upgrade "desloppify[full]"
desloppify update-skill claude    # 安装完整的工作流指南 — 可选择 claude、cursor、codex、copilot、droid、windsurf 或 gemini

将 .desloppify/ 添加到 .gitignore 中——其中包含不应提交的本地状态。

在扫描之前，请检查需要排除的目录（如 vendor、构建输出、生成代码、工作树等），并使用 `desloppify exclude <path>` 排除明显无需扫描的部分。对于任何存疑的路径，请先与我沟通确认后再排除。

desloppify scan --path .
desloppify next

--path 参数指定要扫描的目录（使用 "." 表示整个项目，或 "src/" 等特定子目录）。

你的目标是尽可能提高严格评分。该评分机制不易被操纵——唯一提升评分的方式就是真正改善代码质量。

循环流程：运行 `next`。它代表当前待执行的任务队列，而非全部待办事项清单。它会告诉你现在该修复哪一行代码、哪个文件，以及完成后的解决命令。修复完成后，立即执行 `resolve`，再运行 `next`。如此反复，这就是你的核心任务。

仅在需要查看当前未纳入执行计划的更广泛待办事项时，才使用 `desloppify backlog`。

不要偷懒。无论是大规模重构还是细致的小修小补，都应投入同等精力。没有太大的任务，也没有太小的任务。务必彻底解决问题，而非仅仅做最低限度的改动。

使用 `plan` 或 `plan queue` 来调整优先级顺序或归并相关问题。定期重新扫描。扫描结果中会包含具体的行动指导，请遵照执行，切勿以自己的判断替代。

单体仓库与多项目目录

如果您的工作区包含多个独立的程序（例如，兄弟目录下的前端和后端），请分别使用 --path 参数对它们进行扫描：

desloppify --lang typescript scan --path ./frontend
desloppify --lang python scan --path ./backend

直接扫描包含这两个项目的父目录会导致不同代码库之间的状态和路径上下文相互干扰，从而产生不可靠的结果。每个 --path 指定的目标应当是一个完整的、连贯的项目。Desloppify 会为每种语言维护独立的状态，因此您可以在同一个工作区中分别扫描 TypeScript 前端和 Python 后端，而不会发生冲突——只需针对各自的目标单独执行扫描即可。

工作原理

扫描 ──→ 评分 ──→ 审查 ──→ 分类排序 ──→ 执行 ──→ 重新扫描
  │         │         │          │          │           │
  │     维度      │     优先级化    修复它     验证
  │     量化评估  LLM 主观评价  整理队列  解决它  改进效果
  │                 质量
  检测器发现
  机械性问题
  （无用代码、异味代码、测试覆盖率不足等）

扫描 会在您的代码库中运行一系列机械检测工具，包括无用代码、代码重复、复杂度、测试覆盖率不足、命名问题等。每个问题都会根据不同的维度（文件健康度、代码质量、测试健康度等）进行打分。

审查 则借助大型语言模型来评估主观质量维度，例如命名规范、抽象层次、错误处理模式以及模块边界等。这些主观评分会与机械检测结果一同纳入总分。

分类排序 是确定优先级的关键环节。代理（或您本人）会观察检测结果，归纳其中的规律，将问题归类分组，并补充具体的实现细节，最终形成有序的执行队列——只有明确列入队列的条目才会出现在 next 命令的输出中。在分类排序之前，所有机械性问题都会按影响程度排序显示在队列中，但可能会显得较为杂乱。

执行 是修复循环的核心：next → 修复 → resolve → next。待修复的条目均来自分类排序后的队列。自动修复功能会处理那些可以自动化解决的问题；其余部分则需要人工或代理进一步干预。

重新扫描 用于验证改进效果、捕捉连锁反应，并为下一轮循环提供数据支持。

扫描状态会持久化保存在 .desloppify/ 目录中，因此进度可以在不同会话之间延续。此外，其评分机制具有防作弊特性：若将某些问题标记为“不予修复”，将会拉大宽松评分与严格评分之间的差距；而再次审查相关维度时，如果发现新问题，评分还可能下降。

从 Vibe 编码到 Vibe 工程

Vibe 编码能让项目快速上线。然而，由此产生的代码库往往会在不易察觉、更难修复的方式下逐渐腐化——不仅体现在诸如未使用的导入之类的机械性问题上，还表现在结构性缺陷中。最初看似合理的抽象如今已不再适用；变量和函数的命名逐渐偏离初衷；错误处理方式更是五花八门，甚至同一种逻辑会有三种不同的实现。虽然代码库还能正常运行，但随着开发的推进，维护和协作的体验却每况愈下。

如今，如果提出恰当的问题，大型语言模型确实能够敏锐地识别出这些问题。这也是我们最核心的设想：借助合适的框架构建一个智能体，使其能够将代码库的质量维持在一个真正的标准之上——而这样的标准过去往往需要一位资深工程师耗费数月时间悉心把关才能达成。

因此，我们正尝试定义“好”的具体含义，并将其转化为一个真正值得优化的评分指标。这绝非那种通过压制警告就能轻易刷到100分的 Lint 分数，而是指当分数提升时，代码库本身也确实在质量上得到了实质性改善。这项工作颇具挑战，目前尚未完成，但我们非常重视防止“刷分”行为——因为这直接决定了指标是具有实际意义的信号，还是徒有其表的虚荣数字。

我们的愿景是：无论谁使用这套工具，都能打造出令经验丰富的工程师由衷钦佩的作品。这便是我们所追求的目标。

如果你也希望加入一群致力于创造卓越成果的 Vibe 工程师社区，欢迎来 Discord 交流。

---

我们非常欢迎各类问题、改进建议以及 Pull Request — 欢迎访问 github.com/peteromallet/desloppify。

Desloppify 对所有个人用户完全免费，无论是独立开发者还是企业员工，均可将其用于自身的工作。同时，开源公司也可在任何场景下免费使用，包括商业用途。对于希望将 Desloppify 商业化的非开源企业，请参阅 LICENSE，以获取透明的价格信息。

Desloppify 快速上手指南

Desloppify 是一个 AI 代理工具包，旨在帮助你的 AI 编程助手系统性地识别、理解并提升代码库质量。它结合了机械式检测（死代码、重复代码、复杂度）与大语言模型（LLM）的主观审查（命名、抽象、模块边界），通过优先级的修复循环持续优化代码。

环境准备

• 操作系统：支持 Linux、macOS、Windows
• Python 版本：必须为 Python 3.11 或更高版本
• 项目语言支持：
  • 深度支持：TypeScript, Python, C#, C++, Dart, GDScript, Go, Rust
  • 通用支持（基于 tree-sitter）：Ruby, Java, Kotlin 等共 29 种语言
• C++ 项目特别说明：首选提供 compile_commands.json，若无则尝试基于 Makefile 的本地包含扫描。

安装步骤

1. 升级 pip 并安装 Desloppify 完整功能包：

pip install --upgrade "desloppify[full]"

💡 国内加速建议：如果下载缓慢，可使用清华或阿里镜像源：

pip install --upgrade "desloppify[full]" -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 为你的 AI 代理安装工作流指南（根据你的代理类型选择其一）：

desloppify update-skill claude
# 或者
desloppify update-skill cursor
# 或者
desloppify update-skill copilot
# 其他可选：codex, droid, windsurf, gemini

3. 将生成的状态目录添加到 .gitignore，避免提交本地状态文件：

.desloppify/

基本使用

1. 排除无关目录（可选但推荐）

在扫描前，排除构建输出、第三方库、生成代码等目录：

desloppify exclude node_modules
desloppify exclude build
desloppify exclude dist

如有不确定的目录，请先与团队成员确认后再排除。

2. 执行全量扫描

对当前项目根目录进行扫描：

desloppify scan --path .

若为多项目仓库（如前后端分离），请分别扫描：

desloppify --lang typescript scan --path ./frontend
desloppify --lang python scan --path ./backend

3. 进入修复循环

运行以下命令获取当前最优先的修复任务：

desloppify next

该命令会输出：

• 需要修复的文件路径
• 具体问题描述
• 修复完成后执行的 resolve 命令

标准工作流程：

1. 执行 desloppify next 获取任务
2. 手动或由 AI 代理修复代码
3. 运行提示中的 resolve 命令标记完成
4. 重复执行 desloppify next 继续下一项

4. 查看与管理任务队列

• 查看待处理的全部 backlog（非当前执行队列）：

  desloppify backlog
  

• 调整优先级或聚类相关问题：

  desloppify plan
  desloppify plan queue
  

• 定期重新扫描以验证改进并发现新问题：

  desloppify scan --path .
  

5. 目标分数

持续修复直到严格评分（strict score）达到 98 分以上，这通常意味着代码库已达到资深工程师认可的“优美”标准。评分机制设计有防作弊逻辑，唯有真实提升代码质量才能提高分数。