GitLinkZ

GitLinkZ 是一个面向 GitLink 科研类仓库的智能分析工具。它基于 gitlink-cli 采集真实仓库数据，生成科研项目洞察、复现性评估、开源合规检查和轻量知识图谱，服务于 GitLink / gitlink-cli 及 Skills 生态赛题。

当前推荐参赛路线：

子赛题一“增加和完善 GitLink-CLI 能力”：新增 gitlink-cli repo +tree Shortcut，用于仓库文件树采集。
子赛题二“编写和丰富 GitLink Skills”：交付 gitlink-research-assistant Skill。
子赛题三“构建端到端自动化工作流”：交付一键科研审计脚本。
子赛题四“应用 GitLink 辅助科研”：主线场景，生成科研洞察、复现性、合规和图谱报告。

四个子赛题的覆盖状态见四个子赛题覆盖状态。

功能

采集 GitLink 仓库、Issue、PR、Release、语言、贡献者和根目录文件信息；新版 gitlink-cli 优先使用 repo +tree，旧版自动回退 Raw API。
生成 research_report.md、reproducibility_report.md、compliance_report.md。
生成结构化知识图谱 graph.json 和可打开的 knowledge_graph.html。
提供 Agent Skill：skills/gitlink-research-assistant/SKILL.md。
默认只读运行，不会修改真实 GitLink 仓库。

环境要求

Python 3.10+
Node.js 14+
gitlink-cli

安装 gitlink-cli：

npm install -g @gitlink-ai/cli

认证方式任选其一：

gitlink-cli auth login

或在非交互环境中：

export GITLINK_TOKEN="<your-private-token>"

验证：

gitlink-cli user +me --format json

如果 npm 安装失败，可以按 gitlink-cli 安装说明使用官方源码构建方式：

git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
cd gitlink-cli
make install
npx skills add ./skills -y -g

安装

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

快速运行

scripts/run_research_audit.sh \
  --owner <owner> \
  --repo <repo> \
  --branch auto \
  --out outputs/<owner>_<repo>

也可以直接运行 Python CLI：

PYTHONPATH=src python -m gitlink_research_assistant.cli audit \
  --owner <owner> \
  --repo <repo> \
  --branch auto \
  --out outputs/<owner>_<repo>

--branch auto 会先读取 repo_info.default_branch，再采集根目录文件；如果目标仓库使用 main 而不是 master，不要强制传 master。

输出目录

outputs/<owner>_<repo>/
├── raw/              # gitlink-cli 原始 JSON 和命令文本输出
├── metrics/          # 归一化后的指标结果
├── reports/          # 三份 Markdown 报告
├── graph/            # 图谱 JSON 和 HTML
└── logs/             # 运行日志

测试

PYTHONPATH=src python -m unittest discover -s tests

离线端到端演示，不需要 gitlink-cli 或 Token：

mkdir -p outputs/demo_research-repo/raw
cp tests/fixtures/sample_raw/collection_manifest.json outputs/demo_research-repo/raw/collection_manifest.json
PYTHONPATH=src python -m gitlink_research_assistant.cli audit \
  --owner demo \
  --repo research-repo \
  --branch auto \
  --out outputs/demo_research-repo \
  --skip-collect

当前验证记录

gitlink-cli 已通过源码方式构建验证，当前环境可用版本为 gitlink-cli v0.1.18-22-ga46e06b。
官方 gitlink-cli 仓库的 18 个 Skills 已通过 npx skills add ./skills -y -g 安装。
GitLinkZ 自定义 gitlink-research-assistant Skill 已通过 npx skills add ./skills -y -g 安装。
单元测试已通过：PYTHONPATH=src python -m unittest discover -s tests -v。
离线 fixture 端到端报告生成已通过。
真实公开仓库 Gitconomy/Git4Research 已完成只读验证，默认分支为 main，可生成三份报告和知识图谱；样例输出已固化到 docs/validation/Gitconomy_Git4Research。
repo +tree 已在真实验证中作为根目录文件树数据源使用。

安全说明

默认只读，不发布评论、不关闭 Issue、不合并 PR。
日志会记录命令和耗时，但不会输出 Token。
outputs/ 默认不提交，避免把真实项目数据或日志误传。

许可证

本项目采用 MulanPSL-2.0 许可证，详见 LICENSE。

参赛交付建议

保留真实 GitLink 科研仓库的运行截图或录屏。
在 docs/application_report.md 中补充实际验证仓库、科研价值和落地效果。
若时间允许，将 skills/gitlink-research-assistant/ 或工作流示例提交给 gitlink-cli 官方仓库申请收录。