Jinni

🚀 Jinni 項目指南

Jinni 項目旨在為開發者提供便捷的文件處理和上下文管理功能，通過靈活的規則配置，能夠精準地控制哪些文件被納入上下文，有效解決上下文大小限制等問題。

🚀 快速開始

在使用 Jinni 前，你需要了解一些基本的配置和規則應用邏輯。下面將詳細介紹項目根目錄的設置、規則應用的流程以及如何處理上下文大小錯誤等關鍵信息。

✨ 主要特性

• 靈活的根目錄配置：可自定義項目根目錄，決定文件上下文範圍。
• 多樣化的規則應用：支持覆蓋規則和動態上下文規則，滿足不同場景需求。
• 上下文大小錯誤處理：提供詳細的錯誤信息和多種解決方法。
• 豐富的配置方式：可通過命令行參數或 MCP 客戶端進行配置。

📦 安裝指南

文檔未提及安裝步驟，暫不提供相關內容。

💻 使用示例

基礎用法

在開發環境中運行服務器模塊，可使用以下命令：

python -m jinni.serve serve --root /path/to/your/project_root

高級用法

若需要調整 Python 路徑，可以根據實際需求修改環境變量。

📚 詳細文檔

項目根目錄

• 參數設置：使用 --root 或 root 可指定項目的根目錄。若未指定，默認使用 MCP 客戶端中配置的路徑。
• 作用說明：該設置決定了哪些文件可以被包含在上下文中，並作為所有相對路徑計算的基礎。

規則應用邏輯

1. 確定目標：Jinni 會識別出處理的目標目錄，該目錄可以由用戶提供，也可以是項目根目錄。
2. 覆蓋檢查：若使用了 --overrides（命令行接口）或 rules（MCP），這些規則將被優先使用，同時忽略所有 .contextfiles 和默認規則。路徑匹配基於目標目錄。
3. 動態上下文規則（無覆蓋）：處理每個文件或子目錄時，Jinni 會從目標目錄開始向下查找所有 .contextfiles，直至當前項的目錄。然後將這些發現的 .contextfiles 規則與默認規則結合，編譯成一個規範（PathSpec），並匹配當前文件/子目錄的相對路徑（基於目標目錄計算）。
4. 匹配規則：最後一個匹配當前項相對路徑的模式決定其命運，! 表示否定匹配。若沒有用戶定義的模式匹配，則包含該項，除非它與默認排除（如 !.*）匹配。
5. 目標處理：顯式提供的文件會跳過規則檢查，顯式提供的目錄成為其內容規則發現和匹配的根。輸出路徑始終基於原始 project_root。

上下文大小錯誤 (DetailedContextSizeError)

• 問題描述：當包含的上下文大小超過限制時，Jinni 會提供一個包含 10 個最大文件的列表，這些文件是被嘗試包含的。
• 解決方法：
  1. 審查 largest 文件：檢查錯誤信息中的文件列表，判斷是否有大文件（如數據文件、日誌、構建產物、媒體）不應該成為 LLM 的上下文。
  2. 配置排除：使用 .contextfiles 或 --overrides / rules 來排除不必要的文件或目錄。例如，在 .contextfiles 中排除所有 .log 文件和特定的大數據目錄：

# 排除所有日誌文件
!*.log

# 排除一個大數據文件目錄
!large_data_files/

3. 增加限制（謹慎使用）：若所有包含的文件都是必要的，可以使用 --size-limit-mb（命令行接口）或 size_limit_mb（MCP）來增加大小限制。但需注意 LLM 上下文窗口限制和處理成本。
4. 使用 jinni usage / usage：若需要再次查閱這些說明或配置細節，可使用 jinni usage 命令或查看 usage 文檔。

配置文件

• 覆蓋規則：使用 --overrides 參數指定自定義的 .contextfiles 文件路徑，以覆蓋默認行為。
• MCP 配置：在 MCP 客戶端中設置 rules 屬性為一個數組，包含要排除或包含的具體路徑。

🔧 技術細節

規則應用的技術實現

Jinni 的規則應用邏輯基於目標目錄的確定、規則的覆蓋檢查和動態上下文規則的計算。通過查找 .contextfiles 並與默認規則結合，編譯成 PathSpec 進行路徑匹配，確保規則的準確應用。

上下文大小錯誤處理機制

當上下文大小超過限制時，Jinni 會分析包含的文件，提取 10 個最大文件的信息，並提供相應的解決方法，幫助用戶解決問題。

📄 許可證

文檔未提及許可證信息，暫不提供相關內容。

💡 使用建議

• 在配置規則時，建議先進行小規模測試，確保規則的正確性。
• 處理上下文大小錯誤時，優先審查大文件，避免不必要的文件被包含。
• 增加上下文大小限制時，要充分考慮 LLM 的上下文窗口限制和處理成本。

⚠️ 重要提示

• 運行服務器模塊時，若需要調整 Python 路徑，請謹慎修改環境變量，避免影響其他程序的正常運行。
• 遇到未列出的問題時，請及時參考項目文檔或聯繫維護團隊，避免自行處理導致問題惡化。