1. 摘要

软件包复用生态包含包发现与包管理两个相邻机制。包发现处理消费者在引入依赖之前的识别、理解、比较和判断；包管理处理消费者项目在引入依赖之后的声明、求解、获取、校验、安装、构建、锁定、升级和审计。

Manifest、Registry、Index、Resolver、Lockfile、Artifact、Documentation、Security Metadata 和 Ecosystem Feedback 共同说明软件构件如何成为可发现、可比较、可求解、可获取、可复现、可审计、可维护的依赖对象。主流语言生态提供同一对象模型下的事实案例，并支撑生命周期模型、证据源分类、变量体系和评价尺度。

版本说明

版本：v1.0。

主题：软件包复用生态中的包发现、包管理、证据源、变量体系和评价尺度。

前言

现代软件开发依赖大量外部软件包。依赖引入不只是找到一个可安装名称；它要求消费者识别包身份、理解包功能、判断许可证、求解依赖图、校验构件、固定版本状态，并在后续维护中处理漏洞、弃用、迁移和来源证明。

不同语言生态已经形成各自的 Manifest、Registry、Index、Resolver、Lockfile、Artifact、Documentation 和 Security Metadata。把这些机制放入 对象模型 后，包级判断和生态级判断才能使用同一套术语、证据源和评价尺度。

技术选型工程师需要判断候选包能否进入当前项目；包作者需要让源码项目成为生态可消费对象；工具平台设计者需要确定 registry、index、resolver、dependency graph 和 audit surface 的责任边界；研究者需要在多个语言生态之间抽象共同结构并保留领域差异。四类读者面对同一个复用生态，但行动入口不同；读者路径见 读者路径。

npm、Cargo、PyPI、Maven Central、NuGet.org、ConanCenter、vcpkg registry、SwiftPM、deps.dev 和 Swift Package Index 不是同一类对象。它们分别承担工具、注册表、索引、文档表面、第三方聚合面或发现增强面的职责；这些职责的边界决定身份、元数据、求解、构件、兼容性、安全和治理如何被观察。

Part I: 进入包复用生态

包复用生态把陌生软件构件转化为可依赖工程对象。进入这个对象需要先区分包发现、包管理、读者行动和全书基本命题。

2. 研究对象

软件包复用生态把作者发布的软件构件转化为消费者可依赖的工程对象。这个转化过程需要身份、声明、发布、索引、发现、评估、求解、获取、校验、锁定、维护和治理共同成立。

这个转化过程包含两个核心机制：Package Discovery 和 Package Management。

Package Discovery 是消费者在引入依赖之前识别候选包、理解候选包、比较候选包并形成引入判断的机制。搜索只是 Discovery 的入口之一。分类浏览、标签、相似包、文档阅读、API 检查、依赖图观察、安全状态、维护状态、生态采用度和社区策展都属于 Discovery 的可见表面。

Package Management 是消费者项目声明、解析、获取、校验、安装、构建、锁定、升级、审计和移除依赖的机制。Package Manager 是这个机制的工具投影。npm、pnpm、Yarn、Cargo、pip、uv、Maven、Gradle、NuGet、Conan、vcpkg 和 SwiftPM 是工具实例，不是 Management 机制本身。

Discovery 和 Management 共享同一条包复用生命周期，但二者承担不同责任。Discovery 处理引入前的判断；Management 处理引入后的工程成立。

对象模型 和 评价尺度 用于说明不同语言生态如何让包成为可发现、可比较、可求解、可获取、可复现、可审计、可维护的依赖对象。工具名称只作为机制实例出现。

对象 处理的问题 典型投影

Package Discovery

消费者如何识别、理解、比较候选包并形成引入判断。

搜索页、分类页、文档站、API 浏览器、依赖图、质量信号、安全提示。

Package Management

消费者项目如何声明、求解、获取、校验、安装、构建、锁定、升级和审计依赖。

CLI、构建工具、resolver、lockfile、cache、audit report、install tree。

Registry / Index

包身份、版本、元数据、构件和解析数据如何进入公共或组织内部可见空间。

npm registry、crates.io、PyPI、Maven Central、NuGet.org、Go module proxy、Conan remotes、vcpkg registries。

事实判断以公开规范、官方文档、官方注册表、安全基础设施和标明来源层级的第三方数据表面为依据。

3. 读者路径

包复用生态至少对应四类行动入口：引入依赖、发布包、设计工具平台、构造评价模型。行动不同，所需对象也不同。

3.1. 技术选型工程师

技术选型工程师需要判断一个候选包是否适合当前项目。这个判断不是单一偏好判断，而是功能相关性、许可证、平台兼容性、维护状态、依赖图、安全状态、构件完整性和组织策略的共同结果。

这类读者的主路径是包发现、对象模型、生命周期、相关生态章节 和 包级评价。该路径提供四个判断边界：

  • 包能被搜索到，不等于包适合当前目标。

  • 包能被安装，不等于包能长期维护。

  • 下载量和 Star 是社会证据，不是安全证明。

  • Lockfile 固化的是一次求解结果，不是许可证、安全和平台兼容性的替代物。

3.2. 包作者与库维护者

包作者需要把源码项目构造成生态可消费对象。这个动作不止发布文件，还包括声明身份、依赖、许可证、入口、平台约束、文档、版本、弃用策略和发布身份。

这类读者的主路径是 对象模型、生命周期、安全治理 和 相关生态章节。该路径说明 Manifest 中每个关键字段服务哪个消费者判断，文档和 API 投影如何影响发现，provenance 和 trusted publishing 如何改变发布身份的可观察性。

3.3. 工具、平台与 registry 设计者

工具和平台设计者需要判断一个包生态系统中哪些对象必须存在，哪些数据必须被索引，哪些信号可以进入排序，哪些风险不能被分数抵消。

这类读者的主路径是 对象模型、证据与度量、安全治理、评价尺度、资料来源图 和 结构词表。该路径区分 Registry、Index、Repository、Discovery Surface、Resolver、Lockfile、Artifact、Provenance 和 Attestation 的职责。

3.4. 研究者与模型构造者

研究者需要从多个语言生态中抽象共同结构，同时保留各生态的领域事实。JS/TS、Rust、Python、Go、JVM/Kotlin、.NET、C/C++ 和 Swift 面对不同约束；同一个维度在不同生态中的指标口径可能不同。

这类读者的主路径是 证据与度量、生态对照、评价尺度、变量字典、生态矩阵 和 资料来源图。该路径说明哪些变量可跨生态比较，哪些变量只能生态内比较，官方事实源和第三方聚合面如何分层，评价函数如何避免成为无来源总分。

读者 核心问题 优先章节

技术选型工程师

当前项目是否应引入某个候选包。

第一部、第二部、第三部、相关生态章节、包级评价。

包作者与库维护者

项目如何成为别人能发现、理解、信任、安装和维护的包。

对象模型、生命周期、安全治理、相关生态章节。

工具与平台设计者

registry、index、resolver、discovery surface 和 audit surface 应承担哪些责任。

对象模型、证据与度量、安全治理、评价尺度、资料来源图、结构词表。

研究者与模型构造者

如何用同一套尺度比较多个语言生态，并保留生态差异。

证据与度量、生态对照、评价尺度、变量字典、生态矩阵、资料来源图。

4. 基本命题

包复用不是复制代码。包复用是把一个陌生软件构件放入新的软件系统，并让这个构件在明确身份、明确约束、明确来源、明确依赖图、明确兼容性和明确维护状态的条件下被使用。

一个开发者需要 HTTP client 时，行动通常从发现开始。开发者可能在搜索引擎、npm、crates.io、PyPI、pkg.go.dev、Maven Central、NuGet.org、Swift Package Index 或 GitHub 中寻找候选包。候选包进入视野后，开发者会阅读 README、API 文档、示例、许可证、更新时间、维护者、依赖数量、漏洞提示和安装命令。

选定候选包之后，行动进入管理阶段。消费者项目把依赖写入 Manifest；Package Manager 根据版本约束、平台约束、feature、extras、target framework、lockfile 和 registry metadata 求解依赖图；系统下载或构建 Artifact，校验哈希或签名，写入 Lockfile。后续维护阶段继续处理升级、漏洞、弃用、许可证变化和依赖图变化。

这个行动轨迹说明同一个包复用事件至少涉及八类对象：

  • Manifest 让项目和包可被机器读取。

  • Registry 和 Index 让包进入可发现、可获取、可解析的空间。

  • Discovery Surface 让消费者形成候选集合和比较依据。

  • Resolver 把版本和环境约束合成为一致依赖图。

  • Lockfile 固化一次求解结果。

  • Artifact 承载实际被下载、构建、链接或安装的构件。

  • Security Metadata 让漏洞、发布身份、来源证明和完整性状态可观察。

  • Ecosystem Feedback 把使用、维护、弃用、漏洞和反向依赖回流到发现与管理机制。

基本命题是：软件包复用生态通过这些对象和机制，把作者发布的软件构件转化为消费者可发现、可比较、可求解、可获取、可复现、可审计、可维护的依赖对象。

这条命题同时包含共同结构和生态差异。共同结构包括 Manifest、Registry、Index、Resolver、Lockfile、Artifact、Documentation、Security Metadata 和 Feedback。生态差异来自语言、构建系统、平台、ABI、目标框架、版本策略、注册表治理和供应链基础设施。

因此，评价尺度 不输出无条件总榜。包级评价 回答“某个包在给定查询和消费者上下文中是否适合引入”。生态级评价 回答“某个生态在给定生命周期阶段是否提供足够机制”。二者使用 同一对象模型，但评价对象不同。

Part II: 对象模型

软件包复用生态中的基础对象包括 Package、Artifact、Manifest、Registry、Index、Resolver、Lockfile、Provenance 和 Attestation。生命周期、证据源、生态对照 和 评价尺度 都依赖这些对象边界。

5. Package 与 Artifact

Package 是在某个语言或构建生态中被命名、版本化、可获取、可声明为依赖的软件复用单元。Package 可以是库、框架、CLI 工具、插件、类型声明、源码集合、二进制构件集合或系统库绑定。

Package 的构成性条件包括身份、版本或版本等价状态、可获取位置、依赖声明能力和消费者可引用表面。缺少这些条件时，一个源码仓库仍然可以存在，但它还没有成为该生态中可管理的包对象。

Artifact 是可下载、可缓存、可校验、可构建或可链接的具体构件。Artifact 承载消费者实际获得或生成的内容，例如 npm tarball、Cargo .crate 文件、Python wheel、Maven JAR、NuGet .nupkg、Swift source archive、Conan binary package 或 vcpkg binary cache entry。

Package 不等于 Artifact。Package 是复用生态中的身份和声明对象；Artifact 是某个版本、平台、构建配置或变体下的具体构件。一个 Package 可以对应多个 Artifact。

生态 Package 身份表面 Artifact 表面

JS/TS

package.json 中的 name 与 version。

发布到 npm registry 的 tarball，或工具缓存中的包内容。

Rust

Cargo.toml 中的 package name 与 version。

crates.io 下载的 .crate 文件。

Python

规范化 project name 与 release version。

sdist、wheel，以及带 Python tag、ABI tag、platform tag 的 wheel 文件。

JVM

Maven 坐标中的 groupId、artifactId、version。

JAR、POM、sources、javadoc、Gradle Module Metadata 等仓库文件。

.NET

NuGet package ID 与 exact version。

.nupkg 文件及其中按 target framework 组织的 assets。

C/C++

Conan reference 或 vcpkg port/version/baseline。

由 settings、options、triplet、compiler、runtime、build type 等变量约束的源码或二进制构件。

评价包时必须保留 Package 与 Artifact 的层位差异。包名和版本能定位复用对象，但不能总是定位可用构件。Python、.NET、C/C++、Kotlin Multiplatform 和 Swift binary target 都要求模型继续观察平台、ABI、target framework、variant、toolchain 或 checksum。

6. Manifest、Registry 与 Index

Manifest 是项目或包对机器声明自身身份、依赖、版本、平台、许可证、入口和构建约束的结构化表面。Manifest 让包成为可索引、可求解、可审计、可复现的对象。

Manifest 的职责不是展示项目故事。它向工具链和消费者提供可读取约束：包是谁、依赖谁、支持什么环境、暴露什么入口、如何构建、如何发布、哪些文件进入构件、哪些能力由 feature、extra、target 或 platform 控制。npm package.json、Cargo manifest、PyPA project metadata、Go go.mod、Maven POM、NuGet .nuspec、Swift Package.swift、Conan recipe 和 vcpkg manifest 分别给出这些约束在各生态中的公共表面。参见 npm package.json、Cargo manifest、PyPA pyproject.toml、Go Modules Reference、Maven POM、NuGet .nuspec、Swift PackageDescription、Conan conanfile attributes 与 vcpkg.json reference。

典型 Manifest 包括 package.json、Cargo.toml、pyproject.toml、go.mod、pom.xml、.nuspec、Package.swift、conanfile.py 和 vcpkg.json。这些文件的语法不同，但它们都把源码项目投影为生态可处理对象。

Registry 是接收、保存、分发和索引 package metadata 与 Artifact 的基础设施。Registry 可以提供发布权限、命名空间、版本记录、下载地址、元数据 API、撤回或弃用状态、安全提示和 provenance 材料。

Registry 不等于源码仓库。源码仓库保存开发历史和源文件；Registry 保存生态消费所需的发布对象、版本状态和分发表面。Go 的模块体系把源码仓库、module proxy、checksum database 和 pkg.go.dev 分布到多个基础设施上，但模型中仍需区分源码位置、分发缓存、完整性证明和文档索引。

Index 是可搜索、可解析、可用于发现或依赖求解的数据视图。Index 可以由 Registry 提供，也可以由第三方聚合器构造。

Index 至少有两类用途。Resolver 使用解析型 Index 获取版本、依赖、checksum、artifact URL 或 metadata。Discovery Surface 使用发现型 Index 提供搜索、分类、文档、下载量、反向依赖、安全状态、维护信号和兼容性信号。Cargo registry index、PyPI Simple Repository API 和 NuGet V3 registration 体现了解析型数据视图在不同生态中的形式。参见 Cargo registry index、PyPI Simple Repository API 与 NuGet overview。

对象 主要责任 例子

Manifest

声明包身份、依赖、版本、入口、平台和构建约束。

package.json、Cargo.toml、pyproject.toml、go.mod、pom.xml。

Registry

保存发布对象、版本状态、构件、元数据和治理状态。

npm registry、crates.io、PyPI、Maven Central、NuGet.org。

Index

提供可搜索或可解析的数据视图。

Cargo registry index、PyPI Simple Repository API、NuGet V3 registration、deps.dev graph data。

Repository

保存源码或构件仓库内容。

GitHub repository、GitLab repository、Maven repository layout、private artifact repository。

第三方发现面需要保留事实源层级。MvnRepository、lib.rs、FuGet、Swift Package Index、Libraries.io、deps.dev 和 ecosyste.ms 可以提供重要发现信号，但它们不自动成为对应生态的发布事实源。

7. Resolver、Lockfile 与 Realization

Resolver 是把版本范围、依赖关系、平台约束、feature、extra、target framework、variant、lockfile 和 registry metadata 合成一致依赖图的求解器。Resolver 的输出是依赖图选择结果，不是下载动作本身。

Resolver 的输入来自多个位置：消费者项目的 Manifest、既有 Lockfile、Registry 或 Index metadata、目标运行时、目标平台、工具链配置、组织策略和命令参数。不同生态使用不同求解规则。Go 使用 Minimal Version Selection；Maven 使用 dependency mediation；Gradle 使用 variant-aware resolution 和 conflict resolution；pip 与 uv 处理回溯或跨平台解析；Cargo 处理 version requirement 和 feature resolution；NuGet 处理 target framework、direct dependency wins 和 lowest applicable version 等规则。参见 Go Modules Reference、Maven dependency mechanism、Gradle variant-aware resolution、uv resolution、Cargo resolver 与 NuGet dependency resolution。

Lockfile 是一次依赖求解结果的固化记录。它服务协作一致性、可复现安装、审计和后续升级比较。Lockfile 记录的对象通常包括具体版本、来源、checksum、transitive graph、package identity 和工具特定 metadata。

Manifest 与 Lockfile 的职责不同。Manifest 表达项目意图和约束；Lockfile 保存一次求解结果。Manifest 中的版本范围可以允许多个解，Lockfile 把当前解固定为后续安装、审计和升级的基线。

Realization 是依赖从求解结果变成消费者项目中实际构件的过程。它包括下载、校验、缓存、解包、构建、链接、安装、生成 loader、写入 lock、更新本地环境等动作。

Realization 不是单一安装命令。npm 可能写出 node_modules tree；pnpm 使用 content-addressable store 与链接结构；Yarn 可能生成 Plug’n’Play loader；Cargo 会下载 .crate 并构建；Python 安装器会选择 wheel 或 sdist；NuGet restore 会写入资产文件并校验 package content hash；Conan 和 vcpkg 会在配置矩阵下取得或构建二进制构件。参见 pnpm store、Yarn Plug’n’Play、Python wheel、NuGet PackageReference、Conan binary model 与 vcpkg manifest mode。

对象 回答的问题 失败形态

Resolver

哪些版本和变体共同满足当前约束。

版本冲突、平台不兼容、peer dependency 不满足、variant 无匹配。

Lockfile

当前解如何被协作、审计和未来安装复用。

lock 与 manifest 不同步、checksum 不匹配、来源变化、锁定粒度不足。

Realization

求解结果如何成为本地实际构件。

下载失败、hash mismatch、构建失败、二进制不可用、链接失败、安装脚本失败。

评价包管理机制时不能把 Resolver、Lockfile 和 Realization 合并为“安装”。一个生态可以有清楚的 resolver 但较弱的 lock 语义，也可以有强构件完整性但发现信号不足。模型必须保留这些对象的独立责任。

8. Provenance 与 Attestation

Provenance 描述 Artifact 从什么源码、什么构建过程、什么构建平台、什么发布身份和哪些输入产生。它把构件和构建事实绑定起来，使消费者可以审查来源链条。

Attestation 是对某个 Artifact、构建过程、发布身份或安全事实的可验证声明。Attestation 通常绑定 subject digest、predicate type、builder identity、publisher identity、时间、输入和签名材料。

Provenance 和 Attestation 不等同于“安全”。它们说明构件来自哪里、如何构建、由谁或哪个自动化环境发布；它们不说明构件没有恶意行为，也不替代漏洞公告、代码审计、许可证判断或运行时隔离。

SLSA 提供供应链来源证明的结构化语言。Sigstore 提供基于身份的签名、短生命周期证书和透明日志材料。npm provenance 和 PyPI digital attestations 把注册表发布、CI 身份、构件摘要和证明材料连接到包发布流程中。参见 SLSA specification、Sigstore overview、npm provenance 与 PyPI digital attestations。

对象 可说明 不可说明

Provenance

构件与源码、构建过程、构建平台和发布身份之间的来源关系。

构件无漏洞、无恶意、适合当前项目。

Attestation

某个主体对构件、构建或发布事实作出的可验证声明。

声明内容之外的安全性质。

Checksum / Digest

下载内容是否匹配预期字节内容。

字节内容是否良性或可维护。

Vulnerability Advisory

某个版本范围是否被已知漏洞公告覆盖。

没有公告时包一定安全。

评价系统必须把来源证明、制品完整性、漏洞状态和项目治理分开。一个包存在 provenance 但被公告为恶意时，provenance 只能说明恶意构件的来源，不能抵消恶意状态。

Part III: 生命周期

复用生命周期描述包从源码项目到维护对象的状态转移。每个阶段都有输入、输出、参与对象和失败影响；这些阶段共同规定作者、注册表、索引、消费者项目和维护机制之间的责任转移。

9. Authoring、Declaration 与 Publication

包复用生命周期从作者构造开始。源码、测试、文档、示例、构建脚本和许可证材料形成潜在复用对象；它们还没有自动成为生态中的 Package。

9.1. Authoring

Authoring 是作者构造源码项目的阶段。输入是问题、设计、源码、测试、文档和构建脚本。输出是可以被声明和发布的项目材料。

Authoring 阶段产生结构性证据。API、类型签名、导出符号、文档注释、测试布局、示例和弃用标记都来自这个阶段。它们可以被 docs.rs、pkg.go.dev、FuGet、Swift Package Index 或其他文档表面提取。

Authoring 阶段的失败会进入后续阶段。源码结构混乱、公共 API 不稳定、测试缺失、许可证材料不清楚、构建脚本依赖隐含环境，都会降低后续声明、索引、发现、求解和维护的可靠性。

9.2. Declaration

Declaration 是项目通过 Manifest 声明身份、版本、依赖、许可证、平台、入口、构建后端、特性开关或目标环境的阶段。输入是 Authoring 阶段形成的项目材料。输出是机器可读取的声明表面。

Manifest 是 Declaration 阶段的核心对象。package.json、Cargo.toml、pyproject.toml、go.mod、pom.xml、.nuspec、Package.swift、conanfile.py 和 vcpkg.json 都把项目投影为生态可处理对象。

Declaration 阶段的失败会破坏后续机制。包名不稳定会破坏发现和依赖声明；依赖声明不完整会破坏 resolver；许可证缺失会破坏合规判断；平台约束不清楚会破坏兼容性判断；构建后端不明确会破坏 realization。

9.3. Publication

Publication 是作者把源码包、二进制构件或索引记录发布到 Registry、Repository 或 VCS-backed index 的阶段。输入是 Manifest、Artifact、源码仓库、发布身份和注册表规则。输出是可被消费者或工具链获取的版本状态。

Publication 阶段建立包的公共可见性和可获取性。npm registry、crates.io、PyPI、Maven Central、NuGet.org、ConanCenter、vcpkg registry 和 Swift Package Registry Service 都承担发布或分发职责。Go 的发布路径通过 module path、VCS tag、module proxy 和 checksum database 共同形成。

Publication 阶段的失败包括错误版本、错误构件、错误许可证、错误依赖、错误发布身份和不可撤回的不良 release。发布后状态会被后续 Indexing、Discovery、Resolution 和 Maintenance 使用，因此发布不是单纯上传文件。

阶段 输入 输出 主要失败影响

Authoring

源码、测试、文档、构建脚本。

可被声明和发布的项目材料。

公共 API、构建和许可证状态不稳定。

Declaration

项目材料和 Manifest 规则。

机器可读取的身份、依赖、平台和构建约束。

索引、求解、合规和兼容判断失真。

Publication

Manifest、Artifact、发布身份、注册表规则。

可获取的包版本或发布记录。

错误 release 进入公共依赖图和维护流程。

10. Indexing、Discovery 与 Assessment

Publication 使包进入可获取空间；Indexing、Discovery 和 Assessment 使包进入消费者判断空间。

10.1. Indexing

Indexing 是平台抽取、保存和投影包信息的阶段。输入是发布记录、Manifest、Artifact、源码仓库、文档、构建结果、安全公告和生态反馈。输出是可供搜索、解析、比较和审计的数据视图。

Indexing 至少服务两类消费者。Resolver 需要版本、依赖、checksum、artifact URL、metadata 和 yank/deprecation 状态。人类消费者和发现系统需要描述、README、API 文档、分类、下载量、反向依赖、安全状态、维护状态和兼容性信号。

Indexing 阶段的失败会降低 Discovery 和 Resolution 的质量。元数据缺失会降低召回和比较；依赖数据错误会破坏求解；安全公告映射错误会误导风险判断；第三方聚合数据若不标来源，会造成事实源混淆。

10.2. Discovery

Discovery 是消费者获得候选集合和比较材料的阶段。输入是查询、上下文、搜索索引、分类、文档表面、依赖图、安全信号和社区策展。输出是候选包集合及其可比较证据。这个阶段实现 研究对象 中“引入前判断”的责任。

Discovery 不等于搜索。搜索只处理从查询到候选集合的入口。Discovery 还包括阅读文档、检查 API、比较依赖图、识别许可证、观察维护状态、检查漏洞状态和判断生态位置。

Discovery 阶段的失败包括相关包未被召回、不满足约束的包被高排序、第三方信号被误认为官方事实、下载量被误认为质量、安全证明被误认为无风险证明。

10.3. Assessment

Assessment 是消费者判断候选包是否可引入的阶段。输入是候选集合、消费者目标、运行环境、许可证策略、安全阈值、平台约束、组织规则和可观察证据。输出是引入判断、拒绝判断或继续调查判断。

Assessment 的对象不是抽象质量。它判断某个候选包在给定消费者上下文下是否满足目标和约束。同一个包可能适合原型项目，不适合生产基础设施；可能适合 Linux 服务，不适合移动端；可能功能相关，但许可证禁止使用。

Assessment 阶段的失败会把不合适依赖推进到 Resolution 和 Realization。后续工具可能仍能安装它，但安装成功不能修复许可证不合规、平台错配、维护风险或安全风险。

阶段 输入 输出 主要失败影响

Indexing

发布记录、Manifest、Artifact、文档、安全公告、反馈。

搜索、解析、审计和比较所需的数据视图。

发现排序失真，解析数据错误，风险提示错误。

Discovery

查询、上下文、索引、文档、图谱和安全信号。

候选集合及比较证据。

候选缺失、排序失真、事实源混淆。

Assessment

候选集合、消费者目标、约束和证据。

引入、拒绝或继续调查判断。

不合适依赖进入项目工程链路。

11. Resolution、Realization 与 Maintenance

Assessment 形成引入判断后，包复用进入工程执行阶段。Resolution、Realization 和 Maintenance 决定依赖是否能在消费者项目中稳定成立。

11.1. Resolution

Resolution 是 Package Manager 根据消费者项目声明、目标平台、版本约束、feature、extras、target framework、lockfile 和 Registry metadata 求出一致依赖图的阶段。输入是 Manifest 与 Registry metadata、既有 Lockfile、目标环境、索引数据和命令参数。输出是一组具体包版本、变体和依赖边。

Resolution 的核心是约束求解。npm、Cargo、pip、uv、Maven、Gradle、NuGet、Conan、vcpkg、SwiftPM 和 Go modules 使用不同规则；模型必须记录 resolver family 和 conflict rule。不同 resolver 可能对同一依赖图选择不同版本。

Resolution 阶段的失败包括版本冲突、平台不匹配、variant 无匹配、peer dependency 不满足、target framework 不兼容、source replacement 不合法、lockfile 与 manifest 不同步。

11.2. Realization

Realization 是依赖解变成本地实际构件的阶段。输入是 Resolution 输出、Artifact 来源、checksum、cache/store、构建工具、目标平台和文件系统。输出是项目可使用的依赖构件、本地安装状态、构建产物或 loader，并可能更新 Lockfile。

Realization 处理下载、校验、解包、缓存、构建、链接、安装和记录。这个阶段会暴露 Artifact 层风险：tarball integrity mismatch、wheel 不兼容、native build 失败、JAR 或 .nupkg 下载失败、Conan binary 不存在、vcpkg binary cache 未命中、Swift binary target checksum 不匹配。

Realization 阶段的失败说明求解结果不能在目标环境中落地。它不必然否定 Discovery 和 Assessment 的判断，但会产生新的事实，要求回到约束、平台或构件层重新判断。

11.3. Maintenance

Maintenance 是依赖进入项目后的持续处理阶段。输入是当前依赖图、Lockfile、漏洞公告、deprecation/yank/retract/unpublish 状态、许可证变化、版本发布、组织策略和运行反馈。输出是升级、保留、替换、移除、补丁、审计记录或迁移计划。

Maintenance 使包复用成为长期关系。漏洞公告需要映射到具体版本范围；许可证变化需要判断适用 release；deprecation 和 yanking 改变消费者默认选择；新版本发布可能改变依赖图；Lockfile 刷新会改变构件和审计基线。

Maintenance 阶段的失败包括漏洞长期未处理、锁文件漂移、替代包判断缺少证据、弃用状态被忽略、许可证冲突进入发布产物、发布来源证明缺失导致审计失败。

阶段 输入 输出 主要失败影响

Resolution

Manifest、Lockfile、目标环境、索引数据、版本约束。

一致依赖图、具体版本和变体选择。

冲突、无解、不兼容、lock 与 manifest 不同步。

Realization

依赖解、Artifact、checksum、cache、构建工具。

本地可使用构件、安装状态、构建产物。

下载、校验、构建、链接或安装失败。

Maintenance

依赖图、Lockfile、安全公告、弃用状态、版本变化。

升级、替换、保留、审计或迁移判断。

风险积累、合规失败、不可复现状态。

12. 生态反馈回路

包复用生态不是单向管道。消费者项目可以成为新的作者项目；一次依赖引入可以产生下载、反向依赖、漏洞报告、文档反馈、issue、patch、deprecation、fork、替代包和安全公告。这些反馈会回流到 Indexing、Discovery、Assessment 和 Maintenance。

反馈至少有五类。

使用反馈包括下载量、被依赖数量、source importers、dependent repositories 和重要项目采用。它说明包进入了哪些依赖图，但不直接证明质量或安全。

维护反馈包括 release cadence、issue response、PR merge、maintainer count、bus factor、security policy 和 archived/deprecated 状态。它说明项目是否仍能响应环境变化。

安全反馈包括 CVE、GHSA、OSV、RustSec、Go vulnerability database、NuGet audit、npm audit 和 malware advisory。它说明某些版本范围、提交范围或包状态被公告覆盖。

治理反馈包括 yanking、retraction、deprecation、unpublish、name transfer、owner change、trusted publishing 配置和 token policy。它说明注册表或维护者如何改变包的公共状态和消费者默认选择。

文档与兼容反馈包括 docs build status、platform build matrix、target framework coverage、wheel availability、binary cache availability、API diff 和 deprecation annotation。它说明包是否仍能被理解、构建和使用。

反馈必须保留来源和口径。GitHub dependents、MvnRepository Used By、pkg.go.dev imported-by、Libraries.io dependent repositories 和 crates.io reverse dependencies 不共享同一覆盖范围。把它们合并为无来源的 dependency_count 会破坏评价函数。

生态反馈的作用不是给包贴一个永久标签。它给 Discovery 和 Maintenance 提供新的证据，使消费者可以重新判断候选包、当前依赖和替代路径。

Part IV: 证据与度量

评价判断依赖证据来源和度量层级。事实、口径、权重和上下文经过 评价尺度 投影为可解释判断；评价尺度不替代事实。

13. 证据源

包复用评价需要区分证据来源。不同来源回答不同问题，也有不同失真方式。下载量、README、API 文档、Lockfile、checksum、漏洞公告和 provenance 不能合并为一个“质量信号”。

13.1. 声明性证据

Declared Evidence 来自 Manifest 和作者声明。它表达作者对包的主张。

声明性证据包括 name、version、description、keywords、license、dependencies、repository、homepage、engines、platforms、targets、features、extras、exports、build backend 和 workspace 信息。它的主要来源是 Manifest 与 Registry metadata；它的优势是结构化、可索引、可由工具直接消费；它的风险是缺失、过期、夸大或与构件内部事实不一致。

13.2. 结构性证据

Structural Evidence 来自源码、AST、类型签名、导出符号、文档注释、测试结构、示例、deprecated 标记和 API diff。它表达包本体结构。

结构性证据比 README 更接近对象本体。Go 的 pkg.go.dev、Rust 的 docs.rs、.NET 的 FuGet、Swift Package Index 的 DocC 构建都在不同程度上把源码结构投影为可读证据。

13.3. 图谱证据

Graph Evidence 来自依赖图和被依赖图。它表达包在生态网络中的位置。

图谱证据包括 direct dependencies、transitive dependencies、dependency depth、duplicate versions、reverse dependencies、source importers、repository dependents 和 important dependents。它的风险是覆盖范围不一致：GitHub dependents、pkg.go.dev imported-by、MvnRepository Used By、Libraries.io dependent repositories 和 deps.dev graph data 不是同一口径。

13.4. 运行与构建证据

Operational Evidence 来自 CI、构建矩阵、平台二进制、wheel tag、target framework、ABI、triplet、checksum、lockfile、binary cache 和构建结果。它表达包能否在目标环境中成立。

运行与构建证据在 Python、.NET、C/C++、Swift 和 Kotlin Multiplatform 中尤其重要。名称和版本不能单独推出目标环境可用性；可用性需要观察 Artifact、平台、ABI、toolchain、target framework 或 variant。

13.5. 社会证据

Social Evidence 来自下载量、Star、Fork、issue、PR、讨论、Awesome list、企业案例和社区教程。它表达注意力、经验和采用情况。

社会证据不能直接变成质量、安全或适配度。下载量会被 CI、镜像、传递依赖和历史包袱污染；Star 是注意力，不是生产可信；issue 数量既可能表示问题多，也可能表示使用者多。

13.6. 安全与治理证据

Security and Governance Evidence 来自 CVE、GHSA、OSV、RustSec、Go vulnerability database、NuGet audit、OpenSSF Scorecard、SLSA、Sigstore、trusted publishing、provenance、2FA、owner policy、yank、deprecation、retraction、unpublish 和 name transfer。

安全与治理证据需要拆分为漏洞状态、发布者身份、构建来源证明、制品完整性和项目治理。provenance 不能说明无恶意；没有漏洞公告不说明没有漏洞；Scorecard 是项目治理和开发流程证据，不是安全保证。

证据源 主要对象 证明力 失真风险

Declared

Manifest 与作者声明。

作者主张、工具可读约束。

缺失、过期、夸大、与构件不一致。

Structural

源码、API、类型、文档注释、测试。

包本体结构。

生成失败、平台条件遗漏、私有 API 误读。

Graph

依赖边、反向依赖、图位置。

生态关系和影响面。

覆盖范围不一致、间接依赖污染。

Operational

构建、平台、ABI、checksum、lock。

目标环境可成立性。

构建矩阵有限、缓存状态依赖环境。

Social

下载量、Star、issue、PR、讨论。

注意力和经验信号。

刷量、历史惯性、语义不稳定。

Security/Governance

公告、证明、身份、权限、撤回状态。

信任边界和治理状态。

覆盖不完整、公告映射错误、证明粒度混淆。

14. 维度、变量、指标、权重与分数

评价尺度需要区分五个层级：Dimension、Variable、Metric、Weight 和 Score。层级混淆会把模型降为印象打分。

Dimension 是评价空间中的抽象方向。它回答从哪一类性质观察包或生态，例如身份、元数据、相关性、文档、依赖图、兼容性、可复现性、维护、安全、采用度和治理。

Variable 是某个维度下可取值的观察对象。它回答具体观察什么，例如最近 release 距今天数、直接依赖数量、critical 漏洞数量、是否存在 Lockfile、是否支持目标平台。

Metric 是变量的测量口径。它回答如何测量变量，例如 days_since_last_release、direct_dependency_count、critical_vulnerability_count、reverse_dependency_count_log。Metric 必须有数据来源、单位、采集范围、缺失值处理和失真风险。

Weight 是某个维度、变量或指标在给定消费者上下文中的重要程度。权重不是包事实；权重表达评价目标。企业生产、个人原型、科研脚本、移动端、嵌入式和基础设施库使用不同权重。

Score 是指标归一化和加权后的模型投影。Score 不是事实本身。它只能在明确查询、上下文、硬约束、变量口径和权重之后出现。

层级 定义 例子

Dimension

评价空间中的抽象方向。

兼容性、安全、维护、文档、依赖图。

Variable

维度下可取值的观察对象。

支持的 target framework、已知漏洞数量、最近 release 年龄。

Metric

变量的具体测量口径。

target_framework_count、critical_vulnerability_count、days_since_last_release。

Weight

给定场景中某项指标的重要程度。

生产环境提高安全和可复现权重；原型环境提高相关性和文档权重。

Score

归一化和加权后的评价输出。

包级适配度排序；生态阶段能力画像。

维度可以跨生态共享，指标未必可以跨生态共享。Compatibility 可以作为共同维度；Python 的 wheel tag、.NET 的 TFM、C/C++ 的 ABI/triplet、Swift 的 platform/tools version、JVM/Kotlin 的 variant attributes 和 Go 的 module major suffix 不能合并为同一个物理量。

一个变量进入评价函数之前，需要满足四个条件：数据来源可说明，测量口径可重复，缺失值含义可解释，失真风险可标注。变量字典以 附录 A：变量字典 作为查阅表；不能满足这些条件的信号只能作为提示或人工复核入口。

15. 包级评价

包级评价回答一个问题：某个候选包在给定查询和消费者上下文中是否适合引入。它不生成脱离上下文的全局包排名。

包级评价函数可写作：

Score_package(package, query, consumer_context) -> ranked suitability

package 是候选包。query 是消费者功能意图。consumer_context 包括语言、运行时、目标平台、许可证策略、安全阈值、生产或原型场景、组织规则、性能要求和维护约束。输出是可解释排序或适配度画像。

包级评价至少包含三层。

15.1. 硬约束

硬约束决定候选包是否进入主排序。许可证禁止、目标平台不支持、被注册表或公告标记为恶意、组织策略禁止来源、目标运行时不兼容，都不能被下载量、Star 或文档质量抵消。

Feasible(package, context)
  = license_allowed
  * platform_supported
  * runtime_supported
  * security_floor_passed
  * registry_policy_allowed

这个表达式只说明硬约束的门控关系。它不要求所有实现都使用乘法；它要求不可抵消风险保持不可抵消。

15.2. 相关性

相关性衡量候选包是否回应查询意图。相关性绑定 query，不是包的全局质量。

相关性证据可以来自 description、README、keywords、classifiers、API symbols、examples、documentation headings、package categories 和 ecosystem-specific tags。与 OAuth client 查询无关的 JSON parser 不应因为下载量高而进入前列。

15.3. 质量与信任画像

进入主排序后，包级评价可以形成文档、依赖图、维护、兼容、安全、采用度和可复现画像。画像分量可以被排序模型使用，但它们不应吞掉硬约束，也不应互相冒充。

Suitability(package, query, context)
  = Feasible(package, context)
    gate {
      relevance(query, package),
      documentation_fit(package, context),
      dependency_health(package, context),
      compatibility_fit(package, context),
      maintenance_state(package, context),
      security_governance_state(package, context),
      adoption_signal(package, context)
    }

这个表达式表示包级评价先经过硬约束门控，再生成可解释画像。具体实现可以使用加权、门控、分段函数或规则系统，但输出必须说明排序原因，并保留哪些分量不能抵消其他分量。

分量 回答的问题 不能推出

相关性

包是否回应当前查询意图。

包适合所有场景。

文档/API

消费者能否理解包的公共表面。

代码无漏洞。

依赖图

依赖重量、深度和风险面如何。

功能更好。

兼容性

包是否适合目标运行环境。

许可证可用。

维护状态

包是否仍能响应环境变化。

当前版本无漏洞。

安全治理

漏洞、发布身份、完整性和治理状态是否可观察。

包一定无恶意。

采用信号

生态中是否有使用和经验反馈。

生产可信。

包级评价的输出应是可解释排序。消费者需要知道候选包为什么进入或退出结果，而不是只看到一个无来源总分。

16. 生态级评价

生态级评价回答另一个问题：某个语言或构建生态在某个生命周期阶段是否提供足够机制。它不评价单个包是否适合当前项目。

生态级评价函数可写作：

Score_ecosystem(ecosystem, lifecycle_stage, criterion_set) -> capability profile

ecosystem 是语言或构建生态，例如 JS/TS、Rust、Python、Go、JVM/Kotlin、.NET、C/C++ 或 Swift。lifecycle_stage 是 Authoring、Declaration、Publication、Indexing、Discovery、Assessment、Resolution、Realization 或 Maintenance。criterion_set 是评价标准集合，例如元数据能力、解析能力、可复现能力、安全治理、文档投影或跨平台兼容。

生态级评价输出 capability profile，而不是单一排名。一个生态可能在 resolver 和 lockfile 上强，在 discovery metadata 上弱；也可能在 provenance 上强，在二进制兼容矩阵上复杂。

生命周期阶段 生态级评价问题 示例机制

Declaration

生态是否提供足够 Manifest 表达身份、依赖、平台和构建约束。

package.json、Cargo.toml、pyproject.toml、go.mod、POM、.nuspec。

Indexing

生态是否提供可解析、可搜索、可审计的数据视图。

Cargo index、PyPI Simple API、NuGet V3 API、Maven metadata、Go proxy。

Discovery

生态是否提供文档、分类、API、图谱、安全和维护信号。

docs.rs、pkg.go.dev、Swift Package Index、NuGet.org、Maven Central Search。

Resolution

生态是否提供明确 resolver 规则和冲突解释。

Go MVS、Cargo resolver、Gradle variant-aware resolution、NuGet dependency resolution。

Realization

生态是否支持构件获取、校验、缓存、构建和目标环境落地。

pnpm store、Cargo build、wheel selection、Conan package_id、vcpkg binary caching。

Maintenance

生态是否支持升级、安全公告、弃用、撤回、锁更新和治理状态。

npm audit、NuGet audit、OSV、yanking、deprecation、trusted publishing。

生态级评价必须保留领域事实。Go 的 Manifest 描述性字段少，不等于 Go 缺少发现机制；pkg.go.dev、module path、checksum database 和 MVS 构成另一套机制。C/C++ 的复杂性不等于机制落后；ABI、compiler、runtime、triplet、build type 和 linking 是该生态的领域事实。

生态级评价的目标是能力画像：某生态在哪些生命周期阶段提供了强机制，在哪些阶段依赖第三方表面，在哪些变量上缺少可比较口径。

Part V: 主流生态对照

主流语言生态共享包复用问题，但使用不同 Manifest、Registry / Index、Discovery Surface、Resolver、Lockfile / Reproducibility、Artifact / Compatibility 与 Security / Governance 机制。生态对照的任务是标出事实表和边界，而不是生成工具排行榜；横向速查见 附录 B：生态矩阵。

17. JS/TS 与 Rust

JS/TS 和 Rust 都有可识别的 Manifest、Registry、Resolver 和 Lockfile 表面，但二者生态形态不同。JS/TS 的规模、工具分叉和供应链风险更突出；Rust 的 Cargo、crates.io、Cargo.lock 和 docs.rs 链路更集中。

17.1. JS/TS

JS/TS 的核心 Manifest 是 package.json。它承载 name、version、description、keywords、files、main、exports、bin、scripts、dependencies、devDependencies、peerDependencies、optionalDependencies、engines、os、cpu 等字段。npm registry 保存包 metadata 和 tarball；npm CLI、pnpm、Yarn、Bun 和 Deno/npm compatibility 层会以不同方式消费同一 Manifest。参见 npm package.json。

JS/TS 的 Discovery Surface 包括 npmjs.com、npm search、README、keywords、download counts、dependents、last published date、deprecated state、provenance badge、JSR package page、JSR score 和第三方图谱。JSR 与 npm 相邻，但它强调 TypeScript、ESM、自动文档、score、scope 权限和 npm compatibility。JSR score 是 JSR 自身的发现和质量投影，不能直接等同 npm 下载量。参见 JSR Docs 与 JSR package scoring。

JS/TS 的 Management 不能被单个工具代表。npm 使用 package-lock.json 和传统 node_modules tree；pnpm 使用 content-addressable store、hard link 和 symlink 结构；Yarn 可使用 Plug’n’Play、immutable install、hardened mode 和 cache 校验。Yarn security 文档还给出几个会影响风险建模的工具行为：yarn install 默认不运行 audit，Yarn 4.14 起默认不运行 postinstall，Yarn 4.12 引入的 npmMinimalAgeGate 默认要求新包发布至少 1 天后再安装，hardened mode 在公开 GitHub 仓库 pull request 场景中默认启用并检查 lockfile 解析。统一模型需要记录 resolver family、install layout、lockfile source、checksum、postinstall policy、peer dependency 处理和 script 风险。参见 npm package-lock、pnpm store、Yarn Plug’n’Play 与 Yarn security。

JS/TS 可进入统一模型的变量包括 package identity、scope、exports、dependencies 类型、peer dependency 状态、lockfile integrity、tarball integrity、trusted publishing、provenance、postinstall 策略、age gate、hardened mode、download windows、dependents 和 score badges。

不可直接比较的字段包括不同工具的安装布局、不同 registry 的 score 口径、npm download count 与 JSR score、peer dependency 风险和 postinstall 风险。它们需要保留工具和来源。

17.2. Rust

Rust 的核心 Manifest 是 Cargo.toml。它声明 package metadata、dependencies、dev-dependencies、build-dependencies、features、targets、workspace 和 registry 相关字段。Cargo resolver 根据版本 requirement 和特性约束选择版本，并把结果写入 Cargo.lock。参见 Cargo manifest 与 Cargo resolver。

crates.io 是默认 Registry。Cargo registry index 为解析器提供可用 crate 版本、checksum 和下载信息；.crate 文件是主要 Artifact。docs.rs 为发布到 crates.io 的库构建文档，形成重要 Discovery 和 API projection。lib.rs、RustSec 和 cargo-audit 是生态补充表面，不是 Cargo 内建机制。参见 Cargo registries、Cargo registry index 与 docs.rs about。

Rust 的 Manifest、Registry、Resolver、Lockfile、Artifact 和 Documentation 边界较集中。Cargo Book 明确区分 Cargo.toml 与 Cargo.lock：前者表达 broad dependencies，后者记录 exact dependency information。

Rust 可进入统一模型的变量包括 crate name、version、features、dependencies、target-specific dependencies、Cargo.lock exact graph、checksum、docs.rs build status、repository、license、RustSec advisory、reverse dependencies 和 yanked version。

不可直接比较的字段包括 crates.io download count、docs.rs build status、lib.rs ranking、RustSec 覆盖范围和 feature-expanded dependency weight。Rust feature 使“依赖重量”必须按 feature 配置计算。

对象 JS/TS Rust

Manifest

package.json

Cargo.toml

Registry / Index

npm registry、JSR

crates.io、Cargo registry index

Resolver / Lock

npm、pnpm、Yarn lockfile 与工具特定 resolver

Cargo resolver、Cargo.lock

Artifact

npm tarball、JSR modules

.crate

Discovery

npmjs.com、JSR score、README、downloads

crates.io、docs.rs、lib.rs

Security

npm audit、provenance、trusted publishing、Yarn hardened mode

RustSec、cargo-audit、crates.io trusted publishing

18. Python 与 Go

Python 和 Go 展示两种差异很大的复用模型。Python 围绕 distribution package、wheel、metadata、index 和 resolver 工作；Go 围绕 module path、VCS、module proxy、checksum database 和 Minimal Version Selection 工作。

18.1. Python

Python 的复用对象是 distribution package，不等于 import package。pyproject.toml 的 [build-system] 和 [project] 声明构建后端、name、version、description、readme、requires-python、dependencies、optional-dependencies、classifiers、keywords、URLs 和 license 等字段。构建后形成 sdist 或 wheel，并上传到 PyPI 或兼容 Simple Repository API 的索引。参见 PyPA pyproject.toml 与 PyPA Core Metadata。

Python 的 Index 需要处理文件级事实。Simple Repository API 暴露 project files、download URLs、hashes、requires-python、yanked state、metadata availability、upload time、size 和 provenance links。Wheel tag 表达 Python implementation、ABI 和 platform 兼容性。同一 package release 可以有多个 wheel 服务不同环境。参见 PyPI Simple Repository API 与 Python wheel format。

pip resolver 面对版本约束、environment marker、extras、Requires-Python、多索引和平台特定 wheel。uv 提供 universal resolution 和 uv.lock，可以在同一 lock 中记录跨平台或跨 Python 版本的不同选择。pylock.toml 是 PyPA 定义的可复现安装锁文件格式；uv 的原生锁文件仍是 uv.lock，并可导出为 pylock.toml、requirements 或 SBOM 等格式。Python 的可复现性可以由 pinned requirements、hash-checking、lockfile 和 index hash 共同支撑。参见 uv resolution、uv locking and syncing 与 pylock.toml specification。

Python 可进入统一模型的变量包括 normalized project name、distribution/import mapping、Requires-Python、Requires-Dist、extras、wheel tags、sdist availability、hashes、yanked state、trusted publishing、attestations、known vulnerabilities、index priority 和 dependency confusion 风险。

不可直接比较的字段包括 PyPI classifiers、wheel coverage、download counts、import name 与 distribution name 差异、动态 metadata 和多索引策略。Python 的 compatibility 不能与 Go module compatibility 合并为同一个指标。

18.2. Go

Go 的复用对象是 module 与 package path。go.mod 声明 module path、go version、require、replace、exclude 和 retract。开发者 import package path；Go toolchain 根据 module path、版本和 proxy/VCS 找到模块版本。参见 Go Modules Reference。

Go 使用 Minimal Version Selection。require 声明最低所需版本，MVS 计算 build list。Go 不把 build list 保存为传统 lockfile；go.mod 与 go.sum 共同支撑可重复构建。go.sum 记录模块内容 hash，checksum database 提供公开模块版本的全局可验证来源。

Go 的 Discovery Surface 主要来自 pkg.go.dev。它从 module proxy 和源码生成文档、符号、版本、packages、imported-by 和 vulnerability 投影。pkg.go.dev 在 2026 年发布的官方 API 仍处于 v1beta 路径，提供 package、module、versions、packages、search、symbols、imported-by 和 vulns 等 GET-only 端点；书中把它作为结构化发现数据表面，而不是 Go module 解析规则本身。Go 的描述性 Manifest 字段少，因为 module path、源码文档、semantic import versioning、checksum database 和 pkg.go.dev 共同承担身份、获取、兼容和发现职责。参见 pkg.go.dev about、pkg.go.dev API 与 Go vulnerability management。

Go 可进入统一模型的变量包括 module path、package path、go directive、require graph、direct/indirect dependency、replace/exclude/retract、major version suffix、go.sum entries、checksum database verification、pkg.go.dev documentation、imported-by 和 Go vulnerability data。

不可直接比较的字段包括 pkg.go.dev imported-by、module path 稳定性、MVS build list、checksum database 状态和源码注释质量。Go 缺少传统 classifiers 不应被直接解释为发现能力缺失。

对象 Python Go

身份

规范化 project name；distribution package

module path；package path

Manifest

pyproject.toml、Core Metadata

go.mod

Resolver

pip backtracking、uv universal resolution

Minimal Version Selection

Reproducibility

lockfile、pinned requirements、hash-checking

go.mod、go.sum、checksum database

Compatibility

wheel tag、ABI、platform、Requires-Python

module major suffix、source compatibility、toolchain

Discovery

PyPI、README、classifiers、third-party indexes

pkg.go.dev、module path、source docs

19. JVM/Kotlin 与 .NET

JVM/Kotlin 与 .NET 都面向长期运行的构件生态和企业工具链，但它们使用不同身份结构、解析规则和兼容性模型。JVM/Kotlin 以 Maven coordinates、POM、Gradle variants 和 Kotlin targets 为核心；.NET 以 NuGet package ID、.nuspec、PackageReference 和 target framework 为核心。

19.1. JVM/Kotlin

JVM 包身份通常由 Maven coordinates 表达：groupId、artifactId、version。POM 是 Maven 的 Project Object Model，既保存构建配置，也保存消费者解析传递依赖所需 metadata。Maven repository layout 把 groupId、artifactId 和 version 投影为仓库路径。参见 Maven POM 与 Maven dependency mechanism。

Maven 的 Resolution 处理 transitive dependencies、scope、dependencyManagement、exclusion、optional 和 nearest definition。Gradle 在 Maven/Ivy metadata 之外引入 configuration、attributes、capabilities、variants 和 Gradle Module Metadata。Gradle variant-aware resolution 使同一 component 可以按 usage、category、library elements、JVM version、Kotlin platform type 等属性提供不同 variants。参见 Gradle Module Metadata 与 Gradle variant-aware resolution。

Kotlin Multiplatform 把 variant 问题推到核心位置。同一 library 可能发布 JVM、JS、Native、Android、metadata publication 和 target publication。消费者在 commonMain、jvmMain、iosArm64Main 等源集中的请求不同；单一 Maven POM 难以充分表达这些 target-aware 关系。参见 Kotlin Multiplatform publishing。

JVM/Kotlin 可进入统一模型的变量包括 groupId、artifactId、version、type、classifier、POM dependencies、scope、dependencyManagement、Gradle attributes、capabilities、variants、Kotlin target、bytecode level、plugin portal id、Maven Central namespace 和 signing state。

不可直接比较的字段包括 MvnRepository Used By、Gradle variant attributes、KMP target layout、Maven Central 搜索信号、IDE dependency analyzer 输出。artifactId 不能脱离 groupId 当作全局包名。

19.2. .NET

NET 的中心包生态是 NuGet。NuGet package 由 package ID 和 exact version 指称具体包；.nupkg 是 ZIP 格式构件，包含代码、资源和 .nuspec manifest。SDK-style 项目也可以通过 MSBuild project properties 生成 NuGet metadata。参见 NuGet overview 与 NuGet .nuspec reference。

PackageReference 把 NuGet 依赖直接写入项目文件。NuGet restore 根据 package sources、项目 target framework、dependency groups、version ranges、floating versions 和 lock file 求解 dependency graph。packages.lock.json 记录 exact packages 和 content hash；locked mode 使 restore 在锁文件不匹配时失败。参见 NuGet PackageReference、NuGet dependency resolution 与 NuGet target frameworks。

NET 可进入统一模型的变量包括 package ID、version、owners、verified prefix、.nuspec metadata、PackageReference、dependency groups、TFM、RID、contentHash、packages.lock.json、vulnerability info、deprecation state、license expression 和 repository metadata。

不可直接比较的字段包括 NuGet downloads、Visual Studio package manager 展示、TFM compatibility、verified owner 和 NuGet audit severity。TFM 是 .NET 生态内的兼容性对象，不能直接等同于 Python wheel tag 或 C++ triplet。

对象 JVM/Kotlin .NET

身份

groupId、artifactId、version

package ID、version

Manifest

POM、Gradle Module Metadata

.nuspec、SDK project package properties

Resolver

Maven mediation、Gradle conflict and variant resolution

NuGet dependency resolution

Compatibility

bytecode、scope、Gradle attributes、KMP target

TFM、RID、asset selection

Lock / Reproducibility

Gradle dependency locking、Maven explicit versions and reproducible build settings

packages.lock.json、contentHash、locked mode

Security

Maven Central signatures、SCA/IDE surfaces、Gradle verification

NuGet audit、vulnerability info API

20. C/C++ 与 Swift

C/C 与 Swift 都暴露平台和工具链约束，但二者的复用对象不同。C/C 包评价必须把 ABI、compiler、runtime、build type、link mode、settings/options 和 triplet 当作一等变量；SwiftPM 以 Package.swift、products、targets、platforms、tools version 和 Package.resolved 为核心。

20.1. C/C++

C/C++ 包身份不能只用名称和版本描述。Conan 2 的 binary model 把 package_id 作为二进制包标识，并由 settings、options 和依赖版本等配置参与计算。settings 包括 OS、arch、compiler、compiler.version、compiler.libcxx、compiler.cppstd、compiler.runtime、compiler.runtime_type、build_type 等 ABI 相关条件。参见 Conan binary model。

Conan 的 recipe 通过 conanfile.py 声明 name、version、requires、tool_requires、settings、options、generators、layout 和 package_info。Profiles 聚合 settings、options、环境变量和工具依赖。Conan lockfile 捕获依赖解析结果和 revision，用于在后续版本出现后仍保持 reproducible dependencies。参见 Conan conanfile attributes 与 Conan lockfiles。

vcpkg manifest mode 使用 vcpkg.json 声明 dependencies、features、default-features、builtin-baseline、overrides、supports、version 和 port-version。vcpkg 的 baseline 为 registry 中可考虑的版本集合提供全局版本下限；override 会强制某个依赖使用指定版本并忽略其他版本约束。vcpkg registries 提供 port、baseline file 和 version database；Git registry 的 version entry 可包含 git-tree 以取回旧版本 port files。triplet 捕捉 target environment，例如 CPU、OS、compiler、runtime 和 linkage。Binary caching 影响同一解析结果是否需要本地构建。参见 vcpkg manifest mode、vcpkg.json reference、vcpkg versioning、vcpkg registries 与 vcpkg triplets。

C/C++ 可进入统一模型的变量包括 package reference、recipe revision、port-version、registry baseline、settings、options、profile、triplet、host/target dependency、compiler family/version、standard library、runtime linkage、build type、shared/static、feature set、binary cache key 和 source checksum。

不可直接比较的字段包括“是否有二进制包”、构建缓存命中率、ABI 兼容、triplet coverage、feature-expanded dependency graph 和系统包依赖。C/C++ 的复杂性来自领域事实，不是单纯管理工具缺陷。

20.2. Swift

SwiftPM 的 Manifest 是 Package.swift。它以 PackageDescription API 声明 package name、products、targets、dependencies、platforms、Swift language versions、C/C++ language standard 和 linker settings。// swift-tools-version: 指定处理 Manifest 所需的最低 Swift tools 版本和 PackageDescription API 版本。参见 Swift PackageDescription。

Swift package 的核心对象包括 package、product、target、dependency 和 supported platform。Product 是对外可见构建产物；Target 是源码和构建设置的基本单元；dependency 通常由 Git URL 或 registry scoped identity 与 version requirement 表达。Package.resolved 记录 dependency resolution 的 pin。

Swift Package Registry Service 提供 registry protocol，使 SwiftPM 可以通过 scoped identifier 获取 releases、manifest 和 source archive，并使用 checksum 校验 source archive。Swift Package Index 是第三方发现和兼容性评估表面，它从源码、Git 历史、GitHub metadata 和真实构建矩阵生成搜索、文档和兼容性信号。参见 Swift package registry proposal 与 Swift Package Index FAQ。

Swift 可进入统一模型的变量包括 package identity、repository URL、registry scope/name、SemVer release、tools version、products、product type、targets、target dependency graph、platform minimum deployment versions、Swift language version、binary target checksum、Package.resolved pin 和 SPI build compatibility。

不可直接比较的字段包括 Swift Package Index compatibility matrix、DocC build status、Apple platform deployment target、binary target availability 和 branch/revision dependency。SPI 是重要 Discovery Surface，不是 SwiftPM 的 resolver。

对象 C/C++ Swift

Manifest

conanfile.py、vcpkg.json

Package.swift

Identity

recipe/port plus version and variant variables

package identity、URL or registry scope/name

Compatibility

ABI、compiler、runtime、triplet、settings/options

platforms、tools version、products/targets

Lock / Reproducibility

Conan lockfile、vcpkg baseline/overrides

Package.resolved

Artifact

source package、binary package、binary cache entry

source archive、library/executable product、binary target

Discovery

ConanCenter、vcpkg.io、registries

Swift Package Index、registry service

21. 跨生态数据表面

跨生态数据表面聚合多个生态的包元数据、依赖图、许可证、安全公告、仓库信号和文档入口。它们能提高发现和比较能力，但不能替代各生态的发布事实源。

21.1. 官方事实源与第三方聚合面

官方事实源包括 npm registry、crates.io、PyPI、Go module proxy/checksum/pkg.go.dev、Maven Central、NuGet.org、ConanCenter、vcpkg registries 和 Swift Package Registry Service。它们保存或发布包身份、版本、构件、metadata、解析所需索引或官方文档投影。

第三方或增强发现面包括 deps.dev、Libraries.io、ecosyste.ms、lib.rs、Swift Package Index、MvnRepository 和 FuGet。它们提供搜索、分类、依赖图、反向依赖、许可证、安全公告、维护信号、API 检视和兼容性矩阵，但其字段需要保留来源和覆盖范围。

21.2. 典型数据表面

deps.dev / Open Source Insights 提供跨 npm、Maven、PyPI、Cargo、NuGet、Go、RubyGems 等生态的包、版本、依赖图、许可证、项目映射和 OSV advisory 数据。它可作为图谱和 advisory 聚合层，不是各注册表的写入事实源。参见 deps.dev Docs。

Libraries.io 覆盖多个 package manager 和源码仓库，提供 package metadata、dependencies、dependents、dependent repositories、contributors、SourceRank、stars 和 forks 等字段。其公开说明标注数据来自互联网抓取且不保证准确，因此这些字段只能作为发现提示和人工复核入口。参见 Libraries.io API 与 Libraries.io data。

ecosyste.ms 提供 packages、resolve、archives、licenses、repos、advisories、SBOM 等开放 API 族。它属于开放数据基础设施；每个端点的字段和覆盖范围需要单独审查。参见 ecosyste.ms packages。

Swift Package Index、lib.rs、MvnRepository 和 FuGet 是单生态增强面。SPI 提供 Swift 构建矩阵和 DocC 文档；lib.rs 增强 Rust 包发现；MvnRepository 聚合 Maven 坐标、版本、依赖片段和漏洞提示；FuGet 解析 NuGet 包内 XML docs 和程序集 metadata，提供 API 浏览。

pkg.go.dev 是 Go 官方包发现和文档表面。它不是第三方聚合器，但它与传统上传式 registry 不同；它从 module proxy、source 和 Go documentation pipeline 生成模块、包、符号、版本、imported-by 和漏洞投影。

GitHub Dependency Graph 是仓库视角的依赖图和 SBOM 表面。它从 manifest、lockfile 和 Dependency Submission API 构造图，显示依赖、dependents、许可证和已知漏洞。它不是各 package registry 的全量反向依赖事实源。参见 GitHub Dependency Graph。

21.3. 字段可靠性边界

跨生态字段必须保留 source 和 coverage_scope。反向依赖尤其需要来源：GitHub dependents 是 GitHub 可见公共仓库引用；MvnRepository Used By 是 Maven artifact 层观察；pkg.go.dev imported-by 是 Go package import 层；Libraries.io dependent repositories 是聚合器观察结果；deps.dev dependency graph 是解析和聚合结果。

许可证字段也需要来源。registry_declared、repository_detected、aggregator_normalized 和 advisory_or_compliance_override 可能冲突。合规判断不能自动采用第三方归一化值；冲突应显式标记。

表面 层级 主要能力 边界

deps.dev

第三方聚合与图谱

跨生态 package、version、dependencies、licenses、advisories。

不是注册表写入事实源。

Libraries.io

第三方聚合

搜索、依赖、反向依赖、SourceRank、仓库信号。

数据未验证，只能作为提示。

ecosyste.ms

开放 API 套件

packages、resolve、archives、licenses、SBOM、repos。

端点能力需逐项验证。

Swift Package Index

单生态发现增强

Swift 搜索、构建矩阵、DocC 文档。

不是 SwiftPM resolver。

MvnRepository

单生态第三方发现

坐标、版本、依赖片段、Used By、漏洞提示。

不是 Maven Central 官方事实源。

FuGet

单生态 API 浏览

NuGet package 和 API surface 浏览。

不是 NuGet.org 发布事实源。

GitHub Dependency Graph

仓库图谱

manifest/lockfile dependency graph、SBOM、alerts。

覆盖 GitHub 可见仓库语境。

Part VI: 安全与治理

安全与治理由漏洞状态、发布者身份、构建来源证明、制品完整性和注册表治理共同构成。每类信号只说明有限事实，不能互相替代。

22. 漏洞状态

Vulnerability Advisory漏洞状态描述某个 package、version、commit、version range 或 dependency graph 是否被已知安全公告覆盖。它是安全证据的一部分，不是包安全性的完整结论。

漏洞公告需要至少保留五类字段：生态、包名、受影响版本范围、修复版本范围、严重度和公告来源。OSV、GitHub Advisory Database、NVD、RustSec、Go vulnerability database、NuGet vulnerability info、npm audit advisory 和 PyPI vulnerabilities 字段都可能成为数据来源。参见 OSV schema、GitHub Advisory Database、Go vulnerability management 与 NuGet audit。

恶意包公告和普通漏洞公告需要分开。普通漏洞通常表示某些版本存在可被修复的缺陷；恶意包公告表示包或版本被判定具有有害行为。恶意状态不能被下载量、Star、provenance 或维护活跃度抵消。

withdrawn advisory、yanked release、deprecated package、retracted version 和 fixed version 也必须分开。withdrawn advisory 表示公告记录不再成立；yanked、deprecated、retracted 和 unpublish/delete 属于不同生态的治理状态族，具体解析语义必须回到原生态规则；fixed version 表示漏洞公告中的修复边界。

对象 说明 不能推出

Affected range

哪些版本或提交被公告覆盖。

所有版本都受影响。

Fixed range

哪些版本被公告标为修复。

修复版本适合当前平台和许可证策略。

Severity

公告给出的严重度。

当前项目一定可被利用。

Malware advisory

包或版本被判定为恶意。

来源证明可以抵消恶意状态。

Withdrawn advisory

公告记录被撤回。

包整体安全。

漏洞状态在不同阶段有不同作用。Discovery 阶段可显示候选包是否存在已知风险；Resolution 阶段可对具体依赖图和版本集合做审计；Maintenance 阶段可触发升级、替换、补丁或风险接受记录。

23. 发布者身份

发布者身份描述 Registry 接受谁或哪个自动化环境作为发布主体。它回答“这个版本由什么身份发布”，不回答“这个版本无漏洞”。

传统 token publishing 使用长期或较长期 token 让 CI 或人类账号发布包。token 泄漏会扩大攻击面。2FA、scoped token、granular token、organization permissions 和 publish access policy 可以降低风险，但不能消除构建脚本、源码审查和依赖替换风险。

Trusted Publishing 使用 OIDC 在 Registry 和受信 CI/CD provider 之间建立短期身份交换。npm trusted publishing 和 PyPI Trusted Publishing 都把发布能力绑定到受信自动化环境，减少在 CI 中保存长期 registry token 的需求。参见 npm trusted publishing 与 PyPI Trusted Publishers。

发布者身份有三个层级。

账号身份说明 registry 中哪个用户、组织、owner、maintainer 或 publisher 有权限发布。

自动化身份说明哪个 CI workflow、repository、environment 或 provider 获得短期发布能力。

发布策略说明包是否要求 2FA、是否允许 token publishing、是否要求 trusted publisher、是否限制传统 token。

变量 说明 评价位置

owner_count

有发布或维护权限的账号数量。

项目治理和接管风险。

publisher_identity_visible

发布身份是否对消费者可见。

Discovery 与审计。

trusted_publishing_enabled

发布是否绑定 OIDC trusted publisher。

发布身份风险。

token_publishing_allowed

传统 token 发布是否仍被允许。

凭据泄漏风险。

two_factor_required

发布或设置修改是否要求 2FA。

账号治理基线。

发布身份只能降低身份不确定性。一个包由正确身份发布，不说明代码没有漏洞；一个包有 provenance，不说明维护者没有误发布恶意或脆弱代码。

24. 构建来源与制品完整性

构建来源证明和制品完整性处理两个相邻对象。构建来源证明描述 Artifact 如何产生；制品完整性描述获取到的字节是否匹配预期。

24.1. 构建来源证明

构建来源证明记录源码位置、构建定义、外部参数、resolved dependencies、builder identity、run details 和 subject digest。SLSA provenance predicate 提供这类事实的结构化语言。SLSA Build levels 进一步区分是否有 provenance、provenance 是否由 hosted build platform 生成并签名、构建平台是否具备更强防篡改保证。参见 SLSA specification。

Sigstore 提供 keyless signing、Fulcio certificate、Rekor transparency log 和 cosign 等机制。它把身份、签名事件和透明日志连接起来，使消费者可以验证某个 Artifact 的签名和身份材料。参见 Sigstore overview。

npm provenance 和 PyPI attestations 把 Registry 发布、CI 身份、构件摘要和 attestation 材料连接到包发布流程中。它们增强可审计性，但不替代漏洞状态、代码审计和许可证判断。

24.2. 制品完整性

制品完整性处理下载内容与预期摘要、签名、checksum database 或 attestation subject digest 之间的关系。npm lockfile integrity、pnpm tarball integrity、Yarn checksum、Cargo registry index checksum、Go checksum database、NuGet contentHash、Python Simple API hashes、wheel RECORD 和 Swift binary target checksum 都属于完整性材料。

完整性证明的是字节一致性。它不能说明字节内容良性，也不能说明 API 稳定、许可证合规或目标平台可用。

对象 可说明 不可说明

Provenance

构件由什么源码、构建过程、构建平台和发布身份产生。

构件没有漏洞或恶意。

Attestation

某个主体对构件或构建事实作出的可验证声明。

声明范围之外的安全属性。

Signature

签名者或身份材料与对象之间的绑定。

签名者做出的内容判断一定正确。

Checksum

下载字节是否匹配预期摘要。

字节内容可维护或可安全执行。

Transparency log

签名事件或证明材料是否可公开审计。

事件本身代表良性行为。

评价函数应把构建来源和制品完整性列为不同变量。一个包可以有完整 checksum 但没有 provenance；也可以有 provenance 但当前版本被漏洞公告覆盖。

25. 注册表治理

注册表治理描述谁能声明名字、谁能发布版本、谁能转移所有权、谁能撤回或删除发布物，以及消费者如何观察这些状态。治理信号不是密码学证明，但会改变包的发现、求解和维护语义。

25.1. 命名空间与所有权

命名空间决定包名是否可追溯。npm scope、Maven groupId、NuGet verified prefix、PyPI project name、Conan user/channel、vcpkg registry 和 Swift registry scope/name 都以不同方式承担身份边界。命名空间可以降低混淆风险，但不自动证明包安全。

所有权变量包括 owner、maintainer、publisher、organization、team permission、name transfer policy 和 abandoned project policy。所有权变化会影响接管风险、维护连续性和消费者信任。

25.2. 撤回、弃用、删除和保留

yank、deprecate、retract、unpublish 和 delete 是不同对象。

Yanking、Deprecation、Retraction、Unpublish 和 Delete 属于同一治理状态族，但不是同一个对象。Yanking 在 PyPI、Cargo 等生态中影响默认候选选择；Deprecation 是维护者对包或版本给出的使用警告；Retraction 在 Go 等生态中通过版本声明表达不再推荐；Unpublish 或 Delete 改变历史可用性和名称复用风险。每个状态的 resolver 行为、安装行为和页面展示都必须按生态规则记录。

这些状态会影响 Discovery、Resolution 和 Maintenance。发现页应显示弃用或撤回；resolver 可能跳过 yanked release；维护流程可能触发替换或锁文件更新。

25.3. 治理变量

变量 说明 失真风险

identity_space_type

scope、groupId、prefix、project name、module path 等身份空间或身份辅助信号类型。

不同生态语义不一致。

name_transfer_policy

名称或包所有权如何转移。

政策文本与执行个案可能不同。

release_yanked

release 是否被 yanked。

并不等于 release 被删除。

package_deprecated

包或版本是否被维护者弃用。

弃用原因和替代建议质量不一。

version_retracted

版本是否被生态机制标记不推荐。

生态支持程度不同。

unpublish_or_delete_policy

registry 删除历史版本的政策、条件和限制。

删除政策受时间、依赖量和恶意状态影响。

注册表治理进入评价模型时，需要保留原生态语义。把 PyPI yanking、npm deprecation、Go retract、Cargo yanked、NuGet deprecation 和 npm unpublish 合并为一个布尔值，会破坏消费者判断。

Part VII: 评价尺度

对象、证据 和变量共同形成评价尺度。分数是模型投影，不是事实本身；评价尺度的职责是解释判断来源，不是制造无条件榜单。

26. 变量组

评价尺度使用九组变量。变量组是评价维度下的组织方式，不是最终分数；完整字段口径见 附录 A：变量字典。

变量组 对象 典型变量

身份变量

包如何被唯一定位和追溯。

ecosystem、registry、namespace、scope、groupId、package ID、module path、version、owner、publisher。

声明变量

Manifest 和作者声明提供什么机器可读事实。

description、keywords、license、dependencies、extras、features、targets、platforms、engines、repository URL。

解析变量

依赖图如何被求解。

version range、resolver family、conflict rule、MVS、backtracking、variant selection、target framework selection、lockfile presence。

构件变量

消费者实际获取或生成什么 Artifact。

tarball、wheel、crate、JAR、.nupkg、source zip、binary package、hash、signature、checksum、binary cache key。

兼容变量

包是否能在目标环境成立。

Python tag、ABI、platform、TFM、RID、triplet、settings/options、Swift platforms、KMP target、Go major suffix。

图谱变量

包在依赖网络中的位置。

direct dependencies、transitive dependencies、dependency depth、duplicate versions、reverse dependencies、source importers、important dependents。

维护变量

项目是否能响应环境变化。

last release age、release cadence、issue response、PR merge、maintainer count、bus factor、security policy。

安全变量

漏洞、发布身份、来源证明、完整性和治理状态。

known vulnerabilities、malware advisory、fixed version、trusted publishing、2FA policy、SLSA level、attestation、artifact integrity。

发现变量

消费者如何找到和理解候选包。

search fields、README、API docs、examples、type signatures、categories、downloads、stars、score badges、docs build status。

变量组之间不能互相抵消。许可证禁止、平台不兼容、恶意包公告、组织策略禁止等硬约束，不应被下载量、Star、文档质量或反向依赖数量抵消。

27. 作用域与归一化

评价作用域决定分数能回答什么问题。包级评价和生态级评价使用同一对象模型，但评价对象不同。

包级作用域绑定 package、query 和 consumer_context。没有 query，相关性变量没有意义；没有 consumer_context，许可证、平台、安全阈值和权重没有确定值。

生态级作用域绑定 ecosystem、lifecycle_stage 和 criterion_set。它评价某个生态在声明、索引、发现、求解、落地、安全或维护阶段的机制能力，不评价单个包。

归一化把不同尺度的指标投影到可组合范围。归一化必须保留来源、单位和失真风险。下载量可以取对数，但不同 registry 的统计窗口和去重规则不同；Star 可以时间衰减，但 Star 仍是注意力信号；Scorecard 可以拆分 checks，但总分不能替代安全结论。

缺失值需要分类处理。

缺失类型 含义 处理方式

生态不支持

该生态没有对应机制。

标为 not_applicable，不计为包事实缺失。

数据未公开

机制可能存在，但公开表面不可读。

标为 unknown，降低可观察性。

包未声明

Manifest 或发布元数据缺少字段。

标为 missing，进入声明完整性或治理变量。

聚合器未覆盖

第三方数据源没有该包或字段。

标为 aggregator_gap，不得当作官方缺失。

冲突数据

多个来源给出不同值。

标为 conflict，并保留各来源。

归一化不能删除语义差异。TFM、wheel tag、triplet、Swift platform 和 Gradle attributes 可以同属兼容维度，但不能归一为一个无生态语义的 platform_supported 布尔值。

28. 可比性边界

跨生态比较的目标是发现共同结构和差异边界，不是把所有字段压成同一个物理量。

28.1. 兼容性边界

Compatibility 是共同维度，但各生态指标不同。Python 的 compatibility 关心 Requires-Python、wheel tag、ABI 和 platform；.NET 关心 TFM、RID 和 package assets；C/C++ 关心 ABI、compiler、runtime、settings、options 和 triplet；Swift 关心 platforms、tools version、products、targets 和 binary checksum；JVM/Kotlin 关心 bytecode、scope、Gradle attributes 和 KMP target；Go 关心 module path、major suffix、toolchain 和 source build constraints。

这些指标都服务“目标环境可成立”这一判断，但不能合并为同一测量口径。

28.2. 反向依赖边界

Reverse dependency 的来源不同。GitHub dependents 覆盖 GitHub 可见仓库；MvnRepository Used By 覆盖 Maven artifact 层观察；pkg.go.dev imported-by 观察 Go package import；Libraries.io dependent repositories 来自聚合器抓取；crates.io reverse dependencies 是 crates.io 生态内信号。来源层级见 附录 C：资料来源图。

统一模型可以保留 reverse_signal_type 和 coverage_scope，不能只保存 dependency_count。

28.3. 许可证边界

许可证字段至少有四类来源：registry_declared、repository_detected、aggregator_normalized、compliance_override。它们可能冲突。合规判断应保留冲突，不应自动采用第三方归一化值。

28.4. 安全边界

安全分量不能互相抵消。provenance 不抵消 malware advisory；Scorecard 高分不抵消当前版本 critical vulnerability；没有公告不等于没有漏洞；2FA 不说明构建输入可审计。

28.5. 采用度边界

下载量、Star、fork、issue、dependent count 和企业案例都是采用或注意力信号。它们不直接证明功能适配、安全或维护可靠。采用度可以提升复核优先级，不能替代硬约束。

29. 读懂分数

评价输出应被读作解释材料，而不是裁决。一个分数只有在对象、查询、上下文、变量、来源和权重都明确时才有意义。

包级输出应至少包含四部分：

  • 是否通过硬约束；

  • 与查询的相关性依据；

  • 主要正向证据；

  • 主要风险、缺失和不可比较字段。

生态级输出应至少包含三部分：

  • 被评价的生命周期阶段；

  • 该阶段可观察机制；

  • 该阶段依赖第三方表面或存在口径缺口的位置。

分数不能隐藏拒绝原因。若许可证禁止、目标平台不支持、恶意包公告存在或组织策略禁止来源，输出应显示硬拒绝原因，而不是给出一个被其他变量稀释后的低分。

分数也不能隐藏不确定性。若安全公告来源不覆盖目标生态，若反向依赖只来自第三方聚合器，若下载量统计窗口未知，若许可证字段冲突，输出应保留这些状态。

输出字段 含义

decision

候选包通过、拒绝、需复核或数据不足。

hard_constraints

许可证、平台、安全底线、registry policy 等不可抵消条件。

evidence_summary

主要证据源及其来源层级。

risk_summary

漏洞、治理、维护、兼容、依赖图和来源证明风险。

missing_data

缺失字段、未知来源和聚合器覆盖缺口。

comparability_notes

哪些字段不能与其他生态直接比较。

可解释输出比单一总分更重要。总分最多是入口，解释才是消费者行动的依据。

术语表

索引入口见 索引；变量字段见 附录 A：变量字典。

Package

在某个语言或构建生态中被命名、版本化、可获取、可声明为依赖的软件复用单元。

Artifact

可下载、可缓存、可校验、可构建或可链接的具体构件。

Manifest

项目或包对机器声明自身身份、依赖、版本、平台、许可证、入口和构建约束的结构化表面。

Registry

接收、保存、分发和索引 package metadata 与 artifact 的基础设施。

Repository

保存源码或构件内容的仓库；它不必然承担注册表职责。

Index

可搜索、可解析、可用于发现或依赖求解的数据视图。

Package Discovery

消费者在引入依赖之前识别候选包、理解候选包、比较候选包并形成引入判断的机制。

Package Management

消费者项目声明、解析、获取、校验、安装、构建、锁定、升级、审计和移除依赖的机制。

Package Manager

Package Management 的工具投影，例如 npm、Cargo、pip、uv、Maven、Gradle、NuGet、Conan、vcpkg 和 SwiftPM。

Discovery Surface

面向消费者呈现候选包、文档、分类、图谱、安全状态、兼容性状态或维护信号的可见表面。

Resolver

把版本范围、依赖关系、平台约束、feature、extra、target framework、variant、lockfile 和 registry metadata 合成一致依赖图的求解器。

Lockfile

一次依赖求解结果的固化记录。

Realization

依赖解变成本地实际构件的过程。

Provenance

Artifact 从源码、构建过程、构建平台、发布身份和输入产生的来源事实。

Attestation

对 Artifact、构建过程、发布身份或安全事实的可验证声明。

Checksum

对构件字节内容的摘要校验材料，用于判断获取内容是否匹配预期。

Signature

签名者身份材料与对象之间的密码学绑定。

Transparency log

可公开审计签名事件或证明材料的日志基础设施。

Variant

同一组件在不同消费属性、平台、目标或构建条件下提供的可选构件表面。

Feature

包暴露的可选能力开关，通常会改变依赖、编译条件或公共 API。

Extra

Python 生态中用于声明可选依赖集合的机制。

Target

构建系统中的编译、链接或发布单元；在 SwiftPM 中 target 是源码和构建设置的基本单元。

Product

包对消费者暴露的构建产物；在 SwiftPM 中 product 可由一个或多个 target 组成。

Target Framework

.NET 中用于表达项目或包资产兼容范围的目标框架标识。

Runtime Identifier

.NET 中用于表达运行时平台、操作系统和架构的标识。

Triplet

vcpkg 中用于捕捉目标环境的 CPU、OS、compiler、runtime 等变量组合。

ABI

应用二进制接口；在 C/C++、Python native wheel 和平台绑定中影响二进制构件可用性。

MVS

Go 的 Minimal Version Selection 依赖解析策略。

Backtracking resolver

通过回溯搜索选择满足约束依赖图的解析器类型。

Dependency mediation

Maven 中决定传递依赖冲突版本的规则集合。

Variant-aware resolution

Gradle 根据 attributes、capabilities 和 variants 选择组件变体的解析机制。

Dependency graph

包、版本、变体和依赖边形成的图结构。

Reverse dependency

依赖当前包的其他包、模块、仓库或导入者；来源不同会改变覆盖范围。

Declared Evidence

来自 Manifest 和作者声明的证据。

Structural Evidence

来自源码、API、类型、文档注释、测试、示例和弃用标记的证据。

Graph Evidence

来自依赖图、反向依赖和生态拓扑的证据。

Operational Evidence

来自构建、平台、ABI、checksum、lockfile、binary cache 和运行环境的证据。

Social Evidence

来自下载量、Star、Fork、issue、PR、讨论和社区策展的证据。

Security and Governance Evidence

来自漏洞公告、发布身份、来源证明、制品完整性和注册表治理的证据。

Dimension

评价空间中的抽象方向，例如安全、兼容、维护、文档和依赖图。

Variable

某个维度下可取值的观察对象。

Metric

变量的具体测量口径。

Weight

某个维度、变量或指标在给定消费者上下文中的重要程度。

Score

指标归一化和加权后的模型投影；它不是事实本身。

Consumer context

消费者项目的语言、运行时、平台、许可证策略、安全阈值、组织规则和使用场景。

Hard constraint

不可被其他分量抵消的条件，例如许可证禁止、平台不兼容、恶意包公告或组织策略禁止来源。

Compatibility

包、构件或生态机制在目标语言、运行时、平台、ABI、工具链、target 或 variant 中成立的程度。

Yank

release 被标记为不应默认选择，但不必然从历史中删除。

Deprecation

维护者对包或版本给出的不推荐使用状态或消息。

Retraction

生态机制对版本不再推荐或不应使用的声明。

Unpublish

从注册表中删除已发布包或版本的治理动作。

Trusted publishing

Registry 与受信 CI/CD provider 通过 OIDC 等机制建立短期发布身份交换，减少长期 registry token 暴露。

Publisher identity

Registry 接受的发布主体，包括账号、组织、maintainer、publisher 或受信自动化环境。

Vulnerability advisory

对包、版本范围、提交范围或依赖图风险的公开安全公告。

Malware advisory

对包或版本具有恶意行为的公告；它属于硬拒绝风险。

Affected range

安全公告中被认定受影响的版本或提交范围。

Fixed range

安全公告中被认定修复风险的版本范围。

Source map

资料来源层级、用途和证据权重的分类。

Appendix A: 附录 A：变量字典

变量不是结论；变量是评价函数可以观察、记录、归一化和解释的对象。每个变量都保留评价层级、变量组、数据来源、指标口径、单位或取值、缺失值处理和失真风险。

变量 层级 变量组 数据来源 指标口径 单位/取值 缺失值处理 失真风险

ecosystem_id

package/ecosystem

身份

registry、official docs

包所属语言或构建生态。

枚举

unknown

同一包可能跨多个生态发布。

registry_id

package/version

身份

registry metadata、source map

发布事实源或主要索引源。

枚举/URL

unknown

镜像、私有源和第三方索引可能混淆事实源。

package_identity_tuple

package

身份

manifest、registry metadata

生态定义的包身份组合。

结构值

missing

不同生态身份结构不同，不能只保留 name。

identity_space_type

package/ecosystem

身份

manifest、registry policy

scope、groupId、project name、module path、registry scope、verified prefix 等身份空间或身份辅助信号类型。

枚举

not_applicable

这些对象不全是真命名空间；verified prefix 等字段是身份辅助信号，不是安全证明。

identity_space_value

package

身份

manifest、registry metadata

包所在 scope、groupId、project name、module path root、registry scope、verified prefix 等具体值。

字符串

missing

组织名、域名和源码仓库所有权可能不一致。

version_identifier

package/version

身份

registry metadata、manifest、VCS tag

版本号、release tag、revision 或生态等价版本状态。

字符串

missing

SemVer、calendar version、revision pin 和 port-version 语义不同。

source_repository_linked

package

声明

manifest、registry metadata

是否声明源码仓库位置。

布尔/URL

missing

链接可能过期、迁移或被接管。

issue_tracker_linked

package

声明

manifest、registry metadata

是否声明 issue、bugs 或支持入口。

布尔/URL

missing

入口存在不说明响应能力。

manifest_present

package

声明

source repository、registry metadata

是否存在生态认可的 Manifest。

布尔

missing

动态构建可能隐藏真实 metadata 来源。

manifest_staticness

package/ecosystem

声明

official docs、build backend、manifest

Manifest metadata 是否可静态读取。

static/dynamic/mixed

unknown

动态 metadata 会延迟索引和解析判断。

description_present

package

声明/发现

manifest、registry metadata

是否有机器可读 description。

布尔

missing

描述可能过期、营销化或与 API 不一致。

keyword_or_classifier_count

package

声明/发现

manifest、registry metadata

关键词、classifier、category、topic 数量。

计数

0

不同生态标签受控程度不同。

declared_license

package/version

声明

manifest、registry metadata

包声明的许可证表达。

SPDX/文本

missing

可能与源码 LICENSE、构件内容或聚合器识别冲突。

license_source_type

package/version

声明/治理

registry、repository、aggregator、compliance DB

许可证字段来源层级。

枚举

unknown

自动归一化可能改变法律语义。

license_conflict_present

package/version

治理

多个许可证来源

不同来源是否给出冲突许可证。

布尔

unknown

冲突本身需要人工合规判断。

dependency_classes_declared

package

声明/图谱

manifest

声明了哪些依赖类别。

集合

missing

dependencies、dev、peer、optional、extras、features、tool_requires 等语义不同。

direct_dependency_count

package/version/context

图谱

manifest、registry metadata、resolver output

当前上下文的直接依赖数量。

计数

unknown

dependency class 和 feature/platform 条件不能无差别合并。

transitive_dependency_count

package/version/context

图谱

resolved graph

解析后的传递依赖数量。

计数

unknown

依赖于 resolver、platform、feature、extras、target。

dependency_depth

package/version/context

图谱

resolved graph

解析依赖图最大深度。

计数

unknown

深度受 optional、dev、test、feature 边界影响。

duplicate_version_count

project/context

图谱

resolved graph、lockfile

同一 logical package 的多版本重复数量。

计数

unknown

部分生态允许多版本共存，风险语义不同。

reverse_dependency_signal

package

图谱

registry、GitHub、third-party aggregator

按来源记录被依赖信号。

结构值

aggregator_gap

GitHub dependents、Used By、imported-by、dependent repositories 覆盖不同。

important_dependent_present

package

图谱

deps.dev、registry、manual curation

按显式策展规则记录是否被高影响项目依赖。

布尔/列表

unknown

必须同时记录 curation policy；不能作为未说明来源的客观事实字段。

resolver_family

ecosystem/tool

解析

official docs

解析算法或规则族。

枚举

unknown

同一生态可能有多个工具和配置。

conflict_resolution_rule

ecosystem/tool

解析

official docs

版本冲突、nearest-wins、MVS、highest/lowest、variant 选择等规则。

文本/枚举

unknown

实现细节和错误消息可能随工具版本变化。

version_range_semantics

ecosystem/tool

解析

official docs、manifest spec

版本范围语法和默认解释。

文本/枚举

unknown

同一符号在生态间语义不同。

feature_resolution_model

ecosystem/tool

解析

official docs、manifest

feature、extra、optional、target-specific dependency 如何影响解。

文本/枚举

not_applicable

feature-expanded graph 可能与默认 graph 差异很大。

variant_selection_model

ecosystem/tool

解析/兼容

official docs、metadata

Gradle variants、NuGet assets、Swift targets、Conan package_id 等如何选择。

文本/枚举

not_applicable

变体选择失败常被误读为包质量问题。

lockfile_present

project

解析

consumer project

消费者项目是否存在 lockfile 或等价锁定材料。

布尔

not_applicable

Go 等生态不使用传统 lockfile。

lockfile_granularity

project/tool

解析/构件

lockfile、official docs

锁定对象粒度：版本、hash、source、artifact、variant、platform。

集合

unknown

锁定粒度不足会削弱审计和复现。

lockfile_platform_scope

project/tool

解析/兼容

lockfile、official docs

锁文件是否覆盖单平台、多平台或 universal resolution。

枚举

unknown

跨平台锁可能隐藏平台条件差异。

artifact_type

package/version

构件

registry、index、file metadata

tarball、wheel、crate、JAR、nupkg、module zip、binary package 等。

枚举

unknown

源码构件和二进制构件风险不同。

artifact_hash_present

package/version/artifact

构件/安全

registry、lockfile、index

构件是否有 hash、checksum 或 contentHash。

布尔

missing

hash 说明字节一致，不说明良性。

artifact_signature_present

package/version/artifact

构件/安全

registry、signature endpoint、transparency log

构件是否有签名材料。

布尔

unknown

签名身份、信任根和验证策略不同。

checksum_authority

package/version/artifact

构件/安全

registry、checksum database、lockfile

checksum 来源：registry、lockfile、global DB、attestation subject。

枚举

unknown

不同来源的篡改模型不同。

binary_artifact_available

package/version/context

构件/兼容

registry、package manager cache、artifact listing

目标环境是否有可用二进制构件。

布尔

unknown

构建矩阵只能说明实测构建状态；无二进制不等于不可用，可能需本地构建。

binary_cache_key

package/version/context

构件

Conan、vcpkg、CI cache

二进制缓存命中所需 key 或配置组合。

结构值

not_applicable

缓存命中受配置、远端和构建选项影响。

python_requires

package/version

兼容

Core Metadata、Simple API

Requires-Python 范围。

版本范围

missing

只说明 Python 版本，不说明 ABI/platform wheel 可用。

python_wheel_tag_coverage

package/version

兼容

PyPI files、Simple API

该 release 覆盖的 Python tag、ABI tag、platform tag。

集合

unknown

覆盖目标平台之外的 wheel 不产生可用性。

python_sdist_available

package/version

构件/兼容

PyPI files、Simple API

是否提供 source distribution。

布尔

unknown

sdist 存在不说明目标环境可构建。

go_major_suffix_consistent

package/module

兼容/身份

go.mod、module path

module path 与 v2+ major version 后缀是否一致。

布尔

not_applicable

只适用于 Go module 语义。

go_checksum_verified

package/version

构件/安全

go.sum、checksum database

模块内容是否可由 checksum database 或 go.sum 验证。

布尔

unknown

私有模块和 GOPRIVATE 改变验证路径。

jvm_bytecode_target

package/version/artifact

兼容

POM、Gradle metadata、class files

JVM bytecode 或 target compatibility。

版本

unknown

字节码版本不覆盖所有运行时依赖。

gradle_variant_attribute_set

package/version

兼容/解析

Gradle Module Metadata

发布 variants 的 attribute 集合。

集合

not_applicable

消费者属性匹配规则需要同时记录。

kmp_target_set

package/version

兼容

Kotlin metadata、Gradle metadata

Kotlin Multiplatform targets 覆盖范围。

集合

not_applicable

target 存在不说明每个 target 构建质量一致。

nuget_tfm_coverage

package/version

兼容

nuspec、nupkg assets、NuGet metadata

包覆盖的 Target Framework Moniker 集合。

集合

unknown

TFM 兼容还受 asset selection 和 dependency group 影响。

nuget_rid_asset_present

package/version/context

兼容/构件

nupkg runtimes assets

目标 Runtime Identifier 是否有资产。

布尔

not_applicable

RID fallback 规则可能改变结果。

conan_package_id_inputs

package/version/context

兼容/构件

Conan recipe、profile、lockfile

参与 package_id 的 settings、options、requires。

集合

not_applicable

配置缺失会导致二进制身份不可复现。

vcpkg_triplet

package/version/context

兼容

vcpkg triplet、manifest

目标 CPU、OS、compiler、runtime、linkage 等组合。

结构值

not_applicable

自定义 triplet 会降低跨项目可比性。

swift_tools_version

package/version

兼容

Package.swift

swift-tools-version 声明。

版本

unknown

tools version 不等同于所有平台支持。

swift_platforms_declared

package/version

兼容

Package.swift

声明的 platforms 与最低 deployment version。

集合

missing

未声明时 SwiftPM 使用默认规则。

swift_binary_target_checksum

package/version/artifact

构件/安全

Package.swift、binary target metadata

binary target checksum 是否存在并匹配。

布尔

not_applicable

checksum 不说明二进制良性。

documentation_surface_present

package

发现

docs site、registry、source docs

是否存在可读文档或 API 投影。

布尔

missing

文档存在不等于准确或覆盖当前版本。

api_symbol_index_present

package/version

发现/结构

docs.rs、pkg.go.dev、FuGet、DocC、IDE index

是否有可查询 API 符号索引。

布尔

unknown

生成失败或条件编译会造成缺口。

example_coverage_signal

package/version

发现/结构

README、docs、tests、examples directory

示例是否覆盖主要入口或常见用法。

布尔/计数

unknown

示例可读不说明可运行。

docs_build_status

package/version

发现/运行

docs.rs、Swift Package Index、CI

文档构建是否成功。

pass/fail/unknown

unknown

文档构建成功不说明运行构建成功。

download_signal

package

发现/社会

registry、aggregator

下载量及统计窗口。

计数+窗口

unknown

受 CI、镜像、传递依赖和历史包袱污染。

star_signal

package/repository

社会

source repository

仓库 Star 数及采集时间。

计数

unknown

Star 是注意力，不是适配、安全或维护证明。

fork_signal

package/repository

社会

source repository

仓库 fork 数及采集时间。

计数

unknown

fork 可能是镜像、实验或废弃分叉。

issue_response_median

package/repository

维护

source repository issue tracker

repository-derived metric；指定时间窗内 issue 首次响应时间中位数。

时长

unknown

关闭策略、机器人和外部支持渠道会影响口径。

pr_merge_rate

package/repository

维护

source repository PRs

repository-derived metric；指定时间窗内 PR 合并比例。

比例

unknown

项目可能不接受外部 PR 或使用邮件列表。

days_since_last_release

package

维护

registry、source repository

当前日期减最新 release 日期。

天

unknown

稳定小包可能长期无需 release。

release_cadence

package

维护

registry、source repository

指定时间窗内 release 频率。

次数/时间窗

unknown

高频 release 不一定代表质量更高。

maintainer_count

package

维护/治理

registry、source repository

可观察维护者数量。

计数

unknown

权限和实际维护劳动不一致。

bus_factor_signal

package

维护

repository contribution data

repository-derived metric；贡献集中度或关键维护者数量。

计数/比例

unknown

只看 commit 不能覆盖发布权限和安全响应。

owner_count

package

治理

registry、source repository permissions

有维护或发布权限的可观察账号数量。

计数

unknown

权限细节可能不可见；账号数量不等于实际维护能力。

publisher_identity_visible

package/version

安全/治理

registry metadata、attestation、publish log

发布身份是否对消费者或审计者可见。

布尔

unknown

身份可见不说明发布内容良性。

security_policy_present

package/repository

安全/治理

source repository、registry metadata

是否有 SECURITY policy 或漏洞报告入口。

布尔

missing

政策存在不说明响应质量。

known_vulnerability_count

package/version

安全

OSV、GHSA、ecosystem DB

当前包版本本身被公告覆盖的漏洞数量。

计数

unknown

没有公告不等于没有漏洞。

highest_vulnerability_severity

package/version

安全

OSV、GHSA、NVD、ecosystem DB

当前包版本本身已知漏洞的最高严重度。

枚举

unknown

严重度不等同于当前项目可达性。

resolved_graph_vulnerability_count

project/context

安全

resolved graph、OSV、GHSA、ecosystem DB

解析依赖图中被公告覆盖的漏洞数量。

计数

unknown

传递依赖风险受 resolver、platform、feature 和 lockfile 影响。

resolved_graph_highest_vulnerability_severity

project/context

安全

resolved graph、OSV、GHSA、NVD、ecosystem DB

解析依赖图中已知漏洞的最高严重度。

枚举

unknown

严重度不等同于当前项目可达性。

vulnerability_scope

package/version/project

安全

advisory DB、resolved graph、source map

漏洞变量作用域：package-version、resolved-graph、source commit 或 repository。

枚举

unknown

不同作用域不能合并为同一风险计数。

malware_advisory_present

package/version

安全

registry advisory、GHSA、OSV

是否存在恶意包公告。

布尔

unknown

恶意状态不能被其他分量抵消。

fixed_version_available

package/version

安全/维护

advisory DB、registry

已知漏洞是否存在修复版本。

布尔/版本

unknown

修复版本可能不兼容当前约束。

trusted_publishing_enabled

package

安全/治理

registry metadata、trusted publisher config

发布是否绑定 OIDC trusted publisher。

布尔

unknown

只降低长期 token 风险，不说明代码良性。

two_factor_required

package/registry

安全/治理

registry policy、package settings

发布或高风险操作是否要求 2FA。

布尔

unknown

2FA 不审查源码或构建输入。

token_publishing_allowed

package/registry

安全/治理

registry policy、package settings

是否仍允许传统 token 发布。

布尔

unknown

token 权限粒度和轮换策略也影响风险。

provenance_available

package/version/artifact

安全

registry、attestation endpoint

是否存在 provenance 或 attestation。

布尔

unknown

证明粒度可能是包、版本、文件或构建。

slsa_claimed_level

package/version/artifact

安全

attestation、project docs

项目、构件或 attestation 声称的 SLSA level。

枚举

unknown

声明不等于消费者已验证满足。

slsa_verified_level

package/version/artifact

安全

consumer verification、attestation verification log

消费者验证后接受的 SLSA level。

枚举

unknown

验证策略、信任根和构建身份匹配规则会影响结果。

sigstore_material_present

package/version/artifact

安全

signature、certificate、Rekor log

是否存在 Sigstore 签名、证书或透明日志材料。

布尔

unknown

验证策略和身份匹配仍需定义。

scorecard_check_values

package/repository

安全/治理

OpenSSF Scorecard

各项 check 的原始值或分数。

结构值

unknown

总分不能替代具体安全结论。

release_yanked

package/version

治理

registry metadata

release 是否被 yanked。

布尔

not_applicable

yank 不等于删除，显式 pin 语义不同。

package_deprecated

package/version

治理

registry metadata

包或版本是否被维护者弃用。

布尔/消息

unknown

弃用原因和替代建议质量不一。

version_retracted

package/version

治理

manifest、registry metadata

版本是否被生态机制标记不推荐。

布尔

not_applicable

不同生态支持程度不同。

unpublish_or_delete_policy

ecosystem/registry

治理

registry policy

registry 对删除历史版本的规则。

文本/枚举

unknown

政策受时间、依赖量和恶意状态影响。

name_transfer_policy

ecosystem/registry

治理

registry policy

包名或所有权如何转移。

文本/枚举

unknown

执行个案可能偏离政策文本。

search_field_set

ecosystem/surface

发现

registry search docs、surface observation

搜索使用哪些字段：name、description、keywords、README、API symbols。

集合

unknown

搜索排序细节通常不公开。

surface_badge_set

package/surface

发现

registry page、third-party surface

页面显示的 score、badge、build、docs、安全或 provenance 标签集合。

集合

none

badge 来源和计算口径必须分开。

third_party_surface_count

package/ecosystem

发现

source map、known surfaces

可观察第三方发现表面数量。

计数

0

数量不说明准确性或覆盖率。

source_coverage_scope

variable/source

证据

source documentation

数据源覆盖范围：registry、repository、package import、artifact、public GitHub 等。

文本/枚举

unknown

覆盖范围不明时变量不得进入强排序。

data_freshness_age

variable/source

证据

API metadata、crawl timestamp

数据从采集或更新时间到评价时点的时间差。

时长

unknown

旧数据可能误导维护、安全和下载判断。

source_conflict_present

variable/source-set

证据

多个来源

同一字段是否存在来源冲突。

布尔

false/unknown

冲突需要暴露，不应自动吞掉。

Appendix B: 附录 B：生态矩阵

生态矩阵横向呈现主流生态的 Manifest、Registry、Index、Resolver、Lockfile、Artifact、Compatibility 和 Security Surface。矩阵提供查阅入口；具体边界以生态章节为准。

生态 Manifest Registry / Index Resolver Lock / Reproducibility Artifact Compatibility

JS/TS

package.json

npm registry、JSR

npm、pnpm、Yarn 等工具

package-lock.json、pnpm-lock.yaml、yarn.lock

tarball、JSR module files

engines、os/cpu、exports、peer dependencies

Rust

Cargo.toml

crates.io、Cargo registry index

Cargo resolver

Cargo.lock

.crate

target、features、rust-version

Python

pyproject.toml、Core Metadata

PyPI、Simple Repository API

pip、uv

uv.lock、requirements pins/hashes、pylock.toml

sdist、wheel

Requires-Python、wheel tag、ABI、platform

Go

go.mod

module proxy、checksum database、pkg.go.dev

Minimal Version Selection

go.mod、go.sum

module zip、source

module path、major suffix、build tags、toolchain

JVM/Kotlin

POM、Gradle Module Metadata

Maven Central、Gradle Plugin Portal

Maven mediation、Gradle variant-aware resolution

Gradle dependency locking、explicit versions

JAR、POM、metadata、sources、javadoc

bytecode、scope、attributes、KMP target

.NET

.nuspec、SDK project properties

NuGet.org、NuGet V3 API

NuGet dependency resolution

packages.lock.json

.nupkg

TFM、RID、asset selection

C/C++

conanfile.py、vcpkg.json

Conan remotes、vcpkg registries

Conan、vcpkg versioning

Conan lockfile、vcpkg baseline/overrides

source package、binary package、binary cache

ABI、compiler、runtime、settings/options、triplet

Swift

Package.swift

VCS、Swift Package Registry Service

SwiftPM

Package.resolved

source archive、library/executable product、binary target

platforms、tools version、products、targets
生态 Discovery Surface Security / Governance 第三方或增强面 不可直接比较字段

JS/TS

npmjs.com、npm search、JSR package page、README、downloads、dependents

npm audit、trusted publishing、provenance、2FA、deprecation、unpublish policy

JSR scoring（JSR 官方增强发现信号）、Libraries.io、deps.dev、GitHub Dependency Graph

npm downloads、JSR score、peer dependency risk、postinstall risk

Rust

crates.io、docs.rs、README、reverse dependencies

RustSec、cargo-audit、yanked versions、checksum in registry index

lib.rs、deps.dev

docs.rs build status、lib.rs rank、feature-expanded dependency weight

Python

PyPI project page、classifiers、README、Simple API file metadata

PyPI trusted publishing、digital attestations、yanked files、OSV/GHSA

deps.dev、Libraries.io、GitHub Dependency Graph

distribution/import mapping、wheel coverage、dynamic metadata、multi-index priority

Go

pkg.go.dev search、documentation、symbols、imported-by

checksum database、Go vulnerability database、retract directive

deps.dev、GitHub Dependency Graph

pkg.go.dev imported-by、MVS build list、module path stability

JVM/Kotlin

Maven Central search、Gradle Plugin Portal、artifact pages

signatures、repository policies、dependency verification、advisory surfaces

MvnRepository、deps.dev、Libraries.io

MvnRepository Used By、Gradle attributes、KMP target layout

.NET

NuGet.org、Visual Studio/Rider package UI、README and metadata

NuGet audit、verified prefix、deprecation, contentHash

FuGet、deps.dev、Libraries.io

TFM compatibility、verified owner、NuGet downloads、FuGet API view

C/C++

ConanCenter pages、vcpkg package pages、registry metadata

source checksum、lockfiles、binary package identity、registry baseline

GitHub Dependency Graph、ecosyste.ms

ABI compatibility、triplet coverage、binary cache hit, feature/options graph

Swift

Swift Package Index、registry endpoints、DocC documentation

source archive checksum、binary target checksum、Package.resolved

Swift Package Index compatibility matrix

SPI build matrix、Apple platform target, branch/revision dependency

Appendix C: 附录 C：资料来源图

资料来源图区分官方规范、官方注册表、第三方聚合面、观察性页面和安全公告数据库。它控制 证据与度量 的来源权重：同一字段来自不同来源时，不能自动合并为一个事实。

来源层级 用途 例子 可支撑的判断

官方规范或官方文档

定义生态对象、文件格式、解析规则和工具行为。

npm docs、Cargo Book、PyPA specs、Go ref/mod、Maven docs、Gradle docs、NuGet docs、Conan docs、vcpkg docs、Swift PackageDescription。

Manifest 字段语义、resolver 规则、lockfile 语义、artifact 格式、兼容性模型。

官方注册表或官方服务

保存发布事实、元数据、构件、文档或漏洞投影。

npm registry、crates.io、PyPI、Maven Central、NuGet.org、pkg.go.dev、docs.rs。

包身份、版本状态、发布物、文档构建、下载或官方页面可见事实。

安全基础设施

提供漏洞、来源证明、签名、透明日志或项目治理 checks。

OSV、GitHub Advisory Database、OpenSSF Scorecard、SLSA、Sigstore。

已知漏洞、advisory 版本范围、构建来源证明、签名和治理检查。

第三方聚合器

聚合跨生态包元数据、图谱、许可证和维护信号。

deps.dev、Libraries.io、ecosyste.ms。

跨生态图谱、聚合许可证、反向依赖提示、安全公告汇总、仓库信号。

第三方发现增强面

提供单生态搜索、API 检视、构建矩阵或聚合页面。

lib.rs、Swift Package Index、MvnRepository、FuGet。

发现排序、兼容性矩阵、API 浏览、第三方 Used By 或 ranking。

观察性页面

缺少正式接口文档时的公开页面观察。

具体包页面、搜索结果页面、排行榜页面。

页面上对消费者可见的投影事实；不能单独支撑规范语义。
字段类型 优先来源 冲突处理

Manifest 字段语义

官方规范或官方文档

第三方解释只能作为辅助，不替代规范语义。

包发布事实

官方注册表或官方服务

镜像、聚合器和观察性页面必须标明来源层级。

依赖解析规则

官方工具文档、规范、实现文档

第三方文章不能替代 resolver 规则来源。

反向依赖

生态官方 graph 或明确覆盖范围的聚合器

保留 source_coverage_scope，不合并为单一 dependency_count。

许可证

registry declared、repository file、aggregator normalized、compliance override 分开记录

冲突时标为 conflict，不自动选择一个字段。

漏洞公告

OSV、GHSA、生态官方漏洞数据库、registry audit 数据

保留 affected range、fixed range、withdrawn state 和 source。

来源证明

registry attestation、SLSA provenance、Sigstore/Rekor material

证明来源关系，不替代漏洞、安全和许可证判断。

下载、Star、Fork

registry、repository 或聚合器原始字段

保留统计窗口、采集时间和数据源。

第三方来源必须标明聚合或观察表面身份。第三方字段不能自动替代官方发布事实。

Appendix D: 附录 D：结构词表

本书的结构化标记只声明正文实际使用的关系谓词。标题身份由章节位置、标题文本和正文定义承担；本书不使用 role 受控词表。

谓词 使用位置 含义

depends-on

xref 边

当前判断、阶段、证据或变量口径依赖目标章节中定义的对象、规则或查阅表。

illustrates

xref 边

目标结构为当前章节提供横向示例、矩阵或查阅性展开。

未列入本表的关系词不属于本书的受控谓词。新增关系词需要先进入本表，再进入正文 xref。

参考文献

索引

本索引列出正文中的核心索引入口。HTML 构建可直接阅读本节；支持自动索引的后续工具链可消费正文中的 indexterm 宏。

术语定义见 术语表；结构化关系谓词见 附录 D：结构词表。

索引入口 主要阅读位置

Package、Artifact

对象模型中的 Package 与 Artifact 章节。

Manifest、Registry、Index

对象模型中的 Manifest、Registry 与 Index 章节。

Resolver、Lockfile、Realization

对象模型中的 Resolver、Lockfile 与 Realization 章节。

Provenance、Attestation

对象模型中的来源证明章节 与 安全治理。

Package Discovery、Package Management

第一部研究对象 与 读者路径 章节。

Declared Evidence、Structural Evidence、Graph Evidence、Operational Evidence、Social Evidence、Security and Governance Evidence

证据与度量 中的证据源章节。

Dimension、Variable、Metric、Weight、Score

证据与度量 中的维度、变量、指标、权重与分数章节。

Compatibility

评价尺度 中的可比性边界章节。

Vulnerability Advisory、Trusted Publishing、SLSA、Sigstore

安全与治理 各章。