claude-pangu 2.2.21 → 2.3.0

package/skills/git-master/SKILL.md

@@ -12,434 +12,737 @@ triggers:
 # Git Master 技能
 
 智能 Git 操作技能，提供安全、规范的版本控制操作指引。
+实现 6 阶段提交工作流、3 模式检测、强制性输出校验。
 
-## 三大专业化角色
-
-Git Master 包含三个专业化角色，根据任务自动切换：
+---
 
-### 1. Commit Architect (提交架构师)
+## 模式检测（第一步 - 必须执行）
 
-负责创建原子化、高质量的提交。
+> **⚠️ CRITICAL**: 收到任何 Git 相关请求时，必须**首先**判定操作模式。
+> 不可跳过此步骤直接执行任何 Git 命令。
 
-**核心原则 - 默认多提交**:
+| 用户请求模式 | 检测关键词 | 激活模式 |
+|-------------|-----------|---------|
+| "提交" "commit" "暂存" "stage" | commit, add, stage, push, 提交, 暂存 | **COMMIT** → 进入 Phase 0-6 |
+| "变基" "rebase" "squash" "整理历史" | rebase, squash, fixup, amend, 变基, 合并提交 | **REBASE** → 进入 R1-R4 |
+| "谁改的" "blame" "查找" "什么时候引入" | blame, bisect, log -S, 谁, 何时, 查找, 历史 | **HISTORY_SEARCH** → 进入 H1-H3 |
 
 ```
-┌─────────────────────────────────────────┐
-│  文件数量规则 (MANDATORY)                │
-├─────────────────────────────────────────┤
-│  3+ 文件 → 必须 2+ 个提交               │
-│  5+ 文件 → 必须 3+ 个提交               │
-│  10+ 文件 → 必须 5+ 个提交              │
-└─────────────────────────────────────────┘
+┌─────────────────────────────────────────────┐
+│  MODE DETECTION (MANDATORY FIRST STEP)      │
+├─────────────────────────────────────────────┤
+│                                             │
+│  用户请求 ──→ 关键词匹配                      │
+│              ├─ commit/push/stage            │
+│              │  → COMMIT MODE (Phase 0-6)    │
+│              ├─ rebase/squash/fixup          │
+│              │  → REBASE MODE (R1-R4)        │
+│              └─ blame/bisect/log -S          │
+│                 → HISTORY SEARCH (H1-H3)     │
+│                                             │
+│  ⚠️ 无法判定 → 询问用户明确意图               │
+└─────────────────────────────────────────────┘
 ```
 
-**原子提交原则**:
-- 每个提交只做一件事
-- 提交之间有清晰的依赖关系
-- 后续提交依赖前序提交
+---
+
+## 核心原则：默认多提交
+
+> **🔴 HARD RULE — 不可违反**
 
-### 2. Rebase Surgeon (变基外科医生)
+| 变更文件数 | 最少提交数 | 强制性 |
+|-----------|-----------|--------|
+| 1-2 文件 | 1 个提交 | 可选 |
+| 3-4 文件 | 2+ 个提交 | **MANDATORY** |
+| 5-9 文件 | 3+ 个提交 | **MANDATORY** |
+| 10+ 文件 | 5+ 个提交 | **MANDATORY** |
 
-负责历史重写、冲突解决、分支清理。
+**最小提交数公式**: `min_commits = ceil(file_count / 3)`
 
-**专长**:
-- 交互式 rebase 操作
-- 冲突解决策略
-- 分支合并整理
-- Squash 和 fixup 操作
+### 拆分判定标准
 
-### 3. History Archaeologist (历史考古学家)
+| 拆分条件 | 说明 | 优先级 |
+|---------|------|--------|
+| 不同目录 | `src/` vs `tests/` vs `docs/` | **最高** |
+| 不同组件类型 | 配置 vs 类型 vs 实现 vs 测试 | 高 |
+| 不同关注点 | 基础设施 vs 业务逻辑 | 高 |
+| 不同依赖层 | 被依赖方先提交 | 中 |
+| 实现+测试配对 | 同一功能的实现和测试可合并 | 低 |
 
-负责查找特定变更的时间和作者。
+### 提交前强制自检
 
-**专长**:
-- `git blame` 追溯
-- `git bisect` 二分查找
-- `git log -S` 代码搜索
-- 历史变更分析
+> **⚠️ HARD STOP**: 执行 `git commit` 前，必须完成以下检查。
+> 任何一项不通过，**禁止**继续提交。
+
+```
+┌─────────────────────────────────────────────┐
+│  PRE-COMMIT SELF-CHECK (MANDATORY)          │
+├─────────────────────────────────────────────┤
+│  □ 文件数 ≤ 2？ 或已按规则拆分？              │
+│  □ 每个提交只做一件事？                       │
+│  □ 提交消息匹配检测到的仓库风格？              │
+│  □ 无敏感文件（.env, credentials 等）？       │
+│  □ 提交间有清晰的依赖关系？                   │
+│  □ 3+ 文件的提交有书面理由？                  │
+│                                             │
+│  ✗ 任一未通过 → 回到 Phase 3 重新规划         │
+└─────────────────────────────────────────────┘
+```
 
 ---
 
-## 自动风格检测
+## COMMIT MODE: Phase 0-6 工作流
 
-Git Master 会自动分析仓库的提交风格并匹配：
+### Phase 0: 并行上下文收集
 
-### 检测方法
+> **所有命令必须并行执行**，减少等待时间。
 
 ```bash
-# 分析最近 30 个提交
+# 并行执行以下 4 组命令：
+
+# [1] 工作区状态
+git status
+
+# [2] 变更详情（暂存 + 未暂存）
+git diff
+git diff --staged
+
+# [3] 仓库提交风格（最近 30 条）
 git log --oneline -30
+
+# [4] 分支上下文
+git branch -vv
+git log --oneline main..HEAD 2>/dev/null || git log --oneline master..HEAD 2>/dev/null
 ```
 
-### 检测维度
+收集结果后立即进入 Phase 1。
 
-| 维度 | 选项 | 示例 |
-|------|------|------|
-| **语言** | 英文 / 中文 / 混合 | `feat: add login` vs `feat: 添加登录` |
-| **风格** | Conventional / Plain / Short | `feat(auth): add OAuth` vs `Add OAuth login` |
-| **大小写** | lowercase / Capitalize / UPPERCASE | `add feature` vs `Add feature` |
-| **长度** | 详细 / 简洁 | 50+ chars vs <30 chars |
+---
 
-### 风格报告
+### Phase 1: 风格检测（BLOCKING OUTPUT）
 
-```markdown
-## 仓库提交风格分析
+> **⚠️ CRITICAL**: 此阶段产生的输出**必须打印**后才能进入下一阶段。
+> 不可在内部静默处理。
+
+#### 1.1 语言检测
+
+分析 `git log --oneline -30` 的输出，判定主要语言：
+
+| 检测模式 | 判定语言 |
+|---------|---------|
+| 多数消息含中文字符 | **中文 (Chinese)** |
+| 多数消息含韩文字符 | **韩文 (Korean)** |
+| 多数消息为 ASCII | **英文 (English)** |
+| 混合出现 | **混合 (Mixed)** → 优先匹配占比最高的语言 |
+
+#### 1.2 风格分类
 
-**检测样本**: 最近 30 个提交
+| 风格类型 | 特征 | 示例 |
+|---------|------|------|
+| **SEMANTIC** | `type(scope):` 格式，Conventional Commits | `feat(auth): add OAuth2 login` |
+| **PLAIN** | 动词开头，首字母大写，无前缀 | `Add user authentication` |
+| **SENTENCE** | 完整句子描述 | `Added the authentication module` |
+| **SHORT** | 极简描述，< 20 字符 | `fix typo` |
+
+#### 1.3 MANDATORY 输出块
+
+> **🔴 BLOCKING**: 必须输出以下格式后才能继续。跳过此输出 = 违反协议。
+
+```markdown
+## 📊 风格检测报告
 
 | 维度 | 检测结果 | 置信度 |
 |------|----------|--------|
-| 语言 | 英文 | 95% |
-| 格式 | Conventional Commits | 87% |
-| 大小写 | lowercase | 92% |
-| 平均长度 | 45 字符 | - |
+| 语言 | {English/Chinese/Korean/Mixed} | {N}% |
+| 格式 | {SEMANTIC/PLAIN/SENTENCE/SHORT} | {N}% |
+| 大小写 | {lowercase/Capitalize} | {N}% |
+| 平均长度 | {N} 字符 | - |
 
-**将采用风格**: `<type>(<scope>): <lowercase description>`
+**采用风格**: `{检测到的风格模板}`
+**示例**: `{基于检测风格的示例消息}`
 ```
 
-## 安全协议（不可违反）
+---
 
-### 永远不要:
+### Phase 2: 分支上下文分析
 
-| 禁止操作 | 原因 |
-|----------|------|
-| 更新 git config | 可能影响全局设置 |
-| 运行破坏性/不可逆命令 | 除非用户明确请求 |
-| 跳过 hooks | `--no-verify`, `--no-gpg-sign` 等 |
-| 强制推送到 main/master | 如果用户请求，发出警告 |
-| 未经请求就提交 | 用户必须明确要求 |
-
-### 危险命令白名单（需用户明确请求）:
+#### 2.1 分支状态判定
 
 ```bash
-git push --force        # 强制推送
-git push -f             # 强制推送
-git reset --hard        # 硬重置
-git clean -fd           # 删除未跟踪文件
-git checkout -- .       # 丢弃所有更改
+# 检查当前分支
+git branch --show-current
+
+# 检查与远程的关系
+git status -sb
+
+# 检查是否有未推送的提交
+git log @{u}..HEAD --oneline 2>/dev/null
 ```
 
-### Git Commit --amend 规则
+#### 2.2 历史重写安全评估
 
-**仅在以下所有条件都满足时才能使用 --amend**:
+| 条件 | 判定 | 操作 |
+|------|------|------|
+| 当前在 main/master | **禁止重写** | 仅允许新提交 |
+| 分支已推送到远程且有协作者 | **风险高** | 警告用户，需明确确认 |
+| 本地分支，未推送 | **安全** | 可自由 rebase/amend |
+| 分支已推送但仅自己使用 | **需确认** | 可 force push，但需用户确认 |
 
-1. 用户明确请求 amend，**或者** commit 成功但 pre-commit hook 自动修改了需要包含的文件
-2. HEAD commit 是由你在本次对话中创建的（验证：`git log -1 --format='%an %ae'`）
-3. Commit 还没有推送到远程（验证：`git status` 显示 "Your branch is ahead"）
+#### 2.3 策略决定
 
-**关键**: 
-- 如果 commit **失败**或被 hook **拒绝**，**永远不要** amend - 修复问题并创建**新** commit
-- 如果你已经推送到远程，**永远不要** amend（除非用户明确请求，因为需要 force push）
+```
+分支状态 ──→ 本地未推送？
+             ├─ 是 → 可使用 fixup + autosquash
+             └─ 否 → 已推送？
+                      ├─ 是 → 仅新提交（除非用户要求 force push）
+                      └─ 检查远程 → 决定策略
+```
 
 ---
 
-## 提交工作流
-
-### 步骤 1: 了解状态
+### Phase 3: 原子单元规划（BLOCKING OUTPUT）
 
-并行运行以下命令：
+> **⚠️ CRITICAL**: 此阶段产生的提交计划**必须打印**并等待确认后才能执行。
 
-```bash
-# 查看所有未跟踪文件
-git status
+#### 3.1 计算最小提交数
 
-# 查看将要提交的暂存和非暂存更改
-git diff
+```
+file_count = len(changed_files)
+min_commits = max(1, ceil(file_count / 3))
 
-# 查看最近的提交消息（学习仓库风格）
-git log --oneline -10
+# 硬性下限校验
+if file_count >= 3 and planned_commits < 2: REJECT
+if file_count >= 5 and planned_commits < 3: REJECT
+if file_count >= 10 and planned_commits < 5: REJECT
 ```
 
-### 步骤 2: 分析更改
+#### 3.2 拆分策略
 
-分析所有暂存的更改（之前暂存的和新添加的），起草提交消息：
+按以下优先级拆分：
 
-1. **总结更改性质**：新功能、增强、bug 修复、重构、测试、文档等
-2. **确保消息准确反映更改和目的**：
-   - `add` = 全新功能
-   - `update` = 现有功能增强
-   - `fix` = bug 修复
-   - `refactor` = 代码重组
-3. **不要提交可能包含敏感信息的文件**（`.env`, `credentials.json` 等）
-4. **起草简洁的提交消息**（1-2 句），聚焦"为什么"而非"做什么"
+1. **目录/模块优先**: 不同目录的文件分到不同提交
+2. **关注点分离**: 配置 → 类型/接口 → 实现 → 测试 → 文档
+3. **依赖排序**: 被依赖的代码先提交
+4. **实现+测试配对**: 同一功能的实现文件和测试文件**可以**放同一提交
 
-### 步骤 3: 执行提交
+#### 3.3 3+ 文件提交的强制理由
 
-```bash
-# 添加相关的未跟踪文件到暂存区
-git add <files>
+> **🔴 MANDATORY**: 任何包含 3 个及以上文件的单次提交，**必须**附带书面理由。
 
-# 创建提交
-git commit -m "<type>: <description>"
+合理理由示例：
+- "这三个文件属于同一组件的不同层（model/service/controller），拆分会破坏编译"
+- "重命名操作跨越多个文件，必须原子性完成"
+- "配置文件和配套的类型声明必须同步更新"
 
-# 验证成功
-git status
-```
+不可接受的理由：
+- "方便" "文件太少不值得拆" "一起提交更快"
 
-### 步骤 4: 处理失败
+#### 3.4 MANDATORY 输出块
 
-如果提交因 pre-commit hook 失败：
-1. 修复问题
-2. 创建**新**提交（不要 amend）
+> **🔴 BLOCKING**: 必须输出以下提交计划后才能进入 Phase 4。
 
----
+```markdown
+## 📋 提交计划
 
-## Conventional Commits 格式
+**变更文件数**: {N} 个
+**计划提交数**: {M} 个 (最小要求: {min_commits})
 
-### 基本格式
+### Commit 1: `{type}({scope}): {description}`
+- `path/to/file1.ts` — {变更说明}
+- `path/to/file2.ts` — {变更说明}
 
-```
-<type>(<scope>): <description>
+### Commit 2: `{type}({scope}): {description}`
+- `path/to/file3.ts` — {变更说明}
 
-[optional body]
+{3+ 文件理由（如适用）: ...}
 
-[optional footer(s)]
+### 依赖关系
+Commit 1 → Commit 2 → Commit 3
+(每个提交可独立编译通过)
 ```
 
-### 类型
+---
 
-| 类型 | 描述 | 示例 |
+### Phase 4: 提交策略决定
+
+#### 4.1 Fixup vs 新提交
+
+| 条件 | 策略 | 命令 |
 |------|------|------|
-| `feat` | 新功能 | `feat(auth): add OAuth2 login` |
-| `fix` | Bug 修复 | `fix(api): handle null response` |
-| `docs` | 文档更新 | `docs(readme): update installation` |
-| `style` | 代码格式 | `style: format with prettier` |
-| `refactor` | 重构 | `refactor(utils): simplify parser` |
-| `perf` | 性能优化 | `perf(query): add database index` |
-| `test` | 测试相关 | `test(auth): add login tests` |
-| `build` | 构建系统 | `build: upgrade webpack to v5` |
-| `ci` | CI 配置 | `ci: add GitHub Actions` |
-| `chore` | 杂项 | `chore: update dependencies` |
-| `revert` | 回退 | `revert: revert commit abc123` |
+| 修复前序提交的 bug | fixup | `git commit --fixup=<hash>` |
+| 补充前序提交遗漏的文件 | fixup | `git commit --fixup=<hash>` |
+| 独立的新变更 | 新提交 | `git commit -m "..."` |
+| 用户明确要求 amend | amend | `git commit --amend` (需满足 amend 规则) |
 
-### 示例
+#### 4.2 历史重建决定
 
-**简单提交**:
 ```
-feat(user): add email verification
+使用了 fixup？
+├─ 是 → Phase 6 中执行 autosquash rebase
+└─ 否 → 直接进入 Phase 5
 
-Implement email verification flow with token generation
-and expiration handling.
+分支已推送？
+├─ 是 → 需要 force push（需用户确认）
+└─ 否 → 安全执行
 ```
 
-**带 Breaking Change**:
+---
+
+### Phase 5: 提交执行
+
+#### 5.1 TodoWrite 注册
+
+> 使用 TodoWrite 注册每个提交为独立任务，确保进度可追踪。
+
+```
+TODO 1: [pending] Commit 1 - {description}
+TODO 2: [pending] Commit 2 - {description}
+TODO 3: [pending] Commit 3 - {description}
 ```
-feat(api)!: change response format
 
-BREAKING CHANGE: Response now wraps data in { data, meta } structure.
-Migration guide available in docs/migration.md
+#### 5.2 执行每个提交
+
+对计划中的每个提交，按顺序执行：
+
+```bash
+# 1. 暂存文件
+git add <file1> <file2>
+
+# 2. 执行提交（消息匹配 Phase 1 检测到的风格）
+git commit -m "<message>"
+
+# 3. 验证
+git status
+git log --oneline -1
+```
+
+#### 5.3 提交消息生成规则
+
+- **必须**匹配 Phase 1 检测到的风格
+- **SEMANTIC 风格**: `<type>(<scope>): <lowercase description>`
+- **PLAIN 风格**: `<Verb> <description>`
+- **SENTENCE 风格**: `<Past tense sentence>`
+- **SHORT 风格**: `<brief phrase>`
+- **中文仓库**: 描述部分使用中文
+
+#### 5.4 Hook 失败处理
+
+```
+提交被 pre-commit hook 拒绝？
+├─ 查看 hook 输出，了解失败原因
+├─ 修复问题（lint、格式、测试等）
+├─ 重新暂存修改后的文件
+├─ 创建新提交（⚠️ 绝对不要 amend 失败的提交）
+└─ 更新 TODO 状态
 ```
 
 ---
 
-## 原子提交工作流 (Commit Architect)
+### Phase 6: 验证与清理
 
-### 多文件提交分解
+#### 6.1 提交后验证
 
-当有多个文件需要提交时，**必须**按以下规则分解：
+```bash
+# 检查所有提交是否成功
+git log --oneline -N  # N = 计划提交数
 
+# 确认工作区干净
+git status
+
+# 确认无遗漏文件
+git diff
+```
+
+#### 6.2 Force Push 决定
+
+```
+使用了 fixup/autosquash？
+├─ 是 → git rebase -i --autosquash <base>
+│       ├─ 分支未推送？ → 安全执行
+│       └─ 分支已推送？ → 需用户明确确认 force push
+└─ 否 → 无需额外操作
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  原子提交分解流程                                             │
-├─────────────────────────────────────────────────────────────┤
-│  1. 识别更改的逻辑分组                                        │
-│     - 同一功能的相关文件                                      │
-│     - 基础设施变更 vs 业务逻辑变更                            │
-│     - 依赖变更 vs 代码变更                                    │
-│                                                             │
-│  2. 确定依赖顺序                                              │
-│     - 被依赖的代码先提交                                      │
-│     - 配置/类型先于实现                                       │
-│     - 工具/辅助函数先于业务代码                                │
-│                                                             │
-│  3. 每组独立提交                                              │
-│     - 每个提交可独立编译通过                                   │
-│     - 每个提交有清晰的目的                                    │
-└─────────────────────────────────────────────────────────────┘
+
+#### 6.3 最终报告
+
+```markdown
+## ✅ 提交完成报告
+
+| 提交 | 类型 | 消息 | 文件数 |
+|------|------|------|--------|
+| {hash1} | feat | {msg1} | {N} |
+| {hash2} | test | {msg2} | {N} |
+
+**总计**: {M} 个提交，{N} 个文件
+**分支**: {branch_name}
+**状态**: {已推送/待推送/待 force push}
 ```
 
-### 示例：10 个文件的原子提交
+---
+
+## REBASE MODE: R1-R4
 
-假设修改了以下 10 个文件：
+### R1: 上下文分析与安全评估
 
+```bash
+# 并行执行
+git log --oneline -20
+git branch -vv
+git status
+git log @{u}..HEAD --oneline 2>/dev/null
 ```
-修改的文件:
-├── package.json              # 新增依赖
-├── tsconfig.json             # 配置更新
-├── src/types/user.ts         # 类型定义
-├── src/utils/validation.ts   # 工具函数
-├── src/services/auth.ts      # 认证服务
-├── src/services/user.ts      # 用户服务
-├── src/controllers/auth.ts   # 认证控制器
-├── src/routes/auth.ts        # 认证路由
-├── tests/auth.test.ts        # 测试
-└── README.md                 # 文档
+
+**安全检查清单**:
+
+| 检查项 | 安全 | 危险 |
+|--------|------|------|
+| 当前分支 | feature/* | main/master |
+| 远程状态 | 未推送 | 已推送（需 force push） |
+| 协作者 | 仅自己 | 多人协作 |
+| 工作区 | 干净 | 有未提交更改 |
+
+> **🔴 HARD STOP**: 如果在 main/master 分支上，**禁止**执行 rebase。
+> 必须先切换到 feature 分支。
+
+### R2: 执行 Rebase
+
+#### 交互式 Rebase
+
+```bash
+# 编辑最近 N 个提交
+git rebase -i HEAD~N
+
+# 从某个提交开始
+git rebase -i <commit>^
 ```
 
-**正确的提交分解** (5 个提交):
+#### Rebase 操作符
+
+| 操作 | 缩写 | 说明 |
+|------|------|------|
+| pick | p | 保留提交 |
+| reword | r | 修改提交消息 |
+| edit | e | 停下来修改内容 |
+| squash | s | 合并到前一个提交（保留消息） |
+| fixup | f | 合并到前一个提交（丢弃消息） |
+| drop | d | 删除提交 |
+
+#### Autosquash 工作流
 
 ```bash
-# Commit 1: 基础设施
-git add package.json tsconfig.json
-git commit -m "chore: add zod validation library"
+# 先创建 fixup 提交
+git commit --fixup=<target_hash>
+
+# 然后自动整理
+git rebase -i --autosquash <base_commit>
+```
 
-# Commit 2: 类型和工具
-git add src/types/user.ts src/utils/validation.ts
-git commit -m "feat(types): add user types and validation utils"
+#### Onto Rebase（变更基底）
 
-# Commit 3: 服务层
-git add src/services/auth.ts src/services/user.ts
-git commit -m "feat(services): implement auth and user services"
+```bash
+# 将分支移到新基底
+git rebase --onto <new_base> <old_base> <branch>
+```
 
-# Commit 4: API 层
-git add src/controllers/auth.ts src/routes/auth.ts
-git commit -m "feat(api): add auth controller and routes"
+### R3: 冲突解决与验证
 
-# Commit 5: 测试和文档
-git add tests/auth.test.ts README.md
-git commit -m "test(auth): add auth service tests and docs"
 ```
+冲突发生时：
+1. git status                    — 查看冲突文件
+2. 打开文件，找到 <<<< ==== >>>> 标记
+3. 选择保留内容，删除冲突标记
+4. git add <resolved_files>       — 标记已解决
+5. git rebase --continue          — 继续 rebase
+6. 重复直到所有冲突解决
 
-### 提交依赖图
+放弃 rebase：
+git rebase --abort
+```
 
+**验证**:
+
+```bash
+# Rebase 完成后
+git log --oneline -10
+git diff <base_branch>..HEAD --stat
 ```
-Commit 1 (chore: add zod)
-    ↓
-Commit 2 (types & utils) ─────────────┐
-    ↓                                 │
-Commit 3 (services) ←─ 依赖 types     │
-    ↓                                 │
-Commit 4 (api) ←─ 依赖 services       │
-    ↓                                 │
-Commit 5 (tests) ←─ 依赖所有上述 ─────┘
+
+### R4: 报告
+
+```markdown
+## 📋 Rebase 报告
+
+**操作**: {interactive/autosquash/onto}
+**分支**: {branch_name}
+**结果**:
+- 提交数: {before} → {after}
+- 冲突: {N} 个（已全部解决）
+- 状态: {需要 force push / 已完成}
+
+**变更提交**:
+| 序号 | Hash | 消息 |
+|------|------|------|
+| 1 | {hash} | {message} |
 ```
 
 ---
 
-## 历史考古工具 (History Archaeologist)
+## HISTORY SEARCH MODE: H1-H3
+
+### H1: 确定搜索类型
 
-### 查找代码作者
+| 用户意图 | 搜索类型 | 使用命令 |
+|---------|---------|---------|
+| "谁修改了这行代码" | **blame** | `git blame` |
+| "这个函数什么时候添加的" | **pickaxe** | `git log -S` |
+| "匹配某个模式的提交" | **regex** | `git log -G` |
+| "这个 bug 哪个提交引入的" | **bisect** | `git bisect` |
+| "这个文件的修改历史" | **file_log** | `git log --follow` |
+
+### H2: 执行搜索
+
+#### Blame（追溯）
 
 ```bash
-# 查看文件每一行的最后修改者
+# 查看文件每行的最后修改者
 git blame <file>
 
-# 查看特定行范围
+# 指定行范围
 git blame -L 10,20 <file>
 
-# 忽略空白字符变更
+# 忽略空白变更
 git blame -w <file>
 
 # 显示邮箱
 git blame -e <file>
+
+# 追溯到更早版本（忽略最近一次变更）
+git blame <commit>^ -- <file>
 ```
 
-### 查找特定代码的引入时间
+#### Pickaxe（代码搜索）
 
 ```bash
 # 搜索添加/删除特定字符串的提交
 git log -S "functionName" --oneline
 
-# 搜索正则表达式
+# 显示差异
+git log -S "functionName" -p
+
+# 限定文件范围
+git log -S "functionName" -- "src/**/*.ts"
+```
+
+#### Regex（正则搜索）
+
+```bash
+# 搜索匹配正则表达式的提交
 git log -G "pattern.*regex" --oneline
 
 # 显示差异
-git log -S "functionName" -p
+git log -G "pattern.*regex" -p
 ```
 
-### 二分查找 Bug 引入点
+#### Bisect（二分查找）
 
 ```bash
 # 开始二分
 git bisect start
 
-# 标记当前为坏
+# 标记当前为坏版本
 git bisect bad
 
 # 标记已知好的版本
 git bisect good <commit>
 
-# Git 会自动切换到中间版本，测试后标记：
-git bisect good  # 或
-git bisect bad
+# Git 自动切换到中间版本，测试后标记：
+git bisect good  # 或 git bisect bad
 
 # 找到后重置
 git bisect reset
 ```
 
-### 历史分析报告
+#### File Log（文件历史）
+
+```bash
+# 查看文件完整修改历史
+git log --follow --oneline -- <file>
+
+# 显示差异
+git log --follow -p -- <file>
+
+# 仅显示统计
+git log --follow --stat -- <file>
+```
+
+### H3: 结果呈现
+
+> 搜索结果必须以结构化格式呈现，附带可操作的上下文。
 
 ```markdown
-## 历史考古报告
+## 🔍 历史搜索报告
+
+### 搜索目标
+{要查找的代码/功能/问题}
 
-### 查找目标
-[要查找的代码/功能]
+### 搜索方法
+{blame/pickaxe/regex/bisect/file_log}
 
 ### 发现
 
-| 提交 | 日期 | 作者 | 变更 |
-|------|------|------|------|
-| abc123 | 2024-01-15 | Alice | 首次引入 |
-| def456 | 2024-02-20 | Bob | 重构 |
-| ghi789 | 2024-03-10 | Alice | Bug 修复 |
+| 提交 | 日期 | 作者 | 变更说明 |
+|------|------|------|---------|
+| {hash1} | {date1} | {author1} | {description1} |
+| {hash2} | {date2} | {author2} | {description2} |
 
 ### 关键变更点
-[重要的变更说明]
+{重要的变更说明和上下文}
 
-### 建议
-[基于历史的建议]
+### 可操作建议
+- {基于发现的建议 1}
+- {基于发现的建议 2}
 ```
 
 ---
 
-## Rebase 外科手术 (Rebase Surgeon)
+## 快速参考
 
-### 交互式 Rebase
+### 风格检测速查
 
-```bash
-# 编辑最近 N 个提交
-git rebase -i HEAD~N
+```
+SEMANTIC:  feat(scope): description     ← 有 type( 前缀
+PLAIN:     Add user authentication      ← 首字母大写动词开头
+SENTENCE:  Added the auth module        ← 过去式完整句子
+SHORT:     fix typo                     ← < 20 字符
+```
 
-# 编辑从某个提交开始
-git rebase -i <commit>^
+### 决策树
+
+```
+收到 Git 请求
+├─ 提交类？ → COMMIT MODE
+│  ├─ Phase 0: 并行收集上下文
+│  ├─ Phase 1: 风格检测 [BLOCKING OUTPUT]
+│  ├─ Phase 2: 分支上下文
+│  ├─ Phase 3: 原子规划 [BLOCKING OUTPUT]
+│  ├─ Phase 4: 策略决定
+│  ├─ Phase 5: 逐个执行
+│  └─ Phase 6: 验证报告
+├─ Rebase 类？ → REBASE MODE
+│  ├─ R1: 安全评估
+│  ├─ R2: 执行操作
+│  ├─ R3: 冲突解决
+│  └─ R4: 报告
+└─ 历史查询类？ → HISTORY SEARCH
+   ├─ H1: 确定搜索类型
+   ├─ H2: 执行搜索
+   └─ H3: 结果呈现
 ```
 
-### Rebase 操作符
+### 反模式清单
 
-| 操作 | 缩写 | 说明 |
-|------|------|------|
-| pick | p | 使用提交 |
-| reword | r | 使用提交，但编辑提交消息 |
-| edit | e | 使用提交，但停下来修改 |
-| squash | s | 使用提交，但合并到前一个 |
-| fixup | f | 类似 squash，但丢弃提交消息 |
-| drop | d | 删除提交 |
+> **🚫 以下行为绝对禁止**:
+
+| 反模式 | 正确做法 |
+|--------|---------|
+| 跳过风格检测直接提交 | 必须先完成 Phase 1 |
+| 10 个文件一次提交 | 按规则拆分为 5+ 个提交 |
+| 不打印 BLOCKING OUTPUT | Phase 1 和 Phase 3 的输出不可省略 |
+| 对失败的提交执行 amend | 修复后创建新提交 |
+| 在 main 上执行 rebase | 切换到 feature 分支 |
+| 不检查分支安全就 force push | 先完成 R1 安全评估 |
+| 3+ 文件提交无理由 | 必须附带书面理由 |
+| 内部消化风格检测结果 | 必须输出格式化报告 |
+
+---
+
+## 安全协议（不可违反）
+
+### 永远不要:
+
+| 禁止操作 | 原因 |
+|----------|------|
+| 更新 git config | 可能影响全局设置 |
+| 运行破坏性/不可逆命令 | 除非用户明确请求 |
+| 跳过 hooks | `--no-verify`, `--no-gpg-sign` 等 |
+| 强制推送到 main/master | 如果用户请求，发出警告 |
+| 未经请求就提交 | 用户必须明确要求 |
 
-### Squash 工作流
+### 危险命令白名单（需用户明确请求）:
 
 ```bash
-# 将最近 3 个提交合并为 1 个
-git rebase -i HEAD~3
+git push --force        # 强制推送
+git push -f             # 强制推送
+git reset --hard        # 硬重置
+git clean -fd           # 删除未跟踪文件
+git checkout -- .       # 丢弃所有更改
+```
+
+### Git Commit --amend 规则
+
+**仅在以下所有条件都满足时才能使用 --amend**:
+
+1. 用户明确请求 amend，**或者** commit 成功但 pre-commit hook 自动修改了需要包含的文件
+2. HEAD commit 是由你在本次对话中创建的（验证：`git log -1 --format='%an %ae'`）
+3. Commit 还没有推送到远程（验证：`git status` 显示 "Your branch is ahead"）
+
+**关键**:
+- 如果 commit **失败**或被 hook **拒绝**，**永远不要** amend - 修复问题并创建**新** commit
+- 如果你已经推送到远程，**永远不要** amend（除非用户明确请求，因为需要 force push）
+
+---
+
+## Conventional Commits 格式
 
-# 在编辑器中：
-# pick abc123 First commit
-# squash def456 Second commit  
-# squash ghi789 Third commit
+### 基本格式
 
-# 然后编辑合并后的提交消息
 ```
+<type>(<scope>): <description>
 
-### 冲突解决策略
+[optional body]
 
+[optional footer(s)]
 ```
-冲突解决流程：
-1. 查看冲突文件: git status
-2. 打开文件，找到冲突标记
-3. 选择保留的内容
-4. 删除冲突标记
-5. git add <resolved-files>
-6. git rebase --continue
+
+### 类型
+
+| 类型 | 描述 | 示例 |
+|------|------|------|
+| `feat` | 新功能 | `feat(auth): add OAuth2 login` |
+| `fix` | Bug 修复 | `fix(api): handle null response` |
+| `docs` | 文档更新 | `docs(readme): update installation` |
+| `style` | 代码格式 | `style: format with prettier` |
+| `refactor` | 重构 | `refactor(utils): simplify parser` |
+| `perf` | 性能优化 | `perf(query): add database index` |
+| `test` | 测试相关 | `test(auth): add login tests` |
+| `build` | 构建系统 | `build: upgrade webpack to v5` |
+| `ci` | CI 配置 | `ci: add GitHub Actions` |
+| `chore` | 杂项 | `chore: update dependencies` |
+| `revert` | 回退 | `revert: revert commit abc123` |
+
+### 示例
+
+**简单提交**:
 ```
+feat(user): add email verification
+
+Implement email verification flow with token generation
+and expiration handling.
+```
+
+**带 Breaking Change**:
+```
+feat(api)!: change response format
+
+BREAKING CHANGE: Response now wraps data in { data, meta } structure.
+Migration guide available in docs/migration.md
+```
+
+### 语义化版本关联
+
+- **`fix:`** → PATCH 版本 (1.0.0 → 1.0.1)
+- **`feat:`** → MINOR 版本 (1.0.0 → 1.1.0)
+- **BREAKING CHANGE** → MAJOR 版本 (1.0.0 → 2.0.0)
 
 ---
 
@@ -482,11 +785,11 @@ git status
 git diff
 
 # 检查当前分支是否跟踪远程分支且是最新的
-git status
+git status -sb
 
 # 理解从 base 分支分叉以来的完整提交历史
-git log main..HEAD
-git diff main...HEAD
+git log main..HEAD --oneline
+git diff main...HEAD --stat
 ```
 
 ### 步骤 2: 分析所有更改
@@ -518,39 +821,6 @@ EOF
 )"
 ```
 
-### PR 模板
-
-```markdown
-## Summary
-<1-3 个要点描述这个 PR 做了什么>
-
-## Changes
-- 变更 1
-- 变更 2
-- ...
-
-## Testing
-- 如何测试这些变更
-- 需要注意的测试场景
-
-## Related Issues
-Fixes #123
-```
-
----
-
-## 分支管理
-
-### 创建分支
-
-```bash
-# 从当前位置创建
-git checkout -b feature/xxx
-
-# 从特定分支创建
-git checkout -b feature/xxx origin/main
-```
-
 ### 分支命名约定
 
 | 前缀 | 用途 | 示例 |
@@ -562,77 +832,6 @@ git checkout -b feature/xxx origin/main
 | `docs/` | 文档 | `docs/api-reference` |
 | `test/` | 测试 | `test/e2e-coverage` |
 
-### 保护分支
-
-以下分支受保护，操作前需额外确认：
-- `main`
-- `master`
-- `develop`
-- `production`
-
----
-
-## 常见操作速查
-
-### 查看状态
-
-```bash
-git status                    # 工作区状态
-git diff                      # 未暂存的更改
-git diff --staged             # 已暂存的更改
-git log --oneline -10         # 最近 10 个提交
-git log --graph --oneline     # 图形化历史
-```
-
-### 暂存更改
-
-```bash
-git add <file>                # 暂存特定文件
-git add .                     # 暂存所有更改
-git add -p                    # 交互式暂存
-git reset HEAD <file>         # 取消暂存
-```
-
-### 撤销更改
-
-```bash
-git checkout -- <file>        # 丢弃工作区更改（需用户确认）
-git reset HEAD~1              # 撤销最近一次提交（保留更改）
-git reset --soft HEAD~1       # 软重置
-```
-
-### 远程操作
-
-```bash
-git fetch                     # 获取远程更新
-git pull                      # 拉取并合并
-git push                      # 推送到远程（需用户确认）
-git push -u origin <branch>   # 推送并设置上游
-```
-
----
-
-## 与其他 Agent 协作
-
-### 代码审查后提交
-
-当魏征（代码审查）完成审查后：
-
-```markdown
-# 魏征审查通过后
-@git-master 请提交这些更改，消息为：
-"fix(auth): address code review feedback"
-```
-
-### 功能完成后创建 PR
-
-当鲁班（实现）完成功能后：
-
-```markdown
-# 鲁班实现完成后
-@git-master 请创建 PR 将这个功能合并到 main
-```
-
 ---
 
 ## 配置选项
@@ -665,28 +864,4 @@ git push -u origin <branch>   # 推送并设置上游
 
 ---
 
-## 故障排除
-
-### 提交被 hook 拒绝
-
-1. 查看 hook 输出，了解失败原因
-2. 修复问题（lint、格式、测试等）
-3. 重新添加修改后的文件
-4. 创建新提交（不要 amend）
-
-### 合并冲突
-
-1. 使用 `git status` 查看冲突文件
-2. 手动解决冲突
-3. `git add <resolved-files>`
-4. 继续合并或 rebase
-
-### 推送被拒绝
-
-1. 先 `git pull` 获取最新更改
-2. 解决任何冲突
-3. 重新推送
-
----
-
-*Git Master 技能 - 安全、规范、智能的 Git 操作指引*
+*Git Master 技能 v2.0 — 6 阶段提交工作流 · 3 模式检测 · 强制性输出校验*