| name | pallas-release |
| description | 当维护者说「发版」「release」「更新公告」「错开发版」「要发 Bot/WebUI 了」时，优先读取本 SKILL。 处理 Pallas-Bot 主仓与 Pallas-Bot-WebUI 的发版（更新公告、chore(release)、dev→main PR、Auto Tag Release 与 Release 工作流出包）。 本 SKILL 是发版流程的唯一权威来源；旧 ~/.cursor/rules/pallas-release.mdc 已精简为指针。
|
Pallas 发版（Agent 入口）
本 Skill 描述 Pallas-Bot 与 Pallas-Bot-WebUI 的发版流程。维护者说「发版 / release」时读取并遵守。
本文是发版流程的权威来源；历史规则 ~/.cursor/rules/pallas-release.mdc 仅留指针，不再双源维护。
人类维护者的发布说明见 pallas-release（如有）。
何时触发
- 维护者说「发版准备」「release」「错开发版」「Bot/WebUI 该发了」。
- 默认 patch；WebUI 要 minor/major 时给合入
main 的 PR 打 bump:minor / bump:major。
发版前必读：摸清本版内容（决定公告质量）
发版前先完整梳理本版带了什么，再动笔写公告：
- 本版功能/修复：
git log origin/main..dev --oneline（Bot/WebUI 各自仓内跑），逐条看有没有 feat / fix / 行为变化；feature 分支已合入哪些。
- 新配置项（写公告必须点名，尤其面向用户的开关）：
- 新增环境变量：搜
os.getenv(、env_、REDIS_URL 等模式，或对照 config/pallas.example.toml 与 docs/；
- 新增 WebUI 可调项 / config 段：搜
install_hot_reload_config、env_sections.py、webui.json 相关；
- 新默认值/行为变化（如开关默认关闭、限额默认值）要写清楚开启方式。
- CHANGELOG 里的「提前备忘」：维护者可能提前在
Unreleased / 顶部写入备忘说明（新配置、新功能、已知限制），这些是要整理进更新公告的材料，不是重复的内部 commit 明细。
- 两端配套：Bot 是否捆绑 WebUI（
dist.zip）；本轮 WebUI 是否一并发版；WebUI manifest 声明的 Bot commit 是否可达。
- 错开发版：若维护者要求 Bot 与 WebUI 错开/间隔发版，各自按本流程单独走，版本各自独立，互不绑定。
分支与合入顺序
- 发版 PR：
dev → main。
- WebUI 与 Bot 可以独立发版；Bot Release 从 WebUI tag 中自动选择与当前 Bot commit 兼容的最新
v*，也可手动指定 webui_tag。
- WebUI：合入
main 后由 Release 自动递增版本并打 v* tag（release.yml 监听 PR merged 到 main 或 push v* tag / workflow_dispatch 触发；PR 合入时默认 patch 递增 package.json 并打 tag）。WebUI 的 chore(release) 提交本身不触发打 tag，由 Release 工作流在合并后处理。
- Bot：合入
main 后由 Auto Tag Release 工作流（auto-tag-release.yml）检测 push 到 main 的 HEAD 提交是否为 chore(release): vX.Y.Z（squash 合入时 HEAD 即发版提交；merge commit 时取 HEAD^2=dev tip；main 直发 HEAD 即发版提交同样命中），命中即自动打 vX.Y.Z tag 并触发 Release（出 GitHub Release / 捆绑兼容的 dist.zip / Docker）与 publish-pypi-core（发布 pallas-core 到 PyPI）。未命中（HEAD 非发版提交、或 tag 已存在）则跳过；需要补发时对 Release 工作流 workflow_dispatch，传入 version=vX.Y.Z（可选 webui_tag=v…），PyPI 则对 publish-pypi-core workflow_dispatch。勿空等 auto-tag。
- 开 Bot 发版 PR 前：本地
dev 先快进 / 对齐 origin/main（避免 dev 落后于 main 的纯文档/合入提交漏在 PR 外或把无关 diff 搅进来），再叠本版功能与发版提交。
- 本版尚未合入
dev 的功能（如 feature 分支）：先合入 / cherry-pick 到 dev，再做发版提交。
普通 dev→main PR 的 CHANGELOG 约定
dev→main 多为不含 chore(release) 的普通功能 PR（把一批功能推进 main）。此类 PR 的 CHANGELOG 素材应随批记录，供后续发版引用：
- 每个普通 dev→main PR，在它那批功能提交里写好
## [Unreleased]（只写 ### Added / ### Fixed / ### Changed 明细，不写 ### 更新公告，也不改版本号），随 PR 一起合入 main。更新公告留到真正发版时再依据明细整理。
- 该
Unreleased 记录独立提交或并入功能提交均可（维护者常 amend 进最新功能提交）；关键是每次普通 PR 都带一次，素材随批落到 main。
- 发版时把
main 上累积的 Unreleased 段标题转正式段 ## [X.Y.Z]，补充 ### 更新公告，版本号在 chore(release) 里改。
这样发版面对的是一份已分好类的素材，无需再从几十条 commit 重新归纳。
dev 上的提交形态（必守）
发版准备完成后，origin/main..dev 应满足：
- 最多一条
chore(release): vX.Y.Z。
- 该发版提交必须是
dev 的 tip（最顶提交）；其下可以是本版功能 / 修复 commit。
- 禁止在
chore(release) 之后再堆 fix / feat 把发版顶掉。若 review / CI 修正在发版提交之后落地：把修正 squash / 重排进发版之前的功能提交，再重提 一条 tip 为 chore(release)，必要时对 dev --force-with-lease（禁止强推 main）。
- 出现多条
chore(release)，或 tip 不是发版提交：soft-reset / 重排后重提，维护者要求时可对 dev --force-with-lease。
推荐拆分：
| 提交 | 内容 |
|---|
feat / fix … | 本版代码与测试；不要改版本号与本版 CHANGELOG 段 |
tip：chore(release): vX.Y.Z | 仅版本号 + 本版 CHANGELOG（Bot：pyproject.toml、pallas/__init__.py、CHANGELOG.md） |
提交与 PR
| 项 | 约定 |
|---|
| Commit | chore(release): vX.Y.Z（Bot / WebUI 相同） |
| PR 标题 | 与发版 commit 标题相同 |
| PR 正文 | 只写本版变更；不写打 tag、合入顺序、CI、强推等流程说明 |
| 合入方式 | 用 merge commit（no-ff），保留完整 feature 历史；squash 会压成单条、丢失提交历史。Auto Tag Release / Release 对两种合入方式都兼容 |
| dev 同步 | 合入后 dev 对齐 main（fast-forward）；若用 no-ff 合入，dev 落后于 main 一个 merge commit，直接 reset 到 origin/main 即可 |
CHANGELOG
两端本版都写 ### 更新公告，文风按面向用户的更新说明来写（直接、可读，少空话与内部黑话）：
- 一行一点：用无序列表书写，每条说清一件事；可写得比 Added/Fixed 更面向使用场景，但避免内部黑话。
- 不用「你会明显感觉到」一类固定小节，也不写成一大段逗号串联。
- 不写发版操作句（例如须先发 WebUI tag、须强推
dev）。
- 可用
### Added / ### Fixed / ### Changed 作面向开发者的明细；Bot 捆绑控制台时在公告里单列一点写清 WebUI 版本。
- CHANGELOG 顶部保持简洁：写标题与（可选）Releases 链接即可，不要写「遵循 Keep a Changelog / 语义化版本」一类套话。
- 公告材料来源：优先用 CHANGELOG 里维护者提前写的备忘说明 + 发版前梳理出的新功能/配置项；用面向用户的话重组，别照抄 commit 明细。
Bot 公告格式（按功能分类 + 二级列表）
公告按功能分类组织，同一功能的多个点用二级列表；不要同一分类标签反复并列独立条目，也不要把功能点硬塞成一条长句。
### 更新公告
- **功能分类**：
- 该功能的一个变化点，简洁一句
- 同一功能的另一个变化点
- **另一分类**：
- 一个变化点
- 捆绑控制台 WebUI v0.9.x（Bot 捆绑控制台时单列一条）
- 每条公告简洁，不写环境变量名、默认值、预算数值（配置项点名留给
### Added / docs）。
- 条目不用句号结尾（与 4.3.x 既有风格一致）。
### Added / ### Fixed / ### Changed 作面向开发者明细：每条 * type(scope): 描述 独立一行、不换行拼接；可按需排序归组。
WebUI 须写最低 Bot commit
WebUI 更新公告**第一条（或靠前）**须写明本版控制台依赖的 最低 Bot commit（如「需要 Bot commit 1e198188 及以上；请勿只升控制台」）。完整 SHA 必须写入 WebUI 仓库根目录的 release-manifest.json，并且该 SHA 必须已进入 Bot main。
WebUI
- 在
CHANGELOG.md 的 <!-- entries --> 下写 ## [Unreleased]，正文按更新公告写（含最低 Bot commit；可先有功能 commit，再补公告 / 发版 commit）。
- 更新
release-manifest.json 的 requires.bot.min_commit，使用完整 40 位 SHA；Release 会校验它可从 Bot main 到达，并将 manifest 作为资产及 dist.zip 内容发布。
- 提交
chore(release): vX.Y.Z 且为 dev tip（预期合入后版本；不要手改 package.json version，由合入 main 的 Release 递增并打 tag）。
- 开 PR：
--base main --head dev，标题=发版 commit，正文=变更。
- PR 合并后由 Release 工作流自动递增
package.json 并打 vX.Y.Z tag、出 GitHub Release 资产。确认出现 tag 与资产后再收尾（同步 dev←main、清分支）。未自动触发时 workflow_dispatch 传 bump=patch。
Bot
- 对齐
origin/main → 合入本版功能 → 再发版。
- 同步
pyproject.toml 与 pallas/__init__.py 版本号（只在 chore(release) 里改）。
CHANGELOG.md 顶部写本版正式段（含更新公告；Bot 直接写 ## [X.Y.Z]，不走 Unreleased）。- 提交
chore(release): vX.Y.Z（版本文件 + CHANGELOG 同 commit），并确保其为 dev tip。
- 开 PR：标题=发版 commit，正文=变更。
main 合入后由 Auto Tag Release 自动打 tag 并触发 Release 与 publish-pypi-core。Release 会按当前 Bot commit 选择兼容的最新 WebUI tag，手动传入 webui_tag 时也必须通过 manifest 校验；没有兼容 WebUI 时直接失败，不回退到 main。确认出现 vX.Y.Z tag、Release 资产与 PyPI 发布后再收尾：同步 dev←main、清分支。若本次 push 未命中发版提交而未自动触发，手动打 tag 或 workflow_dispatch。
Bot 在 main 直接发版
维护者指定 bot 直接在 main 发版（不走 dev→main PR，如功能直接落在 main）时：
- 改版本号与 CHANGELOG（仍是发版文件），amend 进
main 最新提交，保持单提交形态。
git push origin main：最新提交未推送时 amend 无需强推；若已推送，须维护者授权后才 --force-with-lease。- 推送后 Auto Tag Release 自动打 tag（
auto-tag-release.yml 检测 push 到 main 的 HEAD 提交是否为 chore(release): vX.Y.Z；main 直发若 HEAD 是发版提交同样命中，无需手动）。若 HEAD 不是发版提交（如 amend 未成功或 push 的是普通提交），手动打签名 annotated tag vX.Y.Z 并确认 Release 工作流出包。
- 打 tag 后确认
Release 工作流出包（并确认 publish-pypi-core 发布到 PyPI）；WebUI 可独立发版，Bot 仅捆绑通过 manifest 校验的 tag。
错开发版
维护者要求 Bot 与 WebUI 错开 / 间隔发版时：
- 各自独立走本流程：版本号各自计算、各自
chore(release)、各自 PR 与 tag；不要求同一轮。
- 先发的一方按正常流程收尾（合并、出 tag、Release 就绪）；后发的一方在发起前对齐已发布的
main 再叠发版提交。
- WebUI 的「需要 Bot commit …」必须以已进入 Bot
main 的完整 SHA 为准；不要求 Bot 与 WebUI 同轮或按固定顺序发布。
- 更新公告里两端各自单列，不混写。
Agent
- 先给 CHANGELOG、版本、PR 标题与正文草案，确认后再提交 / 开 PR /
--force-with-lease。
- 开 PR 后跟 CI 与有效 review；若修正导致 tip 不再是
chore(release)，按上文重排后再推（需维护者已授权发版 / 强推 dev 时可用 --force-with-lease）。
- Bot 发版 PR 合并后确认 Auto Tag Release 已打 tag、
Release 就绪、publish-pypi-core 已发布 PyPI；若自动触发未生效，再手动 gh release create / gh workflow run Release（或等价打 tag）并等到 Release 就绪。
- 不擅自强推
main；不默认登记 Notion。
流程文件维护
- 本 SKILL（
docs/skills/pallas-release/SKILL.md）是权威来源；改流程时先改这里。
- 同步副本在
~/.config/opencode/skills/pallas-release/（opencode 加载用），改动后需同步。
~/.cursor/rules/pallas-release.mdc 只留指针，不再维护双份。
