.agents/skills/prepare-release/SKILL.md
Automate the Cherry Studio release workflow: collect changes → generate bilingual release notes → update files → create release branch → trigger CI/CD.
Parse the version intent from the user's message. Accept any of these forms:
patch, minor, majorx.y.z or x.y.z-<prerelease> without build metadata (e.g. 1.8.0, 1.8.0-beta.1, 1.8.0-rc.1)Defaults to patch if no version is specified. Always echo the resolved target version back to the user before proceeding with any file edits.
--dry-run: Preview only, do not create a release branch.origin/main and all tags, then verify that the checkout is a clean main at exactly origin/main:
git fetch origin refs/heads/main:refs/remotes/origin/main --tags
test "$(git branch --show-current)" = main
test -z "$(git status --porcelain)"
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
origin/main head.package.json. Post Release keeps this synchronized with the last published release.v{current-version} and verify that it exists:
git rev-parse --verify refs/tags/v{current-version}
v<semver>; non-semver preview releases are never a release baseline:
gh release list --limit 1000 --json isDraft,publishedAt,tagName --jq '[.[] | select(.isDraft == false and (.tagName | test("^v(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$")))] | sort_by(.publishedAt) | last | .tagName // empty'
main before another release is prepared.patch / minor / major: bump from the current version.^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ and pass semver.valid; build metadata such as +build.1 is not accepted.HEAD, use the tag.release-metadata-boundary: <baseline-tag>. This machine marker is added to the Post Release pull request body and survives the required squash merge.chore(release): sync <baseline-tag> metadata or that subject followed only by GitHub's squash suffix (#<PR-number>).git log <collection-base>..HEAD --format="%H %s" --no-merges
git log <hash> -1 --format="%B"
```release-note code blocks from each commit body.feat, fix, refactor, perf, docs, etc.).🤖 Daily Auto I18NMergechore(deps)chore: releasechore(release)NONEUsing the collected commit information, generate release notes in both English and Chinese.
Recommended format:
<!--LANG:en-->
Cherry Studio {version} - {Brief English Title}
✨ New Features
- [Component] Description
🐛 Bug Fixes
- [Component] Description
💄 Improvements
- [Component] Description
⚡ Performance
- [Component] Description
<!--LANG:zh-CN-->
Cherry Studio {version} - {简短中文标题}
✨ 新功能
- [组件] 描述
🐛 问题修复
- [组件] 描述
💄 改进
- [组件] 描述
⚡ 性能优化
- [组件] 描述
<!--LANG:END-->
The language markers are the machine-readable contract: include each marker once, keep them in order, and provide non-empty English and Chinese sections. Titles and surrounding explanatory text are presentation choices, not validation requirements.
Rules:
release-note field if present; otherwise summarize from the commit title.[Chat], [Models], [Agent], [MCP], [Settings], [Data], [Build], etc.electron-builder.yml as a style reference before writing.IMPORTANT: User-Focused Content Only
Release notes are for end users, not developers. Exclude anything users don't care about:
INCLUDE only changes that users will notice:
Keep descriptions simple and non-technical:
package.json: Update the "version" field to the new version.electron-builder.yml: Replace the content under releaseInfo.releaseNotes: | with the generated notes. Preserve the 4-space YAML indentation for the block scalar content.resources/cherry-studio/release-history.json: Never edit by hand; the notes must match electron-builder.yml byte for byte. Run node scripts/release/sync-release-history.js --target-version {version}, which prepends (or replaces) the entry for a stable release and leaves the file untouched for a prerelease. In GitHub Actions, the workflow runs this itself after the Claude step.node scripts/release/validate-prepared-release.js --target-version {version} before generating the product manifest, and stop if it rejects the changed paths, version ordering, bilingual sections, or stable history. In GitHub Actions, leave validation to the workflow step that runs after Claude.pnpm build:builtin-knowledge after validation. This refreshes resources/builtin-agents/cherry-assistant/product-manifest.json with the new package version. Never edit the generated manifest by hand. In GitHub Actions, do not run the generator: the workflow runs the same validator first, then runs the trusted generator itself.Show the user:
If --dry-run was specified, stop here.
Otherwise, ask the user to confirm before proceeding to Step 6.
git status --short and stop unless every listed path is one of the four allowed release metadata files. Then create and push a signed, DCO-compliant release commit:
git fetch origin refs/heads/main:refs/remotes/origin/main --tags
test "$(git branch --show-current)" = main
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
test "$(node -p "require('./package.json').version")" = "{version}"
BASELINE_VERSION="$(git show HEAD:package.json | jq -r .version)"
BASELINE_TAG="v$BASELINE_VERSION"
git rev-parse --verify "refs/tags/$BASELINE_TAG"
LATEST_PUBLISHED="$(gh release list --limit 1000 --json isDraft,publishedAt,tagName --jq '[.[] | select(.isDraft == false and (.tagName | test("^v(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$")))] | sort_by(.publishedAt) | last | .tagName // empty')"
test "$LATEST_PUBLISHED" = "$BASELINE_TAG"
REPO="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
gh api --paginate --slurp "repos/$REPO/releases?per_page=100" | TAG="v{version}" node scripts/release/validate-release-state.js prepare
test -z "$(git ls-remote --heads origin refs/heads/release/v{version})"
git status --short
UNEXPECTED_RELEASE_PATHS="$(git status --porcelain | cut -c4- | grep -Ev '^(package\.json|electron-builder\.yml|resources/cherry-studio/release-history\.json|resources/builtin-agents/cherry-assistant/product-manifest\.json)$' || true)"
test -z "$UNEXPECTED_RELEASE_PATHS"
git checkout -b release/v{version}
git add package.json electron-builder.yml resources/cherry-studio/release-history.json resources/builtin-agents/cherry-assistant/product-manifest.json
git commit -S --signoff -m "chore(release): prepare v{version}"
git cat-file commit HEAD | grep -q '^gpgsig '
git log -1 --format=%B | grep -q '^Signed-off-by: '
git push -u origin release/v{version}
package.json and electron-builder.yml. Temporary helper files and local Git operations are allowed; the workflow extracts those two file changes, restores the frozen source SHA, and discards everything else. It then derives the release history, validates, generates the product manifest, creates the branch, and uses GitHub's API to create and verify the signed, DCO-compliant commit. Never push from the Claude step.release/v{version} commit to succeed. auto-release-build.yml revalidates that exact live branch head and dispatches release.yml with all; it builds macOS, Windows, and Linux and creates or updates the draft GitHub Release. Use release.yml manually only to retry a failed all-platform build or one platform for the unchanged tagged commit.backport-release-fixes.yml opens a backport PR for the first merged hotfix: <description> or hotfix(<kebab-case-scope>): <description> PR from main, applies any optional bilingual release note, then appends consecutive hotfixes and source markers to that same open topic branch. It manages every source PR's hotfix and backport-status labels and reports failures on the source PR; never merge main into the release branch.publish-release.yml. Approve the release Environment deployment after inspecting the draft. Publication then acquires the release-state lock, revalidates the approved run, release branch, tag, draft, artifacts, open PRs, and pending hotfixes, and publishes only if they still agree. The draft body contains the bilingual electron-builder.yml notes followed by GitHub's generated changes. The final fetched main SHA is the hotfix cutoff; a hotfix merged after that snapshot belongs to the next release. Publication triggers post-release.yml, which uses the published tag as its source, applies only the release metadata delta to the latest main, and creates a release-sync/v{version} metadata-only PR.package.json, electron-builder.yml, release history, and the generated product manifest. It triggers ci.yml; merge it only after CI passes.chore(release): sync v{version} metadata with only GitHub's optional PR-number suffix, and keep release-metadata-boundary: v{version} on its own line in the squash commit body so the next release can find the boundary reliably.electron-builder.yml before modifying it to understand the current format.package.json, electron-builder.yml, resources/cherry-studio/release-history.json, and the generated resources/builtin-agents/cherry-assistant/product-manifest.json.main.post-release.yml owns that step.