From ff0e88ba39395688b1bf55c6bbd95fa7cb76ecb6 Mon Sep 17 00:00:00 2001 From: chenxiaofu <839989072@qq.com> Date: Wed, 12 Nov 2025 16:50:07 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E4=BA=86README.md=E6=96=87?= =?UTF-8?q?=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 252 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 251 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f6b6fb..1b19deb 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,252 @@ -# openrank +# OpenRank 复现项目 + +这是一个基于 open-digger 和 openrank-neo4j-gds 项目的 OpenRank 算法复现实现，用于开发者贡献度量和开源社区分析。 + +## 项目概述 + +OpenRank 是由 X-lab 开发的开源项目价值评估算法，基于 PageRank 改进而来，专门用于评估开源生态中开发者和项目的贡献价值。本项目提供了一个完整的 OpenRank 算法复现实现，旨在为开源社区分析、贡献者评估和项目健康度监测提供强大工具。 + +## 特性 + +- ✅ **完整的 OpenRank 算法实现**：基于原始论文和开源代码的忠实复现 +- ✅ **支持多种计算模式**：全域 OpenRank 和项目级 OpenRank +- ✅ **灵活的数据源接口**：支持桩函数模拟和真实数据源 +- ✅ **丰富的指标计算**：仓库、用户、社区等多维度分析 +- ✅ **高性能图计算**：优化的图数据结构和迭代算法 +- ✅ **完善的配置系统**：支持参数调优和环境适配 +- ✅ **TypeScript 支持**：完整的类型定义和代码提示 + +## 项目架构 + +本项目采用模块化架构设计，主要包括以下几个核心部分： + +1. **算法核心** (`src/src/algorithm/`)：实现了 OpenRank 算法的核心逻辑，包括图构建、迭代计算和结果生成 +2. **数据层** (`src/src/data/`)：提供数据加载和管理功能，支持模拟数据和真实数据 +3. **配置系统** (`src/src/config/`)：管理算法参数和环境配置 +4. **API 接口** (`src/src/api/`)：提供统一的访问接口和查询功能 +5. **工具函数** (`src/src/utils/`)：通用工具和辅助函数 + +## 安装 + +```bash +# 克隆项目 +git clone +cd openrank + +# 安装依赖 +npm install + +# 构建项目 +npm run build +``` + +## 快速开始 + +### 基础使用 + +```typescript +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); +``` + +### 高级查询 + +```typescript +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` 中配置算法参数： + +```yaml +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 +``` + +### 环境变量 + +```bash +# 设置全局收敛容差 +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. **精细参数**：不同节点类型的不同继承因子 + +## 运行示例 + +```bash +# 运行基础示例 +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. 或在代码中动态设置配置 + +## 测试 + +```bash +# 运行单元测试 +npm test + +# 运行覆盖率测试 +npm run test:coverage + +# 运行集成测试 +npm run test:integration +``` + +## 贡献 + +欢迎提交 Issue 和 Pull Request！ + +1. Fork 本仓库 +2. 创建特性分支 (`git checkout -b feature/amazing-feature`) +3. 提交更改 (`git commit -m 'Add some amazing feature'`) +4. 推送到分支 (`git push origin feature/amazing-feature`) +5. 开启 Pull Request + + +## 参考资料 + +- [open-digger](https://github.com/X-lab2017/open-digger) - 原始项目和数据平台 +- [openrank-neo4j-gds](https://github.com/X-lab2017/openrank-neo4j-gds) - Neo4j 插件实现 +- [OpenRank 算法论文](https://blog.frankzhao.cn/openrank_in_project/) - 算法设计思路 +- [X-lab 开放实验室](https://x-lab.info) - 项目发起方 -- 2.34.1