tae2089/code-context-graph

# code-context-graph 本地代码分析工具，通过 Tree-sitter 将代码库解析为知识图谱。支持 12 种语言、33 个 MCP 工具以及自定义注解搜索。 CCG 主要为 GPT、Claude、Codex 和其他基于 LLM 的编程助手构建。它充当本地或自托管的上下文基础设施：助手可以通过意图搜索代码、检查调用图、追踪影响、检索文档，并将响应限制在一定范围内，而不是将整个代码库读取到上下文中。 这是一个由开发者操作的工具，而不是通用的 SaaS 管理产品。预期的用户是编程助手和能够运行 CLI 命令、配置 MCP、阅读日志并使用生成的图谱/文档来指导代码修改的开发者。 受 [code-review-graph](https://github.com/tirth8205/code-review-graph) 启发 —— 这是一个基于 Python 的代码分析工具。本项目使用 Go 重新实现并扩展了该概念，提供了多数据库支持、自定义注解系统以及用于 AI 驱动代码理解的 MCP 集成。 ## 特性 - **12 种语言**：Go、Python、TypeScript、Java、Ruby、JavaScript、C、C++、Rust、Kotlin、PHP、Lua/Luau - **33 个 MCP 工具**：解析、搜索、影响分析、流程追踪、死代码检测、后处理操作、namespace 文件管理等 - **证据驱动的代码探索**：基于数据库的检索会在助手深入探索具体的图节点之前，返回带有匹配字段、证据节点和可选文档的小型文件级候选项 - **浏览器 Wiki UI**：`ccg-server` 可以提供生成的文档、树状搜索、基于数据库的检索、Context Tray 复制以及 Obsidian 风格的图查看器 - **自定义注解**：`@intent`、`@domainRule`、`@sideEffect`、`@mutates`、`@index` —— 根据业务上下文搜索代码（[详情](guide/annotations.md)） - **Webhook 同步**：GitHub / Gitea 推送事件 → 自动 clone + 构建，支持按仓库的分支过滤和 `.ccg.yaml` `include_paths` 自动加载（[详情](guide/webhook.md)） - **Eval**：基于 Golden 语料库的解析器准确率 (P/R/F1) 和搜索质量 (P@K, MRR, nDCG) 评估（[详情](guide/eval.md)） - **多数据库**：SQLite（本地）、PostgreSQL - **全文搜索**：FTS5 (SQLite)、tsvector+GIN (PostgreSQL) ## 安装说明 ### npm / bun（推荐） ``` npm install -g code-context-graph # or bun install -g code-context-graph ``` npm 包会同时安装 `ccg` 和 `ccg-server`。 ### go install ``` go install github.com/tae2089/code-context-graph/cmd/ccg@latest go install github.com/tae2089/code-context-graph/cmd/ccg-server@latest ``` ### 从源码构建 ``` CGO_ENABLED=1 go build -tags "fts5" -o ccg ./cmd/ccg/ CGO_ENABLED=1 go build -tags "fts5" -o ccg-server ./cmd/ccg-server/ # Or use Makefile (injects version from git tag automatically) make build # Local stripped release-style build make release ``` ## 快速开始 ``` # Parse your project. For the default local SQLite database (ccg.db), runtime # commands create and migrate the database automatically on first use only when # the schema is missing. ccg build . # Build complete: 70 files, 749 nodes, 7387 edges # Search (includes annotations) ccg search "authentication" # Search by business context ccg search "payment" # finds functions with @intent/@domainRule about payments # Build docs and the default vectorless RAG index for agent-oriented exploration ccg docs --out docs # Serve the browser Wiki UI from built assets; builds the graph for DB-backed APIs make wiki-run # Graph statistics ccg status # Version info ccg version # Namespace isolation (MSA) ccg build ./backend --namespace backend ccg search --namespace backend "auth" # Evaluate parser accuracy (12 languages) ccg eval --suite parser # Update golden corpus ccg eval --suite parser --update ``` `ccg docs` 会生成 Markdown 并写入 `.ccg/wiki-index.json` 作为浏览器 Wiki 的兼容性快照。Wiki 优先使用图数据库进行树状 导航和搜索，仅在基于数据库的导航不可用时才使用 `wiki-index.json`。 默认情况下，`ccg docs` 还会刷新社区结构并写入 `.ccg/doc-index.json` 作为兼容性快照，用于 手动 RAG 索引工作流；运行时的 `search_docs` 使用基于数据库的图和 注解证据。当你只需要 Markdown 和 Wiki 快照时，请使用 `--rag=false`； 或者当你想从现有社区数据行重建 RAG 索引而不重新计算社区时，请使用 `--rag-refresh=false`。 对于 LLM 助手，对于广泛的问题（例如“webhook 同步是如何工作的？”或“运营风险在哪里？”），请使用基于数据库的 `search_docs` 作为第一站。它不是 Top1 搜索引擎；它是一个 证据驱动的缩小范围层，应返回带有 `matched_fields`、`matched_terms` 和证据节点的少量相关 文件。使用 `get_doc_content` 阅读缩小范围后的文档，然后只有在路径缩小后，才使用 `get_node`、`query_graph`、 `trace_flow` 和影响工具。将 `ccg search` 用作专注的 注解/关键字候选项搜索，而不是用于广泛代码理解的第一工具。 如果你使用 PostgreSQL、自定义 SQLite DSN、现有的 schema 或受控的 升级工作流，请在运行时命令之前显式运行 `ccg migrate`。当针对由旧版本创建的现有默认 `ccg.db` 升级 CCG 时，这也 适用。有关完整的 迁移契约，请参阅 [CLI 参考](guide/cli-reference.md)。 ## 浏览器 Wiki 当 `--wiki-dir` 指向已构建的 `web/wiki/dist` 目录时，`ccg-server` 可以在 `/wiki` 路径下提供基于 React 的 Wiki UI。Docker 镜像在 `/usr/share/ccg/wiki` 中包含了构建好的 UI；独立二进制文件将资产分开存放，以保持二进制文件体积最小。 Wiki 适用于检查生成的代码库的开发者和助手： - 在文件夹、包、文件和带注解的符号上进行树状导航 - 关键字搜索和带有匹配证据及小型文件级结果集的基于数据库的 `search_docs` - 来自 CCG 注解的丰富符号详情卡片，即使该符号没有生成 Markdown 文件 - Context Tray，用于将文件和无文档符号收集到一个可以复制到另一个 LLM 工具的 Markdown 包中 - 由 `/wiki/api/graph` 支持的 Graph 标签页，显示 namespace 节点和边，并提供针对结构、调用、导入、类型和符号的过滤器 本地开发快捷方式： ``` make wiki-run ``` 当你在启动服务器之前还需要生成的 Markdown、 `wiki-index.json` 快照和兼容的 `doc-index.json` 时，请使用 `make wiki-run-indexed`。 对于自托管部署，请运行 `ccg-server --wiki-dir `，并使用与 `/mcp` 相同的 bearer token 策略保护 `/wiki/api/*`。有关部署详情，请参阅 [Docker](guide/docker.md#wiki-ui) 和 [运行时布局](guide/runtime-layout.md)。 ## 演示 CCG 解析自身代码库的实际输出。 ### 1. 解析代码库 ``` $ ccg build . Build complete: 127 files, 1220 nodes, 12222 edges ``` ### 2. 图谱统计 ``` $ ccg status Nodes: 1220 Edges: 12222 Files: 127 Node kinds: class: 124 file: 127 function: 405 test: 543 type: 21 Edge kinds: calls: 9245 contains: 1097 imports_from: 1128 inherits: 1 tested_by: 751 Postprocess: Status: ok Fail-closed: 0 Recent failures: 0 ``` ### 3. 代码搜索 ``` $ ccg search "impact analysis" internal/analysis/impact/impact_test.go file internal/analysis/impact/impact_test.go:1 internal/analysis/impact/impact.go file internal/analysis/impact/impact.go:1 mcp.ImpactAnalyzer type internal/mcp/server.go:36 impact.EdgeReader type internal/analysis/impact/impact.go:12 impact.Analyzer.ImpactRadius function internal/analysis/impact/impact.go:42 internal/mcp/handler_analysis.go file internal/mcp/handler_analysis.go:1 $ ccg search "dead code" deadcode.Options class internal/analysis/deadcode/service.go:14 deadcode.Service.Find function internal/analysis/deadcode/service.go:38 mcp.handlers.findDeadCode function internal/mcp/handler_analysis.go:273 ``` ### 4. 通过 MCP 进行助手集成 配置 `.mcp.json` 后，你可以直接询问支持 MCP 的编程助手： 助手会调用 CCG MCP 工具，并直接从图谱中回答： ``` trace_flow(qualified_name: "webhook.WebhookHandler.ServeHTTP") → WebhookHandler.ServeHTTP → SyncQueue.Enqueue → safeHandle (retry loop: max 3 attempts, exponential backoff 1s→30s) → clone (git clone, 15min timeout) → build (ccg build, same context) ``` ``` search(query: "authentication") → internal/webhook/handler.go (HMAC signature validation) → cmd/ccg-server/main.go (--webhook-secret flag) ``` ## MCP 服务器 将 `.mcp.json` 添加到你的项目中： ``` { "mcpServers": { "ccg": { "command": "ccg", "args": ["serve", "--db-driver", "sqlite", "--db-dsn", "ccg.db"] } } } ``` 对于远程 HTTP 模式： 使用 `ccg-server` 运行自托管服务器，并连接到 `/mcp`。当配置了 `--wiki-dir` 时，同一 服务器还可以暴露 `/wiki`： ``` { "mcpServers": { "ccg": { "type": "streamable-http", "url": "http://your-server:8080/mcp" } } } ``` 支持 MCP 的客户端（例如 Codex 或 Claude Code）可以连接并访问 33 个 MCP 工具。完整列表请参阅 [MCP 工具参考](guide/mcp-tools.md)。 ## 架构 ``` Source Code → Tree-sitter Parser → Nodes + Edges + Annotations ↓ SQLite / PostgreSQL (GORM) ↓ FTS Search ↓ ccg serve ccg-server stdio MCP Streamable HTTP + Wiki UI ↓ ↓ ↓ ↑ Coding Agents Remote Clients Browser GitHub / Gitea Webhook Wiki push → clone → build → DB ``` 有关组件分解和 DB schema，请参阅 [架构详情](guide/architecture.md)。 ## 文档 | 指南 | 描述 | |-------|-------------| | [韩语指南](guide/ko/README.md) | 한국어 문서 인덱스 (Korean Documentation Index) | | [CLI 参考](guide/cli-reference.md) | 所有命令、标志和配置文件 (`.ccg.yaml`) | | [Eval](guide/eval.md) | 解析器/搜索质量评估、Golden 语料库和指标 | | [Lint](guide/lint.md) | 详细的 `ccg lint` 类别参考、解释指南和 CI 用法 | | [MCP 工具](guide/mcp-tools.md) | 33 个 MCP 工具、助手技能、AI 驱动注解 | | [注解](guide/annotations.md) | 注解系统 — 标签、示例、搜索 | | [Webhook](guide/webhook.md) | Webhook 同步、分支过滤、HMAC、优雅关闭 | | [Docker](guide/docker.md) | Docker 构建、MCP 服务器、Wiki UI、PostgreSQL 部署 | | [运维](guide/operations.md) | 部署配置、数据库选择、就绪状态、Webhook 运维 | | [后处理失败策略](guide/postprocess-failure-policy.md) | 构建和后处理工具的状态规则、失败原因以及自动降级/fail_closed 策略 | | [运行时布局](guide/runtime-layout.md) | `ccg`、`ccg-server`、Wiki 服务和共享的 `ccg-core` 所有权边界 | | [开发](guide/development.md) | 开发指南、集成测试、项目结构 | | [Namespace 迁移](guide/namespace-migration.md) | 默认 namespace 更改和迁移指南 | | [架构](guide/architecture.md) | 数据流、组件、DB schema | | [CLAUDE.md 指南](guide/claude-md-guide.md) | 使用 CCG 的项目模板 | ## 许可证 MIT

标签：AI编程助手, EVTX分析, MCP, SOC Prime, 代码分析, 代码检索, 凭证管理, 开发工具, 日志审计, 测试用例, 请求拦截