Global Executables

Global Executables

发布前，检查 CLI 命令名称是否已被使用。
通过 AI Agent 或浏览器，搜索 npm、PyPI、crates.io、Go 模块、Homebrew、 Debian 等来源中的可执行文件名称。

试用 Playground · 安装 MCP 服务 · 阅读文档 · 浏览数据

为什么要做这个项目

软件包名称不一定就是它安装的命令。搜索软件包名称注册表，可能会漏掉这类冲突：名称不同的软件包已经提供了你打算使用的命令。

索引保留了关键的关联关系：

command → provider → package → ecosystem → source evidence

立即试用——无需安装

打开 索引 Playground， 即可检查名称、查找相似命令、查看提供方或了解数据源覆盖范围。 Playground 与 MCP 服务读取的是同一份公开 JSON 数据集，查询数据不会发送到第三方 API。

如需 AI 辅助检查，请连接下方的 MCP 服务并提问：

I am naming a new CLI. Check `envc`, `evcr`, `evpk`, and `envcp` for exact
collisions and confusingly similar commands. Keep rejected names internal and
explain the coverage caveat for every survivor.

Agent 可以根据证据拒绝使用 envcp，而不只是依赖软件包名称搜索：PyPI 上的 chaperone 和 envcp 都提供了该命令。

你将获得

该服务没有写入工具，也绝不会安装或执行它找到的软件。

快速开始

1. 安装 uv

推荐使用 uv 进行设置。 无需克隆此仓库、下载数据集或创建 API 密钥。

验证 uvx 是否可用：

uvx --version

2. 添加 MCP 服务

选择下方的客户端。首次启动时会从 PyPI 下载软件包；之后启动时会复用 uv 的缓存。

{
  "mcpServers": {
    "global-executables": {
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}

claude mcp add global-executables -- uvx global-executables mcp

codex mcp add global-executables -- uvx global-executables mcp

{
  "servers": {
    "global-executables": {
      "type": "stdio",
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}

{
  "command": "docker",
  "args": ["run", "-i", "--rm", "ghcr.io/asopitech-labs/global-executables-mcp:latest"]
}

3. 向 Agent 提问

试试以下提示词：

Is the command name `envc` already taken? Check similar names too.

Check `envc`, `evcr`, `evpk`, and `envcp` as possible CLI names. Do not show
rejected candidates; explain the dataset coverage for the survivors.

Which package provides the `ruff` executable, and how should I install it in a
Python 3.12 project virtual environment?

Agent 通常会对一批名称调用 check_executables，并对剩余候选项调用 search_similar_executables。

重要

found: true 表示存在冲突。found: false 仅表示当前快照中没有匹配项。当 status 为 unknown 时，由于源代码覆盖不完整，无法证明该名称可用。采用名称前，请先查看 warnings、absence.confidence 和 coverage_scope。

工作原理

快照查询只会获取查询所需的公开 dictionary 分支文件，将其缓存在当前用户的缓存目录中，并通过 ETag 重新验证。网络暂时不可用时，仍可使用缓存文件。

uvx global-executables mcp --help 会列出与标志相同的选项。该软件包自 1.3.0 版本起发布到 PyPI。有关 HTTP 传输、离线运行以及从源代码检出版本运行的信息，请参阅 MCP 指南。

MCP 工具一览

快照查询工具为只读。discover_published_package 会向注册表和制品发起范围受限的实时请求，不会执行软件包代码。在配置了 Git 写入权限的指定运行器上，验证成功后还会预留一个不可变的 intake/<id> 分支，以供集中式重新验证。结果会报告 reservation.status；未配置的副本会报告 unavailable，且不会声称已发布。MCP 和 CLI 都不会直接写入已发布的字典。 仓库中的 Verify and reserve published package discovery GitHub Actions 工作流是指定运行器；它会在收集器启动前同时调用 CLI 和 MCP。 安装解析器会返回操作说明；它们绝不会安装或执行软件。完整的输入和结果契约请参阅 MCP 指南。

定期运行的收集器会在将预留证据合并到 artifact-data 前进行验证和复核。常规刷新仍是唯一会写入字典分支的流程。有关运行器配置和预留生命周期，请参阅 MCP 指南。

支持的生态系统

每个提供方都会保留其来源和置信度级别（direct、filesystem 或 inferred）。不同生态系统的覆盖范围各不相同，因此负面结果会附带明确的 覆盖范围元数据，而不会假装每个注册表都已穷尽。有关收集详情，请参阅 数据来源；有关结果契约，请参阅 覆盖范围与时效性。

文档导航

故障排除

目标

Global Executables 旨在提供：

• 真实可执行文件名称的公共数据集；
• 跨生态系统覆盖；
• 每个收集到的可执行文件都有可追溯的来源；
• 可复现的数据集生成；
• 适合 Git 的结构化数据；
• 用于高效查找的机器可读索引；
• 对可执行文件名称的历史追踪；
• 面向 AI Agent 的 MCP 访问；
• 明确的数据集覆盖范围和时效信息。

数据集本身是主要产物。

MCP 服务是对这些公共数据的访问层，而非事实来源。

试用在线版 索引 Playground， 查看爬取进度，并直接在浏览器中运行只读的 check、search、similar、 coverage 和 assess 查询。该 Playground 是基于公共 JSON 数据集的静态 GitHub Pages 客户端；不会将查询数据发送给第三方 API。

程序与已发布数据的生命周期彼此独立。程序源代码、架构、测试和文档位于 main； 生成的 JSON 词典位于孤儿 dictionary 分支。稳定的原始数据基础 URL 为：

https://raw.githubusercontent.com/asopitech-labs/global-executables/dictionary

有关分支约定、本地设置以及 main URL 切换，请参阅 词典分支迁移说明。

Go 开发遵循 JetBrains 现代 Go 指南。 有关版本审查、构建、测试、安全和发布工作流，请参阅 Go 爬虫开发与构建约定。

架构

Package ecosystems
        │
        ├── Debian / Ubuntu
        ├── Arch Linux
        ├── Homebrew
        ├── npm
        ├── PyPI
        ├── crates.io
        ├── Go modules
        ├── RubyGems
        ├── Packagist / Composer
        ├── ConanCenter
        ├── vcpkg
        ├── xmake-repo
        └── others
                │
                ▼
          GitHub Actions (`main`)
                │
       collect / normalize
                │
                ▼
  `dictionary` branch dataset
                │
        ┌───────┴────────┐
        │                │
        ▼                ▼
   GitHub / raw        MCP Server
      data                │
                          ▼
                     AI agents

GitHub Actions 会定期收集上游软件包信息、规范化可执行文件记录、重新生成索引、验证数据集，并发布生成的文件。

数据模型

规范的基本单位是可执行文件名称。

每个可执行文件都由一个包含其已知提供方的结构化文件表示。

概念上：

{
  "command": "example",
  "providers": [
    {
      "ecosystem": "example-ecosystem",
      "package": "example-package",
      "version": "1.0.0",
      "repository": "https://example.com/repository",
      "source": "example-source",
      "confidence": "direct"
    }
  ],
  "first_seen": "2026-08-14",
  "last_seen": "2026-08-14"
}

单个可执行文件可能在多个生态系统中有多个提供方。

仓库布局

dictionary 分支仅包含已发布的产物：

dictionary/
├── data/
│   ├── executables/
│   │   ├── en/
│   │   │   ├── envc.json
│   │   │   └── envcp.json
│   │   └── gi/
│   │       └── git.json
│   │
│   ├── indexes/
│   │   ├── prefix/
│   │   ├── length/
│   │   ├── ecosystem/
│   │   └── trigram/
│   │
│   ├── metadata.json
│   └── history.json
└── reports/
    ├── production-crawl.json
    └── production-refresh.json

main 分支则单独保留 fixtures/、schema/、src/、tools/、 tests/、docs/、playground/ 和 .github/workflows/；它不跟踪 上述生成路径。规范数据集使用常规结构化文件，无需数据库服务器。

派生索引可复现，并且可以从规范的可执行文件记录重新生成。

查询

精确查询可直接映射到仓库结构。

例如：

envcp
  ↓
prefix: en
  ↓
data/executables/en/envcp.json

这样，使用者无需下载或查询集中式数据库，即可检索单条记录。

派生索引支持更广泛的查询，例如：

• 前缀；
• 可执行文件长度；
• 生态系统；
• 相似名称。

数据来源

每个生态系统的采集器相互独立。

潜在来源包括：

C 和 C++ 没有单一注册表，因此会读取三个配方仓库，并从每个仓库中提取其实际提供的最有力证据。vcpkg 会列出端口安装的工具，因为列出工具名正是安装它们的方式。ConanCenter 配方从不列出其可执行文件，因此会读取已构建软件包自身的文件列表。xmake 会声明某个软件包是二进制文件，但从不说明该二进制文件的名称，因此其记录会标记为 inferred，不应将任何 xmake 记录视为声明。这三者都不是 exhaustive：vcpkg 端口可能安装命令却不声明它，ConanCenter 中无人构建过的配方无法说明已安装的文件，而 xmake 软件包可能以其他名称安装命令。

本项目会记录每个可执行文件的发现方式，而不会将所有观察结果视为同等权威。

置信度

记录可以带有置信度级别，用于说明可执行文件名称是如何确定的。

例如：

direct
filesystem
inferred

direct 表示软件包元数据中明确声明了该可执行文件。

filesystem 表示在软件包内容中观察到该文件已作为可执行文件安装。

inferred 表示该结果是间接推导得出的，应视为置信度较低。

使用者可以根据此信息判断潜在的名称冲突是否值得关注。

安装指南

resolve_installation 和 resolve_installations 提供特定环境的安装指南。Agent 可以直接调用这些 MCP 工具；用户也可以在 浏览器 Playground 中输入相同的目标环境。 CLI 也可以基于本地字典运行解析器：

global-executables resolve-installation pygo --root ./dictionary \
  --environment '{"package_manager":"pip","runtime_version":"3.12","install_scope":"project","virtualenv_bin":"./.venv/bin"}'

MCP 指南说明了所需的目标环境以及 installation-v1 结果约定。未经针对特定目标的安装与调用验证的指南会标记为 unverified。方法验证记录区分了经过测试的软件包管理器语法和未经测试的软件包标识。

Agent 工作流

命名 Agent 应在提出 CLI 名称建议之前使用 Global Executables。

推荐工作流：

Generate candidate names internally
            │
            ▼
     check_executables
            │
            ▼
 Separate `found:true` collisions from `found:false` observations
            │
            ▼
 search_similar_executables for not-found candidates
            │
            ▼
 Remove confusing candidates
            │
            ▼
 Present surviving names

无需向用户展示被拒绝的候选名称。

该服务旨在将冲突检查纳入 Agent 的常规推理工作流，而不是作为手动后续任务。

结果语义

数据集中没有记录，并不能证明某个可执行文件名称从未被使用过。

因此，结果会区分事实观察与对缺失情况的置信度：

collision
clear_in_index
unknown

例如：

{
  "name": "evpk",
  "found": false,
  "status": "unknown",
  "snapshot": "2026-10-19",
  "coverage_scope": "unknown",
  "checked_sources": [
    "arch",
    "crates",
    "debian",
    "go",
    "homebrew",
    "npm",
    "pypi",
    "ubuntu"
  ],
  "searched_sources": [
    "arch",
    "crates",
    "debian",
    "go",
    "homebrew",
    "npm",
    "pypi",
    "ubuntu"
  ],
  "coverage": {
    "arch": {
      "status": "success",
      "coverage_kind": "exhaustive",
      "records": 1647,
      "source": "data/production/intermediate/arch.jsonl"
    },
    "npm": {
      "status": "success",
      "coverage_kind": "partial",
      "records": 127,
      "source": "data/production/intermediate/npm.jsonl",
      "scope": "ecosyste.ms critical npm population covering 80% of downloads or dependent repositories",
      "catalog_complete": true,
      "catalog_packages": 2295,
      "catalog_snapshot": "2026-10-18",
      "catalog_source": "https://packages.ecosyste.ms/critical?registry=npmjs.org",
      "catalog_digest": "sha256:4b610ce561d63b72b7a4137ed75ba5ecbec5fbafda236218fc4264c92db605b3"
    }
  },
  "warnings": [
    {
      "code": "npm_coverage_incomplete",
      "ecosystem": "npm",
      "message": "npm coverage is incomplete or limited to a declared population. A missing result is not proof that no npm package uses this executable and is not permission to adopt the name.",
      "coverage": {
        "status": "success",
        "coverage_kind": "partial",
        "source": "data/production/intermediate/npm.jsonl",
        "scope": "ecosyste.ms critical npm population covering 80% of downloads or dependent repositories",
        "catalog_complete": true,
        "catalog_packages": 2295,
        "catalog_snapshot": "2026-10-18",
        "catalog_source": "https://packages.ecosyste.ms/critical?registry=npmjs.org",
        "catalog_digest": "sha256:4b610ce561d63b72b7a4137ed75ba5ecbec5fbafda236218fc4264c92db605b3"
      },
      "reference": "https://github.com/asopitech-labs/global-executables/issues/54"
    }
  ],
  "absence": {
    "status": "not_found_in_current_index",
    "confidence": "insufficient_coverage",
    "searched_sources": [
      "arch",
      "crates",
      "debian",
      "go",
      "homebrew",
      "npm",
      "pypi",
      "ubuntu"
    ]
  }
}

found:false 表示当前索引中未找到该名称。unknown 表示现有覆盖范围不足以断言该名称完全不存在；这并不意味着无法查询。只有在查询快照中的每个来源都具有 coverage_kind: exhaustive、运行成功，且没有有限的总体限制（scope 或 catalog_* 字段）时，才会返回 clear_in_index。已完成的 npm 关键目录会设置 catalog_complete: true，并保留 coverage_kind: partial；它不会使快照变为穷尽覆盖。npm 覆盖不完整时，还会添加 npm_coverage_incomplete 警告。这些状态均不代表可以采用该名称。

coverage 对象会报告每个来源的采集状态、覆盖类型和记录数。示例展示了两个具有代表性的来源；实时响应会包含快照中的所有来源（也可能包含每个来源的输入路径）。

这并不意味着该名称在法律上或全球范围内都保证可用。

覆盖范围与新鲜度

数据集元数据记录：

• 生成时间戳；
• 快照标识符；
• 已索引的可执行文件数量；
• 已启用的采集器；
• 每个上游来源的新鲜度；
• 采集器状态。

这些信息既可作为结构化数据获取，也可通过 MCP 获取。

因此，Agent 可以评估查询结果的可靠程度，而不是默认将索引视为完整数据。

GitHub 是事实来源

Global Executables 特意将规范数据保存在仓库的孤立 dictionary 分支中。

这带来了：

• 透明的数据来源记录；
• 可审查的更改；
• 可复现的生成过程；
• 历史追踪；
• 派生仓库和镜像；
• 直接访问原始文件；
• 不依赖 MCP 服务的可用性。

即使托管的 MCP 端点消失，数据集仍然可用。

第三方可以直接基于该仓库构建其他 MCP 服务、搜索引擎、CLI 或分析工具。

自动化

GitHub Actions 负责维护数据集。

通用管道如下：

scheduled / manual trigger
          │
          ▼
     run collectors
          │
          ▼
       normalize
          │
          ▼
        merge
          │
          ▼
 generate executable files
          │
          ▼
    generate indexes
          │
          ▼
       validate
          │
          ▼
        publish

采集器应独立于 GitHub Actions 实现实际的采集逻辑，以便也能在本地运行和测试。

开发期间可以使用 act 在本地运行兼容的 GitHub Actions 工作流。

Global Executables 不是什么

Global Executables 不是：

• 商标搜索服务；
• 品牌名称可用性服务；
• 包注册表；
• 包管理器；
• 漏洞数据库；
• 软件目录；
• 未使用名称在法律上可用的证明。

它回答的是一个范围更窄的问题：

在数据集覆盖的软件生态系统中，已知有哪些可执行文件名称正在被使用？

商标、公司名称、域名、仓库名称和更广泛的网络搜索仍需单独进行。

潜在用途

除了 CLI 命名之外，该数据集还可用于：

• 自动化 CLI 命名助手；
• 仓库 CI 策略；
• 包发布检查；
• 生态系统冲突分析；
• 可执行文件发现；
• CLI 生态系统的历史研究；
• IDE 和开发者工具集成；
• AI Agent 发布前检查。

项目原则

公开数据优先，MCP 其次。

Global Executables 的价值不依赖于某种特定的服务实现。

真正持久的资产是公开可用、可复现、跨生态系统的可执行文件名称数据集。

MCP 让 Agent 能立即使用该数据集。

当前实现

本仓库已实现各项模式、确定性构建器、生产级 OS 索引收集器、派生的前缀／长度／生态系统／三元组和逻辑作用域索引、收集器解析器、支持 Git 获取经验证的 npm/PyPI 发现结果的本地／HTTP MCP 服务、评估 API、有界 fixture 新鲜度场景以及 CI 检查。覆盖率按各数据源分别衡量。即使有限的 ecosyste.ms 关键目录已完成（catalog_complete: true），npm 仍保持 coverage_kind: partial；所有注册表中的 npm 长尾包并未纳入索引。有关准确的命名、分片、别名和历史规则，请参阅 docs/DATA_MODEL.md；有关可复现命令、新鲜度状态场景以及如实报告的覆盖率限制，请参阅 docs/OPERATIONS.md。

如需零配置使用，请参阅快速开始。若要在不访问网络的情况下查询固定快照，请安装程序，在独立的工作树中检出已发布分支，并将服务指向该目录：

python -m pip install -e .
git fetch origin dictionary
git worktree add .dictionary origin/dictionary
global-executables-mcp --root . --dataset-root .dictionary

远程访问请使用 --transport streamable-http。两种模式均提供 check_executable、check_executables、get_executable、 search_executables、search_similar_executables、get_coverage、 assess_executable 和 assess_executables；两种模式都不支持写入。无需运行 MCP，即可直接从 dictionary 分支读取规范 JSON 数据，并依据仓库许可证重复使用。有关本地客户端配置、远程端点、资源、健康状态可见性以及仅包含幸存项的 Agent 工作流，请参阅 docs/MCP.md。

手动 fixture 工作流会执行有界的增量新鲜度扫描。它会轮换不可变的测试分区，在 freshness-data 分支上持久化游标和最近一次成功观测结果，并发布机器可读的测试报告。这并非生产环境的新鲜度扫描，也不会刷新完整数据集。覆盖率针对具体快照，由 get_coverage 报告。已发布的快照包含生产级 OS/Homebrew 覆盖率、已完成但仍不完整的 npm 关键目录（catalog_complete，不代表穷尽整个注册表），以及其他注册表（如 PyPI 和 Go）的部分覆盖率；它并未覆盖全球所有生态系统，因此使用方必须保留 clear_in_index／unknown 语义以及 npm_coverage_incomplete 警告。

注册表工件检查可单独恢复。CI 每天刷新有限的 npm 关键目录并将其爬取至 100%；专用本地容器推进 PyPI 和 Go 模块游标，并将检查点发布到 artifact-data；这些本地容器只是临时的完成加速器，达到 100% 后便会停止。某个数据源达到 100% 后，GitHub Actions 每六小时运行一次矩阵任务，通过持久化的刷新游标轮询所有已索引的软件包。成功结果会替换过时的软件包观测结果，包括被较新版本移除的命令。CI 还每天检查一次 crates.io 转储是否发生变化，并且仅在转储有变动时下载。CI 刷新器仅在规范化观测结果发生变化时触发词典重建，并在发布爬取进度时重新部署 Pages。Go 模块、npm、PyPI、RubyGems 和 Packagist 使用事务式 Go 运行时；其 bbolt 状态会一并提交游标、重试判定和观测结果。CI 会重新生成 npm 的有界包集合；PyPI、RubyGems 和 Packagist 复用抽样目录，而 Go 会扩展其索引。完成已声明的目录后，可能会设置 catalog_complete；仅凭该目录，npm 绝不会升级为 coverage_kind: exhaustive。其他数据源只有在其已声明的目录和必需的工件检查均成功完成，且不存在有限集合限制后，才会标记为 exhaustive。 成功收集数据本身并不足以支持「不存在碰撞」的结论。 每个有效查询都会返回事实性的 found 观察结果。对于不存在的名称，夹具、冒烟测试和部分快照无法提供足够的缺失置信度；只有元数据明确标记所查询的完整快照为穷尽式快照时，clear_in_index 才适用。派生搜索索引的完整性由元数据中的固定值校验，并由前缀、长度、生态系统和相似度查询直接使用。

如需了解干净检出后的设置、客户端配置、预期响应和验证步骤，请参阅 docs/SETUP.md。

问题完成情况和发布证据遵循 docs/RELEASE.md；仅有实现方面的声明并不能结项。

数据源、其许可证和条款以及所需的署名信息均列于 docs/DATA_SOURCES.md。