article

README

🚀 CICADA

代码智能：上下文分析、发现与归因

为AI代码助手进行上下文压缩 — 为你的AI提供对Elixir、Python和Erlang代码库的结构化、高效令牌访问。

等待时间最多减少50% · 令牌使用最多减少70% · 解释工作最多减少99% 更紧凑的上下文 = 更高的质量

快速安装 · 安全隐私 · 开发者指南 · AI助手使用说明 · 文档资料

🚀 快速开始

CICADA是一款专为AI代码助手设计的工具，它通过上下文压缩技术，为AI提供对Elixir、Python和Erlang代码库的结构化、高效令牌访问，有效解决了AI代码助手在搜索代码时浪费上下文的问题。

✨ 主要特性

为何选择CICADA？

核心问题：AI代码助手在盲目搜索上浪费上下文。当你只需要一个函数签名时，Grep会转储整个文件，留给实际推理的空间就更少了。

上下文压缩方法

CICADA不是进行原始文本转储，而是为你的AI提供结构化、预索引的知识： | 传统搜索 | CICADA | | ---- | ---- | | Grep转储整个文件 | 仅返回签名 + 调用点 | | 错过别名导入 | 跟踪所有引用类型 | | 没有语义理解 | 当你搜索“身份验证”时，关键字搜索能找到verify_credentials |

你将获得

抽象语法树（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   # 完全重建

命令行工具速查表

| 命令 | 用途 | 运行时机 | | ---- | ---- | ---- | | cicada claude | 配置MCP + 增量重新索引 | 首次设置、本地更改后 | | cicada status | 检查索引健康状态、链接状态、代理文件 | 设置后、故障排除时 | | cicada stats | 查看使用统计信息和令牌指标 | 每月审查、优化时 | | cicada watch | 监视文件并在更改时自动重新索引 | 积极开发期间 | | cicada index --force --regular . | 使用语义关键字进行完全重建 | 大规模重构后或启用AI层级后 | | cicada index-pr . | 同步PR元数据/审查 | 新PR合并后 | | cicada find-dead-code --min-confidence high | 列出未使用的公共函数 | 清理冲刺阶段 |

故障排除

"Index file not found"

先运行索引器： ```bash cicada index /path/to/project ``` 确保索引成功完成。检查`~/.cicada/projects//index.json`是否存在。

"Module not found"

使用代码中出现的准确模块名称（例如，`MyApp.User`，而不是`User`）。如果模块是最近添加的，请重新索引： ```bash cicada index . ```

MCP Server Won't Connect

**故障排除清单**： 1. **验证配置文件是否存在**： ```bash # 对于Claude Code ls -la .mcp.json

对于Cursor

ls -la .cursor/mcp.json

对于VS Code

ls -la .vscode/settings.json

2. **检查路径是否为绝对路径**：
```bash
cat .mcp.json
# 应包含：/absolute/path/to/project
# 而不是：./project 或 ../project

确保索引存在：

ls -la ~/.cicada/projects/
# 应显示你的项目目录

完全重启编辑器（而不仅仅是重新加载窗口）。
检查编辑器MCP日志：

Claude Code: --debug
Cursor: Settings → MCP → View Logs
VS Code: Output panel → MCP

PR Features Not Working

**设置GitHub CLI**： ```bash # 安装GitHub CLI brew install gh # macOS sudo apt install gh # Ubuntu # 或者访问 https://cli.github.com/

进行身份验证

gh auth login

索引PR

cicada index-pr

**常见问题**：
- "No PR index found" → 运行`cicada index-pr .`
- "Not a GitHub repository" → 确保仓库有GitHub远程地址
- 索引缓慢 → 首次索引会获取所有PR；后续运行是增量的
- 速率限制 → GitHub API有速率限制；如果达到限制，请等待并重试

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

Keyword Search Not Working

**错误**："Keyword search not available" **原因**：索引构建时未进行关键字提取。 **解决方案**： ```bash # 重新索引并进行关键字提取 cicada index . # 或者 --fast 或 --max ``` **验证**： ```bash cat ~/.cicada/projects//config.yaml # 应显示 keyword_extraction: enabled ```

更多详细信息：docs/PR_INDEXING.md，docs/08-INCREMENTAL_INDEXING.md。

Python Indexing

**要求**： - Node.js（用于scip-python索引器） - 带有pyproject.toml的Python项目

首次设置： CICADA在首次索引时会通过npm自动安装scip-python。这可能需要一分钟。

已知限制（Beta）：

首次索引可能比Elixir慢（SCIP生成步骤）
大型虚拟环境（.venv）会自动排除
某些动态Python模式可能无法捕获

性能提示：

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

# 使用--fast层级进行更快的索引
cicada index --fast .

报告问题：GitHub Issues，标签为 "Python"。

AI助手使用说明

CICADA提供了7个专注于MCP的工具，旨在跨Elixir、Python和Erlang代码库进行高效的代码探索。

选择合适的工具

| 需求 | 工具 | 注意事项 | | ---- | ---- | ---- | | 开始探索 | query | 🚀 从这里开始 - 使用关键字/模式 + 过滤器（范围、最近、路径）进行智能发现 | | 查看模块的完整API | search_module | 函数、签名、规范、文档。使用what_calls_it/what_it_calls进行双向分析 | | 查找函数的使用位置 | search_function | 定义 + 所有调用点。支持通配符 (*) 和OR (\|) 模式 | | 跟踪git历史 | git_history | 统一工具：blame、提交、PR、函数演变（替代4个旧工具） | | 查找死代码 | find_dead_code | 识别可能未使用的函数，并给出置信度级别 | | 深入研究结果 | expand_result | 自动展开查询结果中的模块或函数 | | 高级索引查询 | query_jq | 为高级用户提供自定义jq查询 |

想查看这些工具的实际操作吗？ 查看完整工作流示例，其中包含专业提示和实际场景。

核心工具

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。

**别再在盲目搜索上浪费上下文了。给你的AI配备CICADA吧。** [开始使用](#quick-install) · [报告问题](https://github.com/wende/cicada/issues)

cicada

README

🚀 CICADA

代码智能：上下文分析、发现与归因

🚀 快速开始

✨ 主要特性

为何选择CICADA？

上下文压缩方法

你将获得

📦 安装指南

安装步骤

临时试用

安装后可用命令

询问示例

💻 使用示例

基础用法

高级用法

启用PR归因（可选）

自动重新索引（监视模式）

🔧 技术细节

隐私与安全

开发者指南

安装与配置

启用PR归因（可选）

命令行工具速查表

故障排除

对于Cursor

对于VS Code

进行身份验证

索引PR

AI助手使用说明

选择合适的工具

核心工具

Git历史（统一工具）

附加工具

节省令牌的响应

📚 详细文档

📄 许可证

运行方式说明

托管运行

本地运行 / 其它方式