pi-cache-optimizer 2.1.0 → 2.2.0

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/index.ts

@@ -51,11 +51,12 @@ const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
 const DEEPSEEK_API_KEY_ENV = "DEEPSEEK_API_KEY";
 
 // WORM-flag: if optimizeSystemPrompt ever detects that its blind-replace
-// logic has accidentally truncated the trellis `<workflow-state>` block
-// (or any structural marker from an upstream extension), we flip this.
-// publishStatus reads it once, appends a footer warning, then resets it.
-// The flag surface is kept separate from the regular cache-stats counter
-// so that a one-turn glitch doesn't poison the persisted metrics.
+// logic has accidentally truncated a structural marker (any XML tag or
+// HTML comment boundary marker present in the original prompt), we flip
+// this. publishStatus reads it once, appends a footer warning, then
+// resets it. The flag surface is kept separate from the regular
+// cache-stats counter so that a one-turn glitch doesn't poison the
+// persisted metrics.
 let promptTruncationDetected = false;
 
 // Minimum count of skills before compression is worth applying.
@@ -387,6 +388,62 @@ function stripSessionOverviewChurn(prompt: string): string {
   return before + cleaned + after;
 }
 
+/**
+ * Extract structural markers from a prompt for the integrity guard.
+ *
+ * The guard runs in `optimizeSystemPrompt` to catch cases where the
+ * blind `rest.replace(part, "")` reorder accidentally eats text inside
+ * an extension-injected structural block (e.g., trellis
+ * `<workflow-state>`, a hypothetical `<task-tracker>`, or AGENTS.md
+ * `<!-- TRELLIS:START -->` markers). When the original prompt contains
+ * a marker that the result is missing, we fall back to the original
+ * prompt rather than ship a corrupted one.
+ *
+ * Three marker categories are recognized (covers ~99% of real-world
+ * extension injection patterns in the pi ecosystem):
+ *
+ *   1. XML-style opening tags  `<tagname>` (lowercase, alpha-num + `_`/`-`)
+ *   2. XML-style closing tags  `</tagname>`
+ *   3. HTML comment START/END  `<!-- NAME:START -->` / `<!-- NAME:END -->`
+ *
+ * Tags with attributes (e.g., `<task id="42">`) are not currently emitted
+ * by any pi extension we know of and are skipped to keep the regex tight.
+ * Markdown headers, horizontal rules, and timestamp patterns are not
+ * usable as guards because they have no closing form to verify.
+ *
+ * The check is deliberately set-based (presence/absence) rather than
+ * count-based: a single occurrence per request is the universal
+ * convention, and a count drop with the same set of unique tags would
+ * be a different class of bug not catchable here.
+ */
+function extractStructuralMarkers(prompt: string): {
+  openingTags: Set<string>;
+  closingTags: Set<string>;
+  commentMarkers: Set<string>;
+} {
+  const openingTags = new Set<string>();
+  const closingTags = new Set<string>();
+  const commentMarkers = new Set<string>();
+
+  // Opening tags: <tagname> with no attributes and no leading slash.
+  // Tagname must start with a letter and contain only alpha-num, `-`, `_`.
+  for (const match of prompt.matchAll(/<([a-z][a-z0-9_-]*)>/gi)) {
+    openingTags.add(match[1].toLowerCase());
+  }
+  // Closing tags: </tagname>
+  for (const match of prompt.matchAll(/<\/([a-z][a-z0-9_-]*)>/gi)) {
+    closingTags.add(match[1].toLowerCase());
+  }
+  // HTML comments with NAME:START or NAME:END inside.
+  // Trellis emits `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` in
+  // the AGENTS.md managed block; other extensions follow this convention.
+  for (const match of prompt.matchAll(/<!--\s*([A-Z][A-Z0-9_-]*):(START|END)\s*-->/g)) {
+    commentMarkers.add(`${match[1]}:${match[2]}`);
+  }
+
+  return { openingTags, closingTags, commentMarkers };
+}
+
 function optimizeSystemPrompt(
   original: string,
   opts: BuildSystemPromptOptions,
@@ -420,17 +477,29 @@ function optimizeSystemPrompt(
     stablePrefix +
     (dynamicRemainder.length > 0 ? "\n\n---\n\n" + dynamicRemainder : "");
 
-  // Sanity check: if trellis (or another extension) injected structural
-  // markers into the prompt that happen to share a substring with one of
-  // our stable candidates, the blind `rest.replace(part, "")` could
-  // silently eat part of the dynamic layer. We anchor on
-  // `<workflow-state>` because it is the most stable structural marker
-  // trellis emits and is never a stable candidate itself.
+  // Sanity check: scan ALL structural markers (XML tags + HTML comment
+  // boundary markers) in the original and verify each one survives the
+  // reorder. If any marker drops, the blind `rest.replace(part, "")`
+  // logic ate something it shouldn't have — fall back to the original
+  // prompt and flag the footer warning. This is provider-agnostic and
+  // extension-agnostic: trellis `<workflow-state>`, a hypothetical
+  // `<task-tracker>`, AGENTS.md `<!-- TRELLIS:START -->`, etc., are all
+  // protected without code changes when new extensions ship.
   //
-  // When the marker was present in the original but is missing in the
-  // result, the reorder is unsafe — fall back to the original prompt
-  // so the model gets a complete prompt, and flag the footer warning.
-  if (original.includes("<workflow-state>") && !systemPrompt.includes("<workflow-state>")) {
+  // Our skills compression runs BEFORE optimizeSystemPrompt and replaces
+  // pi's verbose `<available_skills>` block with a compressed text
+  // section that has no XML tag. So `original` here (post-compression)
+  // does not contain `<available_skills>` and the result doesn't either
+  // — no false positive.
+  const originalMarkers = extractStructuralMarkers(original);
+  const resultMarkers = extractStructuralMarkers(systemPrompt);
+
+  const missing =
+    [...originalMarkers.openingTags].some((tag) => !resultMarkers.openingTags.has(tag)) ||
+    [...originalMarkers.closingTags].some((tag) => !resultMarkers.closingTags.has(tag)) ||
+    [...originalMarkers.commentMarkers].some((m) => !resultMarkers.commentMarkers.has(m));
+
+  if (missing) {
     promptTruncationDetected = true;
     return { systemPrompt: original, stablePrefix: "", changed: false };
   }
@@ -1240,6 +1309,7 @@ export const __internals_for_tests = {
   buildStableCandidates,
   optimizeSystemPrompt,
   stripSessionOverviewChurn,
+  extractStructuralMarkers,
   formatSkillsForPrompt,
   formatSkillsForPromptCompressed,
   compressSkillsInSystemPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "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",