代码质量与规范

项目目前建立了一套提交前代码检查流程来保障代码质量和统一团队风格，建议所有团队成员在开始开发前完成 pre-commit 的安装与配置

关于配置项，简单做下介绍：

1. Commit Message 检查

使用 commitlint-pre-commit-hook 保证所有提交信息遵循 Conventional Commits 规范。

推荐的提交类型包括：

• feat：新增功能
• fix：Bug 修复
• docs：文档更新
• style：代码格式调整
• refactor：代码重构
• test：测试相关变更
• chore：构建、依赖或工具相关变更

示例：

feat(frontend): 新增知识库拖拽排序功能
fix(backend): 修复 RAG 流水线增量向量化问题

2. 前端代码检查

通过 ESLint 9 对 前端 Vue 3 和客户端 React Native 代码进行静态分析，支持 JavaScript、TypeScript、Vue 以及 TSX 文件的分析，使用 Prettier 统一代码风格，检查时将自动尝试修复可自动处理的问题

https://eslint.org/

https://prettier.io/docs/

3. 后端代码检查

采用 Ruff 对后端代码进行检查和格式化

https://docs.astral.sh/ruff/

4. 其他通用检查

• 自动移除行尾空白字符
• 确保文件以换行符结尾
• 检查 YAML 文件语法有效性
• 限制单文件大小（最大 500KB），防止提交过大文件

---

提交前检查设置与使用

1. 安装 pre-commit 钩子

首次使用前，需要先创建环境，安装 pre-commit 工具并激活 Git 钩子：

# 安装 pre-commit（使用 pip）
pip install pre-commit

# 进入项目根目录并安装钩子
cd KnowledgeRAG-GZHU
pre-commit install
pre-commit install --hook-type commit-msg

安装完成后，每次执行 git commit 时，检查流程将自动运行。

2. 手动运行检查

可以随时手动触发完整检查：

# 检查项目中所有文件
pre-commit run --all-files

# 只检查当前已暂存的文件
pre-commit run

3. 提交代码

# 1. 添加修改文件
git add .

# 2. 提交（pre-commit 将自动执行检查）
git commit -m "feat(frontend): 新增知识库详情页功能"

# （不推荐）在特殊情况下，可使用以下命令跳过检查
git commit --no-verify -m "紧急修复..."

若检查未通过，查看日志并根据提示修复问题后，重新 git add 并提交

5. 检查配置更新

当 .pre-commit-config.yaml 文件发生变更时，执行：

pre-commit autoupdate
pre-commit clean
pre-commit install

6. 检查特定工具或文件

# 只运行 Ruff 检查
pre-commit run ruff --all-files

# 只检查某个具体文件
pre-commit run eslint --files xxxx.vue