Merge pull request #187 from ThreeFish-AI/vk/8389-pre-commit-hooks

feat(pre-commit): 配置 Pre-commit Hooks，实现本地 commit 前自动 lint/format 守护

Author: ThreeFish-AI

.github/workflows/release.yml

@@ -193,4 +193,3 @@ jobs:
         with:
           skip-existing: true
           verbose: true
-

.pre-commit-config.yaml

@@ -0,0 +1,57 @@
+# =============================================================================
+# coding-proxy: Pre-commit Hooks Configuration
+# =============================================================================
+# 目的: 在代码提交前自动执行 Ruff lint/format 及通用卫生检查，作为 CI 的前置守护
+#
+# 设计决策：使用 local hook（language: system + uv run）而非 astral-sh/ruff-pre-commit
+#   - 遵循 Single Source of Truth 原则：Ruff 版本由 uv.lock 唯一管控，消除版本漂移
+#   - 与 CI 命令形态完全镜像（uv run ruff check/format）
+#   - 符合 AGENTS.md 包管理规范（统一使用 uv）
+#
+# 安装：uv run pre-commit install
+# 手动全量检查：uv run pre-commit run --all-files
+# =============================================================================
+
+minimum_pre_commit_version: "4.0.0"
+
+repos:
+  # ---------------------------------------------------------------------------
+  # 通用代码卫生检查（pre-commit-hooks 官方钩子集）
+  # 轻量级、无额外依赖、执行极快
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace      # 去除行尾空白
+      - id: end-of-file-fixer        # 确保文件以换行符结尾
+      - id: check-yaml
+        args: ["--unsafe"]           # 兼容 GitHub Actions ${{ }} 表达式语法
+      - id: check-toml               # 校验 TOML 语法（pyproject.toml）
+      - id: check-merge-conflict     # 阻止提交含未解决 merge conflict 标记的文件
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]       # 阈值 1MB（assets/dashboard-v0.2.3.png 为 944KB）
+
+  # ---------------------------------------------------------------------------
+  # Ruff: local hook，直接调用 uv 安装的 Ruff（与 CI 版本完全一致）
+  # 前置条件：uv sync --dev 已执行
+  # ---------------------------------------------------------------------------
+  - repo: local
+    hooks:
+      # 对应 CI: uv run ruff check .
+      # --fix: 自动修复安全可修复问题（isort、UP 现代化等），降低开发摩擦
+      # --exit-non-zero-on-fix: 修复后返回非零码，触发 git 重新暂存已修复文件
+      - id: ruff-lint
+        name: Ruff (lint + auto-fix)
+        language: system
+        entry: uv run ruff check --fix --exit-non-zero-on-fix
+        types_or: [python, pyi]
+        require_serial: false
+
+      # 对应 CI: uv run ruff format --check .
+      # 本地直接 format（自动修复格式），CI 保留 --check 模式作为最终防线
+      - id: ruff-format
+        name: Ruff (format)
+        language: system
+        entry: uv run ruff format
+        types_or: [python, pyi]
+        require_serial: false

AGENTS.md

@@ -46,6 +46,7 @@
   2. **Temp Management**: 临时产物（执行计划等）一律收敛至 `.temp/` 并及时清理；
   3. **Link Validity**: 确保所有引用的 URL 可访问且具备明确的上下文价值；
   4. **Git Commit**: 在需要提交变更到 Git 时，一律使用 Shell 调用 Claude Code 的自定义 Slash Command: `/commit` 进行 git commit 操作（若环境中未安装 Claude Code，则直接读取 `~/.claude/commands/commit.md`，按照其中的规则进行 git commit 操作）。不要执行 Rebase。
+  5. **Pre-commit Hooks**: 克隆仓库后执行 `uv run pre-commit install` 激活本地 Git hooks，使 Ruff lint（含 auto-fix）、Ruff format 及通用代码卫生检查在每次 commit 前自动运行。若 hooks 自动修复了问题，提交会被中断，执行 `git add -p` 审阅修复内容后重新提交即可。
 - **Package Management Standardization (包管理规范)**:
   1. **Python**: 严禁使用 pip/poetry，**必须**统一使用 `uv` 进行包管理与脚本执行（如 `uv run`）；
   2. **JavaScript/TypeScript**: 严禁使用 npm/yarn，**必须**统一使用 `pnpm` 进行包管理与脚本执行。

CHANGELOG.md

@@ -71,9 +71,9 @@
 ## [v0.1.1](https://github.com/ThreeFish-AI/coding-proxy/releases/tag/v0.1.1) — 2026-04-05
 
 > [!IMPORTANT]
-> 
-> **🎉 coding-proxy MVP 惊艳登场！** 
-> 
+>
+> **🎉 coding-proxy MVP 惊艳登场！**
+>
 > 仅需配置一行环境变量，立刻为你的 Claude Code 接入“永不宕机”的多源智能引擎。主供应商打盹？毫秒级自动无缝切换备用通道，全天候护航你的编码心流，向打断大声说不！
 
 ### ✨ 核心亮点

README.md

@@ -118,7 +118,7 @@ graph RL
 
     subgraph CodingProxy["⚡ coding-proxy"]
         direction RL
-        
+
         Router["RequestRouter<br/><code>routing/router.py</code>"]:::router
 
         Router -->NTier
@@ -151,7 +151,7 @@ graph RL
             Tier2 -. "🆘 Safety Net Downgrade" .-> TierN
         end
 
-    end    
+    end
 
     Client -->|"POST /v1/messages"| CodingProxy
 ```

docs/zh-CN/README.md

@@ -118,7 +118,7 @@ graph RL
 
     subgraph CodingProxy["⚡ coding-proxy"]
         direction RL
-        
+
         Router["RequestRouter<br/><code>routing/router.py</code>"]:::router
 
         Router -->NTier
@@ -151,7 +151,7 @@ graph RL
             Tier2 -. "🆘 Safety Net Downgrade" .-> TierN
         end
 
-    end    
+    end
 
     Client -->|"POST /v1/messages"| CodingProxy
 ```

pyproject.toml

@@ -47,6 +47,7 @@ dev = [
     "pytest-asyncio>=1.3",
     "pytest-cov>=6.0",
     "ruff>=0.9.0",
+    "pre-commit>=4.0",
 ]
 
 # ── Ruff: Linter & Formatter（替代 flake8 + isort + Black + pyupgrade 等 6+ 工具） ──