代码库上下文
在AI代理开始搜索之前，绘制团队的惯例图。
](https://www.npmjs.com/package/codebase-context)  ](https://github.com/PatrickSys/codebase-context/blob/master/package.json)
你厌倦了人工智能代理编写“正常工作”的代码，但仍然怀念你的团队实际构建东西的方式。他们搜索范围太广，选择了通用的例子，并在理解回购的形状之前花费代币进行探索。
codebase-context 改变了第一步。从一个有界的约定图开始，该图显示了架构、主要模式和最强的局部示例。然后搜索所需的确切文件、符号或工作流。
以下是代码库上下文的作用：
从有界约定图开始 -第一个调用显示架构层、活动模式、黄金文件和下一个调用，而不会将供应商存储库、夹具、生成的输出或过大的入口点列表转储到默认曲面中。
找到正确的本地示例 -搜索不仅仅返回代码。每个结果都会返回模式信号、文件关系和质量指标，因此代理可以从地图移动到最相关的本地示例，而不是在原始点击中徘徊。
知道当前的情况 -约定可以从您的代码和git历史记录中检测到，而不仅仅是从您编写的规则中检测到。该地图将共同点与上升或下降点区分开来，并指向最能代表当前方向的文件。
在需要时添加支持信号 -团队记忆和编辑准备检查仍然可用，但由于地图和搜索后的支持上下文已经缩小了工作范围。
地图第一，搜索第二，本地第一。默认情况下，你的代码永远不会离开你的机器。
请参阅 当前发现基准 对于登记的发现，只有证据。大门依旧 pending_evidence，以及 claimAllowed 残余 false.
它看起来像什么
真实CLI输出 angular-spotify，用于发布屏幕截图的仓库。
导联信号：图案漂移和金色锉刀
这是大多数工具都忽略的部分：团队现在在做什么，它正在远离什么，以及哪些文件是最值得效仿的例子。
编辑前：飞行前和影响
当代理以编辑意图进行搜索时，它会得到一张紧凑的决策卡：信心、是否可以安全地继续、应用哪些模式、最佳示例以及哪些文件可能会受到影响。
更多CLI示例请参见 docs/cli.md.完整演练： .
快速开始
claude mcp add codebase-context -- npx -y codebase-context服务器以两种模式运行。除非您需要同时连接多个客户端，否则请使用stdio：
| 模式 | 运行方式 | 何时使用 |
|---|---|---|
| 标准 （默认） | 客户端生成的进程 | 一个AI客户端与一个或多个存储库对话 |
| 超文本传输协议 | 长期使用的服务器位于 http://127.0.0.1:3100/mcp | 多个客户端共享一台服务器 |
客户支持概览：
| 客户端 | stdio | HTTP |
|---|---|---|
| 克劳德代码 | 是 | 否（仅限stdio） |
| 克劳德桌面 | 是 | 否 |
| 光标 | 是 | 是-- .cursor/mcp.json 随着 type: "http" |
| 风帆 | 是 | 还没有 |
| Codex | 是 | 是-- --mcp-config 旗帜 |
| VS代码（副本） | 是 | 否 |
| OpenCode | 是 | 尚未记录 |
复制可粘贴模板： templates/mcp/stdio/.mcp.json 和 templates/mcp/http/.mcp.json.
完整的每客户端设置、HTTP服务器说明和本地构建测试： docs/client-setup.md.
首先使用
在探索或编辑之前，获取代码库的约定图：
# See your codebase conventions — architecture layers, patterns, golden files
npx -y codebase-context map
# Then search for what you need
npx -y codebase-context search --query "auth middleware"您的AI代理通过以下方式使用相同的地图 codebase://context MCP资源首次调用。
常见的第一命令
在编辑repo之前，有三个命令可以理解它：
# What are the main conventions and best examples?
npx -y codebase-context map
# Then search for the local example you need
npx -y codebase-context search --query "auth middleware"
# What patterns is the team actually using right now?
npx -y codebase-context patterns这也是你的AI代理通过MCP工具自动消耗的东西；CLI是同一地图加搜索流的人类可读版本。
它的作用
搜索工具(search_codebase)
一次通话返回排名结果 file, summary, score，紧凑型(componentType:layer)、模式趋势信号、关系提示、相关团队记忆、搜索质量评估和飞行前决策卡 intent="edit"。决策卡显示 ready （布尔值）， nextAction 当未准备好时， patterns （做/避免）， bestExample，影响范围("3/5 callers in results")，以及 whatWouldHelp.
默认输出是精简的——如果代理需要代码，它会调用 read_file.添加 includeSnippets: true 用于具有作用域标头的内联代码（例如。 // AuthService.getToken()).
看 docs/capabilities.md 以获取完整的字段参考。
模式和惯例(get_team_patterns)
通过分析代码库来检测您的团队实际做了什么：DI、状态管理、测试和库模式的采用百分比；趋势方向（上升/稳定/下降）从git recent；按现代图案密度排列的金色档案；当两种方法都超过20%时，就会发生冲突。
团队记忆(remember + get_memory)
记录一次决定。从那时起，它会自动出现在搜索结果和飞行前卡片中(refactor:, migrate:, fix:, revert:)在索引过程中，将过去90天的数据自动提取到内存中，无需设置。
存储器类型： convention, decision, gotcha, failure信心衰减：惯例永不衰减，决策半衰期180天，陷阱/失败90天。陈旧的记忆会被标记，而不是盲目信任。
工具
| 工具 | 它做什么 |
|---|---|
search_codebase | 混合搜索+决策卡 intent="edit" |
get_team_patterns | 模式频率、金色文件、冲突检测 |
get_symbol_references | 对符号的具体引用（计数+代码段） |
remember | 记录惯例、决定、陷阱或失败 |
get_memory | 使用信心衰减评分查询团队记忆 |
get_codebase_metadata | 项目结构、框架、依赖关系 |
get_style_guide | 当前项目的样式指南规则 |
detect_circular_dependencies | 文件之间的导入周期 |
refresh_index | 完全或增量重新索引+git内存提取 |
get_indexing_status | 当前指数的进展和统计数据 |
多项目
一台服务器，多个仓库。三种情况：
| 案例 | 发生了什么 |
|---|---|
| 一个项目 | 路由是自动的 |
| 多个项目，活动项目已设置 | 路由到活动项目 |
| 多个项目，不明确 | 返回 selection_required --重试 project |
project 接受项目根路径、文件路径， file:// URI或相对子项目路径（例如。 apps/dashboard).
{
"name": "search_codebase",
"arguments": {
"query": "auth interceptor",
"project": "apps/dashboard"
}
}如果你得到 selection_required，请使用以下路径之一重试 availableProjects.完整的路由细节和响应形状 docs/capabilities.md.
语言支持
通过Tree sitter进行完整符号提取的10种语言：TypeScript、JavaScript、Python、Java、Kotlin、C、C++、C#、Go、Rust。30多种语言，涵盖索引和检索，包括PHP、Ruby、Swift、Scala、Shell和配置格式。Angular、React和Next.js都有专用的分析器；当语法可用时，其他所有内容都使用具有AST对齐组块的Generic分析器。
配置
| 变量 | 默认值 | 描述 |
|---|---|---|
EMBEDDING_PROVIDER | transformers | openai （快速、云）或 transformers （本地、私人） |
OPENAI_API_KEY | -- | 仅在使用时需要 openai 提供者 |
CODEBASE_ROOT | -- | CLI和单项目MCP客户端的Bootstrap根目录 |
CODEBASE_CONTEXT_DEBUG | -- | 设置为 1 用于详细日志记录 |
EMBEDDING_MODEL | Xenova/bge-small-en-v1.5 | 本地嵌入模型覆盖 |
CODEBASE_CONTEXT_HTTP | -- | 设置为 1 以HTTP模式启动（与 --http 旗帜） |
CODEBASE_CONTEXT_PORT | 3100 | HTTP服务器端口覆盖（与 --port；在stdio模式下忽略） |
CODEBASE_CONTEXT_CONFIG_PATH | ~/.codebase-context/config.json | 覆盖服务器配置文件路径 |
演出
- 首次索引：对于~30k个文件，需要2-5分钟（嵌入计算）。
- 后续查询：距离缓存毫秒。
- 增量更新:
refresh_index随着incrementalOnly: true进程仅更改文件（SHA-256清单差异）。
文件结构
.codebase-context/
memory.json # Team knowledge (should be persisted in git)
index-meta.json # Index metadata and version (generated)
intelligence.json # Pattern analysis (generated)
relationships.json # File/symbol relationships (generated)
index.json # Keyword index (generated)
index/ # Vector database (generated)推荐 .gitignore:
# Codebase Context - ignore generated files, keep memory
.codebase-context/*
!.codebase-context/memory.json在CLAUDE.md/AGENTS.md中添加什么
将此粘贴到 .cursorrules, CLAUDE.md, AGENTS.md，或者在您的AI读取项目说明的任何地方：
## Codebase Context (MCP)
**Start of every task:** Call `get_memory` to load team conventions before writing any code.
**Before editing existing code:** Call `search_codebase` with `intent: "edit"`. If the preflight card says `ready: false`, read the listed files before touching anything.
**Before writing new code:** Call `get_team_patterns` to check how the team handles DI, state, testing, and library wrappers — don't introduce a new pattern if one already exists.
**When asked to "remember" or "record" something:** Call `remember` immediately, before doing anything else.
**When adding imports that cross module boundaries:** Call `detect_circular_dependencies` with the relevant scope after adding the import.这些行为每天都会产生最大的影响。复制、修剪不适用于堆栈的内容，并添加一次。
链接
- 基准 --当前发现套件结果和门真相
- 演示 --真实CLI演练
- 客户端设置 --按客户端配置、HTTP设置、本地构建测试
- 能力参考 -工具API、检索管道、决策卡模式
- CLI库 --格式化命令输出示例
- 动机 --研究与设计原理
- 贡献 --开发设置和评估工具
- 更新日志
许可证
弹性-2.0