软件遗产标识符 SWHID：构建通用开源代码档案的内在指纹与持久化生态

文章背景与核心概要

开源代码作为现代数字社会的基石，长期面临着代码仓库失效、平台关闭导致链接 404 以及依赖版本难以永久追溯等持久化痛点。由法国国家信息与自动化研究所 (Inria) 主导的 Software Heritage 项目通过去重的 Merkle DAG 结构，构建了囊括全球数百亿源文件的通用代码档案馆，并推出了基于内容内在哈希的国际标准 SWHID (SoftWare Hash IDentifier) 。本文深入探讨了开源元数据平台 ecosyste.ms 与 Software Heritage 的深度整合实践，作者开发了包括 swh-git、多语言 SWHID 生成库及 WebAssembly 客户端在内的完整开源工具链，将人类可读的软件包标识符与防篡改的内在代码指纹连接起来。这一生态不仅系统性量化评估并补充了核心开源软件的归档覆盖率，还为科研软件追踪与软件物料清单 (SBOM) 的长期可重现性奠定了坚实的基础设施。

内容概要

Summary

本文探讨了如何将全球开源代码归档库 Software Heritage (SWH) 与软件哈希标识符 SoftWare Hash IDentifiers (SWHIDs) 深度整合到 ecosyste.ms 开源元数据平台中。受到巴黎 CodeCommons 全会上一场技术演讲的启发，作者详细阐述了打造一系列配套开源工具的全过程——其中包括专为 Git 定制的归档传输助手 swh-git、面向 Ruby 与 Go 的 SWHID 原生生成库、基于 WebAssembly 的浏览器端客户端，以及 OpenAPI 规范接口封装。这一系列工具旨在打通软件包身份标识与底层代码指纹，显著提升关键开源包的归档完整度，进而为软件生态的长久可重现性保驾护航。

This article explores the integration of Software Heritage (SWH) archives and Software Hash IDentifiers (SWHIDs) into the ecosyste.ms platform. Inspired by a presentation at the CodeCommons plenary in Paris, the author details the creation of various open-source tools—including swh-git, language-specific SWHID generators for Ruby and Go, a WebAssembly client, and an OpenAPI wrapper—to connect package identities, improve archiving coverage, and enable long-term software reproducibility.

目录

Table of Contents

• Software Heritage 开源代码档案馆
• SWHID 软件哈希标识符
• swh-git 传输层助手
• 计算 SWHID 指纹
• Web API 接口封装
• 关键软件包的归档覆盖率
• science.ecosyste.ms 科学计算软件追踪
• packages.ecosyste.ms 软件包版本全生命周期指纹
• 扫描与深度分析代码档案库

• Software Heritage
• SWHIDs
• swh-git
• Computing SWHIDs
• Web API
• Critical Package Coverage
• science.ecosyste.ms
• packages.ecosyste.ms
• Scanning the Archive

Software Heritage 开源代码档案馆

Software Heritage

自法国国家信息与自动化研究所 (Inria) 于 2016 年发起该项目以来，Software Heritage 一直致力于为人类全部公开源代码构建一座通用“数字代码档案馆”。它的爬虫常年穿梭于 GitHub、GitLab、Bitbucket、各大中小型代码托管平台、软件包中心以及各大 Linux 发行版源码库，将采集到的所有代码统一沉淀在一个全局去重的 Merkle DAG 结构之中。截至目前，这张庞大的代码知识图谱已汇聚了来自 4.45 亿个代码源头的约 300 亿个源码文件、230 亿个目录以及 60 亿次代码提交记录。

Software Heritage has been building a universal archive of source code since Inria launched the project in 2016. It crawls GitHub, GitLab, Bitbucket, smaller forges, package registries, and distro sources, storing everything in a single deduplicated Merkle DAG. Currently, this graph holds roughly 30 billion source files, 23 billion directories, and 6 billion commits across 445 million origins.

即使同一个文件出现在成百上千个不同的地方 (例如某个文件既存在于 npm 的 tarball 压缩包中，又被打包进 Debian 源码包) ，Software Heritage 也只会在底层存储一次，直接通过其二进制字节哈希进行内容寻址，而图谱系统则负责记录该文件曾出现过的每一个代码源头 (Origin) 。其内部的 Vault 服务支持按需将任意历史快照、提交记录或目录重新组装为可直接下载的 git bundle 或 tarball 归档，从而确保代码检索完全立足于内容本身，彻底摆脱对原始代码托管服务商与 URL 链接的脆弱依赖。

Files appearing in multiple places (such as an npm tarball and a Debian source package) are stored only once, addressed by their byte hash, while the graph tracks every origin. The Vault can reconstruct any snapshot, commit, or directory on demand as a downloadable git bundle or tarball, ensuring content-based retrieval rather than reliance on original hosting URLs.

SWHID 软件哈希标识符

SWHIDs

档案库中的每一个对象都被赋予了一个结构形如 swh:1:<type>:<sha1> 的 SoftWare Hash IDentifier (SWHID) 。

Every object in the archive is assigned a SoftWare Hash IDentifier structured as swh:1:<type>:<sha1>.

其五大核心对象类型包括：

The five core types include:

• cnt (文件内容字节)
• dir (目录树结构)
• rev (代码提交)
• rel (版本标签)
• snp (仓库快照)

• cnt (file bytes)
• dir (directory tree)
• rev (commit)
• rel (tag)
• snp (repository snapshot)

用户还可以为 SWHID 添加可选的限定修饰符 (Qualifiers) ，用以锚定来源 URL、爬虫访问记录 (Visits) 、目录内部的相对路径乃至具体的代码行号区间。该规范的 1.2 版本已被正式发布为国际标准 ISO/IEC 18670，标志着全球首个针对软件内在标识符的国际标准正式确立。

Optional qualifiers can pin origin URLs, visits, paths inside directories, or line ranges. Version 1.2 of the specification was published as ISO/IEC 18670, establishing the first international standard for intrinsic software identifiers.

SWHID 具备所谓“内在性 (Intrinsic)”——它完全由底层数据字节直接计算生成，不需要任何中心化的注册表或发证权威背书。由于这些哈希的计算规则与 Git 的对象哈希机制天然对齐，开发者本地任何一份 Git 检出仓库中，实际上都已经包含了完全合规的 SWHID。与之相对，形如 pkg:pypi/astropy@7.1.0 的软件包 URL (Package URL, purl) 虽然直观且人类可读，但它们的解析严重依赖于中心化注册中心的持续在线与可用。将这两大标识符体系无缝桥接起来，正是 ecosyste.ms 平台致力于实现的核心目标。

SWHIDs are intrinsic—computed directly from bytes without a registry or issuing authority. Because these hashes align with Git's object hashes, any local Git checkout already contains valid SWHIDs. While package URLs (purls) like pkg:pypi/astropy@7.1.0 are human-readable, resolving them depends on registries remaining active. Bridging these two identifier schemes forms a core focus of ecosyste.ms.

swh-git 传输层助手

swh-git

开源工具 swh-git 作为 Git 远程助手 (Git Remote Helper) ，通过引入全新的 swh:: 自定义传输层协议，允许开发者直接从归档库中检出并还原历史代码：

The swh-git git remote helper adds an swh:: transport layer to retrieve archived code:

git clone swh::github.com/octocat/Hello-World
git clone swh::swh:1:snp:f72e9d06dd0e58236a34328f094ca894a809f230

该助手会在后台向 Software Heritage 的 Vault 申请一份 git-bare bundle 归档包，将其缓存在本地磁盘，随后通过 Git 原生的 git upload-pack 协议无缝完成仓库克隆。对于那些在 GitHub 上早已显示 404、或者原始代码托管站点已经关门大吉的失效仓库而言，这提供了一道至关重要的代码灾难恢复生命线，不仅完整保留了提交历史与标签，还全面支持目录级的 SWHID 检索。

The helper requests a git-bare bundle from the Vault, caches it locally, and serves clones via git upload-pack. It provides a vital recovery mechanism for 404ing repositories or defunct forges, supporting full commit histories, tags, and directory SWHIDs.

计算 SWHID 指纹

Computing SWHIDs

为了在不同编程语言生态中原生计算 SWHID，作者开发了一套跨语言的工具链：

To compute SWHIDs natively across different languages, the author developed:

• swhid gem (Ruby) ：全面支持五种核心对象类型的解析、限定修饰符处理与指纹生成。
• swhid-go (Go) ：提供便捷的命令行工具 (CLI) ，并内置了针对 SHA-1 哈希碰撞的防御性检测机制。
• swhid-wasm：将 swhid-go 编译为 WebAssembly 模块，支持直接在前端浏览器中对软件包注册表中的包或本地归档文件进行客户端哈希计算。

• swhid gem (Ruby): Handles parsing, qualifiers, and generation for all five object types.
• swhid-go (Go): Includes a CLI and built-in SHA-1 collision detection.
• swhid-wasm: A WebAssembly compilation of swhid-go enabling client-side hashing in the browser from package registries or local archives.

Ruby 和 Go 的这套实现均已接入上游官方的 一致性测试套件 (conformance test suite) ，确保生成的标识符严格符合国际规范。

Both the Ruby and Go implementations integrate with the upstream conformance test suite.

Web API 接口封装

Web API

为了高效调用 Software Heritage 的开放接口 (archive.softwareheritage.org/api/1) ，作者开发了 swh-openapi 工具，能够从官方文档字符串 (docstring) 中自动提取并生成标准 OpenAPI 接口描述文件；同时还配套推出了 Go 语言客户端 SDK swh-go ，大幅降低了第三方开发者接入归档生态的门槛。

To interact with the Software Heritage API (archive.softwareheritage.org/api/1), the author created swh-openapi to generate OpenAPI descriptions from docstring data, along with swh-go as a companion client.

关键软件包的归档覆盖率

Critical Package Coverage

借助 swh-critical 审计工具，作者对 packages.ecosyste.ms 关键软件包数据集 中的约 9,800 个核心开源包进行了系统性摸底评估：

An audit using swh-critical evaluated ~9,800 packages in the packages.ecosyste.ms critical set:

• 71.3% 的源码仓库已将其当前默认分支的最新提交纳入归档；
• 89.9% 的匹配版本发布标签 (Release Tags) 均在档案库中完整就绪。

• 71.3% of source repositories had their current default-branch commit archived.
• 89.9% of matched release tags were present.

通过将这些处于高依赖核心位置的软件包任务队列，主动推送给 Software Heritage 的代码即时保存服务 Save Code Now ，ecosyste.ms 能够有效引导爬虫调度算法，将宝贵的采集与算力资源优先倾斜给那些全行业重度依赖的基础源码项目。

By feeding high-dependency package queues into Software Heritage's Save Code Now service, ecosyste.ms can help prioritize crawler resources toward heavily relied-upon source code.

science.ecosyste.ms 科学计算软件追踪

science.ecosyste.ms

science.ecosyste.ms 平台正将这一归档闭环率先应用于科研软件生态。系统会自动拉取学术影响力较高的高分科研项目，自动执行仓库克隆并在本地生成 SWHID 指纹，随后批量调用 Software Heritage 的已知对象接口 (known-objects API) 进行同步校验。一旦验证归档成功，对应的 SWHID 元数据便会与学术数字对象唯一标识符 (DOI) 和学术引用信息并肩展示在项目页面上，同时通过开放的 统计数据 JSON API 供学界直接调用。

The science.ecosyste.ms platform applies this feedback loop to research software. High-score projects undergo automated cloning, SWHID generation, and batch-posting to Software Heritage's known-objects API. Confirmed contributions and SWHID metadata are displayed alongside DOIs and citations on project pages and via a stats page JSON API.

packages.ecosyste.ms 软件包版本全生命周期指纹

packages.ecosyste.ms

未来，packages.ecosyste.ms 平台的集成计划将进一步深入到具体的“软件包版本”层面——直接为官方发布的每个 tarball 压缩包计算对应的目录级 SWHID。这意味着在软件物料清单 (Software Bill of Materials, SBOM) 中声明的每一个依赖组件 (例如 pkg:npm/lodash@4.17.21) ，未来都能精确解析到一个可独立查验、防篡改的 SWHID 权威指纹，从而为各大主流软件包注册中心建立起一套持续滚动的归档覆盖率度量体系。

Future integration on packages.ecosyste.ms will extend this coverage to package versions by computing directory SWHIDs for published tarballs. This allows SBOM components (e.g., pkg:npm/lodash@4.17.21) to resolve to independently verifiable SWHIDs, establishing a rolling measurement of registry coverage.

扫描与深度分析代码档案库

Scanning the Archive

借助开源的 git-pkgs 工具套件——涵盖用于清单提取的 manifests、开源协议分析的 licenses 以及信息速览工具 brief——开发者能够将整个 Software Heritage 档案库当作一座容量惊人的代码分析语料库。当它与 swh-git 强强联手时，无论跨越多少历史版本迭代，针对项目依赖链、合规许可证乃至构建工具链的深度分析，都能实现完全可重现与可验证。

Using the git-pkgs suite—including manifests, licenses, and brief—developers can treat the Software Heritage archive as a massive analysis corpus. Combined with swh-git, analyses of dependencies, licenses, and toolchains become fully reproducible across historical software versions.