技术债检测器

技能文档

---
name: technical-debt-detector
description: Python 项目技术债检测与优先级排序。一次运行扫描五类技术债：延期工作标记（TODO/FIXME/HACK）、安全漏洞（硬编码密钥、不安全调用、bandit 集成）、测试缺口、可维护性问题（缺 docstring、缺类型标注、超长函数）与依赖健康（未固定版本、pip-audit 漏洞扫描），输出带文件行号、严重级别与修复思路的排序报告，支持 JSON 格式供工具集成。当用户要求「找技术债」「审计这个代码库」「该重构哪里」「找 TODO」「检查安全问题」「分析依赖」「哪里缺测试」时触发。触发词：技术债、代码审计、重构优先级、代码质量扫描、TODO 清理、依赖检查。
title: 技术债检测器
category: 开发工具
---

# 技术债检测器

用脚本高效定位大型 Python 项目中的技术债：所有检查都输出精确的文件位置，把 token 成本降到最低，并给出按严重级别排序、可直接执行的修复报告。

## 技能工作流

### 步骤1：运行全量分析

```bash
python3 scripts/analyze_all.py /path/to/project
```

一次运行五类检查：延期工作标记、安全、测试缺口、可维护性、依赖健康。输出按「高 → 中 → 低」排序的报告，每条含 `文件:行号`、问题描述与修复思路。

可选参数：

```bash
python3 scripts/analyze_all.py . --format json          # JSON 输出，供工具集成
python3 scripts/analyze_all.py . --only security testing  # 只跑指定检查
```

### 步骤2：逐项核对高优先级问题

按报告排序处理：

1. 打开报告中的 `文件:行号`
2. 参考该条目的修复思路落实修改
3. 详细修复模式见 `references/fix_patterns.md`

严重级别定义：

- **高 🔴**：立即修——安全漏洞、FIXME/BUG 标记、依赖已知漏洞
- **中 🟡**：尽快修——TODO、缺 docstring、未固定版本、缺测试的模块
- **低 🔵**：有空再修——缺类型标注、超长函数、NOTE 标记

### 步骤3：按需单类深查

聚焦某类问题时单独运行对应检查（同一脚本内通过 `--only` 完成，等价于原各独立分析器）：

| 检查项 | --only 取值 | 输出内容 |
|--------|-------------|----------|
| 延期工作 | `deferred_work` | TODO/FIXME/HACK/XXX 位置 + 内容 + 严重级别 |
| 安全 | `security` | 硬编码密钥、不安全调用；已装 bandit 时自动用它全面扫描 |
| 测试缺口 | `testing` | 没有对应测试文件的模块清单 |
| 可维护性 | `maintainability` | 缺 docstring、缺类型标注、超 50 行函数 |
| 依赖健康 | `dependencies` | 未固定版本；已装 pip-audit 时含已知漏洞 |

示例：

```bash
# 只看高风险延期标记
python3 scripts/analyze_all.py . --only deferred_work --format json | jq '.[] | select(.severity=="high")'

# 安全专项
python3 scripts/analyze_all.py . --only security
```

### 步骤4：JSON 集成

所有输出支持 `--format json`，可与 CI、看板或其他工具集成：

```bash
python3 scripts/analyze_all.py . --format json | jq '.[] | select(.severity == "high")'
```

### 步骤5：修复与复扫

- 按报告修复后**重跑分析**确认对应条目消失、未引入新高危项
- 修复模式速查见 `references/fix_patterns.md`
- 复杂度与代码坏味道（圈复杂度、重复、耦合、死代码）不在本技能范围，建议另行专项分析

## 依赖说明

必需：仅 Python 3 标准库即可运行全部基础检查。

可选增强（缺失时自动跳过，不报错）：

```bash
pip install bandit      # 安全检查升级为 bandit 全面扫描
pip install pip-audit   # 依赖检查附带已知漏洞扫描
pip install pytest-cov  # 配合手工确认覆盖率细节
```

使用说明

# 技术债检测器

扫描 Python 项目的五类技术债：延期工作标记（TODO/FIXME/HACK）、安全漏洞、测试缺口、可维护性问题、依赖健康，输出带文件行号、严重级别与修复思路的排序报告，支持 JSON 供 CI 集成。仅标准库即可运行，装了 bandit / pip-audit 自动增强。

## 最简用法

```bash
python3 scripts/analyze_all.py /path/to/project
```

```bash
python3 scripts/analyze_all.py . --only security --format json
```

## 特点

- 一次运行五类检查，按高/中/低排序直出修复清单
- 每条发现带精确文件行号与修复思路
- 标准库零依赖可跑，bandit/pip-audit 装了自动增强
- JSON 输出可接入 CI 与看板
- 附常见修复模式参考

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。