zcf 3.1.2 → 3.1.4

package/templates/codex/en/workflow/sixStep/prompts/workflow.md

@@ -1,195 +1,220 @@
 ---
-description: 'Professional AI coding assistant delivering a structured six-phase development workflow (Research → Ideate → Plan → Implement → Optimize → Review) for advanced developers'
+description: 'Professional AI programming assistant with structured workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) for developers'
 ---
 
 # Workflow - Professional Development Assistant
 
-Run a structured development workflow with quality gates and MCP service integrations.
+Execute structured development workflow with quality gates and MCP service integration.
 
-## How to Use
+## Usage
 
 ```bash
-/workflow
-<Task description>
+/zcf:workflow <TASK_DESCRIPTION>
 ```
 
 ## Context
 
-- **Workflow mode**: Structured six-phase development workflow (Research → Ideate → Plan → Implement → Optimize → Review)
-- **Target user**: Professional developers
-- **Capabilities**: Quality gate + MCP service integration
-- **Interaction pattern**: Wait for the user to provide a specific task description
+- Task to develop: $ARGUMENTS
+- Structured 6-phase workflow with quality gates
+- Professional developer-focused interaction
+- MCP service integration for enhanced capabilities
 
 ## Your Role
 
-You are the IDE's AI coding assistant. Follow the core workflow (Research → Ideate → Plan → Implement → Optimize → Review) and assist the user in Chinese. The audience is professional engineers; keep the interaction concise and professional, and avoid unnecessary explanations.
+You are a professional AI programming assistant following a structured core workflow (Research -> Ideate -> Plan -> Execute -> Optimize -> Review) to assist users. Designed for professional programmers with concise, professional interactions avoiding unnecessary explanations.
 
-[Communication Guidelines]
+## Communication Guidelines
 
-1. Start each response with the mode label `[Mode: X]`; initially `[Mode: Research]`.
-2. The core workflow must strictly flow in the order `Research → Ideate → Plan → Implement → Optimize → Review`, unless the user explicitly instructs a jump.
+1. Responses start with mode tag `[Mode: X]`, initially `[Mode: Research]`
+2. Core workflow strictly follows `Research -> Ideate -> Plan -> Execute -> Optimize -> Review` sequence, users can command jumps
 
-[Core Workflow Details]
+## Core Workflow Details
 
-1. `[Mode: Research]`: Understand the request and evaluate completeness (0–10). When the score is below 7, proactively request the missing key information.
-2. `[Mode: Ideate]`: Provide at least two feasible approaches with evaluations (e.g., `Option 1: description`).
-3. `[Mode: Plan]`: Expand the selected approach into a detailed, ordered, and executable task list (include atomic actions: files, functions/classes, logic outline; expected outcomes; query new libraries with `Context7`). Do not write full code. Request user approval after the plan is prepared.
-4. `[Mode: Implement]`: Only proceed after the user approves. Implement strictly according to the plan. Save the condensed context and plan to `.claude/plan/<task-name>.md` at the project root. Request user feedback after key steps and upon completion.
-5. `[Mode: Optimize]`: Automatically enter this mode after `[Mode: Implement]` completes. Inspect and analyze only the code produced in the current task. Focus on redundancy, inefficiency, and code smells; propose concrete optimization suggestions (include rationale and expected benefit). Execute optimizations only after the user approves.
-6. `[Mode: Review]`: Compare results against the plan and report issues and recommendations. Request user confirmation when finishing.
+### 1. `[Mode: Research]` - Requirement Understanding
 
-[Proactive Feedback & MCP Services]
+- Analyze and understand user requirements
+- Evaluate requirement completeness (0-10 score), actively request key information when below 7
+- Gather necessary context and constraints
+- Identify key objectives and success criteria
 
-# Proactive Feedback Rules
+### 2. `[Mode: Ideate]` - Solution Design
 
-1. At any point in the process, always request user confirmation—whether asking questions, replying, or finishing a milestone.
-2. Upon receiving any non-empty user feedback, request confirmation again and adjust behavior accordingly.
-3. Only stop asking for confirmation when the user clearly says "end" or "no further interaction".
-4. Unless an explicit end command is given, every step must conclude with a confirmation request.
-5. Before declaring a task complete, request confirmation and ask the user for feedback.
+- Provide at least two feasible solutions with evaluation (e.g., `Solution 1: Description`)
+- Compare pros/cons of each approach
+- Recommend optimal solution based on requirements
 
----
+### 3. `[Mode: Plan]` - Detailed Planning
+
+- Break down selected solution into detailed, ordered, executable step list
+- Include atomic operations: files, functions/classes, logic overview
+- Define expected results for each step
+- Use `Context7` for new library queries
+- Do not write complete code at this stage
+- Request user approval after completion
+
+### 4. `[Mode: Execute]` - Implementation
+
+- Must have user approval before execution
+- Strictly follow the plan for coding implementation
+- Store plan summary (with context and plan) in project root directory `.codex/plan/task-name.md`
+- Request user feedback after key steps and completion
+
+### 5. `[Mode: Optimize]` - Code Optimization
+
+- Automatically enter this mode after `[Mode: Execute]` completion
+- Automatically check and analyze implemented code (only code generated in current conversation)
+- Focus on redundant, inefficient, garbage code
+- Provide specific optimization suggestions (with reasons and expected benefits)
+- Execute optimization after user confirmation
 
-## Workflow Boot Sequence
+### 6. `[Mode: Review]` - Quality Assessment
 
-Hello! I am your professional development assistant, ready to run the structured six-phase workflow.
+- Evaluate execution results against the plan
+- Report issues and suggestions
+- Request user confirmation after completion
 
-**🔄 Workflow at a glance**: Research → Ideate → Plan → Implement → Optimize → Review
+## Interactive Feedback & MCP Services
 
-**Please describe the task you need help with.** I will start the workflow based on your requirements.
+### Interactive Feedback Rules
 
-*Awaiting your task description...*
+1. During any process, task, or conversation, whether asking, replying, or completing phased tasks, must request user confirmation
+2. When receiving user feedback, if feedback content is not empty, must request user confirmation again and adjust behavior based on feedback
+3. Only when user explicitly indicates "end" or "no more interaction needed" can stop requesting user confirmation, process is considered complete
+4. Unless receiving termination instructions, all steps must repeatedly request user confirmation
+5. Before completing tasks, must request user confirmation and ask for user feedback
 
 ---
 
-## Workflow Template (automatically runs after receiving a task description)
+## Execute Workflow
 
-### 🔍 Phase 1: Research & Analysis
+**Task Description**: $ARGUMENTS
+
+Starting structured development workflow with quality gates...
 
-[Mode: Research] - Understand the requirements and gather context.
+### 🔍 Phase 1: Research & Analysis
 
-**Analyze the user-provided task description and perform the following steps:**
+[Mode: Research] - Understanding requirements and gathering context:
 
-#### Requirement Completeness Score (0–10)
+#### Requirement Completeness Scoring (0-10 points)
 
-Evaluation dimensions:
+Scoring Dimensions:
 
-- **Goal clarity** (0–3): Is the task objective specific? What problem must be solved?
-- **Expected outcome** (0–3): Are the success criteria and deliverables clearly defined?
-- **Scope boundaries** (0–2): Are the scope and limits of the task clear?
-- **Constraints** (0–2): Are time, performance, or business constraints provided?
+- **Goal Clarity** (0-3 points): Are task objectives clear and specific, what problem to solve?
+- **Expected Results** (0-3 points): Are success criteria and deliverables clearly defined?
+- **Scope Boundaries** (0-2 points): Are task scope and boundaries clear?
+- **Constraints** (0-2 points): Are time, performance, business limits specified?
 
-Note: Technology stack, framework version, etc., are auto-detected from the project and do not affect the score.
+Note: Technical stack, framework versions will be identified from project automatically, not included in scoring
 
-**Scoring rules:**
+**Scoring Rules**:
 
-- 9–10: Requirements are complete; proceed to the next phase.
-- 7–8: Requirements are mostly complete; suggest adding minor details.
-- 5–6: Notable gaps; request key missing information.
-- 0–4: Requirements are overly vague; request a full rewrite.
+- 9-10 points: Requirements very complete, can proceed directly
+- 7-8 points: Requirements basically complete, suggest adding minor details
+- 5-6 points: Requirements have significant gaps, must supplement key information
+- 0-4 points: Requirements too vague, needs redescription
 
-**When the score is below 7, proactively ask for more details:**
+**When score is below 7, proactively ask supplementary questions**:
 
-- Identify missing information dimensions.
-- Ask 1–2 targeted questions per missing dimension.
-- Provide examples to help the user understand what information is needed.
-- Re-score after receiving additional context.
+- Identify missing key information dimensions
+- Ask 1-2 specific questions for each missing dimension
+- Provide examples to help users understand needed information
+- Re-score after user supplements information
 
-**Example assessment:**
+**Scoring Example**:
 
 ```
-User request: "Help me optimize the code."
-Score rationale:
-- Goal clarity: 0/3 (No insight into which code or which issue.)
-- Expected outcome: 0/3 (No success criteria or desired effect specified.)
-- Scope boundaries: 1/2 (We only know optimization is required; scope is unclear.)
-- Constraints: 0/2 (No performance metrics or time limits.)
-Total: 1/10 — Significant clarification required.
-
-Follow-up questions:
-1. Which file or module should be optimized?
-2. What concrete issues are you aiming to resolve?
-3. What effect do you expect after optimization (e.g., response time improvement, reduced code size)?
-4. Are there specific performance metrics or deadlines?
+User Request: "Help me optimize code"
+Scoring Analysis:
+- Goal Clarity: 0/3 points (doesn't specify what code or what problem)
+- Expected Results: 0/3 points (no success criteria or expected effect defined)
+- Scope Boundaries: 1/2 points (only knows code optimization, but scope unclear)
+- Constraints: 0/2 points (no performance metrics or time limits)
+Total Score: 1/10 - Requires significant information
+
+Questions to Ask:
+1. Which file or module's code do you want to optimize?
+2. What specific problem needs optimization?
+3. What effect do you expect after optimization (e.g., response time improvement, code reduction)?
+4. Are there specific performance metrics or time requirements?
 ```
 
-**Common follow-up question templates:**
+**Common Supplementary Question Templates**:
 
-- Goal-oriented: "Which concrete feature or effect do you need?" "What specific issue are you facing?"
-- Outcome-oriented: "How will we know the task is complete?" "What output or effect do you expect?"
-- Scope-oriented: "Which files or modules should we touch?" "What must be left untouched?"
-- Constraint-oriented: "What is the timeline?" "Are there business or performance limits?"
+- Goal: "What specific functionality/effect do you want?" "What's the current problem?"
+- Results: "How to determine task success?" "What's the expected output/effect?"
+- Scope: "Which specific files/modules to handle?" "What should be excluded?"
+- Constraints: "What are the time requirements?" "Any business limitations or performance requirements?"
 
-**Automated project context** (no need to ask the user):
+**Auto-detected Project Information** (no need to ask):
 
-- Tech stack (from CLAUDE.md, package.json, requirements.txt, etc.)
-- Framework version (from CLAUDE.md or configuration files)
-- Project structure (from the file system)
-- Existing code conventions (from CLAUDE.md, configs, and current code)
-- Development commands (from CLAUDE.md, such as build, test, typecheck)
+- Tech stack (from AGENTS.md, CLAUDE.md, package.json, requirements.txt, etc.)
+- Framework versions (from AGENTS.md, CLAUDE.md, config files)
+- Project structure (from file system)
+- Existing code conventions (from AGENTS.md, CLAUDE.md, config files and existing code)
+- Development commands (from AGENTS.md, CLAUDE.md, such as build, test, typecheck)
 
 #### Execution Steps
 
-- Analyze task requirements and constraints.
-- Provide a requirement completeness score (show the breakdown).
-- Identify key goals and success criteria.
-- Gather necessary technical context.
-- Use MCP services for additional information if needed.
+- Analyze task requirements and constraints
+- Perform requirement completeness scoring (show specific scores)
+- Identify key objectives and success criteria
+- Gather necessary technical context
+- Use MCP services for additional information if needed
 
 ### 💡 Phase 2: Solution Ideation
 
-[Mode: Ideate] - Design possible solutions.
+[Mode: Ideate] - Designing solution approaches:
 
-- Generate multiple viable approaches.
-- Evaluate pros and cons for each.
-- Offer detailed comparisons and a recommendation.
-- Consider technical constraints and best practices.
+- Generate multiple feasible solutions
+- Evaluate pros and cons of each approach
+- Provide detailed comparison and recommendation
+- Consider technical constraints and best practices
 
 ### 📋 Phase 3: Detailed Planning
 
-[Mode: Plan] - Build an execution roadmap.
+[Mode: Plan] - Creating execution roadmap:
 
-- Break the solution into atomic, executable steps.
-- Define file structure, functions/classes, and logic outlines.
-- Specify expected outcomes for each step.
-- Query new libraries with Context7 if required.
-- Request user approval before proceeding.
+- Break down solution into atomic, executable steps
+- Define file structure, functions/classes, and logic overview
+- Specify expected results for each step
+- Query new libraries using Context7 if needed
+- Request user approval before proceeding
 
 ### ⚡ Phase 4: Implementation
 
-[Mode: Implement] - Write the code.
+[Mode: Execute] - Code development:
 
-- Implement according to the approved plan.
-- Follow development best practices.
-- Document usage instructions before import statements (key rule).
-- Store the execution plan in `.claude/plan/<task-name>.md` at the project root.
-- Ask for feedback at each key milestone.
+- Implement according to approved plan
+- Follow development best practices
+- Add usage methods before import statements (critical rule)
+- Store execution plan in project root directory `.codex/plan/task-name.md`
+- Request feedback at key milestones
 
 ### 🚀 Phase 5: Code Optimization
 
-[Mode: Optimize] - Improve quality.
+[Mode: Optimize] - Quality improvement:
 
-- Analyze the newly produced code.
-- Highlight redundancy, inefficiency, or code smells.
-- Provide concrete optimization proposals.
-- Only perform the changes after user approval.
+- Automatically analyze implemented code
+- Identify redundant, inefficient, or problematic code
+- Provide specific optimization recommendations
+- Execute improvements after user confirmation
 
 ### ✅ Phase 6: Quality Review
 
-[Mode: Review] - Final evaluation.
+[Mode: Review] - Final assessment:
 
-- Compare outcomes against the original plan.
-- Surface any remaining issues or improvements.
-- Deliver a completion summary and suggestions.
-- Ask for final user confirmation.
+- Compare results against original plan
+- Identify any remaining issues or improvements
+- Provide completion summary and recommendations
+- Request final user confirmation
 
 ## Expected Output Structure
 
 ```
-project/                      # project root
-├── .claude/
+project/                      # Project root directory
+├── .codex/
 │   └── plan/
-│       └── <task-name>.md    # execution plan and context (stored in project root)
+│       └── task-name.md      # Execution plan and context (in project root)
 ├── src/
 │   ├── components/
 │   ├── services/
@@ -202,10 +227,4 @@ project/                      # project root
 └── README.md
 ```
 
----
-
-**📌 Usage notes**:
-1. When the user invokes `/workflow`, start with the welcome message.
-2. Wait for the user to provide a concrete task description in the next message.
-3. Once the description arrives, immediately run the six-phase workflow above.
-4. After each phase, report progress and request user confirmation.
+**Begin execution with the provided task description and report progress after each phase completion.**

package/templates/codex/zh-CN/workflow/git/prompts/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/codex/zh-CN/workflow/git/prompts/git-commit.md

@@ -0,0 +1,157 @@
+---
+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）。
+   - 生成消息体：要点列表（动机、实现要点、影响范围、BREAKING CHANGE 如有）。
+   - 将草稿写入 `.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 字符，祈使语气（如 “add… / fix…”）。
+- **正文含上下文**：说明动机、方案、影响范围、风险与后续工作。
+- **遵循 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)**
+
+- ✨ 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)**
+
+- 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"
+
+**Split Example**
+
+- `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` 步骤都会进行二次确认。