pi-context-management 0.6.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.6.0-beta.2 — GitHub 测试源码，npm 尚未发布
+
+- 主 Agent 最终回复前检查进度变化，使用现有 `context_notes` 即时更新有变化的笔记，不等待压缩或后台门槛。
+- 收尾规则要求真实来源、完成范围、验证结果、剩余工作与审批；检查保存结果，失败时明确说明，避免循环重试。
+- 通过 Pi 官方工具提示接线，不增加独立收尾模型请求，不强制将回复结束认定为完成。模型遵守情况仍需实测。
+
+## 0.6.0-beta.1 — 本地候选，尚未发布
+
+- 分支内来源检索、带引用笔记、可重放完整状态和已解决普通笔记的有界退休。
+- 后台增量笔记、原生摘要协调、手动交接、带冷却与暂停保护的自动交接。
+- 会话诊断与费用统计；300 秒统一生成期限、一次容量精简及失败重试限制。
+- `PI_SUBAGENT_CHILD=1` 子进程跳过整个扩展，避免在后台子任务中开启记忆交接。
+- 显示实际笔记覆盖时间与后续消息数，区分保存成功和覆盖最新进度。
+- 容量精简允许延续首次候选已提出且有本批新引用的完成更新；保留来源与类型保护。
+- 细分生成检查点的结构、覆盖位置与精简状态变化错误。
+
+兼容性：验证目标为 Pi 0.85.0。新版状态事件不保证旧版插件可读，使用新版写入后不要直接降级继续写该会话。8000 字节 / 32 条容量限制可能阻止更新；真实模型总结质量、长期费用与稳定性仍需 beta 实测。
+
+## 0.1.0
+
+- GitHub 首版：分支历史检索、来源笔记与压缩接线。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danieldexter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# Pi Context Management
+
+为 pi 的长任务提供当前分支历史检索、带来源的任务笔记和自定义压缩。原始消息仍保存在 pi 会话中；模型可按需找回细节，压缩时保存简短笔记和近期对话。
+
+这是借鉴 Codex 实验上下文管理的本地实现。Codex 的历史和笔记服务端没有完整开源，本包不调用其私有接口，也不实现完全相同的窗口重置机制。
+
+## 安装与使用
+
+当前验证版本：`@earendil-works/pi-coding-agent` **0.85.0**、Node.js **24.15.0**。包要求 Node.js ≥22.18.0，其他 pi 版本尚未验证。
+
+当前源码版本为 **0.6.0-beta.2**，加入主 Agent 最终回复前的主动笔记更新规则；保留覆盖进度、细分校验失败和容量精简修正。属于测试版本，npm 尚未发布；GitHub 的旧标签 `v0.1.0` 不包含这些更新。
+
+主 Agent 通过 Pi 官方工具提示收到收尾规则：最终回复前检查本轮是否改变任务进度、决定、约束、阻碍或待审批事项；有变化时使用 `context_notes` 更新原 key，记录实际完成范围、验证结果和剩余事项，检查工具返回 `ok=true` 后才称保存成功。无变化则不写。证据不足不自动标完成，子 Agent 报告保留待核实性质；来源必须是已有真实分支消息，不能引用尚未写出的最终回复。保存失败时要求明确说明并停止循环重试。
+
+这是主 Agent 的提示规则，需要模型遵守；不是回复结束后的强制判定，也不增加独立的收尾模型请求。即时工具写入不受后台字节门槛或冷却限制，后台维护继续兜底。单条工具更新不推进完整历史覆盖位置，因此笔记内容已更新时，`memory.coverage` 仍可能显示后续未归纳消息。8000 字节容量限制依然有效，不能保证每次更新成功。
+
+笔记优先保留当前目标、有效约束、待审批、未完成事项和下一步。完成阶段与旧方案优先保留产物入口和适用限制，已解决运行错误保留原因、有效处理办法及剩余风险；缩短时复用原 key 并保留来源，不按年龄自动删除。环境版本、依赖可用性和工作区状态标为来源时的观测，缺少时间依据时注明时效待核实。这是后续生成的提示策略，不直接改写已有笔记，也不保证模型语义完整性。
+
+笔记容量仍最多 32 条、8000 UTF-8 字节（小窗口可能更低）。生成时以实际预算的 80% 为目标，为格式与来源引用预留空间；容量校验失败后，整次生成最多重新生成同一来源批一次，并反馈 `note_bytes` / `note_count` 的实际值与上限。精简请求计入原有请求上限和共享 300 秒期限，不重置计时；再次失败不保存部分候选。精简保留活跃项类型；只有首次候选已提出完成，且精简结果保留首次候选引用的本批新来源时，才允许延续该完成状态。引用存在不证明任务真的完成，语义仍需人工核对；不得为了容量临时解决未完成事项。
+
+`memory.coverage` 显示笔记覆盖位置、该来源时间和后续消息数（含工具交换），会话面板同步展示。最近保存时间晚，不代表已追上当前任务。后台按回复结束事件触发，新增来源至少达到 `min(16384 UTF-8 字节, 模型窗口 × 10%)`，成功后冷却 60 秒；没有空闲定时生成，因此最后一小段回复可能等待下一轮。后台不依赖自动压缩阈值。遇到未协调的原生摘要会保守停止，由后续检查点协调。消息数只是覆盖差距，不是遗漏事实数。
+
+生成校验错误区分 `invalid_checkpoint_shape`（结构）、`invalid_checkpoint_boundary`（批次确认位置）和 `invalid_checkpoint_repair_transition`（精简引入不允许的状态变化）。旧日志中的 `invalid_checkpoint` 无法据此追溯具体原因。
+
+后台同一来源前缀、笔记状态、模型与生成策略的容量失败不再按冷却定时重试；相关范围/状态/策略改变后才重新尝试，其他暂时性错误仍最多两次。旧策略的失败可在升级后按新策略尝试，自动交接的暂停状态不会因此解除。`/ctx-memory status` 的 `memory` 与会话面板显示已保存笔记数、最近保存时间及最近笔记失败；原生 compact 不计作插件笔记保存。逐次调用日志的 `budget` 仅包含超限类型、实际值和限制，不包含笔记正文。
+
+运行范围：检测到 `PI_SUBAGENT_CHILD=1` 时直接跳过初始化，不注册记忆工具、命令、状态栏、诊断或压缩/交接事件。子 Agent 的上下文压缩仍由 Pi 原生机制处理，主会话行为不变。这一识别约定来自 `pi-subagents`；未设置该标记的其他子 Agent 启动器不在自动识别范围内。
+
+从 GitHub 安装当前测试源码（`main` 会随后续提交更新）：
+
+```powershell
+pi install git:github.com/Danieldexter/pi-context-management@main
+```
+
+首次 npm beta 发布后安装（目前尚未发布）：
+
+```powershell
+pi install npm:pi-context-management@beta
+```
+
+本地开发时，在包目录执行 `npm ci`，然后安装当前目录：
+
+```powershell
+pi install .
+```
+
+已有 pi 会话执行 `/reload`，或重新启动 pi。终端状态栏应出现 `Memory: ready`。本包沿用当前模型和 pi 的压缩配置，无需另配 API key。
+
+```text
+/ctx-memory status
+/ctx-memory notes
+/ctx-memory compact
+/ctx-memory cancel
+/ctx-memory handoff
+/ctx-memory auto off
+/ctx-memory auto on
+/ctx-memory session
+/ctx-memory session export
+```
+
+- `status`：查看笔记数量、原始消息数量、检查点位置和召回剩余额度。
+- `notes`：查看任务笔记。新会话尚未写笔记时只显示说明文字。
+- `compact`：请求 pi 压缩；也会处理 pi 原有的自动压缩事件。
+- `cancel`：取消当前后台笔记或交接准备，已保存笔记保留，后续新增历史仍可触发维护。
+- `handoff`：生成交接包、新建会话并自动接手，详见下文。
+- `auto off` / `auto on`：关闭或恢复本会话的自动交接；设置随交接继承，恢复不会清除冷却和次数限制。
+- `session`：打开会话面板；`session close` 关闭；`session export` 导出近期诊断报告。
+
+更新本地包后执行 `/reload`，再用 `/ctx-memory status` 检查 `version` 和 `loadedAt`。`/reload` 仅重新加载，不自动补写笔记。`checkpointState` 为 `not_created` 表示没有插件检查点或笔记，`notes_only` 表示已有笔记但尚无检查点，`ready` 表示已有插件检查点；它不保证笔记覆盖最新进展。`lastCompaction.origin` 区分插件检查点（`plugin`）与 Pi 原生或其他扩展压缩（`pi`）。`failedAttempts` 是当前分支的历史累计，成功后不清零；`lastFailure` 提供最近失败的代码和时间，并不代表它发生在本次 reload 之后。
+
+分批生成期间，状态栏显示当前批次。尚无笔记且希望现在生成时，执行 `/ctx-memory compact`；完成后查看 `/ctx-memory notes` 并核对内容。
+
+`activeNotes` 和 `resolvedNotes` 分别统计当前笔记集中的活跃项和已解决项。达到条数或字节上限时，插件按保存顺序移出已解决的普通笔记；活跃项、约束、失败尝试和本次更新项不会因容量策略被自动移出。约束和失败尝试的已有 key 不能改成其他种类，以免绕过保护。没有可移出的笔记时仍会明确报告 `notes_budget`。退出当前笔记集不删除原始会话记录，可按来源回查历史。
+
+从 **0.1.3** 起写入版本 2 笔记状态，支持读取旧版笔记与检查点，不迁移或重写已有会话文件。已写入新版状态的会话不要降级到 0.1.2 或更早版本继续写入；旧版不能完整恢复这些状态。
+
+**0.2.0** 另有后台笔记事件和独立的笔记覆盖位置，0.1.3 不识别它们；已使用后台维护的会话也应保留在 0.2.0 或兼容后续版本中继续写入。
+
+正常对话即可使用。也可明确告诉模型：“请把当前目标和约束保存为带来源的任务笔记；需要早期细节时搜索历史。”启动和 `/reload` 本身不补记，下一轮对话结束后会检查新增历史量。
+
+## 后台增量笔记（0.2.0）
+
+默认在每轮模型回复与工具调用结束后检查新增历史。达到 `min(16384 UTF-8 字节, 模型窗口 × 10%)` 时异步生成笔记；前台继续工作，每个扩展实例最多一个后台生成任务。每次选择约 64 KiB 的闭合历史前缀，不拆开工具调用与结果边界；单个超大完整来源可以超过这个选择量，但仍受输入分批约束。后台最多 4 次模型请求、总计 300 秒，全部成功后才保存结果，成功后至少间隔 60 秒再启动。
+
+`/ctx-memory status` 的 `background` 显示是否启用、是否运行、历史失败代码和最近一次成功后台生成的用量；`notesThroughEntryId` 表示笔记已处理的位置，`throughEntryId` 仍只表示已归档位置，两者可以不同。压缩会复用已保存笔记，只处理尚未覆盖的归档来源；显式自定义压缩指令会重新处理归档区间。笔记可能已经覆盖仍保留在上下文中的近期内容，这些内容不因记过笔记而被插件删除。
+
+手动更新笔记、分支切换、重载、关闭或开始压缩会取消未完成后台结果，压缩不等待后台生成。前台运行中的取消信号也会取消后台任务。Pi 0.85 在前台已结束后没有独立的插件停止通知，此时使用 `/ctx-memory cancel`。结果提交前检查原分支祖先、模型和笔记状态；普通消息追加允许继续，笔记修改与压缩会使旧候选失效。
+
+普通后台失败记录诊断，不反复弹窗；60 秒后有新一轮对话才尝试重试，相同源前缀与笔记状态最多尝试两次。再次失败后，需要来源范围、模型或笔记状态改变才能恢复该前缀的尝试，原生压缩仍可继续。遇到尚未衔接的原生摘要或不支持的分支内容时，后台暂缓，交给常规压缩路径处理。磁盘写入失败仍明确提示重新打开保存的会话。
+
+重试标识也包含生成预算。升级到 0.5.3 后，旧 60 秒策略下已经耗尽尝试次数的前缀可在新预算下重新尝试；仍须经过失败冷却并由后续回复触发，同一新预算下的两次限制不变。升级不改写历史失败，也不自动恢复已暂停的自动交接。
+
+后台调用使用当前模型，会产生额外费用；实际质量、速度与总费用改善尚未经过真实模型对比。可以启动 `pi --context-memory-no-background` 关闭后台维护，保留手动笔记与压缩功能。
+
+## 会话交接（0.3.0）
+
+执行 `/ctx-memory handoff`，插件补齐尚未覆盖的任务笔记，保存交接包，然后通过 Pi 0.85 的正式会话接口新建并切换会话，自动发送接手提示。整个过程在当前 Pi 界面中完成，无需复制交接包、输入 `/new` 或另开终端。0.4.0 另支持下述自动触发。
+
+交接包包含带来源的目标、约束、决定、失败尝试、未完成事项等笔记，以及原会话 ID、固定分支摘要校验值、捕获时间、工作目录、Git 状态和文件路径。验证结果只有历史确实记录且模型提取时才会保留，接手时要求重新核对文件和 Git。所有继承笔记标为推断，交接包不能增加授权，待用户决定或审批的事项保持等待。
+
+历史工具默认读取当前会话；指定 `scope: "handoff"` 可回查直接父会话交接时的分支。来源 ID 保留在可见交接包中；后续新增消息、兄弟分支和隐藏 shell 内容不纳入该范围。来源文件丢失、修改或收据绑定不符时拒绝回查，不允许传入任意文件路径。连续交接只提供直接父会话范围，不递归访问更早的祖先会话。
+
+交接需要已落盘的会话和可用模型，沿用有界分批生成，可能产生额外模型费用；交接包和显示文本分别限制为 `min(16384 字节, 模型窗口 × 10%)`，父会话文件读取上限 32 MiB。超限或生成失败不切换。`/ctx-memory cancel` 可取消准备阶段；切换开始后按 Pi 会话替换机制执行。新会话文件以独占创建方式保存并校验，避免等待首条模型回复才落盘。
+
+初始化失败时尝试返回原会话；若其他扩展取消返回，会提示用 `/resume` 打开原会话。Pi 自身在重建运行环境时失败可能无法自动恢复，可重启后 `/resume` 原会话，原记录与已保存交接包仍保留。接手请求启动失败不删除已保存新会话。重开新会话只恢复已有交接内容，不重复发送接手请求。使用交接后的会话请保持在 0.3.0 或兼容版本，旧版本不理解跨会话来源绑定。
+
+## 自动交接（0.4.0）
+
+默认启用。在完整模型回复与工具循环结束后检查 Pi 报告的上下文用量：达到窗口的 **80%**，或已达到 **65%** 且按最近两次完整回复的用量增长推算下一轮将达到 **90%**，就安排一次交接。增长估计仅在同会话、同模型且未压缩时使用；未知用量不触发。后台笔记负责提前增量准备，交接只补齐剩余来源，不另维护一份容易过期的候选包。
+
+增长预测要求连续的有效观测。关闭/恢复、冷却期间无法触发的观测、队列阻塞和未知用量会清除旧基线；恢复后的第一次观测仍可按 80% 直接触发，但不会把间隔内累计增长当成一轮增长。
+
+通过 Pi 正式扩展命令派发接口取得会话控制能力，等待 `waitForIdle()` 后重新核对用量、模型、会话和待处理消息。用户新输入、模型或分支切换、重载、关闭及原生压缩都会撤销准备阶段；不会中断正在运行的工具。原生压缩优先：若它已完成，必须在后续完整回复后重新判断压力，不能凭旧阈值继续切换。进入会话替换后沿用上节的初始化和恢复流程。
+
+每次自动准备最多 **4 个模型请求、300 秒**；新会话初始化验证成功后冷却 **5 分钟**，任意一小时最多 **3 次**。准备时先保存暂停状态，成功目标再解除暂停并继承次数，防止失败或重启后反复切换。失败、取消准备或取消切换后暂停自动交接，可用 `/ctx-memory auto on` 恢复；后台笔记和 Pi 原生压缩仍可继续。手动交接继承自动开关与限制，避免意外重新启用。
+
+普通生成失败不弹窗，查看 `/ctx-memory status` 的 `autoHandoff`：`enabled`、`paused`、`pending`、`attemptsInHour`、`nextEligibleAt` 和 `lastFailure`。准备期间仅更新状态栏；存储失败、初始化恢复失败或接手启动失败才明确提示。`attempt_incomplete` 表示准备未成功完成，包含取消或运行中断，不等于模型错误。`nextEligibleAt` 仅表示时间限制解除，还需后续回复达到压力条件；没有定时器自动唤醒模型。
+
+用 `/ctx-memory cancel` 取消准备。**Pi 0.85 空闲时按 Esc 不会通知扩展，不能保证取消交接准备。** 启动参数 `pi --context-memory-no-auto-handoff` 强制关闭自动交接，优先于 `auto on`，手动交接仍可用。`--context-memory-no-background` 仅关闭后台笔记，不关闭自动交接。
+
+自动交接会创建新会话并产生额外模型调用；继承的待审批事项仍待审批，不因此取得新授权。使用自动交接状态的会话请保持在 0.4.0 或兼容后续版本。触发阈值和增长估计是保守调度策略，尚未通过真实长任务证明质量或费用改善。
+
+卸载时使用对应的安装来源，例如 `pi remove npm:pi-context-management` 或 `pi remove git:github.com/Danieldexter/pi-context-management@v0.1.0`，随后 `/reload`。既有会话中的原始消息和已保存检查点继续保留。
+
+## 会话面板与实测日志（0.5.0）
+
+`/ctx-memory session` 在 Pi 的 widget 区域显示当前/直接来源会话、上下文用量、自动交接状态、目标/约束/未完成项数量、来源检查、调用及失败统计、额外 token、提供方计价和疑似重复工具次数。调用与交接阶段会更新独立状态栏；面板开启时随完成事件刷新，不使用定时器、不替换其他插件的 footer/widget。进度只显示实际阶段和当前批次，不虚构总批数或百分比。面板显示状态属于当前 Pi 实例，重载后可重新打开。
+
+笔记成功提交、自动开关变更、压缩和分支/模型变更也会刷新面板。重叠请求合并为最新视图，失效快照最多立即重试一次；关闭面板后，未完成的刷新不会重新打开它。
+
+`Memory: storage ready` 只表示笔记存储检查通过，不表示本次生成成功。`/ctx-memory status` 的 `budgets.generationTimeoutMs` 与报告的 `policy.generationTimeoutMs` 显示当前整次生成预算（300000）；调用进度和日志的 `generationTimeoutMs` 同步显示这一预算，所有批次共享它，不是每批重新获得五分钟。旧日志缺少该字段时保持未知。
+
+已保存的会话自动写入 **`<Pi 会话文件>.ctxlog.jsonl`**，每次逻辑调用记录开始/结束、类型、模型标识、时间、耗时、已返回用量、结果代码。覆盖前台模型回复和本插件的后台/压缩/交接调用；SDK 内部 HTTP 重试、其他扩展自己的模型调用不保证可见。Pi 原生压缩回退只提供汇总记录，明确标成 `native_compaction`，不伪装成逐次请求。
+
+日志不保存对话正文、工具参数、文件内容、密钥或错误原文；工具重复检测仅保存带临时随机密钥的 HMAC 指纹，不保存密钥。每个日志最多 2 MiB，保留当前和 `.1`、`.2` 两份备份，较旧诊断自动轮转淘汰，**不删除 Pi 会话或任务笔记**。未保存会话没有日志文件；日志写入失败不会阻断模型任务，状态栏会提示，损坏或未写完的行会计入导出诊断。
+
+实测后执行：
+
+```text
+/ctx-memory session export
+```
+
+Pi 会提示导出文件 **`<Pi 会话文件>.ctx-report.json`** 的完整位置。把该 JSON 文件交给分析者即可，无需截图或复制状态输出。再次导出会更新同一份报告。报告包含指标、当前触发策略和原始诊断事件，移除了本地日志路径；日志本身只在你的电脑上保存，不自动上传。多次跨会话实测时建议每个需要比较的阶段导出一次并另存，长期原始日志仍按上述容量保留。
+
+导出范围是当前会话的近期诊断（包含其各分支），加上**验证过的直接父会话在交接捕获之前的诊断**；不递归读取更早会话或扫描其他项目。操作按 ID 去重，初始化失败恢复原会话也保留失败结果。轮转、崩溃、缺失文件或更早版本未记录的数据不能还原；因此统计是保留窗口内的数据，不是全生命周期总额。
+
+0.5.1 的 `operation_start.trigger` 标记 `mode`（manual/automatic）、`reason`（manual/threshold/forecast）和触发时的 `tokens`、`contextWindow`、`growthTokens`、`projectedTokens`。触发判断与诊断共用策略；字段只包含枚举和数值，未知用量为 null，旧日志没有该字段时不能推断触发方式。
+
+`missingPrimaryFiles` 表示读取时缺少主日志的会话数，同时计入 `unavailableFiles`；不存在的可选 `.1`/`.2` 备份不算异常。主日志可能尚未创建、来自未记录诊断的旧会话或已经丢失，不能据此断言发生了删除。面板显示缺失/不可用文件及损坏行数量，零条可见调用不代表历史上没有调用。
+
+指标解释：
+
+- `returnedTokens` / `extraTokens`：已返回的总 token / 笔记、压缩和交接额外 token；未知用量单列，不能把没有数据理解为零成本。
+- `reportedCost` / `extraReportedCost`：Pi/提供方返回的计价估算，不是账单；模型配置价格为零时也会返回零。未返回费用不能推算。
+- `failureRate`：已结束、可观察逻辑调用中的失败比例；取消单列。内部超时按失败记录，未结束调用另列。原生压缩汇总不混入逐调用失败率。失败/取消且所有 token 与费用均为零时，可能只是 SDK 初始值，保守计入用量未知；该解释同时适用于旧日志导出。成功的零用量和失败时实际返回的非零用量仍保留。
+- 前台调用计时到 assistant `message_end`，不包含随后的工具执行；各调用耗时相加在有并发时不等于墙钟时间。交接操作另外记录全流程耗时。
+- `suspectedRepeatedTools`：同一扩展实例中完全相同参数的成功工具调用再次出现的次数。重复读取可能合理，换参数的重复劳动可能漏掉；重载/新实例更换指纹密钥，不作跨实例重复判断。
+- 质量检查核验来源 ID 是否有效、已有活跃项是否消失/改写，并统计目标、约束、未完成项及待审批关键词线索。**不能自动证明语义完整或审批无遗漏**，空计数也不是质量通过。交接包不增加授权。
+
+80% 阈值、65% 起预测 90%、5 分钟冷却和每小时 3 次限制保持不变；它们与导出报告共享同一份策略常量。先根据真实日志比较质量、费用和打断情况，再调整参数，不自动依据可疑重复提示修改任务行为。
+
+## 模型工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `context_history_search` | 区分大小写的字面子串搜索，返回来源 ID、角色、时间和命中片段；支持中文、路径和符号 |
+| `context_history_read` | 按来源 ID 分页读取已记录的原始文本；将返回的 `nextOffset` 原样用于下一页 |
+| `context_notes` | 读取笔记，或使用稳定 `key` 更新目标、约束、决定、失败尝试、未完成项和引用 |
+| `context_status` | 查看当前上下文估算、检查点和召回额度 |
+
+默认范围限于当前会话、当前分支的祖先链；`scope: "handoff"` 的例外见上文。分叉继承祖先消息，不能读取其他分支或父会话之后新增的内容。搜索游标允许同分支继续追加消息；更换查询、范围、分支或会话后应重新搜索。
+
+笔记必须引用该范围中的原始消息 ID；明确标为非推断的用户约束必须引用用户消息。同一 `key` 更新时保留版本关系，已完成事项可标为 `resolved`。来源存在不代表模型的概括一定正确，应按需核对原文。历史记录和笔记均不能增加授权或覆盖最新用户指令。
+
+## 压缩、预算与数据
+
+Pi 触发手动、自动或溢出恢复压缩时，插件通过当前模型连接发送“现有笔记＋本次归档历史”，生成结构化笔记更新。历史过大时按时间顺序分批，每批携带上一批校验通过的笔记；单条超长消息按 Unicode 边界切分，保留来源 ID 和 UTF-16 字符位置。每批按实际 JSON 序列化后的字节数预留系统提示、模型输出及安全空间，不把整段超限上下文再次发给检查点模型。
+
+全部批次成功后才保存一个检查点及完整来源边界；中途失败不会保存部分笔记。仍沿用 Pi 选定的近期消息边界和文件操作跟踪，由 Pi 负责压缩后继续任务。普通检索与笔记读写不额外调用模型。
+
+当前使用 **UTF-8 字节数作为保守预算单位**，不是精确 token 计数：
+
+- 任务笔记最多 `min(8000, 模型窗口 × 5%)` 字节、32 条；完整检查点（笔记和文件操作列表）另受 `min(16384, 模型窗口 × 10%)` 字节限制。文件列表仅在接近完整检查点上限时挤占笔记空间；不会自动删除约束或文件列表来适配预算。笔记按主题复用 key，已 resolved 的笔记仍计入条数上限。
+- 每个 assistant turn 的工具召回总量最多 `min(4000, 模型窗口 × 5%, 安全剩余空间)` 字节；搜索、原文读取和笔记读取共享额度。
+- 安全余量预留 `max(16384, 模型窗口 × 20%)`；空间未知或不足时暂停召回，返回明确错误。
+- 原文单次读取最多 3000 字节，搜索单条摘录最多 1100 字节。大结果通过游标或偏移分页，Unicode 字符保持完整。
+- 普通压缩、手动交接、后台笔记和自动交接都共享最多 300 秒的整次生成预算，由同一常量维护。普通压缩/手动交接最多 16 次请求，后台/自动交接最多 4 次；进入下一批不会重置计时。已有笔记和固定请求信息挤满输入预算、达到批次数上限、模型输出不完整或校验失败时，回退 Pi 默认压缩。用户取消或切换分支时取消整次操作。
+
+笔记写入当前 pi 会话的自定义记录，检查点写入压缩记录，无额外数据库。索引按当前分支重建。`!!` 隐藏命令及输出不参与搜索、读取、笔记引用或压缩模型输入。其他扩展的纯文本 `custom_message` 可参与检索、引用和检查点生成，保留来源 ID，以 `custom` 角色及扩展类型标注，不能单独作为明确用户约束的来源。`display: false` 仅控制界面显示，Pi 仍将这类消息加入模型上下文；扩展的 `details` 和普通 `custom` 状态记录不进入索引。
+
+图片像素、模型内部思考和分支摘要不作为原始文字索引；原日志未保存或已经截断的内容不能恢复。含非文本块的自定义消息、分支摘要或未知消息角色仍触发 `unsupported_context` 并交给 pi 默认压缩，避免静默遗漏内容。
+
+压缩摘要可以按真实记录 ID 搜索和读取，角色为 `summary`，属于派生历史而非用户原话。最近一次原生或其他扩展的压缩摘要会纳入下一次插件检查点输入，并遵守同一分批预算；插件自己的摘要通过笔记状态恢复，不重复包装。引用摘要的笔记标记为推断，摘要不能单独确认用户约束。来源 ID 校验只证明可追查，不证明笔记结论必然正确。
+
+压缩会把上述历史文本发送给当前配置的模型提供方，可能产生费用；分批会增加模型调用次数和耗时。成功检查点累计各批已返回的 usage；普通生成失败时，已返回 usage 累计写入诊断记录，默认压缩的 usage 由 pi 记录。取消操作沿用原有取消行为，不保证另存用量诊断；提供方未返回 usage 的请求也无法精确统计。
+
+分批支持归档历史总量超过模型窗口，但不保证任何超限任务都能恢复：笔记本身超出预算、需要保留的近期上下文仍过大、提供方故障或原生回退失败时，仍可能无法继续。分批是生成摘要的处理方式，不是持久化完整日记，也不保证模型总结无遗漏。
+
+## 故障恢复
+
+- `recall_budget`：先结束当前回复或压缩，再尝试较小页面。未知上下文用量时插件会暂停召回。
+- `stale_scope` / `source_not_found`：当前分支已改变或来源不可见，重新搜索当前历史。
+- `notes_budget`：警告及 `lastFailure.budget` 会给出具体原因、实际值和上限：`note_bytes`（笔记字节数）、`note_count`（笔记条数）或 `file_tracking`（文件列表字节数）。旧失败记录可能没有这些字段。可用现有稳定 key 简化重复笔记，保留有效约束；文件跟踪列表也受完整检查点预算限制，不能靠删减必要文件记录绕过。标记 resolved 本身不会移除笔记或释放空间。诊断只记录数值，不保存失败模型输出或笔记正文。
+- `checkpoint_input_budget`：笔记、自定义压缩指令和来源元数据挤满单批输入空间；减少过长的自定义压缩指令，或使用更大窗口模型。
+- `checkpoint_timeout`：本次生成的时间预算已耗尽。0.5.3 起四条路径统一最多 300 秒；多批共享预算，超时不保存部分候选。状态记录中的内部超时也使用该代码，不再混成用户取消的 `aborted`。失败记录中的未知用量不能据此推断零费用；延长预算不能保证模型最终返回成功。
+- `checkpoint_batch_limit`：本次归档历史超过 16 批，已回退原生压缩，没有保存部分检查点；不要反复重试相同输入，可使用更大窗口模型。
+- 笔记生成失败：显示警告后回退 pi 默认压缩。用户取消或生成期间切换分支时取消本次压缩。
+- `storage_failed` / `Memory: reopen session`：停止使用当前内存会话，**重新打开磁盘中保存的会话**。pi 可能先修改内存再写盘，不能视为已回滚；单独 `/reload` 不足以修复内存与磁盘不一致。检查磁盘空间、路径和写入权限后再继续。
+
+## 验证与限制
+
+```powershell
+npm run check
+npm test
+npm pack --dry-run
+```
+
+离线测试使用真实 pi SDK、会话管理器、扩展加载器和 RPC CLI，以及本地零费率测试模型。覆盖带来源工具循环、10 条约束经连续 3 次压缩和磁盘恢复、fork/tree/reload、分支隔离、Unicode 分页、共享预算、取消、无效生成、写盘失败、split turn 和文件跟踪。真实 TUI 已检查加载、状态、笔记、错误提示和离线回复。
+
+回归测试还覆盖纯文本扩展消息的检查点输入、重复压缩、来源回查、磁盘恢复和分支隔离，以及含非文本块消息的原生回退。另已验证与本机 pi-lens 3.8.74 同时加载、注册事件无错误；该检查没有运行 pi-lens 的完整会话初始化、诊断或缓存流程。
+
+0.3.0 的交接测试使用真实 AgentSessionRuntime，覆盖持久化新会话、接手输入、重启不重复注入、父分支冻结、隐藏来源排除、跨会话绑定、源文件修改/缺失、预算上限、取消和初始化失败恢复。交接功能尚未进行真实 TUI 或真实模型验收。
+
+0.4.0 另覆盖真实运行时自动派发、完整工具循环结束后切换、用量未知/关闭、增长预测、失败重载暂停、用户输入/取消/压缩抢占、冷却与次数、手动交接继承开关和接手启动失败暂停。测试用量和故障为离线夹具，未操作用户真实会话。
+
+0.5.0 全套 98 项离线测试通过，包含连续三次交接并重开、来源核验、日志成本去重、失败恢复/超时/工具耗时口径、日志故障与轮转，以及真实 UI 绑定/RPC 面板输出。另用一个伴随扩展验证 widget/status 互不覆盖；这不等于所有第三方插件的长期兼容验收。面板真实 TUI 视觉效果和真实模型长任务效果仍待实测。
+
+0.5.1 增加关闭后恢复、冷却/未知用量间隔、后台提交后自动刷新、失效快照重试与关闭竞争、主日志缺失和触发字段白名单回归。完整测试 105/105 通过；审查补充显式打开/关闭竞态修复后，类型检查及诊断/RPC 定向复验 16/16 通过（当前共 106 项）。连续三次交接及重开还断言固定样例中的目标、约束、待审批事项和未完成工作保持原文及 active 状态；这验证传递与持久化链路，不等于真实模型总结保真评估。
+
+这些验证证明接口与状态行为，不证明真实模型的笔记质量、正确率提升或 token/费用节省。尚未进行真实模型 A/B 基准、WebUI 实际渲染验收或 pi-lens 完整协作及缓存表现测试。本包不注册 `context` 消息改写 hook；其他接管压缩的扩展仍可能发生功能冲突。