开发者文档

FastFind 在自己电脑里的一个小型搜索服务器可以启动起来。这样其他程序就能获取搜索结果。

从 0.81 起，网页访问默认关闭。 需要在 设置 → 网页访问 中打开，下面的 REST API 才会开启。也有不打开就能连接的方法 — 命名管道 中有详细说明。

• 在 PowerShell、Python 脚本中获取文件列表
• 为自己的启动器或工具加上搜索
• 在结果右键菜单中 加入自己的功能（插件）

索引只存在于您的电脑内，不会外传。服务器也只在 127.0.0.1 上响应。

默认是 9090。可以在设置中更改。

不过必须打开网页访问才会开启。 关闭时，即使程序在运行，那个端口也不存在 — 因为根本不会创建监听套接字。

可以。直接放进 q 即可 — 与在搜索框中输入的语法相同。

GET /api/search?q=dupe:내용 ext:jpg
GET /api/search?q=dupe: path:D:\사진
GET /api/search?q=empty:

结果会 相同的排在一起。分组顺序始终一致，因此同一查询发两次也不会打乱顺序。

dupe:内容 会实际读取文件，因此比其他查询更慢。若候选超过 2 万个，就不再比较内容，而是在 error 中返回提示 — 因为不能以为结果就是全部而去删除。

http://127.0.0.1:9090

程序未运行时服务器也不存在。先用 /api/status 确认更安全。

不能让任何人都能抓取您的文件列表，因此没有令牌就不会响应。

请用以下两种方式之一发送。

令牌可在 /login 页面获取。只有这两个地址无需令牌即可打开。

POST /api/local-auth/login

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:9090/api/search?q=견적서%20ext:pdf&max=50"

要发送的内容

布尔值 1 0 true false on off yes no 都可以。不写值的 &raw 也视为开启。

ext: 用法

⚠ 从程序调用时请加上 raw=1 。

默认情况下会把一些词 会按人的习惯来理解。 这对人很方便，但程序调用时 查询会在无预警下被改变，因此结果看起来不对。

不过，只发送一个词时不会猜测类型。 q=photo 会查找文件名含 photo 的文件。下表在 词有两个或以上时（例如： photo 찾아줘）时适用。

GET /api/search?q=photo             → 이름에 photo 가 든 파일 (낱말 하나 — 짐작 안 함)
GET /api/search?q=photo 찾아줘      → 이미지 파일 전부 (낱말 둘 — 짐작함)
GET /api/search?q=photo 찾아줘&raw=1 → 이름에 photo 가 든 파일

ext: path: size: 等语法 raw=1 开启后仍然有效。 因为那不是猜测，而是您写下的原样。关闭的只有猜测。

我们的理解结果会包含在响应中。

"interpreted": {
  "keyword": null,                 // 실제로 찾은 낱말 (짐작으로 사라지면 null)
  "extensions": ["jpg","png", …],  // 걸린 확장자
  "guessed": true,                 // ← 참이면 짐작이 낱말을 삼킨 것입니다
  "guessed_words": ["photo"],      // 무엇 때문에 바뀌었는지
  "raw": false
}

guessed true 면 raw=1 重新调用即可 可以。

返回的内容

{
  "results": [
    {
      "name": "견적서_한빛건설.pdf",
      "path": "C:\\작업\\2026\\견적서_한빛건설.pdf",
      "size": 284915,
      "ext": "pdf",
      "modified": 1786012800,
      "is_dir": false
    }
  ],
  "total": 12,
  "time_ms": 5.3,
  "query": "견적서 ext:pdf"
}

total 是 符合条件的总数，results 是其中返回的部分。modified 是自 1970 年起的秒数。

查看索引是否就绪、包含多少条目。发送搜索前先确认这个，就能区分程序未运行还是仍在建立索引。

{
  "indexed_files": 4663246,
  "version": "0.86.0",
  "status": "ready"
}

响应中还会带有 engine、engine_gen、mem 等字段，但那是 我们排查问题时使用的值，会不经通知就变更。请勿依赖。

获取输入过程中要显示的候选项。只返回一个字符串数组。

GET /api/suggest?q=견적

["견적서_한빛건설.pdf", "견적서_양식.hwp", "견적_2026.xlsx"]

$t = "여기에 토큰"
$r = Invoke-RestMethod -Uri "http://127.0.0.1:9090/api/search?q=ext:log" `
     -Headers @{ Authorization = "Bearer $t" }
$r.results | Select-Object name, path, size | Format-Table

import requests, urllib.parse

TOKEN = "여기에 토큰"
q = urllib.parse.quote("견적서 ext:pdf")
r = requests.get(f"http://127.0.0.1:9090/api/search?q={q}&max=20",
                 headers={"Authorization": f"Bearer {TOKEN}"})
for f in r.json()["results"]:
    print(f["size"], f["path"])

以下接口也是开放的。但它们是 为我们自己的网页界面而做的，会不经通知就变更。若要使用，请 明白它们可能失效。

如果其中有您常用的，请 告诉我们。我们会优先把有人使用的移入承诺清单。

程序会在用户关闭时一并消失， 如果不开启网页访问，它根本就不会启动。 请不要认为它总是在运行。调用之前， /api/status 确认，若不可用则静默跳过，这样更安全。

如果不想让用户「在设置中打开」， 命名管道 ，请使用它。与网页访问无关，始终可用。

默认是 9090，但用户可在设置中更改。若要发布工具，请 让端口可询问或可配置。

也可以从设置文件中读取。

%LOCALAPPDATA%\FastFind\settings.json

/api/status 里面。 /api/version · /api/health · /api/info 是 没有(404).

要判断某功能是否可用时，请查看 /api/status 의 version 。

默认有 不收录的文件夹。它们是临时文件和系统文件夹，收录只会让结果变乱、索引变大。

这些扩展名 tmp · temp · bak · old · lnk · url 也不收录。

用户可以在 设置 → 索引范围 中修改这个列表，因此每台电脑可能不同。

从 0.81 起，网页访问默认关闭。因此要使用 REST API，就得请用户自己去打开这项设置，而这并不是一个好开口的请求。

请不要写 命名管道是存在的。与网页访问无关， 始终是开着的，，不会开启端口。

\\.\pipe\FastFind

在管道之上 之类的 REST 路由器原样叠在上面。所以路径、参数、响应都与上面说明的完全相同。 改变的只是通道 — 只要把 HTTP 请求写入管道并读取响应即可。

在 Windows 上，管道 就像普通文件一样 打开即可。不需要特殊的库。

GET /api/search?q=견적서 HTTP/1.1
Host: 127.0.0.1
Connection: close

Host 是 必须是数字地址。若填写名称则会被拒绝（这是为了防止 DNS 重绑定）。如果是修改值的请求， Sec-Fetch-Site: same-origin 也请一并加上。只读请求不需要。

Connection: close 를 ，请不要遗漏。 如果没有它，连接会一直保持，想读到最后的一方会永远等待。它表现为「卡住」而不是「不可用」，因此很难发现。

管道是一个实例对应一个连接。我们会预先打开多个，但请求集中时可能会短暂不够用。

2 常被理解为「不存在」而就此放弃，但 在这里表示「请稍等」的情况居多。两种情况都请稍作间隔重试几次（每次 10ms、共五次就够了）。若仍然 2 一直出现，那才是真的“没有 FastFind”。

仅限当前登录这台电脑的用户 才能连接。同一台 PC 上的其他账户不行，网络另一端也不行。

没有需要输入的账号或密码——Windows 会告知连接方是谁，因此我们只需在创建管道时写上一次「仅限此用户」。

它会 把您自己的功能加入 右键点击搜索结果时出现的菜单。

插件是 独立的可执行文件。我们不以 DLL 方式载入应用 — 别人的代码出错时，FastFind 不能跟着崩溃。因此您可以 用任何语言 编写。

FastFind → 플러그인 :  myplugin.exe --path "C:\\file.txt"
플러그인 → FastFind :  표준출력으로 JSON 한 덩어리

{"action":"message","title":"줄 수","text":"1,284줄"}
{"action":"copy","text":"복사할 내용"}
{"action":"open","path":"C:\\어딘가"}

它会数出所选文件有多少行并告诉您。

import sys, json
path = sys.argv[sys.argv.index("--path") + 1]
n = sum(1 for _ in open(path, encoding="utf-8", errors="ignore"))
print(json.dumps({"action": "message", "title": "줄 수",
                  "text": f"{n:,}줄"}, ensure_ascii=False))

把它编译成 exe 放到下面的位置，并在旁边放上 plugin.json。

%LOCALAPPDATA%\\FastFind\\plugins\\linecount\\
    run.exe
    plugin.json

{
  "id": "linecount",
  "name": "줄 수 세기",
  "description": "고른 파일의 줄 수를 셉니다",
  "version": "1.0.0",
  "author": "내 이름"
}

重新启动 FastFind 后，结果右键菜单中就会出现 统计行数。

会一起安装四个。编写时可作参考。

• 文件信息 — 大小、时间、属性
• 哈希 — 计算 SHA-256
• 图像信息 — 尺寸与格式
• 文本统计 — 行数、词数、字符数

我们如实说明。我们只承诺 本页面写明的内容。

程序内部还有更多接口，但大多是我们自己的网页界面在用。公开就意味着不能随意更改的承诺，因此这里 只列出稳定的那些。

新字段 可能会增加。这不会破坏现有内容，请让您的代码忽略不认识的字段。

• 没有官方库。 需要您自行通过 HTTP 调用
• 没有变更通知（Webhook）。 文件出现时没有渠道通知您，需要时得自行轮询
• 插件无法改变结果列表。 目前仅限于从右键菜单执行一件事

如果您有需要，请 告诉我们。只要有人用，我们就做。

不必使用服务器，也可以直接调用可执行文件。

FastFind.exe --console ext:log > list.txt

详情见 使用指南的命令行 一节。