Hello-Scan-Code - 高效代码扫描工具 (插件化架构版本)

🚀 核心特性

🔌 插件化架构

📄 JSON配置系统

📦 PyInstaller打包支持

🖥️ Click命令行界面

📦 安装方式

方式一:下载可执行文件(推荐)

方式二:从源码安装(开发者)

# 克隆项目
git clone https://github.com/taoweidong/Hello-Scan-Code.git
cd Hello-Scan-Code
# 安装依赖
pip install -r requirements.txt
# 或使用Makefile
make install

🚀 快速开始

使用可执行文件

Windows

# 解压下载的文件
unzip hello-scan-code-v1.0.0-windows.zip
cd hello-scan-code-v1.0.0-windows
# 创建配置文件
copy config.template.json config.json
# 编辑配置文件
notepad config.json
# 运行程序
hello-scan-code.exe --path /path/to/code

Linux

# 解压下载的文件
tar -xzf hello-scan-code-v1.0.0-linux.tar.gz
cd hello-scan-code-v1.0.0-linux
# 使用启动脚本(推荐)
./run-hello-scan-code.sh
# 或直接运行
./hello-scan-code/hello-scan-code --path /path/to/code

从源码运行

# 创建配置文件
cp config/config.template.json config.json
# 编辑配置文件
vim config.json
# 运行程序
python main.py --path /path/to/code
# 或使用Makefile
make run

📋 命令行选项

Usage: main.py [OPTIONS]
Options:
 -p, --path PATH 要扫描的代码仓库路径
 -c, --config PATH 配置文件路径 [default: config.json]
 -v, --verbose 启用详细日志输出
 --export-excel PATH 导出Excel报告文件路径
 --export-html PATH 导出HTML报告文件路径
 --export-db 导出结果到数据库
 --help Show this message and exit.

📋 插件化架构JSON配置系统

配置文件示例

{
 "_comment": "Hello-Scan-Code 配置文件模板 (插件化架构版本)",
 "_description": "复制此文件为 config.json 并修改相应配置项",
 "repo_path": ".",
 "search_term": "TODO,FIXME,BUG",
 "is_regex": false,
 "validate": true,
 "validate_workers": 4,
 
 "output": {
 "db_path": "db/results.db",
 "excel_path": "report/results.xlsx"
 },
 
 "logging": {
 "level": "INFO",
 "file_path": "logs/app.log",
 "rotation": "10 MB",
 "retention": "7 days"
 },
 
 "database": {
 "pool_size": 5,
 "max_overflow": 10,
 "pool_timeout": 30
 },
 
 "filters": {
 "ignore_dirs": [
 ".git", "__pycache__", "node_modules",
 "dist", "build", ".vscode", ".idea"
 ],
 "file_extensions": [".py", ".js", ".java"]
 },
 
 "plugins": {
 "enabled": ["keyword", "todo", "security", "regex"],
 "configs": {
 "keyword": {
 "keywords": ["TODO", "FIXME", "BUG", "HACK"]
 },
 "regex": {
 "patterns": {
 "email": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
 "phone": "\\b\\d{3}-\\d{3}-\\d{4}\\b"
 }
 }
 }
 }
}

🔧 开发者指南

构建可执行文件

# 使用Makefile构建
make build-linux # Linux平台
make build-windows # Windows平台
make all # 完整构建流程
# 或手动执行构建脚本
python scripts/build_linux.py
python scripts/build_windows.py

测试

# 运行所有测试
make test
# 运行单元测试
make test-unit
# 运行集成测试
make test-integration
# 检查代码覆盖率
make coverage

📊 插件化架构优势

📝 更新日志

v1.0.0 (插件化架构版本)

📁 项目结构

hello-scan-code/
├── config/ # 配置文件目录
│ ├── config.template.json # 配置模板文件
│ └── ... # 其他配置文件
├── scripts/ # 构建脚本
│ ├── build_linux.py # Linux平台构建脚本
│ └── build_windows.py # Windows平台构建脚本
├── src/
│ ├── __init__.py # Python包初始化文件
│ ├── main.py # 主程序入口
│ ├── engine/ # 扫描引擎模块
│ │ ├── __init__.py 
│ │ ├── scan_engine.py # 优化扫描引擎
│ │ └── grep_scanner.py # Grep预扫描器
│ ├── plugin/ # 插件系统核心
│ │ ├── __init__.py 
│ │ ├── base.py # 插件基础接口
│ │ ├── manager.py # 插件管理器
│ │ ├── registry.py # 插件注册表
│ │ └── discovery.py # 插件发现服务
│ ├── plugins/ # 插件实现
│ │ ├── __init__.py 
│ │ ├── builtin/ # 内置插件
│ │ │ ├── keyword_plugin.py # 关键字扫描插件
│ │ │ ├── todo_plugin.py # TODO检测插件
│ │ │ ├── security_plugin.py # 安全检测插件
│ │ │ └── regex_plugin.py # 正则表达式插件
│ │ └── custom/ # 自定义插件目录
│ ├── config/ # 配置管理模块
│ │ ├── __init__.py 
│ │ └── config_manager.py # 配置管理器
│ ├── database/ # 数据库模块
│ │ ├── __init__.py 
│ │ ├── session_manager.py # 数据库会话管理器
│ │ ├── models.py # 数据库模型
│ │ ├── repositories.py # 数据库仓储
│ │ └── compatibility.py # 兼容性适配器
│ ├── exporters/ # 导出器模块
│ │ ├── __init__.py 
│ │ ├── excel_exporter.py # Excel导出器
│ │ ├── html_exporter.py # HTML导出器
│ │ └── database_exporter.py # 数据库导出器
│ ├── utils/ # 工具函数模块
│ │ ├── __init__.py 
│ │ ├── file_utils.py # 文件工具函数
│ │ ├── text_utils.py # 文本工具函数
│ │ └── platform_utils.py # 平台工具函数
│ └── packaging/ # 打包模块
│ ├── __init__.py 
│ ├── pyinstaller_hooks.py # PyInstaller钩子
│ ├── resource_bundler.py # 资源打包器
│ └── hooks/ # PyInstaller自定义钩子
├── tests/ # 测试目录
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── ... # 其他测试文件
├── pyproject.toml # 项目配置和依赖
├── README.md # 使用说明
├── Makefile # 构建脚本
└── main.py # 根目录入口文件

🧩 插件系统详解

内置插件

开发自定义插件

from src.plugin.base import IScanPlugin, ScanResult, ScanContext
class MyCustomPlugin(IScanPlugin):
 @property
 def plugin_id(self) -> str:
 return "my_custom_plugin"
 
 @property
 def name(self) -> str:
 return "My Custom Plugin"
 
 # 实现其他必需的方法...

项目初始化

git clone https://github.com/taoweidong/Hello-Scan-Code.git
cd Hello-Scan-Code

# 使用 pip
pip install -r requirements.txt
# 或安装特定依赖
pip install loguru pandas openpyxl sqlalchemy alembic pyinstaller click

mkdir -p db report logs

本地运行

cp config/config.template.json config.json
vim config.json

# 基本扫描
python main.py --path /path/to/code
# 详细日志输出
python main.py --path /path/to/code --verbose
# 导出多种格式报告
python main.py --path /path/to/code --export-excel report.xlsx --export-html report.html --export-db

配置参数

技术特点