Tree Sitter Analyzer

🌳 树位分析器

英语 | 日本语 | 简体中文

](https://python.org)     ](https://github.com/aimasteracc/tree-sitter-analyzer/releases) ](https://github.com/aimasteracc/tree-sitter-analyzer)

Tree Sitter Analyzer是用于人工智能辅助开发的本地第一个代码上下文引擎 --结合快速存储库检索、基于AST的结构分析和安全的MCP集成。

它的工作不仅仅是解析代码。它的工作是帮助人类和人工智能代理安全、快速、结构精确地只获取他们实际需要的代码上下文。

find the right files → find the right matches → extract the right structure → send only the right context

*Claude不需要阅读你的整个代码库。你也没有。*

17种语言·项目基本安全·Claude Desktop/Cursor/Roo-Code·CLI+Python API

______________________________________________________________________

✨ v1.11.1的新增功能

• Claude在读取单个文件之前就知道项目的框架: get_project_summary 返回PageRank排名的架构节点——其他所有东西都扩展的类。已在elasticsearch（40k文件）、spring框架（11k）、mybatis、spring petclinic上验证。
• 碰一个关键类？克劳德先阻止你: modification_guard 读取架构排名。重命名 Writeable 弹性搜索→ UNSAFE的判决，排名第一，4745名来电者。这并不奇怪。
• 新语言=新文件，而不是重写：插件 edge_extractors/ 包——Java、Python、TypeScript今天发布。添加Kotlin是一个文件+一行。
• 对陌生项目的探索速度提高2倍：端到端测试——5次有总结的工具调用，10次以上没有总结。克劳德完全跳过了盲目搜索阶段。
• 零配置第一方过滤：Java从pom.xml读取groupId。Python使用 sys.stdlib_module_names。无需维护黑名单。永远。

📖 完整更新日志 查看完整的版本历史记录。

🎬 在行动中看到它

*演示GIF即将推出-展示AI与SMART工作流的集成*

______________________________________________________________________

🎯 为什么选择Tree sitter分析器

Tree sitter Analyzer是一个开源的、本地优先的代码上下文引擎，用于帮助AI助手只读取大型代码库中重要的内容。

• 最少的上下文，而不是整个文件填充：在将最小的有用代码区域发送给AI之前检索它们
• 循证分析：将树形结构与 fd 和 ripgrep 显示相关文件、符号和路径
• 无需大量预处理：适用于混乱的存储库，在这些存储库中，完整索引可能很慢、过时或难以维护

常见用例

• 了解一个非常大的文件或模块在做什么，而无需将整个文件加载到AI提示符中
• 在复杂的存储库中跟踪业务逻辑、UI处理程序或与错误相关的代码路径
• 在要求分析或更改之前，缩小Java和其他大型代码库的AI上下文

______________________________________________________________________

🚀 5分钟快速入门

先决条件

# Install uv (required)
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install fd + ripgrep (required for search features)
brew install fd ripgrep          # macOS
winget install sharkdp.fd BurntSushi.ripgrep.MSVC  # Windows

📖 详细安装指南 适用于所有平台。

验证安装

uv run tree-sitter-analyzer --show-supported-languages

______________________________________________________________________

🤖 人工智能集成

配置您的AI助手，使其通过MCP协议使用Tree sitter Analyzer。

当您的助手处理非常大的文件、嘈杂的存储库范围上下文或一次性加载成本太高的遗留代码时，这种方法尤其有效。

克劳德桌面/光标/Roo代码

添加到MCP配置中：

{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uvx",
      "args": [
        "--from", "tree-sitter-analyzer[mcp]",
        "tree-sitter-analyzer-mcp"
      ],
      "env": {
        "TREE_SITTER_PROJECT_ROOT": "/path/to/your/project",
        "TREE_SITTER_OUTPUT_PATH": "/path/to/output/directory"
      }
    }
  }
}

配置文件位置：

• 克劳德桌面版: %APPDATA%\Claude\claude_desktop_config.json （Windows）/ ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）
• 光标：内置MCP设置
• Roo代码：MCP配置

重启后，告诉AI： Please set the project root directory to: /path/to/your/project

📖 MCP工具参考 获取完整的API文档。

______________________________________________________________________

💻 常见CLI命令

安装

uv add "tree-sitter-analyzer[all,mcp]"  # Full installation

前5条命令

# 1. Analyze file structure
uv run tree-sitter-analyzer examples/BigService.java --table full

# 2. Quick summary
uv run tree-sitter-analyzer examples/BigService.java --summary

# 3. Extract code section
uv run tree-sitter-analyzer examples/BigService.java --partial-read --start-line 93 --end-line 106

# 4. Find files and search content
uv run find-and-grep --roots . --query "class.*Service" --extensions java

# 5. Query specific elements
uv run tree-sitter-analyzer examples/BigService.java --query-key methods --filter "public=true"

📋 View Output Example

╭─────────────────────────────────────────────────────────────╮
│                   BigService.java Analysis                   │
├─────────────────────────────────────────────────────────────┤
│ Total Lines: 1419 | Code: 906 | Comments: 246 | Blank: 267  │
│ Classes: 1 | Methods: 66 | Fields: 9 | Complexity: 5.27 avg │
╰─────────────────────────────────────────────────────────────╯

📖 完整的CLI参考 对于所有命令和选项。

______________________________________________________________________

🌍 支持的语言

📖 功能文档 了解特定语言的详细信息。

______________________________________________________________________

📊 功能概述

______________________________________________________________________

🔬 语法覆盖率（MECE框架）

树保姆分析器保证 零假阳性 在所有17种支持的语言中进行语法覆盖率验证。

第一阶段：MECE架构（2026-03）

新架构:

• 轨迹 句法路径 (node_type, parent_path) 而不仅仅是节点类型
• 用途 精确节点身份匹配 （类型+字节范围+父链+文件路径）
• 消除嵌套节点的错误分类（包装节点不再导致误报）

为何重要:

# OLD method: Position overlap → False Positives
@decorator       # Plugin extracts this
def foo():       # Validator incorrectly marks this as "covered" (it's not!)
    pass

# NEW method: Exact identity matching → Zero False Positives
# Only nodes actually extracted by the plugin are marked as covered

验证命令

# Validate single language
python -c "from tree_sitter_analyzer.grammar_coverage.validator import validate_plugin_coverage_sync; r = validate_plugin_coverage_sync('python'); print(f'{r.coverage_percentage:.1f}% coverage')"

# Validate all languages
python -c "
from tree_sitter_analyzer.grammar_coverage.validator import validate_plugin_coverage_sync
langs = ['python', 'javascript', 'java', 'go', 'typescript', 'c', 'cpp', 'rust', 'ruby', 'php', 'kotlin', 'swift', 'scala', 'bash', 'yaml', 'json', 'sql']
for lang in langs:
    r = validate_plugin_coverage_sync(lang)
    status = '✅' if r.coverage_percentage == 100.0 else '❌'
    print(f'{status} {lang}: {r.coverage_percentage:.1f}% ({r.covered_node_types}/{r.total_node_types})')
"

输出示例 （新格式）：

✅ python: 100.0% (57/57 node types covered)
✅ javascript: 100.0% (58/58 node types covered)
✅ typescript: 100.0% (114/114 node types covered)
...
✅ sql: 100.0% (155/155 node types covered)

MECE保证

• 互斥：每个节点都有一个唯一的 (type, parent_path) → 不得重复计算
• 集体穷尽：完整AST遍历→ 无缺失节点
• 零假阳性：完全匹配→ 只有标记为覆盖的真正提取的节点

📖 语法覆盖框架 了解技术细节和架构。

______________________________________________________________________

🏆 质量与测试

# Run tests
uv run pytest tests/ -v

# Generate coverage report
uv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=html

______________________________________________________________________

🔒 安全与架构

Tree sitter分析器的设计 默认安全 人工智能辅助开发工作流程的原则。

安全模型

项目边界执行

• 所有MCP工具都根据项目根边界验证文件路径
• 无法访问配置的项目目录之外的文件
• Symlink遍历预防
• 路径规范化可防止 ../ 逃跑企图

输入验证

• 所有MCP工具参数的JSON模式验证
• 具有严格mypy遵从性的类型安全Python API
• 执行shell命令前的Sanitized用户输入
• glob/regex搜索的模式验证

无远程执行

• 100%本地处理——无云依赖
• 无遥测或数据收集
• 除了可选的PyPI版本检查外，没有网络调用
• 源代码分析保留在您的计算机上

安全默认值

• 默认情况下为只读文件操作
• 任何文件修改都需要明确的选择加入
• 外部工具（fd、ripgrep）的沙盒子流程执行
• 环境变量隔离

建筑原理

┌─────────────────────────────────────────────────────────┐
│  AI Assistant (Claude Desktop / Cursor / Roo Code)     │
└────────────────────┬────────────────────────────────────┘
                     │ MCP Protocol (JSON-RPC)
                     ▼
┌─────────────────────────────────────────────────────────┐
│  MCP Server Layer                                       │
│  • Input validation (JSON Schema)                       │
│  • Project boundary checks                              │
│  • Tool dispatch                                        │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Analysis Engine                                        │
│  • Tree-sitter AST parsing (17 languages)               │
│  • Fast file search (fd)                                │
│  • Content search (ripgrep)                             │
│  • Output formatting (JSON / TOON)                      │
└─────────────────────────────────────────────────────────┘

关键安全边界:

1. MCP协议：AI只能调用具有经过验证的模式的显式定义的工具
2. 项目根目录：文件操作仅限于配置的目录
3. 只读：未经用户明确同意，不得进行破坏性操作
4. 本地优先：所有处理都在您的机器上进行

安全性测试

• 8942多项自动化测试 包括以安全为重点的边缘案例
• 100%mypy型安全 防止整类错误
• CI/CD安全扫描：Bandit（Python安全），安全（依赖漏洞）
• 人工安全审查 所有MCP工具实现

报告安全问题

发现安全问题？请发送电子邮件至aimasteracc@gmail.com或者在GitHub上打开私人安全咨询。

我们不使用自动安全徽章服务 --我们的安全态势是通过架构、测试和代码审查记录的，而不是通过第三方评分记录的。

______________________________________________________________________

🛠️ 发展

设置

git clone https://github.com/aimasteracc/tree-sitter-analyzer.git
cd tree-sitter-analyzer
uv sync --extra all --extra mcp

质量检查

uv run pytest tests/ -v                    # Run tests
uv run python check_quality.py --new-code-only  # Quality check
uv run python llm_code_checker.py --check-all   # AI code check

📖 架构指南 了解系统设计细节。

______________________________________________________________________

🤝 贡献和许可

我们欢迎捐款！看 贡献指南 发展指南。

⭐ 支持

如果这个项目对你有帮助，请给我们一个⭐ 在GitHub上！

💝 赞助商

@o93 -主要赞助商支持MCP工具增强、测试基础设施和质量改进。

💖 赞助此项目

📄 许可证

MIT许可证-请参阅 许可证 文件。

______________________________________________________________________

🧪 测试

测试覆盖率

运行测试

# Run all tests
uv run pytest tests/ -v

# Run specific test category
uv run pytest tests/unit/ -v              # Unit tests
uv run pytest tests/integration/ -v         # Integration tests
uv run pytest tests/regression/ -m regression  # Regression tests
uv run pytest tests/benchmarks/ -v         # Benchmark tests

# Run with coverage
uv run pytest tests/ --cov=tree_sitter_analyzer --cov-report=html

# Run property-based tests
uv run pytest tests/property/

# Run performance benchmarks
uv run pytest tests/benchmarks/ --benchmark-only

测试文档

测试类别

• 单元测试：单独测试单个组件
• 集成测试：测试组件交互
• 回归测试：确保向后兼容性和格式稳定性
• 性能测试：使用基于假设的不变性检查
• 基准测试：跟踪性能和回归信号
• 兼容性测试：验证跨版本行为

CI/CD集成

• 测试覆盖工作流程：对PR和推送进行自动覆盖检查
• 回归测试工作流程：Golden Master验证和格式稳定性检查
• 性能基准：每日基准运行和趋势分析
• 质量检查：自动抽检、类型检查和安全扫描

贡献测试

在贡献新功能时：

1. 编写测试：遵循 考试写作指南
2. 确保覆盖范围：保持80%以上的代码覆盖率
3. 在本地运行: uv run pytest tests/ -v
4. 检查质量: uv run ruff check . && uv run mypy tree_sitter_analyzer/
5. 更新文档：记录新的测试和功能

______________________________________________________________________

📚 文档

______________________________________________________________________

🎯 专为使用大型代码库和AI助手的开发人员而构建

*使每一行代码都能被人工智能理解，使每个项目都能突破令牌限制*