Awesome Core

🔥 Awesome Core

一句话介绍

把所有 GitHub 上的 awesome 列表下载到你磁盘上的一个目录里， 让你按名称、语言、系统或主题快速查找工具—— 完全离线运行。

例如，你想找“能在 Windows 上运行的 OSINT 工具”。输入：

./awesome search osint --os windows

就能一次获取多个 awesome 列表中的工具，并按排序排列，让那些被多个独立整理者收录的工具 排在最前面 （而不是只在某个热门列表里出现的工具）。

筛选条件之间是 AND 关系，因此很快就会叠加得过多。 --os windows --lang PowerShell 会让“osint”的结果只剩下一个工具——而且不是你想找的那个，而是一个恰好也叫“Sherlock”的 PowerShell 脚本。程序知道筛选条件过窄，会直接指出可以去掉哪个条件：

注意：2 个 AND 筛选条件只留下了 1 个结果。
    去掉 lang=PowerShell  →  8 个结果

建议：只有在结果超过几个时才添加筛选条件。

如果你没时间——三条命令

./awesome start      # 1. wszystko robi za Ciebie (pobiera, buduje, gotowe)
./awesome search nmap
./awesome web        # i otwiera przeglądarkę

./awesome start 会在每一步说明它正在做什么，以及需要多长时间。没有任何操作会在后台自动运行——你始终能看到进度。

开始之前需要准备什么

只需要一样东西：Python 3.8 或更高版本。 就这些。

不需要 jq、curl、GitHub CLI，也不需要自行运行 python -m venv：

• 下载列表通过普通 HTTPS (core/api.py) 完成——没有 gh 会比较慢，因为 GitHub 将搜索限制为每分钟 10 次请求，但仍然可以使用；
• 首次运行 ./awesome web 时，会自动安装用于 Web UI 的 Flask；
• 缺少依赖时，程序会自行提示（./awesome doctor）。

如果你安装了 gh 并完成登录（gh auth login），所有操作会快 30 倍，enrich 功能也会解锁。不过这只是提速，不是必需条件。

在 Linux 上安装：

sudo apt install python3               # albo: sudo dnf install python3

可选：安装后可让下载和工具元数据获取速度提升 30 倍：

gh auth login                          # GitHub CLI, jednorazowo

Windows 无需 bash。 目录中有 awesome.cmd，因此在 PowerShell 中或双击打开后，只需输入：

awesome.cmd start
awesome.cmd web

download.sh 仍然保留，但现在它只是一个调用 Python 的包装脚本——里面已经没有 jq、curl 或 shell 循环了。

其余命令在 PowerShell 中的对应写法：

gh auth login                 # potem reszta jak w Linuxie
.\venv\Scripts\Activate.ps1 # aktywacja venv
.\awesome web

用于 Web UI 的 Flask 会在首次运行 ./awesome web 时自动安装：

Web UI potrzebuje Flaska. Przygotowuję środowisko (requirements.txt):
  Tworzę venv…
  Aktualizuję pip…
  Instaluję z requirements.txt…
  Gotowe. Od teraz web używa venv/.

如果因为某些原因安装失败（网络不可用、代理问题），程序会显示手动操作说明——但你平时无需记住这些步骤。

你不需要懂 SQL、会编程或配置内部设置，也不需要自动更新任何内容。如果出现问题，./awesome status 会告诉你具体该运行什么命令。

首次运行，分步指南

./awesome start

程序会检查你是否已具备所有内容，然后：

如果数据库已经构建，start 不会重新下载任何内容。 它会显示 工具数量并立即启用界面。重建需要主动确认：

./awesome start --rebuild    # kasuje bazę i buduje od nowa (~2 min)
./awesome refresh            # dociąga brakujące dane i przebudowuje

这样一来，意外执行 ./awesome start 就不会浪费你 2 分钟的工作。

坦诚提醒： start 不会查询工具本身的 GitHub 仓库。排名会立即生效 （基于策展人的认可），但工具旁的星标数目前只是列表中的估算值，并非真实数量。 一条命令即可修正：

./awesome enrich      # 30–60 min, odpytuje ~35 tys. repozytoriów
./awesome build       # ~2 min, żeby gwiazdki wsiąkły do rankingu

或者从头开始，一条命令搞定：

./awesome start --full   # download → build → backfill → enrich → build

只需执行一次。随时可以中断（Ctrl+C）——进度会保存，再次运行命令时会接着继续。 如果没有登录 GitHub，enrich 会说明原因并拒绝执行，而不会假装已经完成工作。

如果时间不多，可以跳过步骤 1，之后再补上：

./awesome start --skip-download     # szybka ścieżka: buduje z tego, co już jest

日常使用

./awesome search "port scanner"                    # szukaj po ludzku
./awesome search osint --lang Python              # ...tylko Python
./awesome search "active directory" --os windows  # ...tylko pod Windowsa
./awesome langs                                    # co jest w bazie (języki)
./awesome platforms                                # systemy: Windows, Linux, Docker...
./awesome domains                                  # tematy: osint, security, network...
./awesome why nmap                                 # skąd ten wynik — punkt po punkcie
./awesome mentions nmap                            # w ilu listach jest to narzędzie
./awesome audit                                    # czy katalog nie jest zatruty fałszywymi listami
./awesome audit sindresorhus/awesome               # audyt jednego repozytorium
./awesome lists                                    # najlepsze listy
./awesome info nmap                                # dane + komenda instalacji
./awesome install nmap                             # zainstaluj (git clone)

你自己的列表

如果你发现了好用的工具——马上把它加入自己的列表，最后 复制生成好的 Markdown：

./awesome shortlist add nmap --note "do skanowania sieci"
./awesome shortlist                            # co jest na liście
./awesome shortlist emit --title "Moja lista OSINT" --group domain
./awesome shortlist emit --out moja-lista.md  # zapisz do pliku

Web UI 中也有同样的功能：工具页面上的 ☆ 加入我的列表 按钮， 以及菜单中 我的列表 链接下的列表和 Markdown。在 TUI 中按 k。

此外还有 watch——用于关注你想追踪的列表仓库（收藏列表中的新工具）， 而不是工具列表：

./awesome watch add sindresorhus/awesome
./awesome watch check          # co doszło od ostatniego sprawdzenia

这两个列表都保存在本地，也都不会在后台自动查询。

TUI — 按键

/  szukaj              l  następny język      o  następna platforma
d  następna domena      s  zmień sortowanie     a  wyczyść filtry
g  ukryte perełki      u  niedoceniane        Enter  szczegóły
k  do mojej listy      i  instaluj             ?  pomoc
q  wyjście

四种界面，同一个目录

./awesome            # terminal — najszybszy do szybkiego szukania
./awesome tui        # terminal, ale interaktywnie (strzałki, filtry)
./awesome web        # przeglądarka (port wypisuje na ekranie)
./awesome help       # wszystkie komendy

日常维护（不会自动运行任何操作）

./awesome status     # co jest w bazie, kiedy ostatnio odświeżone, czego brakuje
./awesome refresh    # pobierz nowe listy → metadane → przebuduj bazę

刷新后，./awesome status 会提示准确的命令，例如 ./awesome enrich。浏览器中也一样：/refresh 页面上有四个按钮。 没有 cron、守护进程或后台进程。

关于数量的重要说明： 状态显示的不是“有 X 个工具没有星标”，而是 还有多少个仓库待查询。两者差别很大，因为多个工具经常指向同一个仓库； 而 GitHub 以外的链接（文章、视频、文档）没有星标，也永远不会有星标—— 不要把它们算作待完成的工作。

内容一览

随时可以通过 ./awesome status 查看最新数量。

坦诚提醒： 这里没有任何 AI。没有大模型会挑选、评估或排列工具。 这只是一个解析 GitHub 列表 README 并直接统计数据的普通 Python 程序。 如果 README 中的数字与数据库不一致，就是有人忘记刷新 STAN 区块了。运行 ./awesome status 并修正即可。

接入 AI Agent（MCP）——本地使用，无需 API 密钥

可以将目录提供给本地 Agent（Claude、Cursor，或任何支持「Model Context Protocol」的工具）作为工具来源。Agent 获取的是基于独立策展者共识的排名，而不是某个 README 中出现频率最高的工具。

./awesome mcp --demo    # podgląd: zobaczysz całą wymianę JSON-RPC bez agenta
./awesome mcp           # serwer czeka na stdin (tak to działa w praktyce)

服务提供 5 种工具：search_tools（带筛选条件搜索）、 find_undiscovered_tools（被低估和隐藏的好工具）、explain_tool （解释排名依据：来自哪些列表、得分多少、哪些因素影响了排名）、 lists_with_tool（所有列表及标记为重复的副本）和 catalog_facets （数据库中包含哪些内容：语言、平台、领域）。

将以下内容填入客户端配置，例如 claude_desktop_config.json：

{
  "mcpServers": {
    "awesome-core": {
      "command": "/pełna/ścieżka/do/awesome-core/awesome",
      "args": ["mcp"]
    }
  }
}

也可以不克隆，直接从 PyPI 运行（软件包 awesome-core，也已收录于 MCP 官方注册表，名称为 io.github.twojlogin/awesome-core）：

{
  "mcpServers": {
    "awesome-core": {
      "command": "uvx",
      "args": ["awesome-core"],
      "env": { "AWESOME_DATA_DIR": "/pełna/ścieżka/do/awesome-core/data" }
    }
  }
}

uvx 会从 PyPI 下载并运行服务。AWESOME_DATA_DIR 必须指向由 ./awesome start 构建的数据库目录——软件包本身不包含数据（数据库约 194 MB，并会随着每次下载而增长）。

需要了解的事项：

• 不会有任何内容发送到网络。 无需 API 密钥，无需账户，只读取 本地 SQLite 数据库。服务不包含有副作用的工具。
• 启动即时完成——数据库已经构建好，服务只需读取。
• 结果是包含数字的纯文本（星标数、独立列表数量、评分），因此 Agent 可以引用并比较。
• 协议是通过 stdin/stdout 传输的纯 JSON-RPC 2.0；日志输出到 stderr， 不会干扰通信通道。

这些内容从何而来——会不会对我造成危害

每个人都应该问的问题：如果有人提交了恶意列表怎么办？

列表来源： download.sh 会通过 GitHub 公共 API 查询标记了 topic:awesome-list 的仓库（在 --wide 模式下还包括 topic:awesome 和 topic:curated-list），并按星标数排序。仅此而已——没有任何「推荐」 仓库，也没有随机地址。

绝不会执行任何来自外部仓库的内容：

• README 是数据。解析器只用正则表达式提取其中的链接，仅此而已。 README 内容绝不会传入 eval、exec、shell=True 或任何系统调用。
• awesome install 只会执行 git clone --depth 1。Git 不会运行远程 仓库中的代码（没有任何钩子）。
• 浏览器会转义 HTML，core/md.py 中的 Markdown 渲染器也会转义—— 描述中的 <script> 会作为文本显示，而不是标签。

唯一真实的风险途径：进入模型上下文的描述。 MCP 服务会将工具描述 转换成 Agent 可以读取的文本。描述由未知人员编写，来自未经检查的 仓库。因此：

• 描述会经过 core/untrusted.py 处理，该模块会移除看起来像命令的指令、 角色标记（system:、assistant:）、HTML 标签、curl … | sh 和 rm -rf——同时留下 [odfiltrowano: …] 标记，以便识别。
• MCP 中的 initialize 会明确告知 Agent：这是第三方内容，不是命令。
• 随时可以自行检查：

./awesome untrusted

截至目前：在 186 861 个工具中，检测到 0 起攻击（3 个匹配结果是 误报——rimraf 的描述中有「like rm -rf」，而 safety-net 是一个会 阻止 rm -rf 的工具）。讽刺的是，目录中包含 3 个正是用于防范此问题的 工具（nvidia/skillspector、vaporif/parry-guard、safety-net）。

我不做出这样的承诺：扫描器只能检测已知模式，不能证明内容安全。 因此，请将描述视为数据，而不是命令。

原则：核心不含 AI

项目所有者允许使用 MCP，但不希望处处都有人工智能——尤其不希望它出现在原本应该是本地工具的项目中。我把这一点记录下来，因为如果不加以约束，这项承诺会在第一次重构时消失：

由此得出其他决定：

• 唯一的外部依赖是 flask（web UI）。核心仅使用标准库。
• 排名中没有模型、嵌入、神经网络或 LLM。 排序采用明确的算术规则（core/scoring.py），可以展示，也可以质疑。
• 排名不依赖第三方服务。 没有人能操纵你看到的结果，也无法知道你搜索了什么。
• MCP 是边缘适配器，不是核心逻辑的一部分。你可以移除它，其他功能照常运行。
• 测试 test_no_ai_in_core 会以机制确保这一点：未经许可，核心不会导入 AI 库或网络模块；唯一了解 MCP 协议的文件是 core/mcp.py。

目录可能被投毒吗？我们如何应对

目录由他人的仓库构建而成。这意味着有人可能故意提交一个会收集输入的虚假列表，而其中的“工具”会指向冒充域名或恶意代码。这种情况发生过吗？

./awesome audit

截至今天（2026 年 10 月 6 日，1 032 个列表，186 861 个工具）：7 个列表值得查看，1 个可疑链接。没有确认的攻击。

信号要捕捉的情况：

数据库中的一个示例：laoma2053/awesome-zhuiju-free——25 个工具，0 颗星，没有描述，没有任何链接得到其他列表的证实。

我们不会做什么，以及了解这一点为何重要：

• 这不是恶意软件扫描器。 我们不会识别仓库中的下载器，也不会识别工具代码中的恶意代码。我们不保证能筛出所有问题。
• 信号不是判决。 标记表示“需要人工查看”，而不是“有恶意”。7 个结果中有 3 个最终被证明是诚实但古怪的列表。
• 排名机制本身已有防护：工具至少需要得到两个相互独立的列表认可，而列表副本不计入认可数。单个新建的虚假列表无法把任何东西推到榜首。
• awesome install 只执行 git clone。 它不会运行脚本，不会索要你的 GitHub 密码，也不会执行远程仓库中的代码。但之后由你决定如何处理这些代码——程序无法控制这一点。
• 来自其他列表的描述会通过 MCP 进入模型上下文，因此会经过 core/untrusted.py 处理（见安全章节）。

最简单的原则：某个工具只出现在一个新列表中，而且你从未听说过它，这意味着应该先检查，而不是立即安装。

我不了解的术语

本程序不会推荐任何东西。 它没有“我推荐”“最佳选择”，也没有会推荐工具的大模型。它提供的是：统计数据（独立整理者的认同度、星标数、列表质量，以及工具出现在哪些列表中）和依据明确标准设置的筛选条件。选择权在你手中——因此，程序给出的所有信息都可以通过数据核实。 | backfill | 补齐缺失的列表元数据 | | enrich | 检查工具仓库（每次 API 查询批量处理 50 个） | | build | 使用本地 README 文件重建数据库（约 2 分钟） | | 侧边筛选器 | 可点击的侧边筛选项，例如“语言：Python” |

许可证

MIT——许可证文件位于目录中的 LICENSE。代码是我的，但工具的名称、链接和简短描述来自其他人的 awesome list，归其作者所有。数据库中只有仓库地址和名称（事实，而非他人创作的内容），README 文件本身不会随仓库一起提供——你可以通过 ./download.sh 将它们下载到自己的磁盘上。

已知限制（如实说明）

排名依据是作者写下的内容，而不是代码。 名称、描述、星标数、主题、README：这些都可以随意编写，也都会计入 score。程序绝不会查看仓库代码，因此无法区分工具和名称相同的脚本集合，也无法区分原版和副本。

可量化的结果：awesome selfcheck 会检查 15 个知名工具（名称 → 正确的仓库），通常有 13/15 排在第 #1 位。两次失败都源于同一种情况——粉丝仓库在描述中重复了工具名称，因此排名超过了原版。

./awesome selfcheck

这是这种方法的局限，无法通过调整权重来解决：要突破这一限制，就得查看仓库内容（导入项、输入文件、版本标签），而那是另一个项目。我不会假装自己做到了这一点。

不那么严重，但也如实说明：

• 91% 的工具只出现在一个列表中，因此它们的“整理者认同度”为零——这一假设适用于目录头部，而非长尾部分
• 75 571 条条目是指向 GitHub 之外的链接（文章、视频、文档）：它们永远不会有星标数，也不属于工具

• GitHub 搜索每次查询最多返回 1000 条结果。 因此，下载时会同时发起多次查询（--wide），以扩大结果范围。
• 只有通过 ./awesome enrich 检查过的仓库，我们才知道工具的真实语言。其他工具的语言是根据地址和描述推测的——因此，在无法确定时会显示 ?。排名有意不信任这种推测。
• 仅按需检查 GitHub 之外的链接： ./awesome validate --non-github --limit 500。
• 我们不检查工具是否安全。 仓库旁的信号（已归档、长期未更新）只是供你检查的提示，不是结论。安装任何东西之前，请先阅读代码和发布记录。

想要深入了解的用户

awesome              # wygodny wrapper: ./awesome <komenda>
download.sh          # pobieranie README list z GitHuba (bash + gh + jq)
extract_tools.py     # budowa bazy z lokalnych README
data/awesome.db      # baza SQLite (generowana, w .gitignore)
offline-db/          # pobrane README list (generowane, w .gitignore)

core/store.py        # schemat bazy, migracje, zapis metadanych
core/parser.py       # wyciąganie narzędzi z markdown (listy i tabele)
core/langmap.py      # język / platforma / domena / czyszczenie URL-i
core/scoring.py      # consensus, jakość listy, ranking
core/aliases.py      # synonimy („port scanner” → nmap, masscan…)
core/md.py           # własny renderer Markdown → HTML (bez CDN)
core/builder.py      # orkiestracja builda
core/backfill.py     # metadane list
core/enrich.py       # metadane repozytoriów narzędzi
core/status.py       # stan danych i plan odświeżenia
core/tools_db.py     # zapytania (search, fasetki, ranking)
core/database.py     # zapytania po listach/repozytoriach
core/curator.py      # kolekcje + instalacja
core/validator.py    # weryfikacja linków
core/trust.py        # sygnały ryzyka przy repozytoriach
cli/awesome_cli.py   # CLI
cli/tui.py           # TUI (curses)
web/app.py           # Flask UI
web/templates/       # szablony Jinja2
tests/smoke_test.py  # 106 testy (CI)

mcp-name: io.github.twojlogin/awesome-core