OpenRank 算法改进项目

这是一个基于 open-digger 和 openrank-neo4j-gds 项目的 OpenRank 算法实现，用于开发者贡献度量和开源社区分析。

项目架构

本项目采用模块化架构设计，主要包括以下几个核心部分：

1. 算法核心 (src/src/algorithm/)：实现了 OpenRank 算法的核心逻辑，包括图构建、迭代计算和结果生成
2. 数据层 (src/src/data/)：提供数据加载和管理功能，支持模拟数据和真实数据
3. 配置系统 (src/src/config/)：管理算法参数和环境配置
4. API 接口 (src/src/api/)：提供统一的访问接口和查询功能
5. 工具函数 (src/src/utils/)：通用工具和辅助函数

安装

# 克隆项目
git clone <repository-url>
cd openrank

# 安装依赖
npm install

# 构建项目
npm run build

快速开始

基础使用

import { OpenRank } from './src';

// 创建 OpenRank 实例
const openrank = new OpenRank('./data');

// 运行 OpenRank 计算
const startDate = new Date('2024-01-01');
const endDate = new Date('2024-12-31');
const results = await openrank.calculate(startDate, endDate);

// 获取 Top 10 仓库 OpenRank
const topRepos = await openrank.getRepoOpenrank({
  startYear: 2024,
  startMonth: 1,
  endYear: 2024,
  endMonth: 12,
  limit: 10,
  order: 'DESC'
});

console.log('Top 10 仓库:', topRepos);

高级查询

import { MetricsCalculator, MockDataSource } from './src';

const dataSource = new MockDataSource('./data');
const calculator = new MetricsCalculator(dataSource);

// 获取分布统计
const distribution = await calculator.getOpenrankDistribution({
  startYear: 2024,
  startMonth: 1,
  endYear: 2024,
  endMonth: 12,
});

// 比较不同时期
const comparison = await calculator.compareOpenrank(
  { startYear: 2024, startMonth: 1, endYear: 2024, endMonth: 6 },
  { startYear: 2024, startMonth: 7, endYear: 2024, endMonth: 12 },
  'repo'
);

配置

配置文件

在 config/openrank.yml 中配置算法参数：

global:
  developerRetentionFactor: 0.5      # 开发者继承比例
  repositoryRetentionFactor: 0.3     # 仓库继承比例
  attenuationFactor: 0.85            # OpenRank 衰减系数
  tolerance: 0.01                    # 收敛容差
  maxIterations: 100                 # 最大迭代次数

activityWeights:
  issueComment: 0.5252               # Issue 评论权重
  openIssue: 2.2235                  # 创建 Issue 权重
  openPull: 4.0679                   # 创建 PR 权重
  reviewComment: 0.7427              # 代码评审权重
  mergedPull: 2.0339                 # 合入 PR 权重

projectActivityWeights:
  # 活动类型权重（项目级 OpenRank 用）
  open: 2.0
  comment: 0.5
  review: 1.0
  close: 0.3
  commit: 1.5

  # 反刷与密度抑制（推荐开启）：
  antiGaming:
    enabled: true
    commentTransform: sqrt           # 对高频评论做亚线性变换，降低刷量影响
    commitTransform: sqrt
    linearThresholds:                # 前 N 条线性累加，超过部分按变换（sqrt/log）
      comment: 3
      reviewComment: 3
      commit: 1
    perItemCap:                      # 每个 Issue/PR 的单项计数上限，防极端
      comment: 50
      reviewComment: 40
      commit: 20

环境变量

# 设置全局收敛容差
export OPENRANK_GLOBAL_TOLERANCE=0.01

# 设置最大迭代次数
export OPENRANK_GLOBAL_MAX_ITERATIONS=100

算法原理

全域 OpenRank

全域 OpenRank 基于全局协作网络计算，考虑以下因素：

1. 网络构建：以开发者和仓库为节点，活动关系为边
2. 权重计算：使用活动度指标作为边权重
3. 历史继承：节点部分继承上个月的 OpenRank 值
4. 迭代收敛：使用改进的 PageRank 算法计算

项目级 OpenRank

项目级 OpenRank 在项目内部计算，包含更多节点类型：

1. 节点类型：开发者、仓库、Issue、Pull Request
2. 复杂网络：多种关系类型和权重配置
3. 精细参数：不同节点类型的不同继承因子

运行示例

# 运行基础示例
npm run dev

# 运行测试
npm test

# 检查代码质量
npm run lint

A/B 评估：仓库事件影响

为评估是否引入仓库层事件（Star/Fork/Release 等）对项目级 OpenRank 的影响，本项目提供了 A/B 对比脚本：

• 脚本：scripts/ab_evaluate_repo_events.ts
• 运行方式：npm run ab:repo-events
• 环境变量（可选）：
  • GITHUB_TOKEN：GitHub 访问令牌，避免触发未认证的频率限制
  • OR_AB_OWNER/OR_AB_REPO：目标仓库，默认 FISCO-BCOS/FISCO-BCOS

项目结构

openrank/
├── doc/                # 项目文档和规格说明书
├── front/              # 前端子系统
├── model/              # 设计模型和图表
├── src/                # 源代码目录
│   ├── config/         # 配置文件
│   ├── data/           # 数据存储
│   ├── scripts/        # 辅助脚本
│   ├── src/            # 核心源代码
│   ├── test/           # 测试文件
│   └── test_data/      # 测试数据
└── 文献/               # 参考论文和资料

开发指南

添加新的数据源

1. 实现 DataSource 接口
2. 在 src/src/data/ 目录下创建新的数据源类
3. 更新导出文件

自定义算法参数

1. 修改 config/openrank.yml 配置文件
2. 或使用环境变量覆盖特定参数
3. 或在代码中动态设置配置

测试

# 运行单元测试
npm test

# 运行覆盖率测试
npm run test:coverage

# 运行集成测试
npm run test:integration