docs(资源文件): 新增 Git 提交规范文档

- 添加 docs/GIT_GUIDELINES.md，规定提交格式、类型/范围定义及操作流程

docs/GIT_GUIDELINES.md

@@ -0,0 +1,127 @@
+# Git 提交规范指南
+
+
+## 一、核心原则（前置要求）
+### 1. 操作触发与执行约束
+- **触发条件**：必须在**人为明确指定本文档**，且确认目标远程仓库及分支后，方可执行 `git add`/`commit`/`push` 等涉及代码变更的操作。
+- **禁止场景**：
+  - 禁止在非人为交互场景下自动读取或执行本规范。
+  - 若未被人为指定阅读，AI 需立即停止继续读取本文档。
+- **重复确认机制**：
+  - 禁止在非人为确认情况下执行任何 `git add`/`commit`/`push` 操作。
+  - 每次完成 `git add`/`commit`/`push` 后，后续任何 Git 操作均需重新经过人为确认方可执行。
+  - 每次执行 `git add`/`commit`/`push` 前，必须**罗列出要提交的文件分类及对应的 commit 内容**，经确认后再执行。
+
+### 2. 提交信息要求
+- **清晰可追溯**：准确描述“做了什么”和“为什么做”，避免模糊表述（如“修改代码”“更新文件”）。
+- **粒度最小化**：单次提交仅包含一个完整功能/修复/文档更新，禁止混合多类无关变更（如同时开发功能+修复bug需拆分提交）。
+- **关联上下文**：涉及需求或Bug时，需在提交信息中关联编号（如 `Fixes: #123`，#123 为Bug编号）。
+- **禁止的commit内容**：
+  - 禁止提交包含敏感信息（如密码、密钥、个人隐私数据）的代码变更。
+  - 禁止提交包含二进制文件（如图片、音频、视频等）的变更。
+  - 禁止提交包含自动生成的代码（如编译输出、临时文件）的变更。
+  - 禁止commit内容过于笼统，比如“修改了一些代码”、“更新了文档”、“同步工作区改动”等。
+
+
+## 二、提交格式
+### 基础结构
+```bash
+<类型>(范围): <简短描述>
+[可选：详细说明]
+[可选：关联信息]
+```
+
+- **类型**：标识提交的功能类别（必填）。
+- **范围**：标识修改涉及的模块/文件类型（必填）。
+- **简短描述**：简洁概括变更内容（必填，中文，≤50字）。
+- **详细说明**：复杂变更可换行补充细节（可选,中文）。
+- **关联信息**：关联需求ID、Bug号等（可选，格式如 `Ref: #123` 或 `Fixes: #456`）。
+
+
+## 三、类型与范围定义
+### 1. 提交类型
+| 类型       | 标识       | 适用场景                                                                 |
+|------------|------------|--------------------------------------------------------------------------|
+| 新增功能   | `feat`     | 新增代码功能（接口、模块、逻辑）；新增配置项、资源文件（音频、图片等）。   |
+| 功能修复   | `fix`      | 修复代码bug、逻辑错误；修复配置错误、资源路径问题。                       |
+| 文档更新   | `docs`     | 修改注释、使用手册、API文档；补充README、配置说明。                       |
+| 代码优化   | `refactor` | 重构代码（不新增功能/修复bug，仅优化结构、命名、性能）。                 |
+| 样式调整   | `style`    | 代码格式调整（缩进、空格、注释格式）；不影响代码逻辑。                   |
+| 测试相关   | `test`     | 新增/修改测试用例、测试脚本。                                             |
+| 构建/配置  | `chore`    | 调整依赖、构建脚本、环境配置（如修改requirements.txt、Dockerfile）。     |
+
+### 2. 范围定义
+- `业务代码`：internal、controllers、services等（业务逻辑、数据处理、业务功能模块）。
+- `框架代码`：pkg、middlewares、constants_text等（核心框架、原生功能模块、公共工具类）。
+- `配置文件`：config、env、backup等（系统配置、环境变量）。
+- `资源文件`：docs、.trae、.env等（非代码文件，如音频、图片、字体等）。
+- `无范围`：全局变更（如根目录文档、全局配置）。
+
+
+## 四、操作规范（需人为确认后执行）
+### 1. 暂存（add）流程
+1. **文件分类**：按“类型+范围”对修改文件进行分类（如“feat(修改目标)”类文件、“fix(原始代码)”类文件）。
+2. **列出文件**：明确列出每类需暂存的文件路径（如：`main/修改目标/device.js`、`src/utils/tool.py`）。
+3. **执行暂存**：按分类执行 `git add <文件路径>`，禁止使用 `git add .` 批量暂存。
+4. **确认内容**：执行 `git diff --cached` 检查暂存内容，无误后等待人为确认。
+
+### 2. 提交（commit）流程
+1. **生成信息**：根据文件分类和修改内容，按规范格式生成commit中文信息（包含类型、范围、描述等）。
+2. **展示信息**：清晰展示完整的commit信息（使用中文描述，含详细说明和关联信息）。
+3. **执行提交**：经人为确认后，执行 `git commit -m "<commit信息>"`。
+4. **限制说明**：使用中文写commit信息
+
+### 3. 推送（push）流程
+1. **环境说明**：列出当前本地分支（如：`修改目标_ws`）及可用远程仓库（如：`mjgitlab`/`origin`）。
+2. **确认目标**：询问并确认推送的远程仓库及分支（如：`mjgitlab/修改目标_ws`）。
+3. **执行推送**：仅在人为确认后执行 `git push <远程仓库> <分支>`。
+4. **放弃推送**：若未确认目标或存在冲突风险，放弃推送并提示原因。
+
+
+## 五、示例
+### 1. 新增功能（带关联需求）
+- **文件分类**：`feat(修改目标)`  
+- **涉及文件**：`main/修改目标/wakeup.js`、`main/修改目标/config/wakeup.json`  
+- **Commit信息**：
+  ```bash
+  feat(修改目标): 新增设备语音唤醒功能
+  详细说明：
+  - 支持自定义唤醒词（最长8个字符）
+  - 新增唤醒成功回调接口
+  Ref: #102（关联需求ID）
+  ```
+
+### 2. 修复Bug（带问题描述）
+- **文件分类**：`fix(原始代码)`  
+- **涉及文件**：`src/device/heartbeat.py`  
+- **Commit信息**：
+  ```bash
+  fix(原始代码): 修复设备心跳包发送超时问题
+  问题：设备联网后30秒内未发送心跳，导致被误判为离线
+  修复：调整心跳包发送间隔为10秒
+  Fixes: #567（关联Bug ID）
+  ```
+
+### 3. 文档更新
+- **文件分类**：`docs(修改目标)`  
+- **涉及文件**：`docs/修改目标/tts_api.md`  
+- **Commit信息**：
+  ```bash
+  docs(修改目标): 补充TTS推送接口错误码说明
+  新增错误码400（参数无效）、500（服务异常）的处理建议
+  ```
+
+### 4. 代码优化
+- **文件分类**：`refactor(原始代码)`  
+- **涉及文件**：`src/device/connection.py`  
+- **Commit信息**：
+  ```bash
+  refactor(原始代码): 拆分设备连接逻辑为独立函数
+  提高代码复用性，便于后续维护
+  ```
+
+
+## 六、规范维护
+- 本规范存放于项目根目录 `GIT_COMMIT_GUIDELINES.md`，团队成员需共同遵守。
+- 可通过Git钩子（如`pre-commit`）自动校验提交信息格式，不符合时拦截提交。
+- 定期同步规范执行问题，根据实际场景补充新类型/范围（如新增`perf`标识性能优化）。