contextweaver

contextweaver

捕获 Agent 的有效能力范围，将其提交到版本库，并在部署前查看语义上有意义的变化。

ContextWeaver 目前正在测试一个有意聚焦的产品假设： 能力快照 + 语义漂移。

给定一份 OpenAPI 文档、一条捕获的 MCP tools/list 响应，或一个原生 ContextWeaver 目录，D1 实验会生成确定性的规范化快照，供你检查、验证，并与 之后的候选版本进行比较。它不需要模型账户、网关、工具执行器或 Weaver Stack。

状态： alpha，且具体来说是一次产品实验。实现可用且已通过测试；用户价值假设尚未得到验证。项目正在积极衡量独立用户在真实项目中试用后是否会继续使用此工作流。

尝试能力漂移实验

克隆代码库并安装该检出版本，确保受维护的示例样例与正在评估的代码保持一致：

以下命令使用 python3，与代码库文档中记录的默认值一致（docs/agent-context/workflows.md）。在通过启动器提供 Python 的 Windows 安装环境中，请将 python3 替换为 py -3；如果你的环境已通过 python 提供目标解释器，请始终使用该命令。

git clone --depth 1 https://github.com/dgenio/contextweaver.git
cd contextweaver
python3 -m pip install .

运行受维护的 OpenAPI 示例：

python3 -m contextweaver.d1 snapshot examples/d1/openapi_before.json --source-type openapi --output ./cw-before.json
python3 -m contextweaver.d1 snapshot examples/d1/openapi_after.json --source-type openapi --output ./cw-after.json
python3 -m contextweaver.d1 inspect ./cw-after.json
python3 -m contextweaver.d1 verify ./cw-after.json
python3 -m contextweaver.d1 diff ./cw-before.json ./cw-after.json

候选样例有意进行以下改动：

• 将 customer_id 设为现有 listInvoices 能力的必填项；
• 修改其描述；
• 新增 getInvoice 能力。

差异会将能力的新增/移除与现有逻辑能力的变化区分开来，并报告发生变化的结构化路径。契约变更与仅文档变更也会分别列出。涉及 required、type 或 enum 等字段的变更会被标记为可能造成破坏性影响，以供审核。

该标记有意采取保守策略：ContextWeaver 并未声称自己是完整的 JSON-Schema 兼容性检查器。

完整操作指南：能力漂移实验。

在你自己的源上使用

OpenAPI

python3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities.json
python3 -m contextweaver.d1 verify ./capabilities.json

API 变更后：

python3 -m contextweaver.d1 snapshot ./openapi.yaml --source-type openapi --output ./capabilities-candidate.json
python3 -m contextweaver.d1 diff ./capabilities.json ./capabilities-candidate.json

捕获的 MCP 工具

如果你已将 MCP tools/list 响应保存为 JSON：

python3 -m contextweaver.d1 snapshot ./tools-list.json \
  --source-type mcp \
  --output ./capabilities.json

对于 MCP，D1 会按上游逻辑名称比较工具，因此输入架构的编辑会显示为同一能力的变更，而不是难以解释的移除/新增组合。历史上对架构敏感的路由 ID 会单独保留为 normalized_id，供检查使用。

捕获正在运行的 MCP 服务是单独的操作。snapshot、inspect、diff 和 verify 不会执行发现的能力。

原生 ContextWeaver 目录

python3 -m contextweaver.d1 snapshot ./catalog.json \
  --source-type native \
  --output ./capabilities.json

verify 的含义

verify 会检查 D1 快照契约：结构、确定性排序、逻辑 ID 唯一性，以及规范能力摘要。

它不是：

• 部署审批；
• 安全认证；
• 身份验证或授权；
• 对工具实现正确性的保证；
• 路由质量评估；
• 生产环境运行时证明。

何时不该使用 ContextWeaver D1

否定的结论对本项目来说也是有用的证据。不要仅仅因为能力快照听起来很整洁，就添加 ContextWeaver。

以下情况应选择更简单的方案：

• 普通的 Git diff、配置审查和测试已经能让你清楚地了解能力变更；
• 你的工具/API 范围很小，而且很少变动；
• 你要解决的唯一问题是提供方原生工具搜索；
• 你需要 Agent 循环、工具执行器、IAM 层或生产级编排器；
• 维护另一个需要提交的制品，成本高于它能解决的审查/调试问题。

如果你试用了 D1，最后认为 Git/测试的成本更低，这是有效的产品结论——请告诉我们。

正在测试什么

当前的存续实验提出了一个比代码能否运行更严格的问题：

能力快照和语义偏移报告，能否充分改善真实的审查/人工/风险流程，让独立用户愿意继续使用它们？

项目区分：

qualified exposure
  -> understood the problem
  -> chose to evaluate
  -> attempted setup
  -> reached first useful output
  -> used on a real project
  -> retained independently / removed

Stars、fork、下载量、成功的演示和维护者创建的集成都不视为持续采用。

主导产品决策的跟踪事项是 #758，分发质量门槛是 #855。 无人协助的首次成功和留存由 #658 跟踪，真实采用由 #551 跟踪。

路由、上下文编译和 MCP 网关呢？

ContextWeaver 已包含大量历史运行时功能。这些代码仍然存在，目前已发布的行为也应如实呈现并确保安全，但已有实现并不能证明项目应该继续扩展这些功能。

两个更广泛的假设明确以证据为先：

• **D2 — 有界/感知阶段的上下文编译：**有条件推进。必须证明它相较于当前的提供方/运行时原生机制具有实质价值。
• **D3 — 自定义确定性工具选择：**证伪方向。必须在目标用户真正关心的方面，胜过现代提供方原生工具搜索/延迟加载，或简单的检索基线。

在 D1 实验期间，除非存在具体的外部阻碍或获批的证伪实验，否则项目不会扩展路由能力、运行时捆绑机制、记忆/会话界面、框架覆盖范围、网关范围、向量存储或模型辅助增强。

如果你正在维护使用这些历史界面的现有集成，相关文档仍然可用：

• 哪种历史模式适合？
• 上下文防火墙
• MCP 上下文网关架构
• MCP 网关安全模型
• 比较/替代方案
• 生态系统地图

证据与声明

D1 实现支持范围明确的工程声明，例如在文档所述的源/适配器契约下确定性地构建快照，以及输出结构化语义差异。它尚不能支持更强的声明，即用户需要或会持续使用该产品。

历史上的令牌削减宣传语不会用于推销 D1。针对这些旧基准声明的当前证据完整性工作记录在 #841 中。

请参阅 声明与证据 了解声明登记表，并参阅 能力漂移实验 了解 D1 的确切契约和限制。

Python API 稳定性

D1 有意通过以下方式公开：

python3 -m contextweaver.d1 ...

而不是立即将其提升为历史顶层 CLI 的一部分或新增大型公开 Python API。这是有意为之。该实验应先凭借真实的持续使用证明自身价值，再让项目承担新的兼容性义务。

Weaver Stack 的一部分——可选

ContextWeaver 可以独立使用。它不硬性依赖同系列的 Weaver 项目。

更广泛的 Weaver Stack 包含用于规划、执行边界、护栏、经验和评估的相邻实验/组件。评估 D1 不需要这个生态系统；如果 ContextWeaver 的某项功能无法独立证明其价值，Stack 的一致性也不是保留它的理由。

只有在你确实需要这些相邻职责时，才参阅 生态系统地图。

安装与兼容性

pip install contextweaver

仓库 CI 矩阵覆盖 Python 3.10–3.14。

当前软件包版本：0.18.2

项目	发行版本
ContextWeaver（本仓库，v0.18.2）	当前软件包发行版本

该仓库尚未达到 1.0 版本。请优先使用最新的受支持补丁版本以获得错误修复和安全修复；依赖历史运行时 API 前，请先查看变更日志。

当前路线图

路线图有意按产品决策顺序排列，而非功能队列。

里程碑	状态	含义
v0.18.1 — D1 存续实验基线	✅ 已完成	离线快照/检查/差异/验证功能已具备；用户价值仍未经验证。
v0.18.2	✅ 当前（v0.18.2）	D1 存续实验和发行路径恢复
D1 分发关卡	🔬 先看证据	让入口易于理解，招募合格评估者，并衡量首次成功和留存情况。
D1 决策	⏸ 下一项决策	根据有效分发后的持续价值，决定继续、进一步精简或终止。
D2 / D3	🧪 有条件	仅当 D1 证据或独立发现的问题足以证明有必要时，才开展范围有限的证伪实验。

CI 通过本身不会推动路线图前进。

贡献

在存续实验期间，最有价值的贡献应范围明确并与证据相关：

• 真实的 D1 评估者阻碍；
• 当前容易造成误导或被悄然丢失的语义差异案例；
• 确定性规范化的正确性；
• 对软件包仍在发布的行为进行安全/发行维护；
• 表明更简单的替代方案更胜一筹的反面证据。

请勿仅为追求完整性而添加框架适配器、路由策略、存储后端、运行时阶段或生态系统集成。

请参阅 CONTRIBUTING.md 和 AGENTS.md，了解仓库工程规范。

安全

请参阅 SECURITY.md，了解受支持版本和漏洞报告指南。请勿在公开的采用/评估报告中包含凭据、客户数据、专有架构或私有提示词。

Documentation

• Documentation site
• Capability drift experiment
• Claims & evidence
• Daily Driver guide — historical/runtime users
• Cookbook — broader shipped surfaces
• FAQ
• Changelog

License

Apache-2.0. See LICENSE.