From 9bdd043ae74d62073ce678ed6830d555be067b63 Mon Sep 17 00:00:00 2001
From: Ct201314 <1195214305@qq.com>
Date: Sat, 6 Jun 2026 15:30:51 +0800
Subject: [PATCH] feat(skills): add gitlink-changelog skill

---
 skills/gitlink-changelog/SKILL.md             | 85 +++++++++++++++++++
 .../references/api-reference.md               | 50 +++++++++++
 .../references/conventions.md                 | 45 ++++++++++
 3 files changed, 180 insertions(+)
 create mode 100644 skills/gitlink-changelog/SKILL.md
 create mode 100644 skills/gitlink-changelog/references/api-reference.md
 create mode 100644 skills/gitlink-changelog/references/conventions.md

diff --git a/skills/gitlink-changelog/SKILL.md b/skills/gitlink-changelog/SKILL.md
new file mode 100644
index 0000000..93c2073
--- /dev/null
+++ b/skills/gitlink-changelog/SKILL.md
@@ -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) — 认证、全局参数、安全规则
diff --git a/skills/gitlink-changelog/references/api-reference.md b/skills/gitlink-changelog/references/api-reference.md
new file mode 100644
index 0000000..6de6eb6
--- /dev/null
+++ b/skills/gitlink-changelog/references/api-reference.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 错误码。采集失败返回非零退出码并打印原因。
diff --git a/skills/gitlink-changelog/references/conventions.md b/skills/gitlink-changelog/references/conventions.md
new file mode 100644
index 0000000..f7c7a29
--- /dev/null
+++ b/skills/gitlink-changelog/references/conventions.md
@@ -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 条，超出省略。