技术债最麻烦的地方，不是“代码里有债”这个事实，而是每个人对优先级的感觉都不一样。有人盯着最长的文件，有人盯着最近出错的模块，有人盯着测试覆盖率最低的地方，还有人只记得上次 review 时最难读的函数。最后得到的往往是一串主观清单：都应该修，但很难说先修哪一个。

今天推荐的 iepathos/debtmap 试图把这个问题变成可排序的分析结果。它是一个 Rust 编写的技术债和代码风险分析 CLI，可以在终端、TUI 或 dashboard 中使用，也可以输出 JSON / Markdown，作为自动化和 AI coding assistant 的输入。GitHub 页面当前显示项目约 40 stars、5 forks，主要语言为 Rust，许可证为 MIT。仓库在 2025 年 8 月创建，最近仍在 2026 年 6 月活跃；Cargo.toml 中的当前版本是 0.17.1。

项目概览

属性详情
仓库iepathos/debtmap
定位技术债与代码风险分析 CLI
Stars约 40
Forks5
主要语言Rust
许可MIT
当前版本0.17.1
安装方式cargo install debtmap 或 release 安装脚本

它不只看复杂度

很多代码质量工具会从复杂度开始：圈复杂度、认知复杂度、嵌套层级。这些指标有价值，但单独看它们很容易误判。一个复杂函数如果测试覆盖很好、很少变动、边界清楚，未必是当前最该修的地方。相反，一个看起来不算太复杂的函数，如果频繁被修改、经常出现在 bug fix 里、测试覆盖缺口大，风险可能更高。

Debtmap 的 README 把它的信号拆得很清楚：复杂度、覆盖率、git 历史、耦合、纯度和熵。这里的价值在于组合判断，而不是把某一个指标绝对化。

例如：

  • 复杂度用于判断代码理解成本。
  • 覆盖率用于判断改动时的行为风险。
  • git 历史用于发现总是在变化、总是在修 bug 的区域。
  • 耦合用于判断变更会怎样在代码库里扩散。
  • 纯度用于估计副作用、I/O 和可测试性。
  • 熵用于减少“有意设计出来的复杂性”被误报的概率。

这些信号最后会合成一个优先级分数，并按 critical、high、medium、low 这样的严重程度分组。对维护者来说，这比“这里看着不太舒服”更容易进入行动。

支持 Rust、Python、JavaScript 和 TypeScript

Debtmap 当前支持四类语言：Rust、Python、JavaScript 和 TypeScript。Rust 部分使用 syn 做 AST 分析，并覆盖宏展开和 trait detection；Python、JavaScript、TypeScript 部分则使用 tree-sitter，分别处理函数、类、decorator、JSX、async workflow、TS/TSX 等模式。

这组语言选择很实际。它没有试图一开始覆盖所有语言，而是先聚焦在现代开发和 AI agent 修改频率都很高的栈上。尤其是 TypeScript 和 Python，很多团队已经在这些仓库里引入 coding agent；如果 agent 只是按 issue 改代码，很容易把已有的复杂区域继续堆高。

基本使用方式很直接：

cargo install debtmap
debtmap analyze .

如果只想分析特定语言，也可以传入语言列表：

debtmap analyze . --languages rust,python,javascript,typescript

TUI 适合人工探索，JSON 适合自动化

debtmap analyze . 默认可以进入交互式探索视图。README 里列到的 TUI 功能包括按严重程度浏览 debt items、查看分数拆解、查看 git history、依赖、函数级覆盖率，以及在需要时把上下文复制给 AI assistant。

这类 TUI 的意义在于，它让“优先修哪里”可以被讨论。一个条目为什么排在前面，不只是因为工具给了一个分数，而是因为 reviewer 能看到分数背后的组成：复杂度是否过高、覆盖率是否太低、调用关系是否牵动太多、历史上是否一直在变。

自动化场景则更适合 JSON：

debtmap analyze . --format json --top 10 --output debt.json

JSON 输出可以交给脚本、CI 或内部 dashboard。对于想做质量门禁的团队，这比只在本地跑一次更有用。比如每周对主干生成一份风险清单，或者在大型重构前后比较技术债评分是否真的下降。

Markdown 输出对 AI workflow 很有意思

Debtmap 明确把 AI workflow 放进了设计里。它提供 --format markdown，并强调这个格式可以给 AI coding assistant 使用。README 里写到，它会提供上下文建议、结构化 metadata、紧凑输出，以及确定性输出。

这点很关键。让 AI 修技术债时，最糟糕的指令通常是“帮我优化这个项目”。范围太大，目标太松，agent 很容易挑一些表面重构做完就结束。更好的方式是先用工具给出一个小而清楚的问题：哪个函数、为什么高风险、需要读哪些文件范围、分数由哪些信号组成。

示例命令也很直接：

debtmap analyze . --format markdown --top 1 | claude "Fix this technical debt"

我会把这种用法看成“给 agent 派工前的筛选器”。Debtmap 不负责证明修复正确，也不应该替代测试和 review。它更适合负责前一步：把值得处理的高风险区域找出来，并把上下文压缩成 agent 能读的材料。

Dashboard 给风险分布一个全局视角

除了终端输出，Debtmap 还提供在线 dashboard。使用方式是先生成带上下文和覆盖率信息的 JSON：

debtmap analyze . --format json -o debtmap.json --lcov coverage.lcov --context

然后在 dashboard 中加载这个文件。README 提到 dashboard 会提供 risk quadrant、top debt items、module flow 和 risk radar，并且处理发生在浏览器本地，数据不会离开用户浏览器。

这对团队沟通很有帮助。技术债如果只存在于命令行输出里，很容易停留在少数维护者手里；可视化之后，它更适合在重构计划、质量复盘和里程碑评审中使用。尤其是 risk quadrant，把复杂度和覆盖率缺口放在一起看，能避免团队只盯复杂度或只盯覆盖率。

CI/CD 里要谨慎设门槛

README 给了 GitHub Actions 示例，可以使用 iepathos/debtmap-action@v1，并设置类似 max-complexity-density 和 fail-on-violation 的阈值。

我会建议先观察，再设硬门槛。技术债分析和 lint 不一样，lint 规则通常比较明确，而技术债评分会受到项目结构、测试覆盖数据、历史提交习惯和语言解析质量影响。直接让 CI fail，可能会让团队把时间花在和工具阈值争执上。

更稳妥的路径是：

  • 先在主干定期生成报告。
  • 找几个团队认同的高风险案例校准。
  • 对新增高风险 debt 设提醒。
  • 最后再考虑对特定目录或特定指标设置阻断。

这样工具才更像决策辅助，而不是新的噪音源。

适合哪些场景

Debtmap 适合这些场景：

  • 代码库已经积累多年，大家都知道有技术债，但缺少排序。
  • 团队想把重构任务拆成更小、更可解释的条目。
  • AI coding assistant 已经参与修复、重构或测试补齐。
  • 需要把覆盖率、复杂度和 git 历史放在一起看。
  • 想用 JSON / Markdown 输出接入 CI、dashboard 或内部工具。

它不适合把所有代码质量判断都外包给一个分数。高分条目值得看，但是否要立刻改，还要结合业务风险、发布计划和模块所有权。尤其是遗留系统里，有些复杂代码是为了兼容旧协议或历史数据格式；这种情况下，工具只能提示风险，不能替你做取舍。

总结

iepathos/debtmap 的重点不是“发现代码不够优雅”，而是把技术债变成可排序、可解释、可交给自动化处理的风险清单。它把复杂度、覆盖率、git 历史、耦合和副作用这些信号放在一起，让维护者更容易回答一个具体问题：今天最值得先修哪里？

我喜欢它和 AI workflow 的结合方式。不是让 agent 自己决定从哪里开始改，而是先用分析工具找出高风险区域，再把范围、原因和上下文交给 agent。对开始认真使用 AI coding assistant 的团队来说，这种“先分析，再派工，再验证”的流程，比直接让 AI 大范围重构更可靠。

项目地址：https://github.com/iepathos/debtmap