codegraph

在 AI 开始探索之前，先给它一张地图。

问题 · 功能 · 快速开始 · 命令 · 语言 · AI 集成 · 工作原理 · 最佳实践 · 路线图

## 问题 AI 代理面临着两难的抉择。它们要么消耗数千个 token 去阅读文件，以理解代码库的结构——直到撑爆上下文窗口并导致质量下降；要么去猜测事物的运作方式，而这种猜测往往是错误的。无论哪种情况，都会出问题。代码库越大，情况就越糟。 代理在修改某个函数时，可能完全不知道有 9 个文件导入了它。它会误读某个辅助函数的作用，并在这个误解之上构建逻辑。重构后，它可能会留下死代码。PR（拉取请求）被提交后，你的审查者——无论是人工还是自动化工具——会一次又一次地标记出相同的结构性问题：_“这会破坏 14 个调用者，”_ _“那个函数已经存在了，”_ _“这个导出现在变成了死代码。”_ 如果审查者发现了这些问题，就意味着需要多轮反复沟通。如果没发现，这些问题可能就被发布到生产环境中了。将这种情况乘以每一个 PR、每一个开发者、每一个代码仓库。 防止这些问题的信息其实一直都在——就在代码本身之中。但是如果没有结构化的地图，代理就缺乏能够持续做对的上下文，审查者会在可避免的问题上浪费时间，而系统架构也会在一次又一次未经审查的更改中逐渐崩塌。 ## Codegraph 的功能 Codegraph 为你的整个代码库构建函数级别的依赖图——每一个函数、每一个调用者、每一个依赖关系——并通过亚秒级的增量重建使其保持最新。 它使用 [tree-sitter](https://tree-sitter.github.io/)（原生 Rust 或 WASM）解析你的代码，将依赖图存储在 SQLite 中，并在最重要的地方将其暴露出来： - **MCP server** —— AI 代理通过 30 个工具直接查询依赖图，只需一次调用即可替代 30 次 `grep`/`find`/`cat` 调用 - **CLI** —— 开发者和代理可以在终端中探索、查询和审计代码 - **CI 门禁** —— `check` 和 `manifesto` 命令通过退出码强制执行质量阈值 - **编程式 API** —— 通过 `npm install` 将 codegraph 嵌入到你自己的工具中 代理不再会在没有结构化上下文的情况下盲目修改代码，然后让审查者去收拾残局，而是在接触任何东西之前就知道 _“这个函数在 9 个文件中有 14 个调用者”_。死导出、循环依赖和边界违规会在开发过程中暴露出来——而不是在审查阶段。结果是：PR 需要的审查轮次更少。 **免费。开源。完全本地化。** 零网络调用，零遥测。你的代码始终留在你的机器上。当你需要更深度的智能分析时，接入你自己的 LLM 提供商——你的代码只会发送到你选择的地方。 **只需三个命令即可获得可查询的依赖图：** ``` npm install -g @optave/codegraph cd your-project codegraph build ``` 无需配置文件，无需 Docker，无需 JVM，无需 API 密钥，无需注册账号。将你的代理指向 MCP server，它就能对你的代码库具备结构化的认知。 ### 为什么这很重要 | | 没有 codegraph | 有 codegraph | |---|---|---| | **代码审查** | 审查者一轮又一轮地标记被破坏的调用者、死代码和边界违规 | 结构性问题在开发过程中被捕获——PR 以更少的轮次通过审查 | | **AI 代理** | 修改 `parseConfig()` 时不知道有 9 个文件导入了它——被审查者发现 | `fn-impact parseConfig` 在修改前显示每个调用者——代理主动修复它 | | **AI 代理** | 重构后留下死导出和重复的辅助函数 | 死代码、循环和重复通过钩子和 MCP 查询实时暴露 | | **AI 代理** | 生成能运行但不符合代码库结构的代码 | `context -T` 返回源码、依赖、调用者和测试——代理写出符合规范的代码 | | **CI 流水线** | 捕获测试失败但遗漏了结构退化 | 当影响范围或复杂度阈值超标时，`check --staged` 会使构建失败 | | **开发者** | 接手一个代码库后，需要 grep 几个小时才能了解调用关系 | `context handleAuth -T` 提供与代理使用的相同的结构化视图 | | **架构师** | 绘制的边界规则在几周内就会被破坏 | `manifesto` 和 `boundaries` 在每次提交时强制执行架构规则 | ### 功能对比 _{对比最后验证时间：2026 年 3 月。声明根据各仓库的 README/文档进行验证。完整分析：COMPETITIVE_ANALYSIS.md} | 能力 | codegraph | [joern](https://github.com/joernio/joern) | [narsil-mcp](https://github.com/postrv/narsil-mcp) | [cpg](https://github.com/Fraunhofer-AISEC/cpg) | [axon](https://github.com/harshkedia177/axon) | [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | |---|:---:|:---:|:---:|:---:|:---:|:---:| | 语言 | **23** | ~12 | **32** | ~10 | 3 | 13 | | MCP server | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** | | 数据流 + CFG + AST 查询 | **Yes** | **Yes** | **Yes**¹ | **Yes** | — | — | | 混合搜索 (BM25 + 语义) | **Yes** | — | — | — | **Yes** | **Yes** | | Git 感知 (diff 影响、共变、分支 diff) | **All 3** | — | — | — | **All 3** | — | | 死代码 / 角色分类 | **Yes** | — | **Yes** | — | **Yes** | — | | 增量重建 | **O(changed)** | — | O(n) | — | **Yes** | Commit 级别⁴ | | 架构规则 + CI 门禁 | **Yes** | — | — | — | — | — | | 安全扫描 (SAST / 漏洞检测) | 刻意排除在范围之外² | **Yes** | **Yes** | **Yes** | — | — | | 零配置，`npm install` | **Yes** | — | **Yes** | — | **Yes** | **Yes** | | 图导出 (GraphML / Neo4j / DOT) | **Yes** | **Yes** | — | — | — | — | | 开源 + 商业使用 | **Yes** (Apache-2.0) | **Yes** (Apache-2.0) | **Yes** (MIT/Apache-2.0) | **Yes** (Apache-2.0) | 源码可见³ | 非商业⁵ | ^{¹ narsil-mcp 在最新版本中添加了 CFG 和数据流。 ² Codegraph 专注于结构理解，而非漏洞检测——请使用专门的 SAST 工具（Semgrep、CodeQL、Snyk）进行此类检测。 ³ axon 在 pyproject.toml 中声称使用 MIT，但在仓库中没有 LICENSE 文件。 ⁴ GitNexus 在 git commit 未更改时跳过重新索引，但在发生更改时会重新处理整个仓库——没有按文件的增量解析。 ⁵ GitNexus 使用 PolyForm Noncommercial 1.0.0 许可证。} ### codegraph 的独特之处 | | 区别 | 实际应用 | |---|---|---| | **🤖** | **AI 优先架构** | 30 个工具的 [MCP server](https://modelcontextprotocol.io/) —— 代理直接查询依赖图，无需抓取文件系统。一次调用替代 20+ 次 grep/find/cat 调用 | | **🏷️** | **角色分类** | 每个符号自动标记为 `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` —— 代理无需阅读周围代码即可了解符号的架构角色 | | **🔬** | **函数级别，而不仅仅是文件** | 追踪 `handleAuth()` → `validateToken()` → `decryptJWT()` 并显示如果 `decryptJWT` 更改，跨 9 个文件的 14 个调用者会受到什么影响 | | **⚡** | **始终保持最新的依赖图** | 三层变更检测：日志 (O(changed)) → mtime+大小 (O(n) 次统计) → 哈希 (O(changed) 次读取)。亚秒级重建 —— 代理使用最新数据工作 | | **💥** | **Git diff 影响分析** | `codegraph diff-impact` 显示更改的函数、它们的调用者以及完整的影响范围 —— 并通过 git 共变分析结合历史耦合文件进行丰富。附带 GitHub Actions 工作流 | | **🌐** | **多语言，一张图** | 在单个依赖图中支持 JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + C + C++ + Kotlin + Swift + Scala + Bash + HCL + Elixir + Lua + Dart + Zig + Haskell + OCaml —— 代理无需按语言使用特定工具 | | **🧠** | **混合搜索** | BM25 关键字 + 通过 RRF 融合的语义嵌入 —— `hybrid`（默认）、`semantic` 或 `keyword` 模式；通过 `"auth; token; JWT"` 进行多查询 | | **🔬** | **数据流 + CFG** | 追踪数据如何流经函数（`flows_to`、`returns`、`mutates`）并可视化所有 23 种语言的过程内控制流图 | | **🔓** | **完全本地，零成本** | 无需 API 密钥，无需账户，无需网络调用。可选择接入你自己的 LLM 提供商 —— 你的代码只发送到你想发送的地方 | ## 🚀 快速开始 ``` npm install -g @optave/codegraph cd your-project codegraph build # → .codegraph/graph.db created ``` 完成。依赖图已准备就绪。现在连接你的 AI 代理。 ### 为 AI 代理（主要用例） 直接通过 MCP 连接 —— 你的代理将获得 30 个工具来查询依赖图： ``` codegraph mcp # 33-tool MCP server — AI queries the graph directly ``` 或者将 codegraph 添加到你的代理指令中（例如 `CLAUDE.md`）： ``` Before modifying code, always: 1. `codegraph where ` — find where the symbol lives 2. `codegraph context -T` — get full context (source, deps, callers) 3. `codegraph fn-impact -T` — check blast radius before editing After modifying code: 4. `codegraph diff-impact --staged -T` — verify impact before committing ``` 完整的代理设置：[AI 代理指南](docs/guides/ai-agent-guide.md) · [CLAUDE.md 模板](docs/guides/ai-agent-guide.md#claudemd-template) ### 为开发者 相同的依赖图可通过 CLI 使用： ``` codegraph map # see most-connected files codegraph query myFunc # find any function, see callers & callees codegraph deps src/index.ts # file-level import/export map ``` 或者从源码安装： ``` git clone https://github.com/optave/ops-codegraph-tool.git cd codegraph && npm install && npm link ``` ## ✨ 功能特性 | | 功能 | 描述 | |---|---|---| | 🤖 | **MCP server** | 33 个工具的 MCP server，用于 AI 助手；默认单仓库，可选择开启多仓库 | | 🎯 | **深度上下文** | `context` 在一次调用中为代理提供函数的源码、依赖、调用者、签名和测试；`audit --quick` 提供结构化摘要 | | 🏷️ | **节点角色分类** | 每个符号根据连接性自动标记为 `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` —— 代理瞬间了解其架构角色 | | 📦 | **批量查询** | 接受目标列表并在一个 JSON 负载中返回所有结果 —— 支持多代理并行调度 | | 💥 | **影响分析** | 追踪受更改影响的每一个文件（传递性） | | 🧬 | **函数级追踪** | 调用链、调用者树、函数级影响，以及带有限定调用解析的 A→B 寻路 | | 📍 | **快速查找** | `where` 准确显示符号定义和使用的位置 —— 极简、快速 | | 🔍 | **符号搜索** | 按名称查找任何函数、类或方法 —— 精确匹配优先、相关性评分、`--file` 和 `--kind` 过滤器 | | 📁 | **文件依赖** | 查看文件导入了什么以及什么导入了它 | | 📊 | **Diff 影响** | 解析 `git diff`，找到重叠的函数，追踪它们的调用者 | | 🔗 | **共变分析** | 分析 git 历史中总是一起更改的文件 —— 揭示静态图无法看到的隐藏耦合；通过历史耦合丰富 `diff-impact` | | 🗺️ | **模块地图** | 你连接最多的文件的鸟瞰视图 | | 🏗️ | **结构与热点** | 目录内聚性得分、扇入/扇出热点检测、模块边界 | | 🔄 | **循环检测** | 在文件或函数级别查找循环依赖 | | 📤 | **导出** | DOT、Mermaid、JSON、GraphML、GraphSON 和 Neo4j CSV 图导出 | | 🧠 | **语义搜索** | 基于嵌入的自然语言搜索，支持多查询 RRF 排名 | | 👀 | **监视模式** | 随文件更改增量更新依赖图 | | ⚡ | **始终保持最新** | 三层增量检测 —— 即使在大型代码库上也能实现亚秒级重建 | | 🔬 | **数据流分析** | 过程内参数追踪、返回值消费者、参数流和突变检测 —— 支持所有 23 种语言 | | 🧮 | **复杂度指标** | 每个函数的认知复杂度、圈复杂度、嵌套深度、Halstead 和可维护性指数 | | 🏘️ | **社区发现** | Leiden 聚类，用于发现自然的模块边界和架构漂移 | | 📜 | **Manifesto 规则引擎** | 可配置的通过/失败规则，通过 `check`（失败时退出码为 1）为 CI 门禁设置警告/失败阈值 | | 👥 | **CODEOWNERS 集成** | 将图节点映射到 CODEOWNERS 条目 —— 查看谁拥有每个函数，以及在 `diff-impact` 中的所有权边界 | | 💾 | **图快照** | `snapshot save`/`restore` 用于即时数据库备份和回滚 —— 重构前创建检查点，无需重建即可恢复 | | 🔎 | **混合 BM25 + 语义搜索** | FTS5 关键字搜索 + 基于嵌入的语义搜索，通过倒数排名融合 —— `hybrid`、`semantic` 或 `keyword` 模式 | | 📄 | **分页 & NDJSON 流** | 所有 MCP 工具和 CLI 命令上通用的 `--limit`/`--offset` 分页；`--ndjson` 用于换行符分隔的 JSON 流 | | 🔀 | **分支结构 Diff** | 比较两个 git ref 之间的代码结构 —— 包含传递性调用者影响的增加/删除/更改的符号 | | 🛡️ | **架构边界** | 模块之间用户定义的依赖规则，附带洋葱架构预设 —— 在 manifesto 和 CI 中标记违规 | | ✅ | **CI 验证断言** | 带有可配置门禁的 `check` 命令：复杂度、影响范围、循环、边界违规 —— CI 退出码 0/1 | | 📋 | **综合审计** | 单个 `audit` 命令结合了每个函数的 explain + impact + 健康指标 —— 一次调用替代 3-4 次 | | 🚦 | **分诊队列** | `triage` 将连接性、热点、角色和复杂度合并为一个按优先级排序的审计队列 | | 🔬 | **数据流分析** | 使用 `flows_to`、`returns` 和 `mutates` 边追踪数据如何在函数间流动 —— 所有 23 种语言，默认包含，使用 `--no-dataflow` 跳过 | | 🧩 | **控制流图** | 所有 23 种语言的过程内 CFG 构建 —— `cfg` 命令支持 text/DOT/Mermaid 输出，默认包含，使用 `--no-cfg` 跳过 | | 🔎 | **AST 节点查询** | 存储的可查询 AST 节点（调用、`new`、字符串、正则表达式、抛出、等待） —— `ast` 命令支持 SQL GLOB 模式匹配 | | 🧬 | **扩展的节点/边类型** | `parameter`（参数）、`property`（属性）、`constant`（常量）节点类型，带有 `parent_id` 用于子声明查询；`contains`、`parameter_of`、`receiver` 边类型 | | 📊 | **导出分析** | `exports ` 显示所有导出符号及其每个符号的消费者、重新导出检测和计数 | | 📈 | **交互式查看器** | `codegraph plot` 生成带有分层/力导向/径向布局、复杂度叠加和向下钻取功能的交互式 HTML 图查看器 | | 🏷️ | **稳定的 JSON schema** | `normalizeSymbol` 工具确保在所有命令中输出一致的 7 个字段（name、kind、file、line、endLine、role、fileHash） | 有关真实的 CLI 和 MCP 使用示例，请参见 [docs/examples](docs/examples)。 ## 📦 命令 ### 构建与监视 ``` codegraph build [dir] # Parse and build the dependency graph codegraph build --no-incremental # Force full rebuild codegraph build --dataflow # Extract data flow edges (flows_to, returns, mutates) codegraph build --engine wasm # Force WASM engine (skip native) codegraph watch [dir] # Watch for changes, update graph incrementally ``` ### 查询与探索 ``` codegraph query # Find a symbol — shows callers and callees codegraph deps # File imports/exports codegraph map # Top 20 most-connected files codegraph map -n 50 --no-tests # Top 50, excluding test files codegraph where # Where is a symbol defined and used? codegraph where --file src/db.js # List symbols, imports, exports for a file codegraph stats # Graph health: nodes, edges, languages, quality score codegraph roles # Node role classification (entry, core, utility, adapter, dead, leaf) codegraph roles --role dead -T # Find dead code (unreferenced, non-exported symbols) codegraph roles --role core --file src/ # Core symbols in src/ codegraph exports src/queries.js # Per-symbol consumer analysis (who calls each export) codegraph children # List parameters, properties, constants of a symbol ``` ### 深度上下文（专为 AI 代理设计） ``` codegraph context # Full context: source, deps, callers, signature, tests codegraph context --depth 2 --no-tests # Include callee source 2 levels deep codegraph brief # Token-efficient file summary: symbols, roles, risk tiers codegraph audit --quick # Structural summary: public API, internals, data flow codegraph audit --quick # Function summary: signature, calls, callers, tests ``` ### 影响分析 ``` codegraph impact # Transitive reverse dependency trace codegraph query # Function-level: callers, callees, call chain codegraph query --no-tests --depth 5 codegraph fn-impact # What functions break if this one changes codegraph path # Shortest path between two symbols (A calls...calls B) codegraph path --reverse # Follow edges backward codegraph path --depth 5 --kinds calls,imports codegraph diff-impact # Impact of unstaged git changes codegraph diff-impact --staged # Impact of staged changes codegraph diff-impact HEAD~3 # Impact vs a specific ref codegraph diff-impact main --format mermaid -T # Mermaid flowchart of blast radius codegraph branch-compare main feature-branch # Structural diff between two refs codegraph branch-compare main HEAD --no-tests # Symbols added/removed/changed vs main codegraph branch-compare v2.4.0 v2.5.0 --json # JSON output for programmatic use codegraph branch-compare main HEAD --format mermaid # Mermaid diagram of structural changes ``` ### 共变分析 分析 git 历史以查找总是一起更改的文件 —— 揭示静态图无法看到的隐藏耦合。需要一个 git 仓库。 ``` codegraph co-change --analyze # Scan git history and populate co-change data codegraph co-change src/queries.js # Show co-change partners for a file codegraph co-change # Show top co-changing file pairs globally codegraph co-change --since 6m # Limit to last 6 months of history codegraph co-change --min-jaccard 0.5 # Only show strong coupling (Jaccard >= 0.5) codegraph co-change --min-support 5 # Minimum co-commit count codegraph co-change --full # Include all details ``` 共变数据也会丰富 `diff-impact` —— 历史耦合文件会与静态依赖分析一起显示在 `historicallyCoupled` 部分。 ### 结构与热点 ``` codegraph structure # Directory overview with cohesion scores codegraph triage --level file # Files with extreme fan-in, fan-out, or density codegraph triage --level directory --sort coupling --no-tests ``` ### 代码健康与架构 ``` codegraph complexity # Per-function cognitive, cyclomatic, nesting, MI codegraph complexity --health -T # Full Halstead health view (volume, effort, bugs, MI) codegraph complexity --sort mi -T # Sort by worst maintainability index codegraph complexity --above-threshold -T # Only functions exceeding warn thresholds codegraph communities # Leiden community detection — natural module boundaries codegraph communities --drift -T # Drift analysis only — split/merge candidates codegraph communities --functions # Function-level community detection codegraph check # Pass/fail rule engine (exit code 1 on fail) codegraph check -T # Exclude test files from rule evaluation ``` ### 数据流、CFG 与 AST ``` codegraph dataflow # Data flow edges for a function (flows_to, returns, mutates) codegraph dataflow --impact # Transitive data-dependent blast radius codegraph cfg # Control flow graph (text format) codegraph cfg --format dot # CFG as Graphviz DOT codegraph cfg --format mermaid # CFG as Mermaid diagram codegraph ast # List all stored AST nodes codegraph ast "handleAuth" # Search AST nodes by pattern (GLOB) codegraph ast -k call # Filter by kind: call, new, string, regex, throw, await codegraph ast -k throw --file src/ # Combine kind and file filters ``` ### 审计、分诊与批处理 用于风险驱动的工作流和多代理调度的复合命令。 ``` codegraph audit # Combined structural summary + impact + health in one report codegraph audit --quick # Structural summary only (skip impact and health) codegraph audit src/queries.js -T # Audit all functions in a file codegraph triage # Ranked audit priority queue (connectivity + hotspots + roles) codegraph triage -T --limit 20 # Top 20 riskiest functions, excluding tests codegraph triage --level file -T # File-level hotspot analysis codegraph triage --level directory -T # Directory-level hotspot analysis codegraph batch target1 target2 ... # Batch query multiple targets in one call codegraph batch --json targets.json # Batch from a JSON file ``` ### CI 验证 `codegraph check` 为 CI 门禁和状态机提供可配置的通过/失败断言。退出码 0 = 通过，1 = 失败。 ``` codegraph check # Run manifesto rules on whole codebase codegraph check --staged # Check staged changes (diff predicates) codegraph check --staged --rules # Run both diff predicates AND manifesto rules codegraph check --no-new-cycles # Fail if staged changes introduce cycles codegraph check --max-complexity 30 # Fail if any function exceeds complexity threshold codegraph check --max-blast-radius 50 # Fail if blast radius exceeds limit codegraph check --no-boundary-violations # Fail on architecture boundary violations codegraph check main # Check current branch vs main ``` ### CODEOWNERS 将图符号映射到 CODEOWNERS 条目。显示谁拥有每个函数并揭示所有权边界。 ``` codegraph owners # Show ownership for all symbols codegraph owners src/queries.js # Ownership for symbols in a specific file codegraph owners --boundary # Show ownership boundaries between modules codegraph owners --owner @backend # Filter by owner ``` 所有权数据也会丰富 `diff-impact` —— 受影响的负责人和建议的审查者将与静态依赖分析一起显示。 ### 快照 轻量级 SQLite 数据库备份和恢复 —— 重构前的检查点，无需重建即可立即回滚。 ``` codegraph snapshot save before-refactor # Save a named snapshot codegraph snapshot list # List all snapshots codegraph snapshot restore before-refactor # Restore a snapshot codegraph snapshot delete before-refactor # Delete a snapshot ``` ### 导出与可视化 ``` codegraph export -f dot # Graphviz DOT format codegraph export -f mermaid # Mermaid diagram codegraph export -f json # JSON graph codegraph export -f graphml # GraphML (XML standard) codegraph export -f graphson # GraphSON (TinkerPop v3 / Gremlin) codegraph export -f neo4j # Neo4j CSV (bulk import, separate nodes/relationships files) codegraph export --functions -o graph.dot # Function-level, write to file codegraph plot # Interactive HTML viewer with force/hierarchical/radial layouts codegraph cycles # Detect circular dependencies codegraph cycles --functions # Function-level cycles ``` ### 语义搜索 为每个函数、方法和类提供本地嵌入 —— 通过自然语言搜索。所有操作均使用 [@huggingface/transformers](https://huggingface.co/docs/transformers.js) 在本地运行 —— 无需 API 密钥。 ``` codegraph embed # Build embeddings (default: nomic-v1.5) codegraph embed --model nomic # Use a different model codegraph search "handle authentication" codegraph search "parse config" --min-score 0.4 -n 10 codegraph search "parseConfig" --mode keyword # BM25 keyword-only (exact names) codegraph search "auth flow" --mode semantic # Embedding-only (conceptual) codegraph search "auth flow" --mode hybrid # BM25 + semantic RRF fusion (default) codegraph models # List available models ``` #### 多查询搜索 使用 `;` 分隔查询，可一次从多个角度进行搜索。结果使用 [倒数排名融合 (RRF)](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) 进行排名 —— 在多个查询中排名靠前的项目会上升至顶部。 ``` codegraph search "auth middleware; JWT validation" codegraph search "parse config; read settings; load env" -n 20 codegraph search "error handling; retry logic" --kind function codegraph search "database connection; query builder" --rrf-k 30 ``` 单个尾随分号会被忽略（回退到单查询模式）。`--rrf-k` 标志控制 RRF 平滑常数（默认为 60） —— 较低的值会赋予排名靠前的结果更多权重。 #### 可用模型 | 标志 | 模型 | 维度 | 大小 | 许可证 | 备注 | |---|---|---|---|---|---| | `minilm` | all-MiniLM-L6-v2 | 384 | ~23 MB | Apache-2.0 | 最快，适合快速迭代 | | `jina-small` | jina-embeddings-v2-small-en | 512 | ~33 MB | Apache-2.0 | 质量更好，体积仍然很小 | | `jina-base` | jina-embeddings-v2-base-en | 768 | ~137 MB | Apache-2.0 | 高质量，8192 token 上下文 | | `jina-code` | jina-embeddings-v2-base-code | 768 | ~137 MB | Apache-2.0 | 最适合代码搜索，基于代码+文本训练（需要 HF token） | | `nomic` | nomic-embed-text-v1 | 768 | ~137 MB | Apache-2.0 | 良好的质量，8192 上下文 | | `nomic-v1.5` (默认) | nomic-embed-text-v1.5 | 768 | ~137 MB | Apache-2.0 | **改进的 nomic，Matryoshka 维度** | | `bge-large` | bge-large-en-v1.5 | 1024 | ~335 MB | MIT | 最佳通用检索，MTEB 最高分 | 在 `embed` 期间使用的模型存储在数据库中，因此 `search` 会自动检测它 —— 搜索时无需传递 `--model`。 ### 多仓库注册表 管理支持 codegraph 的项目的全局注册表。注册表存储已构建图的路径，以便在启用多仓库模式时 MCP server 可以查询它们。 ``` codegraph registry list # List all registered repos codegraph registry list --json # JSON output codegraph registry add # Register a project directory codegraph registry add -n my-name # Custom name codegraph registry remove # Unregister ``` `codegraph build` 会自动注册项目 —— 无需手动设置。 ### 常用标志 | 标志 | 描述 | |---|---| | `-d, --db ` | `graph.db` 的自定义路径 | | `-T, --no-tests` | 排除 `.test.`、`.spec.`、`__test__` 文件（适用于大多数查询命令，包括 `query`、`fn-impact`、`path`、`context`、`where`、`diff-impact`、`search`、`map`、`roles`、`co-change`、`deps`、`impact`、`complexity`、`communities`、`branch-compare`、`audit`、`triage`、`check`、`dataflow`、`cfg`、`ast`、`exports`、`children`） | | `--depth ` | 传递性追踪深度（默认因命令而异） | | `-j, --json` | 输出为 JSON | | `-v, --verbose` | 启用调试输出 | | `--engine ` | 解析器引擎：`native`、`wasm` 或 `auto`（默认：`auto`） | | `-k, --kind ` | 按类型过滤：`function`、`method`、`class`、`interface`、`type`、`struct`、`enum`、`trait`、`record`、`module`、`parameter`、`property`、`constant` | | `-f, --file ` | 范围限定为特定文件（`fn`、`context`、`where`） | | `--mode ` | 搜索模式：`hybrid`（默认）、`semantic` 或 `keyword`（`search`） | | `--ndjson` | 输出为换行符分隔的 JSON（每行一个对象） | | `--table` | 输出为自动列对齐的表格 | | `--csv` | 输出为 CSV（RFC 4180，嵌套对象被展平） | | `--limit ` | 限制结果数量 | | `--offset ` | 跳过前 N 个结果（分页） | | `--rrf-k ` | 多查询搜索的 RRF 平滑常数（默认 60） | ## 🌐 语言支持 | 语言 | 扩展名 | 导入 | 导出 | 调用点 | 继承¹ | 类型推断² | 数据流 | |---|---|:---:|:---:|:---:|:---:|:---:|:---:| |  | `.js`, `.jsx`, `.mjs`, `.cjs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |  | `.ts`, `.tsx` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |  | `.py`, `.pyi` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |  | `.go` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |  | `.rs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |  | `.java` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |  | `.cs` | ✓ | ✓ ✓ | ✓ | ✓ | ✓ | |  | `.php`, `.phtml` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |  | `.rb`, `.rake`, `.gemspec` | ✓ | ✓ | ✓ | ✓ | —³ | ✓ | |  | `.c`, `.h` | ✓ | ✓ | ✓ | —⁴ | —⁴ | ✓ | |  | `.cpp`, `.hpp`, `.cc`, `.cxx` | ✓ | ✓ | ✓ | ✓ | — | ✓ | |  | `.kt`, `.kts` | ✓ | ✓ | ✓ | ✓ | — | ✓ | |  | `.swift` | ✓ | ✓ | ✓ | ✓ | — | ✓ | |  | `.scala`, `.sc` | ✓ | ✓ | ✓ | ✓ | — | ✓ | |  | `.sh`, `.bash` | ✓ | ✓ | ✓ | —⁴ | —⁴ | ✓ | |  | `.ex`, `.exs` | ✓ | ✓ | ✓ | — | — | ✓ | |  | `.lua` | ✓ | ✓ | ✓ | — | — | ✓ | |  | `.dart` | ✓ | ✓ | ✓ | ✓ | — | ✓ | |  | `.zig` | ✓ | ✓ | ✓ | — | — | ✓ | |  | `.hs` | ✓ | ✓ | ✓ | — | — | ✓ | |  | `.ml`, `.mli` | ✓ | ✓ | ✓ | — | — | ✓ | |  | `.tf`, `.hcl` | ✓ | —³ | —³ | —³ | —³ | —³ | ## ⚙️ 工作原理 ``` ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌──────────┐ ┌─────────┐ │ Source │──▶│ tree-sitter│──▶│ Extract │──▶│ Resolve │──▶│ SQLite │ │ Files │ │ Parse │ │ Symbols │ │ Imports │ │ DB │ └──────────┘ └───────────┘ └───────────┘ └──────────┘ └─────────┘ │ ▼ ┌─────────┐ │ Query │ └─────────┘ ``` 1. **解析** — tree-sitter 将每个源文件解析为 AST（原生 Rust 引擎或 WASM 备用方案） 2. **提取** — 提取函数、类、方法、接口、导入、导出、调用点、参数、属性和常量 3. **解析** — 导入被解析为实际文件（处理 ESM 约定、`tsconfig.json` 路径别名、`baseUrl`） 4. **存储** — 所有内容以节点 + 边的形式存入 SQLite，包含 tree-sitter 节点边界以及结构边（`contains`、`parameter_of`、`receiver`） 5. **分析**（可选） — 复杂度指标、控制流图（`--cfg`）、数据流边（`--dataflow`）和 AST 节点存储 6. **查询** — 所有查询都在本地针对 SQLite 数据库运行 —— 通常在 100 毫秒以内 ### 增量重建 依赖图保持最新状态，无需重新解析整个代码库。三层变更检测确保重建的工作量与更改的内容成正比，而不是与项目的大小成正比： 1. **第 0 层 — 日志 (O(changed))：** 如果 `codegraph watch` 正在运行，变更日志会准确记录哪些文件被修改。下次构建会读取日志并仅处理这些文件 —— 零文件系统扫描 2. **第 1 层 — mtime+大小 (O(n) 次统计, O(changed) 次读取)：** 没有日志？Codegraph 会对每个文件进行 stat 操作，并将 mtime + 大小与存储的值进行比较。匹配的文件在不读取单个字节的情况下被跳过 3. **第 2 层 — 哈希 (O(changed) 次读取)：** 未通过 mtime/大小检查的文件将被读取并进行 MD5 哈希。只有哈希实际更改的文件才会被重新解析和重新插入 **结果：** 在包含 3,000 个文件的项目中更改一个文件，重建在不到一秒钟内完成。将它放入 commit 钩子、文件监视器中，或者让你的 AI 代理触发它。 ### 双引擎 Codegraph 附带两个解析引擎： | 引擎 | 工作原理 | 何时使用 | |--------|-------------|----------------| | **Native** (Rust) | 从 `crates/codegraph-core/` 构建的 napi-rs 插件 —— 通过 rayon 进行并行多核解析 | 当预构建的二进制文件可用时自动选择 | | **WASM** | `web-tree-sitter` 使用 `grammars/` 中预构建的 `.wasm` 语法 | 当原生插件未安装时作为备用方案 | 两个引擎产生相同的输出。使用 `--engine native|wasm|auto` 控制选择（默认：`auto`）。 在原生路径上，Rust 端到端处理整个热路径管道： | 阶段 | Rust 的工作 | |-------|---------------| | **解析** | 通过 rayon 进行并行多文件 tree-sitter 解析（比 WASM 快 3.5 倍） | | **提取** | 符号、导入、调用、类、类型映射、AST 节点 —— 一次遍历完成 | | **分析** | 在解析期间按函数预计算复杂度（认知、圈复杂度、Halstead）、CFG 和数据流 | | **解析** | 具有 6 级优先级系统和置信度评分的导入解析 | | **边** | 调用、接收者、扩展和实现边的推断 | | **数据库写入** | 通过 rusqlite 进行所有插入（节点、边、AST 节点、复杂度、CFG、数据流） —— `better-sqlite3` 仅在 WASM 备用路径中延迟加载 | Rust crate (`crates/codegraph-core/`) 暴露了一个 `NativeDatabase` napi-rs 类，它为完整的构建生命周期持有一个持久的 `rusqlite::Connection`，从而消除了每次操作中 JS↔SQLite 的往返开销。 ### 调用解析 调用使用**限定解析** —— 方法调用（`obj.method()`）与独立函数调用区分开来，内置接收者（`console`、`Math`、`JSON`、`Array`、`Promise` 等）会被自动过滤掉。导入范围得到尊重：对 `foo()` 的调用只会解析到实际导入或在同一文件中定义的函数，从而消除名称冲突引起的误报。 | 优先级 | 来源 | 置信度 | |---|---|---| | 1 | **导入感知** —— `import { foo } from './bar'` → 链接到 `bar` | `1.0` | | 2 | **同一文件** —— 当前文件中的定义 | `1.0` | | 3 | **同一目录** —— 兄弟文件中的定义（仅限独立调用） | `0.7` | | 4 | **同一父目录** —— 兄弟目录中的定义（仅限独立调用） | `0.5` | | 5 | **方法层级** —— 通过 `extends`/`implements` 解析 | 不定 | 在未知接收者上的方法调用会完全跳过全局备用方案 —— `stmt.run()` 永远不会解析到另一个文件中独立的 `run` 函数。重复的调用者/被调用者边会自动去重。像 `fn.call()`、`fn.apply()`、`fn.bind()` 和 `obj["method"]()` 这样的动态模式也会在尽力而为的基础上被检测到。 Codegraph 还会从常见的回调模式中提取符号：Commander `.command().action()` 回调（作为 `command:build`）、Express 路由处理器（作为 `route:GET /api/users`）和事件发射器监听器（作为 `event:data`）。 ## 📊 性能 每次发布时通过 CI 进行自我测量（[构建基准测试](generated/benchmarks/BUILD-BENCHMARKS.md) | [嵌入基准测试](generated/benchmarks/EMBEDDING-BENCHMARKS.md) | [查询基准测试](generated/benchmarks/QUERY-BENCHMARKS.md) | [增量基准测试](generated/benchmarks/INCREMENTAL-BENCHMARKS.md) | [解析精度/召回率](tests/benchmarks/resolution/))： | 指标 | 最新版 (WASM) | |---|---| | 构建速度 | **14.2 毫秒/文件** | | 查询时间 | **12毫秒** | | 空操作重建 | **15毫秒** | | 1 个文件重建 | **542毫秒** | | 查询：fn-deps | **2毫秒** | | 查询：path | **2毫秒** | | ~50,000 个文件 (估计) | **~710.0秒 构建时间** | 指标按每个文件进行标准化，以便进行跨版本比较。上述时间是针对完整的初始构建 —— 增量重建仅重新解析更改的文件。 ### 轻量级占用空间 仅有 **3 个运行时依赖** —— 其他所有内容都是可选的或 devDependency： | 依赖 | 作用 | | | |---|---|---|---| | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) | SQLite 驱动（WASM 引擎；延迟加载，不用于原生引擎读取） |  |  | | [commander](https://github.com/tj/commander.js) | CLI 参数解析 |  |  | | [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) | WASM tree-sitter 绑定 |  |  | 可选：`@huggingface/transformers`（语义搜索）、`@modelcontextprotocol/sdk`（MCP server） —— 仅在需要时延迟加载。 ## 🤖 AI 代理集成（核心） ### MCP Server Codegraph 是围绕 [模型上下文协议](https://modelcontextprotocol.io/) 服务器构建的，该服务器具有 30 个工具（多仓库模式下有 31 个） —— 代理消费依赖图的主要方式： ``` codegraph mcp # Single-repo mode (default) — only local project codegraph mcp --multi-repo # Enable access to all registered repos codegraph mcp --repos a,b # Restrict to specific repos (implies --multi-repo) ``` **单仓库模式（默认）：** 工具仅在本地 `.codegraph/graph.db` 上运行。`repo` 参数和 `list_repos` 工具不会暴露给 AI 代理**多仓库模式（`--multi-repo`）：** 所有工具都获得一个可选的 `repo` 参数来定位任何已注册的仓库，并且 `list_repos` 变得可用。使用 `--repos` 限制代理可以访问的仓库。 ### CLAUDE.md / 代理指令 将此添加到项目的 `CLAUDE.md` 中，以帮助 AI 代理使用 codegraph。[AI 代理指南](docs/guides/ai-agent-guide.md#claudemd-template)中包含所有命令的完整模板。 ``` ## Codegraph This project uses codegraph for dependency analysis. The graph is at `.codegraph/graph.db`. ### 修改代码前： 1. `codegraph where ` — find where the symbol lives 2. `codegraph audit --quick ` — understand the structure 3. `codegraph context -T` — get full context (source, deps, callers) 4. `codegraph fn-impact -T` — check blast radius before editing ### 修改代码后： 5. `codegraph diff-impact --staged -T` — verify impact before committing ### 其他有用的命令 - `codegraph build .` — rebuild graph (incremental by default) - `codegraph map` — module overview · `codegraph stats` — graph health - `codegraph query -T` — call chain · `codegraph path -T` — shortest path - `codegraph deps ` — file deps · `codegraph exports -T` — export consumers - `codegraph audit -T` — full risk report · `codegraph triage -T` — priority queue - `codegraph check --staged` — CI gate · `codegraph batch t1 t2 -T --json` — batch query - `codegraph search ""` — semantic search · `codegraph cycles` — cycle detection - `codegraph roles --role dead -T` — dead code · `codegraph complexity -T` — metrics - `codegraph dataflow -T` — data flow · `codegraph cfg -T` — control flow ### Flags - `-T` — exclude test files (use by default) · `-j` — JSON output - `-f, --file ` — scope to file · `-k, --kind ` — filter kind ``` ## 📋 最佳实践 有关集成指南，请参见 **[docs/guides/recommended-practices.md](docs/guides/recommended-practices.md)**： - **Git 钩子** —— 提交时自动重建、推送时影响检查、提交信息丰富化 - **CI/CD** —— PR 影响评论、阈值门禁、图缓存 - **AI 代理** —— MCP server、CLAUDE.md 模板、Claude Code 钩子 - **开发者工作流** —— 监视模式、编辑前先探索、语义搜索 - **安全凭证** —— `apiKeyCommand` 支持 1Password、Bitwarden、Vault、macOS Keychain、`pass` 有关 AI 专用集成，请参见 **[AI 代理指南](docs/guides/ai-agent-guide.md)** —— 这是一份全面的参考，涵盖了 6 步代理工作流、完整的命令到 MCP 映射、Claude Code 钩子和节省 token 的模式。 ## 🔁 CI / GitHub Actions Codegraph 附带一个即用型的 GitHub Actions 工作流，可在每个拉取请求上评论影响分析。 将 `.github/workflows/codegraph-impact.yml` 复制到你的仓库中，每个 PR 都会收到如下评论： ## 🛠️ 配置 在项目根目录中创建一个 `.codegraphrc.json` 来自定义行为： ``` { "include": ["src/**", "lib/**"], "exclude": ["**/*.test.js", "**/__mocks__/**"], "ignoreDirs": ["node_modules", ".git", "dist"], "extensions": [".js", ".ts", ".tsx", ".py"], "aliases": { "@/": "./src/", "@utils/": "./src/utils/" }, "build": { "incremental": true }, "query": { "excludeTests": true } } ``` ### Manifesto 规则 为 `codegraph check`（manifesto 模式）配置通过/失败阈值： ``` { "manifesto": { "rules": { "cognitive_complexity": { "warn": 15, "fail": 30 }, "cyclomatic_complexity": { "warn": 10, "fail": 20 }, "nesting_depth": { "warn": 4, "fail": 6 }, "maintainability_index": { "warn": 40, "fail": 20 }, "halstead_bugs": { "warn": 0.5, "fail": 1.0 } } } } ``` 当任何函数超过 `fail` 阈值时，`codegraph check` 将以退出码 1 退出 —— 非常适合 CI 门禁。 ### LLM 凭证 Codegraph 支持使用 `apiKeyCommand` 字段进行安全的凭证管理。你可以无需将 API 密钥存储在配置文件或环境变量中，而是在运行时调用外部机密管理器： ``` { "llm": { "provider": "openai", "apiKeyCommand": "op read op://vault/openai/api-key" } } ``` 命令以空格分隔，并使用 `execFileSync` 执行（没有 shell 注入风险）。优先级：**命令输出 > `CODEGRAPH_LLM_API_KEY` 环境变量 > 文件配置**。失败时，codegraph 会发出警告并回退到下一个来源。 支持任何机密管理器：1Password CLI (`op`)、Bitwarden (`bw`)、`pass`、HashiCorp Vault、macOS Keychain (`security`)、AWS Secrets Manager 等。 ## 📖 编程式 API Codegraph 还导出完整的 API 供你用于自己的工具中： ``` import { buildGraph, queryNameData, findCycles, exportDOT, normalizeSymbol } from '@optave/codegraph'; // Build the graph buildGraph('/path/to/project'); // Query programmatically const results = queryNameData('myFunction', '/path/to/.codegraph/graph.db'); // All query results use normalizeSymbol for a stable 7-field schema ``` ``` import { parseFileAuto, getActiveEngine, isNativeAvailable } from '@optave/codegraph'; // Check which engine is active console.log(getActiveEngine()); // 'native' or 'wasm' console.log(isNativeAvailable()); // true if Rust addon is installed // Parse a single file (uses auto-selected engine) const symbols = await parseFileAuto('/path/to/file.ts'); ``` ``` import { searchData, multiSearchData, buildEmbeddings } from '@optave/codegraph'; // Build embeddings (one-time) await buildEmbeddings('/path/to/project'); // Single-query search const { results } = await searchData('handle auth', dbPath); // Multi-query search with RRF ranking const { results: fused } = await multiSearchData( ['auth middleware', 'JWT validation'], dbPath, { limit: 10, minScore: 0.3 } ); // Each result has: { name, kind, file, line, rrf, queryScores[] } ``` ## ⚠️ 局限性 - **无 TypeScript 类型检查器集成** —— 类型推断解析注解、`new` 表达式和赋值链，但不调用 `tsc` 进行重载解析或复杂的泛型处理 - **动态调用是尽力而为的** —— 复杂的计算属性访问和 `eval` 模式无法被解析 - **Python 导入** —— 解析相对导入，但不跟踪 `sys.path` 或虚拟环境包 - **数据流分析** —— 过程内（单函数范围），非过程间 ## 🗺️ 路线图 有关完整的开发路线图，请参见 **[ROADMAP.md](docs/roadmap/ROADMAP.md)**；有关稳定性策略和版本保证，请参见 **[STABILITY.md](STABILITY.md)**。当前计划： 1. ~~**Rust 核心**~~ — **已完成** (v1.3.0) — 通过 napi-rs 进行原生 tree-sitter 解析、并行多核解析、增量重新解析、Rust 中的导入解析和循环检测 2. ~~**基础加固**~~ — **已完成** (v1.5.0) — 解析器注册表、完整的 MCP、测试覆盖率、增强配置、多仓库 MCP 3. ~~**分析扩展**~~ — **已完成** (v2.7.0) — 复杂度指标、社区发现、流追踪、共变、manifesto、边界规则、check、分诊、审计、批处理、混合搜索 4. ~~**深度分析与图丰富化**~~ — **已完成** (v3.0.0) — 数据流分析、过程内 CFG、AST 节点存储、扩展的节点/边类型、交互式查看器、exports 命令 5. ~~**架构重构**~~ — **已完成** (v3.1.5) — 统一的 AST 分析、可组合的 MCP、领域错误、构建器管道、图模型、限定名、表示层、CLI 可组合性 6. ~~**解析准确度**~~ — **已完成** (v3.3.1) — 类型推断、接收者类型追踪、死代码角色子类别、解析基准测试、`package.json` 导出、monorepo 工作区解析 7. ~~**TypeScript 迁移**~~ — **已完成** (v3.4.0) — 所有 271 个源文件已从 JS 迁移至 TS，零 `.js` 文件残留 8. ~~**原生分析加速**~~ — **已完成** (v3.5.0) — 所有构建阶段均使用 Rust/rusqlite，亚 100 毫秒增量重建，better-sqlite3 仅作为备用方案延迟加载 9. **扩展语言支持** — **进行中** (v3.7.0) — 第 1 批已发布（C、C++、Kotlin、Swift、Scala、Bash），第 2 批已发布（Elixir、Lua、Dart、Zig、Haskell、OCaml）；其余 11 种分为 2 批（23 → 34） 10. **分析深度** — TypeScript 原生解析、过程间类型传播、基于字段的指向分析 11. **运行时与可扩展性** — 事件驱动管道、插件系统、查询缓存、分页 12. **质量、安全与技术债务** — 供应链安全（SBOM、SLSA）、CI 覆盖率门禁、定时器清理、技术债务消灭清单 13. **智能嵌入** — LLM 生成的描述、增强的嵌入、模块摘要 14. **自然语言查询** — `codegraph ask` 命令、对话式会话 15. **GitHub 集成与 CI** — 可复用的 GitHub Action、LLM 增强的 PR 审查、SARIF 输出 16. **高级功能** — 死代码检测、monorepo 支持、代理搜索 ## 🤝 贡献 欢迎贡献！有关设置、工作流、提交约定、测试和架构说明的完整指南，请参见 **[CONTRIBUTING.md](CONTRIBUTING.md)**。 ``` git clone https://github.com/optave/ops-codegraph-tool.git cd codegraph npm install npm test ``` 想要添加新语言？请查阅 **[添加新语言](docs/contributing/adding-a-language.md)**。 ## 📄 许可证 [Apache-2.0](LICENSE)

_{使用 tree-sitter 和 better-sqlite3 构建。你的代码始终留在你的机器上。}

标签：DNS重绑定攻击, Git差异分析, GNU通用公共许可证, MCP Server, MITM代理, Node.js, NPM包, OSV-Scalibr, 人工智能代理, 代码分析, 代码搜索, 代码智能, 依赖图, 凭证管理, 可视化界面, 复杂度度量, 威胁情报, 开发者工具, 本地部署, 架构边界, 自动化攻击, 语义搜索, 重构辅助, 错误基检测, 静态代码分析