aico-cli 0.0.1

package/templates/zh-CN/memory/technical-guides.md

@@ -0,0 +1,126 @@
+# 技术执行指南
+
+本文档提供 Claude Code 执行技术任务时的最佳实践。
+
+## 危险操作确认机制
+
+**重要**：以下操作需要明确的用户确认后才能执行：
+
+### 需确认的操作类型
+
+- **文件系统**：删除文件/目录、批量修改、移动系统文件
+- **代码提交**：`git commit`、`git push`、`git reset --hard`
+- **系统配置**：修改环境变量、系统设置、权限变更
+- **数据操作**：数据库删除、结构变更、批量更新
+- **网络请求**：发送敏感数据、调用生产环境 API
+- **包管理**：全局安装/卸载、更新核心依赖
+
+### 确认方式
+
+执行危险操作前，必须：
+
+1. 明确说明即将执行的操作及其影响
+2. 等待用户明确确认（如"是"、"确认"、"继续"）
+3. 用户未确认或表示犹豫时，提供更多信息或替代方案
+
+## 命令执行最佳实践
+
+### 路径处理规范
+
+**重要**：执行命令时**始终使用双引号包裹文件路径**。
+
+```bash
+# ✅ 正确
+cd "C:\Users\name\My Documents"
+node "/path/with spaces/app.js"
+
+# ❌ 错误
+cd C:\Users\name\My Documents
+```
+
+### 跨平台兼容性
+
+- 优先使用正斜杠 `/` 作为路径分隔符
+- 使用反斜杠时确保路径被双引号包裹
+
+## 搜索工具使用
+
+### 内容搜索
+
+**始终优先使用 `rg` (ripgrep)**，速度更快且不会超时。
+
+```bash
+# ✅ 优先使用
+rg "pattern" .
+rg -t js "console.log" .
+
+# ⚠️ 备选方案
+grep -r "pattern" .
+```
+
+> 提示：如 `rg` 不可用，提醒用户安装：`brew/scoop/apt install ripgrep`
+
+### 文件查找
+
+- 使用 Glob 工具进行模式匹配
+- 使用 LS 工具列出目录
+- 避免使用 `find` 命令
+
+## 工具使用原则
+
+1. **优先专用工具**：使用 Read、Write、Edit 而非 cat、echo
+2. **批量操作**：同时调用多个工具以提高效率
+3. **错误处理**：命令失败时先检查路径引号问题
+
+## 性能优化
+
+- 大型项目使用 Task 工具进行复杂搜索
+- 搜索前了解项目结构，缩小范围
+- 合理使用文件类型过滤提高效率
+
+## 文档更新检查
+
+任务完成后自动检查文档更新需求：
+
+### 判断标准
+
+- **新功能**：需更新 README、CHANGELOG、使用文档
+- **API 变更**：需更新 API 文档、类型定义、接口说明
+- **配置变更**：需更新配置说明、CLAUDE.md、环境变量文档
+- **Bug 修复**：通常无需更新文档（除非影响使用方式）
+
+### 执行流程
+
+1. 分析代码变更类型和影响范围
+2. 自动识别项目中的文档文件
+3. 列出需更新的文档清单
+4. 向用户确认：`检测到以下文档可能需要更新：[文档列表]，是否需要我帮您更新？`
+5. 获得确认后逐一更新相关文档
+
+### 常见文档类型
+
+- **README.md**：功能说明、使用方法、配置说明
+- **CHANGELOG.md**：版本更新记录
+- **CLAUDE.md**：AI 助手配置和指令
+- **API 文档**：接口定义、参数说明
+- **配置文档**：环境变量、配置项说明
+
+## AI 助手行为准则
+
+以下准则定义了 AI 助手在执行任务时应遵循的核心行为规范：
+
+### 1. 持续解决问题直至完成
+
+记住，你是一个 AI 助手 - 请持续工作直到用户的问题完全解决，再结束你的回合并交还给用户。只有在确信问题已解决时才终止你的回合。
+
+### 2. 基于事实而非猜测
+
+如果你对用户请求相关的信息不确定，使用你的工具读取文件并收集相关信息：不要猜测或编造答案。
+
+### 3. 充分规划与反思
+
+你必须在每次函数调用前进行充分的规划，并对之前函数调用的结果进行充分的反思，确保用户的问题完全解决。不要仅通过函数调用来完成整个过程，因为这可能会损害你解决问题和深入思考的能力。此外，确保函数调用具有正确的参数。
+
+### 4. 先读后写原则
+
+在更新或修改文件前，先使用 Read 工具读取文件内容。

package/templates/zh-CN/workflow/bmad/commands/bmad-init.md

@@ -0,0 +1,109 @@
+# /bmad-init 命令
+
+此命令在您的项目中初始化 BMad-Method。
+
+## 当调用此命令时：
+
+1. 检查 `.bmad-core/install-manifest.yaml` 文件是否存在，判断 BMad 是否已安装
+2. 如果已安装，检查 manifest 中的版本号与最新版本对比
+3. 如果未安装或版本过旧，执行：`npx bmad-method@latest install -f -d . -i claude-code`
+4. 显示成功消息并提示用户重启 Claude Code
+
+## 实现
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+async function initBmad() {
+  // 检查是否已安装并获取版本
+  const manifestPath = path.join(process.cwd(), '.bmad-core', 'install-manifest.yaml');
+  let needsInstall = true;
+  let currentVersion = null;
+  
+  if (fs.existsSync(manifestPath)) {
+    try {
+      // 简单版本检查 - 只检查文件是否存在
+      // 完整的 YAML 解析需要 js-yaml 包
+      const manifestContent = fs.readFileSync(manifestPath, 'utf8');
+      const versionMatch = manifestContent.match(/version:\s*(.+)/);
+      if (versionMatch) {
+        currentVersion = versionMatch[1].trim();
+      }
+      
+      // 从 npm 获取最新版本
+      const latestVersion = execSync('npm view bmad-method version', { encoding: 'utf8' }).trim();
+      
+      if (currentVersion === latestVersion) {
+        console.log(`✅ BMad-Method已是最新版本 (v${currentVersion})`);
+        console.log('您可以使用 BMad 命令开始工作流');
+        needsInstall = false;
+      } else {
+        console.log(`🔄 BMad-Method有更新可用：v${currentVersion} → v${latestVersion}`);
+      }
+    } catch (error) {
+      console.log('⚠️  无法验证 BMad 版本，将重新安装');
+    }
+  }
+  
+  if (needsInstall === false) {
+    return;
+  }
+  
+  // 安装 BMad
+  console.log('🚀 正在安装 BMad-Method...');
+  try {
+    execSync('echo -e "1\\n" | npx bmad-method@latest install -f -d . -i claude-code', {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      shell: true
+    });
+    
+    console.log('✅ BMad-Method已成功安装！');
+    console.log('');
+    console.log('═══════════════════════════════════════════════════════════════');
+    console.log('📌 重要提示：请重启 Claude Code 以加载 BMad 扩展');
+    console.log('═══════════════════════════════════════════════════════════════');
+    console.log('');
+    console.log('📂 安装详情：');
+    console.log('   • 所有代理和任务命令都已安装在：');
+    console.log('     .claude/commands/BMad/ 目录中');
+    console.log('');
+    console.log('🔧 Git 配置建议（可选）：');
+    console.log('   如果您不希望将 BMad 工作流文件提交到 Git，请将以下内容添加到 .gitignore：');
+    console.log('     • .bmad-core');
+    console.log('     • .claude/commands/BMad');
+    console.log('     • docs/');
+    console.log('');
+    console.log('🚀 快速开始：');
+    console.log('   1. 重启 Claude Code');
+    console.log('   2. 首次使用推荐运行：');
+    console.log('      /BMad:agents:bmad-orchestrator *help');
+    console.log('      这将启动 BMad 工作流引导系统');
+    console.log('');
+    console.log('💡 提示：BMad Orchestrator 将帮助您选择合适的工作流程，');
+    console.log('       并引导您完成整个开发过程。');
+  } catch (error) {
+    console.error('❌ 安装失败：', error.message);
+    console.log('请手动运行：npx bmad-method@latest install -f -d . -i claude-code');
+  }
+}
+
+// 执行初始化
+initBmad();
+```
+
+## 用法
+
+只需在 Claude Code 中键入：
+
+```
+/bmad-init
+```
+
+此命令将：
+
+1. 在您的项目中安装 BMad-Method 框架
+2. 设置所有必要的配置
+3. 提供如何开始使用 BMad 工作流的指导

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

@@ -0,0 +1,101 @@
+---
+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/zh-CN/workflow/git/commands/git-commit.md

@@ -0,0 +1,152 @@
+---
+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` 步骤都会进行二次确认。

package/templates/zh-CN/workflow/git/commands/git-rollback.md

@@ -0,0 +1,90 @@
+---
+description: 交互式回滚 Git 分支到历史版本；列分支、列版本、二次确认后执行 reset / revert
+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                # 全交互模式，dry‑run
+#   - /git-rollback --branch dev   # 直接选 dev，其他交互
+#   - /git-rollback --branch dev --target v1.2.0 --mode reset --yes
+---
+
+# Claude Command: Git Rollback
+
+**目的**：安全、可视地将指定分支回滚到旧版本。  
+默认处于 **只读预览 (`--dry-run`)**；真正执行需加 `--yes` 或在交互中确认。
+
+---
+
+## Usage
+
+```bash
+# 纯交互：列出分支 → 选分支 → 列最近 20 个版本 → 选目标 → 选择 reset 或 revert → 二次确认
+/git-rollback
+
+# 指定分支，其他交互
+/git-rollback --branch feature/calculator
+
+# 指定分支与目标 commit，并用 hard‑reset 一键执行（危险）
+/git-rollback --branch main --target 1a2b3c4d --mode reset --yes
+
+# 只想生成 revert 提交（非破坏式回滚），预览即可
+/git-rollback --branch release/v2.1 --target v2.0.5 --mode revert --dry-run
+```
+
+### Options
+
+| 选项                   | 说明                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------- |
+| `--branch <branch>`    | 要回滚的分支；缺省时交互选择。                                                     |
+| `--target <rev>`       | 目标版本（commit Hash、Tag、reflog 引用都行）；缺省时交互选择近 `--depth` 条记录。 |
+| `--mode reset\|revert` | `reset`：硬回滚历史；`revert`：生成反向提交保持历史完整。默认询问。                |
+| `--depth <n>`          | 在交互模式下列出最近 n 个版本（默认 20）。                                         |
+| `--dry-run`            | **默认开启**，只预览即将执行的命令。                                               |
+| `--yes`                | 跳过所有确认直接执行，适合 CI/CD 脚本。                                            |
+
+---
+
+## 交互流程
+
+1. **同步远端** → `git fetch --all --prune`
+2. **列分支** → `git branch -a`（本地＋远端，过滤受保护分支）
+3. **选分支** → 用户输入或传参
+4. **列版本** → `git log --oneline -n <depth>` + `git tag --merged` + `git reflog -n <depth>`
+5. **选目标** → 用户输入 commit hash / tag
+6. **选模式** → `reset` 或 `revert`
+7. **最终确认** （除非 `--yes`）
+8. **执行回滚**
+   - `reset`：`git switch <branch> && git reset --hard <target>`
+   - `revert`：`git switch <branch> && git revert --no-edit <target>..HEAD`
+9. **推送建议** → 提示是否 `git push --force-with-lease`（reset）或普通 `git push`（revert）
+
+---
+
+## 安全护栏
+
+- **备份**：执行前自动在 reflog 中记录当前 HEAD，可用 `git switch -c backup/<timestamp>` 恢复。
+- **保护分支**：如检测到 `main` / `master` / `production` 等受保护分支且开启 `reset` 模式，将要求额外确认。
+- **--dry-run 默认开启**：防止误操作。
+- **--force 禁止**：不提供 `--force`；如需强推，请手动输入 `git push --force-with-lease`。
+
+---
+
+## 适用场景示例
+
+| 场景                                            | 调用示例                                                         |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| 热修补丁上线后发现 bug，需要回到 Tag `v1.2.0`   | `/git-rollback --branch release/v1 --target v1.2.0 --mode reset` |
+| 运维同事误推了 debug 日志提交，需要生成反向提交 | `/git-rollback --branch main --target 3f2e7c9 --mode revert`     |
+| 调研历史 bug，引导新人浏览分支历史              | `/git-rollback` （全交互，dry‑run）                              |
+
+---
+
+## 注意
+
+1. **reset vs revert**
+   - **reset** 会改变历史，需要强推并可能影响其他协作者，谨慎使用。
+   - **revert** 更安全，生成新提交保留历史，但会增加一次记录。
+2. **嵌入式仓库** 常有大体积二进制文件；回滚前请确保 LFS/子模块状态一致。
+3. 若仓库启用了 CI 强制校验，回滚后可能自动触发流水线；确认管控策略以免误部署旧版本。
+
+---