目標

讓每位同事知道：遇到什麼情境、該用哪個 skill，
從今天開始就能幫知識庫變好。

不需要技術背景，會用 Claude Code 就行。

系統架構

  ┌─────────────────────────────────────────────────────────────┐
  │  資料來源                                                    │
  │  docs · forum · zebra-manual · blog · changelog · skills    │
  └────────────────────────┬────────────────────────────────────┘
                           │ adapter → chunk → embed
                           ▼
  ┌─────────────────────────────────────────────────────────────┐
  │  pgvector DB            7,400+ chunks · 1536-dim embedding  │
  └────────────────────────┬────────────────────────────────────┘
                           │ query
                           ▼
  ┌─────────────────────────────────────────────────────────────┐
  │  混合搜尋                                                    │
  │  BM25 關鍵字  +  Semantic 向量  →  RRF 合併排序              │
  └────────────────────────┬────────────────────────────────────┘
                           │
                           ▼
  ┌─────────────────────────────────────────────────────────────┐
  │  使用介面                                                    │
  │  Claude Code Skills · Web UI · MCP Server · HTTP API        │
  │  search · learn · report · triage · curate                  │
  └─────────────────────────────────────────────────────────────┘
    

一筆資料的一生

核心循環

安裝與設定

詳細步驟見 github.com/zeabur/zeabur-rag#skills

Step 1：安裝 plugin

claude plugin marketplace add zeabur/zeabur-rag
claude plugin install zeabur-rag@zeabur-rag

Step 2：設定連線

/zeabur-rag-setup

填入以下連線資訊：

驗證：跑 /zeabur-rag-search hello，有回傳結果就代表成功。

知識庫現況

7,841 chunks · 3,023 次搜尋 · 7 個來源

知識庫不是靜態的 — 每個人都能讓它變好。想想你手邊還有什麼知識可以加進來？

Dashboard 總覽

什麼時候用？

• 處理客戶問題
• Debug 時不確定某個行為
• 不確定某個功能怎麼用
• 想確認某件事有沒有文件

/zeabur-rag-search 怎麼設定 custom domain

大部分情況直接用自然語言問就好，Claude 會自動搜知識庫。

網頁介面

怎麼看結果

每筆結果旁會顯示 score，數字越高越相關：

搜完後可以繼續用中文追問，Claude 會保留搜到的內容作為上下文。
結果有用？給個 👍👎 回饋（網頁 UI 或 /zeabur-rag-feedback），幫助我們追蹤搜尋品質。

練習：搜尋

用自己最近遇過的一個真實問題搜看看。

/zeabur-rag-search <你的問題>

觀察：

• 結果正不正確？
• 有沒有過時的資訊？
• 有沒有 score 很低的？那就是知識缺口。

記下你搜到的問題，等等情境 3 會用到。

什麼時候用？

• 剛解完一張 ticket
• 踩到一個坑，花了時間才解決
• 發現一個 undocumented 行為
• 找到一個不在文件裡的解法

/zeabur-rag-learn

Skill 會引導你填寫標題、內容、tags。

網頁介面

什麼是好的貢獻

• 一個 chunk 只回答一個問題
• 只寫驗證過的事實，不寫猜測
• 為過去的自己而寫 — 你當初卡住時希望看到什麼

貢獻後會怎樣

1. 立即被索引，可搜尋
2. 被降權 ×0.7 直到 admin 驗證
3. Admin 用 /zeabur-rag-curate 或 /zeabur-rag-edit 審核
4. 驗證後與其他正式內容平等競爭

不用擔心寫錯 — admin 會 review，不對的會被退回。
審核不限網頁，用 skill 也行，但需要 admin 權限。

練習：貢獻知識

貢獻一條你知道但知識庫裡沒有的知識。

1. 先搜看看有沒有：/zeabur-rag-search <你的主題>
2. 沒有的話，貢獻：/zeabur-rag-learn

每人至少貢獻 1 條。

什麼時候用？

• 搜到過時的資訊
• 內容有錯
• 某個主題明明該有但搜不到

/zeabur-rag-report

網頁介面

三種 Report 類型

你不需要知道正確答案也能 report。
「這個 UI 按鈕已經不存在了」就是有用的回報。

練習：回報問題

回頭看情境 1 的搜尋結果，找一個值得回報的問題。

/zeabur-rag-report

每人至少回報 1 個。

Step 1：看全局

/zeabur-rag-triage

看有多少待處理項目：

需要 admin scope

Triage 介面

Step 2：逐一處理

/zeabur-rag-curate

進入互動式維護流程，一個一個 review：

• Report → 確認問題 → 編輯 chunk 或關閉 report
• Learned chunk → 正確就 verify（移除降權），不對就 reject
• Failed query → 找出缺口 → 用 /zeabur-rag-learn 補上

輔助 Skill

處理過程中可能會用到：

需要 admin scope

Inspect 介面

Edit 介面

Demo

講師示範處理剛才練習中產生的 report 和 learned chunk。

1. /zeabur-rag-triage — 看待處理清單
2. /zeabur-rag-curate — 逐一 review
3. /zeabur-rag-inspect — 檢查 chunk 細節
4. /zeabur-rag-edit — 修正內容

Query Signals

All Chunks

Reports

Learned

Skill 速查表

日常習慣

資料來源與 Adapter

Pipeline 可以隨時重跑更新，新的來源也可以持續加入。

Chunking 怎麼切

所有 adapter 共用同一個 chunker（src/pipeline/chunker.ts）：

每個 chunk 產生一個 1536 維的 embedding（text-embedding-3-small）存入 pgvector。

Pipeline 執行

# 更新單一來源
bun run scripts/cli.ts ingest --adapter docs

# 預覽不寫入
bun run scripts/cli.ts ingest --adapter docs --dry-run

# 全量替換（零停機）
bun run scripts/cli.ts ingest --adapter docs --replace

# 所有來源一次更新
bun run scripts/cli.ts ingest --all

每個 adapter 自動處理：取得原始內容 → 切 chunk → 產生 embedding → 上傳到 DB

兩路搜尋

兩路互補 — 關鍵字抓精確匹配，向量抓語意相關。

RRF 合併排序

score = keyword_weight / (K + keyword_rank)
      + semantic_weight / (K + semantic_rank)

預設權重：keyword 0.25, semantic 0.75, K = 20

不直接比分數，而是比排名 — 兩路都排前面的 chunk 分數最高。

搜尋品質評估

# 跑 eval
bun run scripts/eval.ts --mode hybrid --run-name <name>

# 比較兩次結果
bun run scripts/eval.ts --mode hybrid --run-name <name> \
  --compare data/eval-runs/<baseline>.json

搜尋策略 Roadmap

每一項改動都需要跑 eval 驗證，確保搜尋品質只進不退。

相關資源

後續可以做的事

• 每週 Triage + Curate — 指定 1-2 位 admin 定期維護，讓 report 和 learned chunk 不堆積
• 搜尋品質追蹤 — 每月跑一次 eval，追蹤 Hit@5 和 MRR 趨勢，確保改動有正向效果
• Graph Search 調校 — 實體關聯搜尋已建好（7,500+ entities），待調整權重後上線
• 搜尋回饋 — 搜完覺得有用按 👍、沒用按 👎，這些回饋會進 Dashboard 的 Negative Feedback，幫助找出搜尋盲點

Recap

• 知識庫有 7,400+ chunks，來自 7 個來源
• 搜 → 寫 → 報 → 維護，4 個情境 8 個 skill
• 每個人都能讓知識庫變好，不只是 admin 的事
• 你的回饋（👍👎、report、learn）直接影響搜尋品質