@foolsecret/pi-prompt 0.4.0 → 0.4.9

package/CHANGELOG.md

@@ -4,6 +4,209 @@
 格式参考 Keep a Changelog；版本号遵循 semver，与 `package.json` 一致。
 变更类型：✨新增 / 🐛修复 / 🏗️重构 / 🧹清理 / 🎨样式 / 📄文档。
 
+## v0.4.9 (2026-09-13)
+
+**压缩指令可配置：引导摘要保留“工作状态”**
+
+- ✨ **新增 `compactInstructions`**（config + env `PI_PROMPT_COMPACT_INSTRUCTIONS`）：
+  传给 `ctx.compact({ customInstructions })`，引导 pi 的摘要保留
+  **当前任务 / 已完成到哪 / 下一步 / 阻塞**，避免压缩后丢失工作状态、
+  导致后续回合重新勘测与重复劳动。
+- 📄 **默认内置**（用户可覆盖）：
+  > 摘要时请额外保留：当前正在进行的任务、已完成到哪一步、下一步计划、未解决的阻塞。
+  > 不要只总结历史对话，要保留工作状态。
+
+  显式空串（配置或 env）= 不追加，回到 pi 原生行为。
+- ✨ **设置抽屉**：“上下文”组新增“压缩指令（保留工作状态）”行，
+  submenu 选预设档（内置默认 / 关闭）；自定义文案请改配置文件（长文本无自由输入）。
+- 📄 **勘误**：pi-prompt 本身**不生成**压缩提示词（那是 pi 宿主的），
+  只提供向 `compact()` 追加的**自定义指令**。三轴注入与此无关，一直正常工作。
+- 🧹 测试 93 → **96 全绿**（含“压缩确实带上 customInstructions”端到端）；`tsc` 0 错误。
+
+## v0.4.8 (2026-09-13)
+
+**设置抽屉改为“草稿 + Ctrl+S” + 轴重命名 + Markdown 只读页 + 删除无参 toggle**
+
+- ✨ **设置抽屉改为草稿保存模型**（对齐 pi-pricer）：抽屉内编辑只改内存草稿，
+  状态栏常驻 `● 未保存改动（面）`；**Ctrl+S** 落盘后转 `✓ 已保存`，**Ctrl+R** 丢弃。
+  根层 Esc 且有未保存改动时**拦截退出**（首次提示、二次才放弃）。
+  - 新增 `src/draft.ts`（纯逻辑）：`save()` 会**同时写配置与会话三轴**——
+    否则“未保存”语义是假的（轴改了却不落）。
+  - 键盘拦截用 `matchesKey` 而非裸字节：pi-tui 在增强键盘协议下把 Ctrl+S
+    编码为 CSI-u / modifyOtherKeys，裸比较 `\x13` 永远不命中（保存静默失效）。
+- ✨ **轴重命名**（英文键不变，配置文件兼容）：`show→风格`、`write→代码`、`do→行动`。
+  理由：原中文名“输出风格/代码量/行为力度”不齐整，且“工具”已被分类名占用。
+- ✨ **新增 `src/info-page.ts`**（移植自 pi-pricer）：Markdown + 固定 16 行窗口 +
+  ↑↓/PgUp/PgDn 滚动 + Esc 返回。`/prompt status`、`usage`、`check` 改用它（TUI），
+  无 TUI 回退纯文本 notify。
+- 🐛 **`###` 显示为字面量的根因**：pi-tui 的 Markdown 只对 **h1/h2** 去前缀
+  （`markdown.js:350` 对 `depth>=3` 保留了 `### ` 字面量）。故本项目的 markdown
+  **只用 `#` 与 `##`，禁用 `###`**（已加回归测试锁死）。
+- 🗑️ **删除 `/prompt` 无参的 toggle**：v0.1/v0.2 遗留，与抽屉重复且易误触
+  （会一键把三轴全置 normal）。现在无参 = **显示帮助**。
+- 🧹 测试 83 → **85 全绿**（新增 InfoPage 契约 + 草稿态/Ctrl+S 端到端）；`tsc` 0 错误。
+
+## v0.4.7 (2026-09-13)
+
+**修复设置抽屉：改值后不刷新、无保存提示、toolOutput 开关写错字段**
+
+- 🐛 **改值后根层摘要不刷新**（核心）：`buildRootItems`/`buildGroupItems` 都是
+  **构造时快照**，`SettingsList.items` 也冻结。旧实现下改值后返回根层，摘要仍显示旧值，
+  而重新进入子层却是新值（因为 `submenu` 每次都重建）——即用户看到的
+  “返回上一层和进入后完全不一样”。修：变更后**重建当前层与根层列表**，
+  并用 `selectItem(id)` 把光标放回刚改的行。
+- 🐛 **无保存提示**：抽屉内没有任何状态/提示行，且 `ctx.ui.notify` 在浮层
+  （`ui.custom`）打开时会被遮挡。修：新增**状态栏**（对齐 pi-pricer 形，语义相反），
+  固定显示 `✓ 已自动保存（无需 Ctrl+S）  Enter 修改 · Esc 返回`。
+- 🐛 **toolOutput 开关写错字段**：`flag-toolOutput` 走了顶层 `writeFlag`，但它是
+  嵌套配置 `toolOutput.enabled`。修：单独路由到 `writeToolOutput({ enabled })`。
+- ✨ 回调签名改为返回 `boolean`（写盘成败），状态栏据此显示“已保存/写入失败”。
+- 📄 明确**不提供 Ctrl+S**：pi-prompt 是**即改即存**（与 pi-pricer 的草稿+保存
+  语义不同），提示 Ctrl+S 会暗示“有未保存改动”而与实现矛盾。
+- 🧹 测试 82 → **83 全绿**（新增“状态栏 + 根层摘要刷新”端到端用例）；`tsc` 0 错误。
+
+## v0.4.6 (2026-09-13)
+
+**设置抽屉全量配置项 + 分类钻取（对齐 pi-pricer）+ 修复配置读档丢字段**
+
+- 🐛 **修复（重要）**：`config.load()` 只白名单了 6 个字段，导致
+  `peakUpgrade` / `maxTokensCap` / `autoSample*` / `hysteresis` / `autoCompact*` /
+  `toolOutput` 从配置文件写入后**重读会被静默丢弃**（之前只有 env 与内存注入生效）。
+  改为 `{...parsed}` 全量保留。
+- ✨ **设置抽屉覆盖全部配置项**（之前仅 6 行三轴）：新增开关 5 项、数值 7 项、
+  工具上限 4 项，共 20+ 行。
+- ✨ **分类钻取**（对齐 pi-pricer 的 submenu 范式）：根层 4 分类
+  （**提示词 / 工具 / 上下文 / 其他**）→ Enter 钻入子层 → Esc 逐级返回，
+  面包屑标题 `pi-prompt 设置 · 工具`；根层行显示分类摘要（如 `show=auto`）。
+- ✨ **数值行用预设档子菜单**（`SettingItem` 无自由文本输入）：
+  如 hysteresis `0/0.25/0.5/1`、压缩上限 `100K/200K/400K/800K`。
+- ✨ config 新增类型化写入 `writeFlag` / `writeNumber` / `writeToolOutput`
+  （均走 `persist()` 合并写，不丢未展示字段）。
+- 📄 `DESIGN.md` 同步：front matter 加 `levels` token，正文改为四分类钻取契约。
+- 🧹 测试 76 → **82 全绿**；`tsc --noEmit` 0 错误。
+
+## v0.4.5 (2026-09-13)
+
+**工具输出截断（默认关、按工具分层、缓存友好）**
+
+- ✨ **新增工具输出截断**（config `toolOutput.enabled`，**默认关**）：
+  - 背景：实测工具输出占上下文 **27~65%**（大会话），是输入成本的隐性大项。
+  - pi 自己已把工具输出截到 **50KB**（read/grep/bash/find 全覆盖），但 50KB
+    之上仍有冗余（实测 grep 均 13.6KB、read p95 9.5KB）。
+  - ✨ **按工具分层**（对齐 Reasonix per-tool 思路）：grep 8K / bash 8K /
+    read 16K / 兵底 8K。read 高的原因：模型主动要看，砍很会引发重读。
+  - ✨ **在 `tool_result` hook 创建时截断一次**（此后字节不变 → **缓存友好**）；
+    未超限**原样返回**（零影响）；错误结果不截；图片不截。
+- 📄 **为何默认关**：改工具输出会改变模型看到的内容（行为风险），由用户显式开。
+- 📀 **勘测结论（认知 #48~#50）**：pi 已有 50KB；**只看单一模型会误判 11 倍**
+  （v4-pro/glm 的 hit 是 flash 的 7.5~11.5 倍）；Reasonix 的“32KB”是触发
+  阀值，实际净保留仅 11~16KB，照搬数字无效。
+- 🧹 测试 68 → **76 全绿**；`tsc --noEmit` 0 错误。
+
+## v0.4.4 (2026-09-12)
+
+**自动上下文压缩（默认关）+ 勘测：1M 窗口下 pi 自带压缩形同虚设**
+
+- ✨ **新增自动上下文压缩**（config `autoCompact`，**默认关**）：
+  - 背景：pi 自带压缩阈值为 `contextWindow − 16384`。本用户的
+    deepseek-v4-pro / glm-5.3-flash 窗口均为 **1,000,000** → 阈值 **983,616**，
+    正常使用下**永远不会触发**（实测长会话上下文涨到 33 万仍在涨）。
+  - ✨ **三重触发条件**（非单一阈值）：① 绝对上限 `min(autoCompactMaxTokens,
+    percent×窗口)`；② 会话已跑 ≥ `minTurns` 轮；③ **成本划算**（用真实价表算）。
+  - 📄 **为何默认关**：压缩是“投资”——不压只付缓存读价（hit），
+    压缩需整段重算（miss−hit 价差）。DeepSeek hit=0.02 极便宜，
+    平衡点分析显示**剩 ≤30 轮时压缩永远亏**；仅长会话（≥100 轮、上下文 ≥4 万）
+    才值。GLM（hit=0.23）则明显划算。
+  - 新增 `src/context.ts`（纯函数：`decideCompact` / `compactionSaving`）；
+    config/env：`autoCompact` / `autoCompactMaxTokens`(40万) /
+    `autoCompactPercent`(0.6) / `autoCompactMinTurns`(50)。
+  - `/prompt check` 显示上下文用量、触发阈值、pi 阈值、本会话压缩次数。
+- 🧹 测试 63 → **68 全绿**；`tsc --noEmit` 0 错误。
+
+
+## v0.4.3 (2026-09-12)
+
+**台账加版本标记（v/pv）+ 版本考古：修正一个错误的分析结论**
+
+- ✨ **台账新增 `v`（schema 版本）与 `pv`（插件版本）字段**（只增不改）：
+  历史记录读取时补 `v=0` / `pv=legacy`（不写回文件）。目的：解决"台账跨版本
+  累积导致无法按版本归类"的问题——这是分析准确性所需的事实标记。
+- 📄 **版本考古结论（重要修正）**：台账 1306 条**全部是 `pv=legacy`**
+  （来自 v0.1/v0.2，无版本标记），**v0.4.1+ 干净样本 = 0 条**。
+  因此之前对比面板给出的 **-19.7% 实测缩减率作废**——它是
+  "跨版本混淆 + 选择偏差"的双重假象：
+  - v0.1 无 auto、v0.2 无迟滞（振荡 bug），行为不兼容；
+  - auto 选档非随机：`normal` 组 259/284 是冷缓存（会话早期），
+    `ultra` 组 870/930 是热缓存（会话中段），组间不同质。
+- 📄 **诚实结论**：当前台账**无法回答"auto 省没省"**；需受控 A/B
+  （`autoSample` 的用途，目前默认关）。`/prompt compare` 实测列已加
+  非因果免责声明。
+- 🧹 新增 `scripts/usage-filter.mjs`（版本过滤）与 `scripts/analyze-versions.mjs`
+  （版本考古 + 分层对比）。
+- 🧹 测试 61 → **63 全绿**；`tsc --noEmit` 0 错误。
+
+
+## v0.4.2 (2026-09-12)
+
+**footer 显示修正 + /prompt compare 对比面板**
+
+- 🐛 **修 footer 显示歧义（用户报障）**：切换 show=auto 后 footer 只显示解析后的档位
+  （如 `normal`），看起来像 auto 设置丢了。现改为 `auto→normal`，
+  让"设置是 auto、本轮解析成 normal"一目了然。纯显示改动，不动注入字节。
+  （根因：非 pi-usager 问题，pi-usager 只是原样转发 pi-prompt 的 status。
+  参见 AGENTS.md 认知修正 #39。）
+- ✨ **新增 `/prompt compare` 对比面板**：对比"注入 vs 不注入"的成本，
+  **双轨展示、分别标注口径**：
+  - **估算**：从台账反推"若无注入"会怎样（依赖 `REDUCTION_BY_SHOW` 先验）——
+    标注"基于先验缩减率，非实测"。
+  - **实测**：用 show=normal（不注入）样本做对照（≥5 样本才展示）——
+    标注样本偏差（normal 样本多来自小任务，非随机）。
+  - 样本不足时提示跑 `/prompt check --calibrate` 采集对照组。
+- ✨ 新增 `src/compare.ts`（纯函数层：`compareInjection` / `renderCompare`），
+  不依赖 TUI，node 单测直接断言。
+- 📄 **实数据发现**：本机台账实测缩减率为 **-19.7%**（注入组中位输出反而更高），
+  而估算声称省 ¥6.33——正是样本偏差所致。这就是面板必须双轨标注的原因：
+  单看估算会误以为"肯定省了钱"。
+- 🧹 测试 54 → **61 全绿**；`tsc --noEmit` 0 错误。
+
+
+## v0.4.1 (2026-09-12)
+
+**缓存命中优化：auto 换档迟滞 + 三轴独立注入块（对齐 Reasonix 的 cache-first 纪律）**
+
+- ✨ **auto 换档迟滞（核心）**：auto 选档从"无状态 argmax"改为"带记忆的迟滞"——
+  新最优档的净收益必须扣除**换档的缓存失效成本**后仍更优，才允许换档；否则维持
+  上一轮档位。换档失效成本按 `上一轮 prompt token × (miss−hit) 价差` 估算：
+  **会话越长/前缀越大，换档门槛越高**。
+- ✨ **三轴独立注入块**：注入文案从单串 `[PI-PROMPT show|write|do]` 改为三块
+  `[PI-PROMPT:SHOW <mode>]` / `[PI-PROMPT:WRITE <mode>]` / `[PI-PROMPT:DO <mode>]`，
+  每块字节只随自己的档位变 —— 调 write/do 不再改变 show 块的字节。
+  新增 `PromptRegistry.composeBlock(axis, mode)` 供按轴拼接。
+- ✨ **迟滞可配置**：配置 `hysteresis`（默认 0.5）/ env `PI_PROMPT_HYSTERESIS`；
+  设为 0 即退回旧的无状态 argmax（向后兼容）。
+- ✨ **命中率与前缀可观测**：`/prompt usage` 增加缓存命中率列（按天×模型 +
+  会话累计）；`/prompt check` 增加**注入前缀哈希**（学 Reasonix 的 CaptureShape，
+  一眼看出前缀有没有变）与迟滞设置；启动时提示当前配置对缓存是否友好。
+- 📄 **实测依据（P0）**：本机台账 1055 条显示——输入占成本 75%，命中率已达 97.9%，
+  但输入成本中 miss 贡献约一半；12 次 auto 换档累计浪费 719K token（≈¥0.70，占总成本 8.3%），
+  且浪费与当时前缀大小成正比（23 万 token 前缀换一次 ≈¥0.22）。迟滞回放显示可将其全部压掉。
+- 📄 **勘测结论**：pi 宿主已原生实现 Reasonix 的"历史只追加不改写"（session-manager
+  的 append-only tree）、"单一改写点"（compaction，pi 的 cache-stats 已把非压缩造成
+  的 miss 单独记为 cache waste）、"大内容有界化"（bash 输出截断）。pi-prompt 的注入
+  位于系统提示**最尾部**（`before_agent_start` 返回的 systemPrompt 是最终完整串，
+  追加在其末尾），故只需保证注入字节恒定。
+- 🐛 **实跑验证发现并修复两个集成缺陷**（纯函数单测看不到）：
+  - **自振荡**：换档→缓存失效→cacheState 翻冷→又换回，闭环振荡。
+    修法：switchCost **不再依赖当轮 cached**（任何换档都让下回合失效）。
+  - **三块隔离被击穿**：`join("\n")` 让最后一块少一个换行，show 块字节
+    随其后有无 write/do 而变。修法：每块自带尾部换行 + 直接拼接。
+- 🧹 实跑验证（`scripts/verify-v041.mjs`，驱动真实扩展跑长会话）：
+  迟滞关闭 23 次换档 → 迟滞开启 **0 次**（hold 标记 12 次）；
+  show 块隔离成功；注入确认在 system prompt 末尾。
+- 🧹 测试 41 → **54 全绿**（+13：缓存不变量 4 + 迟滞 5 + 命中率/哈希 3 + 启动提示 1）；
+  `tsc --noEmit` 0 错误。
+
+
 ## v0.4.0 (2026-09-11)
 
 **价格来源交给用户：auto 选档与成本全面走 pi-pricer JSON 价表（价格不再写死）**

package/README.md

@@ -30,7 +30,11 @@
   `/prompt check --calibrate`（3 轮不注入的对照探针）。
 - **台账与自检**。`/prompt usage` 给你按天×模型聚合 + 会话明细的 token/金额表，
   并标注节省估算；`/prompt check` 看台账完整性、校准状态与当前价格来源。
-- **恒定注入语义**。注入文案按档位编号、字节稳定，不破坏 prompt 前缀缓存命中。
+- **对比面板**。`/prompt compare` 回答"插件到底省了多少"——分**估算**（基于先验缩减率）
+  与**实测**（不注入对照样本）两轨展示，各自标注口径，不让假设听起来像事实。
+- **恒定注入语义 + 换档迟滞**。注入文案按档位编号、字节稳定，且三轴各自成块
+  （调 write/do 不动 show 块字节）；auto 换档带**迟滞**——新档优势须扣掉"换档的
+  缓存失效成本"后仍更优才换，避免为省一点输出费而丢掉整段前缀缓存。
 
 ---
 
@@ -45,7 +49,8 @@ pi extension add @foolsecret/pi-pricer
 /price                      # 打开价格面板，改成你实际付费的价
 
 # 3. 打开三轴设置抽屉
-/prompt config              # 会话三轴 + 默认三轴，改完即生效
+/prompt config              # 设置抽屉（4 分类钻取；Ctrl+S 保存 · Ctrl+R 丢弃）
+/prompt                     # 显示帮助
 
 # 4. 看看花了多少、省了多少
 /prompt usage
@@ -58,9 +63,11 @@ pi extension add @foolsecret/pi-pricer
 | 命令 | 干嘛的 |
 |---|---|
 | `/prompt` | 无参 = 全局开关（关停/恢复注入） |
-| `/prompt config` | 三轴设置抽屉（会话档 + 默认档，改完即持久化） |
+| `/prompt config` | 设置抽屉：根层 4 分类（提示词/工具/上下文/其他）钻取；**Ctrl+S 保存 / Ctrl+R 丢弃**，未保存时显示 `● 未保存改动` |
+| `/prompt`（无参） | 显示帮助 |
 | `/prompt status` | 当前三轴状态 |
 | `/prompt usage` | token/金额台账（按天×模型 + 会话明细 + 节省估算） |
+| `/prompt compare` | 对比注入 vs 不注入的成本（估算 + 实测双轨） |
 | `/prompt check` | 自检：台账完整性 / 校准状态 / 价格来源；`--calibrate` 跑探针 |
 | `/prompt-review` | 调用 `prompt-review` 技能审计上一条回复的冗余 |
 
@@ -79,12 +86,43 @@ pi extension add @foolsecret/pi-pricer
   "defaultDo": "normal",
   "peakUpgrade": true,
   "maxTokensCap": null,
-  "autoSample": false
+  "autoSample": false,
+  "hysteresis": 0.5,
+  "autoCompact": false,
+  "autoCompactMaxTokens": 400000,
+  "autoCompactPercent": 0.6,
+  "autoCompactMinTurns": 50,
+  "compactInstructions": "摘要时请额外保留：当前正在进行的任务、已完成到哪一步、下一步计划、未解决的阻塞。不要只总结历史对话，要保留工作状态。",
+  "toolOutput": {
+    "enabled": false,
+    "grep": 8192,
+    "read": 16384,
+    "bash": 8192,
+    "default": 8192
+  }
 }
 ```
 
 环境变量（优先级高于配置）：`PI_PROMPT_SHOW` / `PI_PROMPT_WRITE` / `PI_PROMPT_DO` /
-`PI_PROMPT_PEAK` / `PI_PROMPT_MAX_TOKENS` / `PI_PROMPT_AUTO_SAMPLE`。
+`PI_PROMPT_PEAK` / `PI_PROMPT_MAX_TOKENS` / `PI_PROMPT_AUTO_SAMPLE` /
+`PI_PROMPT_HYSTERESIS` / `PI_PROMPT_AUTO_COMPACT` / `PI_PROMPT_AUTO_COMPACT_MAX_TOKENS` /
+`PI_PROMPT_AUTO_COMPACT_PERCENT` / `PI_PROMPT_AUTO_COMPACT_MIN_TURNS` /
+`PI_PROMPT_TOOL_OUTPUT` / `PI_PROMPT_TOOL_CAP_GREP` / `PI_PROMPT_TOOL_CAP_READ` /
+`PI_PROMPT_TOOL_CAP_BASH` / `PI_PROMPT_TOOL_CAP_DEFAULT` / `PI_PROMPT_COMPACT_INSTRUCTIONS`。
+
+以上配置项**均可在 `/prompt config` 抽屉里修改**（根层 4 分类钻取：
+提示词 / 工具 / 上下文 / 其他），无需手改 JSON。
+
+> **关于 `autoCompact`（默认关）**：pi 自带的压缩阈值是「窗口 − 16K」，在 1M 窗口
+> 模型上 ≈ 98 万，实际很难触发，上下文会一直涨。本插件可在**更早**触发压缩，
+> 但压缩本身有代价（整段重算一次），而缓存读很便宜——算下来只有**长会话**才划算，
+> 所以默认关闭，仅在「超阈值 + 会话已够长 + 成本确划算」三重条件同时满足时才会压。
+>
+> **关于 `toolOutput`（默认关）**：pi 已把工具输出截到 50KB；本项提供**更激进**的
+> 分层上限（grep/bash 8K、read 16K），在工具结果**创建时**截断一次（不改历史，
+> 缓存友好）。它能省的是**每轮重发的缓存读**：以你的真实模型单价（deepseek-v4-pro
+> hit=0.15、glm-5.3-flash hit=0.23）估算，8K 上限可省 **15~25%** 总成本；但会改变
+> 模型看到的内容，故默认关。
 
 历史数据兼容：旧档名 `off` 读取时自动归一为 `normal`，不影响既有台账。
 

package/package.json

@@ -1,57 +1,57 @@
 {
-	"name": "@foolsecret/pi-prompt",
-	"version": "0.4.0",
-	"description": "为 Pi Agent 打造的输出精简提示插件 — 多档力度压缩输出 token 省钱 | A prompt-verbosity plugin for Pi Agent — tiered output compression to save tokens & cost",
-	"keywords": [
-		"pi-package",
-		"pi-extension",
-		"prompt",
-		"verbosity",
-		"concise",
-		"token",
-		"savings"
-	],
-	"license": "AGPL-3.0-only",
-	"author": "Titor-Z",
-	"publishConfig": {
-		"access": "public"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Titor-Z/pi-prompt.git"
-	},
-	"files": [
-		"src/",
-		"extensions/",
-		"prompts/",
-		"README.md",
-		"CHANGELOG.md",
-		"LICENSE"
-	],
-	"scripts": {
-		"test": "node --test --test-force-exit test/*.test.mjs",
-		"typecheck": "tsc --noEmit",
-		"prepublishOnly": "npm run typecheck && npm test"
-	},
-	"pi": {
-		"extensions": [
-			"./extensions/index.ts"
-		]
-	},
-	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
-		"@foolsecret/pi-pricer": "^0.12.0"
-	},
-	"peerDependenciesMeta": {
-		"@foolsecret/pi-pricer": {
-			"optional": true
-		}
-	},
-	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "*",
-		"@types/node": "^22.20.2",
-		"jiti": "^2.4.2",
-		"typescript": "^7.0.2"
-	}
+  "name": "@foolsecret/pi-prompt",
+  "version": "0.4.9",
+  "description": "为 Pi Agent 打造的输出精简提示插件 — 多档力度压缩输出 token 省钱 | A prompt-verbosity plugin for Pi Agent — tiered output compression to save tokens & cost",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "prompt",
+    "verbosity",
+    "concise",
+    "token",
+    "savings"
+  ],
+  "license": "AGPL-3.0-only",
+  "author": "Titor-Z",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Titor-Z/pi-prompt.git"
+  },
+  "files": [
+    "src/",
+    "extensions/",
+    "prompts/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-force-exit test/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@foolsecret/pi-pricer": "^0.12.0"
+  },
+  "peerDependenciesMeta": {
+    "@foolsecret/pi-pricer": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^22.20.2",
+    "jiti": "^2.4.2",
+    "typescript": "^7.0.2"
+  }
 }

package/src/auto.ts

@@ -33,6 +33,12 @@ export interface TierMathInput {
 	injectionTokens: (mode: RuntimeShowMode) => number;
 	/** 同类样本量（平局阈值收缩依据） */
 	sampleCount: number;
+	/**
+	 * 换档的预期损失（¥）：使当轮前缀缓存失效、下轮重新计费的代价。
+	 * 缺省 0（向后兼容）。P0 实测：注入块位于系统提示尾，但仍是同一前缀的
+	 * 一部分 —— 换档会让整段 prompt 缓存失效，损失 ∝ 前缀大小 ×(miss−hit) 价差。
+	 */
+	switchCost?: number;
 }
 
 /** 平局阈值的基准比例（相对最优净收益）：净收益差距小于该比例视为"差不多" */
@@ -54,8 +60,29 @@ const CONSERVATISM: readonly RuntimeShowMode[] = ["normal", "lite", "full", "ult
  *   2. 取净收益最高的档；
  *   3. 在 {最优 × (1 − 平局比例)} 范围内选最保守的一档。
  * 注意平局阈值必须是相对比例（绝对 ¥ 在微元量级上会把一切判成平局）。
+ *
+ * 迟滞（v0.4.1，缓存优化）：传入 previous 上一轮实际档位 + hysteresis 迟滞比例后，
+ * 只有新最优档的净收益比"上一轮档位"高出 |bestNet|×hysteresis + switchCost 才换档；
+ * 否则维持 previous。理由（P0 实测）：注入块变动会让整段前缀缓存失效，
+ * 浪费与当时前缀大小成正比（23 万 token 前缀换一次 ≈ ¥0.22）。换档必须"值得"。
+ */
+export function chooseAuto(
+	input: TierMathInput,
+	previous?: RuntimeShowMode,
+	hysteresis: number = 0,
+): RuntimeShowMode {
+	return chooseAutoDetailed(input, previous, hysteresis).mode;
+}
+
+/**
+ * 选档 + 归因：mode 为最终档位；held 为 true 表示"迟滞压住了本次换档"
+ * （即无迟滞时本会切到 candidate，但被 previous 绊住）——用于台账决策标记。
  */
-export function chooseAuto(input: TierMathInput): RuntimeShowMode {
+export function chooseAutoDetailed(
+	input: TierMathInput,
+	previous?: RuntimeShowMode,
+	hysteresis: number = 0,
+): { mode: RuntimeShowMode; held: boolean } {
 	const priceIn = input.cached ? input.inputHitPrice : input.inputMissPrice;
 	const nets = new Map<RuntimeShowMode, number>();
 	let bestNet = Number.NEGATIVE_INFINITY;
@@ -68,11 +95,22 @@ export function chooseAuto(input: TierMathInput): RuntimeShowMode {
 		if (net > bestNet) bestNet = net;
 	}
 	const tie = Math.abs(bestNet) * tieFraction(input.sampleCount);
+	let candidate: RuntimeShowMode = "normal";
 	for (const mode of CONSERVATISM) {
 		// 升序遍历：第一个进入平局带的档 = 最保守的接近最优
-		if ((nets.get(mode) ?? Number.NEGATIVE_INFINITY) >= bestNet - tie) return mode;
+		if ((nets.get(mode) ?? Number.NEGATIVE_INFINITY) >= bestNet - tie) {
+			candidate = mode;
+			break;
+		}
 	}
-	return "normal";
+	if (previous === undefined || previous === candidate) return { mode: candidate, held: false };
+	// 迟滞：换档要扣掉"缓存失效损失"（switchCost，¥）后仍更优才换。
+	// 这是有原则的门槛（而非拍脑袋的固定比例）：会话越长/前缀越大，换档越贵。
+	const prevNet = nets.get(previous) ?? Number.NEGATIVE_INFINITY;
+	const switchCost = input.switchCost ?? 0;
+	const margin = Math.abs(bestNet) * hysteresis + switchCost;
+	if (bestNet - prevNet <= margin) return { mode: previous, held: true };
+	return { mode: candidate, held: false };
 }
 
 /** 请求规模 → 预期输出 µ 的粗糙分桶（先验；可被校准的 normal 基线中位数覆盖） */
@@ -118,6 +156,10 @@ export class AutoTierChooser {
 	 * 峰谷不再由调用方按硬编码时段推算，而是取价格源返回的 isPeak —— 这样用户在
 	 * pi-pricer 配置里改了峰时段，auto 立即跟随（兜底价格源才退回 DeepSeek 固定时段）。
 	 * peakUpgrade=false 时忽略 isPeak（关闭高峰升档，保持基线定价）。
+	 *
+	 * 迟滞（v0.4.1）：previous 为上一轮实际生效档位；hysteresis 为迟滞比例；
+	 * prevPromptTokens 为上一轮 prompt 总 token（用于估算换档的缓存失效成本）。
+	 * 默认缺省 → 退回无状态纯 argmax，与旧行为一致。
 	 */
 	choose(
 		provider: string,
@@ -127,20 +169,74 @@ export class AutoTierChooser {
 		cached: boolean,
 		ts: number,
 		peakUpgrade: boolean = true,
+		previous?: RuntimeShowMode,
+		hysteresis: number = 0,
+		prevPromptTokens: number = 0,
 	): RuntimeShowMode {
+		const prices = this.priceFor(provider, model, ts);
+		const sampleCount = this.sampleCountFor(provider, bin);
+		const peek = peakUpgrade && prices.isPeak === true;
+		const outputPrice = peek ? prices.output * 2 : prices.output;
+		// 换档代价：任何换档都会让注入块变→整段前缀缓存失效，下一回合重计费。
+		// **不依赖当前 cached 标志**：P0 实测发现"换档→缓存失效→cacheRead=0→
+		// cacheState 翻冷→又换回"的自振荡循环，根因就是只在本轮 cached 时
+		// 才算 switchCost。改为只要有前缀（prevPromptTokens>0）就计代价。
+		// hysteresis<=0 视为完全关闭（含 switchCost），保证向后兼容纯 argmax。
+		const switchCost = hysteresis > 0 ? (prevPromptTokens * (prices.miss - prices.hit)) / 1e6 : 0;
+		return chooseAuto(
+			{
+				estMu,
+				outputPrice,
+				inputMissPrice: prices.miss,
+				inputHitPrice: prices.hit,
+				cached,
+				reduction: (mode) => this.reductionFor(provider, bin, mode),
+				injectionTokens: (mode) => INJECTION_TOKENS_BY_SHOW[mode],
+				sampleCount,
+				switchCost,
+			},
+			previous,
+			hysteresis,
+		);
+	}
+
+	/**
+	 * 同 choose，但额外返回"迟滞是否压住了换档"（held）—— 供台账决策归因。
+	 * 与 choose 共用同一套数学，不重复实现。
+	 */
+	chooseDetailed(
+		provider: string,
+		model: string,
+		bin: TaskBin,
+		estMu: number,
+		cached: boolean,
+		ts: number,
+		peakUpgrade: boolean = true,
+		previous?: RuntimeShowMode,
+		hysteresis: number = 0,
+		prevPromptTokens: number = 0,
+	): { mode: RuntimeShowMode; held: boolean } {
 		const prices = this.priceFor(provider, model, ts);
 		const sampleCount = this.sampleCountFor(provider, bin);
 		const peak = peakUpgrade && prices.isPeak === true;
 		const outputPrice = peak ? prices.output * 2 : prices.output;
-		return chooseAuto({
-			estMu,
-			outputPrice,
-			inputMissPrice: prices.miss,
-			inputHitPrice: prices.hit,
-			cached,
-			reduction: (mode) => this.reductionFor(provider, bin, mode),
-			injectionTokens: (mode) => INJECTION_TOKENS_BY_SHOW[mode],
-			sampleCount,
-		});
+		// 与 choose 同源：任何换档都让前缀缓存失效，代价按前缀大小计（不依赖 cached）。
+		// hysteresis<=0 时归零（关闭迟滞即纯 argmax）。
+		const switchCost = hysteresis > 0 ? (prevPromptTokens * (prices.miss - prices.hit)) / 1e6 : 0;
+		return chooseAutoDetailed(
+			{
+				estMu,
+				outputPrice,
+				inputMissPrice: prices.miss,
+				inputHitPrice: prices.hit,
+				cached,
+				reduction: (mode) => this.reductionFor(provider, bin, mode),
+				injectionTokens: (mode) => INJECTION_TOKENS_BY_SHOW[mode],
+				sampleCount,
+				switchCost,
+			},
+			previous,
+			hysteresis,
+		);
 	}
 }

package/src/command.ts

@@ -6,6 +6,7 @@
  *   /prompt config            打开三轴设置抽屉（复刻 /settings：会话档 + 默认档）
  *   /prompt status            显示三轴现状与台账估算
  *   /prompt usage             显示 token/金额台账（DeepSeek 风格表）
+ *   /prompt compare           对比“注入 vs 不注入”的成本（估算 + 实测对照）
  *   /prompt check [--calibrate] 健康自检；--calibrate 才跑成对探针并重拟合
  *   其余输入一律判非法（提示用 /prompt config）。
  *   review 不再作为档位，请用 /prompt-review 技能
@@ -18,10 +19,11 @@ export type AxisName = "show" | "write" | "do";
 
 /** 解析结果的判别联合 */
 export type PromptCommand =
-	| { type: "toggle" }
+	| { type: "help" }
 	| { type: "config" }
 	| { type: "status" }
 	| { type: "usage" }
+	| { type: "compare" }
 	| { type: "check"; calibrate: boolean }
 	| { type: "invalid"; arg: string };
 
@@ -35,13 +37,19 @@ export function parsePromptCommand(args: string): PromptCommand {
 
 	switch (primary) {
 		case "":
-			return { type: "toggle" };
+			return { type: "help" };
+		case "help":
+			return { type: "help" };
+		case "toggle":
+			return { type: "invalid", arg: "toggle 已移除，请用 /prompt config 抽屉" };
 		case "config":
 			return { type: "config" };
 		case "status":
 			return { type: "status" };
 		case "usage":
 			return { type: "usage" };
+		case "compare":
+			return { type: "compare" };
 		case "check":
 			return { type: "check", calibrate: parts.includes("--calibrate") };
 		default: