---
name: gitlink-research-compliance
version: 1.0.0
description: "科研项目复现性检查：纯远程只读审查一个 GitLink 科研仓库能否被他人复现——委托合规层 + 自研复现性证据链（数据/环境/结果），输出证据导向的《复现性审查记录》。当用户需要判断某个科研/算法/论文复现仓库是否可复现、缺什么、复现风险在哪时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli file --help"
---

# gitlink-research-compliance（科研项目复现性检查）

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

## 说明

本 Skill 面向**科研场景**，回答一个 `gitlink-compliance` 回答不了的问题：**这个科研仓库，别人能不能照着跑出一样的结果？**

它**委托** `gitlink-compliance` 跑通用合规层（许可证/依赖/版权），自己专注科研独有的**复现性证据链**：数据是否可用、环境能否复现、结果可否验证。两者正交，不重复。

**产物哲学（重要）**：输出的是**证据导向的审查记录**，不是分数排名。每个发现先呈现"看到了什么"（文件内容/存在性/链接/原文片段），让科研读者**自行判断**可复现性，分数只是末尾的辅助参考。

## 与 `gitlink-compliance` 的边界

| 维度 | `gitlink-compliance`（被委托） | `gitlink-research-compliance`（本 Skill） |
|---|---|---|
| 核心问题 | 能不能**合法开源** | 能不能被别人**复现** |
| 检查对象 | LICENSE、版权头、依赖许可证 | README + 环境 + 数据 + 权重 + 结果证据 |
| 视角 | 法律/开源合规 | 科研可复现性 |
| 关系 | 上游信号（合规子维度） | 编排者 + 复现性裁决 |

> 职责正交：compliance 管"合法合规"，本 Skill 管"可复现"，可串联。

## 前置条件

- 已 `gitlink-cli auth login`（`auth status` 为已登录）。
- 目标是 GitLink 上的**公开**科研类仓库（私有仓库需有访问权限）。
- （可选）读过 [`../gitlink-compliance/SKILL.md`](../gitlink-compliance/SKILL.md)，便于委托其合规层。

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

读文件内容**不能**一步到位，分三种情况：

| 需求 | 正确命令 | 说明 |
|---|---|---|
| 读 README 明文 | `file +readme` | **唯一**一步取到明文 content 的命令 |
| 读任意文件内容 | `file +get` 取 sha → `file +blob --sha` 取 base64 → 解码 | `file +get` 的 content 字段**恒为 None**，只有 sha 有用 |
| 列目录结构 | `file +entries` | 返回 `data.entries[]`，每项 `{name, type}` |

```bash
# ❌ 错误：api GET .../raw/<分支>/<路径> 对他人仓库返回 403
# ✅ 正确：读任意文件内容两步走
SHA=$(gitlink-cli file +get --owner <o> --repo <r> --path <path> --format json | jq -r '.data.sha')
gitlink-cli file +blob --owner <o> --repo <r> --sha "$SHA" --format json | jq -r '.data.content' | base64 -d
```

> `repo +info` **无 license/language 字段**；许可证类型需读 `LICENSE` 文件头部识别关键词（"MIT License" / "Apache License" / "GNU GENERAL PUBLIC LICENSE" / "木兰宽松许可证" 等）。

## 工作流概览

| 步骤 | 操作 | 命令 |
|------|------|------|
| ① 仓库元信息 | 取语言、大小、是否 fork/mirror | `repo +info` |
| ② 合规层（委托） | 许可证/依赖/版权合规 | 委托 `gitlink-compliance` |
| ③ 数据可用性 | 数据集、下载链接、cite 要求 | `dataset +list` / `file +readme` / `file +entries` |
| ④ 环境可复现 | 环境锁定文件、版本 pin、随机种子 | `file +get`→`+blob` |
| ⑤ 结果可验证 | 测试/评测脚本、预训练权重、参考指标 | `file +entries` / `release +list` |
| ⑥ 综合裁决 | 四维证据汇总 → 审查记录 | （分析，无命令） |

---

## 详细工作流

### Step ① 仓库元信息

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

记录：`name`、`default_branch`、`size`、`forked_from_project_id`（是否 fork）、`mirror`（是否镜像）、`issues_count`/`pull_requests_count`。
> 许可证不在返回里，留给 Step ② 读 LICENSE 文件识别。

### Step ② 合规层（委托 `gitlink-compliance`）

本 Skill 不重复实现合规检查，**委托**已有 skill：

> 按 [`../gitlink-compliance/SKILL.md`](../gitlink-compliance/SKILL.md) 的「工作流 1：完整合规检查」执行，取回其合规评分与问题清单。

本 Skill 在此基础上补一个科研独有的合规检查——**数据集引用（cite）要求**：
- 在 README 里搜 `cite`/`citation`/`BibTeX`/`@inproceedings`/`参考文献` 等关键词；
- 若数据/仓库要求 cite，记入证据（科研数据合规的核心，开发者场景不管）。

### Step ③ 数据可用性（科研独有重点）

科研复现的第一关：**数据拿得到吗？**

```bash
# a. GitLink 原生数据集
gitlink-cli dataset +list --owner <o> --repo <r> --format json
#   → data.releases[]（注意字段名，dataset 用 releases 列表结构）

# b. 顶层目录有无 data/ dataset/ weights/ 目录
gitlink-cli file +entries --owner <o> --repo <r> --ref master --format json
#   → data.entries[]，看 name 是否含数据/权重目录

# c. README 里的数据说明（明文，直接读）
gitlink-cli file +readme --owner <o> --repo <r> --format json
#   → data.content，搜 download/dataset/数据/weights/百度网盘/google drive 等
```

**判定要素**：
- ✅ 优点：数据随仓托管 / 有明确下载链接 / 有 cite 说明
- ❌ 缺口：数据未随仓且无下载指引 / 链接疑似失效 / 缺 cite 要求

### Step ④ 环境可复现（科研独有重点）

科研复现第二关：**环境装得上吗？版本对得上吗？**

```bash
# a. 找环境锁定文件（按主语言匹配常见文件名）
for f in requirements.txt environment.yml environment.yaml Dockerfile Makefile setup.py pyproject.toml package.json go.mod Cargo.toml pom.xml; do
  gitlink-cli file +get --owner <o> --repo <r> --path "$f" --format json | jq -r '.data.sha // empty'
done
# 哪个 sha 非空，说明该文件存在 → 取内容

# b. 取内容（以 requirements.txt 为例）
SHA=$(gitlink-cli file +get --owner <o> --repo <r> --path requirements.txt --format json | jq -r '.data.sha')
gitlink-cli file +blob --owner <o> --repo <r> --sha "$SHA" --format json | jq -r '.data.content' | base64 -d

# c. 随机种子：在 src/ 等代码目录搜 seed 关键词
gitlink-cli file +entries --owner <o> --repo <r> --path src --ref master --format json
#   → 找到 .py 文件后逐个 +get→+blob 读内容，搜 manual_seed/random_state/np.random.seed/seed(
```

**判定要素**：
- ✅ 优点：依赖用 `==`/`===` 精确 pin 版本 / 有 Dockerfile（环境完全锁定）/ 有 conda 锁定文件
- ❌ 缺口：依赖未 pin 版本（只写包名）/ 无任何环境锁定文件 / 训练有种子但推理无种子

### Step ⑤ 结果可验证（科研独有重点）

科研复现第三关：**跑出来的结果对不对，怎么知道？**

```bash
# a. 找测试/评测脚本目录
gitlink-cli file +entries --owner <o> --repo <r> --ref master --format json
#   → 找 tests/、eval*.py、test*.py、demo*.py、scripts/、experiments/

# b. 预训练权重 / 数据包 release
gitlink-cli release +list --owner <o> --repo <r> --format json
#   → data.releases[]（total_count=0 说明无任何 release）

# c. README 里的参考指标（expected output）
gitlink-cli file +readme --owner <o> --repo <r> --format json
#   → 搜 MOTA/MAP/accuracy/F1/precision/%/dB/指标/结果 等关键词
```

**判定要素**：
- ✅ 优点：有评测脚本 + README 给出参考指标 / 有预训练权重 release（可一键复现论文结果）/ 有 demo 脚本
- ❌ 缺口：无评测脚本无法验证产出 / 无预训练权重（需自行训练，复现成本高）/ 无参考指标

### Step ⑥ 综合裁决

汇总四维证据，输出《复现性审查记录》。**先证据，后判定**：

```
🔬 科研项目复现性审查记录 — <owner>/<repo>
═══════════════════════════════════════════════════
审查日期: <YYYY-MM-DD>   主语言: <从 requirements/文件后缀推断>   License: <读LICENSE识别>
审查方式: 纯远程只读（gitlink-cli file/dataset/release）
说明: 本报告呈现复现性相关证据，由读者结合自身环境自行判断；
      末尾参考评分仅作辅助，不构成绝对结论。

───────────────────────────────────────────────────
维度① 合规层（委托 gitlink-compliance + 数据集引用补充）
───────────────────────────────────────────────────
[证据]
  • LICENSE 文件: <存在性 + 识别类型，附头部原文片段>
  • 合规层详情: （见 gitlink-compliance 报告）
  • 数据集 cite 要求: README <第N行> "<原文片段>"  / 未发现
[判定] ✅/⚠️/❌  <一句话>

───────────────────────────────────────────────────
维度② 数据可用性
───────────────────────────────────────────────────
[证据]
  • GitLink 原生数据集: <有/无，dataset +list 结果>
  • 顶层目录: <列出的关键目录>
  • README 数据说明（原文片段）: "..."
[发现]
  ✅ 优点: ...
  ❌ 缺口: ...
[判定] ...

───────────────────────────────────────────────────
维度③ 环境可复现
───────────────────────────────────────────────────
[证据]
  • 环境文件: <文件名 + 内容片段>
  • 版本锁定: ✅/❌ <pin 情况>
  • 随机种子: <搜索结果，哪个文件第几行>
[发现]
  ✅ 优点 / ⚠️ 注意 / ❌ 缺口
[判定] ...

───────────────────────────────────────────────────
维度④ 结果可验证
───────────────────────────────────────────────────
[证据]
  • 测试/评测: <目录/脚本>
  • 预训练权重: release +list → <有/无>
  • 参考指标: README <原文片段>
[发现]
  ✅ 优点 / ❌ 缺口
[判定] ...

═══════════════════════════════════════════════════
参考性评分（辅助总结，请以上方证据为准自行判断）
  ① 合规层    __/20   ② 数据可用性 __/25
  ③ 环境可复现 __/25   ④ 结果可验证 __/30
  参考总分: __/100  (仅供索引，不代表绝对可复现性)
  参考评级: A(≥85)/B(70-84)/C(50-69)/D(<50)
═══════════════════════════════════════════════════
```

### 评分规则（仅辅助参考）

| 维度 | 满分 | 评分依据（✅满分/⚠️半分/❌0分，按检查项加权） |
|---|---|---|
| ① 合规层 | 20 | LICENSE 存在+类型识别 / 数据集 cite 标注 |
| ② 数据可用性 | 25 | 数据随仓 / 下载链接有效 / cite 说明 |
| ③ 环境可复现 | 25 | 环境锁定文件 / 版本 pin / 随机种子 |
| ④ 结果可验证 | 30 | 评测脚本 / 预训练权重 / 参考指标 |

> 分数只是**辅助索引**，报告主体是证据。读者可能因自身有 GPU/特定数据而得出与本评分不同的结论，这是正常的。

## 使用示例

见 [`examples/reproducibility-check.md`](examples/reproducibility-check.md)：在 `ifzhang/FairMOT` 上的完整审查记录。

## 注意事项

- 本 Skill **全程只读**，不写仓库，不建 Issue——科研审查应尊重他人仓库。
- 复现性判断**依赖读者环境**（GPU/数据/操作系统），报告只呈现仓库侧证据，不替读者下绝对结论。
- 依赖文件格式因语言而异，按 Step ① 推断的主语言优先匹配对应文件。
- 部分老仓库镜像自 GitHub（`mirror=true`），其 GitLink release 可能与原仓库不同步，以 GitLink 实际数据为准。
