From 241653a7b5a1c9613b895e9ce7c8dfcfdaab492d Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 1 Jul 2026 11:39:35 +0800 Subject: [PATCH 01/11] =?UTF-8?q?docs(research-fair):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=20gitlink-research-fair=20=E8=AE=BE=E8=AE=A1=20spec=EF=BC=88FA?= =?UTF-8?q?IR=E4=BD=93=E6=A3=80=E6=8A=A5=E5=91=8A=E5=8D=A1+=E5=A4=84?= =?UTF-8?q?=E6=96=B9+=E8=AF=81=E4=B9=A6=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 子任务四（应用GitLink辅助科研）的设计文档： - 报告卡中心架构，5轴 FAIR rubric（对标 FAIR4RS + howfairis），Repro 单独成轴 - 四幕剧本 v1：诊断+处方+证书（不做排行） - 复用 gitlink-license 做许可证/安全支柱 - 验证目标 songhui18/ICCV2021论文复现（处方走 fork） - 含学术引用库与诚实边界（2条已证伪论点禁用） Co-Authored-By: Claude Opus 4.8 --- ...2026-07-01-gitlink-research-fair-design.md | 249 ++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-01-gitlink-research-fair-design.md diff --git a/docs/superpowers/specs/2026-07-01-gitlink-research-fair-design.md b/docs/superpowers/specs/2026-07-01-gitlink-research-fair-design.md new file mode 100644 index 0000000..213c0a6 --- /dev/null +++ b/docs/superpowers/specs/2026-07-01-gitlink-research-fair-design.md @@ -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 skill 生成。* +``` + +哨兵 `` 用于幂等与"基于哪个 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+` 锚定，报告卡标注"完整 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 -- 2.34.1 From cf2b566bd3eb380c13f5148c49804abf93a64a74 Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 1 Jul 2026 12:58:23 +0800 Subject: [PATCH 02/11] =?UTF-8?q?docs(research-fair):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E8=AE=A1=E5=88=92=EF=BC=8810=20=E4=BB=BB?= =?UTF-8?q?=E5=8A=A1=EF=BC=8CTDD=20=E9=80=82=E9=85=8D=E4=B8=BA=20grep/?= =?UTF-8?q?=E5=AE=9E=E8=B7=91=E9=AA=8C=E8=AF=81=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 --- .../plans/2026-07-01-gitlink-research-fair.md | 638 ++++++++++++++++++ 1 file changed, 638 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-01-gitlink-research-fair.md diff --git a/docs/superpowers/plans/2026-07-01-gitlink-research-fair.md b/docs/superpowers/plans/2026-07-01-gitlink-research-fair.md new file mode 100644 index 0000000..c610028 --- /dev/null +++ b/docs/superpowers/plans/2026-07-01-gitlink-research-fair.md @@ -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 ` 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 （） +**范围**：检查 19 项（✓N · ✗N · ⚠N · ⊥N，跳过：<原因>） + +### 五轴雷达 +（ASCII 或 Mermaid 雷达：F/A/I/R/Repro） + +### 逐项 +| 轴 | 项 | 状态 | 证据 | +|---|---|:---:|---| +| <轴> | | ✓/✗/⚠/⊥ | | + +### 🔧 处方（可自动修复 N 项） +- [<轴>] <生成物>（从 <来源> 推断） + +### 📜 可复现证书 +锚定版本：git+commit ｜ FAIR: <等级> ｜ Repro: <状态> +（完整 SWH-ID 需 swh-identify；本次用 commit-SHA 锚定） + +### 🔗 溯源（OpenAlex） +<作者/机构/载体 或 "未找到关联论文，已跳过"> + +### 🧬 科研关系图（KG） +\`\`\`mermaid + +\`\`\` + +--- + +*由 gitlink-research-fair skill 生成。* +\`\`\` + +哨兵 `` 用于幂等与"基于哪个 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+` 锚定，报告卡标注"完整 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=` （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). -- 2.34.1 From b69023a405d8cd0fe9c451b95be47ab81f5cd288 Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 14:35:43 +0800 Subject: [PATCH 03/11] =?UTF-8?q?feat(research-fair):=20SKILL.md=20?= =?UTF-8?q?=E5=AE=8C=E6=95=B4=E5=AE=9E=E7=8E=B0=EF=BC=88frontmatter+?= =?UTF-8?q?=E7=AE=A1=E9=81=93+5=E8=BD=B4rubric+=E6=8A=A5=E5=91=8A=E5=8D=A1?= =?UTF-8?q?+=E5=A4=84=E6=96=B9+=E8=AF=81=E4=B9=A6+KG+=E9=99=8D=E7=BA=A7?= =?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 <noreply@anthropic.com> --- skills/gitlink-research-fair/SKILL.md | 148 ++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 skills/gitlink-research-fair/SKILL.md diff --git a/skills/gitlink-research-fair/SKILL.md b/skills/gitlink-research-fair/SKILL.md new file mode 100644 index 0000000..8340e56 --- /dev/null +++ b/skills/gitlink-research-fair/SKILL.md @@ -0,0 +1,148 @@ +--- +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 小图 + 溯源栏 + +### ⑦ 处方（M4） +对 `✗/⚠` 项生成 CITATION.cff/codemeta.json/LICENSE/复现章节 → 默认预览 + +### ⑧ 发布 +确认后对 fork 开 PR（PR body 带报告卡摘要）+ 出 SWH/commit 证书；内嵌哨兵 + +## 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 发布失败 | 报告卡原文交用户手动粘贴 | -- 2.34.1 From f763132868e7d18d0daf272d300386bf1b7a406b Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 14:38:51 +0800 Subject: [PATCH 04/11] =?UTF-8?q?fix(research-fair):=20=E6=8A=A5=E5=91=8A?= =?UTF-8?q?=E5=8D=A1=E6=A8=A1=E6=9D=BF=E5=A4=96=E5=B1=82=E6=94=B9=204=20?= =?UTF-8?q?=E5=8F=8D=E5=BC=95=E5=8F=B7=E5=9B=B4=E6=A0=8F=EF=BC=8C=E9=81=BF?= =?UTF-8?q?=E5=85=8D=E5=B5=8C=E5=A5=97=20fence=20=E6=8F=90=E5=89=8D?= =?UTF-8?q?=E9=97=AD=E5=90=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- skills/gitlink-research-fair/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/gitlink-research-fair/SKILL.md b/skills/gitlink-research-fair/SKILL.md index 8340e56..5a6f7e0 100644 --- a/skills/gitlink-research-fair/SKILL.md +++ b/skills/gitlink-research-fair/SKILL.md @@ -76,7 +76,7 @@ metadata: ## 报告卡格式（hero 产出） -```markdown +````markdown 🏥 **gitlink-research-fair 科研软件体检报告** **总体**：<等级> <分>/100（F · A · I · R · Repro）｜版本锚定：commit <sha>（<release 或 无>） @@ -108,7 +108,7 @@ metadata: --- <!-- 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` 不匹配 → 提示"报告已过期，建议重评"。 -- 2.34.1 From 929d89f063387a68fbaab20dcb3996864daddff1 Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 14:40:40 +0800 Subject: [PATCH 05/11] =?UTF-8?q?feat(research-fair):=20REFERENCE=EF=BC=88?= =?UTF-8?q?FAIR4RS=E6=98=A0=E5=B0=84+=E8=AF=84=E5=88=86+KG=20schema+?= =?UTF-8?q?=E5=BC=95=E7=94=A8=E5=BA=93+=E8=AF=9A=E5=AE=9E=E8=BE=B9?= =?UTF-8?q?=E7=95=8C=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 <noreply@anthropic.com> --- skills/gitlink-research-fair/REFERENCE.md | 79 +++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 skills/gitlink-research-fair/REFERENCE.md diff --git a/skills/gitlink-research-fair/REFERENCE.md b/skills/gitlink-research-fair/REFERENCE.md new file mode 100644 index 0000000..92a1e8b --- /dev/null +++ b/skills/gitlink-research-fair/REFERENCE.md @@ -0,0 +1,79 @@ +# 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 是否命中。 -- 2.34.1 From 07d9c4044ba00075584bf1c162b5de6f638a720e Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 14:51:42 +0800 Subject: [PATCH 06/11] =?UTF-8?q?docs(research-fair):=20REFERENCE=20=C2=A7?= =?UTF-8?q?=E4=B9=9D=20=E5=9B=9E=E5=A1=AB=20songhui18/ICCV2021=20=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E7=BB=93=E8=AE=BA=EF=BC=88C=2045/100=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 <noreply@anthropic.com> --- skills/gitlink-research-fair/REFERENCE.md | 28 +++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/skills/gitlink-research-fair/REFERENCE.md b/skills/gitlink-research-fair/REFERENCE.md index 92a1e8b..4660396 100644 --- a/skills/gitlink-research-fair/REFERENCE.md +++ b/skills/gitlink-research-fair/REFERENCE.md @@ -74,6 +74,30 @@ Rep1 环境锁（requirements 锁版本/Dockerfile/environment.yml）· Rep2 数 4. **禁止使用两条已证伪论点**：①"MSR 六分类法"、②"FAIR 分高→被引更多"因果。 5. 文献多跑在 GitHub；"在 GitLink 上复刻"是合理外推，须真机跑通闭环。 -## 九、实测结论（live probe，Task 6 回填） +## 九、实测结论（live probe，2026-07-01 于 songhui18/ICCV2021） -> 此节由 Task 6 在 `songhui18/ICCV2021论文复现` 真机验证后回填：license 状态、README/requirements/releases/commit SHA、各轴实测分、fork→PR 链路是否可用、OpenAlex 是否命中。 +**目标仓库**：`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 链路 / OpenAlex 命中情况：见 Task 7 回填。 -- 2.34.1 From 30f1d773b634ed0bf1f4474e1c8e6a4541b463be Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 15:15:17 +0800 Subject: [PATCH 07/11] =?UTF-8?q?docs(research-fair):=20REFERENCE=20=C2=A7?= =?UTF-8?q?=E4=B9=9D=20=E5=9B=9E=E5=A1=AB=20Task7=20fork=E2=86=92PR?= =?UTF-8?q?=E2=9C=85=20+=20OpenAlex=20503=E9=99=8D=E7=BA=A7=20+=20SWH?= =?UTF-8?q?=E4=B8=8D=E5=8F=AF=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- skills/gitlink-research-fair/REFERENCE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/gitlink-research-fair/REFERENCE.md b/skills/gitlink-research-fair/REFERENCE.md index 4660396..ebe76f0 100644 --- a/skills/gitlink-research-fair/REFERENCE.md +++ b/skills/gitlink-research-fair/REFERENCE.md @@ -100,4 +100,6 @@ Rep1 环境锁（requirements 锁版本/Dockerfile/environment.yml）· Rep2 数 **结论**：一个 19⭐ 的"论文复现"合集，FAIR/可复现维度仅得 C——无仓库级 license、无 release、无 CITATION、无数据集说明、依赖散落子目录。**正好印证可复现性危机**（2024 顶会仅 19.5% 提供官方代码）。处方空间大：补根级 LICENSE + CITATION.cff + 统一 requirements + 打 v1.0 release + README 复现章节。 -> fork→PR 链路 / OpenAlex 命中情况：见 Task 7 回填。 +> **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` 锚定（符合 §六降级）。 -- 2.34.1 From 05a0d507f2c7a6c847c109ea9736cdc3f15c8e58 Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 15:19:07 +0800 Subject: [PATCH 08/11] =?UTF-8?q?feat(research-fair):=20examples=20songhui?= =?UTF-8?q?18/ICCV2021=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 <noreply@anthropic.com> --- .../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 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 且只打分不修复。 -- 2.34.1 From d9e3f655d0b19bdfbf62942bf5b972f91e36677b Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 15:21:46 +0800 Subject: [PATCH 09/11] =?UTF-8?q?docs(research-fair):=20README=20=E7=99=BB?= =?UTF-8?q?=E8=AE=B0=20+=20workflow=20=E4=BA=A4=E5=8F=89=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- skills/README.md | 1 + skills/gitlink-workflow/SKILL.md | 1 + 2 files changed, 2 insertions(+) diff --git a/skills/README.md b/skills/README.md index a28cf20..b9a3595 100644 --- a/skills/README.md +++ b/skills/README.md @@ -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 可复现证书 | --- diff --git a/skills/gitlink-workflow/SKILL.md b/skills/gitlink-workflow/SKILL.md index 00a9dc8..c4f36d4 100644 --- a/skills/gitlink-workflow/SKILL.md +++ b/skills/gitlink-workflow/SKILL.md @@ -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 全流程 -- 2.34.1 From cd5f7990af1e1218fda91677ebaef96b43e6ab16 Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Wed, 1 Jul 2026 15:36:13 +0800 Subject: [PATCH 10/11] =?UTF-8?q?fix(research-fair):=20=E6=9C=80=E7=BB=88?= =?UTF-8?q?=E8=AF=84=E5=AE=A1=E4=BF=AE=E5=A4=8D=E2=80=94=E2=80=94=E6=8A=A5?= =?UTF-8?q?=E5=91=8A=E5=8D=A1tally=E8=87=AA=E6=B4=BD(=E2=9C=936=E2=9C=978?= =?UTF-8?q?=E2=9A=A04=E2=8A=A51)+R3=E2=8A=A5=E5=8F=AF=E8=BF=BD=E6=BA=AF+Op?= =?UTF-8?q?enAlex=20503?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit C1: 范围行从 spec 示例的 ✓7✗7⚠3⊥2 改为实测 ✓6✗8⚠4⊥1，并明示 ⊥=R3 委托 gitlink-license 未跑 M1: REFERENCE F1.2 兜底 ⊥→✗（无 release tag） M4: OpenAlex 降级条件 429→429/503（与实测 503 一致） Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- skills/gitlink-research-fair/REFERENCE.md | 4 ++-- .../gitlink-research-fair/examples/research-fair-workflow.md | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/skills/gitlink-research-fair/REFERENCE.md b/skills/gitlink-research-fair/REFERENCE.md index ebe76f0..11af407 100644 --- a/skills/gitlink-research-fair/REFERENCE.md +++ b/skills/gitlink-research-fair/REFERENCE.md @@ -7,7 +7,7 @@ | 原则 | 含义 | 本 Skill 检查项 | GitLink 证据 | 兜底（无字段时） | |------|------|----------------|--------------|------------------| | F1 | 全局唯一持久标识 | A4 持久标识 | repo identifier/URL + commit SHA | commit-SHA 锚定 | -| F1.2 | 版本级唯一标识 | A3 有版本发布 | `release +list` | ⊥（无 release 则 ✗） | +| 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 推断（标注） | @@ -43,7 +43,7 @@ Rep1 环境锁（requirements 锁版本/Dockerfile/environment.yml）· Rep2 数 - 端点：`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/无结果 → 报告卡溯源栏标"未找到关联论文" +- 降级：HTTP 429/503/无结果 → 报告卡溯源栏标"未找到关联论文" ## 六、SWH-ID 说明 diff --git a/skills/gitlink-research-fair/examples/research-fair-workflow.md b/skills/gitlink-research-fair/examples/research-fair-workflow.md index 829eef3..d506789 100644 --- a/skills/gitlink-research-fair/examples/research-fair-workflow.md +++ b/skills/gitlink-research-fair/examples/research-fair-workflow.md @@ -50,7 +50,7 @@ gitlink-cli commit +list --owner songhui18 --repo ICCV2021 --page 1 --format js 🏥 **gitlink-research-fair 科研软件体检报告** **总体**：C 🔴 45/100（F 67 · A 50 · I 17 · R 50 · Repro 40）｜版本锚定：commit `e14ac62`（无 release） -**范围**：检查 19 项（✓7 · ✗7 · ⚠3 · ⊥2） +**范围**：检查 19 项（✓6 · ✗8 · ⚠4 · ⊥1，⊥：R3 源码声明委托 gitlink-license 未在本轮跑） ### 逐项（节选） | 轴 | 项 | 状态 | 证据 | @@ -59,6 +59,7 @@ gitlink-cli commit +list --owner songhui18 --repo ICCV2021 --page 1 --format js | 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 顶会论文复现合集 | -- 2.34.1 From ea10cb007f2935407e2faf9c30a24678748e2e44 Mon Sep 17 00:00:00 2001 From: Martin <cwq985211@163.com> Date: Thu, 2 Jul 2026 15:09:12 +0800 Subject: [PATCH 11/11] =?UTF-8?q?fix(research-fair):=20=E6=8A=A5=E5=91=8A?= =?UTF-8?q?=E5=8D=A1=E5=BF=85=E9=A1=BB=E8=90=BD=E7=9B=98=E2=80=94=E2=80=94?= =?UTF-8?q?=E2=91=A5=E5=8A=A0=E5=AD=98=E6=9C=AC=E5=9C=B0md=E3=80=81?= =?UTF-8?q?=E2=91=A7=E5=8F=8C=E6=A8=A1=E5=BC=8F=E3=80=81=E9=94=99=E8=AF=AF?= =?UTF-8?q?=E8=A1=A8=E5=90=8C=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 修 skill 设计缺陷：原 ⑥渲染+⑧塞PR body，--no-fork 模式报告卡只在终端飘过不落地。 现在 ⑥ 始终存 report-cards/<owner>-<repo>-report-card.md，⑧ 区分 fork/no-fork 两种归宿。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- skills/gitlink-research-fair/SKILL.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/skills/gitlink-research-fair/SKILL.md b/skills/gitlink-research-fair/SKILL.md index 5a6f7e0..bdb1eed 100644 --- a/skills/gitlink-research-fair/SKILL.md +++ b/skills/gitlink-research-fair/SKILL.md @@ -49,14 +49,18 @@ metadata: ### ⑤ 溯源富集（M3） 从 README/CITATION 抽论文 → OpenAlex REST 反查作者/机构（best-effort） -### ⑥ 渲染报告卡（hero） -等级 + 雷达图 + 5 轴逐项表 + 处方摘要 + 证书栏 + KG 小图 + 溯源栏 +### ⑥ 渲染报告卡（hero）并落盘 +等级 + 雷达图 + 5 轴逐项表 + 处方摘要 + 证书栏 + KG 小图 + 溯源栏。 +**始终保存为本地文件** `report-cards/<owner>-<repo>-report-card.md`（cwd 下，含哨兵）——报告卡是可归档/复查的核心产物，**无论后续是否开 PR 都必须落盘，绝不只在终端输出**。 ### ⑦ 处方（M4） 对 `✗/⚠` 项生成 CITATION.cff/codemeta.json/LICENSE/复现章节 → 默认预览 ### ⑧ 发布 -确认后对 fork 开 PR（PR body 带报告卡摘要）+ 出 SWH/commit 证书；内嵌哨兵 +报告卡已在 ⑥ 落盘（`report-cards/<owner>-<repo>-report-card.md`）。 +- **fork 模式**：确认后对 fork 开 PR（PR body 带报告卡摘要）+ 出 SWH/commit 证书 +- **`--no-fork` 或 PR 失败**：报告卡已在本地，告知用户路径，可手动粘贴或提交 +- 哨兵内嵌于报告卡（及 PR body，若开） ## 5 轴评分 Rubric @@ -145,4 +149,4 @@ metadata: | fork 失败/无写权限 | 处方物料落本地（`--no-fork`） | | 二进制是 npm 旧版 | 强制 `./gitlink-cli` 或 `go build` 重建 | | 仓库私有/无权限 | 清晰错误，不发报告 | -| 报告/PR 发布失败 | 报告卡原文交用户手动粘贴 | +| 报告/PR 发布失败 | 报告卡已在 ⑥ 落盘，告知路径，用户可手动粘贴/提交 | -- 2.34.1