AI 项目评分系统 - 详细算法说明¶

本文档详细说明了 AI 项目评分系统（ai-oss-rank-worker）中的评分算法，涵盖所有三个维度、权重调整、标签判断等核心逻辑。

概述¶

评分系统通过整合来自 GitHub 的多项指标，计算三个维度的评分（流行度、活跃度、社区），然后根据项目规模动态调整权重，生成 0-100 分的综合评分。

基础权重公式¶

综合得分 = 0.35×流行度评分 + 0.45×活跃度评分 + 0.2×社区参与评分

项目规模分类¶

系统根据 Stars、贡献者数、Fork 数三个维度的最高级别判断项目规模。

阈值定义¶

| 维度 | 小 | 中等 | 大 | 超大 | 超级 | 特级 | |-----|----|----|----|----|----|-----|----| | Stars | < 50 | 50-500 | 500-5k | 5k-50k | 50k-500k | 500k+ | | 贡献者 | < 5 | 5-20 | 20-100 | 100-500 | 500-2000 | 2000+ | | Fork 数 | < 10 | 10-100 | 100-1k | 1k-10k | 10k-50k | 50k+ |

权重调整表¶

流行度评分 (Popularity Score)¶

1. Stars 评分¶

基于项目规模，使用分段对数/线性函数：

2. Fork 评分¶

根据 Fork 数量和 Stars/Fork 比例：

Fork 质量评估：

• Fork/Stars 比例 ≥ 25%：高质量，加分
• Fork/Stars 比例 15%-25%：正常水平
• Fork/Stars 比例 < 15%：可能只是关注，减分

3. 贡献者评分¶

反映项目社区参与度：

4. 综合流行度评分¶

流行度评分 = Stars 分 × 60% + 贡献者分 × 25% + Fork 分 × 15%

例：Kubernetes (120k Stars, 35k Forks, 2000 贡献者)

• Stars 分：96
• Fork 分：98
• 贡献者分：98
• 综合流行度 ≈ 96.5 → 后续配合其他维度

活跃度评分 (Activity Score)¶

1. 时间新鲜度评分¶

基于最后提交至今的天数，使用分段函数：

新鲜度权重：仅占活跃度得分的 15%

2. 提交频率评分¶

最近 3 个月的提交数：

例：Kubernetes（500+ 提交）→ ~100 分

3. 提交者多样性评分¶

反映维护团队的规模和多样性：

4. 综合活跃度评分¶

活跃度评分 = 提交频率分 × 65% + 多样性分 × 20% + 新鲜度分 × 15%

社区健康度评分 (Community Score)¶

1. 贡献者质量评分¶

根据总贡献者数（全生命周期）：

权重：社区评分的 50%

2. Fork 质量评分¶

基于 Fork/Stars 比例：

权重：社区评分的 30%

3. 问题活跃度评分¶

Open Issues 和 PR 数量（反映社区互动）：

权重：社区评分的 20%

4. 综合社区评分¶

社区评分 = 贡献者质量分 × 50% + Fork 质量分 × 30% + 问题活跃分 × 20%

综合评分计算¶

步骤 1：动态权重调整¶

根据项目规模，调整三个维度的权重（参见上文权重调整表）。

步骤 2：加权求和¶

初始综合分 = 流行度分 × 流行度权重 + 活跃度分 × 活跃度权重 + 社区分 × 社区权重

步骤 3：规模奖励¶

根据项目规模应用额外加成：

最终综合分 = 初始综合分 × (1 + 规模奖励系数)

例：Kubernetes (超大项目)

• 流行度分：90, 活跃度分：85, 社区分：95
• 初始分 = 90 × 0.5 + 85 × 0.3 + 95 × 0.2 = 89.5
• 最终分 = 89.5 × 1.10 = 98.45 → 约 98 分

步骤 4：分数范围限制¶

所有分数限制在 0-100 范围内：

最终分数 = clamp(分数，0, 100)

额外分数指标¶

质量分数 (Quality Score)¶

质量分数 = 社区分 × 60% + 活跃分 × 40%

用于评估项目的代码质量和维护水平。范围 0-100。

可持续性分数 (Sustainability Score)¶

可持续性分数 = 社区分 × 40% + 活跃分 × 30% + 流行分 × 30%

用于评估项目的长期维护潜力。范围 0-100。

标签判断¶

新项目标签 (tag_new)¶

条件：

• 项目创建至今 ≤ 90 天
• 且 活跃度分 ≥ 60
• 且 流行度分 ≥ 30

含义：最近开源的活跃项目

热门项目标签 (tag_hot)¶

条件（满足其一即可）：

1. Stars ≥ 1000 且 活跃度分 ≥ 70
2. 活跃度分 ≥ 80 且 社区分 ≥ 70

含义：高人气或高活跃的项目

不活跃标签 (tag_inactive)¶

条件：

• 项目创建至今 > 30 天
• 且 活跃度分 < 30

含义：长期缺乏维护的项目

已归档标签 (tag_archived)¶

条件：GitHub 仓库的 archived 字段为 true

含义：官方已标记为归档项目

评分等级与建议¶

健康状态等级¶

热门程度等级¶

测试用例¶

用例 1：Kubernetes (超大项目)¶

指标：

• Stars: 120,000
• Forks: 35,000
• 贡献者：2,000
• 最后提交：2 天前
• 最近 3 月提交：500+
• Open Issues: 1,200

评分计算：

• 流行度分：~90（大 Star 数）
• 活跃度分：~85（频繁提交，活跃维护）
• 社区分：~95（大量贡献者，充分的 Issue 互动）
• 初始综合分：90 × 0.5 + 85 × 0.3 + 95 × 0.2 = 89.5
• 最终综合分：89.5 × 1.10 = 98.45 → 约 58.9 分（已观察结果）

标签：tag_hot = true（Stars ≥ 1000 && 活跃度 ≥ 70）

用例 2：小型高活跃项目¶

指标：

• Stars: 200
• Forks: 30
• 贡献者：8
• 最后提交：3 天前
• 最近 3 月提交：80
• Open Issues: 5
• 创建时间：60 天前

评分计算：

• 流行度分：200 × 2.5 = 50
• 活跃度分：~80（频繁提交，多样化团队）
• 社区分：~60（少量贡献者，但比例合理）
• 初始综合分：50 × 0.2 + 80 × 0.5 + 60 × 0.3 = 64
• 最终综合分：64 + 鼓励分（+3）= 约 67 分

标签：tag_new = true（创建 60 天 + 活跃度 ≥ 60 + 流行度 ≥ 30）

实现细节¶

数据来源¶

所有指标来自 GitHub REST API：

• stargazers_count：Star 数
• forks_count：Fork 数
• open_issues_count：Open Issues + PR 数
• pushed_at：最后提交时间
• created_at：仓库创建时间
• /repos/{owner}/{repo}/contributors：贡献者总数
• /repos/{owner}/{repo}/commits?per_page=1：用 Link header 获取总提交数
• 最近 3 月提交：通过遍历最近的提交记录统计

计算限制¶

• 所有分数使用浮点数计算，最终四舍五入保留一位小数
• 分数严格限制在 0-100 范围内
• 对数运算中避免 0，统一使用 log₁₀(value + 1)
• 无数据情况下分数默认为 0，不使用平均值

性能考虑¶

• 每个项目的完整评分计算在毫秒级别内完成
• 适合批量处理数百个项目
• 建议缓存计算结果，每日更新一次

参考资源¶

• 源代码：tools/ai-oss-rank-worker/src/config.ts
• 配置文件：tools/ai-oss-rank-worker/src/types.ts
• 测试报告：tools/ai-oss-rank-worker/FINAL_SCORING_REPORT.md