# clean4llm

**Repository Path**: l0km/clean4llm

## Basic Information

- **Project Name**: clean4llm
- **Description**: clean4llm(Clean for LLM)，项目代码添加到知识库的辅助工具
实现将指定本地文件夹(多数情况下是git代码仓库)递归复制所有源码文件到新文件夹，并排除指定文件二进制文件
- **Primary Language**: Unknown
- **License**: BSD-2-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-11
- **Last Updated**: 2025-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# clean4llm

## 应用场景

开发者尝试将Git代码仓库导入LLM知识库时，常常会遇到一个棘手的问题：仓库中混杂着大量二进制文件（如图片、视频、项目编译中间产物等），这些文件不仅对语言模型毫无价值，还会影响知识库的质量和检索效率。传统的手动过滤方式效率低下，而简单的复制粘贴更会导致"知识库污染"。

即使不考虑污染问题，过多的对LLM无用数据,也会导致向量化时间过乃至失败，比如一个提交纪录很多的Git仓库因为.git下的数据就很大。

clean4llm.sh ( Clean for LLM)专为解决**Git仓库导入知识库时的数据污染问题**而设计，典型场景：
1. 开发者需要将本地代码仓库导入LLM知识库时
2. CI/CD流程中自动准备训练数据集时
3. 构建纯净代码归档时

```mermaid
graph TD
A[原始仓库] --> B[静态规则过滤]
B --> C[动态.gitignore适配]
C --> D[二进制文件兜底检测]
D --> E[纯净代码库]
```

## 快速使用指南

### 基础命令
```bash
./clean4llm.sh 项目路径
```
默认在**当前目录**生成`项目名_src`目录存放过滤结果

### 自定义输出
```bash
./clean4llm.sh ~/my_project --output=~/clean_code
```
> **注：**
>
> 原项目文件不会被修改
>
> -v 参数可以在复制开始前显示被复制的言论的列表

## 技术特性

### 三重过滤机制
1. **静态规则过滤**：覆盖70+文件类型与15+目录模式 ，可自由扩展
2. **动态.gitignore适配**：智能识别项目自定义规则
3. **二进制检测兜底**：通过git check-ignore二次验证

### 安全防护设计
- 写操作仅作用于**新目录**，源文件保持只读
- 错误立即中断：`set -eo pipefail`保障
- 路径白名单校验：拒绝非法目录操作

### 增强显示


#### 实时进度条

复制过程实时显示进度条（支持终端列宽自适应，智能路径折叠显示）

```text
|#################......| 65% (132/203)
当前文件: src/.../utils.py
```
#### 统计报表

复制完成输出文件类型统计报表

```text
===== 统计信息 =====
类型              数量
*.py              142
*.md              23
Dockerfile        5
LICENSE           1
```

## 解决的核心问题

预防知识库污染，过滤**9大类无效数据**：

1. 编译产物（.class/.jar等）
2. 版本元数据（.git/）
3. 媒体文件（图片/音视频）
4. 办公文档（.doc/.xls）
5. 数据库文件（.db/.sqlite）
6. 模型文件（.pt/.onnx）
7. 日志文件（.log）
8. 压缩包（.zip/.rar）
9. 临时文件（~*）

## 使用注意事项
1. **路径规范**：
   
   ```bash
   # 处理含空格路径时必须加引号
   ./clean4llm.sh "目录 含空格"
   ```
2. **权限要求**：对输出目录有写权限
3. **特殊场景**：医学图像（.dcm等）自动过滤

## 自定义过滤规则
通过简单修改脚本，可灵活扩展排除模式：

### 文件扩展名过滤
```bash
# 在 FILE_EXCLUDE_RULES 数组添加新规则
FILE_EXCLUDE_RULES=(
    ...
    '*.msgpack'    # 新增二进制序列化格式
    '*.prototxt'   # 新增协议缓冲区文件
)
```

### 目录路径过滤
```bash
# 在 PATH_EXCLUDE_RULES 数组添加新规则
PATH_EXCLUDE_RULES=(
    ...
    'test-output/' # 新增测试报告目录 
    'temp_*/'      # 新增所有temp_前缀的临时目录
)
```

### 修改示例
假设需要新增排除：
- 地理信息系统的.shp文件
- 虚拟机镜像的.vmdk文件
- 临时文件夹tmp/

```diff
FILE_EXCLUDE_RULES=(
    ...
+   '*.shp'   # 地理信息系统矢量文件
+   '*.vmdk'  # 虚拟机磁盘镜像
)

PATH_EXCLUDE_RULES=(
    ...
+   'tmp/'    # 临时文件目录
)
```

### 生效方式
保存修改后直接运行脚本即可应用新规则：
```bash
# 修改后首次运行示例
./clean4llm.sh ~/project --output=clean_project
```

## Python版本优势
新增的Python版本实现相比原Bash版本具有显著性能提升：
- **Windows系统**：快10倍以上
- **Linux系统**：快约1倍
- 跨平台支持更好

### Python版本使用
```bash
# 基础使用
python clean4llm.py /path/to/project

# 自定义输出目录
python clean4llm.py ~/my_project --output ~/clean_code

# 显示过滤文件列表
python clean4llm.py ~/project -v
```

### 依赖说明
需额外安装以下Python库：
```bash
pip install tqdm wcwidth
```
- `tqdm`：用于显示进度条
- `wcwidth`：支持终端正确显示特殊字符

## 生成可执行文件

为了方便用户使用，clean4llm 提供了 `genexe.sh` 脚本，用于将 `clean4llm.py` 生成为 当前平台的可执行文件（Windows/Linux/MacOS）。

### 功能说明
1. **检查并安装 PyInstaller**：如果未安装，脚本会自动安装 PyInstaller用于生成可执行文件。
2. **清理生成环境**：删除 `build` 和 `dist` 文件夹，确保生成环境干净。
3. **生成可执行文件**：使用 PyInstaller 生成独立的可执行文件，并指定图标 `clean4llm.ico`。

### 使用说明

运行脚本：
   ```bash
$./genexe.sh
生成可执行文件成功 - dist/clean4llm.exe
   ```