🚀 CICADA

代碼智能：上下文分析、發現與歸因

為AI代碼助手進行上下文壓縮 — 為你的AI提供對Elixir、Python和Erlang代碼庫的結構化、高效令牌訪問。

等待時間最多減少50% · 令牌使用最多減少70% · 解釋工作最多減少99% 更緊湊的上下文 = 更高的質量

快速安裝 · 安全隱私 · 開發者指南 · AI助手使用說明 · 文檔資料

🚀 快速開始

CICADA是一款專為AI代碼助手設計的工具，它通過上下文壓縮技術，為AI提供對Elixir、Python和Erlang代碼庫的結構化、高效令牌訪問，有效解決了AI代碼助手在搜索代碼時浪費上下文的問題。

✨ 主要特性

為何選擇CICADA？

核心問題：AI代碼助手 在盲目搜索上浪費上下文。當你只需要一個函數簽名時，Grep會轉儲整個文件，留給實際推理的空間就更少了。

上下文壓縮方法

CICADA不是進行原始文本轉儲，而是為你的AI提供結構化、預索引的知識：

你將獲得

• 抽象語法樹（AST）級索引 – 包含簽名、規範、文檔的模塊/函數/類定義。
• 完整的調用點跟蹤 – 跨Elixir和Python的別名、導入、動態引用。
• 語義搜索 – 按概念而非字面字符串查找代碼。
• Git + PR歸因 – 揭示代碼存在的原因，而不僅僅是代碼本身。
• 死代碼檢測 – 通過依賴分析進行安全重構。
• 自動語言檢測 – 無縫適用於Elixir和Python。

📦 安裝指南

安裝步驟

# 1. 安裝uv（如果需要）
# curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install cicada-mcp

# 在你的倉庫中
cicada claude   # 或者：cicada cursor, cicada vs, cicada gemini, cicada codex, cicada opencode

臨時試用

在永久安裝之前進行試用（索引質量較差，但無需安裝）。

uvx cicada-mcp claude   # 或者 cursor, vs

或者

claude mcp add cicada uvx cicada-mcp

gemini mcp add cicada uvx cicada-mcp

codex mcp add cicada uvx cicada-mcp

安裝後可用命令

• cicada [claude|cursor|vs|gemini|codex|opencode] - 每個項目一鍵交互式設置。
• cicada-mcp - MCP服務器（由編輯器自動啟動）。
• cicada status - 顯示索引狀態、PR索引、鏈接狀態、代理文件、MCP配置。
• cicada stats [repo] - 顯示使用統計信息（工具調用次數、令牌使用情況、執行時間）。
• cicada watch - 監視文件更改並自動重新索引。
• cicada index - 使用自定義選項重新索引代碼（-f/--force + --fast/--regular/--max, --watch）。
• cicada index-pr - 為PR歸因索引拉取請求。
• cicada find-dead-code - 查找可能未使用的函數。
• cicada run [tool] - 直接從命令行界面執行7個MCP工具中的任何一個。
• cicada agents install - 將Claude代碼代理安裝到./.claude/目錄。
• cicada link [parent_dir] - 將當前倉庫鏈接到現有索引。
• cicada clean - 從你的文件夾中完全移除CICADA集成以及所有設置。

詢問示例

你可以向助手提出以下問題：

# Elixir
"Show me the functions in MyApp.User"
"Where is authenticate/2 called?"

# Python
"Show me the AuthService class methods"
"Where is login() used in the codebase?"

# 兩種語言
"Find code related to API authentication"

💻 使用示例

基礎用法

你可以使用以下命令進行基本的配置和索引操作：

# 配置MCP並增量重新索引
cicada claude

# 檢查索引健康狀態、鏈接狀態、代理文件
cicada status

# 查看使用統計信息和令牌指標
cicada stats

# 監視文件並在更改時自動重新索引
cicada watch

# 強制使用語義關鍵字進行完全重建
cicada index --force --regular .

# 同步PR元數據/審查
cicada index-pr .

# 列出未使用的公共函數
cicada find-dead-code --min-confidence high

高級用法

啟用PR歸因（可選）

brew install gh    # 或者 apt install gh
gh auth login
cicada index-pr .     # 增量
cicada index-pr . --clean   # 完全重建

啟用後，你可以解鎖諸如“哪個PR引入了第42行？”或“審查者對billing.ex有什麼評價？”之類的問題。

自動重新索引（監視模式）

通過使用--watch標誌啟動MCP服務器，在文件更改時啟用自動重新索引：

{
  "mcpServers": {
    "cicada": {
      "command": "cicada-mcp",
      "args": ["--watch"],
      "env": {
        "CICADA_CONFIG_DIR": "/home/user/.cicada/projects/<hash>"
      }
    }
  }
}

當監視模式啟用時：

• 一個單獨的進程會監視.ex、.exs（Elixir）和.py（Python）文件的更改。
• 更改會自動重新索引（增量、快速）。
• 2秒的去抖動防止在快速編輯期間進行過多的重新索引。
• 當MCP服務器停止時，監視進程會自動停止。
• 排除的目錄：deps、_build、node_modules、.git、assets、priv、.venv、venv。

🔧 技術細節

隱私與安全

• 100%本地處理：解析和索引在你的機器上進行，無需外部訪問。
• 無遙測數據：CICADA不會收集使用情況或任何遙測數據。
• 只讀工具：MCP端點僅讀取索引，無法更改你的倉庫。
• 可選的GitHub訪問：PR功能依賴於gh和你現有的OAuth令牌。
• 數據佈局：

~/.cicada/projects/<repo_hash>/
├─ index.json      # 模塊、函數、調用點、元數據
├─ config.yaml     # 索引選項 + 關鍵字層級
├─ hashes.json     # 增量索引緩存
└─ pr_index.json   # 可選的PR元數據 + 審查

你的倉庫只會增加一個編輯器配置（.mcp.json、.cursor/mcp.json、.vscode/settings.json、.gemini/settings.json、.codex/mcp.json或.opencode.json）。

開發者指南

安裝與配置

cd /path/to/project
cicada claude   # 或者 cicada cursor / cicada vs / cicada gemini / cicada codex / cicada opencode

啟用PR歸因（可選）

brew install gh    # 或者 apt install gh
gh auth login
cicada index-pr .     # 增量
cicada index-pr . --clean   # 完全重建

命令行工具速查表

故障排除

2. **檢查路徑是否為絕對路徑**：
```bash
cat .mcp.json
# 應包含：/absolute/path/to/project
# 而不是：./project 或 ../project

ls -la ~/.cicada/projects/
# 應顯示你的項目目錄

**常見問題**：
- "No PR index found" → 運行`cicada index-pr .`
- "Not a GitHub repository" → 確保倉庫有GitHub遠程地址
- 索引緩慢 → 首次索引會獲取所有PR；後續運行是增量的
- 速率限制 → GitHub API有速率限制；如果達到限制，請等待並重試

**強制重建**：
```bash
cicada index-pr --clean

更多詳細信息：docs/PR_INDEXING.md，docs/08-INCREMENTAL_INDEXING.md。

# 確保排除.venv
echo "/.venv/" >> .gitignore

# 使用--fast層級進行更快的索引
cicada index --fast .

AI助手使用說明

CICADA提供了7個專注於MCP的工具，旨在跨Elixir、Python和Erlang代碼庫進行高效的代碼探索。

選擇合適的工具

想查看這些工具的實際操作嗎？ 查看 完整工作流示例，其中包含專業提示和實際場景。

核心工具

• query - 智能代碼發現（你的起點）
  • 自動檢測關鍵字與模式。
  • 過濾器：scope（公共/私有）、recent（最近14天）、filter_type（模塊/函數）、match_source（文檔/字符串）。
  • 返回帶有智能下一步建議的代碼片段。
  • 使用path_pattern按位置過濾。
• search_module - 深度模塊分析
  • 查看完整的API：函數、簽名、規範、文檔。
  • 對於Python：顯示帶有方法計數和簽名的類。
  • 對於Elixir：顯示帶有元數表示法的函數。
  • 雙向分析：
    • what_calls_it=true → 查看誰使用了這個模塊（影響分析）。
    • what_it_calls=true → 查看這個模塊依賴於什麼。
  • 支持通配符（Elixir: MyApp.*, Python: api.handlers.*）和OR模式 (MyApp.User|MyApp.Post)。
  • 按可見性（公共/私有/全部）過濾。
• search_function - 函數使用跟蹤
  • 查找定義和所有調用點。
  • what_calls_it=true（默認） → 查看所有調用者。
  • what_it_calls=true → 查看所有依賴項。
  • 使用include_usage_examples=true包含代碼示例。
  • 按usage_type過濾：源文件、測試文件或全部。

Git歷史（統一工具）

• git_history - 所有git操作集成在一個工具中
  • 單行：git_history("file.ex", start_line=42) → blame + PR
  • 行範圍：git_history("file.ex", start_line=40, end_line=60) → 分組blame
  • 函數跟蹤：git_history("file.ex", function_name="create_user") → 演變
  • 文件歷史：git_history("file.ex") → 所有PR/提交
  • 時間過濾：recent=true（14天內）、recent=false（超過14天）、recent=null（所有）
  • 作者過濾：author="john"
  • 可用時自動集成PR索引

附加工具

• expand_result - 從查詢結果深入研究
  • 自動檢測模塊與函數。
  • 顯示帶有使用示例的完整詳細信息。
  • 配置要包含的內容：代碼、依賴項、調用者。
  • 是search_module和search_function的便捷包裝器。
• find_dead_code - 代碼清理分析
  • 三個置信度級別（高、中、低）。
  • 智能檢測回調和行為。
  • 識別動態調用模式。
  • 按模塊級別分組並顯示行號。
  • 排除測試文件和@impl函數。
• query_jq - 高級索引查詢
  • 直接對索引進行jq查詢。
  • 使用| schema進行模式發現。
  • 緊湊（默認）或美觀輸出。
  • 大結果的樣本模式。

詳細參數 + 輸出格式：MCP_TOOLS_REFERENCE.md。

節省令牌的響應

所有工具返回結構化的Markdown/JSON代碼片段（簽名、調用點、PR元數據），而不是完整文件，保持提示簡潔。

v0.5.1新特性：所有工具現在默認使用緊湊輸出，以最小化令牌使用。使用verbose=true可獲得帶有完整文檔和規範的詳細輸出。

📚 詳細文檔

• docs/17-WORKFLOW_EXAMPLES.md
• docs/12-TOOL_DISCOVERABILITY_TASKS.md
• CHANGELOG.md – 版本發佈說明。
• docs/01-KEYWORD_EXTRACTION_ANALYSIS.md – 語義搜索內部機制。
• docs/09-PR_INDEXING.md – GitHub集成詳細信息。
• docs/16-MCP_TOOL_CALL_BENCHMARKING.md – 令牌/時間基準測試。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE。