# 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+：

```powershell
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。

## 自动更新与常驻服务

```powershell
.\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 客户端启动命令：

```text
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 卷高速建索引时，才在管理员终端运行：

```powershell
.\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
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -InstallDir 'D:\Apps\MISAMA Search' -DataDir 'D:\MISAMA Search Data' -AddToPath
```

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

```powershell
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](BENCHMARKS.md)。中文质量集是人工编写的现实场景模拟，不是用户真实硬盘数据；合成百万向量结果也不等同于中文语义质量。

## 已知限制

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

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