Driftya/code-meridian

# CodeMeridian [](https://www.nuget.org/packages/CodeMeridian.Indexer) [](https://www.nuget.org/packages/CodeMeridian.Indexer) [](https://github.com/Driftya/code-meridian/actions/workflows/ci.yml) [](https://github.com/Driftya/code-meridian/actions/workflows/codeql.yml) [](https://github.com/Driftya/code-meridian/actions/workflows/publish-indexer.yml) [](https://github.com/Driftya/code-meridian/actions/workflows/publish-mcp.yml) [](https://github.com/Driftya/code-meridian/actions/workflows/dependabot/dependabot-updates) [](https://github.com/Driftya/code-meridian/pkgs/container/codemeridian-mcp) CodeMeridian 是一个面向 AI 编程代理的本地图谱记忆层。 它将你的代码库索引到 Neo4j 中，并通过 MCP 暴露其结构，这样 AI 编程工具可以在编辑前提出精确的问题，而不是基于已打开的文件进行猜测。它兼容支持 MCP 的客户端，如 GitHub Copilot、Claude Code、Continue.dev、Codex 风格的代理、Cline 以及本地代理工作流。 它旨在成为大型代码库的确定性上下文层：调用者、依赖项、测试、文档、热点、死代码、诊断以及跨项目关系在各个会话中均保持可用。 CodeMeridian 还可以在已索引的代码和文档之上推导出关键词图谱。这在没有直接结构边的情况下，增加了一个可解释的词汇层，用于查找相关的文档、诊断、endpoint 和符号。 这对于每个 token 都很重要的本地或较小编程模型尤其有用。CodeMeridian 并不试图取代模型。它通过在模型编写代码前提供最小且有用的架构切片，来缩小模型的工作范围。 核心使用不需要 LLM API 密钥。可选的语义特性可以使用本地 Ollama 或云端 embedding 提供程序。助手就是 AI；而 CodeMeridian 是知识引擎。 ## 为什么选择 CodeMeridian？ Copilot 依然可以读取当前打开文件之外的文件，但它必须消耗上下文去发现它们，而且这些关系不会持久化。CodeMeridian 让这种发现变得明确、低成本且可重用。 图谱归你所有。CodeMeridian 将索引的代码结构、文档、诊断和记住的项目知识存储在你的 Neo4j 实例中。没有任何数据会被发送到 CodeMeridian 云服务。如果你使用 Copilot、Codex、Claude Code 或其他托管助手，该助手仍然有它自己的数据处理规则，但 CodeMeridian 知识图谱本身始终在你的控制之下。 | 没有 CodeMeridian | 有 CodeMeridian | |---------------------|------------------| | 助手在搜索上下文时临时加载文件 | 助手查询整个代码库的图谱 | | 上下文在会话间消失 | 知识本地持久化在 Neo4j 中 | | “什么调用了这个方法？”需要手动搜索 | `find_impact` 从调用图中给出答案 | | 重构可能会漏掉隐藏的调用者 | 在修改前就能知晓影响范围 | | 死代码和测试漏洞保持不可见 | `find_unreferenced` 和 `find_coverage_gaps` 会将它们暴露出来 | | 大型上下文窗口被噪音填满 | 代理获取最小且有用的架构切片 | | 小型本地模型在处理广泛的仓库上下文时很吃力 | 基于图谱的上下文使任务变小 | | 助手猜测哪个模型/上下文大小足够 | 上下文包包含 token 估算和模型指导 | | 过时的索引会悄悄误导代理 | 新鲜度和漂移检查会提示何时重新索引 | | 文档和决策存在于代码图谱之外 | 知识、文档、诊断和代码链接可以一起查询 | 这在实践中为你带来的好处： - **本地所有权：** 图谱和知识存储运行在你的 Neo4j 中，而不是一个托管的 CodeMeridian 服务中。 - **持久记忆：** 架构、文档、诊断、外部概念和代理笔记在编辑器重启后依然存在。 - **减少上下文浪费：** 工具返回调用者、被调用者、测试、可能涉及的文件和小代码片段，而不是整个文件的堆砌。 - **更安全的编辑：** 影响、下游依赖、诊断、漂移和缺失的测试在实施前都是可见的。 - **模型感知的上下文：** `build_minimal_context` 估算 token 成本，并建议小型模型是否足够。 - **可解释的结果：** 精确、启发式、过时和仅文件匹配的结果都会被标记，以便助手说明它信任了什么。 ## 专为代理优先的工作流而构建 AI 编程代理非常强大，但它们通常在不完整或临时的上下文中工作。它们可能会重复搜索文件、漏掉隐藏的调用者、忘记之前的发现，或者用嘈杂的整个文件堆砌填满它们的上下文窗口。 CodeMeridian 为这些代理提供了一个持久的、基于图谱的仓库映射图。代理不需要在每次会话中都让模型去重新发现代码库，而是可以向 CodeMeridian 查询它所需的特定架构切片。 典型工作流： 1. 在本地启动 CodeMeridian。 2. 索引你的代码库。 3. 连接一个兼容 MCP 的编程代理。 4. 要求代理在编辑前构建一个最小的上下文包。 5. 让代理在工作时使用影响、新鲜度、文档和测试覆盖率检查。 提示词示例： ``` Use CodeMeridian to build a minimal context pack for the authentication flow before changing login behavior. ``` ## 为什么这对较小的本地模型有帮助 当上下文精确时，小型本地编程模型是最有用的。CodeMeridian 通过将代码库转化为基于图谱的记忆层来提供帮助，这样代理就可以检索到最小且有用的上下文，而不是扫描整个代码库。 这对于 7B 级别的模型、低内存机器以及注重上下文大小、隐私和可重复代码理解的本地优先工作流非常有用。 如果没有 CodeMeridian，模型可能需要从文件名和临时搜索中推断架构。有了 CodeMeridian，代理可以提出有针对性的问题： ``` What calls this method? Which tests cover this service? Which frontend components use this endpoint? What docs mention this symbol? Is the graph fresh enough to trust? What is the smallest context needed for this edit? ``` CodeMeridian 并不能神奇地让一个小模型变得完美。它只是减少了模型必须进行的猜测量。 ## 它索引的内容 CodeMeridian 目前支持： - 通过 Roslyn 索引器支持 C# - 通过 ts-morph 索引器支持 TypeScript / TSX - README 和文档文件 - 配置文件，如 `appsettings*.json`、`meridian*.json`、`.env` 和 Docker Compose YAML - **可选的向量 embedding**，用于语义代码相似度（查找重复模式、重构机会） 索引器被设计为一个与语言无关的 pipeline：未来的语言索引器可以写入相同的图模型，并通过相同的 MCP 工具进行查询。Embedding 是**可选的**（默认禁用），现在由 CodeMeridian 后端生成，它可以使用本地 Ollama（免费）或 OpenAI（付费）。 ## 快速开始 前置条件： - Docker Desktop - .NET 10 SDK - VS Code 中的 GitHub Copilot - 索引 TypeScript / TSX 需要 Node.js 18+ 安装 CLI： ``` dotnet tool install -g CodeMeridian.Indexer ``` 启动 CodeMeridian： ``` codemeridian serve codemeridian init ``` 索引此仓库： ``` codemeridian index . --clear ``` 如果你在安装全局工具之前从源码检出运行： ``` Copy-Item .env.sample .env docker compose up -d dotnet run --project tools/Indexer -- . --clear dotnet run --project tools/Indexer -- config rebuild --project CodeMeridian dotnet run --project tools/Indexer -- index . --skip-keywords dotnet run --project tools/Indexer -- keywords rebuild --project CodeMeridian ``` 要创建本地项目配置和 MCP 客户端配置，请运行： ``` codemeridian init . ``` 稍后再次运行 `codemeridian init .` 以刷新现有的 `meridian.json`。缺失的默认值将被合并，配置 `version` 将被提升，并且你现有的特定项目值将被保留。 如果 `.meridian/architecture.json` 不存在，`codemeridian init .` 还会对其进行初始化，将包 `architectures/` 文件夹中捆绑的模板复制到 `.meridian/architectures/` 中，并将代理指导复制到 `meridian-agent-capabilities/` 中，以便仓库文档由用户拥有。捆绑的模板包括 `architecture.clean.template.json`、`architecture.onion.template.json`、`architecture.hexagonal.template.json`、`architecture.layered.template.json` 和 `architecture.vertical-slice.template.json`。活动的架构文件在 `meridian.json` 的 `architecture.path` 中被引用，并在索引后驱动 `find_architecture_violations` 和 `find_smell_paths`。 在 VS Code 或任何支持 MCP 的客户端中打开此文件夹。MCP server 通过 `.vscode/mcp.json` 注册，兼容 MCP 的客户端可以在你聊天时调用 CodeMeridian 工具。 ## 常见问题 向 Copilot 提问，例如： ``` Use CodeMeridian to give me an architectural overview. ``` ``` Before changing OrderService.PlaceOrderAsync, what calls it? ``` ``` Which methods have no test coverage? ``` ``` Build a minimal context pack before I change OrderService.PlaceOrderAsync. ``` ``` How is this TypeScript component connected to the backend? ``` ``` Which Newtonsoft.Json usages are safe to replace with System.Text.Json first? ``` ``` What tightly connected groups look like good extraction candidates in payments? ``` ## 用法 请参阅 [usage.md](docs/usage.md) 获取可复制粘贴的提示词，这些提示词可帮助 AI 编程助手在编辑前安全地使用 CodeMeridian。 ## 核心工具 | 工具 | 功能描述 | |------|-------------| | `query_codebase` | 对代码结构进行自然语言搜索 | | `get_architectural_overview` | 按 namespace/module 提供项目映射 | | `get_context_for_editing` | 为节点提供包含调用者/被调用者/接口的紧凑上下文 | | `build_minimal_context` | 有界的上下文包，包含调用者、被调用者、影响、测试、漏洞、可能涉及的文件、token 估算和模型指导 | | `find_impact` | 向后影响范围分析 | | `find_connection` | 两个代码元素之间的最短路径 | | `find_unreferenced` | 死代码候选 | | `find_coverage_gaps` | 未被测试调用的生产代码 | | `find_test_shield` | 映射直接测试保护、间接屏蔽和未屏蔽的变更路径节点 | | `find_similar_nodes` | 查找重复代码模式（需启用 embeddings） | | `hybrid_search` | 查找节点或子系统边界附近语义相似的代码 | | `find_duplicate_candidates` | 审查可能重复的方法/类并附带重构风险信号 | | `find_config_definitions` | 查找规范配置键定义或覆盖的位置 | | `find_config_usage` | 查找哪些代码读取或绑定规范配置键 | | `search_documentation` | 搜索已索引的 README/ADR/文档内容 | | `rebuild_keyword_graph` | 从索引的图谱文本重建推导出的 `Keyword` 节点和 `HAS_KEYWORD` 边 | | `classify_keywords` | 将推导出的关键词分类为 domain/technical/tooling/common/noise 并持久化有用性评分 | | `find_related_knowledge` | 通过共享关键词查找词汇相关的代码和文档 | | `find_implementation_surface` | 对功能目标可能需要修改的文件和符号进行排名 | | `analyze_feature_implementation_path` | 将功能需求或 docs/features 文件映射到实施状态、触及区域、测试、文档、缺失的图谱证据和风险 | | `replace_surface` | 在库迁移之前将依赖项替换工作分组为安全和有风险的集群 | | `suggest_extractions` | 对看起来是良好提取候选者的紧密连接组进行排名 | | `check_graph_freshness` | 从索引的文件、行和时间戳元数据报告图谱置信度 | | `find_graph_drift` | 在依赖精确实施目标之前检测过时的图谱数据 | | `find_smell_paths` | 显示最短的违规架构依赖路径 | | `find_stale_knowledge` | 检测过时的文档、弱提及、孤立的外部概念和孤立的代码引用 | | `knowledge_decay` | `find_stale_knowledge` 的别名，用于图谱原生的过时知识审查 | | `resolve_exact_symbol` | 在编辑前将符号/文件/行提示解析为规范节点 ID | | `clear_project_knowledge` | 在重建之前清除一个项目的索引图谱和文档 | | `clear_code_graph` | 清除所有已索引的代码图谱节点，同时保留文档 | 当 `.meridian/architecture.json` 存在并被索引时，架构规则将来自索引的项目配置。如果尚未索引特定于项目的架构，CodeMeridian 将回退到默认的 clean-architecture 模板。 ## 文档 - [安装说明](docs/installation.md) - [CodeMeridian 的工作原理](docs/how-it-works.md) - [用法](docs/usage.md) - [索引项目](docs/indexing.md) - [评估会话有效性](docs/evaluate.md) - [功能参考](docs/features.md) - [代码 embeddings 和语义搜索](docs/embeddings.md) - [发布 Indexer 工具](docs/publishing.md) - [Ubuntu 无头部署](docs/ubuntu-headless-deploy.md) - [贡献者和代理指南](AGENTS.md) -详细的代理文档](docs/agent/README.md) ## 关键词增强 关键词增强在 `src/McpServer/appsettings.json` 中的 `KeywordEnrichment` 下进行配置。 主要选项： - `MinimumKeywordLength`：默认为 `4` - `AllowedShortTerms`：默认包含 `api`、`mcp`、`cli`、`sdk`、`jwt`、`sql`、`ast`、`ef`、`ts` - `AdditionalStopwords`：无需更改代码即可抑制的项目特定术语数组 典型工作流： ``` 1. Index your code and docs normally. 2. The MCP server queues incremental keyword refresh as nodes and documents are ingested. 3. Use find_related_knowledge on a node ID when you want explainable lexical matches. 4. Run rebuild_keyword_graph or classify_keywords manually when you want a full repair or rule refresh. ``` CLI 等效命令： ``` codemeridian config rebuild --project CodeMeridian codemeridian keywords rebuild --project CodeMeridian codemeridian keywords classify --project CodeMeridian ``` 配置索引作为正常 `codemeridian index` 流程的一部分运行。当你只想要代码、文档和诊断而不需要配置图谱时，请使用 `--skip-config`。现在，直接配置用法提取在 Roslyn 和 TypeScript 索引器中均可用于 `process.env`、`import.meta.env` 和 C# `IConfiguration` 访问模式。 你可以在 `meridian.json` 中使用 `configurationFiles` 覆盖被视为配置源的文件，例如： ``` { "configurationFiles": [".env", "appsettings.json", "appsettings.*.json", "docker-compose*.yaml"] } ``` 关键词分类在 `KeywordClassification` 下配置。它可以将关键词标记为 `Noise`、`CommonProjectTerm`、`TechnicalConcept`、`ToolingConcept`、`ArchitectureConcept`、`DiagnosticConcept`、`DomainConcept` 或 `Unknown`。 ## 项目布局 ``` src/ Core/ Domain models Application/ Query services and orchestration Infrastructure/ Neo4j graph and knowledge storage McpServer/ MCP server and REST ingestion API Sdk/ Client library for ingestion tools/ Indexer/ Unified indexer CLI RoslynIndexer/ C# Roslyn indexer TsIndexer/ TypeScript / TSX indexer docs/ features.md how-it-works.md installation.md indexing.md publishing.md ``` ## 状态 CodeMeridian 处于早期阶段但已可用。它已经可以索引 C# 和 TypeScript/TSX 项目，将图谱持久化在 Neo4j 中，并为 Copilot、Codex 和其他兼容客户端暴露 MCP 工具。路线图记录在 [TODO.md](TODO.md) 中。 ## 贡献 有关贡献指南、AI 辅助开发期望和验证步骤，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

标签：AI编程助手, AI风险缓解, MCP, MITM代理, Neo4j, SOC Prime, 上下文管理, 代码知识图谱, 代码索引, 多人体追踪, 开发工具, 请求拦截