Claude-Cursor-Context-Combiner：基于Git仓库实现多AI开发工具上下文统一与自动化同步

1. 项目概述：一个解决多AI工具协同开发上下文对齐的框架

如果你和我一样，在日常开发中同时使用 Claude Code 和 Cursor，或者更广泛地说，在多个AI辅助开发工具之间切换，那你一定对“上下文漂移”这个问题深有体会。我经常遇到这样的场景：在 Cursor 里和AI助手详细讨论了某个模块的重构方案，切换到 Claude Code 时，又得把整个项目的背景、当前的问题、已经尝试过的方案重新解释一遍。更糟糕的是，两个工具基于各自不完整的上下文给出的建议常常相互矛盾，导致代码风格不一致、逻辑冲突，最后还得我手动去“缝合”这些碎片化的输出。这种重复的解释工作和上下文重建，不仅效率低下，还引入了大量的人为错误风险。

这正是Claude-Cursor-Context-Combiner这个项目要解决的核心痛点。它不是一个全新的AI模型，也不是一个集成了所有功能的超级IDE。相反，它是一套轻量级的流程框架和思维模型。它的核心思想非常直接：与其让每个AI工具各自为政、维护自己孤立且易失的聊天历史作为上下文，不如将Git仓库本身提升为所有工具共享的、唯一的、权威的“真相之源”。通过一套自动化的脚本和约定，确保无论你使用 Claude Code、Cursor 还是其他兼容的工具，它们所“看到”的项目状态和背景信息都是一致的、最新的。

简单来说，这个框架帮你做了三件事：统一入口、固化上下文、自动化同步。它通过一个引导脚本（bootstrap.js）在你的项目根目录建立一套标准化的结构和Git钩子。每次你提交代码时，这套机制会自动运行，利用Repomix这样的工具生成一份结构化的项目快照（通常是一个XML或JSON文件），这份快照就成为了所有AI工具可以共同引用的“项目说明书”。对于大型或复杂的项目，你还可以选择性地集成Serena来增强语义理解能力。最终，你得到的是一个“自描述”的仓库，AI工具可以像查阅最新版技术文档一样，快速、准确地理解项目全貌，从而提供连贯、一致的辅助。

2. 核心设计思路与哲学：为什么是“仓库即上下文”？

在深入技术细节之前，我觉得有必要先聊聊这个项目的设计哲学。这决定了它不是一个简单的“一键脚本”，而是一种工作方式的转变。我称之为“过程优先，而非自动化优先”。

2.1 从“工具中心化”到“系统中心化”的转变

传统的AI辅助开发流程是“工具中心化”的。我们围绕某个特定的IDE或AI聊天界面来组织工作，上下文被锁死在这个工具的会话里。Claude-Cursor-Context-Combiner 倡导的是“系统中心化”。在这里，你的项目代码库本身就是这个系统的核心。AI工具（Claude, Cursor等）被降级为这个系统中的“执行器”或“顾问”。它们不再“拥有”对项目的理解；相反，它们从系统中（即仓库的快照）读取统一的上下文，然后执行任务。

这种转变带来了几个根本性的优势：

1. 确定性取代“魔法”：AI的响应不再依赖于难以复现的、冗长的聊天历史。响应基于一份确定的、可版本控制的快照文件，任何工具在任何时间点看到的信息都是一样的。这极大提升了协作（即使是人与AI的协作）的可预测性和可调试性。
2. 并行化成为可能：因为上下文源是统一的，你完全可以同时在Cusor里修改前端组件，在Claude Code里优化后端API逻辑，而不用担心两者对项目状态的理解出现分歧。它们都基于最新提交后生成的快照进行工作。
3. 上下文持久化：聊天窗口关了，会话超时了，上下文都不会丢失。只要仓库在，最新的快照就在。重新打开任何工具，它都能立刻“跟上进度”。

2.2 核心组件选型背后的逻辑

框架依赖的几个关键组件不是随意选择的，每个都针对性地解决了“上下文共享”中的一个具体问题。

• Git作为基石：这是最自然的选择。Git已经是现代开发的事实标准，它完整记录了项目的演进历史、每一次变更的意图（提交信息）、以及不同分支的状态。利用Git钩子（如post-commit），我们可以在每次代码状态发生正式变化（提交）时，自动触发上下文更新流程，确保快照与代码库同步。
• Repomix作为上下文打包器：我们需要一种方式，将整个代码仓库（可能包含成千上万文件）转换成一个AI工具能够有效处理的、结构化的文本块。简单的文件拼接会丢失结构信息，并且容易超出上下文窗口。Repomix 在这方面做得非常出色。它不仅仅是将文件内容连接起来，它会分析项目结构，智能地包含或排除文件（如忽略node_modules,.git），并生成一个带有目录树、文件路径和内容的规整输出（如XML）。这就像一个为AI量身定做的、浓缩的项目文档。
• Serena作为语义增强器（可选）：对于超大型项目，即使使用Repomix，生成的快照也可能过于庞大。Serena 的作用类似于一个“智能索引”。它可以在后台为你的代码库建立语义索引，当AI工具需要查询某个特定功能（如“用户登录模块”）时，Serena可以动态地从索引中检索出最相关的代码片段，而不是将整个快照塞给AI。这相当于为AI工具加装了一个精准的“搜索雷达”，在上下文窗口有限的情况下尤其有用。
• MCP作为桥梁：Model Context Protocol 是Anthropic推出的一套协议，旨在让Claude等模型能够安全、可控地访问外部工具和数据源。在这个框架中，我们通过MCP服务器，将生成的Repomix快照文件（context.xml）暴露给Claude Desktop。这样，Claude在回答问题时，就能主动去读取这份最新的项目快照，而不是依赖可能过时的聊天记忆。这是实现“上下文实时同步”的技术关键。

注意：这里有一个非常重要的实践心得。初期我尝试过在每次对话时手动粘贴项目结构，或者依赖IDE的整个工作区作为上下文，效果都很差。前者低效且易错，后者则包含太多噪音（构建产物、配置文件等）。Repomix提供的是一种经过筛选和结构化的上下文，它平衡了信息完整性和可用性。而引入Git钩子自动化这个过程，则是将最佳实践“固化”下来，避免因为人的惰性而导致上下文过期。

3. 详细实操部署与配置指南

理论说完了，我们来看怎么把它用起来。整个部署过程的核心就是那个bootstrap.js脚本。它的作用是在你的项目里搭建起这套自动化工作流的脚手架。

3.1 环境准备与脚本初始化

首先，确保你的系统满足最基础的要求：

1. Node.js：脚本本身是用JavaScript写的，需要Node环境来运行。建议使用LTS版本。
2. Git：这是整个框架的根基，你的项目必须是一个Git仓库。
3. （可选）Claude Desktop：如果你计划通过MCP协议让Claude Desktop自动读取上下文，需要安装它。

部署步骤极其简单，这也是设计目标之一——快速启动，不干扰主开发流程：

1. 获取脚本：从项目仓库中复制bootstrap.js文件，直接放置到你目标项目的根目录下。记住，一定是与你.git文件夹同级的那个目录。

2. 执行初始化：打开终端，切换到项目根目录，执行初始化命令。

   node bootstrap.js init

   这个命令会做以下几件事：

   • 在项目根目录创建一个.mcp/文件夹，用于存放所有与上下文管理相关的配置和生成文件。
   • 在.mcp/下生成一个config.json，包含Repomix的配置（如包含/排除的文件模式）。
   • 在.git/hooks/目录下安装一个post-commit钩子脚本。这个钩子会在每次git commit成功执行后，自动运行Repomix，更新.mcp/context.xml快照文件。
   • 可能会创建一些示例规则文件，用于指导提交信息的规范化（以保持上下文变更的可读性）。

3. 高级初始化选项：

   • 为Claude Desktop配置MCP：如果你使用Claude Desktop，强烈推荐使用以下命令初始化，它会自动帮你配置MCP服务器设置。

     node bootstrap.js init --setup-mcp

     这个命令在完成基础初始化后，会引导你或在后台将本地的快照文件路径配置为Claude Desktop的一个MCP服务器源。这样，Claude Desktop启动后就能自动连接到这个上下文源。
   • 强制覆盖：如果你之前初始化过，或者项目里已有某些钩子，可以使用--force参数。脚本会先备份现有文件，然后进行覆盖。

     node bootstrap.js init --force

4. 验证与帮助：初始化完成后，可以运行检查命令确认一切就绪。

   node bootstrap.js check

   查看所有可用命令和选项：

   node bootstrap.js --help

3.2 关键目录结构与文件解析

初始化后，你的项目根目录会多出一个.mcp文件夹，它的结构大致如下：

你的项目/ ├── .git/ ├── .mcp/ │ ├── config.json # Repomix配置文件，定义如何生成快照 │ ├── context.xml # 由脚本自动生成的项目快照文件（核心） │ ├── rules/ # （可选）存放提交信息规范等规则文件 │ └── hooks/ # Git钩子脚本的副本，用于管理 ├── src/ # 你的项目源代码 ├── bootstrap.js # 你放置的引导脚本 └── ...其他项目文件

我们来重点看看两个核心文件：

.mcp/config.json(Repomix配置示例)

{ "output": ".mcp/context.xml", "format": "xml", "include": ["src/**/*", "*.md", "package.json", "README.md"], "exclude": ["node_modules", ".git", "dist", "build", "*.log", ".mcp/context.xml"], "maxFileSize": 10000, "compress": true }

• include/exclude: 这是控制快照内容的关键。你需要根据项目类型调整。例如，一个前端项目可能需要包含src/,public/, 主要的配置文件；而一个Python项目可能需要包含*.py,requirements.txt。务必排除掉构建产物、依赖库和日志文件，它们只会增加噪音。
• maxFileSize和compress: 对于大型文件（如压缩过的资源、数据集），可以设置大小限制或启用压缩，防止快照体积爆炸。

.mcp/context.xml(生成的快照片段)这是一个由Repomix自动生成的文件，内容结构清晰：

<repository> <path>/User/Projects/my-app</path> <summary>Generated by Repomix at 2023-10-27T10:00:00Z</summary> <tree> - src/ - components/ - Button.jsx [size: 1.2KB] - Header.jsx [size: 0.8KB] - utils/ - api.js [size: 2.1KB] - package.json [size: 0.5KB] - README.md [size: 1.0KB] </tree> <files> <file path="src/components/Button.jsx"> // 这里是Button.jsx文件的实际内容 import React from 'react'; export const Button = ({ children }) => { ... }; </file> <file path="README.md"> # My App This is a project for... </file> <!-- ... 其他文件内容 --> </files> </repository>

这个文件为AI工具提供了完整的项目骨架和血肉。<tree>部分给出了导航，<files>部分提供了具体内容。AI在分析问题时，可以快速定位到相关文件。

3.3 集成Serena以处理大型项目

对于小型或中型项目，Repomix快照可能已经足够。但当项目代码库达到数十万行时，即使压缩过的快照也可能超出AI模型的上下文窗口。这时就需要Serena出场了。

Serena的集成通常是可选的，并且需要额外的安装和配置步骤。大致流程如下：

1. 安装Serena：通常通过Docker或直接克隆其仓库来安装。
2. 配置为索引服务：告诉Serena你的代码库路径，让它建立语义索引。
3. 修改MCP配置：不再直接将context.xml作为MCP源，而是配置一个指向Serena服务器的MCP源。或者，可以配置一个“混合”模式：日常使用Repomix快照，当AI需要深度搜索特定代码时，通过另一个MCP工具调用Serena的搜索接口。

实操心得：在集成Serena时，最大的挑战是平衡索引的更新频率。实时索引每次提交会影响性能，定时索引又可能导致上下文滞后。我的经验是，对于活跃开发的主分支，可以配置在post-commit钩子中触发一个轻量级的索引增量更新。而对于深度分析任务，可以手动触发全量索引重建。这需要根据项目实际情况调整。

4. 日常开发工作流与实战技巧

框架搭建好后，你的日常开发流程会变得非常顺畅。下面是一个典型的使用场景：

4.1 一个完整的开发循环

假设你要为一个React组件添加一个新功能。

1. 开始工作：你打开终端，切换到项目目录。框架已经就绪。
2. 在Cursor中编码：你打开Cursor，开始修改src/components/Button.jsx。Cursor的AI助手基于最新的.mcp/context.xml快照理解整个项目，它知道这个Button组件的所有属性、在哪些地方被使用、以及项目的代码风格。它给出的补全和建议是精准的。
3. 提交代码：修改完成后，你运行git add和git commit。在git commit成功的瞬间，.git/hooks/post-commit钩子被触发。
4. 上下文自动更新：钩子脚本自动执行repomix命令，读取.mcp/config.json的配置，重新扫描项目，生成一个全新的、包含了刚才Button组件修改的context.xml文件。这个过程通常很快，几秒钟完成。
5. 切换到Claude Code进行代码审查：你不需要向Claude解释你改了哪里。直接打开Claude Code，由于MCP已配置，Claude Desktop在后台已经读取了更新后的context.xml。你可以直接提问：“我刚修改了Button组件以支持icon属性，请从代码风格和潜在边界条件（如icon为空时）的角度审查一下我的改动。” Claude基于完全相同的、最新的上下文给出审查意见。
6. 并行处理其他任务：与此同时，你的同事（或者你自己的另一个会话）可以在Cursor里基于同一个最新上下文，修改与Button交互的另一个组件，而不会产生冲突。

这个流程的核心是“提交即同步”。Git提交作为一个明确的、版本化的“里程碑”，触发了上下文的全局刷新，使得所有连接的AI工具瞬间对齐到同一个项目视图。

4.2 在不同IDE和工具间保持同步

这个框架是IDE无关的。虽然文档以Claude Code和Cursor为例，但其原理适用于任何能读取文件或通过MCP/API获取上下文的工具。

• VS Code + 扩展：你可以编写一个简单的VS Code扩展，定时读取.mcp/context.xml文件，或者监听文件变化，然后将内容提供给像CodeGPT、通义灵码这类插件的自定义上下文。
• JetBrains IDE：同样，可以通过开发一个插件或者利用IDE的“自定义文件监视”功能来实现。
• 命令行AI工具：对于llm、aichat这样的命令行工具，你可以在启动命令中直接指定-f .mcp/context.xml来载入上下文。

关键在于，无论前端是什么工具，它们都从同一个地方（.mcp/context.xml）饮水。这保证了信息源的一致性。

4.3 提交信息规范化的价值

框架的引导脚本可能会鼓励或强制你使用规范的提交信息。这看似是一个小细节，实则对维护高质量的上下文至关重要。

一份糟糕的提交信息如“fix bug”，对于未来的AI（或未来的你）理解这次变更的意图毫无帮助。而一份好的提交信息，例如 “feat(Button): add support foriconprop and improve accessibility labels”，其本身就成了上下文快照的一部分。当AI在分析context.xml时，结合代码diff和清晰的提交信息，它能更准确地理解项目的演进逻辑和设计决策。

你可以通过修改.mcp/rules/下的规则文件，来定义适合你团队的提交信息格式（如Conventional Commits），脚本的Git钩子可以集成commitlint这样的工具来强制执行。

5. 常见问题排查与效能优化

在实际使用中，你可能会遇到一些问题。以下是我在长期使用中总结的一些常见情况及解决方法。

5.1 问题排查速查表

5.2 性能与规模优化建议

当项目规模增长时，你需要优化以保持工作流的流畅。

1. 精细化配置config.json：这是最重要的优化点。不要一股脑包含所有文件。只包含AI真正需要理解的源代码、配置文件、文档。严格排除构建输出、依赖、日志、测试数据。对于大型的package-lock.json或yarn.lock，可以考虑只包含package.json。
2. 启用Repomix压缩：设置"compress": true，Repomix会尝试移除代码中的注释和空白字符，能有效减小文件体积。
3. 引入Serena进行动态检索：如前所述，对于巨型单体仓库，这是终极方案。将Serena作为按需查询的搜索引擎，而不是全量加载上下文。
4. 考虑分模块快照：对于微服务或Monorepo项目，可以为每个独立的子模块（子目录）分别运行一套框架，生成各自的.mcp/context.xml。这样，当你在某个子模块工作时，AI工具只加载相关模块的上下文，更加聚焦。
5. 定期清理与归档：context.xml文件会随着每次提交而覆写，一般无需手动清理。但要确保.mcp/目录被正确排除在版本控制之外（已在.gitignore中），避免将生成的快照文件提交到仓库。

5.3 框架的局限性认知

没有银弹，这个框架也有其适用边界：

• 对Git流程的依赖：它深度绑定Git。如果你的团队使用其他版本控制系统，或者开发习惯是不频繁提交，那么“提交即同步”的机制就会失效。你需要调整钩子触发时机，或者手动运行更新命令。
• 非代码资产的上下文：Repomix主要处理文本文件。对于UI设计稿（Figma链接）、产品需求文档（Notion页面）、数据库Schema图等非代码资产，目前的快照无法直接包含。一个变通方法是，将这些资源的链接或关键描述写入README.md或专门的CONTEXT.md文件，让它们被包含在快照中。
• “即时”同步的微小延迟：从提交完成到快照更新，有几秒到十几秒的延迟。在这极短的时间窗口内，如果两个工具同时被使用，可能会读到略微陈旧的上下文。对于绝大多数场景，这可以忽略不计。

我个人在实际使用中的体会是，这个框架最大的价值不在于某一次任务的效率提升，而在于它彻底消除了我在多个强大工具之间切换时的心智负担和协调成本。我不再需要扮演那个在AI工具之间传递信息的“信使”，也不再需要担心因为上下文不同步而导致的返工。它让AI工具真正成为了我统一开发环境下的和谐组成部分，而不是一个个信息孤岛。这感觉就像为你的开发团队引入了一位永远保持同步、永不遗忘的超级助理，而你所做的，只是遵循一个简单而有效的 Git 提交习惯而已。