# 快速開始

編譯 `kura` 執行檔、註冊資料庫、啟動 daemon，並對丟進去的檔案做第一次關鍵字搜尋。

## 環境需求

| 項目 | 需求 | 原因 |
|---|---|---|
| 作業系統 | macOS（APFS/HFS+）或 Linux（ext4/xfs） | daemon 以 `setsid` 脫離終端，watcher 依賴 POSIX 檔案中繼資料 |
| Go | 1.25.1 以上 | `go.mod` 宣告 `go 1.25.1` |
| C 編譯工具鏈 | cgo 可用的任一編譯器 | SQLite 透過 `github.com/mattn/go-sqlite3` 存取 |
| `pdftotext` | 僅 PDF 檔需要（poppler-utils） | PDF 文字以 `pdftotext -layout -enc UTF-8` 擷取 |

## 編譯與安裝

```bash
git clone https://github.com/pardnchiu/KuraDB.git
cd KuraDB
make build
```

| Target | 執行內容 |
|---|---|
| `make build` | `go build -o bin/kura ./cmd/app` |
| `make app` | 停止執行中的 daemon、編譯、以 `sudo` 把執行檔移到 `/usr/local/bin/kura`、啟動 daemon |
| `make stop` | `go run ./cmd/app stop` |
| `make test` | `go test -v -count=1 ./...` |
| `make add <name>`、`make list`、`make remove <name>`、`make edit <old> <new>`、`make port <args>`、`make help` | 以 `go run ./cmd/app` 執行對應子指令 |

## 註冊資料庫並啟動 daemon

```bash
kura add notes
kura
```

`kura add notes` 會建立 `~/.config/kuradb/notes/inbox/`、建立捷徑 `~/Kura_notes`，並把名稱寫進 `db.json`。不帶參數執行 `kura` 會把 daemon fork 到背景並印出位址，例如 `http://localhost:21182`。

daemon 執行期間新增的資料庫，要等 daemon 重啟才會載入：

```bash
kura stop
kura
```

## 丟入檔案並搜尋

```bash
cp ~/Documents/design-notes.md ~/Kura_notes/
curl "$(cat ~/.config/kuradb/endpoint)/api/search?db=notes&q=sqlite"
```

watcher 每 10 秒掃描一次各 inbox，新檔案約 10 秒內即可搜尋。回應依來源檔案分組列出命中的段落：

```json
{
  "keyword": [
    {
      "source": "/Users/you/.config/kuradb/notes/inbox/design-notes.md",
      "matches": [
        { "chunk": 2, "content": "Second paragraph about SQLite" }
      ]
    }
  ]
}
```

要讓 agent 查詢同一份資料，在 MCP client 註冊 stdio MCP 伺服器，例如 Claude Code：

```bash
claude mcp add kura -- kura mcp
```

## 下一步

- [索引流程](/zh/indexing-pipeline)：丟入的檔案如何變成可搜尋的資料列
- [關鍵字搜尋](/zh/keyword-search)：查詢如何比對與排序
- [MCP 伺服器](/zh/mcp-server)：給 agent 用的 `list_rag` 與 `search_rag`
- [CLI 指令](/zh/cli-reference)：所有 `kura` 子指令