LIghtJUNction/magpie-context-folding

Dernière activité source enregistrée: 26 octobre 2026 à 23:14

Catalogue SkillsMP mis à jour: 2 novembre 2026 à 18:02

skills collectés: 2

Étoiles GitHub: 3
Forks GitHub: 0

Installer avec un assistant IA

Copiez ce prompt dans l’assistant IA que vous utilisez.

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

README du dépôt

Fichier source du README : README.md

Lire le README source

Afficher le README complet

<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)

Chargement du README du dépôt…

Skills dans ce dépôt

classification en attente

skill

métier

description

mis à jour

source-fold-markers

non classé

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.

Langue du texte source : anglais

2026-10-26

context-folding

non classé

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.

Langue du texte source : anglais

2026-10-26

Affichage de 2 skills collectés sur 2.