LIghtJUNction/magpie-context-folding

Latest recorded source activity: October 26, 2026 at 23:14

SkillsMP catalog refreshed: November 5, 2026 at 19:57

skills collected: 2

GitHub stars: 3
GitHub forks: 0

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/LIghtJUNction/magpie-context-folding.

Repository README

Repository README source: README.md

Read the source README

Expand full README

<p align="center"> <img src="docs/assets/logo.png" alt="magpie-context-folding 折纸喜鹊 Logo" width="176"> </p> <div align="center"> <h1>magpie-context-folding</h1> <p><strong>让 Agent 主动收起已经完成的长过程，同时保留可精确恢复的原文。</strong></p> <p>显式标记 · 持久归档 · 延迟折叠 · 内容哈希 · CLI 恢复</p> [![Release](https://img.shields.io/github/v/release/LIghtJUNction/magpie-context-folding?style=flat-square)](https://github.com/LIghtJUNction/magpie-context-folding/releases/latest) [![npm](https://img.shields.io/npm/v/magpie-context-folding?style=flat-square&logo=npm)](https://www.npmjs.com/package/magpie-context-folding) [![License](https://img.shields.io/github/license/LIghtJUNction/magpie-context-folding?style=flat-square)](LICENSE) [安装](#安装) · [一分钟理解](#一分钟理解) · [恢复](#恢复原文) · [独立核心](#独立文本核心-ctxf) · [协议](docs/annotation-protocol.md) </div> ## 一分钟理解它本质上不是摘要模型，而是一段**可逆文本替换**： ```text Agent 写出阶段结论 ↓ 用注释标记包住长过程 ↓ 插件先把原文持久化 ↓ 等待一个请求周期 ↓ 把正文替换成 [[cf:v2:<短哈希>]] ↓ 需要时按 scope + 哈希精确读回 ``` 示例： ```text 保留结论：下一步检查 router.ts 的超时分支；失败重试仍未验证。  这里是较长的排查、比较、日志和推导过程。  ``` 第一次完整观察到闭合标记时，正文仍保留。下一次组装请求时，如果达到最小净节省门槛，正文才变成引用： ```text  [[cf:v2:4db3a91c6e2f]]  ``` 插件不猜哪些内容“不重要”。未标记、未闭合、错配或节省量不足的内容保持原样。 ## 它解决什么问题长任务里，历史通常同时包含两种信息： - **仍需要每轮携带的状态**：结论、约束、失败、待办、当前文件和下一步； - **偶尔才需要回查的证据**：长日志、探索过程、大段源码、重复比较和已经结束的推导。折叠协议要求 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、账单节省或任务提速。完整方法和限制见 [基准与质量记录](docs/cost-speed-quality.md)。 ## 安装 ### Magpie 插件 ```bash magpie plugin add npm:magpie-context-folding@0.5.2 ``` 保留已有归档，不要同时加载 npm 包和同一插件的本地源码副本。开发版需要 Bun 1.4+、Node.js 22+ 和 npm： ```bash 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，不依赖标签名。 ## 源码标记同一语法可用于源码注释： ```rust // @context-fold begin parse-options let options = parse_options(input)?; validate_options(&options)?; // @context-fold end parse-options ``` ```python # @context-fold begin parse-options options = parse_options(source) validate_options(options) # @context-fold end parse-options ``` 插件只修改发送给模型的视图，不改写原文件。对 Python、JavaScript 和 TypeScript 会尽量排除字符串中的伪标记；遇到无法可靠解析的模板插值、JSX 或复杂语法时，保守地保留完整源码。完整语法、嵌套、跨消息配对和失败行为见 [注释协议](docs/annotation-protocol.md)。 ## 恢复原文从引用中取出实际短哈希，并使用请求提示中的 scope： ```bash magpie-context-folding read \ --scope 'CURRENT_SCOPE' \ --id 'ACTUAL_SHORT_HASH' \ --restore ``` 主要命令： | 命令 | 作用 | | --- | --- | | `read` | 读取折叠视图、完整原文或分页结果 | | `list` | 找回忘记的引用和历史归档 | | `grep` | 在归档中搜索定义、字符串或证据 | | `meta` | 查看节点、父子关系和哈希元数据 | | `paste` | 将选定内容写入新文件，拒绝覆盖已有文件 | | `status` | 查看当前会话和最近处理状态 | | `stats` | 查看字节和估算 token 统计 | | `forget` | 清理已无活动引用的会话归档 | `scope` 是会话恢复能力值，不应交给其他会话。恢复得到的是历史资料，不会自动执行其中的旧命令。 ## 独立文本核心 `ctxf` `context-folding/` 提供独立 Python 包，用于显式文本转换和持久归档，不依赖 Magpie： ```bash uv tool install ./context-folding cat notes.txt | ctxf > notes.folded.txt ctxf fold --language python < module.py > module.folded.txt ``` `ctxf fold` 立即处理已经闭合的合法标记，不等待下一轮请求。它先保存正文，再输出引用；标准输出只包含转换后的文本，诊断写到标准错误。 ```bash ctxf read --scope default --id ACTUAL_SHORT_HASH --restore ``` Python 核心和 Magpie 插件使用不同归档后端，scope 与引用不互通。用生成引用的同一后端恢复。完整说明见 [独立核心文档](context-folding/README.md) 和 [传输协议](context-folding/docs/TRANSPORT.md)。 ## 配置加载顺序：内置默认值 → 全局配置 → 最近的项目配置 → 插件 options。 - 全局：`$XDG_CONFIG_HOME/context-folding/config.toml` 或 `~/.config/context-folding/config.toml` - 项目：从当前目录向上查找 `.context-folding.toml`，到 Git 根目录停止 ```toml 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` 建组、预算注入和自动摘要。旧配置中的下列字段不会被悄悄映射： ```text 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、回答质量和真实费用是四个不同指标。 ## 开发验证 ```bash npm ci npm run check ``` Python 核心在 `context-folding/` 中独立测试。历史基准和旧费用分析保留用于追溯，但不能直接当作 0.5.x 的效果证明。 ## License [MIT](LICENSE)

Loading the repository README…

Skills in this repository

classification pending

skill

occupation

description

updated

source-fold-markers

unclassified

Add and maintain safe paired source folding comments when creating or modifying code. Use when working on source files that can benefit from compact, recoverable source views.

2026-10-26

context-folding

unclassified

Archive verbose context locally, write reversible summaries, browse originals, and resolve archived references before tools execute. Use when long tool outputs or historical observations consume working context.

2026-10-26

Showing 2 of 2 collected skills.