| name | bk-audit-version-release |
| description | Use when preparing a BK Audit release, writing product-facing release notes, updating release version metadata, checking release gaps, or creating a release commit for bk-audit. |
蓝鲸审计中心版本发布
用于从 main 的实际提交和人工总结中生成产品侧版本日志，并同步版本元数据、提醒发布风险，最后在版本日志 feature 分支上形成一个可合入主分支的 release commit。
基本原则
- 版本日志以证据为准：必须对比前一次发布版本到当前
main 的 commits、diff 和文件路径，不能只照抄人工总结。
- 人工总结是输入，不是最终结论：需要检查“总结提到但 commit 证据不明显”和“commit 有变更但总结遗漏”的项。
- 版本日志面向产品侧：按用户可感知能力归类，避免暴露 hook、schema、内部占位、实现细节等低层表述。
- 发布改动必须收敛成单个语义完整的 release commit；只暂存发布相关文件。
- 信息量较大的发布任务需要维护计划、发现和进展，避免长任务丢上下文；这些文件不提交。
- commit 范围较大或需要多视角取证时，可以使用只读 subagent 拆分“代码链路、风险配置、测试证据、文档质检”，主 agent 必须二次复核后再落结论。
- 不要直接运行当前自动化脚本完成全流程。现有脚本会切分支、拉取、
git add -A 并 --no-verify 提交，和项目规范冲突；除非先修正脚本，否则按本 skill 手动执行文件规则。
必需输入
- 目标版本号：如
1.19.7 或 V1.19.7
- 前一次发布基准：优先使用用户给定 commit；没有则从上一版本 release commit/tag 推断
- 当前发布目标：通常为当前最新
main
- 人工总结点：业务侧明确希望体现的功能、优化、修复
- Commit 信息：如
feat: release-1.19.7版本发布 --story=xxx
信息不足时先从本地仓库推断；只有版本号、基准范围或提交目标无法确定时再问用户。
标准流程
1. 建立版本日志 feature 分支
从最新 main 新建版本日志 feature 分支，避免把发布日志混入业务分支；该分支后续通过 PR 或确认后的合并进入 main。
git status --short --branch
git checkout main
git fetch tencent
git merge --ff-only tencent/main
git checkout -b codex/release-1.19.7-notes
如果当前工作区有未提交改动，先确认这些改动是否属于本次发布；不要自动 stash 或覆盖用户改动。
2. 定位对比范围
优先级：
- 用户明确给出的基准 commit
- 上一版本 release commit，如
feat: release-1.19.6版本发布
- 上一版本 tag，如
v1.19.6-*
release.md 顶部的上一版本号，再用 git log --grep 查找 release commit
必须记录最终采用的范围，例如：
git log --oneline --decorate <base_commit>..main
git diff --stat <base_commit>..main
git diff --name-status <base_commit>..main
3. 归并产品侧版本点
结合 commit 标题、变更文件和人工总结，归并为三类：
新增：新能力、新入口、新接口、新流程、新可观测能力、失败重试能力等优化：已有能力的体验、性能、交互、展示、查询、筛选、导出、权限范围优化修复：缺陷修正、异常状态修复、错误展示修复、误触发修复
写法要求：
- 一条日志表达一个产品能力，不要一条 commit 一条日志。
- 合并重复项，例如“历史分析报告及导出任务支持失败重试”。
- 对“新增/优化/修复”分类有疑问时，优先看用户感知：用户获得新操作能力通常归
新增。
- 避免低层实现词：
hook、MCP schema、占位清理、接口参数增加，除非这些就是对外能力。
- 中间问题过滤：对修复和性能补偿提交，检查是否由同一发布范围内的新增需求引入。只有同时具备提交祖先关系、变更路径或关联事项等证据，且修复仅使新能力达到预期时，才不单列为版本点；保留最终新增或优化能力。证据不足时标为“待确认”，不要自行排除。
一致性检查
生成草稿后必须输出检查结果，提醒用户确认：
| 检查项 | 处理方式 |
|---|
| 人工总结提到但 commit 证据不明显 | 标为“待确认”，列出总结原文 |
| commit 里有明显产品变更但总结没提 | 补入草稿或标为“可能遗漏” |
| 同一能力重复出现 | 合并成一个产品侧表述 |
| 分类可能不准 | 明确指出，例如“失败重试更像新增能力，不是修复” |
| 同版本需求引入的中间问题 | 对修复和性能补偿提交，使用 git merge-base --is-ancestor、文件路径和关联事项交叉确认；确认属于需求开发或联调过程的问题时，不单列日志，仅保留最终能力，并在发现记录写明排除结论和证据 |
| 后端、前端、中英文日志不一致 | 修改到一致后再提交 |
需要保留证据路径：commit hash、文件路径或 diff 统计，方便用户快速复核。
变更与环境 Checklist
根据 diff 文件路径提醒发布关注点。命中即提醒，未命中可说明“未发现”。
| 关注点 | 典型文件或信号 | 发布提醒 |
|---|
| 环境变量/配置 | config/, settings.py, .env, app_desc.yaml | 是否需要新增环境变量、默认值、部署配置 |
| 数据库变更 | migrations/, model 变更 | 是否需要迁移、回滚、数据兼容 |
| 依赖变更 | pyproject.toml, pdm.lock, package.json, lock 文件 | 是否需要重新构建镜像、前端依赖安装 |
| API 网关 | support-files/apigw/ | 是否需要同步网关资源、权限、文档 |
| 异步/定时任务 | tasks.py, management commands, celery/periodic 配置 | 是否需要 worker、beat、队列或补偿任务关注 |
| 权限/场景隔离 | IAM、permission、scene、auth 相关文件 | 是否需要授权模型、存量权限、灰度验证 |
| 观测/监控 | monitor, observability, metrics, logging | 是否需要指标、告警、日志字段确认 |
| 国际化 | locale/, language/lang/ | 是否需要编译翻译或检查中英文文案 |
需要更新的文件
从仓库根目录视角：
release.md：在顶部插入中文版本日志readme.md：更新 release badgereadme_en.md：更新 release badgesrc/frontend/package.json：更新 versionsrc/backend/VERSION：更新 V{version}src/backend/version_md/V{version}_{YYYYMMDD}_zh-cn.mdsrc/backend/version_md/V{version}_{YYYYMMDD}_en.md
日期使用当前日期，格式 YYYYMMDD。
中文模板：
## V1.19.7 版本更新日志
### 新增
- [ 新增 ] ...
### 优化
- [ 优化 ] ...
### 修复
- [ 修复 ] ...
英文模板：
## Version 1.19.7 Release Notes
### New Features
- [ NEW ] ...
### Optimizations
- [ OPTIMIZATION ] ...
### Fixed
- [ FIXED ] ...
如果某一类没有内容，不要强行保留空标题；以本次实际内容为准。
验证与提交
提交前必须执行：
git diff --check -- <release_files>
git add <release_files>
.venv/bin/pre-commit run
git diff --cached --stat
git commit -m "feat: release-1.19.7版本发布 --story=135736074"
规则：
- 只
git add 本次发布文件，不要 git add . 或 git add -A。
- 使用项目自带
.venv/bin/pre-commit。
- 不要用
--no-verify。
debug/、.env、.venv、config/local_settings.py 不要提交。- 提交后检查
git status --short --branch 和 git log -1 --stat --oneline。
合入主分支
如果用户要求合入主分支：
- 先说明 release commit、变更文件、验证结果、待关注 checklist。
- 等用户确认后再 push、创建 PR 或合入。
- 合入后确认
main 最新提交包含 release commit。
不要在未确认的情况下直接推送或合并到主仓库主分支。
交付格式
最终回复必须包含：
- 版本日志摘要
- 一致性检查结论
- 环境与变更 checklist 命中项
- 已修改文件
- 验证结果
- commit hash（如果已提交）
