From b69023a405d8cd0fe9c451b95be47ab81f5cd288 Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 1 Jul 2026 14:35:43 +0800 Subject: [PATCH] =?UTF-8?q?feat(research-fair):=20SKILL.md=20=E5=AE=8C?= =?UTF-8?q?=E6=95=B4=E5=AE=9E=E7=8E=B0=EF=BC=88frontmatter+=E7=AE=A1?= =?UTF-8?q?=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 --- 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 （） +**范围**：检查 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` 不匹配 → 提示"报告已过期，建议重评"。 + +## 处方（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 发布失败 | 报告卡原文交用户手动粘贴 |