| name | releasing-easiauto |
| description | Use when the user asks to publish a new EasiAuto version, create a release, bump the version, or prepare a changelog. Triggers on requests like "发布新版本", "release v1.2.3", "准备发版", or "写更新日志". |
EasiAuto 发版
概述
自动化 EasiAuto 版本发布流程：修改版本元数据 → 总结更新日志 → 推断元数据 → 用户审核 → 使用发行中心发布。
何时使用
- 用户说"发版""发布新版本""release"
- 用户提供了目标版本号并要求发布
- 用户要求准备更新日志
不使用于：仅修改代码不涉及发布、仅查看当前版本号。
流程
Step 0: 确保工作树干净且与远端同步
发版前必须确保工作树无未提交的更改，且本地与远端同步。
git status --short
git fetch origin
git log HEAD..origin/$(git branch --show-current) --oneline
- 工作树有未提交更改 → 先处理（提交或暂存）
- 远端有新提交 → 告知用户，让用户自行处理（pull/rebase），不要在发版流程中自动合并
- 两项检查均通过 → 继续发版
Step 1: 修改版本元数据并提交
- 用户输入目标版本号（若未提供，先询问）
- 同时修改两个文件中的版本号：
src/EasiAuto/__init__.py：__version__ = "<新版本>"pyproject.toml：[project] 下的 version = "<新版本>"
- 运行
uv sync 确保锁定文件同步
- 提交版本升级并推送：
git add src/EasiAuto/__init__.py pyproject.toml uv.lock
git commit -m "upgrade: <新版本>"
git push
Step 2: 总结更新日志
找到上次发版的 git tag：
git tag --sort=-v:refname | head -1
获取从上个 tag 到 HEAD 的 commits：
git log <上个tag>..HEAD --oneline --no-merges
为亮点功能查看代码
亮点功能需要准确的用户感知描述，仅凭 commit message 往往不够。对每个可能成为亮点的 feat: commit：
git show <commit_hash> --stat
git show <commit_hash> --no-stat
看完 diff 后，必须进一步阅读改动的完整文件——diff 只展示片段，完整文件才能理解功能的真实面貌：
- 打开每个改动的源文件，了解完整上下文
- 重点关注 diff 涉及区域周围的代码：上下游逻辑、UI 布局、条件分支
- 对于新增文件，必须全文阅读
重点关注：
- 新增的 UI 组件 / 页面 → 描述其用途和交互
- 新增的用户可操作功能 → 描述操作路径和效果
- 新的自动化能力 → 描述触发条件和结果
- 配置项变更 → 描述新增了什么可配置项
根据代码中的注释、UI 文本、日志消息来提炼功能描述，确保描述精确实质而非泛泛而谈。
内容筛选规则
| 规则 | 说明 |
|---|
| 合并同类 | 多个 commit 实现同一功能 → 合为一条 |
| 忽略内部修复 | bug fix 修复的是本版本引入的问题（tag 之后的）→ 忽略 |
| 忽略技术性更改 | refactor、style、chore、ci、docs 一般不提及，除非改动幅度大（如"重构通知服务"） |
| 提取用户感知 | 从 feat:、fix:、build: 等前缀中提取用户可感知的变化 |
识别同一功能的方法：
- 多个 commit 的
feat: 描述指向同一功能模块（如"隐私保护遮罩"）
- 一个 commit 实现组件，另一个 commit 集成它 → 合并
- 若不确认是否应合并，倾向于分开列出，让用户审核时决定
输出格式
直接输出 JSON，字段与发版工具 update-manifest 的 --desc、--highlights、--others 参数一一对应：
{
"desc": "<概括本版本的主要更改，或特别注意事项。非必填，可留空字符串。>",
"highlights": [
{"name": "<名称>", "description": "<一句话概括功能>"}
],
"others": [
"新增 <功能>",
"优化 <改进>",
"修复 <问题>"
]
}
others 中每条以类型前缀开头：新增 / 优化 / 修复 / 调整 / 移除/ 重构 / 其他highlights 为功能亮点，与 others 互不重复
示例：
{
"desc": "此版本引入了隐私保护、二维码登录等多项新功能，并修复了档案校验时机错误的问题。",
"highlights": [
{"name": "登录状态浮窗", "description": "一目了然地显示当前登录任务执行状态，同时支持打断登录"},
{"name": "隐私保护遮罩", "description": "登录时自动覆盖桌面敏感信息，防止被录屏或投屏泄露"}
],
"others": [
"新增 远程公告",
"新增 二维码登录",
"优化 构建脚本与发版工具",
"修复 档案校验时机错误"
]
}
此 JSON 可直接传入发版 CLI
Step 3: 推断元数据
| 条件 | confirm_required |
|---|
| 存在破坏性更新（如移除功能、不兼容的 API 变更） | true |
| 其他情况 | false |
| 条件 | push_to_beta |
|---|
| is_dev = true | 不适用（置为 false） |
| 正式版，用户未指定 | false（让用户审核时决定） |
推断完成后，明确告知用户每项元数据的值和推断依据。
Step 4: 用户审核
将审核内容写入一个 Markdown 文件，用外部编辑器打开供用户直接修改。保存并关闭即为审核完成。
-
将以下内容整理为清晰格式，写入到项目根目录下的 CHANGELOG_REVIEW.md：
- 目标版本号
- 元数据（is_dev、confirm_required、push_to_beta）
- 完整的更新日志（说明 + 亮点 + 其他更新）
文件模板：
# EasiAuto 发版审核
> 请直接修改以下内容。保存并关闭此文件即视为审核通过。
## 版本号
<目标版本号>
## 元数据
- **is_dev**: (default)
- **confirm_required**: <true/false>
- **push_to_beta**: <true/false>
## 更新日志
### 说明
<版本说明，可留空>
### 亮点功能
- **<名称>**：<一句话概括>
- ...
### 其他更新
- 新增 ...
- 优化 ...
- 修复 ...
-
打开编辑器并等待关闭：
code --wait CHANGELOG_REVIEW.md
该命令会阻塞直到用户在 VS Code 中关闭该文件标签页。保存后关闭即为审核通过。
若 code 不可用（未安装或不在 PATH），降级为手动确认：改用 start CHANGELOG_REVIEW.md 打开文件，然后提示用户**修改并保存文件后，输入"完成"或"审核通过"**继续。
-
编辑器关闭后，从 CHANGELOG_REVIEW.md 中重新解析用户可能修改的内容，作为最终审核结果。
-
审核完成后，删除 CHANGELOG_REVIEW.md 临时文件。
Step 5: 发布
审核通过后，使用 dist-center release CLI 命令执行构建并发布 Release。
若用户显式指定了 is_dev，则加入 --is_dev / --is-dev=no 控制该版本为预发布。
uv run dist-center release \
--version "<版本>" \
--build-first \
--build-full --build-lite \
--desc "<说明>" \
--highlights '<亮点JSON数组>' \
--others '<其他JSON数组>'
版本号规范
遵循 PEP 440。EasiAuto 使用的段类型，按排序从低到高：
| 阶段 | 格式 | 示例 | is_dev |
|---|
| 开发版 | X.Y.Z.devN | 1.2.0.dev1 | true |
| Alpha | X.Y.ZaN | 1.2.0a1 | true |
| Beta | X.Y.ZbN | 1.2.0b1 | true |
| RC | X.Y.ZrcN | 1.2.0rc1 | true |
| 正式版 | X.Y.Z | 1.2.1 | false |
| 发布后修订 | X.Y.Z.postN 或 X.Y.ZrN | 1.1.4r1 | false |
rN 是 postN / revN 的别名，排序在正式版之后，属稳定版本。
参考
- 发行中心源码：
tools/distribution_center/
- 主程序版本定义：
src/EasiAuto/__init__.py
- 项目配置：
pyproject.toml
