---
name: gitlink-research-progress
version: 1.0.0
description: "科研进度跟踪与预警：纯远程只读分析一个 GitLink 仓库的 Issue 时间序列与提交活跃度，识别长期停滞、高优先级无人认领、积压恶化、活跃度突变等科研仓库特有时间线风险，输出证据导向的预警清单。当用户需要判断某个科研/论文复现仓库的进度卡在哪、有没有风险信号、是否停滞时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli issue --help"
---

# gitlink-research-progress（科研进度跟踪与预警）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 本 Skill 全程只读，不向仓库写任何内容（不建 Issue、不评论、不改仓库——科研预警应尊重他人仓库）。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`，禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**

## 说明

本 Skill 面向**科研场景**，回答一个 `gitlink-project-health` 回答不了的问题：**这个科研仓库，时间线上卡在哪了、有没有可量化的风险信号？**

它**委托** `gitlink-project-health` 跑通用静态健康度（关闭率/活跃度评分），自己专注科研特有的**时间线风险预警**：长期停滞的未解决 Issue、高优先级问题无人认领、积压趋势恶化、提交活跃度突变。两者正交，不重复。

**产物哲学（重要）**：输出的是**证据导向的预警清单**，不是单一健康分数。每条预警先呈现"看到了什么信号"（具体 Issue #、停留天数、提交分布），再给 🔴/🟡/🟢 风险等级和科研影响解读。**不替读者下绝对结论，不做主观判断**（如"作者弃坑"），只呈现可量化证据。

## 与 `gitlink-project-health` 的边界

| 维度 | `gitlink-project-health`（被委托） | `gitlink-research-progress`（本 Skill） |
|---|---|---|
| 核心问题 | 项目**当前**总体健康度（静态快照） | 项目**时间线上的风险信号**（动态预警） |
| 指标性质 | 静态汇总：平均响应时间、合并率、活跃度评分 | 动态风险检测：停滞/突击/积压趋势信号 |
| 视角 | 通用软件项目健康度 | **科研/论文复现仓库特有的时间线风险** |
| 时间维度 | 现状快照（单点） | 时间序列（停留天数、速率对比、趋势方向） |
| 输出 | 健康度评分报告（0-10 分） | **预警清单**（🔴/🟡/🟢 + 证据 + 科研影响 + 建议动作） |
| 关系 | 上游信号（健康度基线） | **编排者 + 风险预警裁决** |

> 职责正交：project-health 问"现在健不健康"，本 Skill 问"时间线上有没有该亮红灯的风险"。可串联。

## ⚠️ GitLink 数据现实（务必理解，否则预警会落空）

本 Skill 的设计建立在一次充分探查之上，以下结论决定性地约束了预警维度：

| 数据维度 | GitLink 现状 | 应对 |
|---|---|---|
| 里程碑（`milestone +list`）| 几乎无人使用（多数仓库 `total_count=0`）| 信号⑥ 设为**可选**：无数据则跳过并说明 |
| Issue 的 `due_date`/`done_ratio`/`start_date` | 普遍为空 | **不依赖**这些字段做预警 |
| Issue 的 `status` | GitLink 用**中文 status name**：`新增`/`关闭`/`已解决` | 按 status.name 客户端判"未解决" |
| 标签 | 是"缺陷/疑问/任务"分类标签，非科研阶段/DDL | 不依赖标签做阶段判断 |
| Issue 时间序列（created_at/updated_at）| ✅ 可靠可用 | 信号①②③④ 的数据基础 |
| 提交时间序列（commit_time）| ✅ 可靠可用（秒级时间戳）| 信号⑤ 的数据基础 |

> 因此本 Skill **不以里程碑 DDL 为核心**（数据客观缺失），而以 Issue 时间序列 + 提交活跃度为预警锚点。这是 GitLink 平台现实决定的务实选择。

## 前置条件

- 已 `gitlink-cli auth login`（`auth status` 为已登录）。
- 目标是 GitLink 上的公开仓库（科研/开源项目均可，有 Issue 或提交历史才有预警价值）。
- （可选）读过 [`../gitlink-project-health/SKILL.md`](../gitlink-project-health/SKILL.md)，便于委托其健康度层。

## ⚠️ 关键接口坑（已实测，务必遵守）

| 坑 | 说明 | 正确做法 |
|---|---|---|
| **status 是中文对象** | `status` 字段是 `{id, name, pm_color}`，name 为 `新增`/`关闭`/`已解决` | 判"未解决" = `status.name not in ['关闭','已解决']`，**禁止**用 GitHub 的 open/closed |
| **closed_count 不可靠** | `issue +list --state all` 的 `closed_count` 字段实测可为 0 但实际有已关闭 Issue | 一律按 `status.name` 客户端重新统计 |
| **commit_time 是秒戳** | `commit_time` 是 Unix 秒级时间戳（如 `1608186196`），非 ISO 字符串 | 用 `datetime.fromtimestamp(t)` 转换算日期 |
| **commit +list 返回数可能少于 limit** | 仓库提交总数本身不多时，`--limit 50` 实际返回可能 <50 | 按实际返回数计算，不硬假设 50 条 |
| **assigners 是数组** | `assigners` 为数组 `[]`，空数组=无人认领 | 判"无人认领" = `len(assigners)==0`，不当 null |
| **assigners 为空是常态** | GitLink 多数 Issue assigners 实测为空 | 信号② 触发时结合 priority 双重确认，避免误报 |

## 工作流概览

| 步骤 | 操作 | 命令 |
|------|------|------|
| ① 仓库元信息 | 取创建/更新时间、issue/pr 计数 | `repo +info` |
| ② 健康度基线（委托） | 取静态关闭率/活跃度评分 | 委托 `gitlink-project-health` |
| ③ Issue 全量采集 | 全部 Issue 的 created_at/status/priority | `issue +list --state all` |
| ④ 提交活跃度 | 近 50 提交时间序列 + 贡献者 | `commit +list --limit 50` |
| ⑤ 里程碑（可选） | 有里程碑才做 DDL 预警 | `milestone +list` |
| ⑥ 风险信号分析 | 对 5+1 类信号逐一计算判级 | （纯计算，无命令）|
| ⑦ 综合预警裁决 | 汇总成预警清单 + 趋势概览 | （分析，无命令）|

> 全程只读，零写操作。串联 ≥6 个 CLI 调用。

---

## 详细工作流

### Step ① 仓库元信息

```bash
gitlink-cli repo +info --owner <o> --repo <r> --format json
```

记录：`created_at`、`updated_at`、`issues_count`、`pull_requests_count`、`default_branch`、`forked_from_project_id`（是否镜像仓库——镜像仓库的 GitLink Issue 数据可能不完整，需在报告里注明）。

### Step ② 健康度基线（委托 `gitlink-project-health`）

本 Skill 不重复算静态健康度，**委托**已有 skill：

> 按 [`../gitlink-project-health/SKILL.md`](../gitlink-project-health/SKILL.md) 的「数据采集与分析」执行，取回其**关闭率**与**活跃度评分**作为基线。

本 Skill 在此基础上叠加**动态趋势分析**（project-health 只看静态比例，本 Skill 看近 30 天净变化——见信号④）。

### Step ③ Issue 全量采集（核心数据）

```bash
gitlink-cli issue +list --owner <o> --repo <r> --state all --format json
#   → data.issues[]，每条关键字段：
#     number / subject / status{name} / created_at / updated_at
#     priority_name / comment_journals_count / assigners[] / author{login}
```

**必做的客户端重统计**（因 closed_count 不可靠）：
- 遍历 issues，按 `status.name` 分组：`新增`=未解决，`关闭`/`已解决`=已解决。
- 对每个未解决 Issue，算 `停留天数 = today - created_at`（created_at 形如 `2026-06-14 18:46`）。

### Step ④ 提交活跃度

```bash
gitlink-cli commit +list --owner <o> --repo <r> --limit 50 --format json
#   → 每条含 commit_time（秒戳）/ author.login / commit_message
#   → 按 commit_time 转日期，统计：近 30 天提交数 vs 前 30 天提交数、unique author 数
```

### Step ⑤ 里程碑（可选维度）

```bash
gitlink-cli milestone +list --owner <o> --repo <r> --format json
#   → data.total_count == 0 → 跳过信号⑥，报告注明"未启用里程碑管理"
#   → 非空 → 取每个里程碑的 effective_date(DDL) 与 percent(完成度) 做逾期/未完成预警
#   ⚠️ GitLink 里程碑字段：effective_date(生效日期=DDL，非 due_date)、percent(0-1 完成度)、
#      issues_count/close_issues_count/opened_issues_count、status(open/closed)
#   ⚠️ 单条 Issue 的 milestone_id 实测为 null，里程碑下 Issue 数从 milestone +list 取
```

### Step ⑥ 风险信号分析（纯计算，见下一节规则）

对照「风险信号维度与判定规则」，对采集到的数据逐一计算每个信号的触发情况与等级。

### Step ⑦ 综合预警裁决

汇总成《科研进度预警报告》（见报告模板）。**先证据，后等级**；无数据的维度显式标注"无数据"而非省略。

## 风险信号维度与判定规则（科研独有核心）

每条信号输出 = **[信号证据] + [风险等级 🔴/🟡/🟢] + [科研影响] + [建议动作]**。阈值按仓库规模可调（小仓库可适度放宽，在报告里注明调整）。

### 信号① 长期停滞的未解决 Issue

- **计算**：对每个未解决 Issue（`status.name not in ['关闭','已解决']`），算 `today - created_at`。
- **阈值**：存在停留 >60 天的 → 🔴；仅 30-60 天 → 🟡；全部 <30 天 → 🟢。
- **科研影响**：复现失败/实验卡住的典型信号——问题晾着往往意味着方法走不通或无人能解。
- **建议动作**：逐条列出 >30 天的 Issue（#编号 + 停留天数 + 主题），建议复现者评估是否阻塞关键路径。

### 信号② 高优先级问题无人认领

- **计算**：`priority_name == '高'` 且 `len(assigners)==0` 的未解决 Issue。
- **阈值**：存在 1 个 → 🟡；>1 个 → 🔴；无 → 🟢。
- **科研影响**：关键技术障碍无人接手，瓶颈卡死。
- **建议动作**：列出这些 Issue，提示需要分配负责人或社区协助。

### 信号③ 未解决且零响应

- **计算**：未解决 + `comment_journals_count == 0`。
- **阈值**：存在 1-2 个 → 🟡；>2 个 → 🔴；无 → 🟢。
- **科研影响**：问题被晾，无社区讨论（冷门方向常见，也可能是问题表述不清）。
- **建议动作**：列出零响应 Issue，建议补充复现步骤吸引响应。

### 信号④ 积压趋势（关闭速率 vs 新增速率）

- **计算**：按 `status.name` 统计「近 30 天新增数」与「近 30 天关闭/已解决数」，算净变化 = 新增 - 关闭。
- **阈值**：净增 >3 → 🔴（积压恶化）；-2~+3 → 🟡（平稳）；< -2 → 🟢（消化中）。
- **科研影响**：积压恶化说明问题增长快于解决速度，项目可能正失控。
- **与 project-health 的区别**：project-health 算静态"关闭率"（比例），本信号算"近 30 天净变化"（趋势方向）。
- **建议动作**：报告近 30 天新增/关闭数值与净变化，提示趋势方向。

### 信号⑤ 提交活跃度突变

- **计算**：近 30 天提交数 vs 前 30 天提交数，算变化率；另算近 50 提交的 unique author 数。
- **阈值**：近 30 天 0 提交 → 🔴；下降 >50% → 🟡；其他 → 🟢。
- **附注（bus factor）**：近 50 提交 unique author 数 <2 时，在该信号下附注 "⚠️ 高度依赖单一贡献者"。
- **科研影响**：突击后停滞是赶 DDL 的典型模式；持续无提交可能意味着项目已搁置。
- **建议动作**：报告提交日期分布与变化率，提示活跃度走向。

### 信号⑥ 里程碑 DDL（可选，有数据时启用）

- **计算**：仅当 `milestone +list` 返回非空时；取每个里程碑 `effective_date`（GitLink 的 DDL 字段，非 due_date）与今天对比，结合 `percent`（完成度 0-1）判断。
- **阈值**：`effective_date` 已过且 `percent<1`（逾期未完成）→ 🔴；7 天内到期且未完成 → 🟡；远期或已完成(`percent=1`)或无 `effective_date` → 🟢。
- **无数据时**：报告显式标注「该仓库未启用里程碑管理，信号⑥无数据」，**不**当错误处理。
- **实测参考**：GitLink 上启用里程碑的仓库极少（forgeplus 是已知样本，4 个里程碑中 2 个 effective_date 逾期近 2.5 年且 percent 卡在 93%）。

## 《科研进度预警报告》模板

```
🚨 科研进度预警报告 — <owner>/<repo>
═══════════════════════════════════════════════════
报告日期: <YYYY-MM-DD>   仓库创建: <created_at>   最近更新: <updated_at>
健康度基线（委托 project-health）: 关闭率 <X%> / 活跃度 <score>
分析方式: 纯远程只读（gitlink-cli issue/commit/milestone/repo）
说明: 本报告呈现项目时间线上的风险信号，由读者结合自身对项目的了解自行判断；
      风险等级与评分仅作辅助参考，不构成绝对结论。

═══════════════════════════════════════════════════
📊 预警清单（按风险等级 🔴→🟡→🟢 排序）
═══════════════════════════════════════════════════

【🔴 高风险】<信号名称>
  信号证据:
    • <具体 Issue #、停留天数、数值等客观事实>
  科研影响: <这个信号在科研场景里意味着什么>
  建议动作: <可操作的下一步>

【🟡 中风险】<信号名称>
  信号证据: ...
  科研影响: ...
  建议动作: ...

【🟢 正常】<信号名称>
  信号证据: <达标的事实>
  说明: <为什么无风险>

【— 无数据】信号⑥ 里程碑 DDL（如适用）
  原因: milestone +list 返回 total_count=0，该仓库未启用里程碑管理。

═══════════════════════════════════════════════════
📈 总体趋势概览
═══════════════════════════════════════════════════
  • 积压趋势: <近 30 天净变化，恶化/消化中/平稳>
  • 提交活跃度: <近 30 天 vs 前 30 天，上升/下降/平稳>
  • 关注焦点: <最该优先处理的 1-2 条预警精炼总结>

═══════════════════════════════════════════════════
参考性风险评分（辅助总结，请以上方证据为准自行判断）
  ① 停滞风险    __/25   ② 资源未就位  __/20
  ③ 响应沉寂    __/15   ④ 积压趋势    __/20
  ⑤ 活跃度突变  __/20   ⑥ 里程碑(可选) +10
  参考风险总分: __/100（越高风险越大，0=全维度无风险）
  参考预警等级: 🔴高(>60) / 🟡中(30-60) / 🟢低(<30)
  (仅供索引，不代表项目绝对成败)
═══════════════════════════════════════════════════
```

### 评分规则（风险累加模型）

每个维度是"风险分"，**触发风险才得分，0 分=无风险**，总分越高风险越大：

| 信号 | 风险上限 | 触发即得分（累加，超上限封顶）|
|---|---|---|
| ① 停滞风险 | 25 | 存在 >60 天未解决 +25；仅 30-60 天 +12；无 >30 天 +0 |
| ② 资源未就位 | 20 | 高优先级无人认领，每个 +10（上限 20）|
| ③ 响应沉寂 | 15 | 未解决且 0 评论，每个 +5（上限 15）|
| ④ 积压趋势 | 20 | 净增 >3 +20；-2~+3 +10；< -2 +0 |
| ⑤ 活跃度突变 | 20 | 近 30 天 0 提交 +20；下降 >50% +10 |
| ⑥ 里程碑（可选）| +10 | 有里程碑且逾期 +10；未启用则不计入 100 分基础 |

> 总分上限 100。分数只是辅助索引，报告主体是预警清单证据。

## 使用示例

三份 example 形成"里程碑启用 vs 无里程碑活跃仓 vs 归档降级"的完整对照：

- [`examples/progress-alert-forgeplus.md`](examples/progress-alert-forgeplus.md)：**主验证仓** `Gitlink/forgeplus`（4246 Issue + 4 里程碑，**信号⑥首次启用**，🔴高风险）
- [`examples/progress-alert-gitlink-cli.md`](examples/progress-alert-gitlink-cli.md)：`Gitlink/gitlink-cli`（活跃工具仓，无里程碑→信号⑥降级，🟡中风险）
- [`examples/progress-alert-fairmot.md`](examples/progress-alert-fairmot.md)：`ifzhang/FairMOT`（已归档/数据稀疏仓，降级输出，🟡中风险）

## 注意事项

- 本 Skill **全程只读**，不写仓库、不建 Issue、不评论——科研预警应尊重他人仓库。
- **不做主观判断**（如"作者弃坑"），只呈现可量化的时间线证据，风险结论由读者结合证据自行判断。
- **数据稀疏仓库**（如已归档、Issue/提交极少）不要拒绝分析，而是降级：能算的信号照算，无数据的维度显式标注，这本身就是有价值的预警（"项目已停滞"）。
- 阈值按仓库规模可调：Issue 总数 <10 的小仓库，停滞阈值可适度放宽（如 60 天 → 90 天），并在报告里注明调整理由。
- 镜像仓库（`forked_from_project_id` 非空）的 GitLink Issue 数据可能不完整，需在报告里注明"协作历史可能在源仓库"。

## 已知限制

- GitLink 里程碑普遍无人使用，信号⑥ 在多数仓库无数据（设计为可选维度，无数据时降级跳过）。少数仓库（如 `Gitlink/forgeplus`）启用里程碑，此时信号⑥真正生效。
- Issue 的 due_date/done_ratio 普遍为空，本 Skill 不依赖它们。
- 提交活跃度仅看近 50 条（`--limit 50`），超大型仓库的长期趋势需多次调用分页（本 skill 取近况足够）。
- 趋势分析依赖 created_at/commit_time 时间戳的准确性，若仓库历史时间戳异常需在报告里注明。
