feat(skills): add gitlink-metrics skill
This commit is contained in:
parent
b45241dcda
commit
66793a66ae
|
|
@ -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) — 认证、全局参数、安全规则
|
||||
|
|
@ -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": {"活跃度","协作","社区","可维护性","综合"}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
采集失败返回非零退出码并打印原因。提交无可定位时间戳时不计入活跃趋势。
|
||||
|
|
@ -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) |
|
||||
| 综合 | 上述四项的平均 |
|
||||
|
||||
评分为启发式综合，用于横向参考与趋势观察，非绝对评价。
|
||||
Loading…
Reference in New Issue