🚀 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。