feat(research-fair): SKILL.md 完整实现（frontmatter+管道+5轴rubric+报告卡+处方+证书+KG+降级）

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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 发布失败 | 报告卡原文交用户手动粘贴 |