# Commit 规范(北斗治理规范 v1)

> 团队来源:北斗 / 瑞升
> 设计文档:`docs/superpowers/specs/2026-05-14-beidou-git-governance-design.md`(myproject 仓)
> 适用范围:JHA-126-bili / JHA-117-pronhub 两个项目编号下所有前端仓库

---

## 1. 首次安装

clone 完仓库后,在仓库根执行一次:

```bash
bash scripts/install-hooks.sh
```

效果:把 `core.hooksPath` 指向仓库内 `.githooks/`,启用本地 commit-msg 校验。

紧急绕过:

```bash
git commit --no-verify
```

仅用于紧急上线,事后必须 `git commit --amend` 补全合规 prefix 后再 push。

---

## 2. Commit Subject 必含 4 个 Prefix 之一

每条 commit 的 subject(第一行)必须以下列 4 个 prefix 之一开头,**大小写敏感、方括号包裹、后接一个空格**:

| Prefix | 含义 | 是否计入 AI 占比统计 |
|---|---|---|
| `[Ai]` | AI 辅助生成 | ✅ 计入 AI 分子 |
| `[Human]` | 纯人工 | ✅ 计入人工分子 |
| `[Lib-Upgrade]` | 框架/依赖升级(复用) | ❌ 排除(不计入分母) |
| `[Migrate]` | 跨项目迁移代码 | ❌ 排除(不计入分母) |

---

## 3. 推荐写法

Prefix 后接 Conventional Commits 风格的 `type(scope): subject`:

```
[Ai] feat(player): 钻石购买确认弹窗 ModalPayDiamondPop
[Human] fix(wallet): 修正运营后台金额 currencyType Number 兜底
[Lib-Upgrade] chore(deps): 升级 web-sdk 1.0.8 → 1.1.2
[Migrate] feat(ui): 从 bili2_h5_client 迁入 AvatarWithBadge 组件
```

常用 type:`feat / fix / refactor / docs / test / chore / perf / ci`。

---

## 4. 可选 trailer:Co-Authored-By

`Co-Authored-By` 仅作元数据,**不参与 hook 校验**。统一格式(不带邮箱):

```
Co-Authored-By: Claude
Co-Authored-By: Cursor
Co-Authored-By: Copilot
Co-Authored-By: Cline
```

---

## 5. 豁免列表

下列自动生成的 commit message,hook 直接放行,无需补 prefix:

- `Merge branch ...` / `Merge remote-tracking ...`(merge 自动消息)
- `Revert "..."`(revert 自动消息)
- `fixup! ...` / `squash! ...`(rebase 临时产物)

---

## 6. 紧急绕过

```bash
git commit --no-verify
```

适用场景:线上 P0 hotfix、CI 阻塞导致无法启动 hook 时。

事后补救:

```bash
git commit --amend  # 补全 prefix
git push --force-with-lease  # 仅在尚未被他人 pull 时使用
```

---

## 7. FAQ

**Q1:AI 生成代码我又手工大改了一遍,算 `[Ai]` 还是 `[Human]`?**

A:看主导工作量。AI 写完后超过 50% 代码由人手改,标 `[Human]`;否则 `[Ai]`。原则:"谁产出主要代码就归谁"。

**Q2:revert 一个 `[Ai]` commit 算什么?**

A:revert 自动生成的 `Revert "..."` 消息走豁免分支,无需打 prefix。如果手动写 revert 的 subject,按"撤销动作"的来源标 prefix(自己手工写就 `[Human]`)。

**Q3:cherry-pick 从其它仓库带来的 commit 算 `[Migrate]` 吗?**

A:是。跨项目迁移(cherry-pick / 复制代码 / 移植)统一标 `[Migrate]`,不计入 AI/Human 分母。

---

## 8. 关联文档

- 本仓库 `project.md`(项目元信息 + 风险点 + 交接说明)
- myproject 仓库 `docs/superpowers/specs/2026-05-14-beidou-git-governance-design.md`(设计 spec)
- 北斗治理规范 v1(公司原始文档)