Git 规范
操作前检查
执行 git 命令前必须：
- 确认当前工作目录（
pwd） - Monorepo 项目应从根目录执行 git 操作
- 使用
-C参数指定路径，或在正确目录下执行
bash
# 推荐：从根目录执行
git -C <project-root> status
# 或先切换目录
cd <project-root> && git status提交规范
采用简化版 Conventional Commits 规范：
提交类型
| 类型 | 说明 | 示例 |
|---|---|---|
feat | 新功能 | feat: 添加文档导入功能 |
fix | Bug 修复 | fix: 修复文件上传失败问题 |
docs | 文档更新 | docs: 更新安装说明 |
refactor | 代码重构/优化 | refactor: 优化列表渲染性能 |
test | 测试相关 | test: 添加登录单元测试 |
config | 构建/配置/工具/依赖 | config: 升级依赖版本 |
style | 代码格式（不影响逻辑） | style: 格式化代码 |
说明：
config包含构建配置、CI 配置、依赖管理等；refactor包含代码重构、性能优化等。
提交格式
<type>(<scope>): <subject>
<body>
<footer>示例：
feat(doc): 添加 PDF 解析功能
- 支持 PDF 文本提取
- 支持 PDF 表格识别
- 添加解析进度显示
Closes #123提交要求
- 语言：中文或英文均可，保持一致
- 时态：使用祈使句（如 "添加" 而非 "添加了"）
- 长度：标题不超过 50 字符，正文每行不超过 72 字符
- 关联：如有相关 Issue，在 footer 中关联
- 简洁：简单提交使用单行标题即可，无需额外正文
AI 辅助提交规范
当使用 AI 辅助生成提交时：
- 简洁输出：简单变更使用单行标题，无需详细正文
- 中文优先：提交类型使用英文，如docs, feat等，其他内容使用中文
- 无签名：不添加
Co-Authored-By等水印信息 - 示例：
config: 初始化项目配置
分支策略
采用 Git Flow 变体：
main ───────●───────●───────●──────→ 稳定版本
↑ ↑
│ │
release/*───┘ │
│
develop ───●──●──●──●──●──●──→ 开发分支
↑ ↑
│ │
feature/*──┘ └── hotfix/*分支类型
| 分支 | 命名 | 说明 | 生命周期 |
|---|---|---|---|
main | main | 生产环境，稳定版本 | 永久 |
develop | develop | 开发集成分支 | 永久 |
feature | feature/* | 功能开发 | 临时 |
release | release/* | 发布准备 | 临时 |
hotfix | hotfix/* | 紧急修复 | 临时 |
分支命名
feature/功能名称 # 例：feature/pdf-parser
hotfix/问题描述 # 例：hotfix/login-error
release/版本号 # 例：release/v1.0.0合并规则
feature/*→develop：功能开发完成后develop→release/*：准备发布时release/*→main：发布完成hotfix/*→main+develop：紧急修复
合并策略
合并功能分支必须使用 --no-ff 参数，保留分叉历史线：
bash
git merge --no-ff feature/xxx禁止对功能分支使用 Fast-forward 合并。
例外：hotfix/* → develop 可以使用 Fast-forward。
工作流程
功能开发
bash
# 1. 从 develop 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/new-feature
# 2. 开发并提交
git add .
git commit -m "feat: 添加新功能"
# 3. 推送到远程
git push origin feature/new-feature
# 4. 创建 Pull Request 合并到 develop紧急修复
bash
# 1. 从 main 创建修复分支
git checkout main
git pull origin main
git checkout -b hotfix/critical-bug
# 2. 修复并提交
git add .
git commit -m "fix: 修复关键问题"
# 3. 合并到 main 和 develop
git checkout main
git merge hotfix/critical-bug
git checkout develop
git merge hotfix/critical-bug
# 4. 删除修复分支
git branch -d hotfix/critical-bug版本规范
采用语义化版本（Semantic Versioning）：
MAJOR.MINOR.PATCH
例：1.2.3- MAJOR：不兼容的 API 变更
- MINOR：向后兼容的功能新增
- PATCH：向后兼容的问题修复
版本标签
bash
# 创建标签
git tag -a v1.0.0 -m "发布 v1.0.0"
# 推送标签
git push origin v1.0.0忽略文件
多级 .gitignore 配置
本项目采用两级 .gitignore 配置：
| 文件位置 | 负责范围 | 说明 |
|---|---|---|
/.gitignore | 根目录及全局 | 通用忽略规则（对所有子目录生效） |
/desktop/.gitignore | desktop 子目录 | 前端 + Tauri 专属规则（覆盖/补充根目录规则） |
重要：.gitignore 中的路径是相对于该文件所在目录的。子目录的 .gitignore 只需包含该模块专属的规则，避免与根目录重复。
忽略文件验证
触发时机
以下场景必须验证 .gitignore 的合理性：
- 引入新组件/包：安装新的 npm 包、Rust crate 或其他依赖
- 项目初始化：创建新项目、工作区或子模块
- 提交前检查：每次
git commit前
验证规则
| 检查项 | 说明 | 操作 |
|---|---|---|
| 依赖目录 | node_modules/、target/ 等是否已忽略 | 必须忽略 |
| 构建产物 | dist/、build/、*.exe 等 | 必须忽略 |
| 敏感文件 | .env、密钥文件、配置文件中的密码 | 必须忽略 |
| IDE 配置 | .idea/、.vscode/（除非团队共享） | 通常忽略 |
| 锁文件 | Cargo.lock（应用项目）、pnpm-lock.yaml | 视情况而定 |
验证流程
新增组件/包 → 检查是否产生新的忽略需求
↓
是否确认忽略规则？
↙ ↘
是 否（不确定）
↓ ↓
更新 .gitignore 提醒用户确认
↓ ↓
继续操作 等待用户决策Human-in-Loop 机制
遇到以下情况时，必须暂停并请求用户确认：
- 不确定是否应忽略：文件类型不常见，或用途不明确
- 可能影响团队协作：如
.vscode/配置，可能包含共享设置 - 安全敏感：涉及密钥、凭证、私有配置等
确认方式：
⚠️ 检测到新文件类型 [文件路径]，建议：
- 忽略：[理由]
- 提交：[理由]
请确认处理方式？简洁性原则
始终确保仓库简洁：
- 不提交：依赖、构建产物、临时文件、敏感信息
- 可提交：源代码、配置模板（
.env.example）、文档、必要资源 - 定期清理：检查是否有不应提交的文件已进入仓库