cap-shield

CAP-Shield MCP 服务

为 AI Agent 选择和压缩上下文——召回率经过测量，而非声称。

单个文件。无依赖。无需 SDK。

为什么

更多上下文会让 Agent 表现更差。ETH Zurich 发现，与完全不给 Agent 提供仓库上下文相比，上下文文件会降低任务成功率，同时使推理成本增加 20 % 以上。生产环境中约三分之二的 Agent 故障源于上下文问题，而非模型能力不足。

所以，问题不在于删掉多少内容，而在于保留下来的内容是否足够——这里会在一个我们没有挑选的基准上进行测量：LongMemEval-S，共 500 个问题。Recall@10 为 97.1 %，词法基线为 51.9 %（测量日期：2026-09-28——数据会随检索情况更新；请获取 .well-known/cap-shield.json 查看当前数据，而不是相信此文件中的数据）。

Recall@10 是严格指标：只有找到所有黄金会话时，问题才算答对。只找到一半答案，意味着 Agent 会在依据不完整的情况下自信作答。

八个工具中有两个无需账号。 先测量，再决定。

安装

curl -O https://cap-shield-robin.fly.dev/cap_mcp.py

{
  "mcpServers": {
    "cap-shield": {
      "command": "python",
      "args": ["/absolute/path/to/cap_mcp.py"]
    }
  }
}

Python 3.9+。除此之外无需其他内容。

可选的 SKILL.md 会告诉 Agent 何时使用这些工具——以及何时不该使用。

从 Claude（Claude.ai、Claude Desktop 或 Cowork）使用——无需下载

也可以直接通过 HTTP 访问此服务，因此托管的 Claude 客户端无需在本地安装任何内容即可连接。

在 Claude 中：Settings → Connectors → Add custom connector，并输入服务 URL：

https://cap-shield-robin.fly.dev/mcp

在 Authentication 下，选择 No sign-in——此服务使用 API 密钥进行身份验证，而非 OAuth（尚未构建 OAuth 支持；请参阅下方的“状态”）。Claude 会警告你，任何人都可以在无需登录的情况下使用该连接器——这条警告属实，也正因如此，下面的两个免费工具完全无需密钥，其余工具则需要。

measure_traffic 和 list_packages 可立即使用，无需请求头，也无需账号——无需进行其他配置。

若要使用账号工具（remember、assemble_context、pack_batch、unpack_batch、issue_pass）：请先获取密钥（使用 get_account，或访问控制台 https://cap-shield-console.lovable.app），然后在同一连接器对话框的 Request headers 下添加：

请求头	值
Authorization	Bearer YOUR_KEY_HERE

必须加上 Bearer 前缀——不带前缀的纯密钥会被拒绝，并返回 NYCKEL_KRAVS。这是标准的 bearer-token 请求头，因此，任何允许为远程服务添加自定义请求头的 MCP 客户端，都应该可以使用相同的两个字段，而不只是 Claude——只是目前实际测试过的客户端只有 Claude。

工具

measure_traffic · 无需账号

测量你自己的 Agent 流量中有多少可以节省。无需账号或密钥——请先使用此工具。它会返回传输过程中的字节节省量；如果提供了查询，还会返回通过选择性上下文检索节省的令牌数。不会存储任何内容：文本会在内存中压缩后丢弃。每个 IP 每小时最多调用 20 次。

list_packages · 无需账号

列出可用的字典及其实测压缩率，包括表现不佳的字典。每个条目都会说明它是适用于单条消息，还是只能批量使用，以及有多少条消息经处理后变得更大。无需密钥。

remember · 需要密钥

存储记忆条目，供之后检索。需要密钥。此工具不会调用任何语言模型——它会将文本存储在按租户隔离的存档中。使用 assemble_context 获取相关条目。

assemble_context · 需要密钥

在令牌预算内，检索能够回答问题的记忆条目。需要密钥。将返回的“context”发送给语言模型，而不是发送完整历史记录。此工具本身不会调用模型——它只负责选择要发送的内容。预算是上限，而非目标：相关性不足时就会停止选择，实际用量通常远低于上限。响应会说明哪些条目被省略，以及省略原因。

pack_batch · 需要密钥

将多条消息打包成一个压缩数据包，而不是逐条打包。需要密钥。适用于大量小型／中型消息（每条消息的标头开销只需支付一次，且 zstd 会在它们之间共享上下文）——对于单条消息则没有优势。返回 packet_b64（将其交给 unpack_batch 即可取回消息），以及与逐条单独打包相比测得的字节节省量。安全提示：只批量处理已处于同一信任边界（同一租户／Agent）的消息——不要将受攻击者影响的内容与机密混在一起。批量消息会共享一个压缩上下文，这可能导致它们之间泄露基于大小的信息（类似 CRIME／BREACH 的侧信道）。此端点目前没有填充缓解措施，因此隔离信任边界是唯一的保护手段——不要依赖填充。

unpack_batch · 需要密钥

将由 pack_batch（或 /api/v1/pack-batch 端点）生成的批量数据包解包，还原为完全相同的原始消息列表，并保持顺序。需要密钥。不能用于由单消息打包端点生成的数据包——那是另一种格式，此端点会拒绝处理。

get_account

获取账户和 API 密钥。需要电子邮件地址。密钥仅返回一次，之后无法再次查看——请立即保存。Beta 配额有意设置得较低；它们是硬性限制，不会产生超额用量费用。

issue_pass · 需要密钥

Agent 身份／Agent 护照。 签发一份有效期较短（15 分钟）的签名凭证（JWT），说明调用者代表谁行事。需要密钥。任何人都可以通过 /.well-known/jwks.json 独立验证该凭证，无需再次调用 CAP-Shield。'acts_for' 和 'scope' 不会根据实际情况进行验证：该通行凭证仅证明密钥持有者在此时作出了此声明，且该声明已记录在审计链中。这是身份和所声明的授权，不是支付或访问控制机制。

以上说明直接复制自服务器。如果它们与 tools/list 返回的内容 不一致，以服务器为准，本文件已过时。

可选：针对最难问题升级到 LLM

上文的检索和压缩过程从不调用模型。assemble_context 还会针对某一类特定问题返回 escalate_recommended: true——多步计数（“我提到 X 多少次？”）、 对散布在多条记忆中的金额求和，以及重建多个事件的时间顺序——这类问题的答案并不 包含在任何单条记录中，必须经过整理才能得出。普通检索 大多数时候都能正确回答；此标记适用于其余情况。

如何处理此标记由你决定。CAP-Shield 绝不会消耗 你的令牌，也不会看到你的模型密钥。

cap_escalate_helper.py 是这一步额外处理的参考实现：将它集成到你自己的 工作流中，并仅针对 CAP-Shield 标记的问题，使用你自己的 ANTHROPIC_API_KEY 或 OPENAI_API_KEY 调用它。

pip install anthropic   # or: pip install openai
export ANTHROPIC_API_KEY=...

from cap_escalate_helper import eskalera_om_behovs

cap_svar = assemble_context(...)   # whatever CAP-Shield returned you
svar = eskalera_om_behovs(cap_svar, fraga="How many times did I mention X?",
                           modell="claude")   # or modell="gpt-5-mini"
print(svar["svar"])

如果 escalate_recommended 为 false，则不会向任何模型发送内容——该 函数会立即返回，因此可以安全地对每个响应无条件调用；只有在 CAP-Shield 确实 要求升级时，它才会消耗一次 API 调用。

运行 python cap_escalate_helper.py --demo 可准确查看将要发送的内容， 无需密钥。

一个更有针对性的入口 eskalera_om_behovs_v5 会要求模型 仅提取原始信息（金额、日期、事件名称），并由普通 Python 完成计数、求和或排序——从而消除模型以自由文本作答时可能出现的 一整类算术／排序错误。这是我们在该功能的基准验证中使用的版本。

要在你自己的运行中复现我们公布的数值，必须使用此文件的 当前版本——其背后的提示词和匹配逻辑仍在积极调整，较旧的本地副本可能会导致得分 出现显著差异。

数字的含义

压缩节省的是传输字节数。选择节省的是上下文中的 token 数。这是两种不同的机制——把它们相加得到的数字毫无意义。

压缩后的数据包会在模型看到之前解压，因此这不会降低推理成本。声称事实并非如此，是对这个项目最容易犯的错误。

所有数据均实时发布，包括尚未测量的内容，以及表现不佳的程序包：

https://cap-shield-robin.fly.dev/.well-known/cap-shield.json

请获取该数据，而不是相信本文档。本文档会过时；该数据不会。

不使用 MCP 进行测量

pip install cap-shield

from cap_shield import measure, print_measurement
print_measurement(measure(texts=[...], query="..."))

无需账户，也不会存储任何内容。响应会包含压缩效果不佳的比例——有多少条消息变得更大。

批处理的安全条件

批处理会压缩同一上下文中的多条消息，因此会产生类似 CRIME/BREACH 的侧信道：如果有人能将选定文本放入与秘密相同的批次，并观察批次大小，就能从中获知一些秘密信息。

只对处于同一信任边界内的消息进行批处理。可选填充可消除此信息泄露，每条消息的代价不到两个字节，且默认关闭——我们会明确说明这一点，而不是让你自行假设。

单独打包完全没有这个问题。

可移植性

字典版本永远不会被删除，而且这项保证不依赖我们是否仍在运营：归档导出包含字典二进制文件，独立解包器无需网关、网络或系统的其他部分即可运行。

https://cap-shield-robin.fly.dev/cap_unpack.py

此工具无需令牌即可获取，因为最需要它的人，正是已经无法访问账户的人。

状态

Beta。服务端版本 0.5.0。

文档：https://cap-shield-robin.fly.dev/docs/quickstart 控制台：https://cap-shield-console.lovable.app

许可证

MIT——请参阅 LICENSE。