GitLinkZ

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

当前推荐参赛路线：

• 子赛题一“增加和完善 GitLink-CLI 能力”：repo +tree 已合并到官方 gitlink-cli，并完成多条 CLI Shortcut 增强 PR。
• 子赛题二“编写和丰富 GitLink Skills”：交付 gitlink-research-assistant Skill，并提交 7 个科研 Skills 套件官方 PR。
• 子赛题三“构建端到端自动化工作流”：交付一键科研审计脚本。
• 子赛题四“应用 GitLink 辅助科研”：主线场景，生成科研洞察、复现性、合规和图谱报告。

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

评审快速入口

内容	路径
当前成果总览	docs/current_progress.md
初赛项目书 PDF	docs/GitLinkZ初赛项目书.pdf
初赛项目书 LaTeX	docs/GitLinkZ初赛项目书.tex
提交材料浏览页	docs/submission_index.html
提交材料 Markdown 索引	docs/submission_index.md
赛事交付核对表	docs/competition_delivery_checklist.md
四个子赛题覆盖状态	docs/four_subtasks_status.md
科研场景应用报告	docs/application_report.md
子赛题二 Skills 演示视频	docs/videos/subtask2-skills-demo.mp4
子赛题三工作流演示视频	docs/videos/subtask3-workflow-demo.mp4
子赛题四科研应用演示视频	docs/videos/subtask4-research-demo.mp4
演示视频清单与校验值	docs/videos/README.md
子赛题三视频演示流程	docs/video_demo_subtask3.md
子赛题四视频演示流程	docs/video_demo_subtask4.md
指标定义与局限性	docs/metrics_and_limitations.md
Agent 对话记录	docs/agent_conversation.md
gitlink-cli 外部贡献归档	artifacts/gitlink-cli/README.md
gitlink-cli 官方 PR 记录	docs/subtask1_gitlink_cli_pr.md
科研 Skills 官方 PR 记录	docs/subtask2_research_skills_pr.md
Skill 入口	skills/gitlink-research-assistant/SKILL.md
端到端工作流脚本	scripts/run_research_audit.sh
Gitconomy/Git4Research 验证	docs/validation/Gitconomy_Git4Research/validation_summary.md
songhui18/ICCV2021 验证	docs/validation/songhui18_ICCV2021/validation_summary.md

功能

• 采集 GitLink 仓库、Issue、PR、Release、语言、贡献者和根目录文件信息；新版 gitlink-cli 优先使用 repo +tree，旧版自动回退 Raw API。
• 对 Issue、PR、Release、贡献者和 Commit 完整翻页，按稳定 ID/SHA 去重，并记录每个数据源的完整性。
• 有边界地递归仓库文件树并读取审计所需的小型文本文件；疑似敏感路径绝不读取内容。
• 生成 research_report.md、reproducibility_report.md、compliance_report.md。
• 生成结构化知识图谱 graph.json 和可打开的 knowledge_graph.html。
• 生成赛题三端到端工作流证据链：run_manifest.json、workflow_trace.md、evidence_index.md。
• 生成单仓库 HTML 总览页 index.html、整改方案草案、Issue 草案和 README 补充建议。
• 支持多仓库批量审计，输出对比报告、评分表和批量总览页。
• 支持通过 config/scoring_rules.yaml 调整复现性和合规评分权重。
• 支持通过 templates/*.j2 定制三份 Markdown 报告格式；没有 Jinja2 时自动回退到内置渲染。
• 提供 Agent Skill：skills/gitlink-research-assistant/SKILL.md。
• 默认只读运行，不会修改真实 GitLink 仓库。

环境要求

• Python 3.10+（命令默认使用 python3，可通过 PYTHON=/path/to/python3 覆盖）
• Node.js 14+
• gitlink-cli 0.1.18+

安装 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 python3 -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。

采集边界可显式调整：

scripts/run_research_audit.sh \
  --owner <owner> --repo <repo> \
  --page-size 50 --max-pages 100 \
  --tree-max-depth 3 --tree-max-files 1000 \
  --content-max-files 30 --content-max-bytes 128000

每个数据源使用以下状态之一：

状态	含义
complete	已完成预期分页或边界内扫描
partial	已取得部分数据，但遇到错误、重复页或配置边界
failed	未取得可用数据
unsupported	当前 fixture 或 CLI 不提供该数据源

报告中的 unknown 表示证据不足，不能解释为 0、缺失项或“无风险”。原始请求、采集时间、CLI 版本、默认分支、commit ref、页数、服务端总量和错误记录保存在 raw/collection_manifest.json 与 metrics/metrics.json。

可选配置：

scripts/run_research_audit.sh \
  --owner <owner> \
  --repo <repo> \
  --scoring-rules config/scoring_rules.yaml \
  --templates-dir templates

评分规则会写入 metrics/metrics.json，便于答辩时解释每个分值来源。

输出目录

outputs/<owner>_<repo>/
├── raw/              # gitlink-cli 原始 JSON 和命令文本输出
├── metrics/          # 归一化后的指标结果
├── reports/          # 三份 Markdown 报告
├── graph/            # 图谱 JSON 和 HTML
├── logs/             # 运行日志
├── index.html        # 单仓库工作流总览
├── run_manifest.json # 工作流运行清单
├── workflow_trace.md # 命令执行轨迹
└── evidence_index.md # 证据索引

多仓库批量工作流

cat > /tmp/gitlinkz-repos.txt <<'EOF'
songhui18/ICCV2021
Gitconomy/Git4Research
EOF

scripts/run_batch_research_audit.sh /tmp/gitlinkz-repos.txt outputs/batch --branch auto --timeout 120

批量输出：

outputs/batch/
├── comparison_report.md
├── research_scoreboard.csv
├── index.html
├── songhui18_ICCV2021/
└── Gitconomy_Git4Research/

配置和模板

• config/scoring_rules.yaml：复现性和合规检查的分值配置。
• templates/research_report.md.j2：科研项目洞察报告模板。
• templates/reproducibility_report.md.j2：复现性评估报告模板。
• templates/compliance_report.md.j2：开源合规检查报告模板。

如果通过 --scoring-rules 指定了不存在的文件，程序会直接报错；默认配置文件缺失时会使用内置评分规则。

测试

PYTHONPATH=src python3 -m unittest discover -s tests

构建初赛项目书

项目书使用 LaTeX 编写，通过 Tectonic 生成 PDF：

scripts/build_competition_report.sh

未将 Tectonic 安装到 PATH 时可显式指定：

TECTONIC=/path/to/tectonic scripts/build_competition_report.sh

输出为可检索的矢量版 docs/GitLinkZ初赛项目书.pdf。LaTeX 源码、PDF、三个实际演示视频、 视频流程和真实验证结果均收录在提交索引中。

离线端到端演示，不需要 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
scripts/run_research_audit.sh \
  --owner demo \
  --repo research-repo \
  --branch auto \
  --out outputs/demo_research-repo \
  --skip-collect

当前验证记录

• gitlink-cli 已通过源码方式构建验证，当前环境可用版本为 gitlink-cli v0.1.18-22-ga46e06b。
• 子赛题一官方 PR #143 repo +tree 已合并；后续 CLI Shortcut 增强 PR #314-#324 已提交并等待 Review。
• 子赛题二官方 PR #328 已提交，包含 7 个只读科研 Skills，当前状态为 open 且 mergeable: true。
• 官方 gitlink-cli 仓库的 18 个 Skills 已通过 npx skills add ./skills -y -g 安装。
• GitLinkZ 自定义 gitlink-research-assistant Skill 已通过 npx skills add ./skills -y -g 安装。
• 单元测试已通过：PYTHONPATH=src python3 -m unittest discover -s tests -v（30 项）。
• 离线 fixture 端到端报告生成已通过。
• 真实公开仓库 Gitconomy/Git4Research 已完成只读验证，默认分支为 main，可生成三份报告和知识图谱；样例输出已固化到 docs/validation/Gitconomy_Git4Research。
• 真实论文复现仓库 songhui18/ICCV2021 已完成只读验证，包含 Issue、PR、Fork、Watcher 和贡献者数据；增强样例输出已固化到 docs/validation/songhui18_ICCV2021。
• repo +tree 已在真实验证中作为根目录文件树数据源使用。
• 子赛题二、三、四的三个实际演示视频已提交，文件信息与 SHA-256 见 视频清单。

安全说明

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

许可证

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

参赛交付建议

• 提交平台填写视频材料时使用 三个仓库内视频，无需依赖外部网盘。
• GitLinkZ 收口提交 64547b9 已推送；提交前确认平台 PR 状态与 docs/current_progress.md 一致。
• PR #328 已更新至提交 4cd7a89，继续跟进官方 Review。
• 录制 Agent 读取 Skill、执行只读采集并生成报告的演示过程。