Merge pull request 'feat(skills): 新增 科研进度跟踪与预警的skill : gitlink-research-progress' (#256) from luwanzhou/gitlink-cli:feat/skill-research-progress into master
This commit is contained in:
commit
8a8b760f2c
|
|
@ -0,0 +1,261 @@
|
|||
---
|
||||
name: gitlink-research-progress
|
||||
version: 1.0.0
|
||||
description: "科研进度智能跟踪与预警：监控科研仓库的提交节奏、Issue 解决进度、里程碑完成度、PR 吞吐与贡献者活跃度，自动生成《科研进度周报 + 风险预警》，用红/黄/绿灯标记停滞与风险。当课题组/PI/导师需要掌握科研项目进展、识别延期与停滞风险、生成阶段汇报时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli repo --help"
|
||||
---
|
||||
|
||||
# gitlink-research-progress（科研进度智能跟踪与预警）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
**CRITICAL — 本技能为只读分析型；如需把预警落成 Issue/评论，须先确认用户意图。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
## 功能概述
|
||||
|
||||
本技能面向**课题组负责人（PI）、导师与科研团队**，回答：**「这个（些）科研项目现在进展如何？哪里有延期或停滞风险？」**
|
||||
|
||||
它把科研仓库的协作数据转化为**进度与风险信号**，自动产出一份可直接用于组会/阶段汇报的**《科研进度周报 + 风险预警》**。
|
||||
|
||||
### 五维进度信号
|
||||
|
||||
| 信号 | 衡量 | 风险方向 |
|
||||
|------|------|----------|
|
||||
| 1. 提交节奏（Velocity） | 近 N 周提交频率与趋势 | 提交骤降 = 停滞 |
|
||||
| 2. Issue 进度（Issue Burndown） | 开/闭 Issue 数、解决速度、陈旧 Issue | 开口持续扩大 = 失控 |
|
||||
| 3. 里程碑完成度（Milestone） | 里程碑到期/完成比例 | 临期未完成 = 延期 |
|
||||
| 4. PR 吞吐（Throughput） | 开放/合并 PR、停留时长 | PR 长期挂起 = 阻塞 |
|
||||
| 5. 团队活跃与 Bus Factor | 活跃贡献者数、贡献集中度 | 单点依赖 = 高风险 |
|
||||
|
||||
---
|
||||
|
||||
## 一、确定监控范围与采集元数据
|
||||
|
||||
### 1.1 单仓库或多仓库
|
||||
|
||||
```bash
|
||||
# 单个科研仓库
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 课题组/组织名下多个仓库（逐个跟踪后汇总）
|
||||
gitlink-cli repo +list --user <login> --format json
|
||||
gitlink-cli repo +list --category manage --format json
|
||||
```
|
||||
|
||||
记录 `created_at`、`updated_at`、`default_branch`、`open_issues_count`（若有）。
|
||||
|
||||
---
|
||||
|
||||
## 二、五维信号采集
|
||||
|
||||
### 2.1 信号一 · 提交节奏（Velocity）
|
||||
|
||||
```bash
|
||||
# 取提交列表（按时间），用于统计近 N 周提交分布
|
||||
gitlink-cli api GET "/:owner/:repo/commits?page=1&limit=50" --format json
|
||||
```
|
||||
|
||||
统计：
|
||||
- 近 4 周 / 8 周每周提交数 → 画 ASCII 趋势条
|
||||
- 与上一周期环比（↑/↓/持平）
|
||||
- 最近一次提交距今天数（`days_since_last_commit`）
|
||||
|
||||
**风险规则：**
|
||||
```
|
||||
🔴 最近一次提交 > 30 天 或 近 2 周提交为 0
|
||||
🟡 周提交量环比下降 > 50%
|
||||
🟢 提交稳定或上升
|
||||
```
|
||||
|
||||
### 2.2 信号二 · Issue 进度（Burndown）
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state open --format json
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state closed --format json
|
||||
```
|
||||
|
||||
统计：
|
||||
- 开放 / 已关闭 Issue 数；近 4 周新增 vs 关闭（净增 = 新增 − 关闭）
|
||||
- 陈旧 Issue：开放且 `updated_at` 超过 30/60 天
|
||||
- 平均解决时长（closed 的 created→closed 估算）
|
||||
|
||||
**风险规则：**
|
||||
```
|
||||
🔴 近 4 周净增 Issue 持续为正且 > 5 或 陈旧 Issue 占比 > 50%
|
||||
🟡 净增为正但可控
|
||||
🟢 净增 ≤ 0（在收敛）
|
||||
```
|
||||
|
||||
### 2.3 信号三 · 里程碑完成度（Milestone）
|
||||
|
||||
```bash
|
||||
gitlink-cli milestone +list --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
统计每个里程碑：`due_date`、开放/关闭 Issue 数、完成率 = 已关闭 / 总数。
|
||||
|
||||
**风险规则：**
|
||||
```
|
||||
🔴 里程碑已过期（today > due_date）且完成率 < 80%
|
||||
🟡 距到期 < 14 天且完成率 < 60%
|
||||
🟢 按期推进
|
||||
```
|
||||
|
||||
### 2.4 信号四 · PR 吞吐（Throughput）
|
||||
|
||||
```bash
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --format json
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state merged --format json
|
||||
```
|
||||
|
||||
统计：开放 PR 数、近 4 周合并 PR 数、开放 PR 平均停留天数、是否有 PR 挂起 > 14 天。
|
||||
|
||||
**风险规则：**
|
||||
```
|
||||
🔴 存在开放 PR 停留 > 30 天 或 近 4 周 0 合并但有活跃开发
|
||||
🟡 PR 平均停留 14–30 天
|
||||
🟢 PR 流转顺畅
|
||||
```
|
||||
|
||||
### 2.5 信号五 · 团队活跃与 Bus Factor
|
||||
|
||||
```bash
|
||||
# 主数据源：直接返回每人的 contribution_perc（贡献占比），是 Bus Factor 的可靠依据
|
||||
gitlink-cli repo +contributors --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 可选补充（按代码行）：部分仓库后端会返回 [-1] 失败，属正常，失败则忽略、以上面为准
|
||||
gitlink-cli repo +contributor-stats --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
统计：
|
||||
- 活跃贡献者数（结合提交记录判断近 90 天是否活跃）
|
||||
- 贡献集中度：取 `repo +contributors` 返回的 Top1 `contribution_perc` → **Bus Factor 估计**（占比越高，单点风险越大）
|
||||
|
||||
**风险规则：**
|
||||
```
|
||||
🔴 Bus Factor = 1（Top1 占比 > 80%） 或 活跃贡献者 = 1
|
||||
🟡 Top1 占比 60–80%
|
||||
🟢 贡献相对分散
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、进度健康度评级
|
||||
|
||||
### 3.1 综合灯
|
||||
|
||||
将五个信号的红/黄/绿汇总为**项目总灯**：
|
||||
|
||||
```
|
||||
🔴 红灯（高风险）：任一信号为 🔴，或 ≥3 个 🟡
|
||||
🟡 黄灯（需关注）：1–2 个 🟡，无 🔴
|
||||
🟢 绿灯（健康）：全部 🟢
|
||||
```
|
||||
|
||||
### 3.2 提交节奏 ASCII 趋势
|
||||
|
||||
```
|
||||
近 8 周周提交量：
|
||||
W-7 ████████ 12
|
||||
W-6 ██████ 9
|
||||
W-5 █████████ 14
|
||||
W-4 ███ 4
|
||||
W-3 ██ 3
|
||||
W-2 █ 1
|
||||
W-1 ▏ 0 ← 🔴 提交骤降
|
||||
W-0 ▏ 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、《科研进度周报 + 风险预警》报告模板
|
||||
|
||||
```markdown
|
||||
## 📈 科研进度周报与风险预警
|
||||
|
||||
**项目：** <owner>/<repo>
|
||||
**统计周期：** 2026-06-09 ~ 2026-06-15（近 8 周趋势）
|
||||
**生成时间：** 2026-06-15
|
||||
**项目总灯：** 🟡 黄灯（需关注）
|
||||
|
||||
---
|
||||
|
||||
### 一、一句话结论
|
||||
|
||||
> 核心算法仓库提交节奏明显放缓（近 2 周仅 1 次提交），里程碑 M2 距到期 10 天但完成率 55%，建议本周组会重点对齐。
|
||||
|
||||
### 二、五维信号面板
|
||||
|
||||
| 信号 | 指标 | 灯 |
|
||||
|------|------|----|
|
||||
| 提交节奏 | 近 2 周 1 次提交，环比 ↓78% | 🔴 |
|
||||
| Issue 进度 | 开放 14 / 已闭 36，近 4 周净增 +3 | 🟡 |
|
||||
| 里程碑 | M2 完成率 55%，距到期 10 天 | 🟡 |
|
||||
| PR 吞吐 | 开放 2（最久 9 天），近 4 周合并 5 | 🟢 |
|
||||
| 团队 / Bus Factor | 活跃 3 人，Top1 占比 64% | 🟡 |
|
||||
|
||||
### 三、提交节奏趋势
|
||||
|
||||
（插入第 3.2 节 ASCII 趋势图）
|
||||
|
||||
### 四、风险预警清单
|
||||
|
||||
| 等级 | 风险 | 证据 | 建议 |
|
||||
|------|------|------|------|
|
||||
| 🔴 | 主仓库近 2 周近乎停滞 | 最近提交 11 天前 | 组会确认是否受阻/缺人 |
|
||||
| 🟡 | M2 里程碑有延期苗头 | 完成率 55%，10 天到期 | 砍范围或顺延，更新 due_date |
|
||||
| 🟡 | 存在单点依赖 | Top1 提交占比 64% | 安排第二人熟悉核心模块 |
|
||||
| 🟡 | 陈旧 Issue 累积 | 5 个 Issue >30 天未动 | 分诊：关闭/重排期 |
|
||||
|
||||
### 五、本周建议动作（Top 3）
|
||||
|
||||
1. 排查主仓库停滞原因（环境/卡点/人力），必要时拆任务。
|
||||
2. 重新评估 M2 范围与到期日，更新里程碑。
|
||||
3. 指定核心模块第二负责人，降低 Bus Factor。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、执行步骤总览
|
||||
|
||||
```bash
|
||||
# Step 1：确定范围
|
||||
gitlink-cli repo +info --owner <owner> --repo <repo> --format json
|
||||
|
||||
# Step 2：提交节奏
|
||||
gitlink-cli api GET "/:owner/:repo/commits?page=1&limit=50" --format json
|
||||
|
||||
# Step 3：Issue 进度
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state open --format json
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state closed --format json
|
||||
|
||||
# Step 4：里程碑
|
||||
gitlink-cli milestone +list --owner <owner> --repo <repo> --format json
|
||||
|
||||
# Step 5：PR 吞吐
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state open --format json
|
||||
gitlink-cli pr +list --owner <owner> --repo <repo> --state merged --format json
|
||||
|
||||
# Step 6：团队活跃 / Bus Factor（以 +contributors 为主，其 contribution_perc 即 Bus Factor 依据）
|
||||
gitlink-cli repo +contributors --owner <owner> --repo <repo> --format json
|
||||
gitlink-cli repo +contributor-stats --owner <owner> --repo <repo> --format json # 可选，失败可忽略
|
||||
|
||||
# Step 7：AI 按第二节规则打灯、第四节模板出周报
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- ✅ **纯只读**：默认不写任何内容；落成 Issue/评论需用户明确同意。
|
||||
- ✅ **多仓库汇总**：课题组多仓库时，逐仓采集后再出一张"组级总览表"（每行一个仓库 + 总灯）。
|
||||
- ⚠️ **时间字段**：以 `created_at` / `updated_at` / commit date 估算周期；注意时区与"X 天前"等相对时间需换算。
|
||||
- ⚠️ **分页**：Issue/PR/commit 可能分页，统计趋势时关注 `meta.total_count` 并按需翻页（趋势可只取近若干页近似）。
|
||||
- ⚠️ **里程碑可选**：部分科研仓库不用里程碑，则该信号标"不适用"，不计入总灯。
|
||||
- ⚠️ **contributor-stats 容错**：`repo +contributor-stats`（按代码行）在部分仓库会返回 `[-1]` 失败，属正常；Bus Factor 以 `repo +contributors` 的 `contribution_perc` 为准即可。
|
||||
- ✅ **可定期运行**：建议每周固定时间运行，形成可对比的趋势序列；最终产出为 Markdown 周报。
|
||||
|
|
@ -0,0 +1,110 @@
|
|||
# 示例：为课题组科研仓库生成进度周报与风险预警
|
||||
|
||||
本示例演示用 `gitlink-research-progress` 技能跟踪一个科研仓库的进度，并产出《周报 + 风险预警》。命令均为 gitlink-cli 真实命令，可复现。
|
||||
|
||||
> 实际使用时把 `someorg/algo-core` 替换为目标仓库；数值以实际采集为准。
|
||||
|
||||
---
|
||||
|
||||
## 一、Agent 对话片段
|
||||
|
||||
```
|
||||
用户：帮我看看 someorg/algo-core 这周进展怎么样，有没有要预警的？
|
||||
|
||||
Agent：好的，我用 gitlink-research-progress 技能采集近 8 周的提交/Issue/里程碑/PR/贡献数据，
|
||||
打风险灯并生成周报，全程只读。开始……
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、采集命令序列
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner someorg --repo algo-core --format json
|
||||
|
||||
# 提交节奏
|
||||
gitlink-cli api GET "/someorg/algo-core/commits?page=1&limit=50" --format json
|
||||
|
||||
# Issue 进度
|
||||
gitlink-cli issue +list --owner someorg --repo algo-core --state open --format json
|
||||
gitlink-cli issue +list --owner someorg --repo algo-core --state closed --format json
|
||||
|
||||
# 里程碑
|
||||
gitlink-cli milestone +list --owner someorg --repo algo-core --format json
|
||||
|
||||
# PR 吞吐
|
||||
gitlink-cli pr +list --owner someorg --repo algo-core --state open --format json
|
||||
gitlink-cli pr +list --owner someorg --repo algo-core --state merged --format json
|
||||
|
||||
# 团队 / Bus Factor
|
||||
gitlink-cli repo +contributors --owner someorg --repo algo-core --format json
|
||||
gitlink-cli repo +contributor-stats --owner someorg --repo algo-core --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、信号归集（Agent 内部记录）
|
||||
|
||||
| 信号 | 采集结果 | 灯 |
|
||||
|------|----------|----|
|
||||
| 提交节奏 | 近 2 周 1 次提交，最近提交 11 天前，环比 ↓78% | 🔴 |
|
||||
| Issue | 开放 14 / 已闭 36，近 4 周净增 +3，5 个 >30 天未动 | 🟡 |
|
||||
| 里程碑 | M2 完成率 55%，距到期 10 天 | 🟡 |
|
||||
| PR | 开放 2（最久 9 天），近 4 周合并 5 | 🟢 |
|
||||
| Bus Factor | 活跃 3 人，Top1 占比 64% | 🟡 |
|
||||
|
||||
→ **项目总灯：🔴 红灯。** 依据 SKILL.md 第三节规则「任一信号为 🔴 即红灯」：提交节奏命中「近 2 周提交为 0~1 次」判 🔴，故总灯为红。
|
||||
|
||||
---
|
||||
|
||||
## 四、生成的周报（样例输出）
|
||||
|
||||
```markdown
|
||||
## 📈 科研进度周报与风险预警
|
||||
|
||||
**项目：** someorg/algo-core
|
||||
**统计周期：** 2026-06-09 ~ 2026-06-15（近 8 周趋势）
|
||||
**项目总灯：** 🔴 红灯（高风险）
|
||||
|
||||
### 一、一句话结论
|
||||
> 主仓库近 2 周近乎停滞（最近提交 11 天前），M2 里程碑有延期苗头，存在单点依赖，建议本周组会重点处理。
|
||||
|
||||
### 二、五维信号面板
|
||||
| 信号 | 指标 | 灯 |
|
||||
|------|------|----|
|
||||
| 提交节奏 | 近 2 周 1 次，环比 ↓78%，最近 11 天前 | 🔴 |
|
||||
| Issue 进度 | 开放 14 / 已闭 36，近 4 周净增 +3 | 🟡 |
|
||||
| 里程碑 | M2 完成率 55%，距到期 10 天 | 🟡 |
|
||||
| PR 吞吐 | 开放 2（最久 9 天），近 4 周合并 5 | 🟢 |
|
||||
| 团队 / Bus Factor | 活跃 3 人，Top1 占比 64% | 🟡 |
|
||||
|
||||
### 三、提交节奏趋势
|
||||
近 8 周周提交量：
|
||||
W-7 ████████ 12
|
||||
W-6 ██████ 9
|
||||
W-5 █████████ 14
|
||||
W-4 ███ 4
|
||||
W-3 ██ 3
|
||||
W-2 █ 1
|
||||
W-1 ▏ 0 ← 🔴
|
||||
W-0 ▏ 1
|
||||
|
||||
### 四、风险预警清单
|
||||
| 等级 | 风险 | 建议 |
|
||||
|------|------|------|
|
||||
| 🔴 | 主仓库近 2 周停滞 | 组会确认卡点/人力 |
|
||||
| 🟡 | M2 延期苗头（55%/10天） | 砍范围或顺延 |
|
||||
| 🟡 | 单点依赖（Top1 64%） | 安排第二负责人 |
|
||||
| 🟡 | 5 个陈旧 Issue | 分诊：关闭/重排 |
|
||||
|
||||
### 五、本周建议动作（Top 3）
|
||||
1. 排查主仓库停滞原因，必要时拆任务。
|
||||
2. 重新评估 M2 范围与到期日。
|
||||
3. 指定核心模块第二负责人，降低 Bus Factor。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、可选：定期化
|
||||
|
||||
把上述命令封装为脚本，配合外部定时器（cron / CI 定时任务）每周一运行，即可得到可纵向对比的进度趋势序列。
|
||||
Loading…
Reference in New Issue