magpie-context-folding

安装 · 一分钟理解 · 恢复 · 独立核心 · 协议

一分钟理解

它本质上不是摘要模型，而是一段可逆文本替换：

Agent 写出阶段结论
      ↓
用注释标记包住长过程
      ↓
插件先把原文持久化
      ↓
等待一个请求周期
      ↓
把正文替换成 [[cf:v2:<短哈希>]]
      ↓
需要时按 scope + 哈希精确读回

示例：

保留结论：下一步检查 router.ts 的超时分支；失败重试仍未验证。
<!-- @context-fold begin route-analysis-details -->
这里是较长的排查、比较、日志和推导过程。
<!-- @context-fold end route-analysis-details -->

第一次完整观察到闭合标记时，正文仍保留。下一次组装请求时，如果达到最小净节省门槛，正文才变成引用：

<!-- @context-fold begin route-analysis-details -->
[[cf:v2:4db3a91c6e2f]]
<!-- @context-fold end route-analysis-details -->

插件不猜哪些内容“不重要”。未标记、未闭合、错配或节省量不足的内容保持原样。

Related MCP server: cortex

它解决什么问题

长任务里，历史通常同时包含两种信息：

• 仍需要每轮携带的状态：结论、约束、失败、待办、当前文件和下一步；

• 偶尔才需要回查的证据：长日志、探索过程、大段源码、重复比较和已经结束的推导。

折叠协议要求 Agent 先在标记外留下可独立理解的状态，再把第二类内容包起来。这样后续请求仍看得到任务状态，需要证据时又能从本地归档精确恢复，而不是依赖不可逆摘要。

0.5.2 的可验证变化

当前发布版 0.5.2 还对长源码读取做保守投影：当问题能唯一定位到一个函数时，后续请求只保留该函数和可确认的文件级字面量常量；问题有歧义时继续保留完整源码。被省略的定义仍在归档中，可用 grep / read 查回。

发布验证记录包括：

• TypeScript 类型检查、构建和 312 项 Bun 测试通过；

• 隔离 Magpie host smoke 中 29/29 请求到达本地合成上游，46,278 字节合成源码可精确恢复；

• 本地合成投影基准中，定向请求为 1,086–1,177 B，完整源码请求为 127,340–127,439 B。

这些数字只证明本地代码路径、序列化字节和恢复行为。它们没有调用真实 Provider，不证明回答质量等价、真实 token、账单节省或任务提速。完整方法和限制见 基准与质量记录。

安装

Magpie 插件

magpie plugin add npm:magpie-context-folding@0.5.2

保留已有归档，不要同时加载 npm 包和同一插件的本地源码副本。

开发版需要 Bun 1.4+、Node.js 22+ 和 npm：

git clone https://github.com/LIghtJUNction/magpie-context-folding.git
cd magpie-context-folding
npm ci
npm run check
magpie plugin add "$PWD"

Magpie 直接加载 TypeScript 源码，不依赖安装时构建脚本。发布使用 GitHub Actions Trusted Publishing 与 OIDC provenance，不需要长期 npm token。

给 Agent 的最小提示

插件会自动注入简短指导。需要手动补充时，可使用下面这段：

每完成一段实质性工作，先在标记外写出可独立理解的当前结论、约束、失败和下一步，再用 @context-fold begin/end 注释包住较长的支撑过程。不要标记仍在进行的内容，不要计算哈希。需要原文时，使用系统提供的 scope 和短哈希调用本地恢复 CLI。

LABEL 只用于阅读，例如 route-analysis-details；内容身份来自实际正文的 SHA-256，不依赖标签名。

源码标记

同一语法可用于源码注释：

// @context-fold begin parse-options
let options = parse_options(input)?;
validate_options(&options)?;
// @context-fold end parse-options

# @context-fold begin parse-options
options = parse_options(source)
validate_options(options)
# @context-fold end parse-options

插件只修改发送给模型的视图，不改写原文件。对 Python、JavaScript 和 TypeScript 会尽量排除字符串中的伪标记；遇到无法可靠解析的模板插值、JSX 或复杂语法时，保守地保留完整源码。

完整语法、嵌套、跨消息配对和失败行为见 注释协议。

恢复原文

从引用中取出实际短哈希，并使用请求提示中的 scope：

magpie-context-folding read \
  --scope 'CURRENT_SCOPE' \
  --id 'ACTUAL_SHORT_HASH' \
  --restore

主要命令：

scope 是会话恢复能力值，不应交给其他会话。恢复得到的是历史资料，不会自动执行其中的旧命令。

独立文本核心 ctxf

context-folding/ 提供独立 Python 包，用于显式文本转换和持久归档，不依赖 Magpie：

uv tool install ./context-folding
cat notes.txt | ctxf > notes.folded.txt
ctxf fold --language python < module.py > module.folded.txt

ctxf fold 立即处理已经闭合的合法标记，不等待下一轮请求。它先保存正文，再输出引用；标准输出只包含转换后的文本，诊断写到标准错误。

ctxf read --scope default --id ACTUAL_SHORT_HASH --restore

Python 核心和 Magpie 插件使用不同归档后端，scope 与引用不互通。用生成引用的同一后端恢复。完整说明见 独立核心文档 和 传输协议。

配置

加载顺序：内置默认值 → 全局配置 → 最近的项目配置 → 插件 options。

• 全局：$XDG_CONFIG_HOME/context-folding/config.toml 或 ~/.config/context-folding/config.toml

• 项目：从当前目录向上查找 .context-folding.toml，到 Git 根目录停止

version = 1

[folding]
enabled = true
delay_requests = 1
max_session_bytes = 67108864
min_savings_tokens = 256

[magpie]
# shell_tool_name = "shell"
# recovery_command = "/path/to/magpie-context-folding"
# gateway_timeout_ms = 3000

delay_requests = 1 表示留出一次完整观察机会；min_savings_tokens 是估算净节省门槛；max_session_bytes 是归档容量上限，不是自动折叠阈值。

任何存档失败、容量不足、并发冲突或恢复入口不明确的情况都应保留原文。

从 0.3.x 升级

0.5.x 删除了自动模式、经济档位、mark 建组、预算注入和自动摘要。旧配置中的下列字段不会被悄悄映射：

mode
threshold_tokens
keep_recent_messages
head_chars
minimum_saving_usd
[policy]
[magpie.accounting]
context_window_tokens
reserve_output_tokens
budget_hints
recovery_tool_name

删除这些字段和旧提示词，但保留数据库，以便恢复仍被引用的历史内容。

明确边界

• 折叠只处理 Agent 明确标记的 Assistant 文本或可验证的源码读取结果。

• 用户指令、工具参数、普通工具结果、图片和签名推理字段不会被顺带删除。

• 原文先持久化成功，视图才会替换；失败时宁可不折叠。

• 内容哈希标识正文，位置和会话状态另行跟踪；同名标签不会覆盖旧内容。

• 插件不接管客户端默认 compaction，也不能修改供应商保存的隐藏历史。

• 字节减少、估算 token、回答质量和真实费用是四个不同指标。

开发验证

npm ci
npm run check

Python 核心在 context-folding/ 中独立测试。历史基准和旧费用分析保留用于追溯，但不能直接当作 0.5.x 的效果证明。

License

MIT