Merge pull request #213 from itmisx/fix/compact-turn-boundary

🐛 fix: compact turn boundary

Author: itmisx

agent/compact.go

@@ -18,16 +18,67 @@ import (
 // 本文件封装与 TUI 无关的压缩纯逻辑:token 估算 + RunCompression。
 // bubbletea 胶水(触发时机、tea.Cmd 包装、消息处理、读 model/session)仍在 tui 包,调用这里的导出函数。
 
-// ErrCompactTooFewTurns:压缩因「user 轮数不足」被拒。这是**结构性不可恢复**失败 —— 轮内 for 循环
-// 是单个 user turn,期间 user 轮数恒定,冷却后重试也永远失败,且这个检查在发 LLM 请求前就本地秒拒。
-// agent 据此区别对待:轮数不足永久关本轮压缩(而非冷却重试),避免每圈闪「压缩中…/失败」刷屏
-// (issue #201)。只有瞬时失败(超时/网络)才值得冷却重试。
-var ErrCompactTooFewTurns = errors.New("user 轮数不足,无需压缩")
-
-// keepRecentTurns 是压缩时至少保留的最近 user 轮数下限(与 20% 预算取较大者)。
-// 2 轮能覆盖"最近指代",同时大幅减少过度保留。可按需调整。
+// ErrCompactTooFewTurns:压缩因「对话轮数不足」被拒(轮数按 isTurnBoundary 计,见下)。
+// 这个检查在发 LLM 请求前就本地秒拒,agent 据此区别对待:轮数不足永久关本轮压缩(而非冷却重试),
+// 避免每圈闪「压缩中…/失败」刷屏(issue #201)。只有瞬时失败(超时/网络)才值得冷却重试。
+var ErrCompactTooFewTurns = errors.New("对话轮数不足,无需压缩")
+
+// keepRecentTurns 是压缩时至少保留的最近对话轮数下限(与 compactKeepPct 预算取较大者)。
+// 2 轮能覆盖"最近指代",同时不过度保留。
 const keepRecentTurns = 2
 
+// compactKeepPct 是压缩后保留的尾部上下文占上下文窗口的百分比(切点由它反推)。
+// 15%(原 20%):留得更少 = 压完离触发线更远、少压几次,长任务会话尤其受益。
+const compactKeepPct = 15
+
+// CompactKeepTokens 返回压缩后应保留的尾部上下文 token 数(= 窗口 × compactKeepPct%)。
+// 导出供 tui 使用:"值不值得压"的判断必须与这里的保留口径一致,别再各处各写一份百分比。
+func CompactKeepTokens(ctxWin int) int { return ctxWin * compactKeepPct / 100 }
+
+// CutHistory 按切点截断历史,返回要保留的尾部(新切片,不共享底层数组、不改入参)。
+//
+// 切点按 user|assistant 取(见 isTurnBoundary),长任务轮里往往落在 assistant 上,于是保留段以
+// assistant 打头、整段可能一条 user 消息都没有。这时把**被压掉那部分里最近一条 user 消息**复制
+// 一份放到最前面,一举两得:
+//   - 模型能看到用户任务的原文,而不是只剩摘要里的转述;
+//   - 开头恒为 system → user → assistant。vLLM 按模型自带 chat template 渲染,Mistral / Llama-2 系
+//     模板写着 raise_exception("Conversation roles must alternate ..."),system 后直接跟 assistant 会被拒。
+//
+// 从**被压掉的部分**取,所以它在时间线上必早于保留段的全部内容,插到最前面顺序正确,
+// 也不会与保留段里已有的 user 消息重复。复制时丢掉图片:图会被重新渲染成 base64、很占 token,
+// 而摘要里已有相关描述。保留段本就以 user 开头时原样返回,不做任何事。
+//
+// 所有应用切点的地方都该走这里,别自己 history[cutIdx:] —— 否则各处行为不一致。
+func CutHistory(history []ChatMessage, cutIdx int) []ChatMessage {
+	cutIdx = min(max(cutIdx, 0), len(history))
+	kept := history[cutIdx:]
+	out := make([]ChatMessage, 0, len(kept)+1)
+	if len(kept) > 0 && kept[0].Role != "user" {
+		for i := cutIdx - 1; i >= 0; i-- {
+			// 取最近一条**有正文**的 user 消息:纯图片消息剥掉图后正文为空,
+			// 发出去会是一条没有 content 字段的 user 消息,部分后端直接拒。
+			if history[i].Role != "user" || strings.TrimSpace(history[i].Content) == "" {
+				continue
+			}
+			task := history[i]
+			task.ImagePaths = nil // 图不复制(见上)
+			task.ContentParts = nil
+			out = append(out, task)
+			break
+		}
+	}
+	return append(out, kept...)
+}
+
+// isTurnBoundary 判断这条消息能否当作"一轮对话"的边界,也即能否作为压缩切点。
+//
+// user 和 assistant 都算,tool 不算。两个原因:
+//   - "一个 user 消息 + 几十轮工具调用"的长任务轮里一条 user 都没有(issue #201 的典型形态),
+//     只认 user 就找不到切点,压缩要么退到最前面(等于不压)、要么把整个长轮全保住;
+//   - tool 消息必须紧跟发起调用的 assistant,切在它上面会留下孤儿 tool → API 400
+//     (见 sanitizeToolPairs);而切在 assistant 上,它的 tool 结果自然跟着一起保留,配对不坏。
+func isTurnBoundary(m ChatMessage) bool { return m.Role == "user" || m.Role == "assistant" }
+
 // compactionTimeout 是摘要 LLM 调用的硬超时。没有它,卡住的请求会让压缩锁永远占住、把所有压缩堵死。
 // 给得宽松(容纳大摘要生成 + 本地慢模型,如 4090D 上跑 qwen 摘要大历史,见 issue #201),
 // 只为兜住"永不返回",超时即失败、下轮重试。
@@ -191,7 +242,8 @@ func EstimatePromptTokens(workspace, skillCatalog, summary string, history []Cha
 
 // === 压缩执行 ===
 
-// RunCompression 执行一次会话压缩:按 context_window × 20% 保留尾部上下文。
+// RunCompression 执行一次会话压缩:保留 max(context_window × compactKeepPct%, 最近 keepRecentTurns 轮)
+// 的尾部上下文,切点落在 user / assistant 边界(见 isTurnBoundary),因此也能切进长任务轮内部。
 // 通常在 goroutine 中调用。history 仅含会话消息(不含 system / 旧摘要消息)。
 //
 // 缓存友好:传入 lastSystemPrompt(上次实际发送的 system 文本)时,摘要请求构造成
@@ -201,35 +253,39 @@ func EstimatePromptTokens(workspace, skillCatalog, summary string, history []Cha
 func RunCompression(lastSystemPrompt, lastToolSpecsJSON string, history []ChatMessage, entry ModelEntry, ctxWin int) (
 	summary string, cutIdx int, compressedTurns int, err error) {
 
-	totalUsers := 0
+	// 轮数按 isTurnBoundary(user 或 assistant)计:一个 user 消息 + 几十轮工具调用同样是几十轮对话,
+	// 只数 user 会把这种长任务会话判成"轮数不足"而永远压不动(issue #201)。
+	// 总轮数不多于要保留的轮数 → 全都要留,没有可压前缀。
+	turns := 0
 	for _, msg := range history {
-		if msg.Role == "user" {
-			totalUsers++
+		if isTurnBoundary(msg) {
+			turns++
 		}
 	}
-	if totalUsers <= 2 {
+	if turns <= keepRecentTurns {
 		return "", 0, 0, ErrCompactTooFewTurns
 	}
 
-	// 保留量 = max(20% 预算, 最近 keepRecentTurns 轮),取保留更多者(切点更靠前 = 下标更小)。
-	// 关键:budgetStart 初值 = 0 = "默认保留全部"。从尾部累加 token 攒够 20% 窗口,才把切点后移
-	// (留得更少)。整段历史都不到 20% → budgetStart 停在 0 → keepStart=0 → 守卫拒绝,不压。
-	keepTarget := ctxWin * 20 / 100
+	// 保留量 = max(compactKeepPct 预算, 最近 keepRecentTurns 轮),取保留更多者(切点更靠前 = 下标更小)。
+	// 两个循环都只在 isTurnBoundary 处取切点 —— 切在 tool 上会留下孤儿 tool、被 API 拒。
+	// 关键:budgetStart 初值 = 0 = "默认保留全部"。从尾部累加 token 攒够预算,才把切点后移
+	// (留得更少)。整段历史都不够预算 → budgetStart 停在 0 → keepStart=0 → 守卫拒绝,不压。
+	keepTarget := CompactKeepTokens(ctxWin)
 
-	budgetStart := 0 // 默认保留全部;攒够 20% 才后移切点
+	budgetStart := 0 // 默认保留全部;攒够预算才后移切点
 	cc := 0
 	for i := len(history) - 1; i >= 0; i-- {
 		// 用 MsgTokens(tiktoken 精确分词)按 token 累加全字段,含 ReasoningContent + ToolCalls 参数。
 		cc += MsgTokens(history[i])
-		if history[i].Role == "user" && cc >= keepTarget {
+		if isTurnBoundary(history[i]) && cc >= keepTarget {
 			budgetStart = i
 			break
 		}
 	}
-	turnStart := len(history) // 最近 keepRecentTurns 个 user 轮;不足则保持 len(不参与取 min)
+	turnStart := len(history) // 最近 keepRecentTurns 轮;不足则保持 len(不参与取 min)
 	uc := 0
 	for i := len(history) - 1; i >= 0; i-- {
-		if history[i].Role == "user" {
+		if isTurnBoundary(history[i]) {
 			uc++
 			if uc >= keepRecentTurns {
 				turnStart = i
@@ -242,8 +298,8 @@ func RunCompression(lastSystemPrompt, lastToolSpecsJSON string, history []ChatMe
 		keepStart = turnStart
 	}
 	if keepStart <= 0 {
-		// 整段都要留:历史不足 20% 窗口,或 20% 边界就在最前一条 —— 没有可压缩前缀。
-		return "", 0, 0, fmt.Errorf("历史不足 20%% 窗口,无需压缩")
+		// 整段都要留:历史不足保留预算,或预算边界就在最前一条 —— 没有可压缩前缀。
+		return "", 0, 0, fmt.Errorf("历史不足 %d%% 窗口,无需压缩", compactKeepPct)
 	}
 	cutIdx = keepStart
 

agent/compact_cooldown_test.go

@@ -12,28 +12,51 @@ import (
 )
 
 // RunCompression 因轮数不足被拒时,返回可识别的哨兵错误(agent 据此决定永久关而非冷却重试)。
+// 轮数按 user|assistant 计(见 isTurnBoundary),所以"不足"= 总共不多于 keepRecentTurns 条非 tool 消息。
 func TestRunCompression_TooFewTurnsSentinel(t *testing.T) {
 	hist := []ChatMessage{
 		{Role: "user", Content: "一"},
 		{Role: "assistant", Content: "回一"},
-		{Role: "user", Content: "二"},
-	} // 只有 2 个 user 轮
+	} // 2 轮(user + assistant),不多于要保留的 keepRecentTurns
 	_, _, _, err := RunCompression("", "", hist, ModelEntry{ContextWindow: 100000}, 100000)
 	if !errors.Is(err, ErrCompactTooFewTurns) {
 		t.Fatalf("2 轮应返回 ErrCompactTooFewTurns 哨兵, got %v", err)
 	}
 }
 
-// C-分流①:轮数不足是结构性不可恢复(本轮 user 轮数恒定)→ 永久关,压缩只尝试一次,不每圈刷屏。
-func TestInLoopCompact_TooFewTurnsPermanentOff(t *testing.T) {
+// 一个 user 消息 + 几十轮工具调用:轮数按 user|assistant 计后不再被"轮数不足"拒
+// —— 这正是 issue #201 里长任务会话压不动的形态(旧规则只数 user,这里 totalUsers=1 直接秒拒)。
+func TestRunCompression_SingleUserLongTurnNotRejected(t *testing.T) {
+	hist := []ChatMessage{{Role: "user", Content: "跑测试并修好所有失败"}}
+	body := strings.Repeat("覆盖率数据 line 42 hit; ", 200)
+	for i := range 6 {
+		id := fmt.Sprintf("s%d", i)
+		hist = append(hist, asstCall(id, "Bash", `{"command":"go test"}`), toolMsg(id, "Bash", body))
+	}
+	// BaseURL 为空 → 摘要请求在本地就失败;这里只关心它已越过轮数 / 切点守卫。
+	_, _, _, err := RunCompression("sys", "[]", hist, ModelEntry{ContextWindow: 20000}, 20000)
+	if errors.Is(err, ErrCompactTooFewTurns) {
+		t.Fatal("单个 user 长任务轮不应再被判成轮数不足")
+	}
+	if err != nil && strings.Contains(err.Error(), "无需压缩") {
+		t.Fatalf("不该被切点守卫拒绝:%v", err)
+	}
+}
+
+// C-分流①:压缩成功但历史仍超阈值(再压也切不动)→ 永久关,只尝试一次,不每圈刷屏。
+func TestInLoopCompact_StillOverThresholdPermanentOff(t *testing.T) {
 	const ctxWin = 20000
-	url := compactTestServer(t, false) // 不注入失败;压缩会被 totalUsers<=2 本地拒(发不出请求)
+	url := compactSummaryServer(t) // 压缩请求返正常摘要,其余返工具调用 + 高 prompt_tokens
 
 	cfg := ModelConfig{Flash: ModelEntry{BaseURL: url, Model: "m", APIKey: "k", ContextWindow: ctxWin, MaxTokens: 256}}
-	attempts := runLoopCountingCompactAttempts(t, cfg, bloat2Turns())
+	attempts, est := runLoopCountingCompactAttempts2(t, cfg, bloatedHistory())
 
+	if est > 0 && est < CompactTriggerTokens(ctxWin) {
+		t.Skipf("前提不成立:压缩后估算 %d tok 已低于触发线 %d,本例测不到永久关",
+			est, CompactTriggerTokens(ctxWin))
+	}
 	if attempts != 1 {
-		t.Fatalf("轮数不足应永久关、只尝试 1 次压缩,实际 %d 次(冷却重试会 >1,刷屏)", attempts)
+		t.Fatalf("压完仍超阈值应永久关、只尝试 1 次压缩,实际 %d 次(冷却重试会 >1,刷屏)", attempts)
 	}
 }
 
@@ -79,8 +102,59 @@ func runLoopCountingCompactAttempts(t *testing.T, cfg ModelConfig, hist []ChatMe
 	return attempts
 }
 
-// bloat2Turns 造「2 个 user 轮 + 大工具输出」,过触发线但轮数不足。
-func bloat2Turns() []ChatMessage {
+// runLoopCountingCompactAttempts2 同上,额外返回压缩成功时上报的估算量(用于判断"压完是否仍超线")。
+func runLoopCountingCompactAttempts2(t *testing.T, cfg ModelConfig, hist []ChatMessage) (attempts, est int) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	_, ch := StartStream(ctx, cfg, hist, AgentMode_Auto, t.TempDir(), "", "", "flash", WorkingModeDefault)
+
+	rounds := 0
+	for msg := range ch {
+		switch m := msg.(type) {
+		case CompactingMsg:
+			attempts++
+		case CompactedMsg:
+			est = m.EstPromptTokens
+		case ToolCallStartMsg:
+			if rounds++; rounds >= compactRetryCooldown+4 {
+				cancel()
+			}
+		}
+	}
+	return attempts, est
+}
+
+// compactSummaryServer:对「压缩请求」(body 含 checkpoint 指令)返回一份正常的非流式摘要;
+// 其余请求返回流式 Bash 工具调用 + 高 prompt_tokens(驱动循环、过触发线)。
+func compactSummaryServer(t *testing.T) string {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		if strings.Contains(string(body), "checkpoint") {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"choices":[{"message":{"role":"assistant","content":"## 任务目标\n跑测试\n\n## 下一步\n继续\n最后模式: auto"}}]}`)
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.WriteHeader(http.StatusOK)
+		f, ok := w.(http.Flusher)
+		if !ok {
+			t.Error("ResponseWriter 不支持 Flush")
+			return
+		}
+		f.Flush()
+		fmt.Fprint(w, `data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"c1","type":"function","function":{"name":"Bash","arguments":"{\"command\":\"echo hi\"}"}}]}}]}`+"\n\n")
+		f.Flush()
+		fmt.Fprint(w, `data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":18000,"completion_tokens":10}}`+"\n\n")
+		f.Flush()
+		fmt.Fprint(w, "data: [DONE]\n\n")
+		f.Flush()
+	}))
+	t.Cleanup(srv.Close)
+	return srv.URL
+}
+
+// bloatedHistory 造「过触发线的大历史」:一个 user 任务 + 若干轮大工具输出,可压。
+func bloatedHistory() []ChatMessage {
 	hist := []ChatMessage{{Role: "user", Content: "轮一"}}
 	body := strings.Repeat("覆盖率数据 line 42 hit; ", 200)
 	for i := 0; i < 6; i++ {

agent/llm.go

@@ -144,10 +144,15 @@ type CompactedMsg struct {
 type CompactingMsg struct{}
 
 // CompactFailedMsg 轮内自动压缩失败(摘要请求超时/被拒、历史压不动)。
-// 失败后本轮不再尝试压缩,退回「撞窗口优雅报错」保护 —— 这件事此前完全静默,
-// 用户只看到上下文一路涨上去却不知道中间试过一次(issue #201)。
+// 这件事此前完全静默,用户只看到上下文一路涨上去却不知道中间试过一次(issue #201)。
+//
+// Retrying 区分两种处置,UI 据此给不同的提示 —— 二者对用户的意味完全不同:
+//   - true:瞬时失败(超时/网络/请求被拒),冷却 compactRetryCooldown 圈后还会再试;
+//   - false:结构性失败,本轮永久关闭压缩,此后只剩 reclaim 与工具输出截断兜底,
+//     上下文会一路涨到撞满窗口、由 API 400 收场(即代码里说的「撞窗口优雅报错」)。
 type CompactFailedMsg struct {
-	Reason string
+	Reason   string
+	Retrying bool
 }
 
 // ContextReclaimedMsg 工具输出回收(reclaim)落地后发给 UI。reclaim 是长任务(user 轮≤2、压缩
@@ -708,17 +713,18 @@ func StartStream(
 				ch <- CompactingMsg{} // 先亮状态行:下面这行最长会卡 10 分钟,期间不吐任何 token
 				sum, cutIdx, turns, cerr := RunCompression(convo[0].Content, MarshalToolSpecs(toolSpecs), hist, currentEntry, ctxWin)
 				if cerr != nil {
-					// 按失败类型分流:轮数不足是本轮结构性不可恢复(user 轮数恒定,重试注定再失败)→ 永久关,
+					// 按失败类型分流:轮数不足是本轮结构性不可恢复(轮数恒定,重试注定再失败)→ 永久关,
 					// 不刷屏;瞬时失败(超时/网络)→ 冷却 compactRetryCooldown 圈后重试(见状态变量注释)。
-					if errors.Is(cerr, ErrCompactTooFewTurns) {
-						inLoopCompactOff = true
-					} else {
+					retrying := !errors.Is(cerr, ErrCompactTooFewTurns)
+					if retrying {
 						compactCooldown = compactRetryCooldown
+					} else {
+						inLoopCompactOff = true
 					}
-					ch <- CompactFailedMsg{Reason: cerr.Error()}
+					ch <- CompactFailedMsg{Reason: cerr.Error(), Retrying: retrying}
 				} else {
 					summary = sum
-					kept := append([]ChatMessage(nil), hist[cutIdx:]...)
+					kept := CutHistory(hist, cutIdx) // 保留段不以 user 开头时,补回用户任务原文
 					convo = append([]ChatMessage{{Role: "system", Content: BuildSystemPrompt(workspace, skillCatalog, summary)}}, kept...)
 					lastPromptTokens = 0 // 压完归零,等下一轮真实 usage 再判
 					// 压缩后 prompt 的本地估算:一份两用 —— ① 防死循环判断(下面);② 随 CompactedMsg