# 第一次搜尋

註冊資料庫、啟動 daemon、把檔案放進 inbox，再透過唯讀 HTTP API 查詢。

## 註冊資料庫

```bash
kura add my_docs
```

此命令會：

1. 將名稱中的連續空白合併為底線。
2. 建立 `~/.config/kuradb/my_docs/inbox/`。
3. 建立指向 inbox 的符號連結 `~/Kura_my_docs`。
4. 在 `~/.config/kuradb/db.json` 註冊 `my_docs`。

名稱已註冊或 `~/.config/kuradb/my_docs` 已存在時，命令會失敗。Daemon 執行期間新增的資料庫不會熱載入；查詢前必須重新啟動 KuraDB。

## 啟動 daemon

```bash
kura
```

前景 launcher 會啟動分離的 `--daemon` 程序，並等待 endpoint 檔案最多 10 秒。就緒後會印出類似下列 URL：

```text
http://localhost:43127
```

Daemon 會載入已註冊資料庫、從 SQLite 還原快取、為每個已載入資料庫啟動一個 watcher 與一個 embedding loop，並將唯讀 HTTP API 綁定至 `127.0.0.1`。若 endpoint 檔案未及時出現，launcher 會以錯誤結束，並指向 `~/.config/kuradb/daemon.log`。

## 索引檔案

```bash
cp document.md ~/Kura_my_docs/
```

Watcher 每 10 秒輪詢一次。變更的檔案會被解析並寫入 SQLite；embedding scheduler 每 5 秒輪詢一次，每批最多處理 64 個 pending chunk。Chunk 寫入後即可被關鍵字搜尋找到；完成 embedding 後才會出現在語意搜尋。

## 執行搜尋

讀取選定的 endpoint，並同時查詢兩種策略：

```bash
BASE="$(cat ~/.config/kuradb/endpoint)"
curl "$BASE/api/search?db=my_docs&q=什麼是RAG&limit=5"
```

使用 `target=keyword` 或 `target=semantic` 只執行單一策略：

```bash
curl "$BASE/api/search?db=my_docs&q=向量快取&target=semantic"
```

所有參數與 response 結構見[搜尋 API](/zh/api-reference-search)。