@benbenwu/zcf 3.6.4

package/templates/common/workflow/git/en/git-rollback.md

@@ -0,0 +1,90 @@
+---
+description: Interactively rollback Git branch to historical version; lists branches, versions, then executes reset/revert after confirmation
+allowed-tools: Read(**), Exec(git fetch, git branch, git tag, git log, git reflog, git checkout, git reset, git revert, git switch), Write()
+argument-hint: [--branch <branch>] [--target <rev>] [--mode reset|revert] [--depth <n>] [--dry-run] [--yes]
+# examples:
+#   - /git-rollback                # Full interactive mode, dry-run
+#   - /git-rollback --branch dev   # Select dev directly, other interactive
+#   - /git-rollback --branch dev --target v1.2.0 --mode reset --yes
+---
+
+# Claude Command: Git Rollback
+
+**Purpose**: Safely and visually rollback a specified branch to an older version.
+Defaults to **read-only preview (`--dry-run`)**; actual execution requires `--yes` or interactive confirmation.
+
+---
+
+## Usage
+
+```bash
+# Pure interactive: list branches → select branch → list recent 20 versions → select target → choose reset or revert → confirm
+/git-rollback
+
+# Specify branch, other interactive
+/git-rollback --branch feature/calculator
+
+# Specify branch and target commit, execute with hard-reset in one go (dangerous)
+/git-rollback --branch main --target 1a2b3c4d --mode reset --yes
+
+# Generate revert commit only (non-destructive rollback), preview
+/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run
+```
+
+### Options
+
+| Option                 | Description                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `--branch <branch>`    | Branch to rollback; interactively selected if omitted.                                                             |
+| `--target <rev>`       | Target version (commit hash, tag, or reflog reference); interactively selects recent `--depth` entries if omitted. |
+| `--mode reset\|revert` | `reset`: Hard rollback history; `revert`: Generate reverse commits keeping history intact. Prompts by default.     |
+| `--depth <n>`          | List recent n versions in interactive mode (default 20).                                                           |
+| `--dry-run`            | **Enabled by default**, only preview commands to be executed.                                                      |
+| `--yes`                | Skip all confirmations and execute directly, suitable for CI/CD scripts.                                           |
+
+---
+
+## Interactive Flow
+
+1. **Sync remote** → `git fetch --all --prune`
+2. **List branches** → `git branch -a` (local + remote, filter protected branches)
+3. **Select branch** → User input or parameter
+4. **List versions** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`
+5. **Select target** → User inputs commit hash / tag
+6. **Select mode** → `reset` or `revert`
+7. **Final confirmation** (unless `--yes`)
+8. **Execute rollback**
+   - `reset`: `git switch <branch> && git reset --hard <target>`
+   - `revert`: `git switch <branch> && git revert --no-edit <target>..HEAD`
+9. **Push suggestion** → Prompt whether to `git push --force-with-lease` (reset) or regular `git push` (revert)
+
+---
+
+## Safety Guards
+
+- **Backup**: Automatically records current HEAD in reflog before execution, recoverable with `git switch -c backup/<timestamp>`.
+- **Protected branches**: If protected branches like `main` / `master` / `production` are detected with `reset` mode enabled, requires additional confirmation.
+- **--dry-run enabled by default**: Prevents accidental operations.
+- **--force prohibited**: No `--force` provided; if force push needed, manually enter `git push --force-with-lease`.
+
+---
+
+## Use Case Examples
+
+| Scenario                                                                    | Command Example                                                  |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Hotfix patch deployed with bug, need to rollback to tag `v1.2.0`            | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |
+| Ops colleague pushed debug logs by mistake, need to generate reverse commit | `/git-rollback --branch main --target 3f2e7c9 --mode revert`     |
+| Research historical bugs, guide newcomers through branch history            | `/git-rollback` (full interactive, dry-run)                      |
+
+---
+
+## Notes
+
+1. **reset vs revert**
+   - **reset** changes history, requires force push and may affect other collaborators, use with caution.
+   - **revert** is safer, generates new commits preserving history, but adds one more record.
+2. **Embedded repositories** often have large binary files; ensure LFS/submodule state consistency before rollback.
+3. If repository has CI forced validation, rollback may trigger pipelines automatically; confirm control policies to avoid accidental deployment of old versions.
+
+---

package/templates/common/workflow/git/en/git-worktree.md

@@ -0,0 +1,276 @@
+---
+description: Manage Git worktrees in project-level ../.zcf/project-name/ directory with smart defaults, IDE integration and content migration
+allowed-tools: Read(**), Exec(git worktree add, git worktree list, git worktree remove, git worktree prune, git branch, git checkout, git rev-parse, git stash, git cp, detect-ide, open-ide, which, command, basename, dirname)
+argument-hint: <add|list|remove|prune|migrate> [path] [-b <branch>] [-o|--open] [--track] [--guess-remote] [--detach] [--checkout] [--lock] [--migrate-from <source-path>] [--migrate-stash]
+# examples:
+#   - /git-worktree add feature-ui                     # create new branch 'feature-ui' from main/master
+#   - /git-worktree add feature-ui -o                  # create worktree and open directly in IDE
+#   - /git-worktree add hotfix -b fix/login -o         # create new branch 'fix/login' with path 'hotfix'
+#   - /git-worktree migrate feature-ui --from main     # migrate uncommitted content from main to feature-ui
+#   - /git-worktree migrate feature-ui --stash         # migrate current stash to feature-ui
+---
+
+# Claude Command: Git Worktree
+
+Manage Git worktrees with smart defaults, IDE integration and content migration in structured `../.zcf/project-name/` paths.
+
+Execute commands directly and provide concise results.
+
+---
+
+## Usage
+
+```bash
+# Basic operations
+/git-worktree add <path>                           # create new branch named <path> from main/master
+/git-worktree add <path> -b <branch>               # create new branch with specified name
+/git-worktree add <path> -o                        # create and open directly in IDE
+/git-worktree list                                 # show all worktree status
+/git-worktree remove <path>                        # remove specified worktree
+/git-worktree prune                                # clean invalid worktree references
+
+# Content migration
+/git-worktree migrate <target> --from <source>     # migrate uncommitted content
+/git-worktree migrate <target> --stash             # migrate stash content
+```
+
+### Options
+
+| Option             | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `add [<path>]`     | Add new worktree in `../.zcf/project-name/<path>`      |
+| `migrate <target>` | Migrate content to specified worktree                  |
+| `list`             | List all worktrees and their status                    |
+| `remove <path>`    | Remove worktree at specified path                      |
+| `prune`            | Clean invalid worktree references                      |
+| `-b <branch>`      | Create new branch and checkout to worktree             |
+| `-o, --open`       | Open directly in IDE after creation (skip prompt)      |
+| `--from <source>`  | Specify migration source path (migrate only)           |
+| `--stash`          | Migrate current stash content (migrate only)           |
+| `--track`          | Set new branch to track corresponding remote branch    |
+| `--guess-remote`   | Auto guess remote branch for tracking                  |
+| `--detach`         | Create detached HEAD worktree                          |
+| `--checkout`       | Checkout immediately after creation (default behavior) |
+| `--lock`           | Lock worktree after creation                           |
+
+---
+
+## What This Command Does
+
+1. **Environment Check**
+   - Verify Git repository using `git rev-parse --is-inside-work-tree`
+   - Detect whether in main repo or existing worktree for smart path calculation
+
+2. **Smart Path Management**
+   - Auto-calculate project name from main repository path using worktree detection
+   - Create worktrees in structured `../.zcf/project-name/<path>` directory
+   - Handle both main repo and worktree execution contexts correctly
+
+```bash
+# Core path calculation logic for worktree detection
+get_main_repo_path() {
+  local git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+  local current_toplevel=$(git rev-parse --show-toplevel 2>/dev/null)
+
+  # Check if in worktree
+  if [[ "$git_common_dir" != "$current_toplevel/.git" ]]; then
+    # In worktree, derive main repo path from git-common-dir
+    dirname "$git_common_dir"
+  else
+    # In main repository
+    echo "$current_toplevel"
+  fi
+}
+
+MAIN_REPO_PATH=$(get_main_repo_path)
+PROJECT_NAME=$(basename "$MAIN_REPO_PATH")
+WORKTREE_BASE="$MAIN_REPO_PATH/../.zcf/$PROJECT_NAME"
+
+# Always use absolute path to prevent nesting issues
+ABSOLUTE_WORKTREE_PATH="$WORKTREE_BASE/<path>"
+```
+
+**Critical Fix**: Always use absolute paths when creating worktrees from within existing worktrees to prevent path nesting issues like `../.zcf/project/.zcf/project/path`.
+
+3. **Worktree Operations**
+   - **add**: Create new worktree with smart branch/path defaults
+   - **list**: Display all worktrees with branches and status
+   - **remove**: Safely remove worktree and clean references
+   - **prune**: Clean orphaned worktree records
+
+4. **Smart Defaults**
+   - **Branch creation**: When no `-b` specified, create new branch using path name
+   - **Base branch**: New branches created from main/master branch
+   - **Path resolution**: Use branch name as path when unspecified
+   - **IDE integration**: Auto-detect and prompt for IDE opening
+
+5. **Content Migration**
+   - Migrate uncommitted changes between worktrees
+   - Apply stash content to target worktree
+   - Safety checks to prevent conflicts
+
+6. **Safety Features**
+   - **Path conflict prevention**: Check for existing directories before creation
+   - **Branch checkout validation**: Ensure branches aren't already in use
+   - **Absolute path enforcement**: Prevent nested `.zcf` directories when in worktree
+   - **Auto-cleanup on removal**: Clean both directory and git references
+   - **Clear status reporting**: Display worktree locations and branch status
+
+7. **Environment File Handling**
+   - **Auto-detection**: Scan `.gitignore` for environment variable file patterns
+   - **Smart copying**: Copy `.env` and `.env.*` files that are listed in `.gitignore`
+   - **Exclusion logic**: Skip `.env.example` and other template files
+   - **Permission preservation**: Maintain original file permissions and timestamps
+   - **User feedback**: Provide clear status on copied environment files
+
+```bash
+# Environment file copying implementation
+copy_environment_files() {
+    local main_repo="$MAIN_REPO_PATH"
+    local target_worktree="$ABSOLUTE_WORKTREE_PATH"
+    local gitignore_file="$main_repo/.gitignore"
+    
+    # Check if .gitignore exists
+    if [[ ! -f "$gitignore_file" ]]; then
+        return 0
+    fi
+    
+    local copied_count=0
+    
+    # Detect .env file
+    if [[ -f "$main_repo/.env" ]] && grep -q "^\.env$" "$gitignore_file"; then
+        cp "$main_repo/.env" "$target_worktree/.env"
+        echo "✅ Copied .env"
+        ((copied_count++))
+    fi
+    
+    # Detect .env.* pattern files (excluding .env.example)
+    for env_file in "$main_repo"/.env.*; do
+        if [[ -f "$env_file" ]] && [[ "$(basename "$env_file")" != ".env.example" ]]; then
+            local filename=$(basename "$env_file")
+            if grep -q "^\.env\.\*$" "$gitignore_file"; then
+                cp "$env_file" "$target_worktree/$filename"
+                echo "✅ Copied $filename"
+                ((copied_count++))
+            fi
+        fi
+    done
+    
+    if [[ $copied_count -gt 0 ]]; then
+        echo "📋 Copied $copied_count environment file(s) from .gitignore"
+    fi
+}
+```
+
+---
+
+## Enhanced Features
+
+### IDE Integration
+
+- **Auto-detection**: VS Code → Cursor → WebStorm → Sublime Text → Vim
+- **Smart prompting**: Ask to open in IDE after worktree creation
+- **Direct open**: Use `-o` flag to skip prompt and open immediately
+- **Custom configuration**: Configurable via git config
+
+### Content Migration System
+
+```bash
+# Migrate uncommitted changes
+/git-worktree migrate feature-ui --from main
+/git-worktree migrate hotfix --from ../other-worktree
+
+# Migrate stash content
+/git-worktree migrate feature-ui --stash
+```
+
+**Migration Flow**:
+
+1. Verify source has uncommitted content
+2. Ensure target worktree is clean
+3. Show changes to be migrated
+4. Execute safe migration using git commands
+5. Confirm results and suggest next steps
+
+---
+
+## Examples
+
+```bash
+# Basic usage
+/git-worktree add feature-ui                       # create new branch 'feature-ui' from main/master
+/git-worktree add feature-ui -b my-feature         # create new branch 'my-feature' with path 'feature-ui'
+/git-worktree add feature-ui -o                    # create and open in IDE directly
+
+# Content migration scenarios
+/git-worktree add feature-ui -b feature/new-ui     # create new feature worktree
+/git-worktree migrate feature-ui --from main       # migrate uncommitted changes
+/git-worktree migrate hotfix --stash               # migrate stash content
+
+# Management operations
+/git-worktree list                                 # view all worktrees
+/git-worktree remove feature-ui                    # remove unneeded worktree
+/git-worktree prune                                # clean invalid references
+```
+
+**Example Output**:
+
+```
+✅ Worktree created at ../.zcf/project-name/feature-ui
+✅ Copied .env
+✅ Copied .env.local
+📋 Copied 2 environment file(s) from .gitignore
+🖥️ Open ../.zcf/project-name/feature-ui in IDE? [y/n]: y
+🚀 Opening ../.zcf/project-name/feature-ui in VS Code...
+```
+
+---
+
+## Directory Structure
+
+```
+parent-directory/
+├── your-project/            # main project
+│   ├── .git/
+│   └── src/
+└── .zcf/                    # worktree management
+    └── your-project/        # project worktrees
+        ├── feature-ui/      # feature branch
+        ├── hotfix/          # hotfix branch
+        └── debug/           # debug worktree
+```
+
+---
+
+## Configuration
+
+### IDE Configuration
+
+- Supports VS Code, Cursor, WebStorm, Sublime Text, Vim
+- Configurable via git config for custom IDEs
+- Auto-detection with priority-based selection
+
+### Custom IDE Setup
+
+```bash
+# Configure custom IDE
+git config worktree.ide.custom.sublime "subl %s"
+git config worktree.ide.preferred "sublime"
+
+# Control auto-detection
+git config worktree.ide.autodetect true  # default
+```
+
+---
+
+## Notes
+
+- **Performance**: Worktrees share `.git` directory, saving disk space
+- **Safety**: Path conflict prevention and branch checkout validation
+- **Migration**: Only uncommitted changes; use `git cherry-pick` for commits
+- **IDE requirement**: Command-line tools must be in PATH
+- **Cross-platform**: Supports Windows, macOS, Linux
+- **Environment files**: Automatically copies environment files listed in `.gitignore` to new worktrees
+- **File exclusions**: Template files like `.env.example` are preserved in main repo only
+
+---

package/templates/common/workflow/git/zh-CN/git-cleanBranches.md

@@ -0,0 +1,102 @@
+---
+description: 安全查找并清理已合并或过期的 Git 分支，支持 dry-run 模式与自定义基准/保护分支
+allowed-tools: Read(**), Exec(git fetch, git config, git branch, git remote, git push, git for-each-ref, git log), Write()
+argument-hint: [--base <branch>] [--stale <days>] [--remote] [--force] [--dry-run] [--yes]
+# examples:
+#   - /git-cleanBranches --dry-run
+#   - /git-cleanBranches --base release/v2.1 --stale 90
+#   - /git-cleanBranches --remote --yes
+---
+
+# Claude Command: Clean Branches
+
+该命令**安全地**识别并清理**已合并**或**长期未更新 (stale)** 的 Git 分支。
+默认以**只读预览 (`--dry-run`)** 模式运行，需明确指令才会执行删除操作。
+
+---
+
+## Usage
+
+```bash
+# [最安全] 预览将要清理的分支，不执行任何删除
+/git-cleanBranches --dry-run
+
+# 清理已合并到 main 且超过 90 天未动的本地分支 (需逐一确认)
+/git-cleanBranches --stale 90
+
+# 清理已合并到 release/v2.1 的本地与远程分支 (自动确认)
+/git-cleanBranches --base release/v2.1 --remote --yes
+
+# [危险] 强制删除一个未合并的本地分支
+/git-cleanBranches --force outdated-feature
+```
+
+### Options
+
+- `--base <branch>`：指定清理的基准分支（默认为仓库的 `main`/`master`）。
+- `--stale <days>`：清理超过指定天数未提交的分支（默认不启用）。
+- `--remote`：同时清理远程已合并/过期的分支。
+- `--dry-run`：**默认行为**。仅列出将要删除的分支，不执行任何操作。
+- `--yes`：跳过逐一确认的步骤，直接删除所有已识别的分支（适合 CI/CD）。
+- `--force`：使用 `-D` 强制删除本地分支（即使未合并）。
+
+---
+
+## What This Command Does
+
+1. **配置与安全预检**
+   - **更新信息**：自动执行 `git fetch --all --prune`，确保分支状态最新。
+   - **读取保护分支**：从 Git 配置读取不应被清理的分支列表（见下文“Configuration”）。
+   - **确定基准**：使用 `--base` 参数或自动识别的 `main`/`master` 作为比较基准。
+
+2. **分析识别（Find）**
+   - **已合并分支**：找出已完全合并到 `--base` 的本地（及远程，如加 `--remote`）分支。
+   - **过期分支**：如指定 `--stale <days>`，找出最后一次提交在 N 天前的分支。
+   - **排除保护分支**：从待清理列表中移除所有已配置的保护分支。
+
+3. **报告预览（Report）**
+   - 清晰列出“将要删除的已合并分支”与“将要删除的过期分支”。
+   - 若无 `--yes` 参数，**命令到此结束**，等待用户确认后再次执行（不带 `--dry-run`）。
+
+4. **执行清理（Execute）**
+   - **仅在不带 `--dry-run` 且用户确认后**（或带 `--yes`）执行。
+   - 逐一删除已识别的分支，除非用户在交互式确认中选择跳过。
+   - 本地用 `git branch -d <branch>`；远程用 `git push origin --delete <branch>`。
+   - 若指定 `--force`，本地删除会改用 `git branch -D <branch>`。
+
+---
+
+## Configuration (一次配置，永久生效)
+
+为防止误删重要分支（如 `develop`, `release/*`），请在仓库的 Git 配置中添加保护规则。命令会自动读取。
+
+```bash
+# 保护 develop 分支
+git config --add branch.cleanup.protected develop
+
+# 保护所有 release/ 开头的分支 (通配符)
+git config --add branch.cleanup.protected 'release/*'
+
+# 查看所有已配置的保护分支
+git config --get-all branch.cleanup.protected
+```
+
+---
+
+## Best Practices for Embedded Devs
+
+- **优先 `--dry-run`**：养成先预览再执行的习惯。
+- **活用 `--base`**：维护长期 `release` 分支时，用它来清理已合并到该 release 的 `feature` 或 `hotfix` 分支。
+- **谨慎 `--force`**：除非你百分百确定某个未合并分支是无用功，否则不要强制删除。
+- **团队协作**：在清理共享的远程分支前，先在团队频道通知一声。
+- **定期运行**：每月或每季度运行一次，保持仓库清爽。
+
+---
+
+## Why This Version Is Better
+
+- ✅ **更安全**：默认只读预览，且有可配置的保护分支列表。
+- ✅ **更灵活**：支持自定义基准分支，完美适配 `release` / `develop` 工作流。
+- ✅ **更兼容**：避免了在不同系统上行为不一的 `date -d` 等命令。
+- ✅ **更直观**：将复杂的 16 步清单，浓缩成一个带安全选项的、可直接执行的命令。
+- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。

package/templates/common/workflow/git/zh-CN/git-commit.md

@@ -0,0 +1,205 @@
+---
+description: 仅用 Git 分析改动并自动生成 conventional commit 信息（可选 emoji）；必要时建议拆分提交，默认运行本地 Git 钩子（可 --no-verify 跳过）
+allowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG)
+argument-hint: [--no-verify] [--all] [--amend] [--signoff] [--emoji] [--scope <scope>] [--type <type>]
+# examples:
+#   - /git-commit                           # 分析当前改动，生成提交信息
+#   - /git-commit --all                     # 暂存所有改动并提交
+#   - /git-commit --no-verify               # 跳过 Git 钩子检查
+#   - /git-commit --emoji                   # 在提交信息中包含 emoji
+#   - /git-commit --scope ui --type feat    # 指定作用域和类型
+#   - /git-commit --amend --signoff         # 修补上次提交并签名
+---
+
+# Claude Command: Commit (Git-only)
+
+该命令在**不依赖任何包管理器/构建工具**的前提下，仅通过 **Git**：
+
+- 读取改动（staged/unstaged）
+- 判断是否需要**拆分为多次提交**
+- 为每个提交生成 **Conventional Commits** 风格的信息（可选 emoji）
+- 按需执行 `git add` 与 `git commit`（默认运行本地 Git 钩子；可 `--no-verify` 跳过）
+
+---
+
+## Usage
+
+```bash
+/git-commit
+/git-commit --no-verify
+/git-commit --emoji
+/git-commit --all --signoff
+/git-commit --amend
+/git-commit --scope ui --type feat --emoji
+```
+
+### Options
+
+- `--no-verify`：跳过本地 Git 钩子（`pre-commit`/`commit-msg` 等）。
+- `--all`：当暂存区为空时，自动 `git add -A` 将所有改动纳入本次提交。
+- `--amend`：在不创建新提交的情况下**修补**上一次提交（保持提交作者与时间，除非本地 Git 配置另有指定）。
+- `--signoff`：附加 `Signed-off-by` 行（遵循 DCO 流程时使用）。
+- `--emoji`：在提交信息中包含 emoji 前缀（省略则使用纯文本）。
+- `--scope <scope>`：指定提交作用域（如 `ui`、`docs`、`api`），写入消息头部。
+- `--type <type>`：强制提交类型（如 `feat`、`fix`、`docs` 等），覆盖自动判断。
+
+> 注：如框架不支持交互式确认，可在 front-matter 中开启 `confirm: true` 以避免误操作。
+
+---
+
+## What This Command Does
+
+1. **仓库/分支校验**
+   - 通过 `git rev-parse --is-inside-work-tree` 判断是否位于 Git 仓库。
+   - 读取当前分支/HEAD 状态；如处于 rebase/merge 冲突状态，先提示处理冲突后再继续。
+
+2. **改动检测**
+   - 用 `git status --porcelain` 与 `git diff` 获取已暂存与未暂存的改动。
+   - 若已暂存文件为 0：
+     - 若传入 `--all` → 执行 `git add -A`。
+     - 否则提示你选择：继续仅分析未暂存改动并给出**建议**，或取消命令后手动分组暂存。
+
+3. **拆分建议（Split Heuristics）**
+   - 按**关注点**、**文件模式**、**改动类型**聚类（示例：源代码 vs 文档、测试；不同目录/包；新增 vs 删除）。
+   - 若检测到**多组独立变更**或 diff 规模过大（如 > 300 行 / 跨多个顶级目录），建议拆分提交，并给出每一组的 pathspec（便于后续执行 `git add <paths>`）。
+
+4. **提交信息生成（Conventional 规范，可选 Emoji）**
+   - 自动推断 `type`（`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert` …）与可选 `scope`。
+   - 生成消息头：`[<emoji>] <type>(<scope>)?: <subject>`（首行 ≤ 72 字符，祈使语气，仅在使用 `--emoji` 时包含 emoji）。
+   - 生成消息体：
+     - 必须在 subject 之后空一行。
+     - 使用列表格式，每项以 `-` 开头。
+     - 每项**必须使用动词开头的祈使句**（如 "add…"、"fix…"、"update…"）。
+     - **禁止使用冒号分隔的格式**（如 ~~"Feature: description"~~、~~"Impl: content"~~）。
+     - 说明变更的动机、实现要点或影响范围（3 项以内为宜）。
+   - 生成消息脚注（如有）：
+     - 必须在 Body 之后空一行。
+     - **BREAKING CHANGE**：若存在破坏性变更，必须包含 `BREAKING CHANGE: <description>`，或在类型后添加感叹号（如 `feat!:`）。
+     - 其它脚注采用 git trailer 格式（如 `Closes #123`、`Refs: #456`、`Reviewed-by: Name`）。
+   - 根据 Git 历史提交的主要语言选择提交信息语言。优先检查最近提交主题（例如 `git log -n 50 --pretty=%s`）判断中文/英文；若无法判断，则回退到仓库主要语言或英文。
+   - 将草稿写入 `.git/COMMIT_EDITMSG`，并用于 `git commit`。
+
+5. **执行提交**
+   - 单提交场景：`git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`
+   - 多提交场景（如接受拆分建议）：按分组给出 `git add <paths> && git commit ...` 的明确指令；若允许执行则逐一完成。
+
+6. **安全回滚**
+   - 如误暂存，可用 `git restore --staged <paths>` 撤回暂存（命令会给出指令，不修改文件内容）。
+
+---
+
+## Best Practices for Commits
+
+- **Atomic commits**：一次提交只做一件事，便于回溯与审阅。
+- **先分组再提交**：按目录/模块/功能点拆分。
+- **清晰主题**：首行 ≤ 72 字符，祈使语气。
+- **正文含上下文**：说明动机、方案、影响范围（禁止冒号分隔格式）。
+- **遵循 Conventional Commits**：`<type>(<scope>): <subject>`。
+
+---
+
+## Type 与 Emoji 映射（使用 --emoji 时）
+
+- ✨ `feat`：新增功能
+- 🐛 `fix`：缺陷修复（含 🔥 删除代码/文件、🚑️ 紧急修复、👽️ 适配外部 API 变更、🔒️ 安全修复、🚨 解决告警、💚 修复 CI）
+- 📝 `docs`：文档与注释
+- 🎨 `style`：风格/格式（不改语义）
+- ♻️ `refactor`：重构（不新增功能、不修缺陷）
+- ⚡️ `perf`：性能优化
+- ✅ `test`：新增/修复测试、快照
+- 🔧 `chore`：构建/工具/杂务（合并分支、更新配置、发布标记、依赖 pin、.gitignore 等）
+- 👷 `ci`：CI/CD 配置与脚本
+- ⏪️ `revert`：回滚提交
+- 💥 `feat`：破坏性变更（`BREAKING CHANGE:` 段落中说明）
+
+> 若传入 `--type`/`--scope`，将**覆盖**自动推断。
+> 仅在指定 `--emoji` 标志时才会包含 emoji。
+
+---
+
+## Guidelines for Splitting Commits
+
+1. **不同关注点**：互不相关的功能/模块改动应拆分。
+2. **不同类型**：不要将 `feat`、`fix`、`refactor` 混在同一提交。
+3. **文件模式**：源代码 vs 文档/测试/配置分组提交。
+4. **规模阈值**：超大 diff（示例：>300 行或跨多个顶级目录）建议拆分。
+5. **可回滚性**：确保每个提交可独立回退。
+
+---
+
+## Examples
+
+**Good (使用 --emoji)**
+
+```text
+- ✨ feat(ui): add user authentication flow
+- 🐛 fix(api): handle token refresh race condition
+- 📝 docs: update API usage examples
+- ♻️ refactor(core): extract retry logic into helper
+- ✅ test: add unit tests for rate limiter
+- 🔧 chore: update git hooks and repository settings
+- ⏪️ revert: revert "feat(core): introduce streaming API"
+```
+
+**Good (不使用 --emoji)**
+
+```text
+- feat(ui): add user authentication flow
+- fix(api): handle token refresh race condition
+- docs: update API usage examples
+- refactor(core): extract retry logic into helper
+- test: add unit tests for rate limiter
+- chore: update git hooks and repository settings
+- revert: revert "feat(core): introduce streaming API"
+```
+
+**Good (包含 Body)**
+
+```text
+feat(auth): add OAuth2 login flow
+
+- implement Google and GitHub third-party login
+- add user authorization callback handling
+- improve login state persistence logic
+
+Closes #42
+```
+
+```text
+fix(ui): fix button spacing on mobile devices
+
+- adjust button padding to fit small screens
+- fix styling issues on iOS Safari
+- optimize touch target size
+```
+
+**Good (包含 BREAKING CHANGE)**
+
+```text
+feat(api)!: redesign authentication API
+
+- migrate from session-based to JWT authentication
+- update all endpoint signatures
+- remove deprecated login methods
+
+BREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration
+```
+
+**Split Example**
+
+```text
+- `feat(types): add new type defs for payment method`
+- `docs: update API docs for new types`
+- `test: add unit tests for payment types`
+- `fix: address linter warnings in new files` ←（如你的仓库有钩子报错）
+```
+
+---
+
+## Important Notes
+
+- **仅使用 Git**：不调用任何包管理器/构建命令（无 `pnpm`/`npm`/`yarn` 等）。
+- **尊重钩子**：默认执行本地 Git 钩子；使用 `--no-verify` 可跳过。
+- **不改源码内容**：命令只读写 `.git/COMMIT_EDITMSG` 与暂存区；不会直接编辑工作区文件。
+- **安全提示**：在 rebase/merge 冲突、detached HEAD 等状态下会先提示处理/确认再继续。
+- **可审可控**：如开启 `confirm: true`，每个实际 `git add`/`git commit` 步骤都会进行二次确认。