furl-ctx

<div align="center"><pre> ███████╗ ██╗ ██╗ ██████╗ ██╗ ██╔════╝ ██║ ██║ ██╔══██╗ ██║ █████╗ ██║ ██║ ██████╔╝ ██║ ██╔══╝ ██║ ██║ ██╔══██╗ ██║ ██║ ╚██████╔╝ ██║ ██║ ███████╗ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚══════╝ 人工智能代理的上下文压缩层 <img src="typing.svg" width="42" /> </pre></div> <p align="center"><strong>通常在高熵内容的真实数据上节省0–54%的tokens · 在重复日志/固定装置上最高可达95% · Claude Code插件 + MCP服务器 · 优先本地 · 可逆</strong></p> <p align="center"> <a href="https://github.com/omar-y-abdi/furl-ctx/releases/latest"><img src="https://img.shields.io/github/v/release/omar-y-abdi/furl-ctx?sort=semver&color=blue" alt="发布版本"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="许可证：Apache 2.0"></a> </p> <p align="center"> <a href="#安装">安装</a> · <a href="#证明">证明</a> · <a href="LIBRARY.md">库</a> · <a href="#社区">社区</a> </p> --- Furl 是针对 AI 代理的上下文压缩：它缩小了 Claude Code 代理读取的所有内容——工具输出、日志、网页抓取、RAG 分片——在进入模型的上下文窗口之前。相同的答案，token 成本的一小部分。每个丢弃的字节都可以在需要时按需检索。 名字的由来是航海术语：*furl* 是卷起帆的意思——Furl 将长上下文卷起来，不妨碍模型，并将其放在一条线上，随时准备 *unfurl*（检索）。 Furl 源自作者的 *Headroom* 上下文工程实验项目——早期提交历史记录了该项目的传承。 <p align="center"> <img src="FurlDemo-Fast.gif" alt="Furl 运行中" width="820"> </p> ## 安装 在 Claude Code 中执行两个命令： ``` /plugin marketplace add omar-y-abdi/furl-ctx /plugin install furl@furl ``` 就这样——这安装了压缩钩子、MCP 工具和技能。无需 `pip install`，无需设置：Furl 在首次使用时自行获取。需要 [`uv`](https://docs.astral.sh/uv/) 在您的 PATH 上（与官方 [serena](https://github.com/oraios/serena) 插件相同）。 **您将获得** - **自动压缩钩子** — 在进入上下文之前缩小大型 `Bash` / `WebFetch` / `WebSearch` / `Task`（子代理）输出。失败开启：永远不会破坏工具调用。**它不会触及 `Read` / `Grep` / `Glob` 文件读取——按设计**，因此稍后的 `Edit` 仍然可以看到确切的文件字节；这些读取（通常是编码代理的最大上下文成本）会直接通过，不被压缩（[原因](#证明)）。一个诚实的限制：当输出太大，Claude Code 本身将其持久化到文件并仅向模型提供文件引用时，没有内联输出供钩子压缩。 - **已知问题：** Claude Code ≥2.1.163 目前忽略钩子的替换输出（[anthropics/claude-code#68951](https://github.com/anthropics/claude-code/issues/68951)），因此上述自动 PostToolUse 压缩存储并计算节省，但模型可能仍会接收原始文本，直到该错误修复。手动工具（`furl_compress` / `furl_retrieve` / `furl_search`）不受影响。参见 [LIBRARY.md](LIBRARY.md) 了解当前利用状态和 `FURL_PRETOOL_PIPE` 选项。 - **信号感知卸载 + 可切片检索** — 太大而无法内联压缩的有效载荷（例如 33 MB 跟踪）以结构化摘要（模式、每字段值直方图、示例行）返回，而不是截断的头/尾，代理按需提取窄切片——`retrieve(hash, select_field="name", select_equals="DroppedFrame")` 或数字范围——无需实例化整个内容。 - **MCP 工具** — `furl_compress`、`furl_retrieve`、`furl_stats`、`furl_purge`（擦除存储的原始内容）、`furl_search`（按内容子字符串查找）、`furl_list`（列出存储的条目）。第七个工具 `furl_read` 存在但默认关闭——通过 `FURL_MCP_READ=1` 启用（参见 [LIBRARY.md](LIBRARY.md)）。 - **技能** — 解释 `<<ccr:HASH>>` 检索流程以及如何调整或禁用它。 调整、禁用（`FURL_HOOK_ENABLED=0`）和完整参考：[`plugins/furl/README.md`](plugins/furl/README.md)。检索 TTL 因表面而异：库默认为 30 分钟；此 Claude Code 插件提供 24 小时窗口（`FURL_CCR_TTL_SECONDS=86400`），控制钩子的卸载和 MCP 工具的存储；`furl` CLI（默认情况下 PATH 上没有裸二进制文件——通过 `uv run --no-project --with 'furl-ctx[mcp]' furl ...` 运行，或 `pip install furl-ctx` 获取持久的二进制文件）默认为相同的 24 小时窗口。（一个没有有效 `FURL_CCR_TTL_SECONDS` 的裸 MCP 服务器为其工具存储的条目保留 1 小时会话 TTL，而嵌入在压缩输出中的丢弃行遵循库的 30 分钟默认值——完整的 24 小时窗口需要设置环境变量，因为插件提供了它。） **关于版本号的说明：** Claude Code 插件版本独立于它所固定的 `furl-ctx` 引擎——插件版本不一定意味着引擎版本，反之亦然。`/plugin` 显示插件版本；GitHub Releases 和 `CHANGELOG.md` 跟踪引擎版本；SessionStart 横幅同时显示两者（`furl <plugin> · engine furl-ctx <engine>`），这是同时查看两个版本号的最快方法。 ## 证明 真实数据上的 token 减少——过时的快照（输入在 `benchmarks/data/` 下提交以便审计；重新运行会衡量当前引擎，因此绝对计数可能会与此表不同——诚实读取带以下是权威检查）。每个数字都使用引擎自己的分词器，直接测量 `compress()`——独立于上述 PostToolUse 钩子交付问题；针头召回率为 100%（已知唯一行始终可检索，在输出中或通过 CCR）。以下每个数字都应视为**最佳上限**，而不是典型值——诚实读取如下。 *最佳上限——低熵开发装置（压缩器的快乐路径）：* | 数据集 | 项目 | 之前 | 之后 | 减少 | 信息保留 | |---------------|------:|-------:|-------:|----------:|---------------:| | 代码 | 7 | 41,025 | 471 | 99% | 100% | | 多轮对话 | 135 | 14,866 | 2,073 | 86% | 100% | | 日志 | 90 | 8,595 | 619 | 93% | 100% | | 搜索 | 90 | 4,102 | 318 | 92% | 100% | | 重复日志 | 90 | 3,621 | 120 | 97% | 100% | | 磁盘 | 9 | 694 | 279 | 60% | 100% | 跨整个语料库：**95% 更少的 tokens**（72,903 → 3,880）且信息保留 100%。完整的方法论和 6 次种子对抗性扫描：[BENCHMARKS.md](BENCHMARKS.md)。 **诚实读取：** 上述数字是最佳、低熵的上限，在开发装置上测量——两次独立的样本审计显示，在新鲜的高熵/近乎独特的现实数据上（正是真实日志和列表所在的位置），它们会下降 6–43pp。 在真正高熵的内容上，诚实无损节省位于 **0–54% 区间**，而不是 60–95%（代码 0%，搜索 40%，重复日志 54%）；以下每个数字都应视为上限，而不是典型值，并参见 [BENCHMARKS.md](BENCHMARKS.md) 中的分层感知分解。 `代码` 行的 99% 是 CCR 卸载大型非文件读取工具输出（例如 `Bash` 转储源文本）；代理自己的 `Read`/`Grep`/`Glob` 文件访问绕过压缩钩子，按设计直接传递，不压缩，节省 0%。 ## 也是一个 Python 库 同一个引擎适用于任何 Python 应用程序或 MCP 主机： ```python from furl_ctx import compress messages = [{"role": "tool", "content": "..."}] result = compress(messages, model="claude-sonnet-4") # result.messages → 当内容足够大时压缩；CCR 保持原始内容可检索 ``` 安装、使用、管道内部、提示缓存合约和完整的 `FURL_*` 配置参考位于 [LIBRARY.md](LIBRARY.md)。 ## 社区 问题或错误报告 → [打开 GitHub 问题](https://github.com/omar-y-abdi/furl-ctx/issues)（维护者最能联系到你的方式）。对于聊天，有一个 [Discord](https://discord.gg/yRmaUNpsPJ)。 **维护者说明：** Furl 目前由一个人维护——一个人处理问题、PR 和安全报告，因此响应时间根据可用性而有所不同。[CONTRIBUTING.md](CONTRIBUTING.md) 涵盖了 PR 的审查方式，[SECURITY.md](SECURITY.md) 涵盖了漏洞披露流程；无论团队规模如何，都遵循这些。 ## 许可证 Apache 2.0 — 参见 [LICENSE](LICENSE)。