开源度量与分析

引言

度量开源项目的难点从来不是「算不出数字」，而是「算出的数字能不能支撑决策」。一个典型的失败场景是：团队花几个月搭了一套看板，上面有二十个指标，每个指标都有漂亮的折线图，但没人看——因为没人知道哪个数字该动、动了说明什么、动了该做什么。度量体系烂尾的原因，往往不是工具不好，而是从「采集」直接跳到了「展示」，跳过了中间的「定义」与「解读」。

工程上的难点有三层。第一层是指标定义的歧义：「贡献者数」是按提交去重、按人月去重、还是按首次贡献去重？口径不同，结论可能完全相反。第二层是数据的脏：同一个人有多个邮箱与账号，机器人账号混在贡献者里，force push 与 rebase 让提交历史失真，这些都必须在采集层处理干净。第三层是从数据到行动的链路：指标要能对应到「该做什么」，否则就是装饰。

还有一条根本约束：度量开源是有立场的。你用指标评估依赖、评估维护者、评估自己团队的参与度，三种立场的正确做法完全不同。用评估依赖的指标去考核维护者，会直接摧毁社区信任；用考核指标去评估依赖，会误杀成熟稳定的项目。度量体系设计的第一步，永远是先回答「这个数字给谁看、用来做什么决定」。

本文按「三层结构 → CHAOSS 指标模型 → 采集工具链 → 数据清洗 → 贡献者漏斗 → 留存分析 → 生态健康度 → 看板设计 → 指标误用」展开。需要划清一条边界：选型者视角的健康度评分卡（bus factor、TTFR、依赖分级、加权打分）见开源项目健康度度量 ，本文聚焦度量工程视角——指标体系怎么组织、数据管道怎么搭、留存与生态分析怎么做。读者对象是需要搭建或运营开源度量体系的数据工程师、社区经理与 OSPO 成员。

目录

1. 度量体系的三层结构
2. CHAOSS 指标模型与工作组
3. 数据采集工具链
4. 身份合并与数据清洗
5. 贡献者漏斗分析
6. 留存分析与队列分析
7. 生态健康度度量
8. 看板设计与指标落地
9. 指标误用与反模式

1. 度量体系的三层结构

度量体系的第一个设计决策是分层。不同层级的度量对象、指标、消费方完全不同，混在一起必然产生歧义。

三层结构：
  个体层 Individual   一个人的贡献与行为（评审、提交、响应、 mentoring）
  项目层 Project      一个仓库/社区的运行状态（漏斗、留存、积压、发布）
  生态层 Ecosystem    多个项目构成的技术生态（采用率、依赖关系、标准影响力）

每层的关键问题：
  个体层：这个人的贡献模式如何？是否在流失？是否该授予更多权限？
  项目层：这个社区在健康成长还是在萎缩？瓶颈在哪一环？
  生态层：这个技术方向在扩张还是收缩？谁是枢纽项目？谁在衰落？

个体层的度量最危险。任何用于评估个人的指标都会立刻被优化（Goodhart 定律），并且会扭曲行为——用 commit 数考核会激励拆提交，用响应时长考核会激励敷衍回复。个体层度量的正确用途是辅助判断（如「这个贡献者最近活跃度骤降，可能需要关注」），而不是评价绩效。

三层之间是聚合关系，但聚合要谨慎。把多个项目的「活跃度」平均成一个生态活跃度，会掩盖「少数项目极度活跃、多数项目停滞」的分布特征。生态层的指标应当看分布与枢纽，而不是简单平均。这一点与选型评分卡的差异在于：评分卡是对单个依赖的绝对判断，而生态分析关心的是项目之间的关系与整体结构。

2. CHAOSS 指标模型与工作组

CHAOSS（Community Health Analytics for Open Source Software）是 Linux 基金会下的度量标准项目，它的核心价值不是工具，而是一套被广泛接受的口径定义。照它的口径定义指标，你的数据才能与外部对比，也才能在换工具时保持连续。

CHAOSS 的指标组织方式：
  Working Group（工作组） 按关注领域划分
  Metric（指标）          一个可度量的概念，含定义与实现建议
  Metric Model（指标模型） 一组相关指标的集合，回答一个具体问题

主要工作组：
  Common Metrics        通用指标（贡献者、活跃度、社区）
  Diversity & Inclusion 多样性与包容性
  Evolution             项目演化与生命周期
  Risk                  风险（bus factor、许可证、供应链）
  Value                 开源对组织的价值
  OSPO                  开源办公室相关指标

指标模型比单个指标更有用。一个孤立的「新贡献者数」说明不了什么，但「新贡献者数 + 首次贡献后的留存率 + 首次响应时长」组成一个模型，就能回答「我们的 onboarding 是否有效」。CHAOSS 的指标模型正是围绕「回答一个具体问题」组织的，设计自己的度量体系时应当照这个思路：先有问题，再选指标。

CHAOSS 中常被引用的指标（按关注点）：
  贡献者    Contributors、New Contributors、Contributor Absence Factor（bus factor）
  活跃度    Code Changes、Issues、Reviews、Activity Dates and Times
  留存      Contributor Retention、Repeat Contributors
  时效      Time to First Response、Time to Close、Review Duration
  多样性    Contributor Diversity、Organizational Diversity、Elephant Factor
  风险      Bus Factor、Licensing、Dependency Depth
  价值      Project Velocity、Downstream Adoption

口径要写下来，而不是记在脑子里。每个指标都应当有一份简短的「定义卡」，写明：度量什么、公式、数据来源、排除规则（如排除机器人、排除 bot 提交）、时间窗口、已知局限。这份定义卡是度量体系最容易被省略、却最能防止「同一个指标两个人数出两个值」的东西。

「是否排除机器人」是最高频的口径分歧。dependabot、renovate、stale bot、CI 机器人都以账号形式存在，把它们计入贡献者会显著抬高指标。建议在采集层维护一份机器人名单（按账号后缀 [bot]、已知账号、以及「提交模式高度规律」的启发式识别），并在所有涉及人数的指标里统一排除，同时在定义卡里注明。

3. 数据采集工具链

采集层要解决「从哪拿数据、怎么拿、拿到哪存」。开源的社交编码平台（GitHub、GitLab）提供 API，但直接用 API 做长期度量会遇到限流、数据不全、历史回溯困难等问题，因此通常需要一个中间层。

采集层的三种方案：
  A. 直接调 API + 本地存储     轻量，适合少量仓库、少量指标
  B. 现成度量平台              GrimoireLab / Augur，功能全但需要维护基础设施
  C. 商业服务                  Bitergia、Sourcegraph 等，省运维但成本高

方案 A 适合几十个仓库的量级，用 gh api 或 GraphQL 拉取，落到本地 JSON/SQLite，再算指标。它的优点是透明可控，缺点是每个新指标都要写代码。方案 B 的 GrimoireLab 与 Augur 是 CHAOSS 生态的官方工具：GrimoireLab 提供完整的采集（数据源连接器）、清洗（身份合并）、存储（ElasticSearch/OpenSearch）、可视化（Kibana）链路；Augur 更偏数据科学，提供 API 与 Jupyter 集成。

# 方案 A：轻量采集，按仓库拉取并落库
gh api --paginate "repos/{owner}/{repo}/pulls?state=all&per_page=100" \
  --jq '.[] | {number, user: .user.login, created: .created_at, merged: .merged_at,
               additions, deletions, reviews: .review_comments}' \
  >> data/{owner}__{repo}__prs.jsonl

# 方案 B：GrimoireLab 的采集（简化示意）
grimoirelab-toolkit / perceval github org/repo --from-date 2024-01-01

采集要一次拉全量、之后增量。度量经常需要回溯历史（比如算「过去三年的留存曲线」），如果一开始只拉近期数据，后续补历史会非常痛苦（API 分页、限流、时间窗口）。正确做法是首次做一次全量抓取并落库，之后按日/周增量更新。

注意 API 配额与数据完整性。GitHub REST 匿名调用每小时 60 次，带 token 5000 次；GraphQL 按点数计费。做全量历史抓取前要估算配额（仓库数 × 分页数），并优先用 GraphQL 一次查询多个对象。另一个陷阱是数据变更：PR 的合并状态、标签、评论都会随时间变化，抓取时要记录「抓取时间戳」，否则无法区分「当时的状态」与「现在的状态」。

4. 身份合并与数据清洗

身份合并（identity merging）是度量质量的分水岭。同一个人在不同时间用不同邮箱提交、在不同平台用不同用户名、在 GitHub 上改了用户名——如果不合并，同一个人会被算成多个贡献者，bus factor 虚高、留存率虚低。

身份合并要处理的四类问题：
  1. 多邮箱同一人    git 提交里 alice@corp.com 与 alice@gmail.com 是同一人
  2. 平台账号映射    GitHub 账号与 git 提交邮箱的对应
  3. 改名与迁移      GitHub 用户名变更、账号迁移
  4. 机器人混淆     bot 账号与真人账号的区分

合并的三步：
  规范化 → 候选配对 → 人工确认（高风险配对）

import re, hashlib

def normalize_identity(name, email):
    """规范化：去空白、小写、剥离 + 别名后缀"""
    email = email.strip().lower()
    email = re.sub(r'\+.*@', '@', email)          # alice+work@x -> alice@x
    return {"name": name.strip(), "email": email}

def identity_key(name, email):
    """生成稳定的身份键，用于聚合"""
    n = normalize_identity(name, email)
    return hashlib.sha1(f"{n['name']}|{n['email']}".encode()).hexdigest()[:16]

BOT_PATTERNS = (r'\[bot\]$', r'^dependabot', r'^renovate', r'^stale', r'-ci$')
def is_bot(login):
    return any(re.search(p, login, re.I) for p in BOT_PATTERNS)

合并不能全自动。邮箱相同通常是同一人，但姓名相同（如 zhang wei）可能是不同人；邮箱不同可能是同一人（换了工作）。稳妥的做法是：邮箱完全相同的自动合并；姓名相同但邮箱不同的列为「候选」，人工确认后写入映射表。映射表要版本化保存，且一旦确认永久生效，避免每次采集重新猜。

身份合并的数据模型：
  identities      原始身份（name, email, source, first_seen）
  identity_map    身份 → 统一 person_id 的映射（人工确认）
  persons         合并后的人（含组织归属、是否机器人）

组织归属（affiliation）是另一个必须处理的维度。Elephant Factor、Organizational Diversity 这类指标依赖「贡献者属于哪个组织」，而邮箱域名只是弱信号（gmail.com 无法判断雇主）。做法有三：用邮箱域名匹配已知公司域名；用「提交时间与工作时间的相关性」启发式推断；或者干脆在社区里公开征集 affiliation 信息（CHAOSS 有相关的开放数据实践）。无论哪种，都要在定义卡里注明归属判定的置信度。

所有时间一律存 UTC，展示层再转时区。跨时区团队的「最后提交距今」「响应时长」如果不统一基准，会得出不一致的结论，而这类错误极难被发现。

5. 贡献者漏斗分析

漏斗分析回答「从接触到成为长期贡献者，每一级流失了多少」。它是项目层最有行动指引的度量——每一级的流失率都指向一个具体的改进方向。

贡献者漏斗（每一级算转化率）：
  L0 触达     访问仓库/文档/网站
  L1 首次接触 提交 issue、评论、提问
  L2 首次贡献 提交第一个 PR 或补丁
  L3 二次贡献 6 个月内再次贡献
  L4 持续贡献 12 个月内 >= 3 次且获得 triage 权限
  L5 维护者   获得合并权限、进入治理层

关键转化率：
  L1→L2 首PR转化率    衡量「上手门槛」
  L2→L3 二次留存率    衡量「首次体验质量」
  L3→L4 持续化率      衡量「价值认同」
  L4→L5 晋升率        衡量「治理通道是否通畅」

每一级流失都对应一个可操作的原因。L1→L2 转化低，说明上手门槛高（文档差、环境难搭、good first issue 无人维护）；L2→L3 转化低，说明首次体验差（PR 无人评审、被粗暴拒绝、反馈太慢）；L3→L4 转化低，说明贡献者没看到「留下来有什么意义」（缺乏认可、没有晋升通道）。把转化率与原因对应起来，漏斗就从「报表」变成了「诊断工具」。

# 计算 L2→L3 二次留存：首次 PR 后 6 个月内是否再次贡献
gh api --paginate "repos/{owner}/{repo}/pulls?state=all&per_page=100" \
  --jq '.[] | select(.user.type == "User") | "\(.user.login)\t\(.created_at)"' \
  | sort -k1,1 -k2,2 > prs_by_user.tsv

from datetime import datetime, timedelta
from collections import defaultdict

def retention_cohort(prs, window_days=180):
    """prs: [(login, created_at_iso)]，返回二次留存率"""
    by_user = defaultdict(list)
    for login, ts in prs:
        by_user[login].append(datetime.fromisoformat(ts.replace("Z", "+00:00")))
    first_timers, retained = 0, 0
    for login, times in by_user.items():
        times.sort()
        first, last = times[0], times[-1]
        # 首次贡献在窗口内且有后续贡献
        if last > first:
            first_timers += 1
            if last - first <= timedelta(days=window_days):
                retained += 1
    return retained / first_timers if first_timers else 0.0

漏斗要按人群细分。整体转化率会掩盖重要差异：来自某个渠道的新人可能转化率极高，另一批可能几乎全流失。建议按「来源渠道」「首次贡献类型（文档/代码/翻译）」「是否有导师」等维度切分，找出真正有效的路径。相关 onboarding 设计与新手议题维护见开源社区运营与贡献者漏斗 。

6. 留存分析与队列分析

留存分析比漏斗更细，它回答「不同时期加入的贡献者，各自的留存曲线是什么样的」。核心方法是队列分析（cohort analysis）：把贡献者按「首次贡献所在月份」分组，追踪每组在后续每个月的留存情况。

队列分析的表结构（行=加入月份，列=加入后第 N 个月）：
             M0    M1    M2    M3    M6    M12
  2026-01   100%  38%   25%   20%   14%   9%
  2026-02   100%  42%   30%   24%   --    --
  2026-03   100%  35%   22%   --    --    --
  2026-04   100%  45%   --    --    --    --

读法：
  纵向对比同一列 → 新队列的留存是否在改善（如 M1 从 38% 升到 45%）
  横向看单行     → 留存随时间衰减的形态（陡降说明首月体验差）

队列分析的价值在于区分「趋势」与「结构」。如果整体留存率下降，可能是「新加入的贡献者质量变差」（每个队列都更差），也可能是「最近加入了大量低留存的一次性贡献者」（新队列占比变大）——两者的处置完全不同。队列表能一眼区分这两种情况。

import pandas as pd

def cohort_table(events, freq="M"):
    """events: DataFrame[person_id, month] 每人每月是否有贡献"""
    g = events.groupby("person_id")["month"].min().rename("cohort")
    df = events.join(g, on="person_id")
    df["offset"] = (df["month"].dt.to_period(freq)
                    - df["cohort"].dt.to_period(freq)).apply(lambda x: x.n)
    tbl = df.groupby(["cohort", "offset"])["person_id"].nunique().unstack()
    return tbl.div(tbl[0], axis=0)   # 归一化为留存率

留存曲线的形态比单点数值更有信息量。健康的社区留存曲线通常是「陡降后趋稳」：首月流失快（一次性贡献者），但留下来的核心群体在后续月份保持稳定。如果曲线持续下滑不止，说明社区没有形成「归属感」，贡献者只是路过。

留存的对照分析要控制变量。直接比较「有导师的新人」与「无导师的新人」的留存，可能有选择偏差（更活跃的人本来就更可能被分配导师）。更稳妥的做法是看趋势：同一项目在不同时期、同类人群的留存变化，比跨人群的横向比较更可信。维护者侧的倦怠与流失分析见维护者倦怠与项目可持续性 。

7. 生态健康度度量

生态层关心的是「多个项目构成的技术生态整体是否健康」，它的问题与单项目不同：不是「这个项目活不活」，而是「这个生态在扩张还是收缩、谁是枢纽、谁在衰落」。

生态健康度的四个维度：
  规模      参与的项目数、贡献者数、下游采用数
  结构      依赖关系图：枢纽项目（被大量依赖）、桥接项目（连接两个子生态）
  活力      新增项目速率、项目毕业/归档速率、跨项目贡献者比例
  韧性      单一组织/单一项目的集中度、关键路径上的单点

核心方法：依赖关系图分析
  节点 = 项目/包，边 = 依赖关系
  枢纽度 = 被依赖数（高枢纽度 = 关键，也 = 爆炸半径大）
  中心性 = 在图中连接不同社群的能力

跨项目贡献者比例是生态活力的好指标：有多少人同时为多个项目做贡献。这个比例高，说明生态内部联系紧密、知识在流动；比例低，说明生态是「一堆孤岛」而非真正的共同体。计算方式是构建「贡献者-项目」二部图，统计度数大于 1 的贡献者占比。

# 用依赖数据构建生态图（示意：从 SBOM 或包元数据聚合）
# 输出 项目 -> 被依赖数，用于识别枢纽项目
python3 - <<'PY'
import json, collections
edges = []
for sbom in open("all_sboms.jsonl"):
    d = json.loads(sbom)
    for c in d.get("components", []):
        for dep in c.get("dependencies", []):
            edges.append((c["purl"], dep))
indeg = collections.Counter(b for _, b in edges)
for proj, n in indeg.most_common(20):
    print(f"{n:6d}  {proj}")
PY

枢纽项目要单独跟踪。一个被生态中 80% 项目依赖的库，其健康度直接决定整个生态的稳定性。生态层度量应当维护一份「枢纽项目清单」，对每个枢纽项目跟踪 bus factor、发布节奏、组织集中度——这实际上是开源项目健康度度量的单项目指标在生态层的加权应用。

生态度量的最大陷阱是「可比性」。不同生态的规模、语言、发展阶段差异巨大，横向比较绝对数值几乎没有意义。生态分析应当看结构与趋势（依赖图形态、枢纽集中度、跨项目流动的变化），而不是「A 生态比 B 生态活跃」这种排名。

8. 看板设计与指标落地

度量体系的最后一环是把指标送到需要它的人手里。看板设计的核心原则是**「每个指标都要能触发一个动作」**，否则就删掉。

看板的三条设计原则：
  1. 少而准    每个看板聚焦一个问题（如「onboarding 是否有效」），指标不超过 6 个
  2. 带阈值    每个指标标注健康区间，越线才需要关注
  3. 可下钻    从汇总数字能点到具体的人/PR/issue，便于排查

分层看板是常见的落地方式：给社区经理看的是「漏斗与留存」看板（关注 onboarding）；给维护者看的是「积压与响应时效」看板（关注日常运营）；给管理层看的是「生态与影响力」看板（关注战略）。不同角色看不同指标，避免所有人都被一堆无关数字淹没。

  # 看板配置的思路（以 Grafana/JSON 为例，示意结构）
dashboard: community-health
panels:
  - title: 新贡献者留存（M1）
    metric: retention_cohort_m1
    threshold: {good: ">= 0.25", warn: "0.10-0.25", bad: "< 0.10"}
  - title: 首次响应时长 P50
    metric: ttfr_p50_hours
    threshold: {good: "<= 24", warn: "24-72", bad: "> 72"}
  - title: 90 天老化 issue 占比
    metric: issue_aging_90d_ratio
    threshold: {good: "<= 0.30", warn: "0.30-0.50", bad: "> 0.50"}

告警要按趋势而非单点。单日的指标波动大多没有意义，值得告警的是「连续 N 个周期越线」或「斜率异常」。这与运维监控的思路一致——参考 DevOps 与可观测性 的告警设计经验：只看趋势与持续越线，避免噪声导致脱敏。

看板的最后一步是「定期解读」。数据不会自己变成结论，必须有一个人（通常是社区经理或数据负责人）每月看一遍，写下「这个月什么在变、为什么、下个月做什么」。这份解读记录本身就是度量体系运转的证据，也是防止「看板烂尾」的关键。

9. 指标误用与反模式

度量体系最大的风险不是技术，而是用错指标。以下六种误用最普遍，且几乎都源于「把代理指标当成了目标」。

用单一指标下结论。只看 star 数、只看提交数、只看贡献者数——任何单一指标都可以被操纵，也都会遗漏关键信息。修正：组合指标，跨「人、流程、生态」各取一个，且看趋势而非绝对值。

把度量用于考核。一旦某个指标与绩效挂钩，它立刻失去度量价值，同时扭曲行为。修正：度量只用于自省、选型与发现瓶颈，绝不用于考核个人或社区。

忽略项目生命周期阶段。用同一套阈值评价刚起步的实验项目与成熟的稳定项目，必然误判。修正：按阶段设定不同阈值，成熟项目的「低活跃」往往是优点。

把「无活动」等同于「无人维护」。归档仓库、只做安全维护的 LTS 分支、刻意保持稳定的完成态项目，都呈现低活动特征。修正：结合 EOL 政策与安全公告通道区分，参考项目自身的维护声明。

横向比较不可比的对象。不同规模、不同语言、不同生态的项目之间比绝对数值，得出的结论毫无意义。修正：只比较同一项目的纵向趋势，跨项目比较只看结构性指标（如分布形态）。

采集口径不一致导致数据不可比。同一个「贡献者数」在两个季度用了不同口径，趋势线就是假的。修正：把口径写成定义卡并版本化，口径变更时标注断点。

权衡取舍

核心取舍是度量成本与决策价值之间的平衡。每多一个指标、多一层采集、多一个看板，都增加维护成本；只有当指标能触发具体动作时，这个成本才值得。工程上的经验法则是：先定义要回答的问题，再选最少的指标去回答它，而不是「能采的都采，采完再看有什么用」。

常见坑清单

• 没有定义卡：同一个指标两个人数出两个值——为每个指标写口径、公式、排除规则与局限。
• 机器人混入贡献者：指标虚高，bus factor 失真——采集层统一过滤并按 [bot] 后缀维护名单。
• 身份未合并：同一个人被算成多人，留存率虚低——规范化 + 邮箱自动合并 + 姓名人工确认。
• 时区不统一：响应时长、最后提交时间对不上——一律存 UTC，展示层转换。
• 只拉近期数据：回溯历史时 API 分页与限流拖垮进度——首次全量、之后增量。
• 用 commit 数衡量贡献：激励拆提交与灌水——改用「被合并的、有实质影响的贡献」。
• 漏斗不分人群：整体转化率掩盖渠道差异——按来源、类型、是否有导师切分。
• 队列分析看单行：只看到一个队列的衰减——纵向比同列，识别趋势 vs 结构。
• 把度量用于考核：指标立刻被操纵——只用于自省、选型与发现瓶颈。
• 生态层横向比绝对值：不同生态不可比——只看依赖图结构与流动趋势。
• 告警按单点：噪声导致脱敏——按趋势与连续越线告警。
• 看板只看不解读：数据不会自己变成结论——每月写一次解读与下一步。

小结

开源度量与分析的本质是把「社区里发生了什么」变成「该做什么」的可信链路。它由四部分组成：定义（用 CHAOSS 口径写清指标，先有问题再选指标）、采集与清洗（拉全量、合并身份、过滤机器人、统一时区）、分析（漏斗定位流失点、队列区分趋势与结构、生态图看枢纽与流动）、落地（分层看板 + 阈值 + 定期解读）。任何一环缺失，度量都会退化成「没人看的报表」。

落地顺序建议从定义与采集开始：先明确要回答的两三个问题，照 CHAOSS 口径写出定义卡，再搭最小的采集与清洗链路，然后才做看板。跳过定义直接搭看板，通常以「二十个指标没人看」告终。

如果想继续深入，建议沿两条线读：一条是选型应用，从开源项目健康度度量看本文的指标如何落到加权评分卡上，用于依赖决策；另一条是社区行动，从开源社区运营与贡献者漏斗看漏斗与留存数据如何转化为具体的 onboarding 改进，把「度量」与「运营」两条链路接上。