Merge pull request #207 from itmisx/feature/tool-output-reclaim

⚡️ tool output reclaim

Author: itmisx

agent/compact.go

@@ -22,8 +22,9 @@ import (
 const keepRecentTurns = 2
 
 // compactionTimeout 是摘要 LLM 调用的硬超时。没有它,卡住的请求会让压缩锁永远占住、把所有压缩堵死。
-// 给得宽松(容纳大摘要生成),只为兜住"永不返回",超时即失败、下轮重试。
-const compactionTimeout = 3 * time.Minute
+// 给得宽松(容纳大摘要生成 + 本地慢模型,如 4090D 上跑 qwen 摘要大历史,见 issue #201),
+// 只为兜住"永不返回",超时即失败、下轮重试。
+const compactionTimeout = 10 * time.Minute
 
 // compressionPrompt 是冷路径(无前缀快照)压缩历史时发给 LLM 的 system prompt。
 const compressionPrompt = `你是会话「工作状态 checkpoint」生成器。把对话历史提炼成一份结构化的当前工作状态快照,用于丢弃旧历史后延续上下文。

agent/llm.go

@@ -1703,6 +1703,13 @@ const (
 	reclaimKeepPct = 20
 	// reclaimMinTailToolMsgs:无论预算多小,至少保护最近这么多条工具结果不动(模型正在用)。
 	reclaimMinTailToolMsgs = 4
+	// reclaimMinMsgTokens:单条工具输出小于这个 token 数就不回收 —— 占位标记本身也占地方,
+	// 回收小输出既省不了多少、又可能比原文还长,还白丢信息。只对真正占地方的大输出下手。
+	reclaimMinMsgTokens = 200
+	// reclaimMinTotalPct:整趟回收总量不足窗口这个百分比,就整趟不动。
+	// 每次 reclaim 都会击穿"最早被回收处往后"的前缀缓存,收益太小不值当 —— 攒够一坨再一次剪。
+	// 用百分比而非固定阈值:固定值在小窗口过于苛刻、大窗口又偏松。
+	reclaimMinTotalPct = 5
 	// reclaimMarkerPrefix:被回收工具结果的 Content 前缀,兼作幂等判据(再次 reclaim 时跳过、不重复计数)。
 	reclaimMarkerPrefix = "[已回收] "
 )
@@ -1711,6 +1718,7 @@ const (
 // 只改 Role=="tool" 消息的 Content;user/assistant 消息、工具调用骨架、ToolCallID 配对一律不动
 // (故 sanitizeToolPairs 安全、发给 API 的配对完整)。
 // 保护:最近 reclaimMinTailToolMsgs 条工具结果 + 最近 reclaimKeepPct 预算内的工具输出,留全。幂等。
+// 聚合下限:整趟能回收的总量不足 reclaimMinTotalPct 窗口就整趟不动 —— 避免为一点点收益击穿前缀缓存。
 func reclaimToolOutputs(convo []ChatMessage, ctxWin int) bool {
 	if ctxWin <= 0 {
 		ctxWin = 65536
@@ -1733,7 +1741,9 @@ func reclaimToolOutputs(convo []ChatMessage, ctxWin int) bool {
 		}
 	}
 
-	changed := false
+	// 第一趟:选出"会被回收"的工具结果下标,并累加回收总量(不改动 convo)。
+	var victims []int
+	reclaimable := 0
 	toolSeen := 0   // 已遍历到的(未回收)工具结果条数,用于"最近 N 条"保护
 	keptTokens := 0 // 已保留的工具输出 token 累计,用于预算保护
 	for i := len(convo) - 1; i >= 0; i-- {
@@ -1744,14 +1754,28 @@ func reclaimToolOutputs(convo []ChatMessage, ctxWin int) bool {
 			continue // 已回收:不计 tail、不计预算、不重复处理(幂等)
 		}
 		toolSeen++
+		tokens := MsgTokens(convo[i])
 		if toolSeen <= reclaimMinTailToolMsgs || keptTokens < keepBudget {
-			keptTokens += MsgTokens(convo[i]) // 保护区:留全,并计入预算
+			keptTokens += tokens // 保护区:留全,并计入预算
 			continue
 		}
+		if tokens < reclaimMinMsgTokens {
+			continue // 太小:占位≈原文,回收无意义,留着
+		}
+		victims = append(victims, i)
+		reclaimable += tokens
+	}
+
+	// 聚合下限:总回收量不够就整趟不动,不为小收益击穿缓存。
+	if reclaimable < ctxWin*reclaimMinTotalPct/100 {
+		return false
+	}
+
+	// 第二趟:落地回收。
+	for _, i := range victims {
 		convo[i].Content = toolOutputReference(convo[i].Name, callPath[convo[i].ToolCallID])
-		changed = true
 	}
-	return changed
+	return len(victims) > 0
 }
 
 // toolOutputReference 生成被回收工具结果的引用标记:带工具名与 path(有则),

agent/reclaim_test.go

@@ -135,6 +135,67 @@ func TestReclaim_UnderBudgetNoChange(t *testing.T) {
 	}
 }
 
+func TestReclaim_SmallOldOutputsKept(t *testing.T) {
+	// 较新的几条大 Read 把 keptTokens 撑过预算;更旧的都是小 Bash 输出。
+	// 大的旧 Read 应被回收,小的旧 Bash 不该(占位≈原文,回收无意义)。
+	big := strings.Repeat("x", 8000)
+	convo := []ChatMessage{{Role: "system", Content: "s"}, {Role: "user", Content: "t"}}
+	for k := 0; k < 6; k++ { // 更旧:小 Bash
+		id := fmt.Sprintf("old%d", k)
+		convo = append(convo, asstCall(id, "Bash", `{"command":"echo"}`))
+		convo = append(convo, toolMsg(id, "Bash", "小结果"))
+	}
+	for k := 0; k < 5; k++ { // 较新:大 Read
+		id := fmt.Sprintf("new%d", k)
+		convo = append(convo, asstCall(id, "Read", fmt.Sprintf(`{"path":"f%d.go"}`, k)))
+		convo = append(convo, toolMsg(id, "Read", big))
+	}
+	reclaimToolOutputs(convo, 2048) // keepBudget≈409;5 条大 Read 远超,更旧的进入回收判定
+
+	reclaimedRead := false
+	for _, m := range convo {
+		if m.Role != "tool" || !strings.HasPrefix(m.Content, reclaimMarkerPrefix) {
+			continue
+		}
+		if m.Name == "Bash" {
+			t.Fatal("小的旧 Bash 输出不应被回收(低于 reclaimMinMsgTokens)")
+		}
+		if m.Name == "Read" {
+			reclaimedRead = true
+		}
+	}
+	if !reclaimedRead {
+		t.Fatal("大的旧 Read 输出应被回收(sanity)")
+	}
+}
+
+func TestReclaim_BelowTotalFloorNoChange(t *testing.T) {
+	// 总回收量低于聚合下限(reclaimMinTotalPct 窗口)时,整趟不动 —— 护缓存。
+	ctxWin := 100000                    // minTotal = 5000, keepBudget = 20000
+	huge := strings.Repeat("x", 40000)  // ~10k token,4 条就撑爆 keepBudget
+	medium := strings.Repeat("y", 1200) // > reclaimMinMsgTokens,但两条合计仍 < minTotal
+	convo := []ChatMessage{{Role: "system", Content: "s"}, {Role: "user", Content: "t"}}
+	for k := 0; k < 2; k++ { // 更旧:2 条 medium(会成为候选,但总量小)
+		id := fmt.Sprintf("old%d", k)
+		convo = append(convo, asstCall(id, "Read", `{"path":"o.go"}`))
+		convo = append(convo, toolMsg(id, "Read", medium))
+	}
+	for k := 0; k < reclaimMinTailToolMsgs; k++ { // 较新:huge 占满 tail + 撑爆预算
+		id := fmt.Sprintf("new%d", k)
+		convo = append(convo, asstCall(id, "Read", `{"path":"n.go"}`))
+		convo = append(convo, toolMsg(id, "Read", huge))
+	}
+
+	if reclaimToolOutputs(convo, ctxWin) {
+		t.Fatal("总回收量低于聚合下限时不应回收(护缓存)")
+	}
+	for _, m := range convo {
+		if m.Role == "tool" && strings.HasPrefix(m.Content, reclaimMarkerPrefix) {
+			t.Fatal("聚合下限未过,任何工具输出都不应被回收")
+		}
+	}
+}
+
 func TestReclaim_PairingPreserved(t *testing.T) {
 	// 回收后每条 tool 消息的 ToolCallID / Name 不变,配对完整。
 	convo := buildConvo(10, "Read", strings.Repeat("w", 6000))