uv-agent v0.16.0

中文

v0.16.0 是一个聚焦上下文缓存效率的版本：引入了缓存感知的压缩判定机制（NetGain），让模型在上下文接近窗口上限时自主评估压缩的性价比，从而在保留关键上下文与降低 token 开销之间取得更优平衡。同时系统提示词和 helper 错误诊断也经历了一轮集中打磨。

重点变化

• 缓存感知压缩（cache-aware compaction）

  • 新增回合前轻量级 judge 轮次：当上下文占比超过 judge_min_context_ratio 时，模型先估算 remaining_calls_bucket 和 history_dependency，再通过 NetGain 公式枚举 K 个候选保留量，仅当最佳净收益超过 margin 缩放阈值时才触发压缩。
  • 压缩时按 K token 保留最近上下文原文，避免因摘要丢失关键信息；补偿路径（path B）保留窗口 25% 作为安全余量。
  • 新增配置项：cache_aware、margin、min_gain、judge_model_level、judge_min_context_ratio。
  • /status 面板展示最近一次 judge 的详细结果：依赖等级、NetGain 计算值、阈值及是否触发压缩。
  • 修复压缩请求中 tools=[] 导致 provider 端 prompt 前缀缓存失效的问题；增加 retry guard（最多 3 次），防止 provider 忽略压缩 prompt 仍返回 function_call。

• 系统提示词打磨

  • 为所有 helper <returns> 条目添加 Python 类型标注（path: str、returncode: int、Literal[...] 枚举值等），让模型更准确地理解返回结构。
  • 新增 <instruction_format> 章节，明确 XML 块是系统指令或补充信息，模型必须遵守。
  • 将单一示例替换为两轮 find+act 模式：第一轮集中搜索和阅读，第二轮集中编辑和验证，引导模型在更少的 run_python 调用中完成调查+修改。
  • 修复 read_file 在 Windows 下 CRLF 文件文本双重换行的问题：内部统一归一化为 LF，同时保留换行元数据以供 write_file(like=view) 还原。

• helper 错误诊断增强

  • 基于运行时 helper 调用统计（74% 的已记录错误源于过期上下文），为 replace_text（目标未找到）、read_file（行号越界、around 未匹配）增加了显式的"重新读取文件"提示。
  • 更新 round-2-act 示例：演示先用 search_text 守卫再执行 replace_text，以及 edit_lines 双锚点检查模式，减少静默失败。

• 修复

  • min_gain_usd 重命名为 min_gain（币种无关，匹配 pricing.currency）。
  • 修复 cached_input 的 falsy 陷阱：改为 is not None 检查，使 cache read 真正免费的模型获得正确的 P_read=0。
  • 当 P_read=0 时使用 P_write * 0.01 作为公式底线，确保 NetGain 仍可为这类模型产生正节省值。

Full Changelog: v0.15.3...v0.16.0

---

English

v0.16.0 is a context-cache efficiency release: it introduces a cache-aware compaction judge (NetGain) that lets the model estimate the cost/benefit of compressing before the context window fills, striking a better balance between retaining key context and reducing token spend. The system prompt and helper error diagnostics also received a focused round of polishing.

Highlights

• Cache-aware compaction

  • New pre-turn lightweight judge round: when context exceeds judge_min_context_ratio of the window, the model first estimates remaining_calls_bucket and history_dependency, then the NetGain formula enumerates K retention candidates — compaction only fires when the best net gain exceeds the margin-scaled threshold.
  • Compaction retains the last K tokens of recent context verbatim to avoid losing critical information through summarization; the mid-turn fallback path (path B) keeps 25% of the window as a safety net.
  • New config fields: cache_aware, margin, min_gain, judge_model_level, judge_min_context_ratio.
  • /status panel displays the most recent judge result: dependency level, computed NetGain, threshold, and whether compaction was triggered.
  • Fixed tools=[] in compaction requests breaking provider-side prompt prefix caching; added a retry guard (up to 3 attempts) for providers that ignore the compaction prompt and return a function_call anyway.

• System prompt refinements

  • Added Python type annotations to all helper <returns> entries (path: str, returncode: int, Literal[...] enum values, etc.), giving the model more precise knowledge of return structures.
  • Added an <instruction_format> section clarifying that XML blocks are system instructions or supplementary information and must be followed.
  • Replaced the single example with a two-round find+act pattern: round 1 focuses on search and reading, round 2 on editing and verification — guiding the model to compress investigation + action into fewer run_python calls.
  • Fixed read_file double-spacing on Windows for CRLF files: text is now internally normalized to LF while preserving newline metadata so write_file(like=view) still restores the correct style.

• Enhanced helper error diagnostics

  • Based on runtime helper call statistics (74% of recorded errors stem from stale context), added explicit "re-read the file" hints to replace_text (target not found), read_file (line out of range, around not found).
  • Updated the round-2-act example to demonstrate guarding edits with search_text before replace_text, and dual-anchor checking with edit_lines, reducing silent failures.

• Fixes

  • Renamed min_gain_usd to min_gain (currency-agnostic, matches pricing.currency).
  • Fixed the cached_input falsy trap: switched to is not None check so models with genuinely free cache reads get correct P_read=0.
  • When P_read=0, use P_write * 0.01 as a formula floor so NetGain can still produce positive savings for these models.

Full Changelog: v0.15.3...v0.16.0