forked from Gitlink/gitlink-cli
141 lines
4.0 KiB
Markdown
141 lines
4.0 KiB
Markdown
# 场景 5：科研进度智能跟踪与预警
|
||
|
||
## 目标
|
||
|
||
跟踪科研项目的开发进度，检测异常信号，生成周报和早期预警。
|
||
|
||
## 参数
|
||
|
||
| 参数 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `--owner` | 是 | 仓库所有者 |
|
||
| `--repo` | 是 | 仓库名称 |
|
||
| `--org` | 否 | 组织名称（多仓库模式） |
|
||
| `--weeks` | 否 | 回溯周数（默认 4） |
|
||
| `--output` | 否 | 输出文件路径 |
|
||
|
||
## 数据收集步骤
|
||
|
||
### Step 1: Issue 数据
|
||
```bash
|
||
gitlink-cli issue +list --owner $OWNER --repo $REPO --state open --limit 100 --format json
|
||
gitlink-cli issue +list --owner $OWNER --repo $REPO --state closed --limit 100 --format json
|
||
```
|
||
提取：
|
||
- 每个 Issue 的状态、创建时间、更新时间、标签
|
||
- 按周统计创建数/关闭数
|
||
- 识别停滞 Issue（open + 60天无更新）
|
||
- 识别未分配 Issue
|
||
|
||
### Step 2: PR 数据
|
||
```bash
|
||
gitlink-cli pr +list --owner $OWNER --repo $REPO --state merged --limit 100 --format json
|
||
gitlink-cli pr +list --owner $OWNER --repo $REPO --state open --limit 50 --format json
|
||
```
|
||
提取：
|
||
- 按周统计合并数/新建数
|
||
- 开放 PR 的平均年龄
|
||
- PR 瓶颈检测：开放 > 5 且平均年龄 > 14 天
|
||
|
||
### Step 3: Release 数据
|
||
```bash
|
||
gitlink-cli release +list --owner $OWNER --repo $REPO --limit 20 --format json
|
||
```
|
||
- 计算发布间隔
|
||
- 检测长期无发布（> 180 天）
|
||
|
||
### Step 4: CI 数据
|
||
```bash
|
||
gitlink-cli ci +builds --owner $OWNER --repo $REPO --limit 20 --format json
|
||
```
|
||
- 构建成功率
|
||
- 最近失败次数
|
||
|
||
### Step 5: 多仓库模式（可选）
|
||
如果指定 `--org`：
|
||
```bash
|
||
gitlink-cli repo +list --user $ORG --limit 50 --format json
|
||
```
|
||
对每个仓库执行 Step 1-4，生成聚合报告。
|
||
|
||
## 健康评分
|
||
|
||
```
|
||
Health = issue_velocity * 0.30
|
||
+ pr_merge_rate * 0.25
|
||
+ milestone_ok * 0.25
|
||
+ release_cadence * 0.10
|
||
+ activity_trend * 0.10
|
||
```
|
||
|
||
### issue_velocity
|
||
```
|
||
velocity = issues_closed_28d / 28
|
||
score = min(velocity / 1.0, 1.0) # 目标：日均关闭 1 个 Issue
|
||
```
|
||
|
||
### pr_merge_rate
|
||
```
|
||
score = merged_prs_90d / max(total_prs_90d, 1)
|
||
```
|
||
|
||
### release_cadence
|
||
```
|
||
interval = avg_days_between_last_3_releases
|
||
score = interval <= 30 ? 1.0 : interval <= 90 ? 0.5 : interval <= 180 ? 0.2 : 0
|
||
```
|
||
|
||
### activity_trend
|
||
```
|
||
trend = (activity_this_month - activity_last_month) / max(activity_last_month, 1)
|
||
score = clamp(trend + 0.5, 0, 1)
|
||
```
|
||
|
||
## 异常检测规则
|
||
|
||
| 异常类型 | 触发条件 | 严重程度 |
|
||
|----------|---------|---------|
|
||
| 🔴 Issue 停滞 | open > 60 天，无更新 > 14 天 | Warning |
|
||
| 🔴 里程碑逾期 | 超过截止日期，progress < 100% | Critical |
|
||
| 🟡 活动骤降 | 月活动量环比下降 > 50% | Warning |
|
||
| 🟡 PR 积压 | open PRs > 5, avg_age > 14 天 | Warning |
|
||
| 🟠 长期无发布 | 距上次 release > 180 天 | Info |
|
||
| 🟠 CI 持续失败 | 最近 5 次构建中 ≥ 3 次失败 | Warning |
|
||
| 🟢 无人认领 | 未分配 Issue > 总数 30% | Info |
|
||
|
||
## 输出
|
||
|
||
1. **HTML 周报** (`output/progress-weekly-{date}.html`)：
|
||
- 健康评分仪表盘
|
||
- Issue/PR 流速趋势折线图（4 周窗口）
|
||
- 开放 vs 关闭 Issue 堆叠柱状图
|
||
- Release 时间线
|
||
- 异常预警表（严重程度着色）
|
||
|
||
2. **Wiki Markdown** — 周报摘要 + 异常列表
|
||
|
||
3. **控制台摘要** — 关键指标一目了然
|
||
|
||
## 可执行脚本
|
||
|
||
```bash
|
||
# 单仓库
|
||
bash workflows/10-research-progress.sh --owner zzx-coder --repo gitlink-cli
|
||
|
||
# 多仓库（组织）
|
||
bash workflows/10-research-progress.sh --org zzx-coder --weeks 4
|
||
```
|
||
|
||
## 风险管理建议
|
||
|
||
对于检测到的异常，自动生成建议：
|
||
|
||
| 异常 | 建议 |
|
||
|------|------|
|
||
| Issue 停滞 | 重新评估优先级，关闭或推进；通知负责人 |
|
||
| 里程碑逾期 | 重新规划里程碑时间表；拆分为更小的子任务 |
|
||
| 活动骤降 | 检查团队是否有阻塞因素；组织一次同步会议 |
|
||
| PR 积压 | 安排 Code Review 时间；简化 PR 粒度 |
|
||
| 长期无发布 | 考虑发布当前 master 的最小可用版本 |
|
||
| CI 持续失败 | 优先修复 CI；暂时阻止新 PR 合并直到 CI 恢复 |
|