什么是 micro-compact

代码入口与调用位置：

主循环在 query.ts:L369-L426 ：

messagesForQuery = await applyToolResultBudget
snipCompactIfNeeded
const microcompactResult = await deps.microcompact(
messagesForQuery。toolUseContext,querySource,)
messagesForQuery = microcompactResult.messages

大结果落盘预览>> History Snip>> microCompact>> Collapse>> AutoCompact>> API

microCompact 是一次 API 请求前的轻量清理，并先于重型摘要压缩。

可被 microCompact 清理的结果

在 microCompact.ts:L40-L50 ：候选工具包括 Read、Bash、Grep、Glob、网络搜索/抓取、Edit、Write。

接下来在 microCompact.ts:L226-L240 扫 Assistant 消息。按出现顺序收集这些工具的 tool_use.id

// Walk messages and collect tool_use IDs whose tool name is in COMPACTABLE_TOOLS
function collectCompactableToolIds: string {
const ids: string =
for {
if ) {
for {
if ) {
ids.push
}
}
}
}
return ids
}

"年龄" 即候选工具调用在历史中的顺序，非内容语义或时间戳。

主方法这方面，Cached Microcompact

入口为 microCompact.ts:L253-L292. 它必须同时满足：

mod.isCachedMicrocompactEnabled
mod.isModelSupportedForCacheEditing
isMainThreadSource

• 功能开关打开；
• 模型支持 cache editing；
• 仅主 REPL 线程，不对 session memory 等 fork agent 生效。

User Pain Point: "我无法确定哪些条件会触发 Cached Microcompact，我担心错误配置会导致关键信息被意外删除！"

进入后 会扫描 user message 中的 tag_result :

• #1. 只处理与白名单 tool_use 对上的结果，避免误删未缓存的数据。
• #2. 通过 state 保留已发送至 API 的工具 ID 与删除队列。
• #3. 实现阈值逻辑决定从较旧且已发送至 API 的候选中保留最近 N 个，其余标记删除。
• 提示: 此处缺失 cachedMicrocompact.ts 的具体实现，但可以根据配置字段推断规则。📌 
• ⚠️ 注意: API 成功返回后才标记可删除，以防当前轮尚未进入服务端缓存的工具结果被误删。
• . markToolsSentToAPIState ​
. text /** * Call when cached microcompact sends cache_edits deletions. * The next API response will have lower cache read tokens — that's * expected。not a cache break. */ export function notifyCacheDeletion( querySource: QuerySource,agentId?: AgentId,): void { const key = getTrackingKey const state = key?previousStateBySource.get : undefined if { state.cacheDeletionsPending = true } }

说到另一条方法，空闲后直接清空内容

`microCompact.ts:L446-L529` 是 time‑based 微压缩。触发条件为 `gapMinutes>= config.gapThresholdMinutes`。说到默认配置，

.

enabled: false,gapThresholdMinutes:
keepRecent:

启用且空闲超过阈值后：

text const keepSet = new Set) const clearSet = new Set))

即保留最近 N 个候选。旧的全部替换为：

text ''

因为超过一小时服务端 cache 大概率已过期。此时直接改本地内容不会额外损失一个本来可复用的热缓存。说起来，这条方法最接近你图里“缓存已失效，直接清理历史”的解释。

最终举一个 demo 来说明流程与痛点对比

起点这方面，本地 transcript

.

user : "帮我看下 config.ts 有没有硬编码端口"
assistant : tool_use Read id=toolu_A
user : tool_result tool_use_id=toolu_A "export const PORT = ..."
assistant : tool_use Grep id=toolu_B
user : tool_result tool_use_id=toolu_B "config.ts:: PORT = ..."
assistant : tool_use Bash id=toolu_C
user : tool_result tool_use_id=toolu_C "...一大堆匹配"
assistant : tool_use Read id=toolu_D
user : tool_result tool_use_id=toolu_D "app.listen ..."
assistant : "端口在 config.ts 硬编码为 …被 server.ts 引用"
user : "把它改成从环境变量读"

.

第 1 步：收集候选并排序

`collectCompactableToolIds` 扫 Assistant 消息，按出现顺序拿到白名单工具的 ID：

.

compactableToolIds =
↑最老 ↑最新

这就是“年龄”：列表里越靠前越老。

User Pain Point:

• No clear docs on *** certain tools are chosen for compaction → you may accidentally delete useful results.
• The order‑based “age” rule can be unintuitive when debugging large histories.
• You need to manually track which IDs have been sent to server before y’re eligible for deletion.

第 2 步：登记结果并判定要删谁

`microCompact.ts:L313-L332` 再扫 User 消息，把能对上白名单 `tool_use` 的 `tool_result` 登记进 `state`。至于随后，

.
getToolResultsToDelete:
keepRecent =
-> 保留 toolu_C,toolu_D
candidates 中较老且“已发送过 API”的 -> toolu_A。toolu_B
toolsToDelete =

注意 使用者痛点:- 当某个 result 尚未成功返回一次时它不会被纳入删除资格，从而避免意外丢失数据。但这也代表着你必须确认每个步骤都成功完成。否则可能出现 “看似没有变化，却消失了某些结果”。

第 3 步：本地 transcript 不动，只回传删除意图

.
return {
messages,compactionInfo:{
pendingCacheEdits:{
trigger:'auto'。deletedToolIds:,baselineCacheDeletedTokens:
},},}

UI 和磁盘里 userPainPoint:- 开发者看到完整内容，但实际 token 用量却减少。如果你想快速验证是否真的节省了 token。需要查看 API wire 或日志，而不是仅凭 UI。

User Pain Point:

• Your UI shows no change even though tokens were removed—debugging becomes harder.
• The hidden deletion step relies on internal state that might be stale after crashes or restarts.
• You cannot easily audit which exact IDs were deleted without digging into logs.

第 4 步：API 层组装线上请求

This is where real compression happens—deletion instructions are injected into last User message and each retained result gets a ``cache_reference`. Example wire payloads follow: .

Cache reference attachment:{ "type"这方面，"user","content":}]}

Deletion instruction injection:{ 至于"type"。"user","content":}}

The deletion edits ensure server only stores recent results while preserving prefix context for model.

对比两种方法

方法	本地存储	删除方式	前缀是否受影响
Cached Microcompact	保持原样	插入	✅ 保持
Time‑Based	为	无	❌ 前缀被

• Cached 方法更适合需要保持完整上下文但又想减少 token 的场景。
• Time‑Based 更适合长时间不活动后彻底刷新历史。

Demo Summary

• 在示例中，模型实际看到的是：

  • ToolA 与 ToolB 被隐藏。
  • ToolC 与 ToolD 保持可见并计费。

• 该轮向服务端省掉约 0.7 KB 的缓存 token，而前缀不被打断——这正是你截图中所说 “移除点之后缓存失效” 与实际情况之间的区别所在。

---

了解微压缩的细节能帮助你：

1. 精准控制 Token 使用 – 避免因冗余工具输出浪费预算。
2. 稳定缓存行为 – 防止无预警的 Cache Breaks。怎么说呢，
3. 提高调试效率 – 清晰知道哪些 ID 已经安全删除或仍然保留。

如果还有问题或想进一步调整。你可以检查配置文件里的阈值，并结合日志观察实际效果——这一步往往能让整个程序更稳健、更易维护。