gitcode-release-notes

name	gitcode-release-notes
description	Generate release notes for GitCode repositories from commits (by tag range or since-date), grouped as feat/fix/docs/other, output Markdown for Release pages. 按 tag 区间或日期拉取提交并生成版本发布公告 Markdown。Python 3.7+ standard library only.

GitCode 版本发布公告（Release Notes）

根据 GitCode API 拉取仓库在指定区间内的提交。脚本仅负责获取 commit 与简单过滤；你根据脚本输出的 JSON 总结、归类、润色并生成最终 release note，输出为 Markdown 格式，使阅读清晰、像人写的发布说明。

何时使用

• 用户表达「生成 release notes」「版本发布说明」「从 v1.0 到现在的更新日志」「从某日期到现在的提交记录」等意图。
• 必须在本次对话中提供 --repo owner/repo（必传）；可选提供 --branch、--from、--to、--since-date。

认证

GITCODE_TOKEN：按以下优先级读取。

优先级	来源
1	进程环境变量 GITCODE_TOKEN
2	Windows 用户级环境变量
3	Windows 系统级环境变量

• Linux/macOS：建议在 ~/.bashrc 或 ~/.zshrc 中 export GITCODE_TOKEN="..."。
• 未配置时：脚本报详细错误，提示到 GitCode 个人访问令牌 创建并设置环境变量。

路径约定

• 技能根目录（SKILL_ROOT）：本 SKILL.md 所在目录。脚本通过 __file__ 定位，不依赖当前工作目录。
• 支持 Linux / macOS / Windows；执行时使用脚本绝对路径。

固化流程

1. 解析参数：从用户输入或对话中提取 --repo（必传）、--branch、--from、--to、--since-date。
2. 调用脚本（输出 JSON）：

   python <SKILL_ROOT>/scripts/release_notes.py --repo owner/repo --json [--branch BRANCH] [--from TAG] [--to TAG] [--since-date YYYY-MM-DD]
   

   • 必须带 --json：脚本只做拉取与简单过滤，向 stdout 输出 JSON，不生成最终 Markdown。
   • 区间三选一：--since-date（从该日 00:00 上海时间至今）、--from（从某 tag 至今）、或 --from + --to（两 tag 之间）。
   • --branch 未传时：脚本依次尝试 master → develop → main，都不存在则报错并提示使用 --branch。
3. 读取 JSON：从 stdout 解析 JSON。若退出码非 0 或 stderr 有错误信息，向用户展示详细错误并结束。
4. 生成最终 release note：
   • 根据 JSON 中的 commits 做归类（新特性 / 修复 / 文档 / 其他）、总结（每条或每组用简要概括，不要直接贴 commit 原文）、润色（统一语言、合并同类、去掉无信息量项），生成干净、专业、可对外发布的 release note。
   • 按 「最终 release note 输出格式」 与 「撰写原则」 写出 Markdown（标题、四小节、每条仅写简要说明；不展示 commit 信息；不展示合并条数/测试/合规等无价值信息）。
   • 交付给用户（可保存为文件或粘贴到 GitCode Release）。
5. 禁止：不得在未得到脚本 JSON 前猜测或伪造数据；不得将 commit 列表原样当作最终 release note 交付，须经总结与润色后再交付。其余禁止事项见「禁止」一节。

脚本参数

参数	必填	说明
--repo	是	仓库，格式 owner/repo
--json	必带（本技能调用时）	脚本输出 JSON（仅拉取+简单过滤），由你总结并生成最终 release note
--branch	否	分支；未传时自动尝试 master → develop → main
--since-date	否	从该日期 00:00（Asia/Shanghai）至今的提交
--from	否	起始 tag（到当前 HEAD 或到 --to）
--to	否	结束 tag，与 --from 一起表示区间
--max-per-category	否	仅在不使用 --json 时生效，每类最多展示条数，默认 10

• 区间约定：仅用 --since-date、或仅用 --from、或 --from + --to。若同时传多种，脚本按 --since-date > --from/--to 优先级处理。
• 本技能流程下须带 --json（以获取 JSON 供你总结）；不带 --json 时脚本会直接输出 Markdown，不经过本技能总结步骤。

脚本 --json 输出与你的职责

• 脚本：仅获取 commit 与简单过滤（排除空 message、纯 merge），向 stdout 输出 JSON；不做归类、不写总结。
• 你：从 stdout 解析 JSON，根据 commits 与 stats 做归类、简要概括、润色，按「最终 release note 输出格式」与「撰写原则」写出 Markdown；不得原样罗列 commit。

最终 release note 输出格式（须统一遵守）

生成 Markdown 时必须按以下格式；每条条目的简要说明根据 commit 进行归纳。

1. 标题：# owner/repo Release Notes（版本区间），或使用 JSON 中的 title_line 作为二级标题（如 ## v1.1.0 (YYYY-MM-DD)）时，一级标题可为 # owner/repo Release Notes。
2. 小节顺序与标题（有内容的才输出，顺序不可调换）：
   • ### 🚀 新特性
   • ### 🐛 修复
   • ### 📚 文档
   • ### 🔧 其他更改
3. 每条条目格式：- 简要说明。简要说明由你根据该 commit 归纳；不展示 commit 哈希或链接。
4. 其他更改：仅保留对用户/使用方有感知的架构或能力类变更；不展示「合并与依赖更新（共 N 条）」；若无实质内容可省略该小节或仅 1～2 条。
5. 每类条数：新特性、修复、文档、其他更改每类最多 10 条；优先保留对用户价值最高、最易理解的条目，超出时合并同类或略去次要项。
6. 语言：小节标题与条目说明统一用中文；专有名词、仓库名可保留英文。

撰写原则（保证输出质量）

面向非核心研发（测试、产品、运维等）可快速抓取重点，避免信息过载与内部黑话。

• 精简粒度：按能力/模块合并同类项，单条不堆砌多个无关功能；新特性可按「硬件与拓扑 / 调度 / 设备与插件 / 高可用 / 推理与运维」等维度归纳；修复中不同问题应拆条或按类合并，避免一条里混杂多个无关 bug。
• 术语统一：同一概念全文统一表述（同一术语不混用不同拼写）；专业缩写首次出现时可加括号简要说明；避免仅内部使用的缩写直接出现在对外 release note 中。
• 不展示无价值信息：不展示「合并与依赖更新（共 N 条）」；不体现测试用例、用例补充；不体现合规；不体现内部细节（如 cleancode、codecheck、DT、若干内部 bug 修复）。
• 聚焦价值：只保留对用户/使用方有意义的变更；模糊表述（如仅写「逻辑优化」）应并入具体能力描述或略去；长句适当缩短，条目分行清晰。
• 每条简短可扫读：每条尽量一句话、一个要点，避免用分号/顿号在一句里堆砌多个功能或修复；可参考成熟开源社区（如 Kubernetes、VS Code）的 release note 风格——简短、易扫读，读者几秒内能抓重点。

输出示例（Markdown）

# owner/repo Release Notes（v1.0.0 → v1.1.0）

### 🚀 新特性
- 新增 XXX 支持，兼容 A 与 B 场景。
- 支持从配置文件加载集群拓扑。

### 🐛 修复
- 修复 namespace 与任务名相同时的匹配错误。
- 修复日志打印重复与级别丢失问题。
- 修复包含 init 容器时的配置生成问题。

### 📚 文档
- 更新依赖源说明。

### 🔧 其他更改
- 设备 ID 体系与资源管理实现与重构。
- 故障码与知识库、路径诊断等能力补充与优化。

禁止

• 禁止在未得到脚本输出（JSON）前猜测或伪造数据。
• 禁止在未配置 --repo 时执行脚本（必须提示用户提供 --repo）。
• 禁止将脚本 JSON 中的 commit 列表原样当作最终 release note 交付（须经你总结、归类、润色后输出 Markdown）。
• 禁止直接复制 commit 原文，必须重新总结、改写。
• 禁止出现任何 commit 链接、commit ID、git 地址。
• 禁止罗列零散 fix，同类问题必须合并成一条。
• 只保留对用户/使用方有意义的内容，去掉内部调试、分支合并、过于细碎的文档改动等无关信息。
• 禁止展示「合并与依赖更新（共 N 条）」；禁止体现测试用例、出海与合规、cleancode/codecheck/DT/内部 bug 等内部细节。

示例

用户意图	命令（须带 --json）
从 v1.0.0 到当前	python <S> --repo owner/repo --json --from v1.0.0
从 v1.0.0 到 v1.1.0	python <S> --repo owner/repo --json --from v1.0.0 --to v1.1.0
从 2026-01-08 至今（上海时间）	python <S> --repo owner/repo --json --since-date 2026-01-08
指定分支	python <S> --repo owner/repo --json --since-date 2026-01-08 --branch main

其中 <S> 为 <SKILL_ROOT>/scripts/release_notes.py 的绝对路径。不带 --json 时脚本会直接输出 Markdown，不经过本技能总结步骤。

历史版本

v1.0.0 (2026-03-11)

• 🎉 初始版本发布
• 📖 支持按 tag/日期生成 Release Notes Markdown