From 66793a66aeff392db94d3fd62f428ab2ae0b0caf Mon Sep 17 00:00:00 2001 From: Ct201314 <1195214305@qq.com> Date: Sat, 6 Jun 2026 15:31:29 +0800 Subject: [PATCH] feat(skills): add gitlink-metrics skill --- skills/gitlink-metrics/SKILL.md | 82 +++++++++++++++++++ .../references/api-reference.md | 37 +++++++++ .../references/metrics-formula.md | 45 ++++++++++ 3 files changed, 164 insertions(+) create mode 100644 skills/gitlink-metrics/SKILL.md create mode 100644 skills/gitlink-metrics/references/api-reference.md create mode 100644 skills/gitlink-metrics/references/metrics-formula.md diff --git a/skills/gitlink-metrics/SKILL.md b/skills/gitlink-metrics/SKILL.md new file mode 100644 index 0000000..0c2bc58 --- /dev/null +++ b/skills/gitlink-metrics/SKILL.md @@ -0,0 +1,82 @@ +--- +name: gitlink-metrics +version: 1.0.0 +description: "仓库量化指标看板：计算 PR 合并率、按月活跃趋势、基尼系数、CR3/CR5、巴士因子与多维评分卡（活跃度/协作/社区/可维护性），生成数据驱动的运营看板。当用户提到「指标」「数据看板」「合并率」「活跃趋势」「巴士因子」「评分卡」「metrics」「dashboard」时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + optional_bins: ["python"] + cliHelp: "gitlink-cli repo --help" +--- + +# gitlink-metrics（仓库量化指标看板） + +**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)。 + +## 何时使用本技能 + +- 需要用量化指标评估仓库状态（合并率、活跃趋势、集中度） +- 用户问「这个项目的数据指标怎么样」「给我一个指标看板」「巴士因子是多少」 +- 多仓库横向对比、数据驱动的社区运营 + +## 与 gitlink-insight 的区别 + +`gitlink-insight` 偏定性的健康度评估与周报；本技能聚焦**量化指标与评分卡**—— +PR 合并率、按月活跃趋势、基尼系数、CR3/CR5、巴士因子、四维评分卡，用可计算、 +可对比的数字刻画仓库，功能更偏数据分析。 + +## 指标说明 + +| 指标 | 含义 | +|------|------| +| PR 合并率 | 已合并 PR / 总 PR | +| 按月活跃趋势 | 各月提交量分布 | +| 基尼系数 | 贡献分布不平等程度（0 均衡，1 集中） | +| CR3 / CR5 | 前 3 / 前 5 贡献者占比 | +| 巴士因子 | 累计贡献达 50% 所需最少人数 | +| 多维评分卡 | 活跃度 / 协作 / 社区 / 可维护性 / 综合（各 0-100） | + +## 工作流：生成指标看板 + +### 方式 A：配套脚本（推荐） + +```bash +python scripts/metrics.py --owner Gitlink --repo gitlink-cli +python scripts/metrics.py --owner Gitlink --repo gitlink-cli --format json +``` + +参数说明： + +| 参数 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| `--owner` / `--repo` | string | 是* | 仓库（*或用 `--slug`） | +| `--slug` | string | 否 | `owner/repo` 或完整 URL | +| `--commit-pages` | int | 否 | 提交采集页数（每页 50），默认 6 | +| `--format` | string | 否 | `markdown`（默认）或 `json` | +| `--output` | string | 否 | 输出文件 | + +### 方式 B：用 gitlink-cli 命令 + +```bash +gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json +gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --format json +gitlink-cli api GET /:owner/:repo/commits --query 'page=1&limit=50' --format json +gitlink-cli api GET /:owner/:repo/contributors --format json +``` + +## API 注意事项 + +- 活跃趋势依据提交 `timestamp`（unix）按月统计。 +- PR 合并率依据 `pull_request_status`（1=merged）。 +- 评分卡为启发式综合评分，用于横向参考而非绝对评价。 +- 数据采集全程只读。 + +## References + +- [api-reference.md](references/api-reference.md) — 采集接口与字段 +- [metrics-formula.md](references/metrics-formula.md) — 指标计算公式 +- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则 diff --git a/skills/gitlink-metrics/references/api-reference.md b/skills/gitlink-metrics/references/api-reference.md new file mode 100644 index 0000000..bd741df --- /dev/null +++ b/skills/gitlink-metrics/references/api-reference.md @@ -0,0 +1,37 @@ +# gitlink-metrics API 参考 + +> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。 + +本技能全程只读。 + +## 采集的接口 + +| 接口 | 用途 | +|------|------| +| `GET /:owner/:repo.json` | 规模指标（issues/pulls/releases/star/fork 计数） | +| `GET /:owner/:repo/pulls.json` | PR 合并率（`pull_request_status`） | +| `GET /:owner/:repo/commits.json` | 按月活跃趋势（`timestamp`） | +| `GET /:owner/:repo/contributors.json` | 集中度与评分（`contributions`） | + +## 使用的字段 + +- 仓库：`issues_count` / `pull_requests_count` / `version_releases_count` / `praises_count` / `forked_count` +- PR：`pull_request_status`（0=open,1=merged,2=closed） +- 提交：`timestamp`（unix 秒） +- 贡献者：`contributions` + +## 输出字段（JSON） + +```json +{ + "scale": {"issues","pulls","contributors","releases","stars","forks"}, + "pr_metrics": {"total","merged","closed","open","merge_rate"}, + "monthly_commits": {"2026-05": 93}, + "concentration": {"gini","cr3","cr5","bus_factor"}, + "score_card": {"活跃度","协作","社区","可维护性","综合"} +} +``` + +## 错误处理 + +采集失败返回非零退出码并打印原因。提交无可定位时间戳时不计入活跃趋势。 diff --git a/skills/gitlink-metrics/references/metrics-formula.md b/skills/gitlink-metrics/references/metrics-formula.md new file mode 100644 index 0000000..b7b0cf8 --- /dev/null +++ b/skills/gitlink-metrics/references/metrics-formula.md @@ -0,0 +1,45 @@ +# 指标计算公式 + +## PR 合并率 + +``` +合并率 = 已合并 PR 数 / 总 PR 数 × 100% +``` + +PR 状态依据 `pull_request_status`：0=open, 1=merged, 2=closed。 + +## 按月活跃趋势 + +按提交 `timestamp`（unix 秒）换算为 UTC 年月，统计各月提交数。 + +## 基尼系数（贡献分布） + +基于贡献次数排序后的洛伦兹曲线： + +``` +G = 2 × Σ(i × xᵢ) / (n × Σxᵢ) − (n + 1) / n +``` + +其中 xᵢ 为升序排序后的贡献值，n 为贡献者数。0=完全均衡，1=完全集中。 + +## CR3 / CR5（集中度） + +``` +CRk = 前 k 名贡献者贡献之和 / 总贡献 × 100% +``` + +## 巴士因子 + +累计贡献达到 50% 所需的最少人数（贡献降序累加）。越小表示知识越集中、单点风险越高。 + +## 多维评分卡（各 0-100） + +| 维度 | 计算 | +|------|------| +| 活跃度 | min(100, 近 3 个月平均月提交 × 2) | +| 协作 | PR 合并率（百分数取整） | +| 社区 | min(100, 贡献者数 × 4 + Star + Fork) | +| 可维护性 | min(100, 巴士因子 × 20) | +| 综合 | 上述四项的平均 | + +评分为启发式综合，用于横向参考与趋势观察，非绝对评价。