rekipedia 完整教學 — Codebase 變成 AI-Ready 知識庫

一份「裝起來就能用」的 internal tutorial，給團隊內部準備把 rekipedia 跑進工作流的同事看。 目標版本：v0.17.29 (2026-05-28)，MIT License。

1. 專案定位

rekipedia 是一套**把任何 codebase 掃成「AI agent 可 query 的知識庫」**的 CLI 工具。它做三件事：

1. Index：tree-sitter 抽出 symbols + relationships，存進 SQLite (.rekipedia/store.db)
2. Wiki：用 LLM (optional) 為每個 module / 重要 file 生成 markdown wiki page
3. Serve：透過 (a) CLI reki ask (b) web UI reki serve (c) MCP stdio server reki mcp 三種介面對外提供 Q&A

與類似專案的差異：

為什麼要關注：MCP server 直接給 Claude Code / Cursor 用，6 個 tool（ask / search_nodes / get_context / get_relationships / get_hub_nodes / get_impact）讓 agent 在「有 citation」的條件下回答 codebase 問題，理論上可以顯著降低 agent hallucination。

2. 安裝指南

2.1 PyPI 安裝（最簡單）

1pip install rekipedia
2# or
3pipx install rekipedia
4# or one-shot
5npx rekipedia

需求：Python 3.11+。

2.2 從 source 安裝（開發者用）

1git clone --depth 1 https://github.com/unrealandychan/rekipedia.git
2cd rekipedia
3pip install -e ".[dev]"
4# or with uv (推薦)
5uv sync

2.3 LLM 設定（optional but 推薦）

1export REKIPEDIA_API_KEY=sk-...        # OpenAI / Anthropic / OpenAI-compatible
2export REKIPEDIA_MODEL=gpt-4o          # 預設 gpt-4o
3# Ollama 範例
4export REKIPEDIA_API_KEY=ollama
5export REKIPEDIA_MODEL=ollama/llama3

--no-llm 可完全離線跑，只是 wiki 不會有 LLM-generated summary。

2.4 Docker Sandbox（optional，加強 isolation）

1docker build -f Dockerfile.sandbox -t rekipedia-sandbox:latest .

如果 sandbox image 不存在，rekipedia 會 fallback 到 LocalRunner（純 Python，無容器隔離）。

2.5 首次掃描

1cd <your-repo>
2reki scan .          # 全掃，生成 wiki + 知識庫
3reki embed .         # （optional）建立 FAISS 語義索引，啟用 hybrid RAG
4reki ask "what is the entry point of this codebase?"

知識庫位置：.rekipedia/store.db（純本地，不上雲）。

3. 核心架構解析

rekipedia 是個模組化 Python 套件，src/rekipedia/ 下有 17 個子模組。下圖標出主要資料流：

flowchart TD
    A[Codebase] -->|tree-sitter| B[extractors.py]
    B --> C[(SQLite store.db)]
    C --> D[analysis/]
    D -->|graph_analysis| E[hotspots / impact]
    C --> F[synthesis/page_builder]
    F -->|LLM via litellm| G[wiki/ markdown pages]
    G --> H[rag/embedder + FAISS]
    H --> I[orchestrator/run_ask]
    C --> I
    I --> J1[CLI: reki ask]
    I --> J2[Web UI: reki serve]
    I --> J3[MCP Server: reki mcp]
    K[.rekipedia/] -->|store| C
    K -->|wiki/| G
    K -->|embeddings/| H

3.1 子模組職責表

3.2 資料流（reki ask 路徑）

flowchart LR
    Q[User Question] --> A[orchestrator/run_ask]
    A --> S1[rag/vector_store FAISS]
    A --> S2[(SQLite store.db)]
    S1 -->|top-k chunks| M[LLM prompt]
    S2 -->|symbol:line| M
    M --> R[LLM via litellm]
    R --> O[Answer + file:line citations]

3.3 MCP Server 架構

src/rekipedia/cli/mcp_server.py（13KB）實作 stdio MCP server，提供 6 個 tool：

Claude Code / Cursor 透過 .mcp.json 自動發現，agent 直接呼叫這 6 個 tool。

4. Helper Scripts 詳細用法

rekipedia 沒有大量 helper script — 主要入口就是 reki CLI（24 個 subcommand）。逐項說明：

4.1 索引 / Build

4.2 Query / Read

4.3 Analysis / Refactor

4.4 Export / Integration

4.5 Makefile（開發者）

1make install       # uv sync
2make dev           # install runtime + dev deps
3make lint          # ruff / mypy / 寫報告
4make test          # pytest
5make test-cov      # pytest --cov
6make build         # Python wheel + npm tarball
7make docker-build  # 編 sandbox image
8make release       # PyPI + npm

4.6 scripts/lint-and-report.sh

唯一的 helper script（11.8KB），跑完整 lint pipeline（ruff / mypy / 整理報告）。make lint 內部呼叫它。

5. 應用場景

5.1 個人 dev 日常

1# 在新專案目錄
2reki scan .
3reki ask "where does database connection get initialized?"
4reki ask "what tests exist for the auth module?"

5.2 New hire 第一週

1reki onboard .      # 生成 onboarding doc
2reki tour           # guided walkthrough
3reki ask "如何在本地起 dev server？"

5.3 Refactor 前 due diligence

1reki hotspots                    # 找關鍵檔案，動之前先看
2reki impact src/core/engine.py   # 算下游影響
3reki refactor . --dry-run        # 預覽建議

5.4 Claude Code / Cursor MCP 整合

在 repo root 放 .mcp.json：

1{
2  "mcpServers": {
3    "rekipedia": {
4      "command": "reki",
5      "args": ["mcp"],
6      "cwd": "."
7    }
8  }
9}

Claude Code 啟動時自動發現，agent 之後問 codebase 問題會走 rekipedia 的 grounded answer 路徑。

5.5 CI / CD 整合

1# .github/workflows/wiki.yml
2- name: Update rekipedia wiki
3  uses: unrealandychan/rekipedia/action@v0.17.26
4  with:
5    api-key: ${{ secrets.REKIPEDIA_API_KEY }}

5/27 才剛 release 的官方 GitHub Action，把 reki update . 跑成 CI step，每次 push 自動 reindex wiki。

5.6 在本專案（AI-knowledge_template v1）整合的想法

• 可能取代 / 補充現有 Layer 4 graphify：rekipedia 更 codebase-centric，graphify 是 generic knowledge graph
• 可能補充 Layer 6 gitnexus：rekipedia 多了 LLM-generated wiki page + impact analysis
• 不建議直接取代：rekipedia LLM 呼叫成本不可忽略（每 scan 都會跑 page_builder 用 LLM），graphify / gitnexus 純靜態分析省 API cost

6. 資安掃描報告

6.1 掃描結論

6.2 整體結論

🟢 GREEN — 可在內部團隊使用。

• 沒有發現任何 RCE / SSRF / SQL injection 等高風險 pattern
• subprocess 與 Docker sandbox 設計合理，無 shell=True
• 機密透過 env var 處理，不留 trace
• 唯一需要注意：啟用 --apply flag 跑 reki refactor 會自動改 source code（5/26 新加的 feature），首次使用務必先 --dry-run 確認

6.3 給 internal 採用的建議

• 先在 sandbox repo 跑過一次 reki refactor . --dry-run + reki scan . 確認輸出
• LLM 呼叫透過 internal LiteLLM proxy（已有 REKIPEDIA_MODEL env 可指）
• 大型 repo 跑 reki scan 前先 du -sh . 預估 token cost（page_builder 對每個 module 都會呼叫 LLM）

7. FAQ

Q1: 沒有 LLM API key 能用嗎？ A: 可以。reki scan . --no-llm 跑完整 indexing + symbol graph，只是 wiki 沒有 LLM summary。Hotspots / impact / search 都不需要 LLM。

Q2: 知識庫多大？ A: .rekipedia/store.db 通常 5–50 MB（依 repo 大小）。FAISS embedding 額外 ~10–100 MB。

Q3: 支援哪些語言？ A: tree-sitter extractors 內建 Python / Go / TypeScript / Rust / Java。其他語言會被當 generic text 處理。

Q4: 跟 RAG 框架（langchain / llamaindex）差別？ A: rekipedia 是 codebase-specific，內建 symbol graph + impact analysis；langchain / llamaindex 是 generic RAG framework，需要自己寫 codebase 的 extractor 與 graph 邏輯。

Q5: 可以多人共用一個 store.db 嗎？ A: 設計上是 single-user single-machine。團隊共用建議用 reki export . --format zip 把 wiki + store 一起 commit 進 repo，或用 5/28 release 的 GitHub Action 讓 CI 跑 update。

Q6: 跑一次 reki scan 成本？ A: 以 gpt-4o 為例，10K 行 codebase ~ $0.5–2 USD。--no-llm 模式 $0。

Q7: 跟本專案 graphify Layer 衝突嗎？ A: 不衝突。graphify 偏 generic knowledge graph（適合多 source：code + docs + paper），rekipedia 純 codebase。可以同時用，職責互補。

8. 進階技巧

8.1 對特定 module 跑 ask

1reki ask "explain the orchestrator module" --scope src/rekipedia/orchestrator/

8.2 結合 git hook 自動更新

1reki hook install   # 寫入 .git/hooks/post-commit
2# 之後每次 commit 自動跑 reki update .

8.3 用 Ollama 完全離線

1export REKIPEDIA_API_KEY=ollama
2export REKIPEDIA_MODEL=ollama/qwen2.5-coder:14b
3reki scan .

8.4 把 wiki 變 GitHub Pages

1reki export . --format html --out docs/
2# 然後在 GitHub repo settings 開 Pages 指向 docs/

8.5 在 CI 跑 --impact-only 加速

1reki update . --impact-only --since HEAD~1

只重生最新一個 commit 影響到的 wiki page，CI 時間從幾分鐘降到幾秒。

9. 整合進其他工作流

9.1 與 Claude Code （MCP）

放 .mcp.json 後，Claude 在問「auth 在哪」前會自動呼叫 reki ask，回答帶 file:line citation。

9.2 與 paper-qa-lite (Layer 10)

paper-qa-lite 處理 paper PDF；rekipedia 處理 codebase。兩者完全互補，可以在同一個 research project 內並用：

• paper-qa-lite → 回答「論文裡怎麼說 X 演算法」
• rekipedia → 回答「我們專案哪裡實作了 X 演算法」

9.3 與 graphify (Layer 4)

graphify 跑完 graphify init . 產出 generic knowledge graph；rekipedia 跑完 reki scan . 產出 codebase wiki。兩個 output 都進到 agent context 後，agent 對 codebase 的回答品質會比單獨用任何一個都好（兩者 grounding source 不同）。

9.4 與 gh-tutorial-qd (Layer 12)

本份 tutorial md 即是 gh-tutorial-qd 的產出範例。rekipedia 不在 gh-tutorial-qd 上游 pipeline 內，但 rekipedia 的 README + AGENTS.md 是 gh-tutorial-qd 抓 metadata 的好標的。

10. 重點摘要 Checklist

• pip install rekipedia 或 npx rekipedia
• 設定 REKIPEDIA_API_KEY 與 REKIPEDIA_MODEL（或直接 --no-llm）
• cd <repo> && reki scan . 首次掃描
• reki embed . 建立 FAISS 索引（optional）
• 試問：reki ask "what is the entry point?"
• 放 .mcp.json 讓 Claude Code / Cursor 自動發現
• CI 加 GitHub Action 自動 update（v0.17.26+）
• Refactor 前先 reki hotspots + reki impact <file>
• 用 reki refactor . --dry-run 預覽後再 --apply

11. 進一步閱讀

• 主 README：https://github.com/unrealandychan/rekipedia#readme
• 中文 README：README.zh-TW.md
• AGENTS.md（agent 用法詳解）：https://github.com/unrealandychan/rekipedia/blob/main/AGENTS.md
• rekipedia-agent-skill.md（Claude skill 整合範例）：repo root
• GitHub Pages：https://unrealandychan.github.io/rekipedia/
• PyPI：https://pypi.org/project/rekipedia/
• MCP 規範：https://modelcontextprotocol.io
• 本專案相關 Layer：Layer 4 graphify、Layer 6 gitnexus、Layer 10 paper-qa-lite、Layer 12 gh-tutorial-qd