From 05a0d507f2c7a6c847c109ea9736cdc3f15c8e58 Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 1 Jul 2026 15:19:07 +0800 Subject: [PATCH] =?UTF-8?q?feat(research-fair):=20examples=20songhui18/ICC?= =?UTF-8?q?V2021=20=E7=9C=9F=E5=AE=9E=E8=B5=B0=E6=9F=A5=EF=BC=88C45+?= =?UTF-8?q?=E5=A4=84=E6=96=B9PR#1+=E8=AF=81=E4=B9=A6+=E5=AF=B9=E7=85=A7B69?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .../examples/research-fair-workflow.md | 153 ++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 skills/gitlink-research-fair/examples/research-fair-workflow.md diff --git a/skills/gitlink-research-fair/examples/research-fair-workflow.md b/skills/gitlink-research-fair/examples/research-fair-workflow.md new file mode 100644 index 0000000..829eef3 --- /dev/null +++ b/skills/gitlink-research-fair/examples/research-fair-workflow.md @@ -0,0 +1,153 @@ +# 示例：科研软件 FAIR 体检（真实数据） + +> 基于 `songhui18/ICCV2021`（显示名"ICCV2021论文复现"，URL identifier=`ICCV2021`）于 2026-07-01 在 Claude Code 中实跑。 +> 这是 19⭐/17fork 的 ICCV 2021 论文复现合集，3328 文件、17 个论文复现子目录。 +> 一个"**可复现性**"工具去体检一个"**论文复现**"合集——主题共振。 + +--- + +## Step 1：取上下文（真实输出摘要） + +| 项 | 实测值 | +|---|---| +| URL identifier | `ICCV2021`（**CLI 用 identifier，不是中文显示名**） | +| `license_id` | `None`（**根目录无 LICENSE**；20 个 LICENSE 全在子目录随上游代码） | +| releases | `0`（无任何版本发布） | +| 根级文件 | 仅 `README.md` | +| CITATION.cff / codemeta.json / .zenodo.json | 均无 | +| requirements.txt | 13 处（**仅子目录，无根级依赖锁**） | +| `has_dataset` | `False` | +| topics | python, jupyter notebook, cuda | +| description | 详尽（≥20 字） | +| HEAD commit | `e14ac625752171fd46c90778cf5c7b000d05307b` | + +> ⚠️ **关键踩坑**：`gitlink-cli --repo` 必须传 `identifier=ICCV2021`；用中文显示名"ICCV2021论文复现"会返回 **404**。identifier 从 `search +repos` 结果取。 + +采集命令： + +```bash +gitlink-cli repo +info --owner songhui18 --repo ICCV2021 --format json +gitlink-cli file +list --owner songhui18 --repo ICCV2021 --format json # 3328 文件扁平列表 +gitlink-cli release +list --owner songhui18 --repo ICCV2021 --format json +gitlink-cli commit +list --owner songhui18 --repo ICCV2021 --page 1 --format json +``` + +## Step 2：5 轴评分（真实） + +| 轴 | 分 | 关键依据 | +|---|---|---| +| F 可发现 | 67 | F1✓ 详尽描述 · F2✓ 3 topics · F3✗ 无 codemeta/.zenodo | +| A 可访问 | 50 | A1✓ 公开 · A2✗ **无仓库级 license** · A3✗ 无 release · A4✓ commit SHA | +| I 可互操作 | 17 | I1⚠ 依赖散落子目录无根级锁 · I2✗ 无机器可读 license · I3✗ 无标准元数据 | +| R 可复用 | 50 | R1✗ 无 CITATION · R2⚠ 根 README 是论文列表 · R4✓ 无明显敏感泄露 | +| Repro 可复现 | 40 | Rep1⚠ · Rep2✗ 无数据集说明 · Rep3⚠ · Rep4✗ 无 release · Rep5✓ 入口齐全 | + +**总评：C 🔴 45/100** —— 一个 19⭐ 的论文复现合集，FAIR/可复现仅得 C。 + +## Step 3：报告卡（真实全文） + +````markdown +🏥 **gitlink-research-fair 科研软件体检报告** + +**总体**：C 🔴 45/100（F 67 · A 50 · I 17 · R 50 · Repro 40）｜版本锚定：commit `e14ac62`（无 release） +**范围**：检查 19 项（✓7 · ✗7 · ⚠3 · ⊥2） + +### 逐项（节选） +| 轴 | 项 | 状态 | 证据 | +|---|---|:---:|---| +| A | A2 有许可证 | ✗ | `license_id` 为空，根目录无 LICENSE（20 个 LICENSE 全在子目录） | +| F | F3 标准元数据 | ✗ | 无 codemeta.json / .zenodo.json | +| I | I1 依赖清单 | ⚠ | requirements.txt 仅在 13 个子目录，无根级统一锁 | +| R | R1 溯源/引用 | ✗ | 无 CITATION.cff | +| Repro | Rep2 数据集说明 | ✗ | `has_dataset=False`，README 无数据集说明 | +| Repro | Rep5 入口可执行 | ✓ | 子目录含 train.py×16 / main.py×13 / test.py×15 | +| F | F1 清晰描述 | ✓ | description 详尽描述 CV 顶会论文复现合集 | + +### 🔧 处方（可自动修复 4 项） +- [A2] 添加 LICENSE（MIT / 木兰 PSL v2） +- [R1] 生成 CITATION.cff +- [F3/I3] 生成 codemeta.json +- [Rep3] 补 REPRODUCIBILITY.md 复现指南 + +### 📜 可复现证书 +锚定版本：`git+commit e14ac625752171fd46c90778cf5c7b000d05307b` ｜ FAIR: C 🔴 ｜ Repro: ⚠ 部分可复现 +（完整 SWH-ID 需 `swh-identify`；环境无 `swh.model`，本次用 commit-SHA 锚定） + +### 🔗 溯源（OpenAlex） +⚠️ 未命中——匿名搜索被限流（HTTP 503，需 free API key），已降级跳过（符合 freemium 边界）。 + +### 🧬 科研关系图（KG） +```mermaid +graph LR + R[Repo: ICCV2021合集] -->|contributes-to| C1[Contributor: 宋辉/songhui18] + R -->|has| D{Dataset?}:::miss + R -->|licensed-under| L{License?}:::miss + R -->|version-at| H[commit e14ac62] + classDef miss fill:#fee,stroke:#c33; +``` + +--- + +*由 gitlink-research-fair skill 生成。* +```` + +## Step 4：处方 PR（真实闭环 ✅） + +**全自动跑通**（无需克隆 3328 文件大仓，纯 API 建文件）： + +```bash +gitlink-cli repo +fork --owner songhui18 --repo ICCV2021 # → caoweiqiong/ICCV2021 +gitlink-cli branch +create --owner caoweiqiong --repo ICCV2021 --name feat/fair-remediation --from master +gitlink-cli file +create --owner caoweiqiong --repo ICCV2021 --branch feat/fair-remediation \ + --path LICENSE --message "Add MIT LICENSE (fix A2)" --content "$(cat LICENSE)" +# … 同样建 CITATION.cff / codemeta.json / REPRODUCIBILITY.md +gitlink-cli pr +create --owner caoweiqiong --repo ICCV2021 --head feat/fair-remediation --base master \ + --title "Improve research FAIRness & reproducibility (gitlink-research-fair 处方)" \ + -b "$(cat pr_body.md)" +``` + +**PR**：https://www.gitlink.org.cn/caoweiqiong/ICCV2021/pulls/1 （`pull_request_number: 1`, id `145336`, open） + +PR body 含体检报告卡摘要 + 修复表。新增 4 文件： + +| 文件 | 修复项 | FAIR 原则 | +|------|--------|-----------| +| `LICENSE` | 补 MIT 许可证 | R1.1 / A2 | +| `CITATION.cff` | 补引用信息 | R1.2 / R1 | +| `codemeta.json` | 补标准元数据 | F2 / F3 / I3 | +| `REPRODUCIBILITY.md` | 补复现指南 | Rep3 | + +**预期效果**：合并后 A2/F3/I3/R1/Rep3 由 ✗/⚠ → ✓，总分 **C 45 → B ~75**。 + +## Step 5：证书 + +- **锚定版本**：`git+commit e14ac625752171fd46c90778cf5c7b000d05307b`（HEAD，无 release） +- **SWH-ID**：环境无 `swh.model`，用 commit-SHA 锚定（完整 SWH-ID 需 `swh-identify`） +- **结论**：FAIR C 🔴 · Repro ⚠ 部分可复现 —— 可作为"待改进科研软件"的基线快照，供后续 release 后重评对比。 + +--- + +## 对照：有 license 的仓库（证明评分区分度） + +对 `leejt/GraphGallery`（图神经网络多框架开发工具，Python，有 license）跑同一 rubric： + +| 轴 | songhui18/ICCV2021 | leejt/GraphGallery | +|---|---|---| +| F | 67 | 67 | +| A | **50**（无 license） | **75**（✓ 根级 LICENSE） | +| I | 17（无根级依赖锁） | 67（✓ 根级 requirements.txt + setup.py） | +| R | 50 | 67 | +| Repro | 40 | 70（✓ setup.py 可安装） | +| **总评** | **C 🔴 45** | **B 🟡 69** | + +**区分度 +24 分**，主要由 **A2 license + I1/Rep1 打包可安装** 拉开。rubric 正确奖励"有 license + 可安装"的仓库。（GraphGallery 仍缺 CITATION/release，故是 B 非 A——评分诚实，不虚高。） + +--- + +## 关键结论 + +1. **主题共振**：用"可复现性"工具体检"论文复现"合集——一个 19⭐ 的真实科研仓库竟只得 C，**正好印证可复现性危机**（2024 顶会仅 19.5% 提供官方代码）。 +2. **闭环可用**：fork → 建分支 → `file +create` 建修复文件 → 开 PR，**全程纯 API、无需克隆大仓**，处方 PR 真实落地。 +3. **诚实降级**：OpenAlex 匿名限流(503)→溯源跳过；无 `swh.model`→commit-SHA 锚定——都是设计内的优雅降级，**不掩盖、不编造**。 +4. **评分有区分度**：C 45（无 license 合集）vs B 69（有 license 工具），rubric 行为正确。 +5. **差异于 howfairis**：GitLink 原生 + 报告卡 + **自动修复闭环** + SWH 证书 + OpenAlex 溯源，howfairis 只跑 GitHub 且只打分不修复。