Icon Matcher

基于渲染结果对比的 CoDesign IconFont 图标匹配命令行工具。

给定一个 SVG 文件，自动从 CoDesign 图标库中找到最相似的图标，返回图标名称和相似度。

工作原理

1. 将 SVG 光栅化为位图
2. 计算感知哈希（pHash）指纹
3. 与索引中所有图标的指纹进行汉明距离比较
4. 返回相似度最高的匹配结果

安装

npm install
npm run build

快速开始

一键同步（推荐）

从 CoDesign 拉取图标并构建索引，一条命令搞定：

node dist/cli.js sync

运行后会交互式提示输入 Cookie（从浏览器 DevTools 复制），然后自动拉取图标列表并构建索引。

匹配图标

# 交互模式（推荐）
node dist/cli.js match

# 指定文件
node dist/cli.js match --file icon.svg

# 指定 SVG 内容
node dist/cli.js match --svg '<svg>...</svg>'

命令详解

fetch - 拉取图标列表

从 CoDesign API 拉取图标列表，交互式输入 Cookie。

node dist/cli.js fetch
node dist/cli.js fetch --output ./my-icons.json

| 参数 | 默认值 | 说明 | |------|--------|------| | --output <path> | .codesign-icons.json | 输出文件路径 |

build-index - 构建索引

将图标清单文件中的 SVG 光栅化并计算指纹，生成索引缓存。

node dist/cli.js build-index
node dist/cli.js build-index --manifest allIcons.json --force

| 参数 | 默认值 | 说明 | |------|--------|------| | --manifest <path> | .codesign-icons.json | 清单 JSON 文件路径 | | --cache <path> | .icon-matcher-cache.json | 缓存文件路径 | | --size <number> | 128 | 光栅化尺寸（像素） | | --force | - | 强制全量重建，忽略缓存 |

支持增量构建：仅对新增或变更的图标重新计算指纹。

match - 匹配图标

将输入的 SVG 与索引中的图标进行相似度匹配。

node dist/cli.js match
node dist/cli.js match --file test.svg
node dist/cli.js match --file test.svg --json

不提供 --file 或 --svg 时进入交互模式，支持粘贴 SVG 内容或输入文件路径。

| 参数 | 默认值 | 说明 | |------|--------|------| | --file <path> | - | SVG 文件路径 | | --svg <content> | - | SVG 内容字符串 | | --manifest <path> | - | 清单文件路径（缓存缺失时自动重建） | | --cache <path> | .icon-matcher-cache.json | 缓存文件路径 | | --top <number> | 5 | 返回结果数量 | | --threshold <number> | 0.85 | 相似度阈值 | | --margin <number> | 0.05 | 置信度边距 | | --size <number> | 128 | 光栅化尺寸（像素） | | --json | - | 以 JSON 格式输出 | | --force | - | 强制重建索引 |

search - 关键字搜索

按名称关键字搜索图标（模糊匹配）。

node dist/cli.js search arrow
node dist/cli.js search close --json

| 参数 | 默认值 | 说明 | |------|--------|------| | --manifest <path> | - | 清单文件路径 | | --cache <path> | .icon-matcher-cache.json | 缓存文件路径 | | --json | - | 以 JSON 格式输出 |

sync - 同步并构建

fetch + build-index 的组合命令。

node dist/cli.js sync
node dist/cli.js sync --force

| 参数 | 默认值 | 说明 | |------|--------|------| | --manifest <path> | .codesign-icons.json | 清单文件路径 | | --cache <path> | .icon-matcher-cache.json | 缓存文件路径 | | --size <number> | 128 | 光栅化尺寸（像素） | | --force | - | 强制全量重建 |

日常使用流程

# 首次使用：同步图标并构建索引
node dist/cli.js sync

# 之后匹配图标（索引已缓存，直接使用）
node dist/cli.js match

# 图标库有更新时，重新同步
node dist/cli.js sync

Cookie 获取方式

1. 浏览器打开 CoDesign
2. 打开 DevTools → Network
3. 随意点击一个请求，复制 Request Headers 中的 Cookie 值
4. 粘贴到命令行提示中

Cookie 一般有效期为数天到一两周，过期后重新复制即可。

开发

npm run build      # 编译 TypeScript
npm run test       # 运行测试
npm run typecheck  # 类型检查