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 <repository-url>
+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) - 项目发起方