GitHub Release
目标
当用户明确要求"发布项目到 GitHub"、"创建 GitHub Release"或"生成 Release Notes"时使用。智能分析 tag 间历史变化并生成专业的 Release Notes；明确发布/创建请求时自动创建 GitHub Release，单独的 notes/历史总结请求仅生成预览，除非用户随后确认发布。支持首次发布、常规版本、预发布版本（alpha/beta/rc），自动识别 prerelease 标记。
流程
输入
触发条件
用户需要：
- 发布项目的新版本到 GitHub
- 创建 GitHub Release 并自动生成 Release Notes
- 推送某个 tag 到 GitHub 并创建 release
- 总结版本间的历史变化
你需要确认的输入
-
目标 tag（如
v3.0.0）- 如未指定，列出最近 tags 供选择
-
项目路径（可选，默认当前工作目录）
-
任务输出目录（宿主可设置
TASK_OUTPUT_DIR，指向本轮已声明的./.bensz-api/task-.../git-publish-release/output/；未设置时临时 notes 使用 OS 临时目录并立即清理）
认证通过
gh auth login管理，无需手动配置 token。
明确要求“发布项目到 GitHub”或“创建 GitHub Release”时，按配置执行远程发布；仅要求“生成 Release Notes”或“总结版本间的历史变化”时只生成文案/预览，不调用 gh release create，除非用户随后明确确认发布。release.require_confirmation 的含义是：明确发布/创建请求可作为本次授权，覆盖已有 Release 仍按下方错误处理规则询问；不得把文案生成请求视为远程发布授权。
执行步骤
工作流程
确认项目信息
bash# 获取 owner/repo REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
获取最新 Release 信息
bash# 获取最近一次 release 的 tag PREVIOUS_TAG=$(gh release list --limit 1 --json tagName -q '.[0].tagName')
- 如果存在历史 release，比较范围为：
PREVIOUS_TAG..TARGET_TAG - 如果是首个 release，比较范围为：从初始 commit 到
TARGET_TAG
分析历史变化
获取两个版本之间的 commit 历史：
bash# 如果有历史 release git log ${PREVIOUS_TAG}..${TARGET_TAG} --pretty=format:"%h|%s|%an|%ad" --date=short # 如果是首个 release git log ${TARGET_TAG} --pretty=format:"%h|%s|%an|%ad" --date=short
生成 Release Notes
根据 commit 历史和项目特点，智能生成 Release Notes。
Release Notes 结构
🎉 [版本号] - [吸引人的标题] [一句话总结本次发布的核心价值/意义] 🚀 核心亮点： • [亮点1] • [亮点2] • [亮点3] ✨ 主要更新： [类别1] • 更新内容1 • 更新内容2 [类别2] • 更新内容3 • 更新内容4 🔧 技术改进： • 技术改进1 • 技术改进2 📋 完整变更日志： [简略说明获取方式或列出主要 commits]
标题撰写原则
- 情感化表达：使用"革命性"、"突破性"、"里程碑"等词汇
- 场景化描述：说明这个版本解决什么问题、带来什么价值
- 时效性关联：如"为 2026 年就绪"、"拥抱新范式"
内容分类原则
根据 commit 信息自动分类：
| 类别图标 | 类别名称 | Commit 关键词示例 |
|---|---|---|
| 🚀 | 核心亮点 | breakthrough, major, feature |
| ✨ | 新功能 | add, new, feature |
| 🐛 | Bug 修复 | fix, bugfix, resolve |
| 🔧 | 技术改进 | refactor, optimize, improve |
| 📝 | 文档更新 | docs, readme, guide |
| 🔐 | 安全更新 | security, fix vulnerability |
| 💥 | 破坏性变更 | breaking, deprecate |
语言风格
- 简洁有力：每个要点不超过一行
- 价值导向：强调"为什么"而非仅仅"是什么"
- 用户视角：用用户能理解的语言，避免技术术语堆砌
- 适当煽动：使用感叹号、emoji 营造氛围，但不过度
判断是否为 Prerelease
根据 tag 名称自动判断：
- 包含
alpha,beta,rc,pre等标识 →prerelease: true - 否则 →
prerelease: false
按授权创建 GitHub Release
仅在用户明确要求发布/创建 Release，或在预览后明确确认发布时执行以下命令；单独的 Release Notes/历史总结请求不得执行此步骤。
bash# 将 Release Notes 写入临时文件（避免 shell 转义问题） # TASK_OUTPUT_DIR 可由宿主设置为本次任务已声明的 # ./.bensz-api/task-.../git-publish-release/output/ 目录；未注入时仅使用 # 一次性的 OS 临时目录，并在流程结束后清理，不把它当作任务产物。 NOTES_DIR="${TASK_OUTPUT_DIR:-${TMPDIR:-/tmp}}" mkdir -p "$NOTES_DIR" NOTES_FILE=$(mktemp "$NOTES_DIR/release-notes-XXXXXX.md") cat > "$NOTES_FILE" << 'NOTES_EOF' [生成的 Release Notes 内容] NOTES_EOF # 正式版 gh release create "$TARGET_TAG" \ --title "$TARGET_TAG" \ --notes-file "$NOTES_FILE" # 预发布版（tag 含 alpha/beta/rc/pre 时） gh release create "$TARGET_TAG" \ --title "$TARGET_TAG" \ --notes-file "$NOTES_FILE" \ --prerelease # 清理临时文件 rm -f "$NOTES_FILE"
参考资源
- Release Notes 生成策略：references/release-notes-strategy.md
- Release Notes 示例模板：references/release-templates.md
- GitHub CLI 文档：https://cli.github.com/manual/gh_release_create
输出
输出格式
完成发布后，向用户输出：
✅ Release 发布成功！ 📍 Release URL: [release 链接] 🏷️ Tag: [tag 名称] 📅 发布时间: [时间] 📝 Release Notes 预览： [生成的前 10 行 notes]
如果用户只要求 Release Notes 或历史总结，输出文案预览及对应的历史范围，不报告 Release URL，也不宣称已发布。
输出管理
BenszAPI 任务工作区
校验
前置检查
确认 gh CLI 已安装并已认证：
bashgh auth status
如未认证，提示用户运行：
bashgh auth login
失败与恢复
错误处理
| 场景 | 处理方式 |
|---|---|
gh 未安装 | 提示安装：brew install gh 或访问 https://cli.github.com |
gh 未认证 | 提示运行 gh auth login |
| Tag 不存在 | 提示用户可用的 tags 列表 |
| 网络请求失败 | 重试 3 次，仍失败则报错并给出手动创建指南 |
| 权限不足 | 提示检查 gh auth status 及仓库权限 |
| Release 已存在 | 询问用户是否覆盖（使用 gh release edit） |
实现注意事项
- 跨平台兼容：始终使用正斜杠
/处理路径 - Notes 转义：使用
--notes-file传递临时文件，避免 shell 特殊字符转义问题 - Git 远程解析：
gh repo view自动处理 HTTPS 和 SSH 两种 remote URL 格式 - 认证管理：
ghCLI 使用系统 keychain 或~/.config/gh/hosts.yml存储凭证，无需手动管理 token
约束
公共硬约束
本块由 docs/templates/skill-common-constraints.md 统一维护；每个 SKILL.md 的 ## 约束 必须逐字同步本块，不得在副本中改写公共规则。
- 任务需要落盘时，使用唯一的
./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/根目录；共享材料放入shared/，Skill 专属材料放入该 Skill 的input/、output/、log/。 - 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身
config.yaml:skill_info.version；公开 API、协议、目录或配置变更同步文档与CHANGELOG.md。 bensz-collect-bugs是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入~/.bensz-skills/bugs/，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。
