@tom_doerr: 将项目转换为AI代理可导航的知识图谱 https://github.com/Muvon/octocode

将项目转化为AI代理可导航的知识图谱 https://t.co/X982Yp1Kuc https://t.co/jUqR9GNnEj — # Muvon/octocode 源代码：https://github.com/Muvon/octocode ### 面向AI代理的结构化代码智能 — MCP服务器 + 知识图谱 + 语义搜索 GitHub星标 (https://github.com/Muvon/octocode/stargazers) 许可证 (https://opensource.org/licenses/Apache-2.0) Rust (https://www.rust-lang.org) 发布版本 (https://github.com/Muvon/octocode/releases) 为你的AI助手配备一个代码库的大脑。 Octocode将你的项目转化为可导航的知识图谱，Claude、Cursor和其他AI代理可以搜索、理解并导航它。 🚀 快速开始 • 🤖 MCP集成 • 📖 文档 • 🌐 网站 (https://octocode.muvon.io) — ## 🤖 为AI代理打造 问题： AI助手对你的代码库视而不见。它们无法搜索你的文件、理解依赖关系，或记住跨会话的上下文。 解决方案： Octocode的MCP服务器为AI代理提供： - 🔍 语义搜索 — 按含义而非关键词查找代码 - 🕸️ 知识图谱 — 导航导入、调用和依赖关系 - 📝 代码签名 — 无需阅读整个文件即可查看结构 - 🧠 持久记忆 — 跨对话记住决策 支持： Claude Desktop • Cursor • Windsurf • 任何兼容MCP的AI json // 添加到你的AI助手配置中 { "mcpServers": { "octocode": { "command": "octocode", "args": ["mcp", "--path", "/your/project"] } } } 现在你的AI助手可以： 你："认证在哪里处理？" AI：*搜索你的代码库* "认证在src/middleware/auth.rs中，它导入jwt.rs进行令牌验证，并调用user_store.rs进行查找。" 你："哪些文件依赖支付模块？" AI：*查询知识图谱* "src/api/handlers/payment.rs导入payment/mod.rs，还被src/workers/refund.rs和src/cron/billing.rs使用" 你："记住这个bug修复以供将来参考" AI：*存储到记忆中* "好的。我会记住这个认证绕过修复，并在审查安全代码时应用类似的模式。" ## 🤔 为什么选择Octocode？ 标准RAG将你的代码视为扁平文本块。 它能找到听起来相似的代码片段，但不知道auth_middleware.rs导入了jwt.rs、调用了user_store.rs，并连接到router.rs。 Octocode理解结构。 # 语义搜索找到正确的代码 octocode search "authentication middleware" → src/middleware/auth.rs | 相似度 0.923 # GraphRAG揭示完整的依赖链 octocode graphrag get-relationships --node_id src/middleware/auth.rs 传出：导入 → jwt (src/auth/jwt.rs): 令牌验证逻辑 调用 → user_store (src/db/user_store.rs): 按令牌查找用户 传入：导入 ← router (src/router.rs): 将认证接入请求管道 Octocode使用tree-sitter AST解析提取真实符号（函数、导入、依赖），构建文件之间关系的GraphRAG知识图谱，并通过MCP暴露一切 — 因此AI工具可以导航你的项目架构，而不仅仅是搜索它。 ## 🔬 工作原理 源代码 → Tree-sitter AST → 符号与关系 → 知识图谱 ↓ 嵌入 + 混合搜索 + 重排 → MCP服务器 1. AST解析 — tree-sitter提取真实代码符号（函数、类、导入），而非任意文本块 2. 知识图谱 — GraphRAG映射文件之间的关系：imports、calls、implements、extends、configures等9种以上类型 — 每种都有重要性权重 3. 混合搜索 — 语义相似度 + BM25全文搜索 + 重排 — 而不仅仅是向量嵌入 4. MCP服务器 — 向任何兼容MCP的客户端暴露semantic_search、view_signatures和graphrag工具 ## ✨ 与众不同之处 | | 标准RAG | 文档查找工具 | Octocode | |—|—|—|—| | 索引 | 文本块 | 外部库文档 | 你的代码库结构（AST） | | 理解 | 相似文本 | API规范和使用 | 函数、导入、依赖 | | 跨文件 | 否 | 否 | 是 — 导航依赖图 | | 关系 | 否 | 否 | imports、calls、implements、extends… | | AI集成 | 各异 | MCP | 原生MCP服务器 + LSP | > 文档工具给AI的是你使用库的手册。Octocode给AI的是你如何将它们组合在一起的蓝图。 用Rust构建以获得性能。本地优先保护隐私。开源（Apache 2.0）透明可信。 ## 🚀 快速开始 ### 1. 安装 bash # 通用安装程序（Linux、macOS、Windows） curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh # macOS使用Homebrew brew install muvon/tap/octocode 其他安装方式 bash # Cargo（从源码构建） cargo install --git https://github.com/Muvon/octocode # 从发布页下载二进制文件 # https://github.com/Muvon/octocode/releases 参阅安装指南获取平台特定说明。 ### 2. 设置API密钥 bash # 必需：嵌入提供商（Voyage AI每月有2亿免费令牌） export VOYAGE_API_KEY="your-voyage-api-key" # 可选：用于提交信息、代码审查的LLM export OPENROUTER_API_KEY="your-openrouter-api-key" 获取你的Voyage API密钥： voyageai.com (https://www.voyageai.com/)（有免费套餐） 其他嵌入提供商 Octocode支持多种嵌入提供商： bash # OpenAI export OPENAI_API_KEY="your-key" octocode config --code-embedding-model "openai:text-embedding-3-small" # Jina AI export JINA_API_KEY="your-key" octocode config --code-embedding-model "jina:jina-embeddings-v3" # Google export GOOGLE_API_KEY="your-key" octocode config --code-embedding-model "google:text-embedding-005" 参阅API密钥指南了解所有支持的提供商。 ### 3. 索引你的代码库 bash cd /your/project octocode index # → 在342个文件中索引了12,847个代码块 ### 4. 搜索你的代码 bash # 自然语言搜索 octocode search "authentication middleware" # 多查询获取更广泛结果 octocode search "auth" "middleware" "session" # 按语言过滤 octocode search "database connection pool" --lang rust # 搜索提交历史 octocode search "authentication refactor" --mode commits ### 5. 连接你的AI助手 添加到你的MCP客户端配置（Claude Desktop、Cursor、Windsurf）： json { "mcpServers": { "octocode": { "command": "octocode", "args": ["mcp", "--path", "/your/project"] } } } 完成！你的AI助手现在理解你的代码库结构了。 ## 🔌 MCP服务器集成 Octocode包含一个内置MCP服务器，将你的代码库作为工具暴露给AI助手。这是使用Octocode的主要方式 — 让你的AI助手直接访问搜索和导航你的代码。 ### 可用工具 | 工具 | 功能 | |——|–––––––| | semantic_search | 按含义查找代码 — “认证流程”、“错误处理”、“数据库查询” | | view_signatures | 查看文件结构 — 函数签名、类定义、导入 | | graphrag | 查询关系 — “什么调用这个函数？”、“这个模块导入什么？” | | structural_search | AST模式匹配 — 查找.unwrap()调用、new实例化、特定模式 | ### 对话式AI示例 连接后，你的AI助手可以回答关于你的代码库的问题： 你："用户认证在哪里实现？" AI：*使用semantic_search* "在src/auth/login.rs中找到。authenticate()函数验证数据库凭据，生成JWT令牌，并将会话存储在Redis中。" 你："哪些文件依赖支付模块？" AI：*使用graphrag* "src/api/handlers/payment.rs导入payment/mod.rs，还被src/workers/refund.rs和src/cron/billing.rs使用。支付模块导出process_payment()和validate_transaction()函数。" 你："显示API层中的所有错误处理" AI：*使用structural_search* "在src/api/中找到23个错误处理模式： - 15个使用Result和显式错误类型 - 8个使用.unwrap()（handlers/user.rs:42、handlers/auth.rs:87中可能出现panic） - 3个使用.expect()并带有自定义消息" ### 快速设置 Octomind（推荐） — 零配置，Octocode预装： bash curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash octomind run developer:rust Claude Code（CLI） — 命令行设置： bash claude mcp add octocode -- octocode mcp --path /path/to/your/project Claude Desktop / Cursor / Windsurf — 添加到配置： json { "mcpServers": { "octocode": { "command": "octocode", "args": ["mcp", "--path", "/path/to/your/project"] } } } 配置位置： - Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS） - Cursor：~/.cursor/mcp.json或设置 → MCP服务器 - Windsurf：设置 → MCP 📖 完整的MCP客户端设置指南 — 包含15个以上客户端的详细说明，包括VS Code（Cline/Continue）、Zed、Replit等。 ## 🎯 你能用它做什么？ 新开发者入职： 你："认证系统如何工作？" AI：*搜索和导航* "认证从src/middleware/auth.rs开始，它验证JWT令牌。它调用src/auth/jwt.rs进行令牌验证，后者使用配置中的公钥。认证失败通过src/errors/auth_error.rs返回401。会话通过src/cache/session.rs存储在Redis中。" 代码考古： 你："找到我们处理数据库错误的所有地方" AI：*结构化搜索* "找到47个错误处理模式： - 32个使用Result和正确的错误类型 - 15个使用.unwrap()（src/db/user.rs:23、src/db/order.rs:156中可能出现的问题） - 建议在这些位置添加正确的错误处理" 自信重构： 你："什么依赖PaymentProcessor trait？" AI：*查询图谱* "src/api/handlers/checkout.rs、src/workers/refund_worker.rs和src/cron/billing.rs都依赖PaymentProcessor。该trait定义在src/domain/payment.rs中，由src/infrastructure/stripe.rs和src/infrastructure/paypal.rs实现。" 代码审查协助： 你："审查这个PR的安全问题" AI：*分析更改* "PR在src/auth/hash.rs中添加了密码哈希。然而，它使用SHA256，这种算法速度快，容易被暴力破解。建议使用bcrypt或argon2。另外发现3个.unwrap()可能在生产环境中panic。" ## 🌐 支持的语言 | 语言 | 扩展名 | 功能 | |–––––|————|–––––| | Rust | .rs | 完整AST解析、pub/use检测、模块结构 | | Python | .py | 导入/类/函数提取、文档字符串解析 | | TypeScript/JavaScript | .ts、.tsx、.js、.jsx | ES6导入/导出、类型定义 | | Go | .go | 包/导入分析、结构体/接口解析 | | PHP | .php | 类/函数提取、命名空间支持 | | C++ | .cpp、.hpp、.h | 包含分析、类/函数提取 | | Ruby | .rb | 类/模块提取、方法定义 | | Java | .java | 导入分析、类/方法提取 | | JSON | .json | 结构分析、键提取 | | Bash | .sh、.bash | 函数和变量提取 | | Markdown | .md | 文档章节索引、标题提取 | 还有：通过tree-sitter支持的CSS、Lua、Svelte等 ## 📚 文档 - 入门指南 — 第一步和基本工作流程 - 安装指南 — 详细方法和从源码构建 - MCP客户端设置 — 连接到Claude、Cursor、Windsurf和15个以上客户端 - MCP集成 — MCP服务器详情和高级配置 - 命令参考 — 完整CLI参考 - 配置 — 模板和自定义 - API密钥 — 提供商设置指南 - 架构 — 底层工作原理 - 贡献指南 — 开发环境设置 ## 🔒 隐私与安全 - 🏠 本地优先 — 支持的平台上有本地嵌入模型（macOS ARM默认构建）；所有平台支持云提供商 - 🔐 安全 — API密钥本地存储，支持环境变量 - 🚫 尊重.gitignore — 从不索引敏感文件 - 🛡️ MCP安全 — 本地服务器，搜索不需外部网络 - 📥 云安全 — 嵌入仅处理元数据，从不处理源代码 📊 检索质量基准测试 我们使用人工标注的254个查询（127个代码 + 127个文档）的真实数据集来衡量语义搜索质量，每个查询有精确的行范围注释。每个查询有1-3个按相关性评分的预期结果。在提交b1771ba (https://github.com/Muvon/octocode/commit/b1771ba)上测试，使用基准配置（上下文检索、Voyage重排器、RaBitQ量化）。 文档搜索（–mode docs）— Hit@10：0.953，MRR：0.776 | 指标 | 分数 | |––––|—––| | Hit@5 | 0.929 (118/127) | | Hit@10 | 0.953 (121/127) | | MRR | 0.776 | | NDCG@10 | 0.801 | | Recall@5 | 0.902 | | Recall@10 | 0.921 | 未命中的查询（127个中的6个）： | # | 查询 | 预期 | 获得（第一） | |—|—––|–––––|———––| | 43 | how to set up MCP proxy for managing multiple repositories | doc/MCP_INTEGRATION.md:286-311 | doc/MCP_INTEGRATION.md:286-4 | | 51 | what are the prerequisites before using octocode | doc/GETTING_STARTED.md:6-12 | doc/CONTRIBUTING.md:7-33 | | 59 | what to do when hitting API rate limits | doc/GETTING_STARTED.md:209-216 | doc/PERFORMANCE.md:304-356 | | 75 | typical performance metrics for small medium and large projects | doc/PERFORMANCE.md:4-13 | doc/PERFORMANCE.md:414-14 | | 112 | how to install octocode on different operating systems | INSTALL.md:4-14 | INSTALL.md:49-70 | | 115 | how to fix macOS Gatekeeper blocking the binary | INSTALL.md:199-206 | INSTALL.md:198-119 | 代码搜索（–mode code）— Hit@10：0.992，MRR：0.895 | 指标 | 分数 | |––––|—––| | Hit@5 | 0.992 (126/127) | | Hit@10 | 0.992 (126/127) | | MRR | 0.895 | | NDCG@10 | 0.906 | | Recall@5 | 0.962 | | Recall@10 | 0.974 | 未命中的查询（127个中的1个）： | # | 查询 | 预期 | 获得（第一） | |—|—––|–––––|———––| | 105 | how does the system ensure two developers get the same database path | src/storage.rs:60-83 | src/mcp/proxy.rs:631-644 | 指标：Hit@k（答案出现了吗？）、MRR（排名多高？）、NDCG@10（最佳结果排在第一了吗？）、Recall@k（找到了多少？）。参阅benchmark/获取方法论、评分脚本和完整数据集。 ## 🤝 社区与支持 - ⭐ 在GitHub上给我们星标 — 真的很帮助！ - 🐛 报告问题 (https://github.com/Muvon/octocode/issues) - 💬 讨论 (https://github.com/Muvon/octocode/discussions) - 📧 [email protected] - 🌐 muvon.io (https://muvon.io) ## ⚖️ 许可证 Apache License 2.0 — 参阅LICENSE了解更多详情。 — 用🦀 Rust由Muvon (https://muvon.io)在香港构建 ⭐ Star (https://github.com/Muvon/octocode) • 🍴 Fork (https://github.com/Muvon/octocode/fork) • 📣 分享 (https://twitter.com/intent/tweet?text=Octocode%20-%20AI-powered%20code%20intelligence%20with%20built-in%20MCP%20server&url=https://github.com/Muvon/octocode)