From 6565c7bc61e6f3e0de36e61113c3f556f7b4e766 Mon Sep 17 00:00:00 2001 From: luwanzhou Date: Mon, 15 Jun 2026 10:44:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20add=20gitlink-research-progress?= =?UTF-8?q?=20=E2=80=94=20=E7=A7=91=E7=A0=94=E8=BF=9B=E5=BA=A6=E8=B7=9F?= =?UTF-8?q?=E8=B8=AA=E4=B8=8E=E9=A2=84=E8=AD=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增科研进度智能跟踪与预警 Skill：监控科研仓库的提交节奏、Issue 解决进度、 里程碑完成度、PR 吞吐与贡献者活跃度（Bus Factor），用红/黄/绿灯标记停滞与 风险，自动生成《科研进度周报 + 风险预警》。 - SKILL.md：五维进度信号、风险规则、综合灯与提交趋势图、周报模板、执行步骤 - examples/progress-workflow.md：真实命令驱动的周报生成示例 子赛题四（科研辅助）。纯 Markdown，只读分析型。 --- skills/gitlink-research-progress/SKILL.md | 261 ++++++++++++++++++ .../examples/progress-workflow.md | 110 ++++++++ 2 files changed, 371 insertions(+) create mode 100644 skills/gitlink-research-progress/SKILL.md create mode 100644 skills/gitlink-research-progress/examples/progress-workflow.md diff --git a/skills/gitlink-research-progress/SKILL.md b/skills/gitlink-research-progress/SKILL.md new file mode 100644 index 0000000..0ffb446 --- /dev/null +++ b/skills/gitlink-research-progress/SKILL.md @@ -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 --repo --format json + +# 课题组/组织名下多个仓库（逐个跟踪后汇总） +gitlink-cli repo +list --user --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 --repo --state open --format json +gitlink-cli issue +list --owner --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 --repo --format json +``` + +统计每个里程碑：`due_date`、开放/关闭 Issue 数、完成率 = 已关闭 / 总数。 + +**风险规则：** +``` +🔴 里程碑已过期（today > due_date）且完成率 < 80% +🟡 距到期 < 14 天且完成率 < 60% +🟢 按期推进 +``` + +### 2.4 信号四 · PR 吞吐（Throughput） + +```bash +gitlink-cli pr +list --owner --repo --state open --format json +gitlink-cli pr +list --owner --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 --repo --format json + +# 可选补充（按代码行）：部分仓库后端会返回 [-1] 失败，属正常，失败则忽略、以上面为准 +gitlink-cli repo +contributor-stats --owner --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 +## 📈 科研进度周报与风险预警 + +**项目：** / +**统计周期：** 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 --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 --repo --state open --format json +gitlink-cli issue +list --owner --repo --state closed --format json + +# Step 4：里程碑 +gitlink-cli milestone +list --owner --repo --format json + +# Step 5：PR 吞吐 +gitlink-cli pr +list --owner --repo --state open --format json +gitlink-cli pr +list --owner --repo --state merged --format json + +# Step 6：团队活跃 / Bus Factor（以 +contributors 为主，其 contribution_perc 即 Bus Factor 依据） +gitlink-cli repo +contributors --owner --repo --format json +gitlink-cli repo +contributor-stats --owner --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 周报。 diff --git a/skills/gitlink-research-progress/examples/progress-workflow.md b/skills/gitlink-research-progress/examples/progress-workflow.md new file mode 100644 index 0000000..a03f0b4 --- /dev/null +++ b/skills/gitlink-research-progress/examples/progress-workflow.md @@ -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 定时任务）每周一运行，即可得到可纵向对比的进度趋势序列。