dep-rank

dep-rank

按星标数或可信度为 GitHub 依赖项目排名。

dep-rank 可找出依赖于指定 GitHub 项目的最受欢迎仓库。它会抓取 GitHub 的依赖项目页面，通过 GraphQL API 丰富结果，并可作为命令行工具和面向 AI Agent 的 MCP 服务使用（参见 MCP 服务）。

快速开始

pip install dep-rank
dep-rank deps https://github.com/django/django

CLI 参考

dep-rank deps — 列出热门依赖项目

dep-rank deps https://github.com/django/django
dep-rank deps https://github.com/django/django --rows 20 --min-stars 100
dep-rank deps https://github.com/django/django --descriptions --format json
dep-rank deps https://github.com/django/django --packages

选项	默认值	描述
--rows	10	结果数量
--min-stars	5	星标数最低筛选条件
--format	table	输出格式：table 或 json
--descriptions	off	通过 GitHub API 获取描述（需要令牌）
--packages	off	搜索软件包而非仓库
--token	DEP_RANK_TOKEN	GitHub 令牌
--max-pages	200	最多抓取页数（上限为 1000）
--no-adaptive-stop	off	禁用自适应提前停止；抓取会持续进行，直到内容耗尽或达到 --max-pages
--rank-by	stars	排名策略：stars 或 trust（启发式，需要令牌）
--trust-check	off	检查最多 25 个热门结果的抽样星标历史（需要 --rank-by trust 和令牌）
--downloads	off	显示每个依赖项目下载量最高的注册表软件包（ecosyste.ms / deps.dev / npm；仅显示）

在表格输出中（deps、search 和实时进度表），对于支持 OSC 8 超链接的终端，仓库名称会显示为指向其 GitHub 页面的可点击链接；管道或重定向输出则为纯文本。

dep-rank search — 在依赖项目中搜索代码

dep-rank search https://github.com/django/django "from django.db import"
dep-rank search https://github.com/django/django "middleware" --max-repos 20

选项	默认值	描述
--max-repos	10	要搜索的仓库数量上限
--min-stars	50	仅搜索星标数达到此值的仓库
--token	DEP_RANK_TOKEN	GitHub 令牌（必需）
--max-pages	200	最多抓取页数（上限为 1000）

search 始终执行有界的非自适应 top-K 抓取（此命令不提供 --no-adaptive-stop；自适应提前停止始终处于禁用状态）。

部分结果

抓取结果（deps 以及 search 的预抓取阶段）会报告任务是否已完成：结果中包含 complete 标志和 reason。complete: false 表示抓取提前停止，原因可能是 max_pages_reached（提高 --max-pages）、trend_converged（自适应启发式判断 top-K 已稳定；使用 --no-adaptive-stop 可持续抓取，直到内容耗尽或达到 --max-pages）、network_failure 或 rate_limited。此时，total_count/filtered_count 是基于实际抓取页面得出的下限，并非总量。

dep-rank cache — 管理缓存

dep-rank cache stats    # Show cache size
dep-rank cache clear    # Clear all cached data

MCP 服务

dep-rank mcp 会通过 stdio 运行一个 MCP 服务，让 AI Agent 可以直接调用 dep-rank。它需要可选的 mcp extra：

pip install "dep-rank[mcp]"

客户端配置（该命令适用于任何可启动 stdio 服务的 MCP 客户端）：

{
  "mcpServers": {
    "dep-rank": {
      "command": "uvx",
      "args": ["--with", "dep-rank[mcp]", "dep-rank", "mcp"],
      "env": { "DEP_RANK_TOKEN": "ghp_your_token_here" }
    }
  }
}

必须设置 DEP_RANK_TOKEN：缺少它时，两个工具都会失败。令牌仅从服务的环境变量中读取，绝不会从工具参数中读取。

工具：

• get_dependents — 按星标数或信任度对仓库的依赖者排名（dep-rank deps 工作流）。参数与 CLI 一致：url、rows、min_stars、dependent_type、descriptions、rank_by、trust_check、downloads、max_pages、adaptive_stop。
• search_dependents — 在排名靠前的依赖者中搜索代码（dep-rank search 工作流）：url、query、max_repos、min_stars、max_pages。

注意事项：

• 结果可能不完整。在将计数视为总数之前，请检查 complete 和 reason；详见部分结果。
• 信任分数是相对于样本池的启发式指标，不代表质量或欺诈判定；详见信任度排名。
• 调用会逐个运行；有调用正在运行时到达的调用需要等待。
• 长时间运行的调用会报告进度，包括等待 GitHub 速率限制的情况。Claude Code 会将运行时间超过两分钟的 MCP 调用转入后台。
• 服务会遵循其环境中的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。不支持 SOCKS 代理（例如 ALL_PROXY=socks5://...）：从服务环境中移除该代理之前，工具调用都会失败并报错。

Docker MCP Toolkit

ghcr.io/j7an/dep-rank 镜像可在 Docker MCP Toolkit 下运行 MCP 服务。它提供容器隔离（无主机文件系统访问权限；当网关以 --block-network 运行时，网络访问仅限 GitHub），并且所有连接的 Agent 框架共用一个配置文件。但它不会改变提示词注入风险：工具结果仍包含来自第三方仓库的文本，Agent 也会读取这些文本。

先决条件：安装 Docker MCP Toolkit 的 Docker Desktop，并启用配置文件（在 Docker Desktop 中启用 MCPWorkingSets 功能标志，或运行 docker mcp feature enable profiles）。

1. 将此服务定义保存为 ~/.docker/mcp/catalogs/dep-rank.yaml。网关只会从该目录读取 file:// 定义。

   name: dep-rank
   title: dep-rank
   type: server
   image: ghcr.io/j7an/dep-rank:latest
   description: Rank a GitHub repo's dependents by stars or trust heuristic, and search their code
   secrets:
     - name: dep-rank.token
       env: DEP_RANK_TOKEN
       example: ghp_your_token_here
   volumes:
     - dep-rank-cache:/cache
   allowHosts:
     - github.com:443
     - api.github.com:443
   

   使用 downloads 的 get_dependents 还需要将 packages.ecosyste.ms:443、api.npmjs.org:443 和 api.deps.dev:443 加入 allowHosts；否则下载统计会显示为不可用。

   为确保安装可复现，请将 image 固定为发布标签（ghcr.io/j7an/dep-rank:<version>）或 @sha256: 摘要。使用 gh attestation verify oci://ghcr.io/j7an/dep-rank:<version> --repo j7an/dep-rank 验证镜像的构建来源证明。

2. 创建配置文件。请保留 --id dep-rank：如果不指定它，ID 会变为 dep_rank，与下方的框架配置不匹配。

   docker mcp profile create --name dep-rank --id dep-rank \
     --server "file://$HOME/.docker/mcp/catalogs/dep-rank.yaml"
   

3. 保存 GitHub 令牌：

   gh auth token | docker mcp secret set dep-rank.token
   

   如果缺少密钥，网关会将字面值 <UNKNOWN> 作为 DEP_RANK_TOKEN 传入，因此调用会报 GitHub 错误，而不是显示“缺少令牌”消息。

4. 将每个框架指向网关。请手动编写条目，确保包含 --block-network，该参数用于强制执行 allowHosts：

   {
     "mcpServers": {
       "dep-rank": {
         "command": "docker",
         "args": ["mcp", "gateway", "run", "--profile", "dep-rank", "--block-network"]
       }
     }
   }
   

   也可以运行 docker mcp client connect <client> -p dep-rank，但它写入的条目不会包含 --block-network；请自行添加。

注意：

• 每次工具调用都会启动一个全新的容器。dep-rank-cache 卷会在调用之间保留缓存。
• 网关可能会留下代理容器。运行 docker rm -f $(docker ps -aq --filter label=docker-mcp-proxy=true) 将其移除。

Python API（暂定）

在 Python 中使用 dep_rank.core.dependents.get_dependents 执行 deps 工作流。 它会返回 dep_rank.core.models.DependentsResult；使用 dep_rank.core.models.DependentType 选择仓库或软件包的依赖方。此 API 在 0.x 期间可能会变更。

import asyncio

import httpx2

from dep_rank.core.cache import SqliteCache
from dep_rank.core.dependents import get_dependents
from dep_rank.core.models import DependentsResult, DependentType


async def main(cache_dir: str | None = None) -> None:
    cache = SqliteCache(cache_dir) if cache_dir is not None else None
    try:
        if cache is not None:
            await cache.initialize()
        async with httpx2.AsyncClient() as session:
            result: DependentsResult = await get_dependents(
                session,
                "https://github.com/django/django",
                dependent_type=DependentType.REPOSITORY,
                cache=cache,
            )
            for repo in result.repos:
                print(repo.url, repo.stars)
            if not result.complete:
                print("Partial results:", result.reason)
    finally:
        if cache is not None:
            await cache.close()


asyncio.run(main(cache_dir=".dep-rank-cache"))

dep_rank.core.cache.SqliteCache(path) 接受一个缓存目录。缓存是可选的： 在此示例中调用 main() 可省略缓存。调用方负责打开和关闭会话，以及初始化和关闭缓存；get_dependents 不会关闭其中任何一项。 默认情况下，最多返回 10 个至少有 5 个星标的依赖方，并按星标数排名。 如需获取描述或进行信任度排名，请显式传入 GitHub token，例如 token=...； 库入口不会读取 DEP_RANK_TOKEN。如需获取可选的软件包下载统计信息，请传入 downloads=True；此查询不需要 token。 检查 result.downloads_check.complete 和 .unavailable，以区分查询失败与没有匹配软件包的仓库。

对于无效的 GitHub 仓库 URL、rank_by 不是 "stars" 或 "trust"、未提供 token 却设置了 descriptions=True、未提供 token 却设置了 rank_by="trust"，或在 rank_by 不是 "trust" 时设置了 trust_check=True，get_dependents 会引发 ValueError。信任度分数是相对于候选集合的启发式指标，并非质量或欺诈判定。

如果结果不完整，请检查 result.complete 和 result.reason；结果不完整时，各项计数均为下限。result.stale_pages 统计从已过期缓存条目中提供的页面数；当信任度分数使用了部分元数据时，result.trust_metadata_complete 为 false。result.trust_pool_size 表示共同参与评分的依赖方数量，信任度分数是相对于这些依赖方计算的（未按信任度排名时为 0）。这些字段存在于结果对象中，但会从 model_dump() 和 JSON 序列化（model_dump_json()）中排除。 如果无法获取信任度元数据，结果会回退为按星标数排名；请检查 result.ranked_by == "trust" 以确认是否采用了信任度排名，因为 trust_metadata_complete 仅描述成功进行信任度排名时所使用的元数据。

身份验证

设置 DEP_RANK_TOKEN 环境变量，并填入 GitHub 个人访问令牌：

export DEP_RANK_TOKEN=ghp_your_token_here

对于非简单用途，token 实际上是必需的：未经身份验证的 GitHub HTML 抓取每个 IP 每小时限制约 60 次请求，因此未经身份验证的运行仅适用于小规模的一次性抓取。设置 DEP_RANK_TOKEN 可提高此限制。

无需 token 即可使用的功能：

• dep-rank deps — 核心抓取和星标排名

需要 token 的功能：

• --descriptions 标志 — 通过 GitHub GraphQL API 获取仓库描述
• --rank-by trust — 通过 GitHub GraphQL API 获取互动度／近期活动元数据
• --trust-check — 为信任度排名添加经过身份验证的 REST 星标历史请求
• dep-rank search — 在依赖方中进行代码搜索
• dep-rank mcp — 两个 MCP 工具都要求在服务环境中设置 DEP_RANK_TOKEN

在 github.com/settings/tokens 创建 token，并授予 public_repo 权限范围。

工作原理

dep-rank 使用三阶段流水线：

1. 抓取 — 获取 GitHub 的 /network/dependents HTML 页面，发现 GitHub 列出的依赖仓库及其大致星标数
2. 补充信息（可选）— 通过一次 GraphQL 批量查询获取前 N 条结果的准确星标数和描述（替代 100 次单独的 REST API 调用）
3. 呈现 — 将结构化结果作为 Rich 表格返回

使用 --downloads 时，排名完成后会为显示的行添加可选的软件包下载统计数据。

GitHub 只会列出已启用依赖关系图的仓库。自 2025 年 6 月起，新建的公开仓库默认关闭依赖关系图，长期不活跃的仓库也会禁用该功能，因此统计数量可能遗漏实际依赖仓库。

响应会缓存在本地 SQLite 数据库中（macOS 上为 ~/Library/Caches/dep-rank，Linux 上为 $XDG_CACHE_HOME/dep-rank 或 ~/.cache/dep-rank，Windows 上为 %LOCALAPPDATA%\dep-rank\dep-rank\Cache），并支持通过 ETag 发起条件请求。在已通过身份验证的运行中，过期页面会立即返回，并在后台刷新（过期后重新验证）。未经身份验证的运行会原样返回过期页面，且不会刷新；发生这种情况时，deps 会在 stderr 上输出提示。设置令牌或运行 dep-rank cache clear，即可获取最新结果。

软件包下载量

dep-rank deps https://github.com/django/django --downloads

--downloads 可与 --repositories 和 --packages 一起使用，且无需令牌要求。对于每个显示的依赖项，ecosyste.ms 提供软件包候选项和非 npm 下载量，deps.dev 提供证明证据。npm 下载量来自 npm 的下载 API（api.npmjs.org，最近 30 天）；非 npm 下载量是 ecosyste.ms 的快照，可能存在延迟。显示符合条件的候选项中下载量最高的软件包；下载量绝不会影响星标或可信度排名。

符合以下任一规则即可接受软件包：

• deps.dev 通过发布证明或 SLSA 证明将软件包与仓库关联，且至少有一条证明标记为 verified: true。
• 不带命名空间的软件包名称与仓库名称匹配：匹配前会转为小写、移除 -、_ 和 .，并可选择去掉一个已识别的语言后缀。
• 带命名空间的软件包（@scope/name、vendor/name、publisher/name）仅在其命名空间与仓库所有者按相同规则规范化后匹配时才接受；仅名称部分匹配并不足够。

即使有证明，标记为 removed 的软件包也会被拒绝。✓ 表示已验证的仓库到软件包关联证明；它不能证明软件包的构建方式。仅凭名称匹配且没有标记的软件包未经验证：安装前请先检查。抢注者可能会注册匹配的名称，也可能注册尚未认领的所有者范围或供应商命名空间。仍在列表中的恶意软件没有结构化标记可供这些查询结果使用，合法软件包之后也可能遭到入侵。dep-rank 不是漏洞扫描器；请使用 pip-audit、npm audit 或 OSV 等工具检查已知漏洞。

下载量可能虚高或过时，统计周期也各不相同：/mo 表示上个月，total 表示累计值，其他周期会明确显示。不同周期的原始下载量不能直接比较。名称匹配也可能遗漏合法软件包（例如，仓库中的软件包名称不同）。— 表示未找到符合条件的软件包；unavailable 表示查询失败。查询失败不会影响 deps 运行，并会向 stderr 输出警告，包括 JSON 模式。

**向第三方发送数据：**选择启用后，显示行对应的仓库 URL 会发送至 ecosyste.ms 和 deps.dev。显示的 npm 软件包名称也会发送至 api.npmjs.org。查询请求不会包含调用方凭据。

JSON 会添加每个仓库的 downloads 对象（或 null）以及顶层的 downloads_check；未使用该标志时会省略这些字段。此示例仅供说明：所选软件包和下载量可能会变化。

{
  "repos": [{
    "owner": "facebook",
    "name": "react",
    "downloads": {
      "ecosystem": "npm",
      "name": "react-is",
      "downloads": 1524448794,
      "period": "last-month",
      "verified": true
    }
  }],
  "downloads_check": {
    "complete": true,
    "unavailable": []
  }
}

下载量为 null 表示没有符合条件的软件包，除非仓库的 owner/name 出现在 downloads_check.unavailable 中；在这种情况下，查询失败，且 downloads_check.complete 为 false。

信任度排名

dep-rank deps --rank-by trust 会根据轻量级综合分数重新排列依赖项目，而不是按原始星标数排名。星标数有参考价值，但容易被操纵；信任度排名会将星标数与其他非星标指标结合——分叉数、议题和拉取请求总数，以及最近活动时间——这些数据通过低成本的 GitHub GraphQL 查询获取（每次请求批量查询 25 个仓库，因此候选池较大时会发起多次请求）。

dep-rank deps https://github.com/django/django --rank-by trust --token ghp_...

重要注意事项：

• 此分数是相对于候选池的排名指标，而非绝对质量分数——它会根据抓取到的候选集合对各项指标进行最小-最大归一化。
• 它只会重新排列抓取到的候选池（按星标数排名前 N 的依赖项目），不会涵盖所有依赖项目。
• 这是启发式方法，不会检测虚假星标。默认情况下不会获取星标历史；可通过 --trust-check 选择性抽样。两种模式都不会获取 GHArchive 数据或外部欺诈数据集。
• 信任度排名会抓取更大的候选池，因此比星标排名更深入，也更慢。
• --rank-by trust 需要 GitHub 令牌；信任度分数会显示在 --format json 输出中每个仓库的 trust 字段下。

分数的计算方式

信任度模式会将星标数最高的依赖项目放在一起评分，然后显示该排名中前 --rows 个项目。评分数量（候选池大小）为 min(100, rows × 10)，且不会少于 --rows；如果匹配的依赖项目更少，则按实际数量评分。默认的 --rows 10 会为 100 个项目评分并显示 10 个；--rows 50 会为 100 个项目评分并显示 50 个。当 --rows ≥ 100，或匹配的依赖项目不超过 --rows 个时，会显示所有获得评分的项目。

四项指标（最近活动时间除外）都会进行对数缩放，并在候选池内进行最小-最大归一化：候选池中的最低值映射为 0，最高值映射为 1，中间值按比例映射。如果候选池中所有仓库的某项指标值都相同（包括候选池只有一个仓库的情况），则该项指标对所有仓库都设为 0.5。最终分数为加权和 × 100：

指标	权重
星标数	35%
分叉数	25%
议题 + 拉取请求（所有时间）	20%
最近一次推送的时间	20%

• 100 表示该仓库在候选池的所有指标上都排名最高。50 表示归一化后的加权指标平均值为 0.5。这不是中位排名：归一化会在候选池的极值之间进行线性映射，因此一个离群值可能导致候选池中的大多数项目远低于 50。分数为 50 并不代表「可信度只有 100 分的一半」。
• 分数只可在同一次运行中进行比较。更换目标、--rows 或 --min-stars 都会改变候选池，进而改变所有分数。
• 由于表格显示的是候选池中的前列项目，分数通常会集中在高位：默认设置只显示排名前十分之一的项目。--rows 100 会显示完整分数范围。
• 表格页脚会注明获得评分的依赖项目数量和显示的行数。JSON 会在 trust.components 下包含各项指标的 0–1 数值。

Star-history 检查

dep-rank deps https://github.com/django/django --rank-by trust --trust-check

此可选检查使用 GitHub 经过身份验证的 仓库星标历史 API，抽样检查最多 25 个排名靠前的返回仓库最近 30 周的每日星标数。当此时间窗口内星标数不少于 200，且至少 15% 集中在同一天时，检查会添加 concentrated_starring 警示。它不会改变信任分数或排名。这不能证明存在虚假星标：产品发布和 Hacker News 热度飙升也可能呈现相同模式。有关星标信号的动机和局限，请参阅 StarScout 和下方的研究资料。

表格页脚会报告已检查与返回的仓库数量、集中模式、insufficient_history（时间窗口内不足 200 个星标）以及 unavailable（无法获取历史记录）。只有在请求此检查时，JSON 才会添加顶层 trust_check 状态；例如（摘录）：

{
  "trust_check": {
    "complete": true,
    "window_weeks": 30,
    "repos_checked": 1,
    "insufficient_history": [],
    "unavailable": []
  },
  "repos": [{
    "trust": {
      "cautions": [{
        "code": "concentrated_starring",
        "description": "300 of 1,000 stars in the last 30 weeks arrived on 2026-09-01"
      }]
    }
  }]
}

trust_check.complete 描述的是抽样仓库的可用情况，而非所有结果或所有历史星标的覆盖情况。历史记录不可用时，该字段为 false，但排名仍可正常使用。如果信任排名不可用，则会跳过此检查，并将返回的仓库标记为不可用。此检查不使用账户级信号：GitHub 于 2026 年 7 月将星标者列表访问限制为仓库管理员和协作者；本检查依据的仍是汇总星标历史。

警示信号

按信任度排名的结果可能包含信息性警示信号。这些信号基于同一次元数据获取生成，默认不会发出额外请求。可选的 --trust-check 会通过单独的请求添加星标历史警示。在 JSON 中，信号显示在每个仓库的 trust.cautions 下（由 code + description 组成的列表，也可能为空）；在表格中则显示为 Cautions 列中的简短标签，且仅当至少一个结果含有信号时才显示。表格下方会说明出现的每个标签。

代码	表格标签	显示条件
low_non_star_activity	low-activity	星标数 ≥ 500，且 fork 数、issue 数 + pull request 数均低于星标数的 1%
stale_activity	stale	星标数 ≥ 500，且超过 365 天没有推送
archived_or_disabled	archived	仓库已归档或禁用
new_with_high_stars	young	星标数 ≥ 1,000，且创建时间在最近 180 天内
concentrated_starring	spike	仅适用于 --trust-check：抽样时间窗口内星标数 ≥ 200，且至少 15% 集中在同一天

阈值是固定的启发式规则。星标数下限代表最低样本量；低活跃度信号要求 fork 数和 issue/PR 数同时偏低，因为热门列表和文档仓库通常很少有 issue。缺失的元数据不会触发信号。基于时间的信号以本次运行的 scraped_at 时间为准。

警示信号不能证明存在虚假星标或恶意行为。 它们标示出值得进一步查看的模式，而正常仓库——例如已完成的库、归档项目、突然走红的新工具——也可能符合这些模式。它们不会改变信任分数。

关于星标可能被操纵的动机，参考了 StarScout（仓库、 预印本、 ICSE 2026）。 低资源 API 的依据是 GitHub GraphQL 速率限制文档。

开发

# Prerequisites: Python 3.11+, uv
uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy src tests

致谢

dep-rank 是对 Andriy Orehov 的 ghtopdep 的全面重写。原项目采用 MIT 许可证。

许可证

MIT — 详情请参阅 LICENSE。