pi-cache-optimizer 2.1.0 → 2.1.1

package/README.md

@@ -65,7 +65,15 @@ Generic OpenAI-compatible proxies are **not** treated as OpenAI-family just beca
 pi install npm:pi-cache-optimizer
 ```
 
-After installation, `PI_CACHE_RETENTION=long` is applied automatically, the system prompt is reordered automatically, `~/.pi/agent/models.json` is auto-seeded with a DeepSeek block when no DeepSeek-like model is configured, and the footer shows cache stats after supported model-family responses with exposed usage.
+After installation, `PI_CACHE_RETENTION=long` is applied automatically, the system prompt is reordered and skills are compressed automatically, session-overview churn is stripped automatically, `~/.pi/agent/models.json` is auto-seeded with a DeepSeek block when no DeepSeek-like model is configured, and the footer shows cache stats after supported model-family responses with exposed usage.
+
+## Opt-out
+
+| Env var | Effect |
+|---------|--------|
+| `PI_CACHE_OPTIMIZER_NO_AUTO_CONFIG=1` | Skip DeepSeek `models.json` auto-seed |
+| `PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1` | Keep pi's verbose `<available_skills>` XML (opt out of one-line index) |
+| `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=1` | Add `prompt_cache_key` to OpenAI-family requests (opt-in) |
 
 ## Uninstall
 

package/README.zh-CN.md

@@ -23,6 +23,9 @@
 | 功能 | 方式 | 是否需要手动操作 |
 |------|------|:---:|
 | 🔄 重组 system prompt | `before_agent_start` 钩子 — 稳定前缀在前、动态上下文在后 | ❌ 自动 |
+| 🗜️ 压缩 Skills XML | 将 pi 的每 skill 四行 XML 替换为按 skills-root 分组的紧凑单行索引（大小缩减约 93%） | ❌ 自动 |
+| 🧹 剥离 session-overview 动态尾字段 | 从 `<session-overview>` 中移除 `RECENT COMMITS`、`Working directory`、`Line count`——这些字段每轮都在变，破坏前缀缓存 | ❌ 自动 |
+| 🛡️ 完整性 guard | 检测 prompt 重排是否意外截断了 trellis 结构标记；如发生则回退到原始 prompt 并在 footer 显示 `⚠️ integrity` | ❌ 自动 |
 | ⏳ 长缓存保留 | 扩展加载时设置 `PI_CACHE_RETENTION=long`；Pi/provider compat 决定实际发送内容 | ❌ 自动 |
 | 🔗 保守 compat 提醒 | DeepSeek session-affinity 提醒，以及 Claude 兼容 endpoint 的明显 cache-control 提醒 | ⚠️ 见下 |
 | 📊 Provider-specific 底部统计 | 在 Pi footer/status 中显示受支持 provider family 的只读缓存统计 | ❌ 自动 |
@@ -65,7 +68,15 @@ Generic OpenAI-compatible 代理**不会**仅因为使用 OpenAI 形状 API 或
 pi install npm:pi-cache-optimizer
 ```
 
-安装后 `PI_CACHE_RETENTION=long` **自动生效**，system prompt **自动重组**；如果 `~/.pi/agent/models.json` 还没有 DeepSeek-like 模型，会自动 seed 一个 `deepseek` provider 块；受支持 model family 的响应完成且暴露 usage 后，底部状态栏会显示缓存统计。
+安装后 `PI_CACHE_RETENTION=long` **自动生效**，system prompt **自动重组**、skills 自动压缩、session-overview 动态尾字段自动剥离；如果 `~/.pi/agent/models.json` 还没有 DeepSeek-like 模型，会自动 seed 一个 `deepseek` provider 块；受支持 model family 的响应完成且暴露 usage 后，底部状态栏会显示缓存统计。
+
+## 退出（Opt-out）
+
+| 环境变量 | 作用 |
+|---------|------|
+| `PI_CACHE_OPTIMIZER_NO_AUTO_CONFIG=1` | 跳过 `models.json` DeepSeek 自动写入 |
+| `PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1` | 保留 pi 的 verbose `<available_skills>` XML（退出一行索引模式） |
+| `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=1` | 对 OpenAI-family 请求添加 `prompt_cache_key`（需主动启用） |
 
 ## 卸载
 
@@ -196,7 +207,8 @@ Pi 本身还会根据模型 compat 和 `PI_CACHE_RETENTION` 决定是否发送
 
 本包现在有 provider-family stats adapter，但仍避免盲目泛化：
 
-- DeepSeek cache 是自动的 prefix/KV cache。命中是 best-effort，代理可能隐藏 DeepSeek usage 字段。
+- DeepSeek cache 是自动的 prefix/KV cache。命中是 best-effort，代理可能隐藏 DeepSeek usage 字段。DeepSeek 的 Anthropic API 兼容层**明确忽略 `cache_control` markers**（对所有 content 类型均忽略）——像 Claude Code 那样用显式缓存断点对 DeepSeek 无效。
+- **Kiro / kiro-api**：`pi-provider-kiro` 扩展使用 AWS CodeWhisperer / Q Developer 流式协议（不是 Anthropic Messages / OpenAI Chat Completions / Bedrock Converse）。该协议没有 `cache_control` marker 的注入位置，也不返回 `cache_read_input_tokens`。对 Kiro Claude 模型，底部会显示 **0%**——这是 `pi-provider-kiro` 的限制，不是本扩展的 bug。不要强行用特殊逻辑 bump 这些数字。
 - OpenAI-family prompt caching 只有在真实上游支持且 prompt 足够长时才会自动生效。adapter 基于模型名称且刻意保守；不会用 provider/API/base URL metadata 推断官方 OpenAI 支持。
 - Claude prompt caching 依赖显式 Anthropic cache-control breakpoints。本版本只报告 Pi/provider 暴露的统计；不会插入 breakpoint，也不会修改请求体。
 - Gemini/Vertex 可能暴露 implicit cached-content token count。本版本不会创建、保存、更新或删除 explicit Gemini cached-content resources。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Pi extension that improves provider-side KV/prompt cache hit rates (DeepSeek, OpenAI, Claude, Gemini) by reordering the system prompt, requesting long retention, and showing footer cache stats. Renamed from pi-deepseek-cache-optimizer.",
   "keywords": [
     "pi-package",