image-similarity-search —— Cocos Creator 3.x 图搜资源插件
你是不是也遇到过这个场景
项目做了大半年，公共资源目录堆了几千张碎图。美术甩给你一张效果图：“这个按钮用的是之前那张图，你找一下。”
然后你打开 assets/common/，翻了二十层文件夹，文件名全是 btn_close.png、icon_lock.png、bg_01.png，根本分不清哪张是哪张。问美术，美术说"我忘了放哪了，你找找"。
image-similarity-search 就是来解决这个痛点的：复制效果图截图，一键反查工程内相似图片资源，不用再靠文件名猜、靠文件夹翻。
实际效果
复制一张 Discord 半个图标的截图，搜索结果：
复制一把锁的 半个图标截图，搜索结果：
复制 KYC 带文本图标，搜索结果：
复制 Facebook 部分内容图标，搜索结果：
功能特点
-
剪贴板直接搜：复制截图后点「搜索剪贴板」或直接按
Ctrl+V，自动识别剪贴板图片并检索。 - 混合特征检索：CLIP 语义特征（ViT-B/32，512维）+ ORB 视觉词袋（128维）+ HSV 颜色直方图（64维）+ 空间分块（16维），拼成 720 维向量做余弦相似度检索。纯色图标、局部裁剪、带背景截图都能命中。
-
多路径检索：检索路径支持多个目录，用逗号分隔（如
db://assets/common, db://assets/icons）。 - 建立/刷新索引：首次使用先建索引，增量缓存秒级加载；资源有变动时点「刷新索引」强制重建。
- 相似度阈值可调：滑块控制严格程度，越高越严格（只找最像的），越低越宽松（结果更多）。
- 点击定位资源：结果卡片点击即在资源管理器中高亮定位，双击可预览大图。
- 暗黑/浅色双主题：右上角月亮/太阳按钮一键切换。
- 自动环境安装：首次打开面板引导安装 Python 环境，自动建 venv + 装依赖，不用手动配环境。
- 资源规模：支持几百到上万张碎图的资源库。千张图建库约 2~5 分钟，检索响应毫秒级，日常使用无压力。
- 支持 Cocos Creator 3.8.x（3.8.5 实测），开箱即用。
使用教程
首次使用
第一次打开面板，会提示安装运行环境：
点击「安装环境」，插件自动建 Python venv 并安装依赖（约 300MB），等待完成即可。
日常使用
-
建立索引：首次使用先点「建立索引」，插件自动扫描检索路径下所有图片并提取特征。首次会自动下载 CLIP 模型（约 600MB），耐心等待。索引缓存到本地，二次启动秒级加载。
-
配置检索路径：在「检索路径」输入框填要搜索的资源目录，多个路径用逗号分隔，如
db://assets/common, db://assets/icons。 -
复制效果图截图：从美术给的效果图里截图（可以只截局部图标，不需要完整边缘）。
-
搜索：点「搜索剪贴板」按钮，或直接按
Ctrl+V，插件自动识别剪贴板图片并返回相似结果。 -
定位资源：在结果卡片中点击对应图片，即在资源管理器中高亮定位到该资源文件；双击可预览大图。
配置说明
- 结果数量：控制返回多少条相似结果（默认 10，最多 200）。
- 相似度阈值：滑块调节，默认 0.40。数值越高只保留越相似的结果，数值越低返回更多但相似度一般的结果。搜不到时可降低阈值重试。
- 当前检索图：显示当前用于搜索的截图，可点「清除」清空。
问答环节
- 原理是什么？
回答：插件内置一个 Python 后端进程，用 OpenCLIP ViT-B/32 模型提取图片的语义特征向量（512维），叠加 ORB 局部纹理特征和颜色直方图特征，拼成 720 维混合向量。建库时对每张资源图提取向量并存入 FAISS 向量索引；搜索时对截图提取同样的向量，做余弦相似度检索返回 TopK 结果。
- 需要联网吗？
回答：首次建索引时需要联网下载 CLIP 模型（约 600MB），下载完缓存到本地。之后所有检索完全离线，不需要网络。
- 为什么搜不到？
回答：1. 检查检索路径是否正确；2. 降低相似度阈值滑块；3. 资源有新增变动时点「刷新索引」重建索引；4. 纯色/极简图标 ORB 特征少，CLIP 语义特征会兜底，但如果图案完全相同只是颜色微调，可能需要降低阈值。
- Python 环境怎么处理？
回答：插件首次打开面板时引导安装，自动检测本机 Python 3.11+，自动在插件目录下创建 venv 并安装依赖（numpy、opencv、faiss、torch、open_clip）。不需要手动配置 Python 环境。如果 torch 安装失败，插件自动降级为纯 ORB+颜色模式，基础功能仍可用。
- 索引缓存存在哪？
回答：存在插件目录下
python/.cache/，按检索路径哈希命名，不入库。删除后下次建索引自动重建。
- 支持哪些图片格式？
回答：png、jpg、jpeg、bmp、webp、tga、gif、tiff。
- 支持的编辑器版本？
回答：测试了 3.8.5，其他 3.8.x 版本原则上支持。
来吧,小宝贝, 快乐的
时光 