11 KiB

Raw Permalink Blame History

子赛题四 · 使用说明（热点分析 + 科研画像）

本文聚焦子赛题四两个核心功能：① 科研热点分析与知识图谱（对应 gitlink-research-graph，S2）、② 科研仓库画像（对应 gitlink-research-insight，S1）。两者均命令行独立运行，不依赖云端网页；内容与对应 SKILL.md 保持一致。

环境准备

cd gitlink-cli                          # 仓库根（含 scripts/research/）
gitlink-cli auth login                  # Token 7 天有效；平台数据采集需登录
pip install -r scripts/research/requirements.txt   # 热点图谱需 networkx；画像仅需标准库

算法层在 scripts/research/，Go 出数据（gitlink-cli + collect.py）+ Python 做算法，取数与计算分离、可离线单测。

一、热点分析 · 科研热点追踪与知识图谱

1.1 功能定位

给定一个研究方向（如「深度学习」「知识图谱」），回答：有哪些相关仓库？哪些主题是热点？哪些学者/团队活跃？ 并把「关键词 → 仓库 → 学者/主题」关系画成一张知识图谱，为开题、综述、找合作做态势感知。

对应 Skill：skills/gitlink-research-graph/SKILL.md（子赛题四·S2）。实现：scripts/research/graph_build.py（建图谱）+ scripts/research/hotspot.py（热度评分/飙升项目）。

1.2 数据与算法

① 取数 collect()（在线）：对每个关键词调 search +repos（按 repo_fullname 去重，取 top N），再对每个仓库取 repo +info / repo +contributors / repo +languages / repo +readme（前 4000 字符）。

② 建图 build_graph()（纯函数，不联网，networkx.MultiDiGraph）：

节点：repo:owner/name（含 language/stars/forks/desc）、scholar:login（来自 contributors，过滤 bot/i-robot）、topic:x（由 topics.py 词典在 description+readme 上抽取）。

边（5 类）：

边类型	含义	权重
`contributes_to`	scholar → repo	contribution_perc 解析为 0~1
`owns`	scholar → repo（author==contributor）	—
`covers_topic`	repo → topic	出现次数/max
`collaborates_with`	scholar ↔ scholar（共贡献同一仓库）	—
`related_to`	topic ↔ topic（同一仓库共现）	—

③ 热度评分（hotspot.py 补充）：综合热度分 stars + forks×2 + visits//10 + 近期更新加成（≤7天+30 / ≤30天+20 / ≤90天+10 / ≤180天+5），compute_velocity 识别短期飙升项目。

1.3 命令与参数

# A. 知识图谱（主）—— 默认输出 JSON 到 stdout
python scripts/research/graph_build.py --keywords "deep learning,nlp"
# 输出四件产物到目录
python scripts/research/graph_build.py --keywords "knowledge graph,gnn" --repos-limit 20 --out ./out

# B. 热度评分/飙升项目（补充）
python scripts/research/hotspot.py --category 深度学习 --limit 30 --out ./out     # GitLink 官方分类精选源（自带 visits）
python scripts/research/hotspot.py --keywords "deep learning,机器学习" --limit 12 --days 90 --out ./out  # 关键词源 + 近 90 天飙升

参数	说明
`--keywords`	逗号分隔的科研关键词（图谱/热度均支持）
`--category`	GitLink 官方分类名（仅 hotspot.py，自带 visits 热度字段）
`--repos-limit` / `--limit`	取多少个仓库
`--days`	近 N 天过滤（仅 hotspot.py，0=不过滤，用于找飙升）
`--out`	输出目录

1.4 输出产物

文件	内容
`graph.json`	结构化图谱：`nodes`(repo/scholar/topic) + `edges`(5 类) + `core_scholars` + `core_teams` + `topic_heat` + `meta`
`report.md`	中文趋势报告：主题热度榜 Top10 + 核心学者 + 核心团队
`graph.mmd`	Mermaid 图（按 repo/scholar/topic 三色 classDef，截断到 ≤40 节点防爆炸）
`graph.dot`	Graphviz DOT（`dot -Tsvg graph.dot -o graph.svg` 渲染）

graph.json 结构示例：

{
  "scenario": "S2_research_knowledge_graph",
  "nodes": [{"id":"repo:owner/name","type":"repo","props":{"language":"Python","stars":120}}],
  "edges": [{"source":"scholar:alice","target":"repo:owner/name","type":"contributes_to","weight":0.6}],
  "core_scholars": [{"login":"alice","repo_count":2}],
  "topic_heat": [{"topic":"deep_learning","count":2}]
}

1.5 真实验证

在真实科研仓库生态 mindspore-Ecosystem/mindspore 验证（关键词 mindspore）：图谱正确识别 deep_learning / scientific_computing / nlp / computer_vision 等主题；covers_topic 权重落在 (0,1]；contributes_to 正确解析 contribution_perc（"60%"→0.6）；bot 账号被过滤。单测 test_graph_build.py（17 用例，离线 mock）。

1.6 Agent 触发（Claude Code）

读 skills/gitlink-research-graph/SKILL.md，用关键词 deep learning,nlp 在 GitLink 构建科研知识图谱：调 graph_build.py --keywords "..." --out ./out，把 topic_heat（热点主题）和 core_scholars（核心学者）读回，用中文给我一份这个方向的热点态势小结。

1.7 渲染图谱

Mermaid 块可直接贴进支持 Mermaid 的 Markdown 查看器；DOT 用 dot -Tsvg graph.dot -o graph.svg 出矢量图。

二、科研画像 · 仓库级洞悉 + 四维评分

2.1 功能定位

面对一个陌生科研代码仓库，回答：它是怎么一步步长成现在这样的（谱系）？值得引用/复现到哪一步？ 从提交谱系、合并节奏、文档演进、实验组织、创新点五个角度做 lineage 分析，并给出四维科研评分（可复现性/活跃度/引用价值/协作健康）。

对应 Skill：skills/gitlink-research-insight/SKILL.md（子赛题四·S1）。实现：scripts/research/lineage.py（谱系算法）+ SKILL.md 四维评分体系。

2.2 数据与算法（lineage.py）

① 取数（collect.py 封装 gitlink-cli）：repo_info（默认分支）、commits(ref=默认分支)、prs(state=merged)、tree + tree(path='docs')、readme。

② 谱系算法（纯函数，已单测，不联网）：

函数	产出
`is_experiment_file`	识别 experiment/benchmark/eval*/tests?/data/ → 科研产物文件
`is_doc_file`	.md / docs/ → 文档
`build_branch_map`	分支列表（单分支简化：name/commits/last_active/is_default）
`pr_merge_patterns`	合并 PR 按时间升序（number/title/merged_time/changed_files）
`doc_evolution`	docs/*.md 的演进（file/last_date）
`innovation_points`	高影响合并（改文件多 / 合入默认分支 / 含里程碑关键词）→ 创新点（描述+证据+类别）

2.3 四维评分体系（回答「值不值得引用/复现」）

维度	满分	判定
🔁 可复现性（科研核心）	10	CI 配置(+2) / 依赖锁定 go.sum 等(+2) / 数据说明(+2) / 运行文档(+2) / 版本归档 release·tag(+2)；工程类仓库「数据项」算 N/A
📈 活跃度	10	近 3 月提交频率 + Issue/PR 活跃 + 贡献者趋势
📑 引用价值	10	LICENSE + 版本归档 + 文档完整 + 社区关注
🤝 协作健康	10	Issue 响应 + PR 合并率 + 巴士因子（核心贡献者占比，>50% 单点风险）

关键设计：

fork 检测（Step 0）：若是 fork，引用价值自动改评 upstream（避免「评了半天是别人的项目」）。
巴士因子：核心贡献者提交占比，越集中越危险。

2.4 命令与参数

# 默认输出 JSON 到 stdout
python scripts/research/lineage.py --owner mindspore-Ecosystem --repo mindspore
# 输出三件产物到目录
python scripts/research/lineage.py --owner <OWNER> --repo <REPO> --branches-limit 5 --out ./out
# 可复现脚本
bash skills/gitlink-research-insight/examples/research-insight-workflow.sh <OWNER> <REPO> [OUT_DIR]

参数	说明
`--owner` / `--repo`	目标仓库（必填）
`--branches-limit`	分支分析上限
`--out`	输出目录（不传则 JSON 到 stdout）

2.5 输出产物

文件	内容
`lineage.json`	commit_timeline / branch_map / pr_merge_patterns / doc_evolution / experiment_files / innovation_points / meta
`report.md`	中文洞悉报告（这个科研项目怎么长成、关键创新点）
`branch_graph.mmd`	Mermaid gitGraph 分支演进图

lineage.json 结构示例：

{
  "scenario": "S1_repository_research_insight",
  "repo": "owner/repo", "default_branch": "master",
  "commit_timeline": [{"date":"2024-05-01","count":12}],
  "innovation_points": [{"description":"...","evidence":"PR #2 ...","category":"大规模重构/新特性"}],
  "meta": {"commit_count":320,"merged_pr_count":9,"doc_count":5,"experiment_file_count":8}
}

2.6 真实验证

mindspore-Ecosystem/mindspore（default_branch=master；issue≈20346；PR=9；贡献者=6）：提交时间线、合并 PR 演进、docs 清单、benchmark/tests 实验文件均正确识别；高影响合并被标为「大规模重构/新特性」创新点。
whale_hihihi/gitlink-cli（四维评分端到端验证）：fork 检测识别为 Gitlink/gitlink-cli 的 fork → 引用价值改评 upstream；巴士因子 17%（低风险）；可复现性 8/10。报告原件 demo/research-insight-report-whale_gitlink-cli.md。

单测 test_lineage.py 全部离线通过（不联网、不调 gitlink-cli）。

2.7 Agent 触发（Claude Code）

读 skills/gitlink-research-insight/SKILL.md，评估 whale_hihihi/gitlink-cli 这个科研项目值不值得引用和复现：先做 fork 检测（若 fork 则引用价值改评 upstream）→ 调 lineage.py --owner whale_hihihi --repo gitlink-cli --out ./out 取谱系 → 按四维评分表（可复现性5项/活跃度/引用价值/协作健康+巴士因子）打分 → 给我一份科研画像报告。

三、两个功能的配合

热点分析（找方向）              科研画像（评估具体仓库）
关键词/分类 ──→ 热度榜 ──→ 选定高潜力仓库 ──→ lineage 谱系 + 四维评分
            ↓                                       ↓
      知识图谱（主题/学者）                    引用/复现建议

先用热点分析在一个研究方向里找飙升/高潜力仓库与活跃学者，再用科研画像对候选仓库逐一评估「值不值得引用、能不能复现」，形成「选题 → 评估」闭环。

四、故障排查

现象	解决
`401 / 请登录`	`gitlink-cli auth login`（Token 7 天有效）
`ModuleNotFoundError: networkx`	`pip install -r scripts/research/requirements.txt`（热点图谱必需）
大仓库采集慢/限流	减小 `--repos-limit` / `--limit`；hotspot.py 用 `--category` 精选源缩小范围
`repo +info` 取不到 default_branch	目标仓库可能为空或无默认分支，换一个有提交历史的仓库
Mermaid 节点太多	graph.mmd 已截断到 ≤40 节点；如需全量用 graph.dot + Graphviz 渲染

11 KiB Raw Permalink Blame History Unescape Escape