lovstudio Release via CI/CD
幂等、自适应的发布流程。默认自动执行 setup + publish。
默认使用 changesets，除非用户明确选择保留 semantic-release。
Step 0: 开场笑话 🎭
在开始发布前，先讲一个程序员笑话放松一下：
从以下笑话中随机选一个讲：
为什么程序员总是搞混万圣节和圣诞节？因为 Oct 31 = Dec 25
程序员最讨厌的数字是什么？2.0——因为它意味着重写
"我的代码能跑了！" "太好了，提交吧。" "等等，我先看看为什么能跑..."
产品经理：这个需求很简单。程序员：你这句话本身就很复杂。
为什么程序员喜欢暗黑模式？因为 bugs 都怕光
git commit -m "最终版" → git commit -m "最终版2" → git commit -m "这次真的是最终版"
99 个 bug 在代码里，99 个 bug～ 修掉一个，编译一下，127 个 bug 在代码里...
讲完笑话后，继续执行发布流程。
参数
无参数 → setup + publish（默认，自动模式）
setup → 仅检查/修复配置
publish → 仅执行发布
--keep-semantic-release → 保留现有 semantic-release 配置
patch|minor|major → 指定版本类型
自动模式行为
原则：除非非常不确定，否则自动执行
自动提交：有未提交更改时，自动
git add -A && git commit- 提交信息从 diff 内容推断（如 "fix: update xxx" 或 "feat: add xxx"）
- 仅当变更复杂且无法推断意图时才询问
自动版本：默认 patch，除非用户显式指定
- 首次发布（无 tag）→
0.1.0（不是 1.0.0！1.0+ 需要用户明确指定） - 当前版本
0.x.y→ 保持0.x前缀，按 patch/minor 递增 - 默认 → patch（最安全的选择）
- 用户参数
minor→ minor - 用户参数
major→ major - 用户显式指定
1.0.0或major且当前 ≥ 0.x → 才可升到 1.0+ - 检测到
BREAKING变更 → 询问用户是否使用 major
版本号哲学：0.x 表示「功能在持续演进」，1.0 表示「稳定 API 承诺」。无用户指引时永远不要自行跳到 1.0+。如果已有错误的 1.0+ tag，应提议重写（删除旧 tag/release，从 0.x 重新开始）。
- 首次发布（无 tag）→
询问条件：只有以下情况才询问用户
- 工作区有多个不相关的变更
- 变更涉及敏感文件（如 .env, secrets）
- 版本类型无法自动推断（如 refactor 可能是 patch 或 minor）
自动分支处理：如果在 feature 分支
- 自动提交当前变更
- 自动 push 到 remote
- 自动切换到 main 并 merge feature 分支
- 使用
--no-ff保留分支历史
自动 Issue 处理：从分支名/commit 检测关联 issue
- 分支名格式：
*/issue-<number>*或*/<number>-* - Commit 格式：
Closes #<number>/Fixes #<number>/Resolves #<number> - 发布成功后自动 comment + close
- 分支名格式：
Step 1: 自动检测项目
类型: Tauri (src-tauri/) | Monorepo (pnpm-workspace.yaml) | Node (package.json) | Shell (无 package.json)
目标: npm | GitHub Release | 二进制
子类型:
- Obsidian 插件 → GitHub Release Only（tag 触发，无 npm）
- Vite/前端项目 (private: true) → GitHub Release + dist.zip
发布工具:
- 检测到 semantic-release → 询问是否迁移到 changesets（推荐）
- 检测到 changesets → 继续使用
- 未配置 → 自动配置 changesets
Shell 项目：只需 workflow + tag + CHANGELOG.md
Vite/前端项目：GitHub Release + 上传 {project}-{version}.zip
所有项目类型：必须维护 CHANGELOG.md，发布前自动在顶部添加新版本变更记录，workflow 从中提取 release notes。禁止使用 generate_release_notes: true。
semantic-release 迁移检测
检测是否使用 semantic-release：
# 检查 package.json 是否有 semantic-release 相关配置
grep -q "semantic-release" package.json && echo "semantic-release detected"
# 检查 workflow 是否调用 semantic-release
grep -rq "semantic-release" .github/workflows/ && echo "workflow uses semantic-release"
如果检测到 semantic-release 且未传 --keep-semantic-release：
- 使用 AskUserQuestion 询问用户是否迁移到 changesets
- 推荐迁移（changesets 更灵活、支持 Monorepo）
- 用户同意后执行迁移（见下方「迁移步骤」）
迁移到 changesets 步骤
# 1. 初始化 changesets
pnpm add -D @changesets/cli
pnpm changeset init
# 2. 更新 .changeset/config.json
cat > .changeset/config.json << 'EOF'
{
"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
"changelog": "@changesets/cli/changelog",
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
EOF
# 3. 移除 semantic-release 配置
# - 从 package.json 删除 "release" 配置块
# - 从 devDependencies 删除 semantic-release 相关包
# 4. 更新 workflow（见下方 Workflow 模板）
Setup 阶段
检查并报告
✓/✗ .github/workflows/release.yml
✓/✗ .github/workflows/release.yml 包含 `permissions: contents: write`
✓/✗ Repo workflow permissions (write)
✓/✗ [Node] package.json (packageManager, scripts)
✓/✗ [Node] package.json 包含 packageManager 字段
✓/✗ [Node] .changeset/config.json（推荐）
⚠️ [Node] semantic-release 检测（建议迁移到 changesets）
✓/✗ [npm] NPM_TOKEN secret
✓/✗ CHANGELOG.md 存在且格式正确（## x.y.z 格式）
✓/✗ [Tauri] Cargo.toml 版本同步
✓/✗ 区域/国内镜像由独立 post-CI workflow 同步，不在主发布 DAG 中
自动修复
Repo 权限:
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
gh api "repos/${REPO}/actions/permissions/workflow" -X PUT \
-f default_workflow_permissions=write -F can_approve_pull_request_reviews=true
packageManager 字段（如缺失）:
# 按 lockfile/现有字段检测，不要强行改成 pnpm
if node -e "process.exit(require('./package.json').packageManager ? 0 : 1)" 2>/dev/null; then
node -p "require('./package.json').packageManager"
elif [ -f bun.lock ] || [ -f bun.lockb ]; then
BUN_VERSION=$(bun --version)
# 在 package.json 中添加 "packageManager": "bun@${BUN_VERSION}"
elif [ -f pnpm-lock.yaml ]; then
PNPM_VERSION=$(pnpm --version)
# 在 package.json 中添加 "packageManager": "pnpm@${PNPM_VERSION}"
elif [ -f yarn.lock ]; then
YARN_VERSION=$(yarn --version)
# 在 package.json 中添加 "packageManager": "yarn@${YARN_VERSION}"
else
NPM_VERSION=$(npm --version)
# 在 package.json 中添加 "packageManager": "npm@${NPM_VERSION}"
fi
Shell 项目 Workflow:
模板见 references/general-release-playbooks.md。Shell 项目也必须支持 workflow_dispatch，并从 CHANGELOG.md 提取 release notes。
Node 项目原则:
- 必须支持
workflow_dispatch - Tauri 用 job chaining（GITHUB_TOKEN 限制）
- npm 包需要
NPM_TOKEN - workflow 必须按
packageManager选择 bun/pnpm/yarn/npm，不要强行写死 pnpm - Bun 项目使用
oven-sh/setup-bun@v2、bun install --frozen-lockfile、bun run build - pnpm 项目使用
pnpm/action-setup@v4，不要指定 version（读取 packageManager 字段） - Tauri macOS 交叉编译需添加 Rust targets:
aarch64-apple-darwin,x86_64-apple-darwin
CHANGELOG.md 集成:
- 发布时从
CHANGELOG.md提取对应版本内容作为 release notes - Fallback: CHANGELOG.md 无内容时用 GitHub 自动生成
- 避免
generate_release_notes在多 job 重复
区域镜像必须后置
- 主发布 DAG 只负责构建、签名/公证、上传权威发布源并公开 Release。
- 国内、区域或社区镜像必须由公开 Release 之后单独调度的 post-CI workflow 同步；禁止把镜像上传放进平台构建 job，也禁止让
publish-release依赖镜像 job。 - post-CI workflow 必须按不可变 tag 从权威发布源重新下载资产，再上传镜像，确保镜像内容与已发布资产一致。
- 调度失败只输出 warning；镜像 workflow 允许独立失败和重试，不得回滚或阻塞主 Release。
- 主工作流成功后先报告权威 Release 成功，再独立监控并验证镜像状态。模板见
references/general-release-playbooks.md。
Publish 阶段
前置检查
git status --porcelain # 不干净 → 自动提交（见自动模式）
git branch --show-current # 非 main/master → 自动合并（见分支处理）
git pull --rebase
# CHANGELOG.md 检查：不存在 → 自动创建（从 git log 生成历史记录）
# 发布前必须在 CHANGELOG.md 顶部添加新版本变更记录
长 workflow 防漂移：
- 创建 release commit 和 tag 前，必须确认本轮要发布的 diff 已经全部提交。
git tag后记录RELEASE_COMMIT=$(git rev-parse HEAD)；workflow、release、验证都只对应这个 commit。- workflow 运行期间如果用户继续修改工作区，发布完成后只做
git status报告，不要把新脏改动补进已打 tag 的版本。 - 如果必须包含这些新改动，重新 bump 一个新版本；不要静默移动已发布/已公告的 tag。
自动分支合并
BRANCH=$(git branch --show-current)
MAIN_BRANCH="main" # 或 master，自动检测
# 如果不在 main 分支
if [ "$BRANCH" != "$MAIN_BRANCH" ]; then
# 1. 提交并推送当前分支
git add -A && git commit -m "<auto message>" || true
git push origin "$BRANCH"
# 2. 切换到 main 并拉取最新
git checkout "$MAIN_BRANCH"
git pull origin "$MAIN_BRANCH"
# 3. 合并 feature 分支（保留历史）
git merge "$BRANCH" --no-ff -m "Merge branch '$BRANCH' into $MAIN_BRANCH
<changeset description>
Closes #<issue_number>" # 如果检测到关联 issue
fi
自动 Issue 检测与处理
# 从分支名提取 issue 号
BRANCH=$(git branch --show-current)
ISSUE_NUM=""
# 匹配模式：issue-123, 123-feature, feature/issue-123
if [[ "$BRANCH" =~ issue-([0-9]+) ]]; then
ISSUE_NUM="${BASH_REMATCH[1]}"
elif [[ "$BRANCH" =~ ^([0-9]+)- ]]; then
ISSUE_NUM="${BASH_REMATCH[1]}"
elif [[ "$BRANCH" =~ /([0-9]+)- ]]; then
ISSUE_NUM="${BASH_REMATCH[1]}"
fi
# 从 commit message 提取（作为补充）
if [ -z "$ISSUE_NUM" ]; then
COMMITS=$(git log "$MAIN_BRANCH"..HEAD --format=%s 2>/dev/null)
ISSUE_NUM=$(echo "$COMMITS" | grep -oE '(Closes|Fixes|Resolves) #[0-9]+' | head -1 | grep -oE '[0-9]+')
fi
# 验证 issue 存在且未关闭
if [ -n "$ISSUE_NUM" ]; then
STATE=$(gh issue view "$ISSUE_NUM" --json state -q '.state' 2>/dev/null || echo "")
if [ "$STATE" = "OPEN" ]; then
echo "检测到关联 Issue #$ISSUE_NUM"
else
ISSUE_NUM="" # 忽略已关闭的 issue
fi
fi
发布后自动关闭 Issue
# 在 workflow 成功后执行
if [ -n "$ISSUE_NUM" ]; then
VERSION="v${VERSION}"
RELEASE_URL="https://github.com/${REPO}/releases/tag/${VERSION}"
# 添加评论
gh issue comment "$ISSUE_NUM" --body "已在 ${VERSION} 中修复。
Release: ${RELEASE_URL}"
# 关闭 issue
gh issue close "$ISSUE_NUM" --reason completed
echo "✓ Issue #$ISSUE_NUM 已关闭"
fi
自动提交逻辑
# 1. 检查变更
CHANGES=$(git status --porcelain)
if [ -z "$CHANGES" ]; then exit; fi
# 2. 分析变更推断提交类型
# - 修改现有文件 → fix
# - 添加新文件 → feat
# - 删除文件 → chore
# - 配置文件 → chore
# 3. 推断提交描述（从文件名/diff 内容）
# - 单文件：直接用文件名
# - 多文件同类：归纳共同点
# - 复杂变更：才询问用户
# 4. 自动提交
git add -A && git commit -m "${TYPE}: ${DESC}"
自动版本推断
# 版本类型优先级：
# 1. 用户显式参数 (patch/minor/major/具体版本号)
# 2. 检测到 BREAKING 变更 → 询问用户
# 3. 无 tag（首次发布）→ v0.1.0（不是 v1.0.0！）
# 4. 当前 0.x → 保持 0.x，按 patch/minor 递增
# 5. 默认 patch（最安全）
#
# ⚠️ 1.0+ 需要用户明确指定，绝不自行跳到 1.0+
LATEST=$(git tag -l 'v*' | sort -V | tail -1)
if [ -z "$LATEST" ]; then
NEXT="v0.1.0" # 首次发布从 0.1.0 开始
else
# 解析当前版本并递增
# 0.1.0 + patch → 0.1.1
# 0.1.1 + minor → 0.2.0
# 只有用户显式指定 major 或 1.0.0 才跳到 1.x
fi
# 检查是否有 BREAKING 变更
LAST_MSG=$(git log -1 --format=%s)
if [[ "$LAST_MSG" =~ ^BREAKING ]] || [[ "$LAST_MSG" =~ ^major: ]]; then
echo "检测到可能的 BREAKING CHANGE: $LAST_MSG"
echo "是否使用 major 版本？(y/N)"
# 使用 AskUserQuestion 工具询问
fi
VERSION_TYPE="${USER_SPECIFIED_VERSION:-patch}"
Shell 项目
# 获取最新 tag 并递增
LATEST=$(git tag -l 'v*' | sort -V | tail -1)
NEXT="v0.1.0" # 无 tag 时默认 0.1.0（不是 1.0.0！）
# 自动递增 patch（0.1.0 → 0.1.1），minor 需用户指定
git tag "$NEXT" && git push --tags
# workflow 自动触发
Node 项目
自动模式（默认）:
- 版本：从 commit 类型自动推断（见自动版本推断）
- 方式：默认
local（最快）
询问模式（仅当无法推断时）:
版本: [patch] / [minor] / [major]
方式: [local] 快速本地 | [ci] 通过 PR | [ci-auto] PR+自动合并
Local 路径（Tauri）:
# 1. 创建 changeset（如缺失）
cat > .changeset/<name>.md << 'EOF'
---
"<package>": patch
---
<description>
EOF
# 2. Bump version
pnpm changeset version # 或项目自定义的 changeset:version 脚本
git add . && git commit -m "chore: release v${VERSION}"
git push
# 3. 创建并推送 tag（workflow checkout 需要 tag 存在）
git tag v${VERSION} && git push origin v${VERSION}
# 4. 触发构建
gh workflow run release.yml -f tag=v${VERSION}
sleep 3
RUN_ID=$(gh run list -w release.yml -L 1 --json databaseId -q '.[0].databaseId')
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
echo "Workflow: https://github.com/$REPO/actions/runs/$RUN_ID"
# 5. **必须**等待 workflow 完成（指数退避轮询）
gh_view_json() {
local run_id="$1"
local json="$2"
local query="$3"
local attempt=1
while [ "$attempt" -le 5 ]; do
if gh run view "$run_id" --json "$json" -q "$query"; then
return 0
fi
sleep $((attempt * 2))
attempt=$((attempt + 1))
done
return 1
}
DELAY=5
MAX_DELAY=60
while true; do
STATUS=$(gh_view_json "$RUN_ID" status '.status') || {
echo "GitHub API 暂时不可用，下一轮继续重试..."
sleep "$DELAY"
continue
}
if [ "$STATUS" = "completed" ]; then
CONCLUSION=$(gh_view_json "$RUN_ID" conclusion '.conclusion' || echo "unknown")
echo "Workflow $CONCLUSION"
break
fi
echo "Status: $STATUS, waiting ${DELAY}s..."
sleep $DELAY
DELAY=$((DELAY * 2 > MAX_DELAY ? MAX_DELAY : DELAY * 2))
done
Local 路径（纯 Node）:
pnpm build && pnpm changeset publish
git push --follow-tags
NOTES=$(awk -v ver="${VERSION}" '/^## / { if (found) exit; if ($2 == ver) { found=1; next } } found { print }' CHANGELOG.md)
gh release create "v${VERSION}" --notes "${NOTES:-Release v${VERSION}}" --latest
CI 路径:
git add -A && git commit -m "chore: add changeset" && git push
# 等待 Version Packages PR
gh pr merge ... --squash --delete-branch # ci-auto
References
- Tauri/macOS signing/notarization/Windows fallback:
references/tauri-release-workflow.md - Shell, Vite, monorepo templates, post-release mirror separation, workflow monitoring, README/Vercel audits, issue automation, and failure recovery:
references/general-release-playbooks.md
When a referenced template conflicts with this SKILL.md, follow the stricter rule: maintain CHANGELOG.md, preserve package manager choice, do not print secrets, wait for workflow completion with retry, and verify final release assets before reporting success.