# Bk Audit Version Release

> 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.

- Skill: `tencentblueking/bk-audit-version-release` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add tencentblueking/bk-audit-version-release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencentblueking/bk-audit-version-release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tencentblueking (https://skillmd.com/u/tencentblueking)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencentblueking/bk-audit-version-release

---


# 蓝鲸审计中心版本发布

用于从 `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`。

```bash
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. 定位对比范围

优先级：

1. 用户明确给出的基准 commit
2. 上一版本 release commit，如 `feat: release-1.19.6版本发布`
3. 上一版本 tag，如 `v1.19.6-*`
4. `release.md` 顶部的上一版本号，再用 `git log --grep` 查找 release commit

必须记录最终采用的范围，例如：

```bash
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 badge
- `readme_en.md`：更新 release badge
- `src/frontend/package.json`：更新 `version`
- `src/backend/VERSION`：更新 `V{version}`
- `src/backend/version_md/V{version}_{YYYYMMDD}_zh-cn.md`
- `src/backend/version_md/V{version}_{YYYYMMDD}_en.md`

日期使用当前日期，格式 `YYYYMMDD`。

中文模板：

```markdown
## V1.19.7 版本更新日志

### 新增

- [ 新增 ] ...

### 优化

- [ 优化 ] ...

### 修复

- [ 修复 ] ...
```

英文模板：

```markdown
## Version 1.19.7 Release Notes

### New Features

- [ NEW ] ...

### Optimizations

- [ OPTIMIZATION ] ...

### Fixed

- [ FIXED ] ...
```

如果某一类没有内容，不要强行保留空标题；以本次实际内容为准。

## 验证与提交

提交前必须执行：

```bash
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`。

## 合入主分支

如果用户要求合入主分支：

1. 先说明 release commit、变更文件、验证结果、待关注 checklist。
2. 等用户确认后再 push、创建 PR 或合入。
3. 合入后确认 `main` 最新提交包含 release commit。

不要在未确认的情况下直接推送或合并到主仓库主分支。

## 交付格式

最终回复必须包含：

- 版本日志摘要
- 一致性检查结论
- 环境与变更 checklist 命中项
- 已修改文件
- 验证结果
- commit hash（如果已提交）