feat(skills): add gitlink-changelog skill
This commit is contained in:
parent
b45241dcda
commit
9bdd043ae7
|
|
@ -0,0 +1,85 @@
|
|||
---
|
||||
name: gitlink-changelog
|
||||
version: 1.0.0
|
||||
description: "版本变更对比：对比提交历史，按 conventional commits 归类生成结构化变更日志，标注不兼容变更与贡献者。当用户提到「变更日志」「changelog」「版本对比」「两个版本之间改了什么」「发版变更」「what changed」时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
optional_bins: ["python"]
|
||||
cliHelp: "gitlink-cli release --help"
|
||||
---
|
||||
|
||||
# gitlink-changelog（版本变更对比）
|
||||
|
||||
**CRITICAL — 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
**CRITICAL — 本技能全程只读，不修改任何远程数据。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。
|
||||
|
||||
## 何时使用本技能
|
||||
|
||||
- 发版前想生成一份变更日志（changelog）
|
||||
- 用户问「这个版本相比上个版本改了什么」「最近有哪些变更」
|
||||
- 需要把提交历史整理成结构化的版本说明
|
||||
|
||||
## 何时不使用
|
||||
|
||||
- 自动创建 Release 并发布 → 用 `gitlink-release` / `gitlink-release-auto`
|
||||
- 仅比对代码 diff → 用 `gitlink-compare`
|
||||
|
||||
## 能力概览
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| 提交归类 | 按 conventional commits（feat/fix/docs…）分组 |
|
||||
| 不兼容变更标注 | 识别 `!` 标记与 BREAKING CHANGE |
|
||||
| scope 与作者 | 提取每条变更的 scope 与提交者 |
|
||||
| 贡献者汇总 | 列出本次范围内的全部贡献者 |
|
||||
|
||||
## 工作流：生成变更日志
|
||||
|
||||
### 方式 A：配套脚本（推荐）
|
||||
|
||||
```bash
|
||||
# 生成最近提交的变更日志
|
||||
python scripts/changelog.py --owner Gitlink --repo gitlink-cli
|
||||
|
||||
# 标注版本范围（用于报告标题）
|
||||
python scripts/changelog.py --owner Gitlink --repo gitlink-cli --since v0.1.17 --until v0.1.18
|
||||
|
||||
# JSON 输出
|
||||
python scripts/changelog.py --owner Gitlink --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
参数说明：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `--owner` / `--repo` | string | 是* | 仓库（*或用 `--slug`） |
|
||||
| `--slug` | string | 否 | `owner/repo` 或完整 URL |
|
||||
| `--since` / `--until` | string | 否 | 版本/标签，用于报告标注 |
|
||||
| `--max-pages` | int | 否 | 提交采集页数（每页 50），默认 6 |
|
||||
| `--format` | string | 否 | `markdown`（默认）或 `json` |
|
||||
| `--output` | string | 否 | 输出文件 |
|
||||
|
||||
### 方式 B：用 gitlink-cli 命令
|
||||
|
||||
```bash
|
||||
# 获取版本列表（定位版本时间）
|
||||
gitlink-cli release +list --owner Gitlink --repo gitlink-cli --format json
|
||||
|
||||
# 获取提交历史
|
||||
gitlink-cli api GET /:owner/:repo/commits --query 'page=1&limit=50' --format json
|
||||
```
|
||||
|
||||
## API 注意事项
|
||||
|
||||
- GitLink 的 compare 接口需要鉴权，本技能改用提交列表分析，无需登录即可处理公开仓库。
|
||||
- conventional commits 规范化率低的仓库，归类精度会下降；报告会标注规范化提交占比。
|
||||
|
||||
## References
|
||||
|
||||
- [api-reference.md](references/api-reference.md) — 采集接口与字段
|
||||
- [conventions.md](references/conventions.md) — conventional commits 归类规则
|
||||
- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
# gitlink-changelog API 参考
|
||||
|
||||
> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。
|
||||
|
||||
本技能全程只读。
|
||||
|
||||
## 采集的接口
|
||||
|
||||
### 提交列表
|
||||
|
||||
```
|
||||
GET /:owner/:repo/commits.json?page=<n>&limit=50
|
||||
```
|
||||
|
||||
每页硬上限 50 条，以 `total_count` 为终止依据。使用字段：
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `commits[].message` | 解析 conventional 类型、scope、描述、BREAKING |
|
||||
| `commits[].sha` | 报告中标注短 sha |
|
||||
| `commits[].author.login` / `.name` | 提取贡献者 |
|
||||
|
||||
### 版本发布列表
|
||||
|
||||
```
|
||||
GET /:owner/:repo/releases.json
|
||||
```
|
||||
|
||||
用于 `--since`/`--until` 定位版本时间窗口。字段：`tag_name` / `name` / `created_at`。
|
||||
|
||||
## 关于 compare 接口
|
||||
|
||||
GitLink 的 `GET /:owner/:repo/compare/{base}...{head}` 接口需要鉴权（公开访问返回 401）。
|
||||
因此本技能不依赖 compare，而是用提交列表分析，无需登录即可处理公开仓库。
|
||||
|
||||
## 输出字段（JSON）
|
||||
|
||||
```json
|
||||
{
|
||||
"since": "v0.1.17", "until": "v0.1.18",
|
||||
"total_commits": 127, "typed_commits": 70, "breaking_count": 0,
|
||||
"groups": {"feat": 27, "fix": 16, "docs": 15, ...},
|
||||
"detail": {"feat": [{"type","scope","desc","sha","author","breaking"}]},
|
||||
"contributors": ["..."]
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
沿用 gitlink-shared 错误码。采集失败返回非零退出码并打印原因。
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
# Conventional Commits 归类规则
|
||||
|
||||
本技能按 [Conventional Commits](https://www.conventionalcommits.org/) 规范解析提交。
|
||||
|
||||
## 提交格式
|
||||
|
||||
```
|
||||
<type>(<scope>)<!>: <description>
|
||||
```
|
||||
|
||||
- `type`：变更类型（见下表）
|
||||
- `scope`：可选，影响范围（如 `auth`、`issue`）
|
||||
- `!`：可选，标记不兼容变更
|
||||
- `description`：变更描述
|
||||
|
||||
## 识别的类型
|
||||
|
||||
| type | 含义 | 报告分组 |
|
||||
|------|------|----------|
|
||||
| feat | 新功能 | ✨ 新功能 |
|
||||
| fix | 缺陷修复 | 🐛 缺陷修复 |
|
||||
| perf | 性能优化 | ⚡ 性能优化 |
|
||||
| refactor | 重构 | ♻️ 重构 |
|
||||
| docs | 文档 | 📝 文档 |
|
||||
| test | 测试 | ✅ 测试 |
|
||||
| build | 构建 | 📦 构建 |
|
||||
| ci | 持续集成 | 👷 持续集成 |
|
||||
| style | 代码风格 | 💄 风格 |
|
||||
| chore | 工程杂项 | 🔧 工程 |
|
||||
| revert | 回退 | ⏪ 回退 |
|
||||
|
||||
不匹配上述类型的提交归为 `other`，不计入分组（但仍计入总数）。
|
||||
|
||||
## 不兼容变更（BREAKING CHANGE）
|
||||
|
||||
满足任一即标记为不兼容变更，单列在报告顶部 ⚠️ 区块：
|
||||
|
||||
- 类型后带 `!`，如 `feat!:` 或 `feat(api)!:`
|
||||
- 提交正文包含 `BREAKING CHANGE`
|
||||
|
||||
## 报告分组顺序
|
||||
|
||||
feat → fix → perf → refactor → docs → test → build → ci → style → chore → revert
|
||||
|
||||
每组最多展示 30 条，超出省略。
|
||||
Loading…
Reference in New Issue