開發者文檔

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

詳情見 使用指南的命令列 一節。