本仓库发版路径（本节优先于正文）

• 本仓库无 .git、无 CI、无 gh，正文里的 tag push / gh release create / Xposed 仓库步骤在本仓库不执行；scripts/release-exec.sh 仅在带 git 的上游克隆里有效。
• 实际出包：改 app/build.gradle.kts 的 versionCode → sh project/sync.sh zafiro-15-1.8.1-Fork → cd /data/local/aitools && ZAFIRO_VARIANT=debug sh env.sh build --max-workers=1（VARIANT 必填，默认 release 而 app 无该变体）。
• 校验：日志出现 RC=0 + size: + md5:；产物落 /data/local/aitools/out/。
• 装包前必须先输出摘要（改动文件表 + versionCode + size + md5），再 pm install -r -d。
• 文案：README.md / README_CN.md 的「当前能力」与「设计取舍」两节；
• 正文 Phase 1–3（版本号决策、文案格式、pitfalls、hard rules）仍然适用。

Release New Version

Release workflow for Forge.

Repos involved:

One APK, two notes. CI builds and signs the APK and creates the Release when a tag is pushed to the main repo. There is no CI in the Xposed repo — its release is a manual gh operation. Never build locally.

Phase 1 — Gather facts

Collect all of this before asking the user anything:

1. Local version: read versionCode / versionName from app/build.gradle.kts.
2. Latest release baseline: gh release view -R niki914/zafiro (returns the latest non-draft, non-prerelease release by default). Parse its tag v<code>-<name>.
3. Version string locations: find every place the current version literal lives:

   rg -n '<current versionName>' -g '*.{md,kt,kts,txt,py}' .

   Only scan these extensions: md, kt, kts, txt, py. Nothing else. rg respects .gitignore by default — do not disable that.
4. Changes since last release: commits and merged PRs from the last release tag to origin/main:

   git log v<code>-<name>..origin/main --oneline --no-merges
   gh pr list -R niki914/zafiro --state merged --limit 50 --json number,title --jq '.[] | "\(.number) \(.title)"'

5. If local versionCode/versionName do not match the latest release tag: stop and ask the user how to proceed. Do not guess.

Summarize the changes for the user in plain language before drafting.

Phase 2 — Draft release notes (iterate until explicit approval)

Write bilingual notes (Chinese first, ---, then English) from the change list. Apply these rules strictly — they are derived from every historical release:

1. Only user-perceivable changes. New features, visible improvements, refactors with user-facing impact. Never list chores, CI fixes, string cleanups, dependency bumps, internal renames.
2. Bug fixes are always vague. Collapse all fixes into one line: "修复了一些问题" / "Fixed several issues". Optionally append one phrase naming the improved area (e.g. "优化了 Phone Use 执行效率"). Never enumerate specific bugs.
3. 4–8 numbered entries. Feature names are brand terms (Phone Use, Skills System) — keep them consistent with past usage.
4. Breaking changes get a blockquote before the list, in both languages, telling users what to do (e.g. the 1.1.0 package-name rename note told users to set up the new version as a fresh start).
5. Milestone items (e.g. "仓库已开源，欢迎 Star、提 Issue、参与贡献") go as the final entry when applicable.

Present the draft. The user will revise it — redraft and repeat until the user explicitly approves. Approval is an explicit statement from the user, not silence.

Few-shot (real entries from past releases):

• Good feature entry: 1. 新增 Phone Use：支持自动点按、滑动、滚动、输入文字、打开 App
• Good vague fix entry: 7. 修复了一些问题
• Bad entry (do not write): 修复了 composer 光标在深色主题下的偏移 — too specific; fold into "修复了一些问题"
• Bad entry (do not write): chore: remove 13 unreferenced UI strings — not user-perceivable, drop entirely

Phase 3 — Propose version number (iterate until explicit approval)

Semver x.y.z:

• Pump X — proud version: milestone, rebranding, headline feature, open-source moment.
• Pump Y — normal update: regular features.
• Pump Z — shamed version: fixing a severe/P0 bug.

Propose one number with a one-line justification referencing the change list. Also report every location found in Phase 1 step 3 that needs the version string updated. Iterate with the user until explicit approval of both the number and the file list.

Phase 4 — Execute

Confirm once more before anything irreversible (exact version number, tag, target commit, and whether to publish to Xposed).

Save the approved release notes into a temporary file (e.g. /tmp/zafiro-release-notes.md).

Automated Execution (Preferred)

Run the release execution script from repo root:

# Main repo only:
bash .agents/skills/release-new-version/scripts/release-exec.sh <new code> <new name> /tmp/zafiro-release-notes.md

# Main repo + Xposed repo:
bash .agents/skills/release-new-version/scripts/release-exec.sh <new code> <new name> /tmp/zafiro-release-notes.md --xposed

The script automates:

1. Re-counting code lines badge (update-code-badge.sh).
2. Updating versionCode and versionName in app/build.gradle.kts.
3. Committing release: bump to <new name> and pushing to origin main.
4. Creating tag v<code>-<name> and pushing to origin.
5. Waiting for GitHub Actions release build CI to succeed (gh run watch).
6. Updating the GitHub Release title to Release - <name> and replacing CI notes with approved bilingual notes.
7. If --xposed is given: downloading APK, generating Xposed notes (with open-source links), and creating the Xposed release with --latest on Xposed-Modules-Repo/com.niki914.zafiro.

Manual Fallback Steps

If running manually without the script:

1. Update the code-line badge so it lands in the release commit:

   bash .agents/skills/release-new-version/scripts/update-code-badge.sh

2. Update versionCode = <new code>, versionName = "<new name>" in app/build.gradle.kts.
3. Update module structure in both READMEs (README.md and README_CN.md) and AGENTS.md if applicable.
4. Audit and complete multilingual string parity across all modules.
5. Commit: release: bump to <new name>, push to origin main.
6. Tag and push:

   git tag v<code>-<name>
   git push origin v<code>-<name>

7. Wait for CI:

   gh run watch <run-id> -R niki914/zafiro --exit-status

8. Replace CI notes:

   gh release edit v<code>-<name> -R niki914/zafiro --title "Release - <name>" --notes "<approved notes>"

9. (Optional) Xposed repo:

   gh release download v<code>-<name> -R niki914/zafiro -p "*.apk" --dir /tmp/
   gh release create <code>-<name> /tmp/*.apk -R Xposed-Modules-Repo/com.niki914.zafiro --title "Release - <name>" --notes "<approved notes>" --latest

Release notes format

Historical releases follow this format strictly (no deviations):

• English first, Chinese after, separated by a single --- line. Never reverse the order.
• No language headers (no **English** / **中文** labels) — the notes start directly with the numbered list. Blank line separates the --- from the lists.
• The --title "Release - <name>" is part of the format, not optional. Set the title via --title, never inside the release note body.

Phase 5 — Xposed repo (optional, ask first)

Ask: "这次要发 Xposed 仓库吗？" If yes, pass --xposed to release-exec.sh or run step 9 manually. If no, run without --xposed and state clearly "本次未发 Xposed 仓库".

Known pitfalls

• CI build failure: Aliyun Maven mirror 502. Overseas GitHub Actions runners intermittently fail on the Aliyun mirror if it is ordered before mavenCentral() / gradlePluginPortal() in settings.gradle.kts. Standard sources go first, Aliyun after. If CI fails on dependency resolution, check the mirror order.
• Tag already exists / CI failed and needs a re-trigger. The same tag cannot be pushed twice:

  git push origin :v<code>-<name>   # delete remote tag
  git tag -d v<code>-<name>         # delete local tag
  git tag v<code>-<name>            # re-tag at latest commit
  git push origin v<code>-<name>

Hard rules

• Never build locally. CI builds everything.
• Never modify versionName without explicit user approval.
• Never push a tag without showing the user the exact tag and target commit first.
• If any state is ambiguous (local ≠ remote, tag exists, CI red), stop and ask.