feat(copilot): Agent 优化七件套 + 检索按作者收口

Agent/Copilot 优化（已采纳范围）：
- P0 时区：Chat 全程按 X-Timezone 算"今天"、解析 date_from/date_to
  与渲染日期，修跨 UTC 日界归属偏一天；站点级近况总结仍走 UTC。
- P0 prompt cache：Anthropic 最后一个 system 块打 cache_control 断点，
  缓存 tools+system 静态前缀，抵消 ReAct 循环重发成本；OpenAI 端服务端自动缓存。
- P1 top_k 放宽：limit 入参 + effectiveTopK 随上下文窗口缩放（默认 6/大窗 10，上限 20）。
- P1 maxRounds 可配：ECH0_AGENT_MAX_ROUNDS（默认 4）。
- P1 新工具 stats_overview：纯内存聚合给精确量化（总条数/活跃天/按月/最活跃月/Top标签）。
- P3 工具并发：execTools 三段式（顺序去重 → errgroup 有界并发 → 顺序收尾），
  并修 Anthropic 多 tool_result 配对隐患（先聚 tool_result 再追加图片消息）。
- P3 轮内 token 预算：MaxContextTokens 超限时回收最旧工具结果（替换为占位、不删消息）。

多用户隔离（检索收口本人）：
- embedding Search 增 authorUsername：over-fetch 后按 username 过滤再裁到 k。
- EchoQueryDto.UserID（json:"-"，opt-in）按 echos.user_id 精确过滤。
- Copilot 注入 UserReader（wire 跨域绑定 user 服务），Chat 检索收口当前对话用户。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lin-snow

internal/agent/provider_anthropic.go

@@ -53,6 +53,10 @@ func (p *anthropicProvider) buildParams(req Request) anthropic.MessageNewParams
 		Messages:  msgs,
 	}
 	if len(systemBlocks) > 0 {
+		// Prompt cache：在最后一个 system 块打 ephemeral 断点。Anthropic 缓存顺序为
+		// tools → system → messages，故此断点会把 tool 定义 + system 整段静态前缀一并缓存，
+		// 工具循环里 round 2/3 与短时连续请求即命中缓存，抵消 ReAct 多轮的 token 成本。
+		systemBlocks[len(systemBlocks)-1].CacheControl = anthropic.NewCacheControlEphemeralParam()
 		params.System = systemBlocks
 	}
 	if tools := p.buildTools(req.Tools); len(tools) > 0 {

internal/agent/provider_openai.go

@@ -15,6 +15,10 @@ import (
 )
 
 // openaiProvider 适配 OpenAI 兼容协议（OpenAI / DeepSeek / Qwen / Moonshot / Ollama 等）。
+//
+// Prompt cache：OpenAI 兼容端是服务端自动缓存（前缀 >1024 token 自动命中），无客户端字段可设，
+// 故无需像 Anthropic 那样显式打 cache_control 断点——工具循环里重复的 system+工具定义前缀会被
+// 服务端自动复用。
 type openaiProvider struct {
 	setting model.AgentSetting
 }

internal/agent/run.go

@@ -6,20 +6,27 @@ package agent
 import (
 	"context"
 	"strings"
+	"unicode/utf8"
 
 	logUtil "github.com/lin-snow/ech0/internal/util/log"
 	"go.uber.org/zap"
+	"golang.org/x/sync/errgroup"
 )
 
 // defaultMaxRounds 是工具轮数上限护栏：防模型反复调工具死循环烧 token。
 const defaultMaxRounds = 3
 
+// maxParallelTools 是单轮内并发执行工具调用的上限：模型一轮发多个工具调用时并发跑（多为 I/O
+// 密集的检索），削减串行延迟，同时 clamp 住并发度避免突发打满下游。
+const maxParallelTools = 4
+
 // defaultRunStrings 是 RunStrings 各字段留空时的回退（保持历史中文行为，向后兼容）。
 var defaultRunStrings = RunStrings{
-	DedupNote:   "（已检索过，结果见上）",
-	UnknownTool: "未知工具：",
-	ToolError:   "工具执行失败：",
-	ImageNote:   toolImageNote,
+	DedupNote:       "（已检索过，结果见上）",
+	UnknownTool:     "未知工具：",
+	ToolError:       "工具执行失败：",
+	ImageNote:       toolImageNote,
+	ContextTrimNote: "（早前检索结果已省略以控制长度）",
 }
 
 // withDefaults 用 defaultRunStrings 填充留空字段。
@@ -36,6 +43,9 @@ func (s RunStrings) withDefaults() RunStrings {
 	if s.ImageNote == "" {
 		s.ImageNote = defaultRunStrings.ImageNote
 	}
+	if s.ContextTrimNote == "" {
+		s.ContextTrimNote = defaultRunStrings.ContextTrimNote
+	}
 	return s
 }
 
@@ -90,6 +100,8 @@ func runLoop(ctx context.Context, provider Provider, req RunRequest, out chan<-
 	strs := req.Strings.withDefaults()
 
 	for round := 0; round < maxRounds; round++ {
+		// 轮内 token 预算回收：超限时把最旧的工具结果替换为占位，防多轮累积撑爆窗口。
+		trimContext(messages, req.MaxContextTokens, strs.ContextTrimNote)
 		o := streamRound(ctx, provider, out, messages, toolDefs, req.Temp)
 		if o.aborted {
 			return // ctx 取消
@@ -112,6 +124,7 @@ func runLoop(ctx context.Context, provider Provider, req RunRequest, out chan<-
 	}
 
 	// 工具轮用尽仍在调工具：强制一轮「不给工具」让模型据已检索到的结果作答，保证有回答。
+	trimContext(messages, req.MaxContextTokens, strs.ContextTrimNote)
 	o := streamRound(ctx, provider, out, messages, nil, req.Temp)
 	if o.aborted {
 		return
@@ -177,8 +190,18 @@ func streamRound(
 	return o
 }
 
-// execTools 顺序执行一轮的工具调用：去重、emit Searching/ToolResult、把结果追加进 messages。
+// execTools 执行一轮的工具调用：去重、emit Searching/ToolResult、把结果追加进 messages。
 // 工具执行错误不中止（回喂模型自愈）；仅 ctx 取消时返回 false。
+//
+// 三段式（保留消息顺序、去重确定性，同时并发掉 I/O 密集的执行）：
+//
+//	A. 顺序预处理——去重命中 / 未知工具就地定好其 tool 结果消息，其余记为待执行；
+//	B. 有界并发执行待执行项（emit Searching + Execute），结果按 index 写入各自槽，无竞态；
+//	C. 顺序收尾——按调用原序 emit ToolResult、定好 tool 结果消息与（可选）带图消息。
+//
+// 追加顺序：**先把全部 tool 结果消息按原序追加，再追加带图 user 消息**。这样一轮 assistant 的
+// 多个 tool_use 的 tool_result 紧邻聚合，满足 Anthropic「tool_result 必须在紧随的同一条 user
+// 消息里与 tool_use 一一对应」的约束（旧逐条「结果→图→结果→图」会把后续 result 推远导致配对失败）。
 func execTools(
 	ctx context.Context,
 	out chan<- AgentEvent,
@@ -188,49 +211,111 @@ func execTools(
 	messages *[]Message,
 	strs RunStrings,
 ) bool {
-	for _, tc := range calls {
+	n := len(calls)
+	toolMsgs := make([]Message, n)   // 每个调用对应的 tool 结果消息（含去重/未知/错误/正常）
+	imageMsgs := make([]*Message, n) // 每个调用可选的带图 user 消息（多模态）
+	outputs := make([]ToolOutput, n)
+	execErrs := make([]error, n)
+
+	// A. 顺序预处理：去重与未知工具就地定好结果消息；其余记为待执行（保留原序 index）。
+	var runnable []int
+	for i, tc := range calls {
 		key := tc.Name + ":" + string(tc.Args)
 		if seen[key] {
-			*messages = append(*messages, Message{Role: RoleTool, ToolCallID: tc.ID, Content: strs.DedupNote})
+			toolMsgs[i] = Message{Role: RoleTool, ToolCallID: tc.ID, Content: strs.DedupNote}
 			continue
 		}
 		seen[key] = true
-
-		tool, ok := toolByName[tc.Name]
-		if !ok {
-			*messages = append(*messages, Message{Role: RoleTool, ToolCallID: tc.ID, Content: strs.UnknownTool + tc.Name})
+		if _, ok := toolByName[tc.Name]; !ok {
+			toolMsgs[i] = Message{Role: RoleTool, ToolCallID: tc.ID, Content: strs.UnknownTool + tc.Name}
 			continue
 		}
+		runnable = append(runnable, i)
+	}
 
-		if !emit(ctx, out, AgentEvent{Kind: AgentSearching, ToolName: tc.Name, ToolArgs: tc.Args}) {
-			return false
-		}
+	// B. 有界并发执行：每个 goroutine emit Searching + Execute，结果写入独立 index 槽。
+	// emit 失败（ctx 取消）→ 返回 ctx.Err() 让整组取消。g.Wait 阻塞至所有 goroutine 结束，
+	// 故 outputs/execErrs 的写入在 Wait 返回前全部完成，后续顺序读取无竞态。
+	var g errgroup.Group
+	g.SetLimit(maxParallelTools)
+	for _, idx := range runnable {
+		idx, tc, tool := idx, calls[idx], toolByName[calls[idx].Name]
+		g.Go(func() error {
+			if !emit(ctx, out, AgentEvent{Kind: AgentSearching, ToolName: tc.Name, ToolArgs: tc.Args}) {
+				return ctx.Err()
+			}
+			outputs[idx], execErrs[idx] = tool.Execute(ctx, tc.Args)
+			return nil
+		})
+	}
+	if err := g.Wait(); err != nil {
+		return false // ctx 取消
+	}
 
-		output, execErr := tool.Execute(ctx, tc.Args)
-		if execErr != nil {
+	// C. 顺序收尾：按原序 emit ToolResult、定好结果/带图消息。
+	for _, idx := range runnable {
+		tc := calls[idx]
+		if execErrs[idx] != nil {
 			logUtil.GetLogger().Warn("agent tool execute failed",
 				zap.String("module", "agent"),
 				zap.String("tool", tc.Name),
-				zap.Error(execErr))
-			*messages = append(*messages, Message{Role: RoleTool, ToolCallID: tc.ID, Content: strs.ToolError + execErr.Error()})
+				zap.Error(execErrs[idx]))
+			toolMsgs[idx] = Message{Role: RoleTool, ToolCallID: tc.ID, Content: strs.ToolError + execErrs[idx].Error()}
 			continue
 		}
-
-		if !emit(ctx, out, AgentEvent{Kind: AgentToolResult, ToolName: tc.Name, Meta: output.Meta}) {
+		if !emit(ctx, out, AgentEvent{Kind: AgentToolResult, ToolName: tc.Name, Meta: outputs[idx].Meta}) {
 			return false
 		}
-		*messages = append(*messages, Message{Role: RoleTool, ToolCallID: tc.ID, Content: output.Content})
-
-		// 多模态：工具带出了图片（如命中 Echo 的配图）→ 紧跟一条带图 user 消息递给模型。
+		toolMsgs[idx] = Message{Role: RoleTool, ToolCallID: tc.ID, Content: outputs[idx].Content}
+		// 多模态：工具带出了图片（如命中 Echo 的配图）→ 用带图 user 消息递给模型。
 		// 走 user 消息而非塞进 tool_result，是因 OpenAI 的 tool 角色消息只能纯文本，
 		// user 带图两家协议都支持，一套逻辑通用。
-		if len(output.Images) > 0 {
-			*messages = append(*messages, Message{Role: RoleUser, Content: strs.ImageNote, Images: output.Images})
+		if len(outputs[idx].Images) > 0 {
+			imageMsgs[idx] = &Message{Role: RoleUser, Content: strs.ImageNote, Images: outputs[idx].Images}
+		}
+	}
+
+	// 先追加全部 tool 结果（聚合相邻，满足 Anthropic 配对约束），再追加带图消息。
+	*messages = append(*messages, toolMsgs...)
+	for i := range imageMsgs {
+		if imageMsgs[i] != nil {
+			*messages = append(*messages, *imageMsgs[i])
 		}
 	}
 	return true
 }
 
+// trimContext 在轮内消息上下文超 budget 时回收最旧的工具结果：把其 Content 替换为 note 占位
+// （保留消息与 ToolCallID 配对，绝不删消息——否则 tool_use/tool_result 失配会被 API 400）。
+// budget<=0 时不回收。逐条替换直到回到预算内或没有可回收的工具结果。
+func trimContext(messages []Message, budget int, note string) {
+	if budget <= 0 {
+		return
+	}
+	for contextTokens(messages) > budget {
+		idx := -1
+		for i := range messages {
+			if messages[i].Role == RoleTool && messages[i].Content != note {
+				idx = i
+				break
+			}
+		}
+		if idx < 0 {
+			return // 没有可回收的工具结果了
+		}
+		messages[idx].Content = note
+	}
+}
+
+// contextTokens 估算消息上下文的 token 总量（仅按文本 rune 计，图片不计）。
+func contextTokens(messages []Message) int {
+	total := 0
+	for i := range messages {
+		total += utf8.RuneCountInString(messages[i].Content)
+	}
+	return total
+}
+
 // toolImageNote 是带图 user 消息的说明文本，告诉模型这些图来自上一步检索命中的 Echo。
 const toolImageNote = "（以下是上一步检索命中的 Echo 的配图，供你结合图片内容作答）"
 

internal/agent/run_test.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"strings"
 	"testing"
 	"time"
 
@@ -343,6 +344,78 @@ func TestRunLoop_CustomImageNote(t *testing.T) {
 	}
 }
 
+// 单轮多工具：模型一轮内发起两个不同工具调用，二者都执行（并发），且下一轮上下文里两条
+// tool 结果按调用原序回灌；Searching/ToolResult 各 2 次。-race 下应无竞态。
+func TestRunLoop_ParallelToolsSingleRound(t *testing.T) {
+	toolA := Tool{
+		Def:     ToolDef{Name: "tool_a", Description: "a", Parameters: json.RawMessage(`{"type":"object"}`)},
+		Execute: func(_ context.Context, _ json.RawMessage) (ToolOutput, error) { return ToolOutput{Content: "AAA"}, nil },
+	}
+	toolB := Tool{
+		Def:     ToolDef{Name: "tool_b", Description: "b", Parameters: json.RawMessage(`{"type":"object"}`)},
+		Execute: func(_ context.Context, _ json.RawMessage) (ToolOutput, error) { return ToolOutput{Content: "BBB"}, nil },
+	}
+	fp := &fakeProvider{scripts: [][]Event{
+		{toolCallEvent("c1", "tool_a", `{}`), toolCallEvent("c2", "tool_b", `{}`), doneEvent()},
+		{textEvent("answer"), doneEvent()},
+	}}
+
+	evs := runLoopSync(context.Background(), fp, RunRequest{Setting: enabledSetting(), Tools: []Tool{toolA, toolB}})
+
+	if n := countKind(evs, AgentSearching); n != 2 {
+		t.Fatalf("AgentSearching count = %d, want 2", n)
+	}
+	if n := countKind(evs, AgentToolResult); n != 2 {
+		t.Fatalf("AgentToolResult count = %d, want 2", n)
+	}
+
+	// 下一轮 Messages 里两条 RoleTool 必须按调用原序：c1(AAA) 在 c2(BBB) 之前。
+	var toolMsgs []Message
+	for _, m := range fp.gotReqs[1].Messages {
+		if m.Role == RoleTool {
+			toolMsgs = append(toolMsgs, m)
+		}
+	}
+	if len(toolMsgs) != 2 {
+		t.Fatalf("next round should carry 2 tool results, got %d", len(toolMsgs))
+	}
+	if toolMsgs[0].ToolCallID != "c1" || toolMsgs[0].Content != "AAA" {
+		t.Fatalf("first tool result = %+v, want c1/AAA", toolMsgs[0])
+	}
+	if toolMsgs[1].ToolCallID != "c2" || toolMsgs[1].Content != "BBB" {
+		t.Fatalf("second tool result = %+v, want c2/BBB", toolMsgs[1])
+	}
+}
+
+// 轮内 token 预算回收：超 MaxContextTokens 时，最旧的 RoleTool 结果被替换为占位，较新的保留。
+func TestRunLoop_TrimsOldestToolResultOverBudget(t *testing.T) {
+	note := defaultRunStrings.ContextTrimNote
+	msgs := []Message{
+		{Role: RoleSystem, Content: "S"},
+		{Role: RoleUser, Content: "Q"},
+		{Role: RoleAssistant, ToolCalls: []ToolCall{{ID: "t1", Name: "search_echos"}}},
+		{Role: RoleTool, ToolCallID: "t1", Content: strings.Repeat("a", 100)}, // 最旧、最大
+		{Role: RoleAssistant, ToolCalls: []ToolCall{{ID: "t2", Name: "search_echos"}}},
+		{Role: RoleTool, ToolCallID: "t2", Content: strings.Repeat("b", 20)}, // 较新
+	}
+	// 预算 50：替换最旧的 t1(100→note 长度) 后 1+1+len(note)+20 应 ≤ 50。
+	fp := &fakeProvider{scripts: [][]Event{{textEvent("ok"), doneEvent()}}}
+
+	runLoopSync(context.Background(), fp, RunRequest{
+		Setting:          enabledSetting(),
+		Messages:         msgs,
+		MaxContextTokens: 50,
+	})
+
+	got := fp.gotReqs[0].Messages
+	if got[3].Content != note {
+		t.Fatalf("oldest tool result should be trimmed to note, got %q", got[3].Content)
+	}
+	if got[5].Content != strings.Repeat("b", 20) {
+		t.Fatalf("recent tool result should be preserved, got %q", got[5].Content)
+	}
+}
+
 // 多模态：工具带出图片时，下一轮 Messages 应追加一条带图的 RoleUser（Content==toolImageNote）。
 func TestRunLoop_ToolImageNoteAppended(t *testing.T) {
 	img := ImagePart{MediaType: "image/png", Base64: "abc"}

internal/agent/types.go

@@ -104,10 +104,11 @@ type Event struct {
 // RunStrings 是 Loop 在工具循环中回喂给模型 / 注入消息的少量提示文案。由领域层（知道 locale）
 // 注入，使 agent 包保持 i18n 零依赖；任一字段留空则回退到 defaultRunStrings（中文，保持历史行为）。
 type RunStrings struct {
-	DedupNote   string // 同一查询重复调用时整条 tool 结果的内容
-	UnknownTool string // 未知工具名提示的前缀（后接工具名）
-	ToolError   string // 工具执行失败提示的前缀（后接错误信息）
-	ImageNote   string // 带图 user 消息的说明文本
+	DedupNote       string // 同一查询重复调用时整条 tool 结果的内容
+	UnknownTool     string // 未知工具名提示的前缀（后接工具名）
+	ToolError       string // 工具执行失败提示的前缀（后接错误信息）
+	ImageNote       string // 带图 user 消息的说明文本
+	ContextTrimNote string // 轮内 token 预算回收时，替换最旧工具结果内容的占位文案
 }
 
 // RunRequest 是 Loop 层对领域层（Copilot Service）暴露的请求。
@@ -119,6 +120,9 @@ type RunRequest struct {
 	Temp      *float32      // nil → 不设置
 	Strings   RunStrings    // 回喂/注入文案；零值字段回退到 defaultRunStrings
 	Timeout   time.Duration // 单轮运行（含工具循环）整体超时；<=0 → 不额外设超时（沿用传入 ctx）
+	// MaxContextTokens 是工具循环里整轮消息上下文的软上限（估算 token）；>0 时超限即回收
+	// 最旧的工具结果（替换为 Strings.ContextTrimNote），防多轮工具结果累积撑爆窗口。0 → 不回收。
+	MaxContextTokens int
 }
 
 // AgentEventKind 区分 Loop 上浮给领域层的语义事件类型。

internal/config/config.go

@@ -175,6 +175,9 @@ type MigrationConfig struct {
 type AgentConfig struct {
 	// TimeoutSeconds 是单轮 Agent 运行（含整个工具循环）的整体超时，单位秒；<=0 表示不额外设超时。
 	TimeoutSeconds int `env:"ECH0_AGENT_TIMEOUT_SECONDS"`
+	// MaxRounds 是 Chat 单轮问答内的工具调用轮数上限（ReAct 护栏），防模型反复调工具烧 token；
+	// <=0 时 agent 包回退内置默认。
+	MaxRounds int `env:"ECH0_AGENT_MAX_ROUNDS"`
 }
 
 // Config 返回全局配置中心
@@ -311,6 +314,7 @@ func defaultConfig() *AppConfig {
 		},
 		Agent: AgentConfig{
 			TimeoutSeconds: 120,
+			MaxRounds:      4,
 		},
 	}
 }

internal/di/wire.go

@@ -24,6 +24,8 @@ import (
 	"github.com/lin-snow/ech0/internal/server"
 	"github.com/lin-snow/ech0/internal/service"
 	commentService "github.com/lin-snow/ech0/internal/service/comment"
+	copilotService "github.com/lin-snow/ech0/internal/service/copilot"
+	userService "github.com/lin-snow/ech0/internal/service/user"
 	"github.com/lin-snow/ech0/internal/storage"
 	"github.com/lin-snow/ech0/internal/task"
 	"github.com/lin-snow/ech0/internal/transaction"
@@ -131,6 +133,8 @@ var HandlerSet = wire.NewSet(
 	handler.EmbeddingSet,
 
 	service.CopilotSet,
+	// Copilot 的 UserReader 跨域绑定到 user 服务（取当前对话用户：展示名 + 检索按作者收口）。
+	wire.Bind(new(copilotService.UserReader), new(*userService.UserService)),
 	handler.CopilotSet,
 
 	service.BackupSet,