---
description: 发版工作流：根据变更类型决定版本号，更新所有版本文件和 changelog，运行验证，commit 并 push
argument-hint: 可选：feature | bugfix | 或直接描述本次发布内容
allowed-tools: ["Read", "Edit", "Bash", "Glob", "Grep"]
---

# /release — Planet 发版工作流

## 版本号规则

| 变更类型 | 版本跳动 | 适用场景 |
|---------|---------|---------|
| `feature` | `+0.1.0` | 纯新功能，无 bugfix |
| `improvement` | `+0.0.1` | UI 调整、小功能增强、bugfix 混合，或以 UI/体验改进为主的迭代 |
| `bugfix` | `+0.0.1` | 纯 bug 修复，无新功能 |
| `docs` / `maintenance` / `refactor` | 默认不发版，除非用户明确要求 |

意图混合时以用户明确描述为准；bugfix + 小 feature 混合默认判定为 `improvement`（`+0.0.1`）。

## 必须同步更新的文件

使用 `git rev-parse --show-toplevel` 获取仓库根目录，以下路径均相对于根目录：

- `VERSION`
- `frontend/package.json`（`"version"` 字段）
- `pyproject.toml`（`version =` 字段）
- `uv.lock`（**不要手动编辑**，通过 `uv lock` 重新生成）
- `docs/CHANGELOG.md`
- `docs/version-history.md`

## 节省上下文规则

发版判断应以确定性 CLI 证据为主，优先使用紧凑命令和定点读取：

```bash
git status --short
git diff --stat HEAD
git diff --name-only HEAD
rg -n "version|^## |^Released:|当前开发版本|current" VERSION frontend/package.json pyproject.toml docs/CHANGELOG.md docs/version-history.md
```

除非需要判断某个代码变更是否属于本次发版，否则不要读取完整 diff。

## 执行步骤

### Step 1 — 环境检查

```bash
git branch --show-current          # 确认在 dev 分支
git status --short                 # 检查是否有无关的未暂存修改
cat VERSION                        # 读取当前版本
```

若当前**不在 `dev` 分支**，停下来告知用户，不要继续。

若存在无关的未暂存修改，列出并询问用户是否一并提交，或先 stash。

### Step 2 — 确定发版类型与新版本号

- 若 `$ARGUMENTS` 提供了明确类型（`feature` / `bugfix`），直接使用
- 否则根据 `git diff --stat HEAD`、`git diff --name-only HEAD`、必要的 focused diff 和 `git log` 推断
- 计算新版本号（例：`0.26.2` → bugfix → `0.26.3`）
- **先输出发版计划供用户确认**：

```
发版计划：
  类型：bugfix
  版本：0.26.2 → 0.26.3
  分支：dev
  将更新：VERSION, frontend/package.json, pyproject.toml, uv.lock, CHANGELOG.md, version-history.md
```

### Step 3 — 更新版本号文件

按顺序更新（每步用 Edit 工具，精确替换，不要重写整个文件）：

1. `VERSION` — 直接替换全部内容为新版本号
2. `frontend/package.json` — 替换 `"version": "x.x.x"` 行
3. `pyproject.toml` — 替换 `version = "x.x.x"` 行
4. 运行 `uv lock` 重新生成 `uv.lock`（在仓库根目录下执行）

### Step 4 — 更新 CHANGELOG.md

在文件顶部插入新条目，格式：

```markdown
## [x.x.x] — YYYY-MM-DD

### ✨ Features / 🐛 Fixes / 🔧 Improvements
- ...（只列高信号条目，最多 5 条）
- ...

---
```

日期使用 `date +%Y-%m-%d` 获取今天的日期。

### Step 5 — 更新 docs/version-history.md

- 更新文件头部的"当前开发版本"字段
- 在时间线表格顶部插入新行：`| vx.x.x | YYYY-MM-DD | 一句话摘要 |`

### Step 6 — 验证

针对本次变更范围做最小验证：

- Python 文件有修改：先用 `git diff --name-only HEAD -- '*.py'` 列出，再运行 `python3 -m py_compile <changed_files>`
- Frontend 文件有修改：先用 `git diff --name-only HEAD -- frontend` 判断范围，再运行项目标准检查（若无则跳过并说明）
- 版本号一致性检查：用 grep 确认 VERSION、package.json、pyproject.toml 中的版本号完全一致

```bash
cat VERSION
rg -n "\"version\":|^version =|version = " frontend/package.json pyproject.toml uv.lock
```

### Step 7 — 提交前预览

展示将要提交的文件列表：

```bash
git diff --stat HEAD
```

再次确认所有必须文件都在变更列表中，**不包含**非预期文件（如调试文件、.env 等）。

### Step 8 — Commit & Push（用户确认后）

```bash
git add VERSION frontend/package.json pyproject.toml uv.lock docs/CHANGELOG.md docs/version-history.md
# 若有代码变更也一并 stage
git add <code_files>

git commit -m "release: bump version to x.x.x"
git tag vx.x.x
git push origin dev
git push origin vx.x.x
```

commit message 固定格式：`release: bump version to x.x.x`

### Step 9 — 完成确认

输出摘要：

```
✓ 版本号已更新：0.26.2 → 0.26.3
✓ CHANGELOG 已更新
✓ version-history 已更新
✓ uv.lock 已重新生成
✓ 验证通过
✓ commit: release: bump version to 0.26.3
✓ tag: v0.26.3
✓ 已 push 到 origin/dev
```

## 注意事项

- `uv.lock` 只能通过 `uv lock` 生成，绝不手动编辑
- 发版 commit 只包含版本文件 + 本次功能代码，不混入无关改动
- 若环境中 `uv` 不可用，说明原因并跳过 lockfile 更新，提醒用户手动运行