---
name: release-flow
owner: team-lead
version: 2
last-updated: 2026-04-23
---

# SOP: 研发发布总览

本文档是发布链路的**入口图**。具体怎么执行每一步看子 SOP。

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

## 产物 × 机器

| 产物 | 去哪 | 触发 |
|---|---|---|
| Python 包 `acong-tech-xiangqin` | PyPI | `git push --tags` |
| Skill `xiangqin` (skills.sh) | `acong-tech-skills/xiangqin` GH 仓 | `git push --tags` |
| Skill `xiangqin` (ClawHub) | `clawhub.ai/acong-tech-xiangqin` | `git push --tags` |
| 服务端代码 | alpha 测试机 | 合 main 自动 |
| 服务端代码 | epsilon 生产机 | `git push --tags` 自动 chain |
| 文档站 | Cloudflare Pages | 合 main 自动 |

## 时间线

```
┌──────────────────────────────────────────────────────────┐
│ 日常开发                                                  │
│                                                           │
│  本地：改码 → uv run pytest → uv run ruff check           │
│      ↓                                                    │
│  git push main                                            │
│      ├─ ci.yml：test + lint + mkdocs + CF Pages           │
│      └─ deploy-staging.yml:                               │
│          └─ test（gate）→ rsync → alpha → restart         │
│      ↓                                                    │
│  人肉 alpha 验收：xq --endpoint http://alpha ... 跑流程    │
│      ↓                                                    │
│  OK → bump version                                        │
└──────────────────────────────────────────────────────────┘
                      ↓
┌──────────────────────────────────────────────────────────┐
│ 发布（一个 tag 触发全链路）                                │
│                                                           │
│  改 pyproject.toml / __init__.py / CHANGELOG 三处版本号   │
│  commit + push main                                       │
│      ↓                                                    │
│  git tag vX.Y.Z && git push --tags                        │
│      ↓                                                    │
│  release.yml（on tag）:                                   │
│    ├─ test（gate：pytest + ruff + format check）           │
│    │       ↓ 绿                                           │
│    ├─ publish-pypi      （uv publish）                    │
│    ├─ sync-skills-sh    （clone + cp SKILL.md + tag+push）│
│    ├─ publish-clawhub   （clawhub publish）               │
│    └─ deploy-production （needs publish-pypi）            │
│            ↓ rsync → epsilon → restart → smoke test       │
│      ↓                                                    │
│  端到端验：xq 装新版 → register 真手机号 → 跑 M4 流程      │
└──────────────────────────────────────────────────────────┘
```

**关键：tag = 全链路上线事件**。打 tag 前必须本地 pytest 绿 + alpha 验过。

## 版本号规则

SemVer：
- **patch** (`0.3.1 → 0.3.2`)：bug fix，用户无感升级
- **minor** (`0.3.x → 0.4.0`)：新功能，用户可选用；0.x 期允许 BREAKING（CHANGELOG 标）
- **major** (`0.x → 1.0.0`)：生产就绪 + 对外 API 稳定承诺

**单一版本源**：`pyproject.toml` 的 `version`。`__init__.py.__version__` / CHANGELOG 段 / git tag 都跟着它走。改版本号时 3 处一起改。

**跳号情况**：ClawHub 已发 0.4.1 作 metadata-only patch，主仓从 0.4.0 直接 bump 到 0.4.2 对齐三端。后续按 semver 正常递增。

## 子 SOP

| 场景 | 看哪 |
|---|---|
| 正常发版（alpha 验过 → tag → 全链路一键上线） | [services/publish.md](./services/publish.md) + [services/deploy.md](./services/deploy.md) |
| 紧急线上 bug | [services/hotfix.md](./services/hotfix.md) |
| 发完发现有问题 / 要回滚 | [emergency/rollback.md](./emergency/rollback.md) |
| 数据库坏了要恢复 | [services/restore.md](./services/restore.md) |

## Secrets（GitHub repo settings → Secrets）

| secret | 用途 |
|---|---|
| `PYPI_API_TOKEN` | `uv publish` 发 PyPI |
| `SKILL_REPO_DEPLOY_KEY` | push 到 `acong-tech-skills/xiangqin` 的 SSH deploy key |
| `CLAWHUB_TOKEN` | clawhub CLI 认证（`clh_xxx`） |
| `ALPHA_SSH_KEY` | deploy-staging.yml 用 |
| `ALPHA_HOST` | alpha 机器 IP |
| `EPSILON_SSH_KEY` | release.yml 的 deploy-production job 用 |
| `EPSILON_HOST` | `112.124.27.213` |
| `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` | CF Pages |

## Workflow 文件

- `.github/workflows/ci.yml` —— push/PR：test + lint + mkdocs + CF Pages
- `.github/workflows/deploy-staging.yml` —— push main：test（gate）+ rsync → alpha
- `.github/workflows/release.yml` —— push tag：test（gate）+ 并行 PyPI / skills.sh / ClawHub + chain deploy-production

## 归档

见 [archive/](archive/index.md)（暂无）。
