# [Feature Request] 新增 `/acp compact` 命令，复用 `models.json` 实现协同压缩

[Juna9969]

1. 背景与动机 (Background & Motivation)

当前 billion-context-pi 的 compress 工具调用由主模型 (Main LLM) 自身完成。为了降低主模型的 Token 消耗和推理干扰，我们需要引入“独立压缩模型”机制。

痛点：如果让用户在 acp.json 中手动配置压缩模型的 baseUrl 和 apiKey，会造成严重的重复配置。
解决方案：直接复用 Pi Coding Agent 原生的模型配置文件 ~/.pi/agent/models.json。通过新增 /acp compact 命令，让用户一键将已配置的某个模型（如小参数量的 Qwen、GPT-4o-mini 等）指定为专属的“上下文压缩模型”。

2. 命令设计 (CLI Command Design)

在插件中注册 /acp compact 命令，行为定义如下：

• /acp compact (无参数)：显示当前配置的压缩模型状态。如果未配置，列出 ~/.pi/agent/models.json 中可用的模型 ID 供用户参考。
• /acp compact <model-id>：将 <model-id> 设置为当前会话/全局的压缩模型。
• /acp compact reset：清除配置，Fallback 回默认行为（由主模型执行压缩）。

状态持久化：
用户的选择应持久化到插件的状态中（例如写入 ~/.pi/acp.json 的 compressionModelId 字段），以便下次启动时自动生效。

3. 系统架构与协同流程 (Proposed Pipeline Flow)

AI 在修改代码时，请遵循以下协同 Pipeline：

1. Command Execution: 用户执行 /acp compact qwen-mini。插件验证 qwen-mini 存在于 models.json 中，并将 compressionModelId: "qwen-mini" 写入配置。
2. Context Event Trigger: 插件拦截 context 事件，决定需要压缩，主模型调用 compress 工具。
3. Interception & Routing (核心修改点):
   • 检查配置中是否存在 compressionModelId。
   • If Exists: 拦截工具调用。读取 ~/.pi/agent/models.json，提取该 model-id 对应的 provider, baseUrl, apiKey, model 等凭证。
   • Dynamic Client: 动态实例化一个 LLM Client（独立于主模型），并构建摘要专用的 System Prompt。
   • API Call: 将请求发送给该压缩模型。
4. Result Injection: 将压缩模型返回的摘要结果，作为 compress 工具的 toolResult 注入回会话历史中。
5. Fallback (If Not Exists / Error): 如果未配置，或动态调用的外部模型报错（网络超时、API 余额不足），必须捕获异常并 Fallback 到主模型，由主模型自己生成摘要，确保 Session 不中断。

4. 给 AI/开发者的实现建议 (Implementation Hints for AI)

为了实现此 Feature，建议 AI 代理/开发者重点关注以下模块的修改：

• [ ] 模型配置读取 (Models Config Parsing):
  需要读取 ~/.pi/agent/models.json。注意：请使用 os.homedir() 拼接路径（参考项目中已有的 src/user-config.ts 路径解析逻辑），确保跨平台（Windows/macOS/Linux）兼容。
• [ ] 命令注册 (Command Registration):
  在 src/commands.ts 中注册 /acp compact 命令，处理参数解析和状态更新，并向用户输出友好的 UI 反馈。
• [ ] 工具执行层 (src/compress-tool.ts):
  修改 handleCompress 逻辑。增加一层判断：如果存在 compressionModelId，则从内存中缓存的 models.json 数据里查找对应的 API 凭证，并发起独立的 HTTP 请求（或复用 Pi 内部的 LLM 调用接口，如果 Pi 暴露了相关 API 的话）。
• [ ] 降级与容错 (Fallback Mechanism - 极其重要):
  外部压缩模型的调用必须是 try...catch 包裹的。一旦失败，Log 记录警告，并立即将执行权交还给主模型（即执行原有的压缩逻辑）。

5. 验收标准 (Acceptance Criteria)

• 成功注册 /acp compact 命令，能正确读取并列出 models.json 中的模型。
• 执行 /acp compact <id> 后，触发 compress 工具时，主模型不再消耗 output tokens，而是由指定的模型完成摘要。
• 具备完善的 Fallback 机制：指定的压缩模型 API 报错时，能无缝降级为主模型压缩，不阻断主流程。
• 单元测试覆盖：Mock models.json 读取、Mock 外部模型 API 响应、验证 Fallback 逻辑。
• 更新 README.md 和 CONFIGURATION.md，说明如何使用 /acp compact 命令。

[Juna9969]

/acp compact不配置情况下（默认主模型）

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 确认一下「未配置」时的行为：

• /acp compact 未配置任何压缩模型（即 acp.json 里没有 compressionModelId 字段）时，compress 工具保持现有默认行为——由主模型自己生成摘要，和现在完全一致，不会发起任何外部 LLM 调用。
• 也就是说 compressionModelId 是可选字段：
  • 不存在 → 主模型压缩（默认，零额外开销）；
  • 存在且调用成功 → 由指定模型压缩，主模型不消耗 output tokens；
  • 存在但调用失败（网络超时 / API 报错 / 余额不足）→ catch 住异常，无缝 Fallback 回主模型，Session 不中断。
• /acp compact（无参数）会显示当前状态：未配置时提示「当前使用主模型压缩」，并列出 ~/.pi/agent/models.json 里可用的模型 ID 供参考。
• /acp compact reset 清除 compressionModelId，回到默认主模型行为。

我按这个语义实现。继续开发中，稍后贴 PR。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] /acp compact 功能已开发完成，分支已推送到 origin，可发起 PR。

实现内容

命令（src/commands.ts）

• /acp compact — 显示当前压缩模型状态；未配置时列出 ~/.pi/agent/models.json 中可用模型
• /acp compact <id> — 设置压缩模型（支持 <id> 或 <provider>/<id>），持久化到 ~/.pi/acp.json 的 compressionModelId
• /acp compact reset — 清除配置，回退到主模型

核心逻辑（src/compress-model.ts + src/compress-tool.ts）

• 新增 CompressionModelClient：用 getAgentDir() 拼接 models.json 路径（跨平台），解析 provider/baseUrl/apiKey，通过 ModelRuntime.complete() 调用独立压缩模型生成摘要
• handleCompress 增加路由：配置了 compressionModelId 时，把每个 range 的内容发给压缩模型生成摘要
• Fallback（关键）：外部调用全程 try/catch；模型无法解析 / 网络超时 / API 报错 / 空响应时，记录 warn 并立即回退到主模型自己的摘要，Session 不中断

测试（新增 18 个，全部通过）

• tests/compress-model.test.ts：Mock models.json 读取、Mock 外部模型 API（SSE）、resolve/summarize/截断/持久化
• tests/acp-compact.test.ts：/acp compact 列表/设置/未知/reset；compress 成功走独立模型 + 失败回退主模型
• 全量：446 通过 / 0 失败，typecheck 通过，build 成功

文档：README.md（/acp compact 章节）+ CONFIGURATION.md（compressionModelId 参考）

验收标准对照

• 注册 /acp compact，正确读取并列出 models.json 模型
• 设置后 compress 由指定模型完成摘要（见下方 token 说明）
• 完善 Fallback：API 报错时无缝降级主模型，不阻断主流程
• 单测覆盖：Mock models.json、Mock 外部 API、验证 Fallback
• 更新 README.md 和 CONFIGURATION.md

关于「主模型不再消耗 output tokens」的说明

acp-kernel 的 validateEntry 要求每个 range 的 summary 字段非空（空摘要会被丢弃）。因此主模型仍需先给出一个极简占位 summary（几个 token），配置了压缩模型时该 range 的摘要会被压缩模型的结果覆盖，主模型的摘要仅作为 Fallback 保留。这样主模型写摘要的开销从「完整详细摘要」降到「占位符」，实质性的摘要生成全部由压缩模型承担，同时保证 Fallback 无缝。若要做到主模型零输出，需要改 acp-kernel 允许空 summary（跨仓库改动，需先发布 acp-kernel）——如需我可以另开 issue 跟进。

分支 / PR

• 分支：feat/acp-compact-compression-model（已推送）
• 创建 PR：https://github.com/ranxianglei/billion-context-pi/pull/new/feat/acp-compact-compression-model
• 按 AGENTS.md 约定，PR 合并由人工执行（Agent 不合并）。

[ranxianglei]

#80
这个设计未必能达到预期。参考这个 issue

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 已读 #80，你的判断成立。重算 token 账后确认：/acp compact（独立压缩模型）单独用，达不到 #240 预期的 token 降幅。

关键：压缩的真实成本里，"写摘要的 output tokens" 只是小头。 每次压缩事件，主模型的实际开销有两块：

1. 决策：主模型分析上下文、选 range（input+output tokens）。独立模型不分担这块——主模型仍要调 compress 并给出 range。
2. Prompt Cache 失效（大头）：selective compression 在历史中间就地改写，把压缩点之后的整个后缀踢出缓存前缀，后续每轮都按全价重算这段 input。换谁写摘要都不影响——改写历史的动作照旧，缓存照样失效。

我的实现只把「写完整摘要」换成「写占位符」，省的是第 1 点里摘要 output 那一小截；决策 input 和缓存失效都没动。所以它确实能缓解「推理干扰」（主模型不用逐字写摘要了），但对「Token 消耗」帮助有限——因为大头是缓存失效，不是摘要 output。

#80 第 2 点（保护 Prompt Cache）才是主杠杆：阶段内 model-visible history 尽量 append-only、可删 tool output 标 pending drop、到压力高/阶段结束再一次性批量压缩、检索结果追加到尾部。把「频繁就地压缩」变成「偶发批量 rollover」，缓存失效次数大幅下降。独立压缩模型在这个框架里退居次要优化（批量 rollover 时把摘要甩给便宜模型）。

下一步请你定方向：

• A：# [Feature Request] 新增 /acp compact 命令，复用 models.json 实现协同压缩 #240 收窄为「独立压缩模型」独立小优化（可先合并），另开 issue 做「Prompt Cache 稳定性 / 批量 rollover」（主杠杆）。
• B：暂停 # [Feature Request] 新增 /acp compact 命令，复用 models.json 实现协同压缩 #240，重新设计成「批量 rollover + 独立压缩模型」整体方案再动手。

我倾向 A（两者正交，独立压缩模型先落地，缓存稳定性单独立项）。

一个机制细节想先跟你对齐：「pending drop」如果指立即从 prompt 隐藏，那本身就会改前缀、触发缓存失效，与目标矛盾；所以更可能是延迟到 rollover 才真正移除（阶段内先留着、占一点 context，换取缓存稳定）。这个 trade-off 我想确认你的预期再动手。

[ranxianglei]

先拆分出一个独立模型支持压缩 不过尽量复用同一个 session 保证独立模型尽量 prefix cache

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 收到，方向明确：先做独立压缩（独立调用），并尽量复用同一个 session 让独立调用吃到 prefix cache。

我的理解（请纠正）：

• "独立" = 独立调用——把压缩推理隔离出去，不污染主模型上下文、不干扰主模型推理，而不是必须换一个更便宜的模型。
• 复用同一个 session = 独立调用用同一个模型 + 共享主 session 的 prompt 前缀，这样这次调用的 input 大部分命中缓存，既隔离又便宜。

一个绕不开的 trade-off： prefix cache 按「模型」隔离命名空间——

• 用同一个模型 → 前缀能命中缓存（input 便宜）；
• 换成更便宜的模型（models.json）→ 不同模型 cache 不共享，前缀 miss，input 按全价。

所以「吃 cache」和「用便宜模型」基本二选一。我倾向：独立调用默认复用 session 模型 + 共享前缀（主路径：隔离 + cache 便宜），/acp compact <id> 作为可选指定更便宜模型（文档注明会失去 cache 共享）。

动手前想确认两点：

1. 默认行为：未 /acp compact 时，是保持现状（主模型自己写摘要），还是也让压缩走「同模型独立调用 + 共享前缀」？即独立调用是 opt-in，还是直接成为压缩的默认路径？
2. prefix 共享的实现深度：独立调用的 prompt 前缀要和主 session 逐 token 一致才命中缓存（[主 system prompt] + [历史到压缩点] + [同 tools]，末尾追加"总结 range X..Y"指令）。你希望我尽量复刻 Pi 的主 prompt 构造（命中率最高但脆弱），还是先做简化版（复用 system prompt + 历史，tools 能对齐就对齐，best-effort 命中）？

我的倾向：独立调用（同模型 + 共享前缀）作为压缩默认路径，/acp compact <id> 可选覆盖为更便宜模型；prefix 先做简化版跑通隔离 + 部分 cache，再逐步提命中率。等你拍板。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 好，按 A 走：#240 保持「独立压缩模型」独立优化（可合并）；「Prompt Cache 稳定性 / 批量 rollover」是主杠杆——我这边没有建 issue 的权限，稍后把 issue 草稿贴出来，你或维护者建一下。

按 m00179「复用同一个 session」细化，两个待定点我先按如下推进（不对就喊停）：

1. 默认行为：保持 opt-in（未 /acp compact = 主模型自写摘要，不变）。启用后：
   • /acp compact session → 用 session 模型（同模型 + 共享前缀：吃 cache + 隔离压缩推理）；
   • /acp compact <id> → 用 models.json 里的模型（更便宜，但不同模型 cache 不共享）；
   • /acp compact reset → 回主模型自写。
2. prefix 共享：best-effort——独立调用尽量复用 session 的 system prompt + 历史前缀，能否逐 token 命中取决于能否对齐 Pi 主 prompt 的序列化，先跑通「隔离 + 部分 cache」，命中率后续再调。

核心语义我理解为：「独立」= 独立调用（隔离压缩推理，不污染主上下文）；「复用 session」= 同模型 + 共享前缀（cache 便宜）。我先探一下 Pi 侧怎么拿到 session 的 prompt/messages 来做前缀复用，然后动手改，改完贴更新。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 按 A 走，session 模式已实现并推送（分支 feat/acp-compact-compression-model，新增 commit c5e7de8）。

本次实现（session 共享前缀）：

• /acp compact session：用 session 自己的模型，在独立调用里复用 session 的 prompt 前缀（system prompt + active tools + Pi 刚发送的那批 transformed messages），末尾只追加一条"总结 range X..Y"的指令。前缀和主模型上一轮发的完全一致 → 命中 provider prompt cache，input 便宜；压缩推理也隔离在主模型上下文之外。
• 前缀来源：context 事件里捕获 billion-context 变换后的 rebuilt messages（不是原始重建，保证和 Pi 实际发送的逐 token 一致）。
• /acp compact <id>（models.json 模型）保留为另一条路径：更便宜但不同 cache 命名空间、不共享前缀。
• 未捕获到前缀（首轮）→ 退化为 fresh prompt（带 range 内容）；任何失败 → Fallback 主模型摘要，Session 不中断。
• 测试：4 个新 session 用例（set / status / 共享前缀成功且验证请求体含前缀 / Fallback）。全量 450 pass，typecheck + build 通过。

PR（人工合并）： https://github.com/ranxianglei/billion-context-pi/pull/new/feat/acp-compact-compression-model

---

另开的 follow-up issue 草稿（主杠杆：Prompt Cache 稳定性 / 批量 rollover），你过目后我可以直接建（或你建）：

标题：[Feature Request] Prompt Cache 稳定性 / 批量 rollover 压缩（主杠杆）

背景：#80 提出、#240 确认——压缩真实成本的大头是 Prompt Cache 失效：selective compression 在历史中间就地改写，把压缩点之后的整个后缀踢出缓存前缀，后续每轮按全价重算。#240 的独立压缩模型只解决"隔离 + 摘要 output"，没动缓存失效。本 issue 做主杠杆。

目标：把"频繁就地压缩"变成"偶发批量 rollover"，阶段内 model-visible history 尽量 append-only，缓存失效次数大幅下降。

方案要点（待细化）：

1. 阶段内 append-only（不就地改中间）；
2. 可删 tool output 标 pending drop（延迟移除，不每次改前缀）；
3. 压力高 / 阶段结束时一次性批量压缩 + 删除（一次失效摊薄到整段）；
4. decompress / search 结果追加到尾部，不插回原位置。

关键设计问题（需先对齐）：

• pending drop 若指"立即从 prompt 隐藏"会本身改前缀、与目标矛盾 → 更可能是"延迟到 rollover 才移除"（阶段内先留着占一点 context，换缓存稳定）。需量化：缓存省的钱 vs 临时多占的 context。
• rollover 触发条件：上下文阈值？阶段边界如何判定？
• 与 # [Feature Request] 新增 /acp compact 命令，复用 models.json 实现协同压缩 #240 独立压缩模型正交、可组合（rollover 时摘要甩给独立模型）。

验收标准：阶段内 append-only；pending drop 标记 + 延迟移除；批量 rollover；检索结果追加尾部；单测验证 rollover 前后缓存前缀一致；文档更新。

要不要我把这个 follow-up 直接建成 issue？

[ranxianglei]

分支提交为 pr 问题提交为 issue

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 已按「分支 → PR，问题 → issue」提交：

• PR feat: /acp compact — dedicated compression model (session shared-prefix + models.json) #241（分支 feat/acp-compact-compression-model）：feat: /acp compact — dedicated compression model (session shared-prefix + models.json) #241
  实现 /acp compact（session 共享前缀 + models.json 模型两种模式 + Fallback），450/450 测试通过。等你 review / 合并（合并按惯例由人工执行）。
• Issue [Feature Request] Prompt Cache 稳定性 / 批量 rollover 压缩（主杠杆） #242（主杠杆 follow-up）：[Feature Request] Prompt Cache 稳定性 / 批量 rollover 压缩（主杠杆） #242
  「Prompt Cache 稳定性 / 批量 rollover 压缩」——背景、方案要点（阶段内 append-only、pending drop、批量 rollover、检索结果追加尾部）、关键设计问题（pending drop 与缓存前缀的矛盾、rollover 触发条件、与 # [Feature Request] 新增 /acp compact 命令，复用 models.json 实现协同压缩 #240 的正交组合）、验收标准都已写好。

PR 和 issue 都建好了，你看下内容有没有要调整的。

[ranxianglei]

🤖 ework agent · vllm-qwen/qwen3.8-27b

[bot] 这个 issue 本会话已完成，状态确认（刚验证过）：

• 代码：分支 feat/acp-compact-compression-model（clean，已 push，含 631d51e + c5e7de8 两个 commit）。
• PR feat: /acp compact — dedicated compression model (session shared-prefix + models.json) #241（open，未合并）：feat: /acp compact — dedicated compression model (session shared-prefix + models.json) #241 —— /acp compact 完整实现（session 共享前缀 + models.json 模型两种模式 + Fallback），450/450 测试通过，typecheck + build 干净。
• Issue [Feature Request] Prompt Cache 稳定性 / 批量 rollover 压缩（主杠杆） #242（open）：[Feature Request] Prompt Cache 稳定性 / 批量 rollover 压缩（主杠杆） #242 —— 主杠杆 follow-up「Prompt Cache 稳定性 / 批量 rollover」。

验收标准对照：

• /acp compact 注册 + 读取/列出 models.json 模型
• 触发 compress 时由指定模型完成摘要（session 模式还复用了 prompt 前缀）
• Fallback：压缩模型报错时降级主模型，不阻断主流程
• 单测：mock models.json、mock 外部 API、验证 Fallback（+ session 共享前缀用例）
• README + CONFIGURATION 更新

PR 等你 review / 合并（合并按惯例由人工执行）。如需调整告诉我。

[ranxianglei]

简述下状态

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 状态简述：

#240 已完成，等 review。

• 分支 feat/acp-compact-compression-model（已 push，clean）→ PR feat: /acp compact — dedicated compression model (session shared-prefix + models.json) #241（open）：feat: /acp compact — dedicated compression model (session shared-prefix + models.json) #241
• 实现：/acp compact [session|<id>|reset]
  • session：用 session 自身模型 + 复用 prompt 前缀（省 input、隔离压缩推理）
  • <id>：models.json 里的更便宜模型
  • 未设置 → 主模型自写摘要（默认不变）；任何失败 → Fallback 主模型，不中断
• 450/450 测试通过，typecheck + build 干净，README/CONFIGURATION 已更新。

主杠杆另立 issue： #242（open）「Prompt Cache 稳定性 / 批量 rollover」——因为压缩 token 成本大头是缓存失效，不是写摘要，这块才是主杠杆：#242

下一步：你 review / 合并 PR #241（人工合并）；#242 待你拍板方案后开工。