# 科研辅助场景使用文档

> 子任务四 · 5 大科研辅助模块完整使用指南
> 最后更新：2026-07-04
> 全程只读，可放心对任意公开仓库运行

## 目录

1. [模块 A：科研项目洞悉](#模块-a科研项目洞悉)
2. [模块 B：热点追踪与知识图谱](#模块-b热点追踪与知识图谱)
3. [模块 C：科研合规与复现性](#模块-c科研合规与复现性)
4. [模块 D：科研协作智能匹配](#模块-d科研协作智能匹配)
5. [模块 E：科研进度跟踪与预警](#模块-e科研进度跟踪与预警)
6. [委托模式说明](#委托模式说明)

---

## 模块 A：科研项目洞悉

### 功能

回答"这个科研项目怎么样？"——采集 8 维数据，做 4 维评分，生成 HTML 报告。

### 使用方法

```bash
# 基本用法
cd skills/gitlink-research-insight/scripts
DRY_RUN=true bash research-insight-full.sh z2_cc gitlink-cli

# 实际运行（生成报告）
bash research-insight-full.sh z2_cc gitlink-cli
```

### 8 维数据采集

| 维度 | 数据来源 | 示例 |
|------|----------|------|
| 仓库信息 | `repo +info` | name/default_branch/size |
| 主题标签 | `repo +info` → topics | gitlink/cli/tools |
| 语言分布 | `repo +info` → languages | Go 70.1%/JS 22.7%/Shell 6.7% |
| 贡献者 | `repo +contributors` | 16 人 |
| 提交记录 | `commit +list --limit 100` | 100 条 |
| Issue | `issue +list --state all` | 17 个 |
| PR | `pr +list --state all` | 2 个 |
| 协作者 | `collaborator +list` | 3 人 |

### 4 维评分模型

| 维度 | 权重 | 子维度 |
|------|------|--------|
| 成熟度 | 25% | 年龄(25%)+影响力(25%)+Fork(20%)+维护(30%) |
| 文档质量 | 20% | README+LICENSE+CI+CHANGELOG |
| 贡献模式 | 30% | 贡献者数量+质量 |
| 社区健康度 | 25% | Issue 关闭率+PR 合并率+响应速度 |

### 验证结果（z2_cc/gitlink-cli）

| 维度 | 评分 | 说明 |
|------|------|------|
| 成熟度 | 2.8/10 | 0 个月、0 Star、2 Fork，早期阶段 |
| 文档质量 | 5.0/10 | 有 README 缺 LICENSE 和 CI |
| 贡献模式 | 6.8/10 | 16 人协作良好 |
| 社区健康度 | 4.4/10 | Issue 关闭率低 |
| **综合** | **4.8/10** | — |

### 产物

`_output/research-insight-report.html` — 交互式 HTML 报告

---

## 模块 B：热点追踪与知识图谱

### 功能

回答"这个领域有哪些相关项目？"——多关键词搜索 → 实体关系提取 → 交互式知识图谱。

### 使用方法

```bash
cd skills/gitlink-research-hotspot/scripts
bash hotspot-full.sh gitlink CLI
# 参数：关键词1 关键词2 ...（支持任意数量）
```

### 工作流程

1. **多关键词搜索**：搜索"gitlink"+"CLI"，去重后 21 个仓库
2. **数据丰富**：采集每个仓库的 Star/Fork/语言/主题/组织
3. **实体识别**：项目 21 | 主题 4 | 技术栈 2 | 组织 4
4. **关系提取**：belongs_to / topic / language / depends_on
5. **可视化**：Mermaid 知识图谱 + HTML 交互式渲染

### 验证结果

搜索"gitlink"+"CLI"找到 21 个仓库，构建知识图谱：
- 4 主题：java / dockerfile / batchfile / swift
- 2 技术栈：Go / Java
- 4 组织：Gitlink / wangtao / otto / mozilong
- 4 种关系：belongs_to / topic / language / depends_on

### 产物

- `_output/knowledge-graph-gitlink.html` — 交互式知识图谱（支持缩放/拖拽/点击高亮）
- `_output/hotspot-trend-report-gitlink.html` — 热点趋势报告

---

## 模块 C：科研合规与复现性

### 功能

回答"这个科研仓库别人能跑出一样结果吗？"——三维复现性证据链审查。

### 使用方法

```bash
cd skills/gitlink-research-compliance
# 按 SKILL.md 步骤执行（全程只读）
gitlink-cli repo +info --owner ifzhang --repo FairMOT --format json
gitlink-cli file +get --owner ifzhang --repo FairMOT --path LICENSE --format json
gitlink-cli file +readme --owner ifzhang --repo FairMOT --format json
gitlink-cli dataset +list --owner ifzhang --repo FairMOT --format json
gitlink-cli release +list --owner ifzhang --repo FairMOT --format json
```

### 三维复现性证据链

| 维度 | 检查项 | 命令 |
|------|--------|------|
| ① 数据可用性 | dataset +list / README 数据说明 / 是否随仓托管 | `dataset +list` / `file +readme` |
| ② 环境可复现 | requirements.txt / Dockerfile / CI / 依赖锁定 | `file +get --path requirements.txt` |
| ③ 结果可验证 | release 权重 / 测试脚本 / 指标一致性 | `release +list` |

### 委托模式

委托 `gitlink-compliance` 跑通用合规层（LICENSE/依赖/版权），自研复现性证据链。两者正交不重复。

### 验证结果（ifzhang/FairMOT）

| 维度 | 发现 | 等级 |
|------|------|------|
| 合规 | MIT License · Copyright (c) 2020 YifuZhang | ✅ |
| 数据 | README 给下载来源，未随仓托管 | ⚠️ |
| 环境 | requirements.txt: yacs/opencv/cython/motmetrics | ✅ |
| 结果 | release 0 个，无预训练权重 | ❌ |
| 引用 | README 无 cite/BibTeX | ⚠️ |

### 产物哲学

输出**证据导向审查记录**（非分数排名）。每个发现先呈现"看到了什么"（文件内容/存在性/原文片段），让科研读者自行判断可复现性。

---

## 模块 D：科研协作智能匹配

### 功能

回答"谁适合做什么任务？"——从提交历史推断角色，按角色匹配待办 Issue。

### 使用方法

```bash
cd skills/gitlink-research-matching
# 按 SKILL.md 步骤执行
gitlink-cli pr +list --owner Gitlink --repo forgeplus --format json > .probe-data/pr.json
gitlink-cli issue +list --owner Gitlink --repo forgeplus --format json > .probe-data/issue.json
gitlink-cli commit +list --owner Gitlink --repo forgeplus --limit 50 --format json > .probe-data/commit.json
```

### 4 角色推断

| 角色 | 推断信号 | 示例 |
|------|----------|------|
| 数据 | PR 标题含"data" / 分支名含"data/" / 文件路径含"data/" | 数据采集/清洗/标注 |
| 算法 | PR 标题含"model" / 分支名含"model/" / 文件路径含"model/" | 模型设计/实验 |
| 工程 | PR 标题含"fix:" / 分支名含"fix/" / 文件路径含"src/" | 框架/部署/工具链 |
| 评测 | PR 标题含"eval" / 分支名含"eval/" / 文件路径含"eval/" | 指标/对比/分析 |

### 委托模式

委托 `gitlink-research-insight` 提供贡献者画像数据，自研角色匹配。insight 是数据层，本模块是分析层。

### 验证结果（Gitlink/forgeplus）

4246 Issue / 355 PR，3 位活跃贡献者：

| 贡献者 | PR 数 | 推断角色 | 置信度 | 依据 |
|--------|-------|----------|--------|------|
| xxq250 | 12 | 工程 | 🟡 中 | 版本发布号+部署说明 |
| dtwdtw | 7 | 工程 | 🟢 高 | 全部 fix: 前缀 |
| maxjhandsome | 1 | 工程 | 🔴 低 | PR 数不足 |

**角色覆盖偏科**：3 人全落"工程"角色，无数据/算法/评测。这本身也是匹配算法的正确输出。

---

## 模块 E：科研进度跟踪与预警

### 功能

回答"项目卡在哪了、有什么风险？"——6 维风险信号检测 + 100 分制评分。

### 使用方法

```bash
cd skills/gitlink-research-progress
# 按 SKILL.md 步骤执行
gitlink-cli repo +info --owner Gitlink --repo gitlink-cli --format json
gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state all --format json
gitlink-cli commit +list --owner Gitlink --repo gitlink-cli --limit 50 --format json
gitlink-cli milestone +list --owner Gitlink --repo gitlink-cli --format json
```

### 6 维风险信号

| 信号 | 检测逻辑 | 风险等级 |
|------|----------|----------|
| ① 长期停滞 | 未解决 Issue 停留 >60 天 | 🔴 高 |
| ② 高优无人 | 高优先级 Issue 无人认领 | 🔴 高 |
| ③ 零回复 | 未解决且 0 评论 | 🟡 中 |
| ④ 积压恶化 | 近 30 天新增 > 关闭 | 🟡 中 |
| ⑤ 提交突变 | 提交活跃度骤降/骤升 | 🟡 中 |
| ⑥ 里程碑 DDL | 里程碑临近且未完成 | 🔴 高 |

### GitLink 数据现实（重要）

| 数据维度 | GitLink 现状 | 应对 |
|----------|-------------|------|
| 里程碑 | 几乎无人使用（total_count=0） | 信号⑥设为可选 |
| Issue due_date/done_ratio | 普遍为空 | 不依赖 |
| Issue status | 中文：新增/关闭/已解决 | 按 status.name 客户端重统计 |
| Issue 时间序列 | ✅ 可靠可用 | 信号①②③④数据基础 |
| 提交时间序列 | ✅ 可靠可用（秒级时间戳） | 信号⑤数据基础 |

因此本模块**不以里程碑 DDL 为核心**，而以 Issue+提交时间序列为预警锚点。

### 委托模式

委托 `gitlink-project-health` 跑静态健康度（关闭率/活跃度评分），自研动态风险预警。两者正交。

### 验证结果（Gitlink/gitlink-cli）

19 Issue（9 新增/10 关闭），关闭率 53%：

| 信号 | 发现 | 等级 |
|------|------|------|
| ① 长期停滞 | #2(86天) #5(65天) #6(64天) + 4 个 30-60 天 | 🔴 高 |
| ③ 零回复 | #17、#18 未解决且 0 评论 | 🟡 中 |
| ⑤ 提交突变 | 近 30 天 15 条 vs 前 30 天 0 条 → 活跃上升期 | 🟢 低 |

评分：62/100

---

## 委托模式说明

5 个科研模块普遍采用"委托通用 Skill + 自研科研层"模式：

| 科研模块 | 委托的通用模块 | 自研部分 | 边界 |
|----------|---------------|----------|------|
| research-compliance | compliance（合规层） | 复现性证据链 | 合规管"合法"，本模块管"可复现" |
| research-matching | research-insight（画像） | 角色匹配 | insight 管数据，本模块管分析 |
| research-progress | project-health（健康度） | 时间线风险预警 | health 管"现状"，本模块管"趋势" |

设计原则：两者正交，不重复。通用 Skill 处理跨领域共性问题，科研层处理科研特有问题。

— 文档完 —
