MISAMA Search 1.0

MISAMA Search 是一个 Windows 优先、完全本地、只读取文件和文件夹名称的语义搜索器。它不依赖 Everything，也不打开文件正文。

能做什么

• 精确名称、子串、中文二元组模糊匹配和父目录上下文排序；
• BGE-small-zh-v1.5 本地语义检索，例如“获奖经历”找到“简历”；
• USearch HNSW Int8 百万级向量索引，缺少原生模块时回退 Float32 精确检索；
• 稳定 uint64 文件 ID，新增、删除和改名进行增量向量更新；
• watch 自动监听子目录变化，不需要管理员权限；
• serve 提供只监听 127.0.0.1 的常驻 HTTP 服务，模型只加载一次；
• MCP stdio Server 和 MISAMA Agent Harness Tool 共用同一索引；
• 可选 Windows MFT 服务负责整块 NTFS 卷高速扫描，只有安装服务和读取原始卷需要管理员权限。

隐私边界

索引包含名称、路径、类型和本地向量，不包含文件正文。扫描、嵌入和排序均在本机完成。MCP 会把所选结果交给 MCP 调用者；MISAMA 云模型适配器默认关闭，只有用户执行 /privacy files on 后才返回最多 10 条相对路径、名称、类型和分数，绝不返回绝对路径、完整索引或向量。

快速开始（源码）

需要 Node.js 24+ 和 Go 1.24+：

npm.cmd ci
npm.cmd run model:install
go build -trimpath -o .\bin\misama-search.exe .\cmd\misama-search

.\bin\misama-search.exe scan -backend walk -index .\data\my.idx 'D:\要索引的目录'
.\bin\misama-search.exe semantic-build -index .\data\my.idx
.\bin\misama-search.exe search -index .\data\my.idx '原神角色文件夹'

模型约 23.3 MiB。下载后可设置 MISAMA_OFFLINE=1 完全离线；MISAMA_MODEL_DIR 可指定自定义或随身模型目录。npm.cmd run model:verify 会校验四个模型文件的固定 SHA-256。

自动更新与常驻服务

.\bin\misama-search.exe refresh -index .\data\my.idx
.\bin\misama-search.exe watch -index .\data\my.idx
.\bin\misama-search.exe serve -index .\data\my.idx -addr 127.0.0.1:37421

HTTP 搜索：POST /v1/search，JSON 为 {"query":"获奖经历","limit":5,"semantic":true}。服务拒绝绑定非回环地址。

MCP

MCP 客户端启动命令：

node D:\路径\MISAMA-Search\semantic\mcp-server.mjs

环境变量：MISAMA_SEARCH_INDEX、MISAMA_SEARCH_EXE；如果连接常驻服务，再设置 MISAMA_SEARCH_URL 和可选的 MISAMA_SEARCH_TOKEN。Tool 名称是 semantic_file_search。

可选 MFT 服务

普通工作区直接使用 walk + watch，无需服务。只有整块 NTFS 卷高速建索引时，才在管理员终端运行：

.\bin\misama-search.exe mft-service install -index 'D:\MISAMA-Data\whole-d.idx' 'D:\'
.\bin\misama-search.exe mft-service start
.\bin\misama-search.exe mft-service status
.\bin\misama-search.exe mft-service stop
.\bin\misama-search.exe mft-service uninstall

服务名是 MISAMASearchMFT。它只执行文件名元数据扫描与索引刷新，不运行云模型、MCP 或 Agent。

安装、升级与卸载

从发布压缩包解压后：

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -InstallDir 'D:\Apps\MISAMA Search' -DataDir 'D:\MISAMA Search Data' -AddToPath

再次运行同一安装命令即升级，独立 DataDir 不会被覆盖。卸载默认保留索引；只有显式增加 -RemoveData 才会删除：

powershell -ExecutionPolicy Bypass -File 'D:\Apps\MISAMA Search\scripts\uninstall.ps1' -InstallDir 'D:\Apps\MISAMA Search' -DataDir 'D:\MISAMA Search Data'

已测事实

• 100 条冻结中文场景：Recall@5 99%，MRR 0.945；
• 百万条 512 维 Int8 HNSW：P95 4.82 ms，Recall@10 95.5%；
• 常驻语义服务热查询：P95 4.54 ms；
• 常驻纯名称服务热查询：P95 0.252 ms；
• npm 生产依赖审计：0 漏洞（2026-08-20）。

硬件、方法和限制见 BENCHMARKS.md。中文质量集是人工编写的现实场景模拟，不是用户真实硬盘数据；合成百万向量结果也不等同于中文语义质量。

已知限制

• Windows 原生 MFT 后端仅支持 NTFS，并需要管理员权限；失败时 auto 回退目录遍历；
• watch 收到变化后会做名称元数据对账，大目录后续可继续升级为按 USN 事件直接更新；
• HNSW 容量用尽时自动全量重建，尚未实现双索引无停机切换；
• 首次模型下载需要联网，离线发布可把已校验的 models 目录单独分发。

许可证：项目源码 MIT。第三方组件见 THIRD_PARTY_NOTICES.md。