release

Release Command

功能说明

执行标准化的版本发布流程，包括 SNAPSHOT 版本替换、创建 Release commit 和 Tag、创建发布分支、以及准备下一个 SNAPSHOT 版本。

不含构建验证：仅做版本号替换和 Git 操作。 不含自动推送：仅做本地操作，推送由用户手动完成。

用法

/release <version>

例如：

/release 1.2.3

参数说明

• <version>: 发布版本号，格式为 X.Y.Z（必需），例如 1.2.3

参数来源：$ARGUMENTS

执行步骤

步骤 1：解析并验证参数

从 $ARGUMENTS 中提取版本号。

版本号格式验证：

• 必须匹配 X.Y.Z 格式（X、Y、Z 均为非负整数）
• 如果格式不正确，报错退出：错误：版本号格式不正确，期望格式为 X.Y.Z（例如 1.2.3）

解析版本组件：

• 主版本号 MAJOR = X
• 次版本号 MINOR = Y
• 修订版本号 PATCH = Z
• 下一修订版本号 NEXT_PATCH = Z + 1
• SNAPSHOT 版本 = X.Y.Z-SNAPSHOT
• 发布版本 = X.Y.Z
• 下一 SNAPSHOT 版本 = X.Y.(Z+1)-SNAPSHOT

确认 SNAPSHOT 存在：

使用 Grep 搜索 X.Y.Z-SNAPSHOT：

Grep(pattern="X.Y.Z-SNAPSHOT")

• 如果没有找到任何匹配，报错退出：错误：未找到 X.Y.Z-SNAPSHOT，请确认当前代码版本是否正确
• 如果找到匹配，列出所有包含 SNAPSHOT 的文件，告知用户即将替换的范围

步骤 2：确认工作区状态

git status --short

• 如果有未提交的更改，报错退出：错误：工作区有未提交的更改，请先提交或暂存（git stash）后再执行发布
• 工作区必须是干净的才能继续

步骤 3：全局替换 SNAPSHOT → Release

使用 Grep 搜索所有包含 X.Y.Z-SNAPSHOT 的文件：

Grep(pattern="X.Y.Z-SNAPSHOT")

对于每个匹配的文件，使用 Edit 工具将 X.Y.Z-SNAPSHOT 替换为 X.Y.Z：

Edit(
  file_path="<matched-file>",
  old_string="X.Y.Z-SNAPSHOT",
  new_string="X.Y.Z",
  replace_all=true
)

覆盖的文件范围（由 Grep 全局搜索决定，包括但不限于）：

• **/pom.xml — Maven 版本号和 <fit.version> 属性
• README.md — 版本标题
• docs/**/*.md — 文档中的版本引用
• *.java — 源码中硬编码的版本字符串
• *.js — fit.js 中的 VERSION 常量
• package.json — Node.js 版本号

必须排除的目录（这些目录包含 AI 工具配置、命令模板和示例，不应被版本替换影响）：

• .agents/
• .ai-workspace/
• .claude/
• .codex/
• .gemini/
• .opencode/

替换后验证：

Grep(pattern="X.Y.Z-SNAPSHOT")

确认没有残留的 X.Y.Z-SNAPSHOT。如果仍有残留，继续替换直到全部清除。

步骤 4：创建 Release commit

git add -A && git commit -m "Release X.Y.Z"

步骤 5：创建轻量标签

git tag vX.Y.Z

步骤 6：创建发布分支

git branch release-X.Y.Z

步骤 7：回退当前分支到 Release commit 之前

Release commit 和 tag 已经通过 release-X.Y.Z 分支保留，现在需要将当前开发分支回退到 Release commit 之前的状态，使下一个 SNAPSHOT commit 与 Release commit 成为兄弟关系（共享同一个父节点），而非父子关系。