斑馬手冊 2.0

你的 AI 同事終於知道公司在幹嘛了

~1 小時 · 全員適用 · Hands-on

← → 或滑動切換

目標

讓每位同事知道：遇到什麼情境、該用哪個 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                  │
  └─────────────────────────────────────────────────────────────┘

核心循環

Search

Report

Curate

Learn

知識庫

越轉越好

Setup

安裝與設定

詳細步驟見 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

填入以下連線資訊：

變數	值
URL	`https://kb.zeabur.com`
API Key	`rak_e132e5a744f35cc1ab3014c697061baa550705783fcc1a0c3dddc276830d3415`

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

Part 1

知識庫現況

Source	說明
docs	Zeabur 官方文件
forum	論壇技術問答
zebra-manual	內部維運手冊
blog	部落格文章
changelog	更新日誌
skills	Skill 文件本身
learned	使用者貢獻（就是你！）

知識庫不是靜態的 — 每個人都能讓它變好。

Part 1

Dashboard 總覽

情境 1

遇到問題，先搜知識庫

/zeabur-rag-search

情境 1 — Search

什麼時候用？

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

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

也可以直接用自然語言問 Claude，它會自動搜知識庫。

情境 1 — Search

網頁介面

情境 1 — Search

怎麼看結果

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

Score	意思
> 0.035	高度相關 — 關鍵字和語意都命中
0.015–0.035	部分相關，需要自己判斷
< 0.015	可能沒有相關知識 — 這是一個 gap

搜完後可以繼續用中文追問，Claude 會保留搜到的內容作為上下文。

練習

練習：搜尋

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

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

觀察：

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

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

情境 2

解決了問題，把知識寫回去

/zeabur-rag-learn

情境 2 — Learn

什麼時候用？

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

/zeabur-rag-learn

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

情境 2 — Learn

網頁介面

情境 2 — Learn

什麼是好的貢獻

太模糊	好的
「可以設定 health check」	「Zeabur 預設每 10 秒送 `GET /`。要改路徑的話，設 `ZEABUR_HEALTH_CHECK_PATH=/health`。」

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

情境 2 — Learn

貢獻後會怎樣

立即被索引，可搜尋
被降權 ×0.7 直到 admin 驗證
驗證後與其他正式內容平等競爭

不用擔心寫錯 — admin 會 review，不對的會被退回。

練習

練習：貢獻知識

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

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

每人至少貢獻 1 條。

情境 3

搜到的結果有問題

/zeabur-rag-report

情境 3 — Report

什麼時候用？

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

/zeabur-rag-report

情境 3 — Report

網頁介面

情境 3 — Report

三種 Report 類型

Type	什麼時候用
`outdated`	以前是對的，但平台已經改了
`incorrect`	現在就是錯的
`missing`	這個主題完全沒有被收錄

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

練習

練習：回報問題

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

/zeabur-rag-report

每人至少回報 1 個。

情境 4

維護知識庫品質

Admin Skills

情境 4 — 維護

Step 1：看全局

/zeabur-rag-triage

看有多少待處理項目：

類別	說明
Open Reports	使用者回報的問題
Unverified Learned	貢獻的知識還沒驗證
Low Similarity Signals	搜不到好結果的 query
Negative Feedback	使用者給了負評的搜尋

需要 admin scope

情境 4 — 維護

Triage 介面

情境 4 — 維護

Step 2：逐一處理

/zeabur-rag-curate

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

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

情境 4 — 維護

輔助 Skill

處理過程中可能會用到：

Skill	用途
/zeabur-rag-inspect	看某個 chunk 的完整內容、report 記錄、編輯歷史
/zeabur-rag-edit	直接修改 chunk 的標題、內容、tags、visibility

需要 admin scope

情境 4 — 維護

Inspect 介面

情境 4 — 維護

Edit 介面

情境 4 — 維護

Demo

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

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

Dashboard

Query Signals

Dashboard

All Chunks

Dashboard

Reports

Dashboard

Learned

速查表

Skill 速查表

情境	Skill	權限
遇到問題，先搜	/zeabur-rag-search	所有人
解決後寫回知識	/zeabur-rag-learn	所有人
搜到錯的或缺的	/zeabur-rag-report	所有人
看 chunk 詳情	/zeabur-rag-inspect	Admin
直接改 chunk	/zeabur-rag-edit	Admin
看待處理清單	/zeabur-rag-triage	Admin
批次維護	/zeabur-rag-curate	Admin

日常習慣

1. 處理 ticket 前 → /zeabur-rag-search

2. 處理 ticket 後 → /zeabur-rag-learn（如果發現新知識）

3. 搜到怪結果 → /zeabur-rag-report

4. 每週 → /zeabur-rag-triage + /zeabur-rag-curate（admin）

附錄

Pipeline Adapters

資料怎麼進知識庫

附錄 — Adapters

資料來源與 Adapter

Adapter	來源	觸發方式
`docs`	zeabur/zeabur 官方文件（en-US）	git clone → markdown 解析
`forum`	論壇 MongoDB	直接讀 DB，只取已解決的帖子
`zebra-manual`	zebra-manual git repo	git clone → markdown + frontmatter
`blogs`	zeabur.com/blog	git clone zeabur-com repo
`changelogs`	zeabur.com/changelog	git clone zeabur-com repo
`skills`	Claude Code skill 文件	git clone → SKILL.md 解析
`learned`	使用者透過 /learn 貢獻	即時寫入，不需 pipeline

附錄 — Adapters

Chunking 怎麼切

Adapter	切法	目標大小
`docs`	按段落（`\n\n`）累積合併	~800 chars
`forum`	問題 → 一個 chunk，回答按段落切	~800 chars
`zebra-manual`	先按 `##` heading 分 section，再按段落切	~800 chars
`blogs`	按段落累積合併	~800 chars
`changelogs`	按段落累積合併	~800 chars
`skills`	按段落累積合併	~800 chars
`learned`	不切 — 使用者寫的就是一個 chunk	—

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

附錄 — Adapters

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

附錄

混合搜尋策略

為什麼搜得到

附錄 — 搜尋

兩路搜尋

	BM25（關鍵字）	Semantic（向量）
原理	tf-idf 詞頻統計	embedding cosine similarity
擅長	精確關鍵字、錯誤訊息、ID	語意相似、換句話說、跨語言
弱點	同義詞搜不到	精確字串可能漏掉
分詞	中文 `Intl.Segmenter`、英文 Porter stemmer	模型內建 tokenizer

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

附錄 — 搜尋

RRF 合併排序

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

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

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

參數	預設	說明
`keyword_weight`	0.25	BM25 的權重
`semantic_weight`	0.75	語意搜尋的權重
`decay`	180 天	時間衰減半衰期，越新的文件排越前

附錄 — 搜尋

搜尋品質評估

# 跑 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

指標	說明
Hit@5	前 5 筆有沒有命中正確答案
MRR	正確答案排第幾名（越前面越好）
nDCG@5	排序品質的綜合指標

附錄

項目	連結
內部專案	github.com/zeabur/zeabur-rag
公開專案	github.com/zeabur/rag-service
一鍵部署模板	zeabur.com/templates/H126IM
知識庫 Web UI	kb.zeabur.com
Skill 安裝說明	github.com/zeabur/zeabur-rag#skills

開始擴充知識庫吧！

每一次搜尋、回報、貢獻
都讓知識庫對所有人更好。

/zeabur-rag-search /zeabur-rag-learn /zeabur-rag-report /zeabur-rag-triage /zeabur-rag-curate

跳到指定頁面

斑馬手冊 2.0

你的 AI 同事終於知道公司在幹嘛了

目標

系統架構

核心循環

安裝與設定

知識庫現況

Dashboard 總覽

遇到問題，先搜知識庫

/zeabur-rag-search

什麼時候用？

網頁介面

怎麼看結果

練習：搜尋

解決了問題，把知識寫回去

/zeabur-rag-learn

什麼時候用？

網頁介面

什麼是好的貢獻

貢獻後會怎樣

練習：貢獻知識

搜到的結果有問題

/zeabur-rag-report

什麼時候用？

網頁介面

三種 Report 類型

練習：回報問題

維護知識庫品質

Admin Skills

Step 1：看全局

Triage 介面

Step 2：逐一處理

輔助 Skill

Inspect 介面

Edit 介面

Demo

Query Signals

All Chunks

Reports

Learned

Skill 速查表

日常習慣

Pipeline Adapters

資料怎麼進知識庫

資料來源與 Adapter

Chunking 怎麼切

Pipeline 執行

混合搜尋策略

為什麼搜得到

兩路搜尋

RRF 合併排序

搜尋品質評估

相關資源

開始擴充知識庫吧！

每一次搜尋、回報、貢獻都讓知識庫對所有人更好。

每一次搜尋、回報、貢獻
都讓知識庫對所有人更好。