---
name: hotfix
owner: team-lead
version: 1
last-updated: 2026-04-23
---

# SOP: 紧急 hotfix（线上已坏，不能走常规 release-flow）

决策依据：[release-deploy-sop ADR](../../decisions/2026-04-23-release-deploy-sop.md) F 条。

## 触发场景

- 生产用户报 xq 命令在某种输入下崩
- `/health` 返回 500 / 服务 systemd 起不来
- 安全漏洞（token 泄漏 / 越权）
- **不适合 hotfix 的**：性能退化、文案错、新功能 bug —— 走常规 release-flow

## 流程（跳 alpha 验证直上 epsilon）

```
本地复现 bug
    ↓
在 main 上改（不拉分支）
    ↓
写 regression test（必须，hotfix 禁 "等下再补 test"）
    ↓
uv run pytest 全绿
    ↓
git commit + push
    ↓
GHA ci.yml 绿 → bump patch 版本 + CHANGELOG
    ↓
git tag vX.Y.(Z+1) + push --tags
    ↓
GHA release.yml 自动：test gate → PyPI + skills.sh + ClawHub
                    → deploy-production（chain，自动上 epsilon）
    ↓
生产冒烟 curl + 复现刚才的 bug 路径
    ↓
通知受影响用户升级
```

## 前置（即使紧急也不能省）

- [ ] 本地 `uv run pytest` 全绿
- [ ] 新增的 regression test 覆盖刚才那个 bug（证明你真修对了）
- [ ] 版本号同步：`pyproject.toml` / `__init__.py` / `CHANGELOG.md`
- [ ] CHANGELOG 标 `### Fixed` + 一行说明

## 为什么可以跳 alpha

alpha 验证是为了"不破坏现有功能"。hotfix 场景下现有功能已经破坏了，alpha 再跑一圈也是观察 bug。直接上 epsilon 修，收益 > 风险。

但 pytest 绿 + regression test **不能跳** —— 那是你唯一的自动化网。

## 如果 hotfix 本身也挂了

立刻按 [../emergency/rollback.md](../emergency/rollback.md) 退回到出 bug 前的 tag。不要在生产上连续打 patch。

## 事后

hotfix 发完当天（或次日）在 `brain/wiki/log.md` append 一条事故记录：触发时间 / 影响范围 / 根因 / 修复 / 预防。

## 历史事故

- （初版，待事故充填）
