Merge pull request #208 from itmisx/fix/compaction-visibility

🐛 fix: compaction-visibility

Author: itmisx

agent/llm.go

@@ -108,12 +108,51 @@ type HistoryUpdateMsg struct {
 	History []ChatMessage
 }
 
-// CompactedMsg 在「单个长 turn 内」自动压缩后发给 UI:摘要存在 session(每轮注入 system 尾部),
-// 而 system 不入 history(HistoryUpdateMsg 会剥掉)——必须用这条把新摘要带出来,否则下轮上下文丢失。
-// history 截断由随后的 HistoryUpdateMsg 同步。Turns = 本次被压掉的 user 轮数,仅供 UI 提示。
+// CompactedMsg 在「单个长 turn 内」自动压缩后发给 UI。
+//
+// 摘要 + 截断后的历史**必须装在同一条消息里**:两者曾经分两条发(CompactedMsg 带摘要、随后的
+// HistoryUpdateMsg 带截断历史),而 UI 是一条一条消费的,用户若恰好在两条之间按 ESC,中断逻辑会
+// drainAndDiscard 掉后一条 —— 结果是「摘要存下了、历史没截断」,下一轮把摘要和完整历史一起发出去,
+// 内容重复、上下文反而比压缩前更大(issue #201 里"莫名其妙涨到 87%"的机制之一)。
+// 装成一条后要么全生效、要么全不生效:中断时 agent 直接 return,它压好的 convo 一并丢弃,
+// UI 保留完整历史,下一轮重来,只是白压一次 —— 状态始终自洽。
 type CompactedMsg struct {
 	Summary string
 	Turns   int
+	// History = 压缩后的完整 convo(含首条 system)。UI 用它替换本地副本,剥掉 system 后存盘。
+	History []ChatMessage
+	// EstPromptTokens = 压缩后「下一次请求」的本地估算(system + tools + 保留的历史)。
+	// TUI 状态栏显示的是上一次请求的真实 prompt_tokens,压缩截断历史后它仍是压缩前的大数,
+	// 要等下一次请求才更新 —— 本轮若被 ESC 中断就永远不更新,看起来像"压了没动"(issue #201)。
+	// 由 agent 捎出来而不是让 TUI 自己估:CompactedMsg 到达时 TUI 的 history 还没被截断(截断靠
+	// 随后的 HistoryUpdateMsg),自己估只会估出压缩前的数;而这个值 agent 防死循环时本就要算。
+	EstPromptTokens int
+}
+
+// CompactingMsg 轮内自动压缩「开始」时发给 UI:RunCompression 是一次同步的 LLM 调用,
+// 最长会卡 compactionTimeout(2 分钟),期间 agent 停在那儿、一个 token 也不吐。不发这条的话
+// 界面上只有普通的流式 spinner,用户看不出在压缩,只觉得卡死了(issue #201)。
+// 收到后 UI 把活动状态行切成「压缩中…」,由 CompactedMsg(成功)或 CompactFailedMsg(失败)复位。
+type CompactingMsg struct{}
+
+// CompactFailedMsg 轮内自动压缩失败(摘要请求超时/被拒、历史压不动)。
+// 失败后本轮不再尝试压缩,退回「撞窗口优雅报错」保护 —— 这件事此前完全静默,
+// 用户只看到上下文一路涨上去却不知道中间试过一次(issue #201)。
+type CompactFailedMsg struct {
+	Reason string
+}
+
+// ContextReclaimedMsg 工具输出回收(reclaim)落地后发给 UI。reclaim 是长任务(user 轮≤2、压缩
+// 结构上不触发)里**唯一**在减负的一层,可它此前只发 HistoryUpdateMsg —— 不刷状态栏、不留痕迹、
+// 不广播,把上下文从 100% 压到 20% 用户却什么都看不到,以为"没压成功"(issue #201)。
+// 这条把 reclaim 对齐到自动压缩的待遇:痕迹 + web 提示 + 状态栏刷新。
+type ContextReclaimedMsg struct {
+	Count  int // 被回收的工具结果条数
+	Tokens int // 净回收掉的 token(原文 - 占位标记)
+	// EstPromptTokens = 回收后「下一次请求」的本地估算。状态栏读的是上一次请求的真实 prompt_tokens,
+	// 回收后它仍是回收前的大数,要等下一次请求才更新 —— 本轮被 ESC 中断就永远不更新。用它把已失效的
+	// 真实值降下来(TUI 侧只降不升,见 CompactedMsg.EstPromptTokens 同款逻辑)。
+	EstPromptTokens int
 }
 
 // VisionUnsupportedMsg:本以为支持视觉的模型,实际发图被端点拒(如 404 "no image input")。
@@ -579,6 +618,9 @@ func StartStream(
 		ch <- ModelSwitchMsg{Role: role, ModelID: currentEntry.Model}
 
 		toolSpecs := buildToolSpecs(mode)
+		// 工具定义 JSON 的 token 数,本轮不变(toolSpecs 只在这里建一次)。算一次复用:reclaim
+		// 给 UI 的估算要含它,口径才与真实 prompt_tokens / 压缩的 EstimatePromptTokens 对齐。
+		toolSpecsTokens := EstTokens(MarshalToolSpecs(toolSpecs))
 
 		// 发出本轮"实际发送"的前缀快照(system 文本 + tool specs JSON),供 TUI 持久化:
 		// 重启变化检测 + 缓存友好压缩复刻旧前缀。tool specs 随 mode/role 变,故必须存实际值。
@@ -625,7 +667,10 @@ func StartStream(
 					curEst += MsgTokens(convo[i]) // 实时估算(与 clampMaxTokens 同口径);可后续复用其结果省一遍
 				}
 				if max(lastPromptTokens, curEst) >= ctxWin*compactTriggerPct/100 {
-					if reclaimToolOutputs(convo, ctxWin) {
+					if n, freed := reclaimToolOutputs(convo, ctxWin); n > 0 {
+						// 回收后 prompt 估算 = system+messages(curEst 已含,减去净回收量)+ tools schema。
+						estAfter := curEst - freed + toolSpecsTokens
+						ch <- ContextReclaimedMsg{Count: n, Tokens: freed, EstPromptTokens: estAfter}
 						ch <- HistoryUpdateMsg{History: convo}
 					}
 				}
@@ -638,21 +683,26 @@ func StartStream(
 				lastPromptTokens >= ctxWin*compactTriggerPct/100 &&
 				len(convo) > 0 && convo[0].Role == "system" {
 				hist := convo[1:]
+				ch <- CompactingMsg{} // 先亮状态行:下面这行最长会卡 2 分钟,期间不吐任何 token
 				sum, cutIdx, turns, cerr := RunCompression(convo[0].Content, MarshalToolSpecs(toolSpecs), hist, currentEntry, ctxWin)
 				if cerr != nil {
 					inLoopCompactOff = true // 压不动(历史太短/摘要失败)→ 本轮不再尝试,退回撞窗口报错
+					ch <- CompactFailedMsg{Reason: cerr.Error()}
 				} else {
 					summary = sum
 					kept := append([]ChatMessage(nil), hist[cutIdx:]...)
 					convo = append([]ChatMessage{{Role: "system", Content: BuildSystemPrompt(workspace, skillCatalog, summary)}}, kept...)
 					lastPromptTokens = 0 // 压完归零,等下一轮真实 usage 再判
+					// 压缩后 prompt 的本地估算:一份两用 —— ① 防死循环判断(下面);② 随 CompactedMsg
+					// 带给 TUI 刷新状态栏(见 CompactedMsg.EstPromptTokens 注释)。
+					estAfter := EstimatePromptTokens(workspace, skillCatalog, summary, kept)
 					// 防死循环:若压缩后历史仍超阈值(最近 5 轮本身就超窗口,RunCompression 切点缩不动),
 					// 再压也无效 → 本轮关掉循环内压缩,退回撞窗口优雅报错,避免反复压缩刷请求。
-					if EstimatePromptTokens(workspace, skillCatalog, summary, kept) >= ctxWin*compactTriggerPct/100 {
+					if estAfter >= ctxWin*compactTriggerPct/100 {
 						inLoopCompactOff = true
 					}
-					ch <- CompactedMsg{Summary: summary, Turns: turns}
-					ch <- HistoryUpdateMsg{History: convo}
+					// 摘要 + 截断历史 + 新量级一条送达,原子生效(见 CompactedMsg 注释)。
+					ch <- CompactedMsg{Summary: summary, Turns: turns, History: convo, EstPromptTokens: estAfter}
 				}
 			}
 			// 按本轮模型支不支持视觉,即时把带图消息渲染成 base64 或 路径+OCR(见 renderConvoImages)。
@@ -1714,12 +1764,14 @@ const (
 	reclaimMarkerPrefix = "[已回收] "
 )
 
-// reclaimToolOutputs 就地把"较旧的工具结果内容"换成引用标记以回收上下文,返回是否发生改动。
+// reclaimToolOutputs 就地把"较旧的工具结果内容"换成引用标记以回收上下文,
+// 返回(被回收条数, 净回收 token = 原文-占位);未发生改动返回 (0, 0)。计数供 UI 提示 ——
+// 不出声的话用户看不出上下文被动过,只当"没压成功"(issue #201)。
 // 只改 Role=="tool" 消息的 Content;user/assistant 消息、工具调用骨架、ToolCallID 配对一律不动
 // (故 sanitizeToolPairs 安全、发给 API 的配对完整)。
 // 保护:最近 reclaimMinTailToolMsgs 条工具结果 + 最近 reclaimKeepPct 预算内的工具输出,留全。幂等。
 // 聚合下限:整趟能回收的总量不足 reclaimMinTotalPct 窗口就整趟不动 —— 避免为一点点收益击穿前缀缓存。
-func reclaimToolOutputs(convo []ChatMessage, ctxWin int) bool {
+func reclaimToolOutputs(convo []ChatMessage, ctxWin int) (count, freed int) {
 	if ctxWin <= 0 {
 		ctxWin = 65536
 	}
@@ -1768,14 +1820,19 @@ func reclaimToolOutputs(convo []ChatMessage, ctxWin int) bool {
 
 	// 聚合下限:总回收量不够就整趟不动,不为小收益击穿缓存。
 	if reclaimable < ctxWin*reclaimMinTotalPct/100 {
-		return false
+		return 0, 0
 	}
 
-	// 第二趟:落地回收。
+	// 第二趟:落地回收。净回收量 = 原文 - 占位标记(标记本身也占几十 token),按净值报给 UI。
+	freed = reclaimable
 	for _, i := range victims {
 		convo[i].Content = toolOutputReference(convo[i].Name, callPath[convo[i].ToolCallID])
+		freed -= MsgTokens(convo[i])
+	}
+	if freed < 0 {
+		freed = 0
 	}
-	return len(victims) > 0
+	return len(victims), freed
 }
 
 // toolOutputReference 生成被回收工具结果的引用标记:带工具名与 path(有则),

agent/reclaim_emit_test.go

@@ -0,0 +1,98 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+// reclaimPlainSSE 一个只回一句文本、不带工具调用的假端点(收到即结束本轮)。
+func reclaimPlainSSE(t *testing.T, text string) string {
+	return sseServer(t, func(w http.ResponseWriter, flush func(), _ <-chan struct{}) {
+		fmt.Fprintf(w, "data: {\"choices\":[{\"delta\":{\"content\":%q}}]}\n\n", text)
+		flush()
+		fmt.Fprint(w, "data: [DONE]\n\n")
+		flush()
+	})
+}
+
+// reclaimBloatedHistory 造"1 个 user 轮 + 一堆大工具输出" —— reclaim 的目标形态(#201)。
+func reclaimBloatedHistory(rounds, perTool int) []ChatMessage {
+	h := []ChatMessage{{Role: "user", Content: "跑单元测试并生成覆盖率报告"}}
+	body := strings.Repeat("覆盖率数据 line 42 hit; ", perTool)
+	for i := range rounds {
+		id := fmt.Sprintf("c%d", i)
+		h = append(h,
+			asstCall(id, "Bash", fmt.Sprintf(`{"command":"go test ./pkg%d/"}`, i)),
+			toolMsg(id, "Bash", body),
+		)
+	}
+	return h
+}
+
+// 回收落地后 agent 必须发 ContextReclaimedMsg(带条数、净回收 token、回收后估算),
+// 否则 TUI 无从刷新状态栏 / 留痕迹 —— reclaim 又会回到"默默干活、零反馈"(issue #201)。
+func TestStartStream_EmitsContextReclaimed(t *testing.T) {
+	const ctxWin = 20000
+	hist := reclaimBloatedHistory(30, 120) // 够大,过 70% 触发线,且 reclaim 有得回收
+
+	// 本地先跑一遍拿期望值(agent 内部走同一个函数)。
+	local := append([]ChatMessage(nil), hist...)
+	wantCount, wantFreed := reclaimToolOutputs(local, ctxWin)
+	if wantCount == 0 {
+		t.Fatal("测试数据没能触发回收,调大 reclaimBloatedHistory")
+	}
+
+	url := reclaimPlainSSE(t, "好的")
+	cfg := ModelConfig{Flash: ModelEntry{
+		BaseURL: url, Model: "m", APIKey: "k",
+		ContextWindow: ctxWin, MaxTokens: 256,
+	}}
+	_, ch := StartStream(context.Background(), cfg, hist,
+		AgentMode_Auto, t.TempDir(), "", "", "flash", WorkingModeDefault)
+
+	var got []ContextReclaimedMsg
+	for msg := range ch {
+		if m, ok := msg.(ContextReclaimedMsg); ok {
+			got = append(got, m)
+		}
+		if e, ok := msg.(StreamErrMsg); ok {
+			t.Fatalf("假端点不该报错: %v", e.Err)
+		}
+	}
+
+	if len(got) == 0 {
+		t.Fatal("历史已过阈值,回收应发生并发 ContextReclaimedMsg")
+	}
+	if got[0].Count != wantCount || got[0].Tokens != wantFreed {
+		t.Errorf("回收消息 = {Count:%d Tokens:%d}, want {Count:%d Tokens:%d}",
+			got[0].Count, got[0].Tokens, wantCount, wantFreed)
+	}
+	// 回收后估算应为正、且明显小于回收前的整段历史(说明真减了负)。
+	if got[0].EstPromptTokens <= 0 {
+		t.Errorf("回收后估算应为正, got %d", got[0].EstPromptTokens)
+	}
+	if before := EstimateHistoryTokens(hist); got[0].EstPromptTokens >= before {
+		t.Errorf("回收后估算 %d 应小于回收前历史 %d", got[0].EstPromptTokens, before)
+	}
+}
+
+// 上下文没到阈值:不回收,也不该发 ContextReclaimedMsg。
+func TestStartStream_NoReclaimWhenSmall(t *testing.T) {
+	url := reclaimPlainSSE(t, "好的")
+	cfg := ModelConfig{Flash: ModelEntry{
+		BaseURL: url, Model: "m", APIKey: "k",
+		ContextWindow: 200000, MaxTokens: 256,
+	}}
+	_, ch := StartStream(context.Background(), cfg,
+		[]ChatMessage{{Role: "user", Content: "你好"}},
+		AgentMode_Auto, t.TempDir(), "", "", "flash", WorkingModeDefault)
+
+	for msg := range ch {
+		if m, ok := msg.(ContextReclaimedMsg); ok {
+			t.Errorf("小上下文不该触发回收: %+v", m)
+		}
+	}
+}

agent/reclaim_test.go

@@ -46,7 +46,7 @@ func TestReclaim_OldReplacedRecentKept(t *testing.T) {
 	convo := buildConvo(10, "Read", big)
 	before := len(convo)
 
-	if !reclaimToolOutputs(convo, 4096) { // 预算 = 4096*20% ≈ 819 token
+	if n, _ := reclaimToolOutputs(convo, 4096); n == 0 { // 预算 = 4096*20% ≈ 819 token
 		t.Fatal("应发生回收")
 	}
 	reclaimed, kept := countTool(convo)
@@ -63,7 +63,7 @@ func TestReclaim_OldReplacedRecentKept(t *testing.T) {
 
 func TestReclaim_TailProtected(t *testing.T) {
 	convo := buildConvo(reclaimMinTailToolMsgs+3, "Bash", strings.Repeat("x", 5000))
-	reclaimToolOutputs(convo, 1024) // 预算极小
+	_, _ = reclaimToolOutputs(convo, 1024) // 预算极小
 
 	seen := 0
 	for i := len(convo) - 1; i >= 0; i-- {
@@ -79,7 +79,7 @@ func TestReclaim_TailProtected(t *testing.T) {
 
 func TestReclaim_ReferenceHasNameAndPath(t *testing.T) {
 	convo := buildConvo(8, "Read", strings.Repeat("y", 8000))
-	reclaimToolOutputs(convo, 2048)
+	_, _ = reclaimToolOutputs(convo, 2048)
 
 	found := false
 	for _, m := range convo {
@@ -98,10 +98,10 @@ func TestReclaim_ReferenceHasNameAndPath(t *testing.T) {
 
 func TestReclaim_Idempotent(t *testing.T) {
 	convo := buildConvo(8, "Read", strings.Repeat("z", 6000))
-	if !reclaimToolOutputs(convo, 2048) {
+	if n, _ := reclaimToolOutputs(convo, 2048); n == 0 {
 		t.Fatal("首次应有改动")
 	}
-	if reclaimToolOutputs(convo, 2048) {
+	if n, _ := reclaimToolOutputs(convo, 2048); n > 0 {
 		t.Fatal("再次 reclaim 不应有新改动(幂等)")
 	}
 }
@@ -116,7 +116,7 @@ func TestReclaim_NonToolUntouched(t *testing.T) {
 		{Role: "assistant", Content: asstBig},
 	}
 	before := len(convo)
-	reclaimToolOutputs(convo, 1024)
+	_, _ = reclaimToolOutputs(convo, 1024)
 	if convo[1].Content != userBig {
 		t.Fatal("user 消息不应被改")
 	}
@@ -130,7 +130,7 @@ func TestReclaim_NonToolUntouched(t *testing.T) {
 
 func TestReclaim_UnderBudgetNoChange(t *testing.T) {
 	convo := buildConvo(6, "Read", "tiny") // 工具输出很小
-	if reclaimToolOutputs(convo, 1_000_000) {
+	if n, _ := reclaimToolOutputs(convo, 1_000_000); n > 0 {
 		t.Fatal("预算充足时不应回收")
 	}
 }
@@ -150,7 +150,7 @@ func TestReclaim_SmallOldOutputsKept(t *testing.T) {
 		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 远超,更旧的进入回收判定
+	_, _ = reclaimToolOutputs(convo, 2048) // keepBudget≈409;5 条大 Read 远超,更旧的进入回收判定
 
 	reclaimedRead := false
 	for _, m := range convo {
@@ -186,7 +186,7 @@ func TestReclaim_BelowTotalFloorNoChange(t *testing.T) {
 		convo = append(convo, toolMsg(id, "Read", huge))
 	}
 
-	if reclaimToolOutputs(convo, ctxWin) {
+	if n, _ := reclaimToolOutputs(convo, ctxWin); n > 0 {
 		t.Fatal("总回收量低于聚合下限时不应回收(护缓存)")
 	}
 	for _, m := range convo {
@@ -205,7 +205,7 @@ func TestReclaim_PairingPreserved(t *testing.T) {
 			ids[i] = m.ToolCallID
 		}
 	}
-	reclaimToolOutputs(convo, 2048)
+	_, _ = reclaimToolOutputs(convo, 2048)
 	for i, m := range convo {
 		if m.Role == "tool" {
 			if m.ToolCallID != ids[i] {

agent/workflow_tool.go

@@ -63,7 +63,9 @@ func handleWorkflowTool(
 		}
 		var sb strings.Builder
 		for _, m := range metas {
-			fmt.Fprintf(&sb, "- %s (%s):%s\n", m.Name, m.Scope, m.Description)
+			// 不带 scope 括号:模型会把 " (builtin)" 连同 name 一起抄进调用参数,导致匹配失败
+			// (同 buildSkillCatalog 的处理)。scope 对模型选 workflow 无决策价值。
+			fmt.Fprintf(&sb, "- %s: %s\n", m.Name, m.Description)
 		}
 		return tools.ToolResult{Output: strings.TrimRight(sb.String(), "\n"), Success: true}