200行Python造一个搜索系统：awesome-reverse-engineered搜索排序算法逐行详解-平芜编程栈

200行Python造一个搜索系统：awesome-reverse-engineered搜索排序算法逐行详解

awesome-reverse-engineered 是一个收录 17,000+ 逆向工程开源项目的索引库，而支撑它的搜索系统只用约 200 行 Python、零第三方依赖写成——没有 Elasticsearch、没有倒排索引库，仅靠标准库的re、json、math就实现了字段加权、同义词扩展、热度加分和活跃度降权。本文逐行拆解这套搜索排序算法，让你学一套可以直接搬到自己项目里的轻量搜索方案。

一个数据文件 + 一个脚本 = 完整搜索系统

这个项目的搜索架构简单到出乎意料：

组成	文件	作用
数据	data/entries.json	17,000+ 条项目条目（纯 JSON 数组，CC0 协议）
引擎	mcp/re_index.py	约 200 行搜索 + 打分 + 排序逻辑
入口	CLI / mcp/reverse_engineered_mcp.py / plugin/skills/find-reverse-engineered/SKILL.md	人、AI Agent 三种用法共用同一引擎

每条数据就 10 个字段：name、url、desc、category、subcategory、stars、lang、license、pushed、topics等。搜索的全部难度不在数据，而在下面五个函数的写法。

第一步：数据加载与 24 小时缓存

load() 按优先级从三处取数据：环境变量RE_INDEX_DATA→ 本地缓存（24 小时内有效）→ 仓库自带的data/entries.json。网络拉取失败时自动降级到本地副本，并只在 stderr 打一条 note。这种"多级回退 + 静默降级"保证了离线也能用：

path = os.environ.get("RE_INDEX_DATA") # 1. 环境变量指定 if not fresh: # 2. 缓存超过 24h 就刷新 data = urllib.request.urlopen(RAW, timeout=20).read() for p in (CACHE, BUNDLED): # 3. 回退到本地文件 if os.path.exists(p): return json.load(open(p))

字段权重表：为什么项目名比描述"值钱"

fields() 把每条数据拆成 7 个带权重的文本字段——这是排序质量的第一个关键：

return [ (3.0, 项目名), # name (3.0, slug), # URL 末段，"-" 换成空格 (2.0, topics 拼接), (1.5, 一句话描述 desc), (1.0, subcategory), (1.0, category), (1.0, platform), ]

字段	权重	理由
项目名 / URL slug	3.0	命名最精确，搜`psd parser`时命中名字就该排最前
topics 标签	2.0	人工精选的关键词
描述 desc	1.5	自然语言，噪音较多
分类 / 子分类 / 平台	1.0	粗粒度，仅做辅助

命中同字段的所有文本按max取最高权重，避免"在描述里出现 10 次"刷分。

短关键词的词边界匹配规则

hit() 只有 4 行，却解决了一个经典坑——短词误匹配：

def hit(term, text): if len(term) <= 3: return re.search(rf"(?<![a-z0-9]){re.escape(term)}(?![a-z0-9])", text) is not None return term in text

词长 ≤3 时（如ps、x、ai）：用词边界正则，ps不会命中psd、x不会命中max；
词长 >3 时：直接子串匹配，速度更快，还能匹配bluetooth le这类短语片段。

同义词扩展：ps1 = playstation 1 = psx

SYNONYMS 是一张手写双向映射表：

SYNONYMS = { "twitter": ["x"], "x": ["twitter"], "ps1": ["playstation 1", "psx"], "ps2": ["playstation 2"], "ble": ["bluetooth"], "bluetooth": ["ble"], "car": ["vehicle", "automotive"], "chatgpt": ["openai"], ... }

打分时每个查询词会带上同义词一起检索，但同义词命中只算7 折（w * 0.7）——因为"直接搜到ps1"显然比"搜ps1命中了playstation"更可信。这比引入同义词词典或向量近邻便宜得多，且完全可控。

打分公式逐行拆解

score() 是整个搜索系统的心脏：

for t in terms: # ① 每个查询词独立打分 for alt in [t] + SYNONYMS.get(t, []): # ② 词 + 同义词 for w, text in fs: if hit(alt, text): best = max(best, w if alt == t else w * 0.7) # ③ 取最高权重，同义词 7 折 if not matched: return None # ④ AND 语义：任一词没命中 → 整条出局 total += 0.8 * math.log10((e.get("stars") or 0) + 1) # ⑤ 热度加分（对数压缩） if e.get("archived"): total -= 1.0 # ⑥ 归档仓库 -1.0 if pushed 早于 3 年前: total -= 0.5 # ⑦ 久不更新 -0.5 return (matched, total) # ⑧ 返回 (命中词数, 总分)

几个值得抄走的细节：

AND 语义：所有查询词都必须命中（至少一个同义词），否则返回None直接出局，不产生"沾边结果"；
对数热度加分：0.8 * log10(stars+1)。1000 星只加 2.4 分，6 万星加 3.8 分——热度能微调排名，但永远不会压过"名字精确命中"（3.0 分）这个最强信号；
活跃度降权：非官方 API 工具随厂商接口变动容易失效，归档（-1.0）和 3 年没提交（-0.5）会把僵尸项目压下去；
返回二元组(matched, total)：命中词数单独保存，给下一级的排序用。

过滤、排序与"完整匹配优先"

search() 把前面所有零件串起来，流程是硬过滤 → 打分 → 双键排序 → 分层截断：

# 硬过滤：分类子串匹配 / 语言精确匹配 / 最低星数 / 归档开关 if category and category.lower() not in (e["category"] + " " + e.get("subcategory", "")).lower(): continue res.sort(key=lambda x: (-x[0][0], -x[0][1])) # 先按命中词数，再按总分 full = [e for ... if m == len(terms)] # 所有词都命中 partial = [e for ... if m < len(terms)] # 部分命中 return (full + partial)[:limit], full # 完整匹配永远排在前面

排序键(-命中词数, -总分)保证了语义相关性 > 分数：搜 3 个词时，命中 3 个词的低分项目一定排在只命中 2 个词的高分项目前面。最后把结果分成"完整匹配 / 部分匹配"两层，CLI 在只有部分匹配时会明确提示no project matches all of: ...，让用户知道自己在看兜底结果。

fmt() 负责把结果渲染成"编号 + 星数 · 语言 · License · 最后提交 + 分类路径"的紧凑卡片，方便人和 Agent 都能一眼读完。

把 200 行脚本变成三种入口

同一个re_index模块被复用出三种用法：

命令行：零配置直接跑（用仓库自带数据）

RE_INDEX_DATA=data/entries.json python3 mcp/re_index.py search psd parser --lang Python RE_INDEX_DATA=data/entries.json python3 mcp/re_index.py search whatsapp --min-stars 500 --json RE_INDEX_DATA=data/entries.json python3 mcp/re_index.py categories

MCP 服务：mcp/reverse_engineered_mcp.py 用 stdio + JSON-RPC 把脚本包成 MCP server，暴露search_reverse_engineered、get_reverse_engineered_project、list_reverse_engineered_categories三个工具，Claude Code、Cursor 等 AI 客户端装好后即可让 Agent "先搜再逆向"；
Agent Skill：plugin/skills/find-reverse-engineered/SKILL.md 把搜索、选型（看归档/活跃度/License）、读 README、克隆的四步工作流写成了可执行的技能说明，配套的 plugin/skills/find-reverse-engineered/scripts/re_index.py 与 mcp 版本由 scripts/render.py 保持同步。

三个可直接复用的搜索排序设计

多字段加权 + max 取高：给不同文本字段设权重，同字段多次命中不叠加，防止长描述刷分；
AND 主排序 + 部分匹配兜底：严格结果和宽松结果分层展示，而不是混在一起糊弄用户;
对数热度 + 活跃度降权：log(stars)让热度只做微调，归档/停更惩罚让索引里的"死项目"自动沉底。

整套系统从加载、匹配、打分到排序只有约 200 行、一个文件、零依赖——如果你的项目需要给几千条 JSON 数据加一个"够聪明"的搜索，这套加权字段 + 词边界 + 同义词折减 + 双键排序的组合，远比上一套搜索引擎划算。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

200行Python造一个搜索系统：awesome-reverse-engineered搜索排序算法逐行详解