使用说明

上下文结构

当前稳定版本： v1.0.7。参见更改日志.md 发布说明。

官方注册支持

Context Fabric已配置为正式包含在 模型上下文协议（MCP）注册表.

命名空间: io.github.VIKAS9793/context-fabric
元数据: server.json
分布：作为带有官方MCP注册表元数据的npm包发布。

AI编码代理的上下文同步层。确保项目连续性，消除代理内存漂移，并在任何编码会话中自动管理令牌预算。

Context Fabric是一个MCP服务器，它在每次git提交时自动捕获项目状态，检测存储的上下文何时偏离代码库现实，并向AI代理提供结构化的、令牌预算的简报，而不需要任何开发人员操作。

问题

使用AI编码代理的开发人员手动构建和维护文档系统、会话切换仪式和上下文工作流，以弥补本地项目连续性工具的缺失。这些解决方法共享一个属性：它们在提交后会过时，没有任何东西可以检测到它。

问题不在于AI会忘记。问题是 上下文漂移 --代码更改后，存储的上下文变得不正确，AI代理自信地处理不正确的上下文。

Context Fabric是从根本上解决这个问题的基础设施层。

CADRE——上下文感知漂移解析引擎

Context Fabric由以下驱动干部，五引擎内部架构。每个引擎都解决了在真实开发人员工作流程中观察到的特定、有记录的故障模式。

CADRE是什么。 CADRE是开发人员目前自行构建的每个手动上下文管理系统的自动替代品。它位于git事件流和AI代理之间，决定捕获什么上下文，何时漂移，哪些部分与活动查询相关，它们在令牌中的成本是多少，以及如何结构化和可靠地交付它们。

CADRE代表谁。 开发人员正在构建多会话人工智能辅助的软件项目，他们目前花时间在以下任何一项上：在提交后更新markdown文件、创建会话结束摘要、维护CLAUDE.md或AGENTS.md文件、为项目上下文构建RAG管道，或在每个任务之前手动决定加载哪些文档。

五个引擎

E1——观察者

安装git post提交挂钩 context-fabric init每次提交时自动触发。读取已提交的Git blob而不是可变工作树，计算SHA256指纹，提取导出的符号，计算令牌估计，并将所有内容追加到本地SQLite存储中。安装后，开发人员什么也不做。

替换：每次提交的降价工作流程、5步会话仪式和用于在会话前提取结构化项目知识的AI面试工作流程。

E2——锚

在每一个 cf_query 调用，将存储的SHA256哈希值与每个跟踪文件的当前状态进行比较。返回漂移报告，漂移分数为0-100，严重程度分类为：低（低于10%）、中（10-30%）、高（超过30%）。过期文件由路径和哈希增量标识。

替换：苏黎世联邦理工学院的研究（arXiv:2602.11988）表明，手动文档对齐审查和AGENTS.md中未被发现的过时性会降低AI编码性能。

E3——路由器

使用来自的查询文本对存储的组件索引运行SQLite FTS5 BM25 cf_query.返回按相关性排序的组件。路径匹配的权重是导出符号匹配的2倍，因为文件路径承载着关于代码库组织的结构意义。当查询产生零MATCH结果时，回退到近距排序。

替换：手动选择每个任务要包含哪些文档，以及当项目在多个文件中分解知识时出现的模块化上下文选择问题。

E4--调速器

使用相关性排序列表上的贪婪选择，将可配置的代币预算上限应用于E3排名的输出。默认值：模型上下文窗口的8%，剩下92%用于对话和代码。跳过过大的组件，因此剩余的预算仍可供以后排名的比赛使用。E1预先计算的令牌估计值意味着在预算选择时没有额外的文件读取。

替换：手动令牌管理，以及无限期保持会话活动的模式，以避免重启时上下文恢复的成本。

E5--织布机

根据E3和E4的输出编写一份结构化的降价简报。章节：项目状态、架构、架构决策、预算摘要。当E2严重性为MED或HIGH时，在所有其他内容之前都会添加漂移警告部分，因此AI在阅读之前会被告知上下文可靠性。

替换：从不更新的静态AGENTS.md简报，以及开发人员在每次会话开始时执行的手动简报准备。

数据流

git commit
    |
    v
E1 WATCHER --- SHA256 fingerprint --- SQLite upsert --- FTS5 index update
                                                              |
                                                      cf_query("...")
                                                              |
                                                              v
                                        E2 ANCHOR --- drift check --- DriftReport
                                                              |
                                                              v
                                        E3 ROUTER --- FTS5 BM25 --- ranked component list
                                                              |
                                                              v
                                        E4 GOVERNOR --- greedy selection --- budget-capped set
                                                              |
                                                              v
                                        E5 WEAVER --- briefing composition --- MCP response

快速开始

npx context-fabric init

初始化SQLite存储区，安装git post commit钩子，在下运行稳定的本地运行时 .context-fabric/runtime，并运行初始捕获。将MCP服务器连接到您的工具，从下一次提交开始，上下文传递就处于活动状态。

安装和设置

初始化您的项目: 导航到任何git托管存储库并运行：
```
npx context-fabric init
```

配置您的AI环境（光标/VS代码/Windsurf）: 将以下内容添加到MCP配置文件中。

Windows用户（至关重要）:

{
  "mcpServers": {
    "context-fabric": {
      "command": "cmd",
      "args": ["/c", "npx", "context-fabric"]
    }
  }
}

Mac/Linux用户:

{
  "mcpServers": {
    "context-fabric": {
      "command": "npx",
      "args": ["-y", "context-fabric"]
    }
  }
}

健康与维修

在验证本地安装或从损坏的挂钩/运行时状态恢复时使用健康命令。

npx context-fabric doctor
npx context-fabric doctor --repair

doctor 报告架构版本、搜索索引版本、数据库完整性、降级模式、挂起和失败的捕获，以及钩子运行时就绪情况。 doctor --repair 刷新本地运行时包，重新安装稳定的钩子包装器，验证 .gitignore，并在数据库正常时重建搜索索引。

故障排除

`spawn npx ENOENT` 错误

这通常意味着 npx 不在IDE的系统继承路径中。

修复：使用绝对路径 node 和那个 context-fabric 二元的。
使用 where node （Windows）或 which node （Mac/Linux）查找您的路径。

NVM/FNM用户示例：

"command": "/Users/name/.nvm/versions/node/v22.14.0/bin/node",
"args": ["/Users/name/.nvm/versions/node/v22.14.0/bin/context-fabric"]

WSL用户

如果你在Windows上运行VS Code，但你的代码在WSL中，你必须跑 init 在WSL终端内部，使用WSL绝对路径到配置中的节点。

项目路径空间

在Windows上，项目路径中的空格（例如。， C:\My Projects\app)可以打破 npx 产卵。如果服务器发生故障，请考虑将项目移动到没有空格的路径。

反馈与报告

如果有东西坏了，请跑：

npx context-fabric doctor

npx context-fabric diag 仍然可用作兼容性别名。

常见问题

Context Fabric是否将我的代码发送到服务器？ 不可以。它仅是本地的，不会发出用于捕获、检索或漂移分析的出站网络调用。

它是否索引未提交的更改？ 否。捕获的状态基于已提交的Git对象。漂移检查会检测到未提交的更改，但在您提交并捕获它们之前，它们不会被索引为新的事实来源。

这是替代品吗 AGENTS.md, CLAUDE.md，还是人类医生？ 它减少了对手动会话切换文档的需求，但它不能替代产品规格、入职指南或面向利益相关者的文档。

它在本地写入哪些文件？ 它写在下面 .context-fabric/ 用于数据库和运行时捆绑包，并安装 .git/hooks/post-commit 以保持自动捕获。

我什么时候不应该使用它？ 如果您需要云同步、跨仓库搜索、实现主体的完整语义索引或MCP工具的项目文件突变，请不要使用Context Fabric。

如何恢复损坏的安装？ 跑 npx context-fabric doctor 第一。如果钩子运行时或本地状态需要修复，请运行 npx context-fabric doctor --repair.

完整常见问题解答： docs/FAQ.md

MCP工具

工具	引擎	目的
`cf_capture`	E1	在git提交之外手动捕获上下文
`cf_drift`	E2	独立漂移检查--返回严重性和过时文件计数
`cf_query`	E2+E3+E4+E5	当前任务的完整背景简报
`cf_health`	本地运行状况	报告数据库、捕获、挂钩和搜索索引运行状况
`cf_log_decision`	存储	跨会话坚持架构决策

技术栈

层	包	版本
MCP协议	`@modelcontextprotocol/sdk`	`1.29.0`
存储和搜索	`better-sqlite3` +FTS5	`12.8.0`
架构验证	`zod`	`^4.3.6`
语言	TypeScript	`5.5+`
运行时	Node.js	`>=22.0.0 <25.0.0`
传输	stdio（第1阶段）	MCP SDK内置

安全

访问类型	范围
文件系统读取	仅限项目根目录--路径遍历被拒绝
文件系统写入	`.context-fabric/cf.db`, `.context-fabric/runtime/**`, `.context-fabric/bin/post-commit`，以及 `.git/hooks/post-commit`
网络	无--零出站连接，无遥测
项目文件写入	无--没有工具调用写入项目文件

看安全.md 用于漏洞披露过程。

需求

Node.js >=22.0.0 和 <25.0.0
git仓库
任何与MCP兼容的AI编码工具

贡献

阅读贡献.md 在打开pull请求之前。

项目文档

👥 项目团队

萨卡斯人 --产品负责人/HITL/代理协调人
反重力 --AI代理/代码架构师

🔬 研究与数据免责声明

该项目是正在进行的人工智能原生开发工作流程和上下文感知漂移解决方案研究的一部分。

公共数据：公开会话期间生成的片段、日志或指标可用于研究和验证目的。
隐私：没有个人数据或专有代码库逻辑存储在本地之外 .context-fabric 除非明确共享。

许可证

麻省理工学院——见许可证.

建造于萨卡斯人.

使用说明

上下文结构

官方注册支持

问题

CADRE——上下文感知漂移解析引擎

五个引擎

数据流

快速开始

安装和设置

健康与维修

故障排除

spawn npx ENOENT 错误

WSL用户

项目路径空间

反馈与报告

常见问题

MCP工具

技术栈

安全

需求

贡献

项目文档

👥 项目团队

🔬 研究与数据免责声明

许可证

相关 MCP

Figma MCP服务器

代码分析服务器

AI开发框架

Token节约MCP服务

内存银行管理协议

文档搜索服务

`spawn npx ENOENT` 错误