chroe
/
gitlink-cli
forked from Gitlink/gitlink-cli
0
0
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

feat: 新增 gitlink-research-fair 科研软件 FAIR 体检 Skill（子任务四） #5

Merged
yetja merged 11 commits from caoweiqiong/gitlink-cli:feat/gitlink-research-fair into master 2026-07-02 16:15:10 +08:00
Conversation 0 Commits 11 Files Changed 7 +1300
7 changed files with 1300 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

638
docs/superpowers/plans/2026-07-01-gitlink-research-fair.md Normal file
View File

@ -0,0 +1,638 @@
# gitlink-research-fair Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Build a `gitlink-research-fair` Claude Code Skill that turns any GitLink research repo into a FAIR 体检报告卡 + auto-remediation PR + reproducibility certificate.
**Architecture:** Methodology-type Skill (pure Markdown + gitlink-cli calls, no Go). Report-card-centric: M1 FAIR Checker (5-axis rubric, reuses gitlink-license for license/security) + M2 KG + M3 OpenAlex provenance + M4 Remediation. Validated end-to-end on `songhui18/ICCV2021论文复现`.
**Tech Stack:** Markdown (SKILL.md/REFERENCE.md/examples), gitlink-cli (Go CLI, source build), Mermaid (KG viz), OpenAlex REST (optional enrichment).
**Source of truth:** `docs/superpowers/specs/2026-07-01-gitlink-research-fair-design.md` (read it first).
---
## Environment & Gotchas (engineer must know)
- **Branch:** already on `feat/gitlink-research-fair` (master is protected — never push master). Commit only your own files; leave pre-existing `D README_TASKB.md` / `D gitlink-cli.exe` / `?? dist/` untouched.
- **Binary:** use the go/bin source build. Verify: `gitlink-cli version` → `gitlink-cli dev`, and `gitlink-cli search --help` shows `+repos`. If commands like `file`/`member` are missing, run `go build -o gitlink-cli.exe .` in the repo root and use `./gitlink-cli.exe`.
- **Encoding (Windows):** gitlink-cli JSON contains Chinese. When parsing with Python, always set `PYTHONUTF8=1 PYTHONIOENCODING=utf-8`. Never inline Chinese inside `python -c "..."` on this shell (GBK-mangles it) — write a `.py` file instead.
- **Known GitLink CLI bug:** `file +tree --recursive true` returns empty on some repos. Workaround: `file +tree` top-level → `file +get --path <subdir>` recursively, or use `file +list`.
- **All examples use `--owner songhui18 --repo ICCV2021论文复现`** unless noted. 处方 (open PR) needs write access → **fork first** (`gitlink-cli repo +fork`); if fork/push fails, fall back to `--no-fork` (write materials to local files).
- **Verification commands** use `grep` (available in Git Bash). Expected outputs are illustrative; the check is "contains the key string".
---
## File Structure
| File | Responsibility |
|------|----------------|
| `skills/gitlink-research-fair/SKILL.md` | Entry doc: frontmatter, CRITICAL headers, command interface, 8-step pipeline, 5-axis rubric, report card template, remediation guardrails, certificate, KG/OpenAlex, error table |
| `skills/gitlink-research-fair/REFERENCE.md` | Deep reference: FAIR4RS per-principle mapping, scoring algorithm, KG schema (triples), OpenAlex fields, SWH-ID notes, **academic citation library**, honesty caveats (incl. 2 banned claims), live-probe findings |
| `skills/gitlink-research-fair/examples/research-fair-workflow.md` | Real walkthrough on songhui18: report card + remediation PR + certificate, with contrast run on a licensed repo |
| `skills/gitlink-research-fair/examples/img/` | Screenshots (GitLink web: opened PR) — optional but recommended for deliverable |
| `skills/README.md` | Add gitlink-research-fair row (科研辅助类) |
| `skills/gitlink-workflow/SKILL.md` | Optional cross-link |
---
## Task 1: Scaffold SKILL.md (frontmatter + CRITICAL headers)
**Files:**
- Create: `skills/gitlink-research-fair/SKILL.md`
- [ ] **Step 1: Create SKILL.md with frontmatter and CRITICAL headers**
Content (exact):
```markdown
---
name: gitlink-research-fair
version: 1.0.0
description: "科研软件 FAIR 体检：分析 GitLink 科研仓库的可发现/可访问/可互操作/可复用/可复现性，输出体检报告卡，自动开 PR 修复缺口并签发 SWH/commit 锚定的可复现证书。当用户需要评估科研仓库的 FAIR 性与可复现性、生成科研软件体检报告时触发。"
metadata:
requires:
bins: ["gitlink-cli"]
cliHelp: "gitlink-cli repo --help"
---
# gitlink-research-fair（科研软件 FAIR 体检）
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有写操作（开修复 PR）默认先预览、确认后再执行；`--auto` 跳过预览但仍受护栏约束。**
**CRITICAL — 绝不自动 merge；绝不 force-push；处方只对 fork 开 PR，绝不碰原仓库。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；详细检查清单、评分算法、KG schema 与学术引用见 [`REFERENCE.md`](REFERENCE.md)。
```
- [ ] **Step 2: Verify frontmatter + CRITICAL lines**
Run: `head -20 skills/gitlink-research-fair/SKILL.md | grep -c -e "name: gitlink-research-fair" -e "description:" -e "CRITICAL"`
Expected: `6` (1 `name:` + 1 `description:` + 4 `CRITICAL` lines). If `<6`, fix.
- [ ] **Step 3: Commit**
```bash
git add skills/gitlink-research-fair/SKILL.md
git commit -m "feat(research-fair): scaffold SKILL.md（frontmatter + CRITICAL 头）"
```
---
## Task 2: SKILL.md — 命令接口 + 8 步管道
**Files:**
- Modify: `skills/gitlink-research-fair/SKILL.md` (append after the 前置条件 line)
- [ ] **Step 1: Append 概述 + 命令接口 + 8 步管道 sections**
Append (exact content):
```markdown
## 概述
本 Skill 引导 AI 对任意 GitLink 科研仓库做结构化、有学术标准依据、低误报的"FAIR + 可复现性"诊断，产出**体检报告卡**，并对缺口**自动开 PR 修复**、用 **SWH/commit 锚定**签发**可复现证书**。许可证/安全子项**复用 `gitlink-license`**。四幕剧本（v1）：诊断 → 处方 → 证书。
## 命令接口（skill 约定参数，非 CLI flag）
| 参数 | 默认 | 说明 |
|------|------|------|
| `--owner/--repo` | 自动从 cwd 解析 | 目标科研仓库 |
| `--lenses` | 全 5 轴 | 子集，如 `F,A,Repro` |
| `--auto` | 关 | 跳过预览直接开 PR（仍受护栏） |
| `--no-fork` | 关 | 不开 PR，处方物料落本地 |
| `--enrich` | 开 | 启用 OpenAlex 溯源（限流自动降级） |
| `--refresh` | 关 | 即使有旧报告哨兵也重评 |
## 管道（8 步）
### ① 取上下文
`repo +info`（元数据/license/topics/has_dataset）· `file +list`（关键文件清单）
### ② 深采
`file +get` 读 LICENSE/CITATION.cff/codemeta.json/README/requirements/Dockerfile · `release +list`（版本）· `commit +list`（SHA）· `issue/pr +list`（协作）· `member +list`（作者）
### ③ FAIR 评分（M1）
逐项评 5 轴（许可证/安全子项委托 `gitlink-license` 流程）→ `✓/✗/⚠/⊥` + 证据 + 置信度
### ④ KG 构建（M2）
四实体(Repo/Contributor/File/Commit)+Paper/Dataset/License 节点 → Mermaid 小图 + triples JSON
### ⑤ 溯源富集（M3）
从 README/CITATION 抽论文 → OpenAlex REST 反查作者/机构（best-effort）
### ⑥ 渲染报告卡（hero）
等级 + 雷达图 + 5 轴逐项表 + 处方摘要 + 证书栏 + KG 小图 + 溯源栏
### ⑦ 处方（M4）
对 `✗/⚠` 项生成 CITATION.cff/codemeta.json/LICENSE/复现章节 → 默认预览
### ⑧ 发布
确认后对 fork 开 PR（PR body 带报告卡摘要）+ 出 SWH/commit 证书；内嵌哨兵
```
- [ ] **Step 2: Verify the pipeline + interface landed**
Run: `grep -c -e "管道（8 步）" -e "命令接口" -e "### ⑧ 发布" skills/gitlink-research-fair/SKILL.md`
Expected: `3`
- [ ] **Step 3: Commit**
```bash
git add skills/gitlink-research-fair/SKILL.md
git commit -m "feat(research-fair): SKILL 命令接口 + 8 步管道"
```
---
## Task 3: SKILL.md — 5 轴 rubric 表
**Files:**
- Modify: `skills/gitlink-research-fair/SKILL.md` (append after 管道)
- [ ] **Step 1: Append the 5-axis rubric**
Append (exact):
```markdown
## 5 轴评分 Rubric
> 对标 **FAIR4RS（Nature Sci Data 2022）+ howfairis 5 维**。诚实声明：这是**适配版**评分（社区尚无认证级自动校验器），不是官方认证。**FAIR ≠ 可复现**，故 Repro 单独成轴。逐条映射与证据见 [`REFERENCE.md`](REFERENCE.md)。
每项判定 `✓满足 / ✗缺失 / ⚠部分 / ⊥GitLink 无该字段(跳过并标注)`，附证据来源 + 置信度。
| 轴 | FAIR4RS 映射 | 检查项（证据） |
|----|--------------|----------------|
| **F 可发现** | F1/F2 | F1 清晰描述(repo desc ≥20 字) · F2 话题/关键词(topics) · F3 标准元数据(codemeta.json/.zenodo.json) |
| **A 可访问** | F1.2/R1.1 | A1 公开(is_public) · A2 有许可证(license_id/LICENSE)[gitlink-license] · A3 有版本发布(release tag) · A4 持久标识(commit SHA/SWH-ID) |
| **I 可互操作** | R1.1/I | I1 依赖清单(requirements/go.mod/package.json/environment.yml) · I2 许可证机器可读(SPDX/license_id) · I3 元数据标准格式(CITATION.cff/codemeta) |
| **R 可复用** | R1.2/R2 | R1 溯源/引用(CITATION.cff/README 引用) · R2 README 质量(安装+使用) · R3 源码声明[gitlink-license] · R4 无敏感泄露[gitlink-license] |
| **Repro 可复现** ⭐差异轴 | （独立于 FAIR） | Rep1 环境锁(锁版本/Dockerfile) · Rep2 数据集说明(has_dataset/README 引用) · Rep3 复现步骤(README 章节) · Rep4 版本固定 · Rep5 入口可执行(main/Makefile/CLI) |
**评分**：轴分 = 满足项 / (总项 − ⊥项)（⚠ 计 0.5）；总评 = 5 轴均分（某轴全 ⊥ 则记 N/A 并排除）；等级 **A🟢≥80 / B🟡60-79 / C🔴<60**。`confidence=low` 标"待人工确认"，不进总评。
```
- [ ] **Step 2: Verify all 5 axes + scoring present**
Run: `grep -c -e "F 可发现" -e "A 可访问" -e "I 可互操作" -e "R 可复用" -e "Repro 可复现" -e "A🟢≥80" skills/gitlink-research-fair/SKILL.md`
Expected: `6`
- [ ] **Step 3: Commit**
```bash
git add skills/gitlink-research-fair/SKILL.md
git commit -m "feat(research-fair): SKILL 5 轴 FAIR rubric 表"
```
---
## Task 4: SKILL.md — 报告卡模板 + 处方护栏 + 证书 + KG/OpenAlex + 错误降级
**Files:**
- Modify: `skills/gitlink-research-fair/SKILL.md` (append after rubric)
- [ ] **Step 1: Append report card template**
Append (exact):
```markdown
## 报告卡格式（hero 产出）
\`\`\`markdown
🏥 **gitlink-research-fair 科研软件体检报告**
**总体**：<等级> <分>/100（F · A · I · R · Repro）｜版本锚定：commit <sha>（<release 或 无>）
**范围**：检查 19 项（✓N · ✗N · ⚠N · ⊥N，跳过：<原因>）
### 五轴雷达
（ASCII 或 Mermaid 雷达：F/A/I/R/Repro）
### 逐项
| 轴 | 项 | 状态 | 证据 |
|---|---|:---:|---|
| <轴> | <id 项名> | ✓/✗/⚠/⊥ | <gitlink-cli 证据> |
### 🔧 处方（可自动修复 N 项）
- [<轴><id>] <生成物>（从 <来源> 推断）
### 📜 可复现证书
锚定版本：git+commit <sha> ｜ FAIR: <等级> ｜ Repro: <状态>
（完整 SWH-ID 需 swh-identify；本次用 commit-SHA 锚定）
### 🔗 溯源（OpenAlex）
<作者/机构/载体 或 "未找到关联论文，已跳过">
### 🧬 科研关系图（KG）
\`\`\`mermaid
<Repo—contributes→Contributor · Repo—licensed?—? · Repo—has→Dataset?>
\`\`\`
---
<!-- gitlink-research-fair v1 | repo:<owner>/<repo> | grade:<G> | sha:<head-sha> -->
*由 gitlink-research-fair skill 生成。*
\`\`\`
哨兵 `<!-- gitlink-research-fair v1 | repo | grade | sha -->` 用于幂等与"基于哪个 commit"标识。重跑检测旧哨兵 → 默认提议更新（`--refresh` 才覆盖）；`sha` 不匹配 → 提示"报告已过期，建议重评"。
```
- [ ] **Step 2: Append 处方 + 护栏 + 证书 + KG/OpenAlex + 错误降级**
Append (exact):
```markdown
## 处方（M4，惊艳闭环）
| 缺口 | 生成物 |
|------|--------|
| F3 缺 codemeta.json | 从 repo +info + README 生成 codemeta.json 草稿 |
| R1 缺 CITATION.cff | 从 README/作者生成 CITATION.cff 草稿 |
| A2 缺 license | 给 MIT / 木兰 PSL v2 模板（任选） |
| Rep1 缺依赖锁 | 从 import 扫描建议 requirements.txt |
| Rep3 缺复现章节 | 从入口/README 生成"复现"章节草稿 |
**安全护栏**：默认全量预览 → 确认 → 对 **fork** 开一个 PR（PR body 带报告卡摘要）；`--auto` 跳过预览但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 物料落本地。所有写操作需认证。
## 证书（SWH/commit 锚定）
用 HEAD commit SHA + release tag 锚定版本。若环境有 Python `swh.model` → 算完整 SWH-ID；否则 `git+<commit-SHA>` 锚定，报告卡标注"完整 SWH-ID 需 swh-identify"。证书含：仓库、锚定版本、FAIR 等级、Repro 状态、可引用条目（对标 ACM Artifact Badge）。嵌报告卡证书栏。
## KG + OpenAlex（支撑栏）
- **KG**：四实体(Repo/Contributor/File/Commit)+Paper/Dataset/License；关系 contributes-to/authored/depends-on/cites/licensed-under/version-at。输出 Mermaid 小图 + triples JSON（schema 见 REFERENCE）。
- **OpenAlex**：README/CITATION 抽论文 → REST `/works` 反查作者/机构/载体。降级：限流或抽不到 → 跳过，标注"未找到关联论文"。
## 错误处理与降级
| 情况 | 处理 |
|------|------|
| `file +tree --recursive` 返回空 | 手动递归子目录 |
| 无 LICENSE | A2 ✗，处方建议模板 |
| OpenAlex 限流/无果 | 跳过溯源栏标注 |
| `swh.model` 不可用 | commit-SHA 锚定 + 标注 |
| 仓库过大 | 抽样文件 + "部分审查"标注 |
| fork 失败/无写权限 | 处方物料落本地（`--no-fork`） |
| 二进制是 npm 旧版 | 强制 `./gitlink-cli` 或 `go build` 重建 |
| 仓库私有/无权限 | 清晰错误，不发报告 |
| 报告/PR 发布失败 | 报告卡原文交用户手动粘贴 |
```
- [ ] **Step 3: Verify sentinel + key sections**
Run: `grep -c -e "gitlink-research-fair v1 | repo" -e "## 处方" -e "## 证书" -e "swh.model" skills/gitlink-research-fair/SKILL.md`
Expected: `4`
- [ ] **Step 4: Commit**
```bash
git add skills/gitlink-research-fair/SKILL.md
git commit -m "feat(research-fair): SKILL 报告卡模板+处方护栏+证书+KG/OpenAlex+错误降级"
```
---
## Task 5: REFERENCE.md — FAIR4RS 映射 + 评分算法 + KG schema + 引用库 + 诚实边界
**Files:**
- Create: `skills/gitlink-research-fair/REFERENCE.md`
- [ ] **Step 1: Create REFERENCE.md with all deep-reference sections**
Content (exact):
```markdown
# gitlink-research-fair 参考文档
> 本文件为 SKILL.md 的深度参考。评分细则、KG schema、OpenAlex/SWH 技术细节、学术引用库与诚实边界均在此。
## 一、FAIR4RS 逐条映射
| 原则 | 含义 | 本 Skill 检查项 | GitLink 证据 | 兜底（无字段时） |
|------|------|----------------|--------------|------------------|
| F1 | 全局唯一持久标识 | A4 持久标识 | repo identifier/URL + commit SHA | commit-SHA 锚定 |
| F1.2 | 版本级唯一标识 | A3 有版本发布 | `release +list` | ⊥（无 release 则 ✗） |
| F2 | 富元数据 | F1 描述/F2 topics/F3 codemeta | `repo +info` desc/topics；`file +get` codemeta.json | README 抽取（标注推断） |
| R1.1 | 清晰可访问许可证 | A2/I2 | `repo +info` license_id；LICENSE 文件 | gitlink-license 识别 |
| R1.2 | 详细溯源 | R1 | CITATION.cff/README 引用 | LLM 从 README 推断（标注） |
| R2 | 对其他软件的限定引用 | R3 | 源码 SPDX/依赖清单 | gitlink-license 维度4 |
## 二、评分算法
- 每项状态：`✓`(1) / `⚠`(0.5) / `✗`(0) / `⊥`(跳过，不计入分母)
- 轴分 = Σ状态值 / (轴内项数 − ⊥项数) × 100
- 总评 = 各轴分均值（全 ⊥ 轴记 N/A 排除）
- 等级：A🟢≥80 / B🟡60-79 / C🔴<60
- `confidence=low`：标注"待人工确认"，不计入分子分母
## 三、可复现性 checklist（独立于 FAIR）
Rep1 环境锁（requirements 锁版本/Dockerfile/environment.yml）· Rep2 数据集说明（has_dataset/README 引用/下载脚本）· Rep3 复现步骤（README "运行/复现/Quick Start" 章节）· Rep4 版本固定（release tag 或 commit 锚定）· Rep5 入口可执行（main.py/train.py/Makefile/CLI）
## 四、KG schema（triples）
实体：Repo, Contributor, File, Commit, Paper, Dataset, License
关系（主谓宾三元组）：
- (Contributor)—contributes-to→(Repo)
- (Contributor)—authored→(Paper)
- (Repo)—depends-on→(File/依赖)
- (Paper)—cites→(Paper)
- (Repo)—licensed-under→(License)
- (Repo)—version-at→(Commit)
- (Repo)—has→(Dataset)
输出：`triples.json`（数组 of {s,p,o}）+ Mermaid `graph LR` 小图。
## 五、OpenAlex 字段
- 端点：`https://api.openalex.org/works?search=<title>` （2025-02 起 freemium，建议带 `mailto` 参数走 polite pool）
- 取字段：`authorships[].author.display_name`、`authorships[].institutions[].display_name`、`host_venue.display_name`（或 `primary_location.source.display_name`）、`concepts[].display_name`、`doi`
- 降级：HTTP 429/无结果 → 报告卡溯源栏标"未找到关联论文"
## 六、SWH-ID 说明
- 完整 SWH-ID = `swh:1:dir:<hash>` 或 `swh:1:rev:<hash>`，基于 Merkle DAG，需 `swh.model`（Python）计算或 `swh-identify`
- 环境无 `swh.model` 时：用 `git+<commit-SHA>` 作版本锚定，报告卡标注"完整 SWH-ID 需 swh-identify"
- commit SHA 来自 `commit +list`（HEAD）
## 七、学术引用库（"信服"骨架，每条对抗式核验过）
| 支撑点 | 文献 |
|--------|------|
| 科研软件 FAIR 原则 F1/F1.2/F2/R1.1/R1.2/R2 可机器校验 | Barker et al. 2022, *Nature Scientific Data*, https://www.nature.com/articles/s41597-022-01710-x |
| 可复现性危机：2024 ICLR/ICML/NeurIPS 仅 19.5% 提供官方代码 | PaperCoder, arXiv:2504.17192 (Table 9) |
| 结构化对比表/报告卡范式 | ORKG, Jaradeh et al. K-CAP 2019 |
| 仓库→RDF 知识图谱 schema（13 实体/47 关系/794 万三元组） | LPWC, ISWC 2023 |
| SWH-ID 版本锚定（Merkle DAG, git 兼容） | Di Cosmo et al. ICMS 2020, PMC7340894 |
| 作者/机构溯源用 OpenAlex REST | Priem et al. 2022, arXiv:2205.01833 |
| 仓库级 KG 问答（四实体+SZZ+Cypher, CoT 50%→90%） | Repo-KG, arXiv:2412.03815 |
| 科研软件可复现徽章体系 | ACM Artifact Review Badging, https://www.acm.org/publications/policies/artifact-review-badging |
| 直接竞品 howfairis（5 维，仅 GitHub） | https://github.com/fair-software/howfairis |
| 战略时机：PWC 不稳定 | TIB 博客 2025-10 "Papers With Code went offline"（单一二手源，pitch 前复核） |
## 八、诚实边界（不可过度宣称）
1. FAIR4RS 自称 **aspirational**；本 Skill 是**自建 checker**（社区尚无认证级校验器），不说"套用现成标准工具"。
2. **FAIRness ≠ 可复现性**（FAIR 必要非充分）—— Repro 单独成轴。
3. OpenAlex 自 2025-02 起 freemium（~$1/day、需 key、100 req/s）—— 单仓演示够，批量控量。
4. **禁止使用两条已证伪论点**：①"MSR 六分类法"、②"FAIR 分高→被引更多"因果。
5. 文献多跑在 GitHub；"在 GitLink 上复刻"是合理外推，须真机跑通闭环。
## 九、实测结论（live probe，Task 6 回填）
> 此节由 Task 6 在 `songhui18/ICCV2021论文复现` 真机验证后回填：license 状态、README/requirements/releases/commit SHA、各轴实测分、fork→PR 链路是否可用、OpenAlex 是否命中。
```
- [ ] **Step 2: Verify citations + banned claims + sections**
Run: `grep -c -e "s41597-022-01710-x" -e "2504.17192" -e "禁止使用两条已证伪" -e "## 九、实测结论" skills/gitlink-research-fair/REFERENCE.md`
Expected: `4`
- [ ] **Step 3: Commit**
```bash
git add skills/gitlink-research-fair/REFERENCE.md
git commit -m "feat(research-fair): REFERENCE（FAIR4RS映射+评分+KG schema+引用库+诚实边界）"
```
---
## Task 6: Live probe songhui18 — 回填 REFERENCE 实测结论
**Files:**
- Modify: `skills/gitlink-research-fair/REFERENCE.md` (§九 实测结论)
- [ ] **Step 1: Probe repo metadata + files**
Run (capture outputs):
```bash
gitlink-cli repo +info --owner songhui18 --repo ICCV2021论文复现 --format json > /tmp/rf_info.json
gitlink-cli file +list --owner songhui18 --repo ICCV2021论文复现 --format json > /tmp/rf_files.json
gitlink-cli release +list --owner songhui18 --repo ICCV2021论文复现 --format json > /tmp/rf_rel.json
gitlink-cli commit +list --owner songhui18 --repo ICCV2021论文复现 --page 1 --format json > /tmp/rf_commits.json
```
Expected: each file non-empty, valid JSON with `"ok": true`. If any errors, debug auth/binary first (see Environment & Gotchas).
- [ ] **Step 2: Extract ground truth (license/desc/topics/releases/README/requirements/commit SHA)**
Write `_probe.py` (UTF-8) and run with `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python _probe.py`:
```python
# -*- coding: utf-8 -*-
import json, glob
def load(p):
try:
raw=open(p,encoding='utf-8').read(); i=raw.find('{')
return json.loads(raw[i:]) if i>=0 else {}
except Exception as e:
return {'_err':str(e)}
info=load('/tmp/rf_info.json'); files=load('/tmp/rf_files.json')
rel=load('/tmp/rf_rel.json'); commits=load('/tmp/rf_commits.json')
d=info.get('data',info) if isinstance(info,dict) else {}
print('license_id:', d.get('license_id'))
print('desc_len:', len(d.get('description') or ''))
print('topics:', d.get('topics'))
print('has_dataset:', d.get('has_dataset'))
print('is_public:', d.get('is_public'))
# releases
rd=rel.get('data',rel) if isinstance(rel,dict) else {}
releases=rd.get('releases') or rd.get('project_releases') or []
print('releases:', len(releases) if isinstance(releases,list) else releases)
# files — look for key names
fd=files.get('data',files) if isinstance(files,dict) else {}
entries=fd.get('entries') or fd.get('files') or fd.get('trees') or []
names=[ (e.get('name') or e.get('path') or '') for e in entries ] if isinstance(entries,list) else []
key=['LICENSE','LICENSE.md','COPYING','README.md','README','requirements.txt','environment.yml','Dockerfile','Makefile','CITATION.cff','codemeta.json','.zenodo.json','go.mod','package.json']
print('present:', [k for k in key if any(k==n or n.endswith('/'+k) for n in names)])
print('absent :', [k for k in key if not any(k==n or n.endswith('/'+k) for n in names)])
# HEAD commit sha
cd=commits.get('data',commits) if isinstance(commits,dict) else {}
cl=cd.get('commits') or []
print('head_sha:', (cl[0].get('sha') if cl and isinstance(cl,list) else None))
```
Expected: prints real values (adapt field paths if GitLink nests differently — inspect raw JSON). Record: license state (expect absent), README/requirements present?, releases (expect 0), HEAD sha, has_dataset.
- [ ] **Step 3: Backfill REFERENCE §九 with real findings**
Replace the `> 此节由 Task 6...回填` line with real data: license state (expected: absent), README present?, requirements present?, releases count (expected: 0), HEAD commit SHA, has_dataset, and each axis's real ✓/✗ (preview the grade — expect B/C due to no license).
- [ ] **Step 4: Commit**
```bash
git add skills/gitlink-research-fair/REFERENCE.md
git commit -m "docs(research-fair): REFERENCE 回填 songhui18 实测结论"
```
---
## Task 7: Live run — 报告卡 + 处方 PR（fork）+ 证书
**Files:**
- (produces real artifacts; outputs captured into Task 8's examples doc)
- [ ] **Step 1: Produce the report card following SKILL.md**
Using Task 6 ground truth, walk the 8-step pipeline on `songhui18/ICCV2021论文复现`: score all 5 axes, build KG (Mermaid), try OpenAlex enrichment (search README for paper title/DOI → query api.openalex.org; if none, mark skipped), render the full report card with real values + sentinel + real commit SHA.
Expected: a complete Markdown report card with a real grade (B/C), real axis scores, real evidence per item.
- [ ] **Step 2: Fork + open remediation PR**
```bash
gitlink-cli repo +fork --owner songhui18 --repo ICCV2021论文复现 --format json
# clone the fork locally, add generated CITATION.cff + LICENSE + 复现章节, commit, push
# then:
gitlink-cli pr +create --owner <你的login> --repo ICCV2021论文复现 \
--head <你的login>:feat/fair-remediation --base master \
--title "Improve research FAIRness & reproducibility (gitlink-research-fair)" \
--body "<报告卡摘要>"
```
Expected: PR created with a numeric id. **Fallback**: if fork/push fails, use `--no-fork` — write CITATION.cff/LICENSE/复现章节 to a local `_remediation/` dir and note "fork 链路不可用，已降级本地物料" in the examples doc.
- [ ] **Step 3: Verify certificate + capture screenshot**
Confirm the certificate line in the report card has the real HEAD commit SHA (from Task 6) and grade. If `swh.model` importable in python, compute full SWH-ID; else keep `git+<sha>`. Capture a screenshot of the opened PR on GitLink web → save to `skills/gitlink-research-fair/examples/img/pr-songhui18.png` (recommended).
- [ ] **Step 4: Commit (artifacts/screenshots only)**
```bash
git add skills/gitlink-research-fair/examples/img/ # if screenshot captured
git commit -m "feat(research-fair): songhui18 实跑报告卡+处方PR+证书（截图）"
```
(No commit if --no-fork fallback and no screenshot — proceed to Task 8.)
---
## Task 8: examples/research-fair-workflow.md — 真实走查
**Files:**
- Create: `skills/gitlink-research-fair/examples/research-fair-workflow.md`
- [ ] **Step 1: Write the real walkthrough using Task 6+7 outputs**
Content skeleton (fill with REAL data from Tasks 6-7):
```markdown
# 示例：科研软件 FAIR 体检（真实数据）
> 基于 `songhui18/ICCV2021论文复现`（论文复现合集，19⭐）于 2026-07-XX 实跑。
## Step 1：取上下文（真实输出摘要）
- license_id: <实测> ｜ 描述: <长度>字 ｜ topics: <...> ｜ has_dataset: <...>
- 关键文件：LICENSE=<有/无> · README=<...> · requirements=<...> · CITATION.cff=<...> · releases=<N>
## Step 2：5 轴评分（真实）
| 轴 | 分 | 关键依据 |
|---|---|---|
| F | <实> | ... |
| A | <实> | 无 license → A2 ✗ |
| I | <实> | ... |
| R | <实> | ... |
| Repro | <实> | ... |
**总体：<等级> <分>/100**
## Step 3：报告卡（真实全文）
<贴 Task 7 报告卡全文，含哨兵>
## Step 4：处方 PR
<PR 链接 / 或 --no-fork 降级说明>，含 CITATION.cff + LICENSE + 复现章节
## Step 5：证书
锚定 commit <SHA>，FAIR <等级>，Repro <状态>
## 对照：有 license 仓库
跑 `<对照仓库>`（有 license）→ 预期 A 级，证明评分区分度。
## 关键结论
- "论文复现"仓库被"可复现性"工具体检：主题共振
- 无 license = 天然缺口，处方有活干
- 与 howfairis 差异：GitLink 原生 + 自动修复 + 证书
```
- [ ] **Step 2: Verify real data (no placeholders)**
Run: `grep -E "TBD|TODO|<等级>|<分>|<实>|<实测>|<SHA>" skills/gitlink-research-fair/examples/research-fair-workflow.md`
Expected: no matches (all `<...>` placeholders filled with real data). If any remain, fill them from Tasks 6-7.
- [ ] **Step 3: Commit**
```bash
git add skills/gitlink-research-fair/examples/research-fair-workflow.md
git commit -m "feat(research-fair): examples songhui18 真实走查"
```
---
## Task 9: 对照仓库跑（证明评分区分度）
**Files:**
- Modify: `skills/gitlink-research-fair/examples/research-fair-workflow.md` (对照 section)
- [ ] **Step 1: Pick a licensed repo and run the pipeline**
Use `leejt/图神经网络快速开发测试工具` (has license_id=Y) — or `Edgedev/Edge深度学习框架`. Run `repo +info` + `file +list` to confirm it has a LICENSE, then score the 5 axes.
Expected: A2 = ✓ (has license) → A axis notably higher than songhui18; overall grade A (≥80) or clearly higher than songhui18's B/C.
- [ ] **Step 2: Fill the 对照 section with real contrast numbers**
Update the "对照：有 license 仓库" section with: repo name, its grade (expect A), and a one-line contrast ("songhui18 B/C（无 license）vs 对照 A（有 license）→ 评分有区分度").
- [ ] **Step 3: Commit**
```bash
git add skills/gitlink-research-fair/examples/research-fair-workflow.md
git commit -m "docs(research-fair): 对照仓库证明评分区分度"
```
---
## Task 10: 注册 + README + workflow 链接 + 最终验收
**Files:**
- Modify: `skills/README.md`
- Modify: `skills/gitlink-workflow/SKILL.md` (optional cross-link)
- [ ] **Step 1: Register the skill (so Claude Code's Skill tool discovers it)**
Run: `bash scripts/setup-skills.sh` (creates the junction into `~/.claude/skills/`). Then verify discovery: `ls ~/.claude/skills/ | grep gitlink-research-fair`.
Expected: `gitlink-research-fair` listed.
- [ ] **Step 2: Add README row**
In `skills/README.md`, add to the 智能 Skills table (near gitlink-review):
```markdown
| **gitlink-research-fair** | 科研软件 FAIR 体检 | 5 轴 FAIR/可复现评分、报告卡、自动修复 PR、SWH/commit 可复现证书 |
```
Verify: `grep -c "gitlink-research-fair" skills/README.md` → `≥1`.
- [ ] **Step 3: (Optional) cross-link from gitlink-workflow**
In `skills/gitlink-workflow/SKILL.md`, under a research/repo-health context, add a line linking to `../gitlink-research-fair/SKILL.md`.
- [ ] **Step 4: Final acceptance check (spec §16)**
Verify each (run/read):
- [ ] `skills/gitlink-research-fair/` 三件套齐全（SKILL.md + REFERENCE.md + examples/）
- [ ] 5 轴 rubric 每项有证据来源 + 状态判定 + 兜底
- [ ] songhui18 真跑通：报告卡 + 处方 PR（或 --no-fork 降级）+ 证书，有截图
- [ ] 对照仓库评分有区分度
- [ ] 边界（私有/空/无 README）降级正确（至少手动核对 SKILL 错误表覆盖）
- [ ] REFERENCE 含引用库 + 2 条禁用论点
- [ ] README 已登记
- [ ] **Step 5: Commit + final state**
```bash
git add skills/README.md skills/gitlink-workflow/SKILL.md
git commit -m "docs(research-fair): README 登记 + workflow 链接 + 注册"
git log --oneline -12
```
Expected: clean commit history on `feat/gitlink-research-fair`, all artifacts present. Then open a PR to master (per protected-branch workflow).

249
docs/superpowers/specs/2026-07-01-gitlink-research-fair-design.md Normal file
View File

@ -0,0 +1,249 @@
# 科研软件 FAIR 体检 Skill（gitlink-research-fair）设计
- **日期**：2026-07-01
- **状态**：已批准，待编写实现计划
- **作者**：CWQ + Claude
- **定位**：子任务四（应用 GitLink 辅助科研，加分项）——把 GitLink 科研仓库转化为"FAIR 体检报告卡 + 自动修复 + 可复现证书"；纯 Markdown skill（SKILL.md + REFERENCE.md + examples/），无需 Go 代码
- **架构中心**：报告卡中心（FAIR 体检报告为 hero 产出，KG/处方/证书/OpenAlex 为其栏目）
---
## 1. 背景与目标
子任务四要求把 gitlink-cli 与学术科研结合，做一个"科研分析层"skill。gitlink-cli 现有 17 个 skill 都是**数据采集/运维型**（issue/pr/search/user/pm/review/health/license/changelog/ci/repo/branch/release/triage/workflow/org/shared），缺少把仓库数据**升维成科研洞察**的能力。
本 skill 填补该缺口：对任意 GitLink 科研仓库执行**结构化、有学术标准依据、低误报**的"FAIR + 可复现性"诊断，产出一张**体检报告卡**，并对发现的缺口**自动开 PR 修复**、用 **SWH/commit 锚定版本**签发**可复现证书**。
**实用性目标**：评分有据（对标 FAIR4RS + howfairis）、每项检查可追溯证据（哪个 gitlink-cli 字段/文件）、缺口可执行修复（生成 CITATION.cff/codemeta.json/LICENSE/复现章节）、能在真实 GitLink 科研仓库跑通。
**创意性目标**：四幕剧本（**诊断 → 处方 → 证书**，v1 不含排行）+ 中国代码托管平台**原生**的科研软件诊断（现有 howfairis/Codefair 只跑 GitHub）+ 知识图谱 + OpenAlex 溯源。
## 2. 非目标（YAGNI）
- **不做多仓库 FAIR 排行榜**（第四幕"排行"留 v2）
- 不做 CI/webhook 自动触发——按需由 agent 调用
- **绝不自动 merge** 修复 PR；处方默认预览确认，`--auto` 仅跳过预览
- **绝不 force-push、绝不碰原仓库**——处方只对 fork 开 PR
- 不修改 gitlink-cli 的 Go 代码——纯 skill 交付物
- 不重复 `gitlink-license` 已有能力——许可证/安全子项**委托复用**它
## 3. 关键决策（用户确认）
| 决策点 | 选择 | 理由 |
|--------|------|------|
| v1 范围 | 诊断 + 处方 + 证书（不做排行） | 保留最惊艳的"自动修复闭环"，避开多仓库验证成本 |
| 验证仓库 | `songhui18/ICCV2021论文复现`（处方走 fork） | "论文复现"主题与"可复现性"内核共振；19⭐真实活跃；无 license=现成缺口 |
| 架构中心 | 报告卡中心（A 方案） | 最强"信服"载体（FAIR4RS 逐项可核对）；避免评委认知过载 |
| 许可证/安全支柱 | 复用 `gitlink-license` | 已有 4 维评分+模式库，不重复造 |
| 发表策略 | 默认预览、确认后开 PR；`--auto` 跳过预览 | 沿用既有"先预览再执行"偏好 |
## 4. 学术依据与差异化（"信服"骨架，每条对抗式核验过）
| 支撑点 | 文献（已核验） | 在 skill 中的用途 |
|--------|----------------|------------------|
| 科研软件 FAIR 原则有国际标准，F1/F1.2/F2/R1.1/R1.2/R2 可逐条机器校验 | Barker et al. 2022, *Nature Sci Data* [s41597-022-01710-x]（3-0 ✓×3） | 评分骨架 |
| 可复现性危机铁证：2024 ICLR/ICML/NeurIPS 论文仅 19.5% 提供官方代码 | PaperCoder [arXiv:2504.17192] Table 9（2-0 ✓） | 开场"为什么重要"硬数据 |
| 结构化对比表/报告卡是有学术先例的成熟范式 | ORKG (K-CAP 2019)（3-0 ✓） | 报告卡范式出处 |
| 仓库数据→RDF 知识图谱的实体/关系 schema 可借鉴（13 实体/47 关系/794 万三元组） | LPWC, ISWC 2023（3-0 ✓） | KG 本体设计 |
| 版本锚定用 SWH-ID（Merkle DAG + git 兼容哈希，本地可生成） | Di Cosmo et al. ICMS 2020 [PMC7340894]（3-0 ✓） | 证书版本锚定 |
| 作者/机构溯源直接调 OpenAlex REST 反查（无需自建索引） | Priem et al. 2022 [arXiv:2205.01833]（3-0 ✓） | 溯源富集 |
| 仓库级 KG 问答在真实仓库跑通（四实体+SZZ+Cypher，CoT 50%→90%） | Repo-KG [arXiv:2412.03815]（3-0 ✓） | KG+推理可行性基线 |
| 科研软件"可用+可复现"有现成徽章体系可对标 | ACM Artifact Badging [acm.org]（5 核验） | 证书/徽章锚 |
| 直接竞品 howfairis（5 维：repository/license/registry/citation/checklist）只跑 GitHub | fair-software/howfairis | 差异化：GitLink 原生 |
**差异化叙事（必须咬死）**：*第一个原生跑在中国代码托管平台上、面向任意科研仓库的实时 FAIR+可复现性诊断 → 自动修复 → 证书闭环，纯 Agent Skill 形态。* 与 Software Heritage（重存档）、Papers With Code（重列表）、OpenAlex（重文献）、ASCL（重天体软件）正交。
**战略时机**：据 TIB 2025-10 博客 *Papers With Code went offline*，PWC 出现下线/不稳定，社区在找替代——中国平台原生科研软件诊断工具是真空（⚠️ 单一二手源，pitch 前自行复核 PWC 状态）。
**诚实边界（不可过度宣称）**：
1. FAIR4RS 原文自称 **aspirational**，F1.2/R1.1/R1.2/R2 可逐条校验，但"全自动合规验证器"社区仍在建（SOMEF/FAIR EVA）——本 skill 是**自建 checker**，这本身是贡献，不说"套用现成标准工具"。
2. **FAIRness ≠ 可复现性**（FAIR 是必要非充分）——报告卡里 Repro **单独成轴**，不混为一谈。
3. OpenAlex 自 2025-02 起 freemium（免费档 ~$1/day、需 API key、100 req/s）——批量控量，单仓演示够。
4. **两条已被证伪的论点禁止使用**：①"MSR 六分类法"、②"FAIR 分高→被引更多"的因果（研究已剔除）。
5. 文献多跑在 GitHub——"在 GitLink 上复刻"是合理外推，必须真机跑通闭环。
## 5. 文件清单与改动范围
| 文件 | 动作 | 内容 |
|------|------|------|
| `skills/gitlink-research-fair/SKILL.md` | 新增 | 主管道、5 轴 rubric、报告卡模板、处方护栏、证书、KG/OpenAlex、错误降级、命令接口 |
| `skills/gitlink-research-fair/REFERENCE.md` | 新增 | FAIR4RS 逐条映射表、评分算法、KG schema(triples)、OpenAlex 字段、SWH-ID 说明、**学术引用库**、诚实边界 |
| `skills/gitlink-research-fair/examples/research-fair-workflow.md` | 新增 | `songhui18/ICCV2021论文复现` 真实走查（报告卡+处方 PR+证书+截图） |
| `skills/README.md` | 修改 | 新增 gitlink-research-fair（科研辅助类） |
| `skills/gitlink-workflow/SKILL.md` | 修改（可选） | 在合适处链回本 skill |
## 6. 命令接口
skill 由 agent 调用，参数（约定，非 CLI 子命令）：
| 参数 | 默认 | 说明 |
|------|------|------|
| `--owner/--repo` | 自动从 cwd 解析 | 目标科研仓库 |
| `--lenses` | 全 5 轴 | 子集，如 `F,A,Repro` |
| `--auto` | 关 | 跳过预览直接开 PR（仍受护栏：不 force-push/不碰原仓/不 merge） |
| `--no-fork` | 关 | 不开 PR，处方物料落本地文件供手动处理 |
| `--enrich` | 开 | 启用 OpenAlex 溯源（限流则自动降级） |
| `--refresh` | 关 | 即使存在旧报告哨兵也重评 |
## 7. 数据流（8 步管道）
```
① 取上下文 repo +info（元数据/license/topics/has_dataset）· file +list（关键文件清单）
② 深采 file +get 读 LICENSE/CITATION.cff/codemeta.json/README/requirements/Dockerfile ·
release +list（版本）· commit +list（SHA）· issue/pr +list（协作）· member +list（作者）
③ FAIR 评分 M1 逐项评 5 轴（许可证/安全子项委托 gitlink-license 流程）→ ✓/✗/⚠/⊥ + 证据 + 置信度
④ KG 构建 M2 四实体(Repo/Contributor/File/Commit)+Paper/Dataset/License 节点 → Mermaid 小图 + triples
⑤ 溯源富集 M3 从 README/CITATION 抽论文 → OpenAlex REST 反查作者/机构（best-effort）
⑥ 渲染报告卡 hero：等级+雷达图+5 轴逐项表+处方摘要+证书栏+KG 小图+溯源栏
⑦ 处方 M4 对 ✗/⚠ 项生成 CITATION.cff/codemeta.json/LICENSE/复现章节 → 默认预览
⑧ 发布 确认后对 fork 开 PR（PR body 带报告卡摘要）+ 出 SWH/commit 锚定证书；内嵌哨兵
```
每项检查的内部数据结构：
```json
{
"axis": "A", "id": "A2", "title": "有明确许可证",
"status": "✗", // ✓满足 | ✗缺失 | ⚠部分 | ⊥无字段(跳过)
"evidence": "repo +info.license_id 为空；根目录无 LICENSE 文件",
"confidence": "high", // high | medium | low
"fix": "建议添加 MIT 或木兰 PSL v2 LICENSE（处方可自动生成）"
}
```
## 8. 评分 Rubric（核心）
> 对标 **FAIR4RS（Nature Sci Data 2022）+ howfairis 5 维**。诚实声明：这是**适配版**评分（社区尚无认证级自动校验器），不是官方认证。**FAIR ≠ 可复现**，故 Repro 单独成轴。
每项判定 `✓满足 / ✗缺失 / ⚠部分 / ⊥GitLink 无该字段(跳过并标注)`，附**证据来源** + 置信度。
| 轴 | FAIR4RS 映射 | 检查项（证据） |
|----|--------------|----------------|
| **F 可发现** | F1/F2 | F1 清晰描述(repo desc 非空且≥20 字) · F2 话题/关键词(topics) · F3 标准元数据(codemeta.json/.zenodo.json) |
| **A 可访问** | F1.2/R1.1 | A1 公开(is_public) · A2 有许可证(license_id/LICENSE)[gitlink-license] · A3 有版本发布(release tag) · A4 持久标识(commit SHA/SWH-ID) |
| **I 可互操作** | R1.1/I | I1 依赖清单(requirements/go.mod/package.json/environment.yml) · I2 许可证机器可读(SPDX/license_id) · I3 元数据标准格式(CITATION.cff/codemeta) |
| **R 可复用** | R1.2/R2 | R1 溯源/引用(CITATION.cff/README 引用) · R2 README 质量(安装+使用) · R3 源码声明[gitlink-license] · R4 无敏感泄露[gitlink-license] |
| **Repro 可复现** ⭐差异轴 | （独立于 FAIR） | Rep1 环境锁(锁版本/Dockerfile) · Rep2 数据集说明(has_dataset/README 引用) · Rep3 复现步骤(README 章节) · Rep4 版本固定 · Rep5 入口可执行(main/Makefile/CLI) |
**评分算法**：轴分 = 满足项 / (总项 − ⊥项)（⚠ 计 0.5）；总评 = 5 轴均分 → 等级 **A🟢≥80 / B🟡60-79 / C🔴<60**。若某轴全部为 ⊥（GitLink 无任何可用字段），该轴记 N/A 并从总评均分中排除。`⊥` 项在报告卡"范围"行注明"GitLink 无 X 字段，已跳过 N 项"，不静默吞掉。`confidence=low` 的项标注"待人工确认"，不进总评分计算。
## 9. 报告卡格式（hero 产出）
```markdown
🏥 **gitlink-research-fair 科研软件体检报告**
**总体**：B 🟡 64/100（F 70 · A 50 · I 40 · R 80 · Repro 80）｜版本锚定：commit a1b2c3d（无 release）
**范围**：检查 19 项（✓11 · ✗4 · ⚠2 · ⊥2，跳过：GitLink 无 codemeta 字段）
### 五轴雷达
Repro 80
/ \
R 80 F 70
\ /
I 40 —— A 50
### 逐项（节选）
| 轴 | 项 | 状态 | 证据 |
|---|---|:---:|---|
| A | A2 有许可证 | ✗ | license_id 空，根目录无 LICENSE |
| Repro | Rep3 复现步骤 | ⚠ | README 有"使用"但无完整复现流程 |
| F | F1 清晰描述 | ✓ | repo desc 详述 CV 顶会论文复现合集 |
### 🔧 处方（可自动修复 3 项）
- [R1] 生成 CITATION.cff（从 README/作者推断）
- [A2] 添加 LICENSE（MIT / 木兰 PSL v2 任选）
- [Rep3] 补"复现"章节（从入口推断）
### 📜 可复现证书
锚定版本：git+commit a1b2c3d ｜ FAIR: B 🟡 ｜ Repro: ⚠ 部分可复现
（完整 SWH-ID 需 swh-identify；本次用 commit-SHA 锚定）
### 🔗 溯源（OpenAlex）
未找到关联论文（README 未含可识别 DOI/标题）— 已跳过
### 🧬 科研关系图（KG）
[Mermaid: Repo—contributes→Contributor×3 · Repo—licensed?—? · Repo—has→Dataset? ]
---
<!-- gitlink-research-fair v1 | repo:songhui18/ICCV2021论文复现 | grade:B | sha:a1b2c3d -->
*由 gitlink-research-fair skill 生成。*
```
哨兵 `<!-- gitlink-research-fair v1 | repo | grade | sha -->` 用于幂等与"基于哪个 commit"标识。
## 10. 处方模块（M4，惊艳闭环）与安全护栏
对可自动修复的 ✗/⚠ 项生成物料：
| 缺口 | 生成物 |
|------|--------|
| F3 缺 codemeta.json | 从 repo +info + README 生成 codemeta.json 草稿 |
| R1 缺 CITATION.cff | 从 README/作者生成 CITATION.cff 草稿 |
| A2 缺 license | 给 MIT / 木兰 PSL v2 模板（任选） |
| Rep1 缺依赖锁 | 从 import 扫描建议 requirements.txt |
| Rep3 缺复现章节 | 从入口/README 生成"复现"章节草稿 |
**安全护栏**（沿用既有偏好）：
- 默认全量预览 → 用户确认 → 对 **fork**（`caoweiqiong/ICCV2021论文复现`）开一个 PR，PR body 带报告卡摘要
- `--auto` 跳过预览，但**永不 force-push、永不碰原仓库、永不自动 merge**
- `--no-fork`：不开 PR，物料落本地文件供手动处理
- 所有写操作需认证（遵循 `gitlink-shared`）
## 11. 证书（SWH/commit 锚定）
- 版本锚定：HEAD commit SHA + release tag（若有）
- 若环境有 Python `swh.model` → 算完整 SWH-ID；否则用 `git+<commit-SHA>` 锚定，报告卡标注"完整 SWH-ID 需 swh-identify"
- 证书内容：仓库、锚定版本、FAIR 等级、Repro 状态、生成时间、可引用条目（对标 ACM Artifact Badge 的 Available/Functional 风格）
- 嵌入报告卡"证书栏"；亦可单独输出可复制引用文本
## 12. KG + OpenAlex（支撑栏，非主角）
- **KG**：四实体（Repo / Contributor / File / Commit）+ Paper / Dataset / License 节点；关系 contributes-to / authored / depends-on / cites / licensed-under / version-at。输出 Mermaid 小图（报告卡内嵌）+ triples JSON（REFERENCE 给 schema）。借鉴 LPWC 实体/关系划分与 Repo-KG 四实体。
- **OpenAlex**：从 README/CITATION 抽论文标题/作者/DOI → REST `/works` 反查作者机构/发表载体/概念。降级：freemium 限流或抽不到 → 跳过，标注"未找到关联论文"，不影响主报告卡。
## 13. 错误处理与降级
| 情况 | 处理 |
|------|------|
| `file +tree --recursive` 返回空 | 手动递归子目录（gitlink-license 已知坑） |
| 无 LICENSE | A2 ✗，处方建议模板 |
| OpenAlex 限流/无果 | 跳过溯源栏标注 |
| `swh.model` 不可用 | commit-SHA 锚定 + 标注 |
| 仓库过大 | 抽样文件 + "部分审查"标注 |
| fork 失败/无写权限 | 处方物料落本地文件供手动 PR |
| 二进制是 npm 旧版 | 强制 `./gitlink-cli` 或提示 `go build` 重建 |
| 仓库私有/无权限 | 清晰错误，不发报告 |
| 报告/PR 发布失败 | 报告卡原文交用户手动粘贴 |
## 14. 验证计划（真实数据）
主目标：**`songhui18/ICCV2021论文复现`**（论文复现合集，19⭐/17fork，Python/CUDA/Jupyter，无 license）。
验证项：
- [ ] 报告卡正确给出 B/C 级（因无 license，A2 ✗），5 轴评分有区分度
- [ ] 处方：fork 后成功开 1 个 PR（CITATION.cff + LICENSE + 复现章节），PR body 含报告卡摘要
- [ ] 证书：commit-SHA 锚定正确（若有 swh.model 则给完整 SWH-ID）
- [ ] **对照**：跑一个有 license 的仓库（`leejt/图神经网络快速开发测试工具` 或 `Edgedev/Edge深度学习框架`）→ 预期 A 级，证明评分有区分度
- [ ] **边界**：私有仓 / 空仓 / 无 README → 降级正确，不崩溃
- [ ] OpenAlex 溯源：能抽到论文则富集，抽不到则标注降级
- [ ] KG：Mermaid 图 + triples JSON 正确生成
结果（真实输出 + 截图）写入 `examples/research-fair-workflow.md`。
## 15. 风险与未决
- **GitLink 元数据粒度**：FAIR4RS 某些条目（如 R2 限定引用、标准 codemeta）GitLink 无专用字段 → 用 ⊥ 跳过 + 文件探测 + LLM 推断兜底，明确标注"推断 vs 已验证"。实现时需在真实仓库上确认哪些项可机器读取。
- **OpenAlex freemium 限额**：2025-02 起；单仓演示够，批量需控量。
- **SWH-ID 完整性**：纯 Markdown+CLI 环境无 `swh.model` 时只能 commit-SHA 锚定；实现时探测依赖，降级已内建。
- **GitLink GraphQL/REST 粒度**：Repo-KG 的 Cypher QA 需图数据库，本 skill **不引入图数据库**（纯 Mermaid+triples），KG 仅作可视化/溯源，不做复杂问答（YAGNI）。
- **处方 PR 真实性**：对 fork 开 PR 需 `gitlink-cli repo +fork` + 本地改文件 + push + `pr +create`；需实测 fork→PR 链路是否顺畅，不通则降级 `--no-fork`。
## 16. 验收标准
1. `skills/gitlink-research-fair/` 三件套齐全，结构与 health/changelog/triage/review 等智能 skill 一致
2. 5 轴 rubric 每项有明确证据来源 + 状态判定 + 兜底规则
3. `songhui18/ICCV2021论文复现` 真实跑通：报告卡 + 处方 PR（对 fork）+ 证书，有截图
4. 对照仓库评分有区分度（有 license → A，无 → B/C）
5. 边界情况（私有/空/无 README）降级正确
6. REFERENCE.md 含完整学术引用库 + 诚实边界（含 2 条禁用论点）
7. README 登记 gitlink-research-fair

1
skills/README.md
View File

@ -162,6 +162,7 @@ skills/
| **gitlink-changelog** | Release Notes 自动生成 | 从 commit/PR/Issue 历史自动生成版本说明 |
| **gitlink-triage** | Issue 智能分拣 + 新人引导 | 自动分类、打标签、分配责任人、good-first-issue 引导 |
| **gitlink-review** | 智能代码审查 | 分析 PR diff，多视角评审 + 对抗式自检，结构化 Review 意见自动评论 |
| **gitlink-research-fair** | 科研软件 FAIR 体检 | 5 轴 FAIR/可复现评分、体检报告卡、自动开 PR 修复缺口、SWH/commit 可复现证书 |
---

105
skills/gitlink-research-fair/REFERENCE.md Normal file
View File

@ -0,0 +1,105 @@
# gitlink-research-fair 参考文档
> 本文件为 SKILL.md 的深度参考。评分细则、KG schema、OpenAlex/SWH 技术细节、学术引用库与诚实边界均在此。
## 一、FAIR4RS 逐条映射
| 原则 | 含义 | 本 Skill 检查项 | GitLink 证据 | 兜底（无字段时） |
|------|------|----------------|--------------|------------------|
| F1 | 全局唯一持久标识 | A4 持久标识 | repo identifier/URL + commit SHA | commit-SHA 锚定 |
| F1.2 | 版本级唯一标识 | A3 有版本发布 | `release +list` | ✗（无 release tag） |
| F2 | 富元数据 | F1 描述/F2 topics/F3 codemeta | `repo +info` desc/topics；`file +get` codemeta.json | README 抽取（标注推断） |
| R1.1 | 清晰可访问许可证 | A2/I2 | `repo +info` license_id；LICENSE 文件 | gitlink-license 识别 |
| R1.2 | 详细溯源 | R1 | CITATION.cff/README 引用 | LLM 从 README 推断（标注） |
| R2 | 对其他软件的限定引用 | R3 | 源码 SPDX/依赖清单 | gitlink-license 维度4 |
## 二、评分算法
- 每项状态：`✓`(1) / `⚠`(0.5) / `✗`(0) / `⊥`(跳过，不计入分母)
- 轴分 = Σ状态值 / (轴内项数 − ⊥项数) × 100
- 总评 = 各轴分均值（全 ⊥ 轴记 N/A 排除）
- 等级：A🟢≥80 / B🟡60-79 / C🔴<60
- `confidence=low`：标注"待人工确认"，不计入分子分母
## 三、可复现性 checklist（独立于 FAIR）
Rep1 环境锁（requirements 锁版本/Dockerfile/environment.yml）· Rep2 数据集说明（has_dataset/README 引用/下载脚本）· Rep3 复现步骤（README "运行/复现/Quick Start" 章节）· Rep4 版本固定（release tag 或 commit 锚定）· Rep5 入口可执行（main.py/train.py/Makefile/CLI）
## 四、KG schema（triples）
实体：Repo, Contributor, File, Commit, Paper, Dataset, License
关系（主谓宾三元组）：
- (Contributor)—contributes-to→(Repo)
- (Contributor)—authored→(Paper)
- (Repo)—depends-on→(File/依赖)
- (Paper)—cites→(Paper)
- (Repo)—licensed-under→(License)
- (Repo)—version-at→(Commit)
- (Repo)—has→(Dataset)
输出：`triples.json`（数组 of {s,p,o}）+ Mermaid `graph LR` 小图。
## 五、OpenAlex 字段
- 端点：`https://api.openalex.org/works?search=<title>` （2025-02 起 freemium，建议带 `mailto` 参数走 polite pool）
- 取字段：`authorships[].author.display_name`、`authorships[].institutions[].display_name`、`host_venue.display_name`（或 `primary_location.source.display_name`）、`concepts[].display_name`、`doi`
- 降级：HTTP 429/503/无结果 → 报告卡溯源栏标"未找到关联论文"
## 六、SWH-ID 说明
- 完整 SWH-ID = `swh:1:dir:<hash>` 或 `swh:1:rev:<hash>`，基于 Merkle DAG，需 `swh.model`（Python）计算或 `swh-identify`
- 环境无 `swh.model` 时：用 `git+<commit-SHA>` 作版本锚定，报告卡标注"完整 SWH-ID 需 swh-identify"
- commit SHA 来自 `commit +list`（HEAD）
## 七、学术引用库（"信服"骨架，每条对抗式核验过）
| 支撑点 | 文献 |
|--------|------|
| 科研软件 FAIR 原则 F1/F1.2/F2/R1.1/R1.2/R2 可机器校验 | Barker et al. 2022, *Nature Scientific Data*, https://www.nature.com/articles/s41597-022-01710-x |
| 可复现性危机：2024 ICLR/ICML/NeurIPS 仅 19.5% 提供官方代码 | PaperCoder, arXiv:2504.17192 (Table 9) |
| 结构化对比表/报告卡范式 | ORKG, Jaradeh et al. K-CAP 2019 |
| 仓库→RDF 知识图谱 schema（13 实体/47 关系/794 万三元组） | LPWC, ISWC 2023 |
| SWH-ID 版本锚定（Merkle DAG, git 兼容） | Di Cosmo et al. ICMS 2020, PMC7340894 |
| 作者/机构溯源用 OpenAlex REST | Priem et al. 2022, arXiv:2205.01833 |
| 仓库级 KG 问答（四实体+SZZ+Cypher, CoT 50%→90%） | Repo-KG, arXiv:2412.03815 |
| 科研软件可复现徽章体系 | ACM Artifact Review Badging, https://www.acm.org/publications/policies/artifact-review-badging |
| 直接竞品 howfairis（5 维，仅 GitHub） | https://github.com/fair-software/howfairis |
| 战略时机：PWC 不稳定 | TIB 博客 2025-10 "Papers With Code went offline"（单一二手源，pitch 前复核） |
## 八、诚实边界（不可过度宣称）
1. FAIR4RS 自称 **aspirational**；本 Skill 是**自建 checker**（社区尚无认证级校验器），不说"套用现成标准工具"。
2. **FAIRness ≠ 可复现性**（FAIR 必要非充分）—— Repro 单独成轴。
3. OpenAlex 自 2025-02 起 freemium（~$1/day、需 key、100 req/s）—— 单仓演示够，批量控量。
4. **禁止使用两条已证伪论点**：①"MSR 六分类法"、②"FAIR 分高→被引更多"因果。
5. 文献多跑在 GitHub；"在 GitLink 上复刻"是合理外推，须真机跑通闭环。
## 九、实测结论（live probe，2026-07-01 于 songhui18/ICCV2021）
**目标仓库**：`songhui18/ICCV2021`（显示名"ICCV2021论文复现"，URL identifier = `ICCV2021`，**注意 CLI 要用 identifier 不是中文显示名**），19⭐/17fork，3328 文件，17 个论文复现子目录，最后更新约 4 年前。
**关键事实**：
- `license_id` = None；**根目录无 LICENSE**（20 个 LICENSE 全在子目录随上游代码）→ **A2 ✗**
- releases = 0（无任何版本发布）→ **A3 ✗ / Rep4 ✗**
- 根级文件仅 `README.md`；无根级 requirements.txt / CITATION.cff / codemeta.json / .zenodo.json
- CITATION.cff=0、codemeta.json=0、.zenodo.json=0 → **F3 ✗ / I3 ✗ / R1 ✗**
- requirements.txt 13 处（仅子目录）、Dockerfile 5、Makefile 3、main.py 13、train.py 16、test.py 15 → 子目录复现较完整，但**根级无统一依赖锁**
- `has_dataset` = False → **Rep2 ✗**
- topics = [python, jupyter notebook, cuda] → **F2 ✓**；description 详尽（≥20 字）→ **F1 ✓**
- HEAD commit SHA = `e14ac625752171fd46c90778cf5c7b000d05307b`
**5 轴实测分**：F 67 · A 50 · I 17 · R 50 · Repro 40 → **总评 C 🔴 45/100**
| 轴 | 分 | 关键依据 |
|----|----|----------|
| 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⚠ 子目录 requirements 无根级锁 · Rep2✗ 无数据集说明 · Rep3⚠ 子目录有步骤无统一复现章 · Rep4✗ 无 release · Rep5✓ 入口齐全 |
**结论**：一个 19⭐ 的"论文复现"合集，FAIR/可复现维度仅得 C——无仓库级 license、无 release、无 CITATION、无数据集说明、依赖散落子目录。**正好印证可复现性危机**（2024 顶会仅 19.5% 提供官方代码）。处方空间大：补根级 LICENSE + CITATION.cff + 统一 requirements + 打 v1.0 release + README 复现章节。
> **fork→PR 链路（Task 7 实测，2026-07-01）**：✅ 跑通。`repo +fork` → `branch +create feat/fair-remediation --from master` → `file +create` 建 4 文件（LICENSE / CITATION.cff / codemeta.json / REPRODUCIBILITY.md）→ `pr +create` → **PR #1**（`caoweiqiong/ICCV2021#1`，open，id 145336）。**全程纯 API 建文件，无需克隆 3328 文件大仓**（`file +create` 支持 `--branch`）。
> **OpenAlex 溯源（Task 7 实测）**：⚠️ 匿名搜索被限流（HTTP 503 *"rate-limited due to heavy load, use free API key"*），溯源栏降级跳过——**正好印证 freemium 边界（§八-3）**，skill 优雅降级、报告卡标注"未命中"。
> **SWH-ID（Task 7 实测）**：环境无 `swh.model`，证书用 `git+commit e14ac62` 锚定（符合 §六降级）。

152
skills/gitlink-research-fair/SKILL.md Normal file
View File

@ -0,0 +1,152 @@
---
name: gitlink-research-fair
version: 1.0.0
description: "科研软件 FAIR 体检：分析 GitLink 科研仓库的可发现/可访问/可互操作/可复用/可复现性，输出体检报告卡，自动开 PR 修复缺口并签发 SWH/commit 锚定的可复现证书。当用户需要评估科研仓库的 FAIR 性与可复现性、生成科研软件体检报告时触发。"
metadata:
requires:
bins: ["gitlink-cli"]
cliHelp: "gitlink-cli repo --help"
---
# gitlink-research-fair（科研软件 FAIR 体检）
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有写操作（开修复 PR）默认先预览、确认后再执行；`--auto` 跳过预览但仍受护栏约束。**
**CRITICAL — 绝不自动 merge；绝不 force-push；处方只对 fork 开 PR，绝不碰原仓库。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；详细检查清单、评分算法、KG schema 与学术引用见 [`REFERENCE.md`](REFERENCE.md)。
## 概述
本 Skill 引导 AI 对任意 GitLink 科研仓库做结构化、有学术标准依据、低误报的"FAIR + 可复现性"诊断，产出**体检报告卡**，并对缺口**自动开 PR 修复**、用 **SWH/commit 锚定**签发**可复现证书**。许可证/安全子项**复用 `gitlink-license`**。四幕剧本（v1）：诊断 → 处方 → 证书。
## 命令接口（skill 约定参数，非 CLI flag）
| 参数 | 默认 | 说明 |
|------|------|------|
| `--owner/--repo` | 自动从 cwd 解析 | 目标科研仓库 |
| `--lenses` | 全 5 轴 | 子集，如 `F,A,Repro` |
| `--auto` | 关 | 跳过预览直接开 PR（仍受护栏） |
| `--no-fork` | 关 | 不开 PR，处方物料落本地 |
| `--enrich` | 开 | 启用 OpenAlex 溯源（限流自动降级） |
| `--refresh` | 关 | 即使有旧报告哨兵也重评 |
## 管道（8 步）
### ① 取上下文
`repo +info`（元数据/license/topics/has_dataset）· `file +list`（关键文件清单）
### ② 深采
`file +get` 读 LICENSE/CITATION.cff/codemeta.json/README/requirements/Dockerfile · `release +list`（版本）· `commit +list`（SHA）· `issue/pr +list`（协作）· `member +list`（作者）
### ③ FAIR 评分（M1）
逐项评 5 轴（许可证/安全子项委托 `gitlink-license` 流程）→ `✓/✗/⚠/⊥` + 证据 + 置信度
### ④ KG 构建（M2）
四实体(Repo/Contributor/File/Commit)+Paper/Dataset/License 节点 → Mermaid 小图 + triples JSON
### ⑤ 溯源富集（M3）
从 README/CITATION 抽论文 → OpenAlex REST 反查作者/机构（best-effort）
### ⑥ 渲染报告卡（hero）并落盘
等级 + 雷达图 + 5 轴逐项表 + 处方摘要 + 证书栏 + KG 小图 + 溯源栏。
**始终保存为本地文件** `report-cards/<owner>-<repo>-report-card.md`（cwd 下，含哨兵）——报告卡是可归档/复查的核心产物，**无论后续是否开 PR 都必须落盘，绝不只在终端输出**。
### ⑦ 处方（M4）
对 `✗/⚠` 项生成 CITATION.cff/codemeta.json/LICENSE/复现章节 → 默认预览
### ⑧ 发布
报告卡已在 ⑥ 落盘（`report-cards/<owner>-<repo>-report-card.md`）。
- **fork 模式**：确认后对 fork 开 PR（PR body 带报告卡摘要）+ 出 SWH/commit 证书
- **`--no-fork` 或 PR 失败**：报告卡已在本地，告知用户路径，可手动粘贴或提交
- 哨兵内嵌于报告卡（及 PR body，若开）
## 5 轴评分 Rubric
> 对标 **FAIR4RS（Nature Sci Data 2022）+ howfairis 5 维**。诚实声明：这是**适配版**评分（社区尚无认证级自动校验器），不是官方认证。**FAIR ≠ 可复现**，故 Repro 单独成轴。逐条映射与证据见 [`REFERENCE.md`](REFERENCE.md)。
每项判定 `✓满足 / ✗缺失 / ⚠部分 / ⊥GitLink 无该字段(跳过并标注)`，附证据来源 + 置信度。
| 轴 | FAIR4RS 映射 | 检查项（证据） |
|----|--------------|----------------|
| **F 可发现** | F1/F2 | F1 清晰描述(repo desc ≥20 字) · F2 话题/关键词(topics) · F3 标准元数据(codemeta.json/.zenodo.json) |
| **A 可访问** | F1.2/R1.1 | A1 公开(is_public) · A2 有许可证(license_id/LICENSE)[gitlink-license] · A3 有版本发布(release tag) · A4 持久标识(commit SHA/SWH-ID) |
| **I 可互操作** | R1.1/I | I1 依赖清单(requirements/go.mod/package.json/environment.yml) · I2 许可证机器可读(SPDX/license_id) · I3 元数据标准格式(CITATION.cff/codemeta) |
| **R 可复用** | R1.2/R2 | R1 溯源/引用(CITATION.cff/README 引用) · R2 README 质量(安装+使用) · R3 源码声明[gitlink-license] · R4 无敏感泄露[gitlink-license] |
| **Repro 可复现** ⭐差异轴 | （独立于 FAIR） | Rep1 环境锁(锁版本/Dockerfile) · Rep2 数据集说明(has_dataset/README 引用) · Rep3 复现步骤(README 章节) · Rep4 版本固定 · Rep5 入口可执行(main/Makefile/CLI) |
**评分**：轴分 = 满足项 / (总项 − ⊥项)（⚠ 计 0.5）；总评 = 5 轴均分（某轴全 ⊥ 则记 N/A 并排除）；等级 **A🟢≥80 / B🟡60-79 / C🔴<60**。`confidence=low` 标"待人工确认"，不进总评。
## 报告卡格式（hero 产出）
````markdown
🏥 **gitlink-research-fair 科研软件体检报告**
**总体**：<等级> <分>/100（F · A · I · R · Repro）｜版本锚定：commit <sha>（<release 或 无>）
**范围**：检查 19 项（✓N · ✗N · ⚠N · ⊥N，跳过：<原因>）
### 五轴雷达
（ASCII 或 Mermaid 雷达：F/A/I/R/Repro）
### 逐项
| 轴 | 项 | 状态 | 证据 |
|---|---|:---:|---|
| <轴> | <id 项名> | ✓/✗/⚠/⊥ | <gitlink-cli 证据> |
### 🔧 处方（可自动修复 N 项）
- [<轴><id>] <生成物>（从 <来源> 推断）
### 📜 可复现证书
锚定版本：git+commit <sha> ｜ FAIR: <等级> ｜ Repro: <状态>
（完整 SWH-ID 需 swh-identify；本次用 commit-SHA 锚定）
### 🔗 溯源（OpenAlex）
<作者/机构/载体 或 "未找到关联论文，已跳过">
### 🧬 科研关系图（KG）
```mermaid
<Repo—contributes→Contributor · Repo—licensed?—? · Repo—has→Dataset?>
```
---
<!-- gitlink-research-fair v1 | repo:<owner>/<repo> | grade:<G> | sha:<head-sha> -->
*由 gitlink-research-fair skill 生成。*
````
哨兵 `<!-- gitlink-research-fair v1 | repo | grade | sha -->` 用于幂等与"基于哪个 commit"标识。重跑检测旧哨兵 → 默认提议更新（`--refresh` 才覆盖）；`sha` 不匹配 → 提示"报告已过期，建议重评"。
## 处方（M4，惊艳闭环）
| 缺口 | 生成物 |
|------|--------|
| F3 缺 codemeta.json | 从 repo +info + README 生成 codemeta.json 草稿 |
| R1 缺 CITATION.cff | 从 README/作者生成 CITATION.cff 草稿 |
| A2 缺 license | 给 MIT / 木兰 PSL v2 模板（任选） |
| Rep1 缺依赖锁 | 从 import 扫描建议 requirements.txt |
| Rep3 缺复现章节 | 从入口/README 生成"复现"章节草稿 |
**安全护栏**：默认全量预览 → 确认 → 对 **fork** 开一个 PR（PR body 带报告卡摘要）；`--auto` 跳过预览但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 物料落本地。所有写操作需认证。
## 证书（SWH/commit 锚定）
用 HEAD commit SHA + release tag 锚定版本。若环境有 Python `swh.model` → 算完整 SWH-ID；否则 `git+<commit-SHA>` 锚定，报告卡标注"完整 SWH-ID 需 swh-identify"。证书含：仓库、锚定版本、FAIR 等级、Repro 状态、可引用条目（对标 ACM Artifact Badge）。嵌报告卡证书栏。
## KG + OpenAlex（支撑栏）
- **KG**：四实体(Repo/Contributor/File/Commit)+Paper/Dataset/License；关系 contributes-to/authored/depends-on/cites/licensed-under/version-at。输出 Mermaid 小图 + triples JSON（schema 见 REFERENCE）。
- **OpenAlex**：README/CITATION 抽论文 → REST `/works` 反查作者/机构/载体。降级：限流或抽不到 → 跳过，标注"未找到关联论文"。
## 错误处理与降级
| 情况 | 处理 |
|------|------|
| `file +tree --recursive` 返回空 | 手动递归子目录 |
| 无 LICENSE | A2 ✗，处方建议模板 |
| OpenAlex 限流/无果 | 跳过溯源栏标注 |
| `swh.model` 不可用 | commit-SHA 锚定 + 标注 |
| 仓库过大 | 抽样文件 + "部分审查"标注 |
| fork 失败/无写权限 | 处方物料落本地（`--no-fork`） |
| 二进制是 npm 旧版 | 强制 `./gitlink-cli` 或 `go build` 重建 |
| 仓库私有/无权限 | 清晰错误，不发报告 |
| 报告/PR 发布失败 | 报告卡已在 ⑥ 落盘，告知路径，用户可手动粘贴/提交 |

154
skills/gitlink-research-fair/examples/research-fair-workflow.md Normal file
View File

@ -0,0 +1,154 @@
# 示例：科研软件 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 项（✓6 · ✗8 · ⚠4 · ⊥1，⊥：R3 源码声明委托 gitlink-license 未在本轮跑）
### 逐项（节选）
| 轴 | 项 | 状态 | 证据 |
|---|---|:---:|---|
| A | A2 有许可证 | ✗ | `license_id` 为空，根目录无 LICENSE（20 个 LICENSE 全在子目录） |
| F | F3 标准元数据 | ✗ | 无 codemeta.json / .zenodo.json |
| I | I1 依赖清单 | ⚠ | requirements.txt 仅在 13 个子目录，无根级统一锁 |
| R | R1 溯源/引用 | ✗ | 无 CITATION.cff |
| R | R3 源码声明 | ⊥ | 委托 gitlink-license，本轮未跑深度源码声明扫描 |
| 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 v1 | repo:songhui18/ICCV2021 | grade:C | sha:e14ac625 -->
*由 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 且只打分不修复。

1
skills/gitlink-workflow/SKILL.md
View File

@ -27,6 +27,7 @@ metadata:
> - Issue 智能分拣 → [`../gitlink-triage/SKILL.md`](../gitlink-triage/SKILL.md)
> - Release Notes 生成 → [`../gitlink-changelog/SKILL.md`](../gitlink-changelog/SKILL.md)
> - 项目健康报告 → [`../gitlink-health/SKILL.md`](../gitlink-health/SKILL.md)
> - 科研软件 FAIR 体检 → [`../gitlink-research-fair/SKILL.md`](../gitlink-research-fair/SKILL.md)
## 工作流 1：PR 全流程