讓 LLM 讀懂整個程式庫：用 Repomix 建立可控、可壓縮的程式碼上下文

AI 輔助開發最常見的問題，不是模型完全不會寫程式，而是它只看得到你貼進對話框的那幾個檔案。當問題牽涉到設定、資料流、共用型別、測試與部署腳本時，零散的片段很容易讓模型做出局部正確、整體錯誤的建議。

Repomix 的做法很直接：把一個程式庫依照規則打包成單一、適合 AI 處理的檔案，再交給 ChatGPT、Claude、Gemini 或其他工具分析。它不是另一個聊天機器人，而是 AI 程式碼工作流裡的「上下文準備層」。

截至 2026 年 8 月 20 日，GitHub 顯示 Repomix 約有 2.8 萬顆星，主要語言是 TypeScript，採 MIT License；官方最近一次 release 是 v1.18.0，且專案在 2026 年 8 月仍持續更新。這些數字會變動，本文的重點則放在它目前公開的 CLI、設定、壓縮與 MCP 能力。

先理解它解決的問題：上下文不是越多越好

把整個程式庫原封不動塞給模型，看起來像是「提供完整上下文」，實際上常常會遇到三個瓶頸：

檔案太多：node_modules、建置產物、快取、測試快照與產出檔案會稀釋真正重要的程式碼。
token 預算有限：不同模型的 context window 不同，沒有先估算就送出，可能在請求前被截斷，或在模型內部失去重點。
敏感資料不能外流：.env、測試憑證、私有設定或意外提交的 token，都不應因為「請 AI 幫忙看程式」而被一併分享。

Repomix 將這些事情集中在打包階段處理：它會遵守 .gitignore、.ignore 與 .repomixignore，支援 token 統計，並以 Secretlint 做敏感資訊檢查。這不代表輸出就自動安全；安全檢查是輔助，真正送出前仍要人工檢查內容。

五分鐘開始：先產生一份可檢查的輸出

在目標程式庫根目錄執行：

npx repomix@latest

預設會產生 repomix-output.xml。如果你想固定版本、在 CI 或團隊中重複使用，可以安裝成專案開發依賴，或依照官方文件使用全域安裝。第一次建議先不要急著把檔案貼給模型，而是先檢查輸出：

# 查看輸出檔大小與內容
wc -c repomix-output.xml
less repomix-output.xml

對於遠端公開儲存庫，也可以直接指定 GitHub URL 或 owner/repo：

repomix --remote yamadashy/repomix

若要讓結果可重現，使用固定的 branch、tag 或 commit，而不是永遠追蹤預設分支：

repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695

這個細節對技術研究與 bug 回報很重要：模型分析的內容應該能對應到一個明確版本。

用 include 與 ignore 控制上下文邊界

最實用的第一層控制是 glob pattern。假設你正在研究 TypeScript 的核心邏輯與文件，可以只打包相關檔案：

repomix --include "src/**/*.ts,**/*.md"

也可以在保留主要程式碼的同時排除 log 與暫存目錄：

repomix --ignore "**/*.log,tmp/"

這裡的觀念不是「排除越多越好」，而是先定義問題的邊界。例如：

做 API 重構：保留 src/、型別定義、路由、測試與相關文件。
查資料庫問題：再加入 migration、schema 與 repository layer。
查部署問題：加入 Dockerfile、CI workflow、環境設定範例，但排除真正的 secret。

若需要更細的團隊規則，可以執行 repomix --init 產生 repomix.config.json，把輸出格式、檔案篩選與安全選項納入版本控制。官方也支援 TypeScript、JavaScript、JSON5 與 JSONC 等設定形式；使用可執行的 JavaScript/TypeScript 設定時，務必把它當成程式碼審查，而不是單純資料檔。

不只是打包：四種輸出與 token 視角

官方 CLI 支援 xml、markdown、json 與 plain 四種輸出風格，預設是 XML。格式選擇可以依工具調整：

repomix --style markdown -o context.md
repomix --style json -o context.json
repomix --style plain -o context.txt

XML 方便保留檔案邊界與結構；Markdown 適合人工閱讀與貼到一般對話；JSON 適合由其他工具接續處理。不要把格式當成品質保證，真正重要的是檔案選擇與輸出是否仍落在模型的 token 預算內。

Repomix 提供檔案樹與 token 計數，還可以用門檻只顯示較大的檔案：

repomix --token-count-tree
repomix --token-count-tree 1000

如果你要把 token 預算變成 CI 的硬性護欄，可以使用：

repomix --token-budget 120000

官方說明指出，超過預算時輸出仍會產生，但 CLI 會以非零 exit code 結束。這使它適合放進 agent workflow 或 CI：不是等模型回覆「內容太長」，而是在送出前就讓流程失敗。

`--compress`：保留結構，縮小閱讀負擔

當程式庫很大，但你目前只需要理解模組邊界、類別、函式與介面時，可以使用 Tree-sitter 驅動的壓縮：

repomix --compress

它的目標不是把程式碼「摘要成自然語言」，而是抽取重要的程式結構，移除部分實作細節，讓模型先看懂骨架。這對第一輪架構盤點、尋找責任邊界或規劃重構很有用。

但壓縮輸出不適合取代所有原始碼閱讀。當模型要修改一個演算法、追查例外處理或確認競態條件時，仍應重新打包相關檔案的完整內容。比較穩定的策略是兩階段：

先用 --compress 加 token tree，建立全局地圖。
找到疑似相關的模組，再用 --include 產生小範圍、未壓縮的上下文。

這比一次把整個 repository 原封不動交給模型更容易控制，也更容易在 code review 中說明模型是根據哪些檔案做出判斷。

接到 MCP：把一次性檔案變成可查詢工具

如果你的 AI 開發工具支援 Model Context Protocol，Repomix 可以直接以 MCP server 執行：

repomix --mcp

官方文件列出的整合方式包含 VS Code、Cline、Cursor、Claude Desktop 與 Claude Code。以 Claude Code 為例：

claude mcp add repomix -- npx -y repomix --mcp

MCP 的價值在於把「準備一份檔案」轉成「由助手按需打包與查詢」。不過權限邊界會因此變得更重要。官方特別提供 sandbox 模式：

repomix --mcp --sandbox
repomix --mcp --sandbox path/to/project

在 sandbox 下，檔案工具會被限制在指定 workspace；絕對路徑、~、..、越過 symlink 的路徑等都會被拒絕。若 MCP server 可能被不受信任的 agent 或遠端 client 使用，sandbox 應視為預設，而不是事後補救。

更重要的是：不要把 --mcp 當成「AI 可以安全讀取整台主機」。它只解決工具協定與路徑限制，不能替你決定哪些程式碼可以送往第三方模型，也不能取代作業系統權限、網路隔離與 secret rotation。

安全檢查的正確用法

Repomix 預設啟用安全檢查，會用 Secretlint 偵測可能包含憑證格式的檔案，並在 CLI 輸出警告。這是一道很有用的防線，但不應被誤解為完整的資料防外洩方案。建議在送出前建立固定檢查清單：

# 先用專案規則排除常見敏感檔
repomix --ignore ".env,**/.env.*,**/secrets/**,**/*credential*"

# 再人工搜尋輸出中的可疑欄位名稱
rg -n "api[_-]?key|token|secret|password|private[_-]?key" repomix-output.xml

不要為了讓流程成功而隨意使用 --no-security-check。官方文件也提醒，關閉檢查可能暴露敏感資訊；即使是測試檔或範例憑證，也要確認它們不會與真實環境混淆。對遠端 repository 也要特別注意：官方預設不載入遠端儲存庫內的 repomix.config.*，因為 JavaScript/TypeScript 設定可能執行外部命令；只有在確認可信後，才考慮明確信任該設定。

我會怎麼把它放進 AI 程式碼流程

一個可維護的團隊流程可以長這樣：

問題定義
  ↓
決定上下文範圍與版本
  ↓
repomix --include / --ignore
  ↓
檢查安全警告與 token budget
  ↓
先以壓縮輸出做架構盤點
  ↓
針對相關模組產生完整上下文
  ↓
要求 AI 引用檔案與行為依據
  ↓
人工 review、測試、再提交

這個流程的重點不是讓模型「一次知道所有事情」，而是讓上下文可以被重現、被縮小、被檢查。每次送出的打包檔最好記錄 commit hash、使用的 include/ignore 規則與 token 統計；若模型提出修改，也要求它列出依據的檔案，方便人類驗證。

適合與不適合的場景

Repomix 適合：

想讓模型快速建立陌生程式庫的結構地圖。
需要把多個相互依賴的檔案交給 AI 做重構規劃。
想在 CI 或 agent workflow 中對上下文大小設限。
已有 MCP 工具鏈，希望讓程式碼探索更接近按需查詢。

它不會自動解決：

模型是否理解商業規則。
私有程式碼能否合法送到某個模型供應商。
分散式系統的即時狀態、外部資料庫內容或執行期 bug。
沒有測試、沒有 review 的程式碼品質問題。

換句話說，Repomix 是 context engineering 的基礎工具，不是自動重構的保證書。它最有價值的地方，是把「我要給 AI 看哪些程式碼」從臨時複製貼上，提升成一個有規則、有邊界、能在團隊中重複的工程步驟。

結語：先把上下文工程化，再談 AI 生成

AI 助手的輸出品質，常常受限於輸入上下文的品質。Repomix 用一個 CLI 將檔案篩選、格式化、token 觀察、結構壓縮、安全警告與 MCP 整合串起來，讓程式庫閱讀不必每次從手動貼檔案開始。

如果你只想試一次，從 npx repomix@latest 開始；如果你要在團隊或自動化流程中使用，則應進一步固定版本、審查 repomix.config.*、設計 ignore 規則、啟用 token budget，並在 MCP 場景加入 sandbox。當上下文準備變成可驗證的工程流程，AI 才比較可能從「看起來懂」走向「真的能被檢查」。